@pennions/joq

Welcome to Jelmers Object Query

This is a library designed to make querying JSON objects a breeze.

• Welcome to Jelmers Object Query
  • Installation
    • npm
    • yarn
    • CDN
  • Getting started
  • Functions
    • Sort / Order
    • Filter / Where
    • Group
    • Select
    • Distinct
    • Execute
    • Sum
• Support us

Installation

Simply add it to your project using npm or yarn:

npm

npm install @pennions/joq

yarn

yarn add @pennions/joq

Then import it in your code as follows:

import JOQ from "@pennions/joq"

CDN

Just add

<script src="https://cdn.jsdelivr.net/npm/@pennions/joq"></script>

and use it like

const queryable = new joq(yourJsonArray);

Getting started

The library exposed a class, which takes an object array as single argument:

const queryableObject = new JOQ(myObjectArray);

It makes a hard copy of the object. So in this case myObjectArray will not be mutated itself.

Functions

Listed below are all the functions you can call on the queryableObject which is mentioned in the Getting started section.

example:

queryableObject.select("name");
queryableObject.where("name", "like", "john");

const result = queryableObject.execute();

Sort / Order

propertyName

The case-sensitive name of the property you want to sort on.

direction (SortDirection) Can be one of the following:

"asc" for ascending order

"desc" for descending order

SortDetail

{
    propertyName: string;
    direction: SortDirection;
}

Functions

orderBy(propertyName: string, direction: SortDirection)

thenOrderBy(propertyName: string, direction: SortDirection) 

Example:

queryableObject.orderBy("name", "asc");
queryableObject.thenOrderBy("age", "desc");
const result = queryableObject.execute();

Or if you want to add all the details at once in an array, you can use the sort function.

sort(sortDetails: Array<SortDetail>

Filter / Where

propertyName

The case-sensitive name of the property you want to search on.

operator (FilterOperator) Can be one of the following:

">" for GreaterThan

"<" for LesserThan

">=" for EqualsOrGreater

"<=" for EqualsOrLesser

"is" for "==" for Equals

"!=" for NotEquals

"===" for SuperEquals (includes typecheck)

"!==" for SuperNotEquals (includes typecheck)

"like" for Like (string comparison)

"!like" for NotLike (string comparison)

"contains" for Contains (string comparison)

"!contains for NotContains (string comparison)

FilterType

Can be "and" / "or"

FilterDetail

{
    propertyName: string, 
    value: any, 
    operator: FilterOperator, 
    type?: FilterType, /** optional, defaults to "and" **/
    ignoreCase?: boolean /** optional, defaults to "false" **/
}

N.B. ignoreCase only works with 'equals' operator, 'like' already ignores case.

Functions

where(propertyName: string, operator: FilterOperator, value: any, type?: FilterType, ignoreCase?: boolean) 

Implicitly adds "and" type, but where does this as well. So treat it as syntactic sugar.

andWhere(propertyName: string, operator: FilterOperator, value: any, ignoreCase?: boolean)

Implicitly adds "or" type

orWhere(propertyName: string, operator: FilterOperator, value: any, ignoreCase?: boolean)

Or if you want to add all the details at once in an array, you can use the filter function.

filter(filterDetails: Array<FilterDetail>) 

Group

propertyName

The case-sensitive name of the property you want to group on.

Functions

groupBy(propertyName: string)

This is syntactic sugar, adding an additional where does the same.

thenGroupBy(propertyName: string)

Or supply all the properties at once, order matters.

group(groupByProperties: Array<string>)

Select

If you want to make a subselection, you can provide a string or an array of strings with the case-sensitive property names. It will only return objects with those properties

select(selection: Array<string> | string) 

Distinct

This function takes an array of values which will be treated as unique. Merging the properties from the objects that also have the exact same value of this property. The optional concatenation token will default to ', ' but in some cases you want to use a different token, for example when you are working with csv.

distinct(properties: Array<string> | string, concatenationToken?: string) 

N.B. this will also sum any numeric fields. If you do not want this behaviour, make that field distinct as well.

Execute

This function will start all the operations you added and returns the result.

execute() 

Sum

This is a special function, because it returns a single object with the totals of the provided properties. So you cant use execute with this one.

sum(sumProperties: Array<string>, jsonArray: Array<any>)

Example:

const result = queryableObject.sum("age");

But you can also supply your own json array, for example if you grouped it before, you get an array of arrays. So you can also use sum for this subselection easily without creating a new JOQ instance

Example:

const sum = queryableObject.sum("age", result[0]);

Support us

If you are using this for paid products and services please consider:

• Becoming a supporter on Patreon.com
• Doing a one time donation on Ko-Fi.
• If you want to donate but are not able to do so on these platforms, please contact us at www.pennions.com so we can provide an iDeal link.