Reference

General behavior

• All non-querying methods return the object on which they were called.
• All querying methods return data node(s) wrapped in a Flock datastore object.
• Scope for all methods is the current node and its sub-tree.

Core

flock(root, options)

Creates a Flock datastore object out of a data node. May take optional flags that turn off features for performance gain.

Arguments

• root: Any JavaScript object that we want to further query, modify, or receive events of modifications within.
• options: A set of flags controlling the flock's behavior.
  • noevent: No events. Turns off methods .on, .off, .delegate, .once, and .trigger.
  • nomulti: No complex queries, only single nodes may be accessed. Turns off method .query.
  • nochaining: No wrapping of querying methods in Flock object. Methods .get, .parent, .closest, and .query will return raw data instead.

Special value for options: flock.COMPAT, compatible with flock 1.6, and is equal to flags noevent and nochaining being turned on.

Example

var ds = flock({
    employees: {
        Green: {
            John: {}
        },
        Smith: {
            John: {}
            Matt: {}
        }
    }
});

.root

Datastore node object.

Read-only property.

Example

ds
    .get('employees.Smith.John')
    .root; // {...}

Querying

.get(path, nochaining)

Rertieves a single node from the specified path.

Arguments

• path: Datastore path relative to current node. May be in string or array notation. See Path for details on path format.
• nochaining: Flag when true, will return datastore node instead of flock object. Affects the current call only. May be set globally on initializing the main flock object. See above.

Example

// retrieves node for John Smith
var result = ds.get('employees.Smith.John');

.mget(path, options)

Retrieves all nodes matching the path expression. Not available when nomulti is on.

Arguments

• path: Datastore path relative to current node. May be in string or array notation. See Path for details on path format.
• options:
  • limit: Maximum number of entries to retrieve. Default unlimited (undefined).
  • mode: What to do or return upon querying. See below for possible values. Default: flock.VALUES.
  • loopback: Whether to traverse loopbacks. Default: false.
  • undef: Whether to collect undefined entries. Default: false.
  • value: Value to set or callback function the result of which to set on each affected node. When left undefined, .query returns collected nodes.

Values for mode:

• flock.KEYS: Only keys of traversed nodes are collected in an array. The same key may be included multiple times.
• flock.VALUES: Only values of traversed nodes are collected in an array.
• flock.BOTH: Both keys and values are collected. Keys are unique. Values with the same key may overwrite each other.
• flock.DEL: Deletes affected nodes.
• flock.COUNT: Counts affected nodes.

Example

// returns nodes for all employees with first name 'John'
var result = ds.query('employees.*.John'); // flock([{...}, {...}, {...}, ...])

.map(path1, path2, ...)

Maps immediate child nodes to fit structure defined by the values on the provided relative paths. Should be used on nodes with uniform children, such as arrays.

Arguments

Each argument is a path in either string or array notation.

Last argument specifies leaf nodes. If it's an empty path, original child nodes will be used as leaf nodes in the output.

Behavior

Doesn't check uniqueness. Equivalent leaf nodes will overwrite each other.

Example

The following code creates a lookup by employees' department and last name. Notice how the two Smiths overwrite one another.

var ds = flock({
    employees: {
        emp1: {fname: "John", lname: "Smith", department: "IT"},
        emp2: {fname: "John", lname: "Green", department: "HR"},
        emp3: {fname: "Matt", lname: "Smith", department: "IT"},
    }
});

ds
    .get('employees')
    .map(['department'], ['lname'], ['fname']);

/* flock({
    IT: {Smith: "Matt"},
    HR: {Green: "John"}
}) */

Modification

General behavior

• When option noevent is on, modification methods don't fire events.

.set(path, value, options)

Stores a single value on the specified path.

Arguments

• path: Datastore path relative to current node. May be in string or array notation. See Path for details on path format.
• value: Any variable. When value is object, its contents become queryable.
• options:
  • data: Custom data to be passed to event handler.
  • trigger: Whether to trigger event on change. Default: true.

Behavior

Fires flock.CHANGE event if the affected node was previously set, and also flock.ADD otherwise.

Example

ds
    .get('employees')
    .set('Smith.John', {height: 5.7});

.unset(path, options)

Removes node from datastore at the specified path.

Arguments

• path: Datastore path relative to current node. May be in string or array notation. See Path for details on path format.
• options:
  • data: Custom data to be passed to event handler.
  • trigger: Whether to trigger event on change. Default: true.

Behavior

Fires flock.REMOVE event on successful removal.

Example

ds
    .get('employees')
    .unset('Smith.John');

.cleanup(path)

Same as .unset() but removes empty parent nodes as well.

Behavior

Fires flock.REMOVE event on successful removal.

Example

In the example below, the node employees.Green, which would have been left empty using .unset, is removed as well.

ds.cleanup('employees.Green.John'); // {employees: Smith: {John: {}, Matt: {}}}

Events

.on(path, eventName, handler)

Subscribes to event on the current node.

Arguments

• path: Datastore path to be observed.
• eventName: Name of expected event.
• handler: Event handler function. Arguments:
  • event: Object containing target datastore node and name event name.
  • data: Custom data that was passed along to the event trigger.

Example

Subscribes to all changes in the 'employee' branch of the datastore.

ds
    .get('employees')
    .on('changed', function () { alert("boo!"); });

.one(path, eventName, handler)

Same as .on except event is captured only once. After being captured, automatically unsubscribes from event.

.delegate(path, eventName, pPath, handler)

Delegates event capturing to a path relative to current node.

Arguments

• pPath: Node to delegate capturing to. May be in string or array notation. When option nomulti is not set, pPath may be a query expression. See Path for details on path format.

For the rest of the arguments, see .on.

Example

Subscribes to all changes affecting the node 'employees.Smith'.

ds
    .delegate('employees', 'change', 'Smith', function () { alert("boo!"); });

.off(path, eventName, handler)

Unsubscribes from an event.

Arguments

• path: Datastore path that was observed.
• eventName: Event name.
• handler: Event handler function. Optional. When argument handler is omitted, all handlers pertaining event eventName will be removed from the current node, including delegates.

Example

Node 'employees' no longer captures events.

ds
    .off('employees', 'change');

.trigger(path, eventName, options)

Triggers event on the specified path.

Arguments

• path: Datastore path to trigger the event on.
• eventName: Event name.
• options:
  • data: Custom data to be passed to event handlers.
  • target: Custom event target.

Example

ds
    .get('employees.Smith.John')
    .trigger('myEvent', {foo: "bar"});

Utilities