nire0510/jsoq

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

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 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's Issues

JS output

I like what you have, but converting from TS to JS may be tedious for some users. It might be good to have an already-converted JS version.