jsoq
Query and manipulate JSON arrays easily. Powered by lodash, inspired by knex syntax and SQL in general.
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
andnth
functions returnjsoq
and not a single object by default, to enable chaining and for the sake of consistency. - Check tests directory for examples.