Oblivion — Module: documents/probe

Queries objects in memory using a mongo-like notation for reaching into objects and filtering for records

Author:

Terry Weiss

License:

Requires

module:lodash

Classes

queryOperators
updateOperators

Members

<static> delimiter :string

The delimiter to use when splitting an expression

Type:

string

Default Value:

<private, inner> nestedOps :array.<string>

The list of operators that are nested within the expression object. These take the form {path:{operator:operand}}

Type:

array.<string>

<private, inner> operations

The query operations that evaluate directly from an operation

<private, inner> prefixOps :array.<string>

The list of operators that prefix the expression object. These take the form {operator:{operands}} or {operator: [operands]}

Type:

array.<string>

Methods

<static> all(obj, qu) → {boolean}

Returns true if all items match the query

Parameters:

Name	Type	Description
`obj`	array \| object	The object to query
`qu`	object	The query to execute. See module:documents/probe.queryOperators for the operators you can use.

Returns:

Type: boolean

<static> any(obj, qu) → {boolean}

Returns true if any of the items match the query

Parameters:

Name	Type	Description
`obj`	array \| object	The object to query
`qu`	object	The query to execute. See module:documents/probe.queryOperators for the operators you can use.

Returns:

Type: boolean

<static> every(obj, qu) → {boolean}

Returns true if all items match the query. Aliases as `all`

Parameters:

Name	Type	Description
`obj`	array \| object	The object to query
`qu`	object	The query to execute

Returns:

Type: boolean

<static> find(obj, qu) → {array}

Find all records that match a query

Parameters:

Name	Type	Description
`obj`	array \| object	The object to query
`qu`	object	The query to execute. See module:documents/probe.queryOperators for the operators you can use.

Returns:

The results

Type: array

<static> findKeys(obj, qu) → {array}

Find all records that match a query and returns the keys for those items. This is similar to module:documents/probe.find but instead of returning records, returns the keys. If `obj` is an object it will return the hash key. If 'obj' is an array, it will return the index

Parameters:

Name	Type	Description
`obj`	array \| object	The object to query
`qu`	object	The query to execute. See module:documents/probe.queryOperators for the operators you can use.

Returns:

Type: array

<static> findOne(obj, qu) → {object}

Returns the first record that matches the query. Aliased as `seek`.

Parameters:

Name	Type	Description
`obj`	array \| object	The object to query
`qu`	object	The query to execute. See module:documents/probe.queryOperators for the operators you can use.

Returns:

Type: object

<static> findOneKey(obj, qu) → {object}

Returns the first record that matches the query and returns its key or index depending on whether `obj` is an object or array respectively. Aliased as `seekKey`.

Parameters:

Name	Type	Description
`obj`	array \| object	The object to query
`qu`	object	The query to execute. See module:documents/probe.queryOperators for the operators you can use.

Returns:

Type: object

<static> get(path, record) → {*}

Reaches into an object and allows you to get at a value deeply nested in an object. This is not a query, but a straight reach in, useful for event bindings

Parameters:

Name	Type	Description
`path`	array	The split path of the element to work with
`record`	object	The record to reach into

Returns:

Whatever was found in the record

Type: *

<static> mixin(obj, collection)

Binds the query and update methods to a specific object and adds the methods to that object. When called these methods can skip the first parameter so that find(object, query) can just be called as object.find(query)

Parameters:

Name	Type	Description
`obj`	object \| array	The object or array to bind to
`collection`	object \| array	If the collection is not the same as `this` but is a property, or even a whole other object, you specify that here. Otherwise the `obj` is assumed to be the same as the collecion

<static> proxy(obj) → {object}

Binds the query and update methods to a new object. When called these methods can skip the first parameter so that find(object, query) can just be called as find(query)

Parameters:

Name	Type	Description
`obj`	object \| array	The object or array to bind to

Returns:

An object with method bindings in place

Type: object

<static> remove(obj, qu) → {object|array}

Remove all items in the object/array that match the query

Parameters:

Name	Type	Description
`obj`	array \| object	The object to query
`qu`	object	The query to execute. See module:documents/probe.queryOperators for the operators you can use.

Returns:

The array or object as appropriate without the records.

Type: object | array

<static> set(path, record, setter, newValue)

This will write the value into a record at the path, creating intervening objects if they don't exist. This does not work as filtered update and is meant to be used on a single record. It is a nice way of setting a property at an arbitrary depth at will.

Parameters:

Name	Type	Description
`path`	array	The split path of the element to work with
`record`	object	The record to reach into
`setter`	string	The set operation. See module:documents/probe.updateOperators for the operators you can use.
`newValue`	object	The value to write to the, or if the operator is $pull, the query of items to look for

<static> some(obj, qu) → {boolean}

Returns true if any of the items match the query. Aliases as `any`

Parameters:

Name	Type	Description
`obj`	array \| object	The object to query
`qu`	object	The query to execute

Returns:

Type: boolean

<static> unique(obj, qu) → {array}

Returns the set of unique records that match a query

Parameters:

Name	Type	Description
`obj`	array \| object	The object to query
`qu`	object	The query to execute. See module:documents/probe.queryOperators for the operators you can use.

Returns:

Type: array

<static> update(obj, qu, setDocument)

Updates all records in obj that match the query. See module:documents/probe.updateOperators for the operators that are supported.

Parameters:

Name	Type	Description
`obj`	object \| array	The object to update
`qu`	object	The query which will be used to identify the records to updated
`setDocument`	object	The update operator. See module:documents/probe.updateOperators

<private, inner> execQuery(obj, qu, shortCircuit, stopOnFirst)

Executes a query by traversing a document and evaluating each record

Parameters:

Name	Type	Argument	Description
`obj`	array \| object		The object to query
`qu`	object		The query to execute
`shortCircuit`	boolean	<nullable>	When true, the condition that matches the query stops evaluation for that record, otherwise all conditions have to be met
`stopOnFirst`	boolean	<nullable>	When true all evaluation stops after the first record is found to match the conditons

<private, inner> parseQueryExpression(obj) → {object}

Parses a query request and builds an object that can used to process a query target

Parameters:

Name	Type	Description
`obj`	object	The expression object

Returns:

All components of the expression in a kind of execution tree

Type: object

<private, inner> processExpressionObject(val, key) → {object}

Interrogates a single query expression object and calls the appropriate handler for its contents

Parameters:

Name	Type	Description
`val`	object	The expression
`key`	object	The prefix

Returns:

A formatted operation definition

Type: object

<private, inner> processNestedOperator(path, operand) → {object}

Processes a nested operator by picking the operator out of the expression object. Returns a formatted object that can be used for querying

Parameters:

Name	Type	Description
`path`	string	The path to element to work with
`operand`	object	The operands to use for the query

Returns:

A formatted operation definition

Type: object

<private, inner> processPrefixOperator(operation, operand) → {object}

Processes a prefixed operator and then passes control to the nested operator method to pick out the contained values

Parameters:

Name	Type	Description
`operation`	string	The operation prefix
`operand`	object	The operands to use for the query

Returns:

A formatted operation definition

Type: object

<private, inner> pushin(path, record, setter, newValue)

This will write the value into a record at the path, creating intervening objects if they don't exist

Parameters:

Name	Type	Description
`path`	array	The split path of the element to work with
`record`	object	The record to reach into
`setter`	string	The set command, defaults to $set
`newValue`	object	The value to write to the, or if the operator is $pull, the query of items to look for

<private, inner> reachin(path, record) → {*}

Reaches into an object and allows you to get at a value deeply nested in an object

Parameters:

Name	Type	Description
`path`	array	The split path of the element to work with
`record`	object	The record to reach into

Returns:

Whatever was found in the record

Type: *

<private, inner> splitPath(path) → {array}

Splits a path expression into its component parts

Parameters:

Name	Type	Description
`path`	string	The path to split

Returns:

Type: array