jsgjs
Join Select Group-js. A small utility for performing SQL like join select and group operations on Arrays of Objects in JS
JSG js
Join Select Group-js. A small utility for performing SQL like join select and group operations on Arrays of Objects in JS. With high perfomance on large data sets.
Useful for front-end data manipulation and backend datastreaming and analysis without Db storage. ie. combining analytic data from an third party api wiith in house Db.
Installation
npm install jsgjs --save
Node
var JSG = ;
Browser
Also included is a frontend jsgjs.min.js file
<script type="text/javascript" src="/servingDirectory/jsgjs.min.js"></script>var useableObject = initData;
Usage
A creted JSG object has 3 possible methods for manipulating data: -Join -Select -Group
Here is an example of all three used on two data sets
var JSG = ;var users = id:1name:"John" id:2name:"Kate" id:3name:"Mary" id:4name:"Michal";var orders = user_id:2items:1price_cents:100 user_id:2items:5price_cents:10000 user_id:3items:2price_cents:500 user_id:1items:1price_cents:1100; var spendData = users; console // Result name: 'John' items_avg: 1 euros_spent: 11 name: 'Kate' items_avg: 3 euros_spent: 101 name: 'Mary' items_avg: 2 euros_spent: 5 name: 'Michal' items_avg: NaN euros_spent: 0 }
JSG Object
The JSG object provides routes by which to preform the join, group and select methods. It stores and then removes transient data from memory. It takes one argmument which is an array of JSON objects. This argument acts as the left dataset for a join and the primary dataset other operations.
var names = id:1name:"Kate" id:2name:"Mary";var dataObject = names;console // both return the names data set
When join , select or group methods are executed the results overwrite the previous 'data' property of the JSG object (ie. dataObject.data from above)
Join
The Join method creates a join object on which four joins can be preformed:
- outterJoin
- innerJoin
- leftJoin
- rightJoin
These mirror SQL like join in behaviour. rightJoin is simply a left join but inverts the dataSource.
var colours = name:"kate"colour:"blue" name:"john"colour:"red" name:"james"colour:"grey";var foods = name:"kate"colour:"chips" name:"john"colour:"apples";var leftJoinEx = coloursvar rightJoinEx = foods //leftJoinEx and rightJoinEx both return//[ { name: 'kate', 'colour-left': 'blue', 'colour-right': 'chips' },//{ name: 'john', 'colour-left': 'red', 'colour-right': 'apples' },//{ name: 'james', 'colour-left': 'grey', 'colour-right': null } ]
// Join syntax is as follows var myJoinObject = dataSource1typeofJoindataSource2"fieldToJoinOn"
The Join field must exist in both dataSets. If names are different as in the first example (ie join user_id and id) then a select statement or indeed a native array.map() function should be used.
N.B Currently the first row of each data set is used for header evaluation so ensure all relatvent headers are therein contained. There is an assumption of data validity
Select
Select provides similar functionality to the native .map method. However It provides utility in syntax and also in the context of other JSG methods
It takes one argument - selectionArray
Each element in the selectionArray maps one column
A selectionArray element can come in three forms
- String
- Object of form: {title:string, val:string }
- Object of form: { title:string, val:function }
var orders = user_id:2items:1price_cents:100 user_id:2items:5price_cents:10000 user_id:3items:2price_cents:500 user_id:1items:1price_cents:1100;var selectionArray = title:"user"val:"user_id" //maps the field user_id onto a new field named user "price_cents" // this maps the field transparently title:"price_euros"{return rowprice_cents/100} // this operates on each row// note that items is ommited and therefore will be omitted from the results set var result = orders// result// [ { user: 2, price_cents: 100, price_euros: 1 },// { user: 2, price_cents: 10000, price_euros: 100 },// { user: 3, price_cents: 500, price_euros: 5 },// { user: 1, price_cents: 1100, price_euros: 11 } ]
Group
Group allows aggregation of data rows. Group takes two arguments:
- GroupBy
- The field (string) or fields (array of strings) by which to group
- "All" is another valid input (which does what it says on the tin)
- Field(s) to Aggregrate
- This field provides some syntax freedoms.
Fields Argument
The Basic form is as per below
header:"columnName::string"operators:"agerateFunctionName::string" eg: header:"price_cents"operators:"sum""avg""count"
A plain array of strings with columnName and operation seperated by the deliminator :: may also be used
eg: "price_cents::sum""price_cents::avg"
NB : this second option is parsed into the first
Available Operators:
- sum - numeric values only , disregarding null values
- avg - numeric values only , disregarding null values
- count - all values , disregarding null values
- unique - all values , disregarding null values
- median - numeric values only , disregarding null values
- mode - all values , disregarding null values
- max - numeric values only , disregarding null values
- min - numeric values only , disregarding null values
var orders = user_id:2items:1price_cents:100 user_id:2items:5price_cents:10000 user_id:3items:2price_cents:500 user_id:1items:1price_cents:1100;var syntax1 = orders; var syntax2 = orders;
syntax1 and syntax2 will bring the same results
// the output of resultsresult = All: undefined price_cents_sum: 11700 price_cents_avg: 2925 price_cents_median: 1100 price_cents_max: 10000 items_count: 4 items_min: 1 items_sum: 9 ;
Filter (where/having)
Remove rows that dont meet a certain test. Syntax where , filter or having may be used. The one argument is a function that returns a boolean.
var rows = name:"kate"age:30 name:"john"age:20 name:"kate"age:1 name:"mary";var filtered = rows name:"kate"age:30 name:"john"age:20;
Sort (orderBy)
Sort the data according to one field/ column name by ascending (asc) or decending (desc) sort or orderBy methods can be used. The take one or two argument.
- .sort("column","direction")
- .sort("column::direction")
var rows = name:"kate"age:30 name:"john"age:20 name:"kate"age:1 name:"mary"age:16;var sorted = rowsvar sorted = rowsvar sorted = rows name: 'kate' age: 1 name: 'mary' age: 16 name: 'john' age: 20 name: 'kate' age: 30
Release History
- 0.1.0 Initial release