node-datastore

node-datastore

Data library was designed to accomodate most useful and commonly used features that are data-specific, such as sorting, filtering, paginating, aggregation functions, etc. Library addresses issues that we face every time we interact with some sort of web service, be it JSON or XML. The concept of Data in the context of this library refers to an Array of Rows (Array of JSON objects).

Installation

npm install node-datastore

Initialization

var DataStore = require("node-datastore");

DataStore API

Constructor

var myData = new DataStore(data, options);

• data - JSON Object, or Array of object
• options - Configuration object
  • pageSize - page size used for data pagination. Default: 10
  • dataNode - jPath expression to indicate the parent node of your rows. This is used when you initialize DataStore with a complex JSON object which has Array of rows burried deep inside.

Example

var jsonData = {
	company: {
		name: "ABC",
		people: [
			{name: "John", age:26, gender:"male"},
			{name: "Steve", age:24, gender:"male"},
			{name: "Susan", age:22, gender:"female"},
			{name: "Linda", age:30, gender:"female"},
			{name: "Adam", age:32, gender:"male"}
		]
	}
};

var peopleStore = new DataStore(jsonData, { dataNode: "company.people" });

Methods

• setConfig(options) - This method allows you to set configuration options of your DataStore instance after it has been instantiated. It takes the same exact arguments as constructor.
• getRows([start, [end]]) - This method returns all or limited set of rows in your dataset.
• getRowByIndex(index) - Returns a single row by index. Note: Indexes in the rows remain the same regardless the sort, they are assigned during the data fill.
• sort(column | [columnDef, n]) - sorts your data. If you just specify a string column name, then the data will be sorted by that column in Asending order. You may specify a multi-column sort as well, in that case you will need to provide columnDef objects as arguments.
  • columnDef - Column definition object
    • column - String column name
    • order - String "asc" | "desc"
    • type - String "text" | "number" | "date". Default: "text".
• getPage(page [, pageSize]) - Returns a page subset (if pagination is enabled). pageSize argument takes preidence over pageSize option set at initialization.
• count() - Returns a row count.
• filter(expression) - Returns your rows based on filter expression. Expressions follow jPath syntax similar to XPATH but with a hint of JavaScript in it. Ex. "*[field=value]" will match rows where field equals value.
• select(expression) - Returns results of jPath expression as new DataStore object. Similar to filter() method but returns a new DataStore instead of the Array.
• insertRow(row) - Inserts a row object into existing dataset. Row could be an Array or JSON object, just try to keep the structure consistent!
• sum( column ) - This is an aggregate function that will Sum up all the values in the column (if they are numeric of course). Column argument could be either a String name or a numeric column Index.
• avg( column ) - Returns an Average for all column values. Same argument options as above (sum).
• max( column ) - Returns a Maximum number among all values in the column.
• min( column ) - Returns a Minimum number among all values in the column.
• unique( column ) - This is a very powerful function that returns a unique set of values for a given column. Column attribute follows the same properties as above - either column name or index.
• concat( data [, data] ) - As the name implies, this method will concatenate data from another DataStore instance or a Multi-dimensional Array into existing DataStore. This method is very useful when you have two instances of DataStore objects that contain similarly structured data, and you want to work against a merged set to either filter or paginate or find uniques, etc.
• adjustData( [field], cb ) - This method is used to sanitize data. It executes a callback for each row. There are two signatures to this method:
  • field, cb - If you call adjustData with optional field argument, then it will call callback only for a single field and will pass into callback current value and row reference
  • cb - If you call adjustData only with a callback, then a callback will be called for each row in the dataset and a callback will only receive a row reference as an argument.
• join(sourceData, pkFk, options) - Very powerful feature that allows you to merge two DataStore's based on pk->fk relationship. This method supports JOIN operations similar to SQL.
  • sourceData - Another instance of DataStore to merge exsiting DataStore with
  • pkFk - String or Object. If used as String, it implies that both PrimaryKey(PK) and ForeignKey(FK) are named exactly the same. In case PK and FK are named differently, you will need to pass in a mapping object that looks like this: { "destinationKey":"sourceKey" }.
  • options - Configuration options
    • type - Types of Join: inner(both keys match), differential(only non-matching), left(destination biased), right(source biased). Default: inner.
    • whiteList - Array of source field names that are allowed to be merged w/ destination row
    • blackList - Array of source field names that will be excluded when merging w/ destination row
• groupBy( column [,column, column ...]) - Groups data by a column specified, creating a tree-like structure where keys are unique column values and leafs are rows of data. Each column you specify in the arguments will be nested inside of the previous column group.
• clone() - Returns a cloned copy of your DataStore.
• top(n) - Returns a new DataStore which contains a cropped data set of TOP rows specified by n.

Read-only Members

Any instance of the DataStore also exposes several useful state members.

• status - This objects retains a status for operations such as sorting and pagination
  • page - Current page cursor position
  • pageCount - How many pages total are in the set
  • sortedColumn - Currently sorted column ( currently only supported for a single column sort )
  • sortOrder - String value for a current sort order ( currently only supported for a single column sort )
  • currentRange - Object that contains indexes of first and last record within a current page. Ex. {start: 1, end:25} - for a page size of 25.

Row Members

Every row in the DataStore contains only one foreign member that keeps the value of the Row Index __rowIndex__ - use this member to identify row index. This is useful if you will need to find a row later by index. Note: There are 2 underscores on each side of rowIndex!

Events

DataStore instance implements EventEmitter and exposes some useful events

• beforeSort - fires before a sort takes place
• sort - fires right after a sort has been performed
• change - fires whenever the data has changed
• insert - fires whenever a row is inserted