jsoq

Query and manipulate JSON arrays easily. Powered by lodash, inspired by knex syntax and SQL in general.

GitHub package.json version GitHub

Installation

npm i jsoq@latest

Usage

/*** 1. Import jsoq package: ***/
import jsoq from 'jsoq';
// or const jsoq = require('jsoq');

const data = [
  { a: 1, b: 'some text', c: false },
  { a: 2, b: 'another text', c: true },
];

/*** 2. Set the JSON array you want to query: ***/
const output = jsoq.from(data)
  /*** 3. Start manipulating: ***/
  .where({ c: true })
  .select('a')
  /*** 4. Manipulation done, return result: ***/
  .json();
//-> [ { a: 2 } ]

Functions

Basic

.from(json: object[]) - Sets the input JSON array.
```
jsoq.from(data); //-> jsoq
```
.json() - Returns current state of input JSON array.
```
jsoq.from(data).json(); //-> [{}, {}, ...]
```
.string() - Returns current state of input JSON array as string.
```
jsoq.from(data).string(); //-> "[{}, {}, ...]"
```

Aggregation

.avg(property: string) - Computes the average value of a property in JSON array.
```
jsoq.from(data).avg('index'); //-> 3.5
```
.count() - Computes the number of objects in JSON array.
```
jsoq.from(data).count(); //-> 6
```
.max(property: string, scalar?: boolean) - Finds the maximum value of a property in JSON array.
```
jsoq.from(data).max('age'); //-> jsoq
jsoq.from(data).max('age', true); //-> 40
```
.min(property: string, scalar?: boolean) - Finds the minimum value of a property in JSON array.
```
jsoq.from(data).min('age'); //-> jsoq
jsoq.from(data).min('age', true); //-> 21
```
.sum(property: string) - Computes the summation of a property in JSON array.
```
jsoq.from(data).sum('age'); //-> 68
```

Filtering

.between(property: string, range: [min: any, max: any]) - Takes only the objects which are greater than or equals to the first value in range and smaller than or equals to the the second.
```
jsoq.from(data).between('age', [10, 20]); //-> jsoq
jsoq.from(data).between('name', ['A', 'B']); //-> jsoq
```
.distinct(property?: string) - Keeps only the first occurrence of a property in each object in JSON array.
```
jsoq.from(data).distinct(); //-> jsoq
jsoq.from(data).distinct('age'); //-> jsoq
```

.first(n?: number) - Takes n objects from the beginning of JSON array.

jsoq.from(data).first(); //-> jsoq
jsoq.from(data).first(3); //-> jsoq

.ilike(property: string, values: string | string[]) - Takes only the objects which match at list one pattern (case insensitive) in JSON array.
```
jsoq.from(data).ilike('name', 'sha%'); //-> jsoq
jsoq.from(data).ilike('name', ['sha%', '%ro%']); //-> jsoq
```
.in(property: string, values: any[]) - Takes only the objects which property value exists in given array.
```
jsoq.from(data).in('index', [1, 2]); //-> jsoq
```

.last(n?: number) - Takes n objects from the end of JSON array.

jsoq.from(data).last(); //-> jsoq
jsoq.from(data).last(2); //-> jsoq

.like(property: string, values: string | string[]) - Takes only the objects which match at list one pattern (case sensitive) in JSON array.
```
jsoq.from(data).like('name', 'Sha%'); //-> jsoq
jsoq.from(data).like('name', ['Sha%', '%ro%']); //-> jsoq
```
.nth(n: number) - Takes the nth object from JSON array.
```
jsoq.from(data).nth(4); //-> jsoq
```
.skip(n: number) - Takes all objects from JSON array, except of the first n objects.
```
jsoq.from(data).skip(2); //-> jsoq
```

.where(predicate: any) - Takes only the objects which match the predicate in JSON array.

jsoq.from(data).where({ age: 32 }); //-> jsoq
jsoq.from(data).where('isActive'); //-> jsoq
jsoq.from(data).where(o => o.age === 32 || o.isActive); //-> jsoq

Manipulation

.group(property: string) - Transforms JSON array into a dictionary, which composed of keys generated from the array.

jsoq.from(data).group('age'); //-> { '21': [{}, {}...], '32': [{}...] }
jsoq.from(data).group('gender', 'isActive'); //-> { 'female': { 'true': [{}, {}...], 'false': [{}, {}...] }, 'male': { 'true': [{}, {}...], 'false': [{}, {}...] } }

.join(json: any[], property: string, fromProperty?: string) - Merges two JSON arrays based on a property. Takes only objects which exist in both JSON arrays. You may use fromProperty if the common property name is different in each array.
```
jsoq.from(data).join(data2, 'index'); //-> jsoq
```
.leftJoin(json: any[], property: string, fromProperty?: string) - Merges two JSON arrays based on a property. Takes all objects from left (first) JSON array. You may use fromProperty if the common property name is different in each array.
```
jsoq.from(data).leftJoin(data2, 'index'); //-> jsoq
```

.order(property: string) - Changes the order of all properties in array.

jsoq.from(data).order('index'); //-> jsoq
jsoq.from(data).order('index asc', 'age', 'isActive desc'); //-> jsoq

.random() - Returns a random element.
```
jsoq.from(data).random(); //-> {}
```
.rightJoin(json: any[], property: string, fromProperty?: string) - Merges two JSON arrays based on a property. Takes all objects from the right (second) JSON array. You may use fromProperty if the common property name is different in each array.
```
jsoq.from(data).rightJoin(data2, 'index'); //-> jsoq
```
.select(properties: string[]) - Extracts specific properties from all objects in array, with an option to rename keys.
```
jsoq.from(data).select('index'); //-> jsoq
jsoq.from(data).select('index as i', 'isActive as a'); //-> jsoq
```
.shuffle() - Changes the order of all properties in array randomaly.
```
jsoq.from(data).shuffle(); //-> jsoq
```

Comments

All methods which return jsoq are chainable, hence .json() should be called when you're ready to get the output.
first, last and nth functions return jsoq and not a single object by default, to enable chaining and for the sake of consistency.
Check tests directory for examples.

Jsoq

Install / Use

README