cycle-store

Provides nestable storage containers for cycle.js applications.

Installation

npm i cycle-store --save

Scripts

NOTE: Make sure you've installed all dependencies using npm install first.

To generate documentation: npm run doc. This will create documentation in the build/docs folder.

To run unit tests: npm test

API

Store

Kind: global class
Inherits: Broker

• Store
  • new Store()
  • instance
    • .for(name) ⇒ Store
    • .parent() ⇒ Store | undefined
    • .root() ⇒ Store
    • .has(name) ⇒ Boolean
    • .get(name) ⇒ Observable
    • .set(name, value) ⇒ Store
    • .delete(name)
    • .clear([nested])
    • "itemSet"
    • "itemRemoved"
    • "storeCleared"
    • "storeCreated"
  • static
    • .Events : Events
  • inner
    • ~Events : Object

new Store()

Provides container-based storage for cycle.js applications.

Example

var Store = require('cycle-store').Store,
    root = new Store(),
    data = Store.for('records');
Observable.combineLatest(
    btnSaveClicked$,
    data.get('saveCommand'),
    data.get('activeRecord')
).subscribe(function doSaveRecord(_, cmd, record) {
    cmd.invoke(record);
});
data.set('saveRecord', new Command());
data.set('activeRecord', new Record());

store.for(name) ⇒ Store

Retrieves (and creates, if necessary) a child container within the current store.

Kind: instance method of Store
Throws:

• Error Parameter name must be a non-empty string

| Param | Type | Description | | --- | --- | --- | | name | String | The name of the child store to create/retrieve. You can specify nested stores by separating stores with a "/" -- see the examples for details. |

Example

var root = new Store(),
    child = root.for('child'),
    grandchild = child.for('child');
root.for('child/grandchild')) === grandchild; // true

store.parent() ⇒ Store | undefined

Retrieves the parent of the current store. For the root store, this method returns undefined. NOTE: The parent store returned from this method is readonly -- set, clear, and delete will not work and will instead throw errors.

Kind: instance method of Store
Example

if (child.parent().has('some-key')) {
   // ...
}

store.root() ⇒ Store

Retrieves the root store. NOTE: The root store returned from this method is readonly -- set, clear, and delete will not work and will instead throw errors.

Kind: instance method of Store
Example

for (let item of child.root()) {
    log(item.value);
}

store.has(name) ⇒ Boolean

Returns true if the store contains the specified key; otherwise, returns false. NOTE: This method does not consider ancestor stores or child stores, only the store on which it was called.

Kind: instance method of Store
Throws:

• Error Parameter name must be a non-empty string

| Param | Type | Description | | --- | --- | --- | | name | String | The name of the item whose existence should be checked. |

Example

// before setting the key:
store.has('key'); // false
// after setting the key:
store.set('key', 'value');
store.has('key'); // false
// still returns false on child store:
store.for('child').has('key'); // false

store.get(name) ⇒ Observable

Returns an Observable instance whose subscribers will be notified whenever a value exists for the specified key. NOTE: Once a value exists in a child store, inherited value changes will no longer be sent to subscribers. In other words, child store values always take precedence over ancestor store values. See the examples for details.

Kind: instance method of Store
Returns: Observable - A stream of value changes for the specified key.
Throws:

• Error Parameter name must be a non-empty string

| Param | Type | Description | | --- | --- | --- | | name | String | The name of the item whose existence should be checked. |

Example

store.get('some/child/key')
    .subscribe(function onNext(value) {
        log('current value:', value);
    });
store.set('key', 123); // current value: 123
store.set('some/key', 'abc'); // current value: abc
// changing value on store won't update the nested
// value because the 'some' store takes priority:
store.set('key', 'another'); // current value: abc
store.set('some/child/key', 0); // current value: 0
// and now that 'some/child/key' has been set, any
// changes made to 'some/key' will not be propagated:
store.set('some/key', 'nope'); // current value: 0

store.set(name, value) ⇒ Store

Adds or updates a value in the store. You can specify a nested store in the name using forward slashes (/) See the examples for details.

Kind: instance method of Store
Returns: Store - The Store instance on which set was called.
Throws:

• Error Parameter name must be a non-empty string

Emits: itemSet

| Param | Type | Description | | --- | --- | --- | | name | String | The name of the item to set. | | value | * | The value to associate with the specified key. |

Example

store.set('key', 'value');

Example

store
    .set('key', 'base value')
    .set('child/key', 'override value')
    .set('child/grandchild/key', 'another override value');

store.delete(name)

Removes an instance from the store. You can specify nested stores using forward slashes (/) in the name. See the examples for details.

Kind: instance method of Store
Throws:

• Error Parameter name must be a non-empty string

Emits: itemRemoved

| Param | Type | Description | | --- | --- | --- | | name | String | The name of the item to delete. |

Example

store.set('key', 'value');
store.delete('key');

Example

store.delete('child/key');

store.clear([nested])

Removes all items in the store (and, optionally, in nested stores).

Kind: instance method of Store
Emits: storeCleared

| Param | Type | Default | Description | | --- | --- | --- | --- | | [nested] | Boolean | false | true to remove all items from nested stores. Default is false. |

Example

store
    .set('key a', 'value 1')
    .set('key b', 'value 2')
    .clear();

"itemSet"

An item was added to or updated in the store instance.

Kind: event emitted by Store
Properties

| Name | Type | Description | | --- | --- | --- | | name | String | The name of the item added or updated. | | value | * | The new value of the item. |

Example

store.on(Store.Events.SET, function(data) {
  log.info('An item was added:', data.name, data.value);
});

"itemRemoved"

An item was removed from the store.

Kind: event emitted by Store
Properties

| Name | Type | Description | | --- | --- | --- | | name | String | The name of the item removed from the store. |

Example

store.on(Store.Events.REMOVED, function(data) {
  log.info(data.name, 'was removed');
});

"storeCleared"

All items were removed from the store instance.

Kind: event emitted by Store
Example

store.on(Store.Events.CLEARED, function(data) {
  log.info('The store has been cleared.');
});

"storeCreated"

A new nested store has been created.

Kind: event emitted by Store
Properties

| Name | Type | Description | | --- | --- | --- | | name | String | The name of the newly created store. | | child | Store | The newly created store instance. |

Example

store.on(Store.Events.CREATED, function(data) {
  log.info('A new store was created:', data.name);
  data.store.set('created-on', Date.now());
});

Store.Events : Events

An enumeration of event names used internally that external callers can also subscribe to.

Kind: static property of Store
Example

store.on(Store.Events.SET, function itemAdded() { ... });
store.on(Store.Events.REMOVED, function itemRemoved() { ... });

Store~Events : Object

Kind: inner typedef of Store
Properties

| Name | Type | Description | | --- | --- | --- | | SET | String | 'item-set' - An item was added or updated. | | REMOVED | String | 'item-removed' - An item was removed. | | CLEARED | String | 'store-cleared' - All items were removed. | | CREATED | String | 'store-added' - A new child store was created. |