JSDoc: Class: Resultset

new Resultset(collection)

Resultset class allowing chainable queries. Intended to be instanced internally. Collection.find(), Collection.where(), and Collection.chain() instantiate this.

Parameters:

Name	Type	Description
`collection`	Collection	The collection which this Resultset will query against.

Source:

controldb.js, line 2949

Example

mycollection.chain()
     .find({ 'doors' : 4 })
     .where(function(obj) { return obj.name === 'Toyota' })
     .data();

Members

branch

Alias of copy()

Source:

controldb.js, line 3060

Methods

compoundsort(properties) → {Resultset}

Allows sorting a resultset based on multiple columns.

Parameters:

Name	Type	Description
`properties`	array	array of property names or subarray of [propertyname, isdesc] used evaluate sort order

Source:

controldb.js, line 3330

Returns:

Reference to this resultset, sorted, for future chain operations.

Type: Resultset

Example

// to sort by age and then name (both ascending)
rs.compoundsort(['age', 'name']);
// to sort by age (ascending) and then by name (descending)
rs.compoundsort(['age', ['name', true]]);

copy() → {Resultset}

copy() - To support reuse of resultset in branched query situations.

Source:

controldb.js, line 3045

Returns:

Returns a copy of the resultset (set) but the underlying document references will be the same.

Type: Resultset

count() → {number}

count() - returns the number of documents in the resultset.

Source:

controldb.js, line 3765

Returns:

The number of documents in the resultset.

Type: number

Example

var over30Count = users.chain().find({ age: { $gte: 30 } }).count();

docs(optionsopt) → {array}

Terminates the chain and returns array of filtered documents

Parameters:

Name Type Attributes Description

options

object

allows specifying 'forceClones' and 'forceCloneMethod' options.

Properties

Name	Type	Description
`forceClones`	boolean	Allows forcing the return of cloned objects even when the collection is not configured for clone object.
`forceCloneMethod`	string	Allows overriding the default or collection specified cloning method. Possible values include 'parse-stringify', 'jquery-extend-deep', 'shallow', 'shallow-assign'
`removeMeta`	bool	Will force clones and strip $ctrl and meta properties from documents

Source:

controldb.js, line 3787

Returns:

Array of documents in the resultset

Type: array

Example

var resutls = users.chain().find({ age: 34 }).data();

eqJoin(joinData, leftJoinKey, rightJoinKey, mapFunopt, dataOptionsopt) → {Resultset}

eqJoin() - Left joining two sets of data. Join keys can be defined or calculated properties eqJoin expects the right join key values to be unique. Otherwise left data will be joined on the last joinData object with that key

Parameters:

Name Type Attributes Description

joinData

Array | Resultset | Collection

Data array to join to.

leftJoinKey

string | function

Property name in this result set to join on or a function to produce a value to join on

rightJoinKey

string | function

Property name in the joinData to join on or a function to produce a value to join on

mapFun

function

(Optional) A function that receives each matching pair and maps them into output objects - function(left,right){return joinedObject}

dataOptions

object

options to data() before input to your map function

Properties

Name	Type	Description
`removeMeta`	bool	allows removing meta before calling mapFun
`forceClones`	boolean	forcing the return of cloned objects to your map object
`forceCloneMethod`	string	Allows overriding the default or collection specified cloning method.

Source:

controldb.js, line 4001

Returns:

A resultset with data in the format [{left: leftObj, right: rightObj}]

Type: Resultset

Example

var db = new controldb('sandbox.db');

var products = db.addCollection('products');
var orders = db.addCollection('orders');

products.insert({ productId: "100234", name: "flywheel energy storage", unitCost: 19999.99 });
products.insert({ productId: "140491", name: "300F super capacitor", unitCost: 129.99 });
products.insert({ productId: "271941", name: "fuel cell", unitCost: 3999.99 });
products.insert({ productId: "174592", name: "390V 3AH lithium bank", unitCost: 4999.99 });

orders.insert({ orderDate : new Date("12/1/2017").getTime(), prodId: "174592", qty: 2, customerId: 2 });
orders.insert({ orderDate : new Date("4/15/2016").getTime(), prodId: "271941", qty: 1, customerId: 1 });
orders.insert({ orderDate : new Date("3/12/2017").getTime(), prodId: "140491", qty: 4, customerId: 4 });
orders.insert({ orderDate : new Date("7/31/2017").getTime(), prodId: "100234", qty: 7, customerId: 3 });
orders.insert({ orderDate : new Date("8/3/2016").getTime(), prodId: "174592", qty: 3, customerId: 5 });

var mapfun = function(left, right) {
  return {
    orderId: left.$ctrl,
    orderDate: new Date(left.orderDate) + '',
    customerId: left.customerId,
    qty: left.qty,
    productId: left.prodId,
    prodName: right.name,
    prodCost: right.unitCost,
    orderTotal: +((right.unitCost * left.qty).toFixed(2))
  };
};

// join orders with relevant product info via eqJoin
var orderSummary = orders.chain().eqJoin(products, "prodId", "productId", mapfun).data();

console.log(orderSummary);

find(query, firstOnlyopt) → {Resultset}

Used for querying via a mongo-style query object.

Parameters:

Name	Type	Attributes	Description
`query`	object		A mongo-style query object used for filtering current results.
`firstOnly`	boolean	<optional>	(Optional) Used by collection.findOne()

Source:

controldb.js, line 3464

Returns:

this resultset for further chain ops.

Type: Resultset

Example

var over30 = users.chain().find({ age: { $gte: 30 } }).data();

map(mapFun, dataOptionsopt)

Applies a map function into a new collection for further chaining.

Parameters:

Name Type Attributes Description

mapFun

function

javascript map function

dataOptions

object

options to data() before input to your map function

Properties

Name	Type	Description
`removeMeta`	bool	allows removing meta before calling mapFun
`forceClones`	boolean	forcing the return of cloned objects to your map object
`forceCloneMethod`	string	Allows overriding the default or collection specified cloning method.

Source:

controldb.js, line 4077

Example

var orders.chain().find({ productId: 32 }).map(function(obj) {
  return {
    orderId: $ctrl,
    productId: productId,
    quantity: qty
  };
});

mapReduce(mapFunction, reduceFunction) → {value}

data transformation via user supplied functions

Parameters:

Name	Type	Description
`mapFunction`	function	this function accepts a single document for you to transform and return
`reduceFunction`	function	this function accepts many (array of map outputs) and returns single value

Source:

controldb.js, line 3945

Returns:

The output of your reduceFunction

Type: value

Example

var db = new controldb("order.db");
var orders = db.addCollection("orders");
orders.insert([{ qty: 4, unitCost: 100.00 }, { qty: 10, unitCost: 999.99 }, { qty: 2, unitCost: 49.99 }]);

function mapfun (obj) { return obj.qty*obj.unitCost };
function reducefun(array) {
  var grandTotal=0;
  array.forEach(function(orderTotal) { grandTotal += orderTotal; });
  return grandTotal;
}
var grandOrderTotal = orders.chain().mapReduce(mapfun, reducefun);
console.log(grandOrderTotal);

remove() → {Resultset}

Removes all document objects which are currently in resultset from collection (as well as resultset)

Source:

controldb.js, line 3910

Returns:

this (empty) resultset for further chain ops.

Type: Resultset

Example

// remove users inactive since 1/1/2001
users.chain().find({ lastActive: { $lte: new Date("1/1/2001").getTime() } }).remove();

simplesort(propname, options) → {Resultset}

Simpler, loose evaluation for user to sort based on a property name. (chainable). Sorting based on the same lt/gt helper functions used for binary indices.

Parameters:

Name Type Description

propname

string

name of property to sort by.

options

object | bool

boolean to specify if isdescending, or options object

Properties

Name	Type	Attributes	Default	Description
`desc`	boolean	<optional>	false	whether to sort descending
`disableIndexIntersect`	boolean	<optional>	false	whether we should explicity not use array intersection.
`forceIndexIntersect`	boolean	<optional>	false	force array intersection (if binary index exists).
`useJavascriptSorting`	boolean	<optional>	false	whether results are sorted via basic javascript sort.

Source:

controldb.js, line 3202

Returns:

Reference to this resultset, sorted, for future chain operations.

Type: Resultset

Example

var results = users.chain().simplesort('age').data();

sort(comparefun) → {Resultset}

User supplied compare function is provided two documents to compare. (chainable)

Parameters:

Name	Type	Description
`comparefun`	function	A javascript compare function used for sorting.

Source:

controldb.js, line 3169

Returns:

Reference to this resultset, sorted, for future chain operations.

Type: Resultset

Example

rslt.sort(function(obj1, obj2) {
     if (obj1.name === obj2.name) return 0;
     if (obj1.name > obj2.name) return 1;
     if (obj1.name < obj2.name) return -1;
   });

transform(transform, parametersopt) → {Resultset}

transform() - executes a named collection transform or raw array of transform steps against the resultset.

Parameters:

Name	Type	Attributes	Description
`transform`	string \| array		name of collection transform or raw transform array
`parameters`	object	<optional>	(Optional) object property hash of parameters, if the transform requires them.

Source:

controldb.js, line 3085

Returns:

either (this) resultset or a clone of of this resultset (depending on steps)

Type: Resultset

Example

users.addTransform('CountryFilter', [
  {
    type: 'find',
    value: {
      'country': { $eq: '[%lktxp]Country' }
    }
  },
  {
    type: 'simplesort',
    property: 'age',
    options: { desc: false}
  }
]);
var results = users.chain().transform("CountryFilter", { Country: 'fr' }).data();

update(updateFunction) → {Resultset}

Used to run an update operation on all documents currently in the resultset.

Parameters:

Name	Type	Description
`updateFunction`	function	User supplied updateFunction(obj) will be executed for each document object.

Source:

controldb.js, line 3869

Returns:

this resultset for further chain ops.

Type: Resultset

Example

users.chain().find({ country: 'de' }).update(function(user) {
  user.phoneFormat = "+49 AAAA BBBBBB";
});

where(fun) → {Resultset}

where() - Used for filtering via a javascript filter function.

Parameters:

Name	Type	Description
`fun`	function	A javascript function used for filtering current results by.

Source:

controldb.js, line 3713

Returns:

this resultset for further chain ops.

Type: Resultset

Example

var over30 = users.chain().where(function(obj) { return obj.age >= 30; }.data();

(static) Collection#compoundsort(properties) → {Resultset}

Allows sorting a resultset based on multiple columns.

Parameters:

Name	Type	Description
`properties`	array	array of property names or subarray of [propertyname, isdesc] used evaluate sort order

Source:

controldb.js, line 7143

Returns:

Reference to this resultset, sorted, for future chain operations.

Type: Resultset

Example

// to sort by age and then name (both ascending)
rs.compoundsort(['age', 'name']);
// to sort by age (ascending) and then by name (descending)
rs.compoundsort(['age', ['name', true]]);

(static) Collection#copy() → {Resultset}

copy() - To support reuse of resultset in branched query situations.

Source:

controldb.js, line 7064

Returns:

Returns a copy of the resultset (set) but the underlying document references will be the same.

Type: Resultset

(static) Collection#docs(optionsopt) → {array}

Terminates the chain and returns array of filtered documents

Parameters:

Name Type Attributes Description

options

object

allows specifying 'forceClones' and 'forceCloneMethod' options.

Properties

Name	Type	Description
`forceClones`	boolean	Allows forcing the return of cloned objects even when the collection is not configured for clone object.
`forceCloneMethod`	string	Allows overriding the default or collection specified cloning method. Possible values include 'parse-stringify', 'jquery-extend-deep', 'shallow', 'shallow-assign'
`removeMeta`	bool	Will force clones and strip $ctrl and meta properties from documents

Source:

controldb.js, line 7217

Returns:

Array of documents in the resultset

Type: array

Example

var resutls = users.chain().find({ age: 34 }).data();

(static) Collection#find(query, firstOnlyopt) → {Resultset}

Used for querying via a mongo-style query object.

Parameters:

Name	Type	Attributes	Description
`query`	object		A mongo-style query object used for filtering current results.
`firstOnly`	boolean	<optional>	(Optional) Used by collection.findOne()

Source:

controldb.js, line 7183

Returns:

this resultset for further chain ops.

Type: Resultset

Example

var over30 = users.chain().find({ age: { $gte: 30 } }).data();

(static) Collection#map(mapFun, dataOptionsopt)

Applies a map function into a new collection for further chaining.

Parameters:

Name Type Attributes Description

mapFun

function

javascript map function

dataOptions

object

options to data() before input to your map function

Properties

Name	Type	Description
`removeMeta`	bool	allows removing meta before calling mapFun
`forceClones`	boolean	forcing the return of cloned objects to your map object
`forceCloneMethod`	string	Allows overriding the default or collection specified cloning method.

Source:

controldb.js, line 7250

Example

var orders.chain().find({ productId: 32 }).map(function(obj) {
  return {
    orderId: $ctrl,
    productId: productId,
    quantity: qty
  };
});

(static) Collection#simplesort(propname, options) → {Resultset}

Simpler, loose evaluation for user to sort based on a property name. (chainable). Sorting based on the same lt/gt helper functions used for binary indices.

Parameters:

Name Type Description

propname

string

name of property to sort by.

options

object | bool

boolean to specify if isdescending, or options object

Properties

Name	Type	Attributes	Default	Description
`desc`	boolean	<optional>	false	whether to sort descending
`disableIndexIntersect`	boolean	<optional>	false	whether we should explicity not use array intersection.
`forceIndexIntersect`	boolean	<optional>	false	force array intersection (if binary index exists).
`useJavascriptSorting`	boolean	<optional>	false	whether results are sorted via basic javascript sort.

Source:

controldb.js, line 7127

Returns:

Reference to this resultset, sorted, for future chain operations.

Type: Resultset

Example

var results = users.chain().simplesort('age').data();

(static) Collection#sort(comparefun) → {Resultset}

User supplied compare function is provided two documents to compare. (chainable)

Parameters:

Name	Type	Description
`comparefun`	function	A javascript compare function used for sorting.

Source:

controldb.js, line 7108

Returns:

Reference to this resultset, sorted, for future chain operations.

Type: Resultset

Example

rslt.sort(function(obj1, obj2) {
     if (obj1.name === obj2.name) return 0;
     if (obj1.name > obj2.name) return 1;
     if (obj1.name < obj2.name) return -1;
   });

(static) Collection#transform(transform, parametersopt) → {Resultset}

transform() - executes a named collection transform or raw array of transform steps against the resultset.

Parameters:

Name	Type	Attributes	Description
`transform`	string \| array		name of collection transform or raw transform array
`parameters`	object	<optional>	(Optional) object property hash of parameters, if the transform requires them.

Source:

controldb.js, line 7091

Returns:

either (this) resultset or a clone of of this resultset (depending on steps)

Type: Resultset

Example

users.addTransform('CountryFilter', [
  {
    type: 'find',
    value: {
      'country': { $eq: '[%lktxp]Country' }
    }
  },
  {
    type: 'simplesort',
    property: 'age',
    options: { desc: false}
  }
]);
var results = users.chain().transform("CountryFilter", { Country: 'fr' }).data();