@mocks-server/nested-collections

---

Nested collections

A collections manager that allows to store items with an id and a value. Other descendant collections can be created recursively. Each collection has a method allowing to get items from all descendent collections in a flat way, adding a collection id to each one of them.

It also provides methods for merging the collections, removing items or collections, etc. Events are emitted whenever any descendant collection or item changes.

Usage

A brief example:

const { NestedCollections } = require("@mocks-server/nested-collections");

const alerts = new NestedCollections("alerts");
alerts.set("root", "This alert is stored in the root collection");

const pluginsAlerts = alerts.collection("plugins");
pluginsAlerts.set("foo-alert-id", "This alert is stored in the plugins collection");

const pluginAlertsA = pluginsAlerts.collection("a");
const pluginAlertsB = pluginsAlerts.collection("b");

pluginAlertsA.set("foo-1", "Alert from plugin A");
pluginAlertsB.set("foo-2", "Alert from plugin B");

console.log(alerts.collection("plugins").collection("b").get("foo-2"));
// Alert from plugin B

console.log(alerts.flat);
/*
[
  {
    id: 'root',
    value: 'This alert is stored in the root collection',
    collection: 'alerts'
  },
  {
    id: 'foo-alert-id',
    value: 'This alert is stored in the plugins collection',
    collection: 'alerts:plugins'
  },
  {
    id: 'foo-1',
    value: 'Alert from plugin A',
    collection: 'alerts:plugins:a'
  },
  {
    id: 'foo-2',
    value: 'Alert from plugin B',
    collection: 'alerts:plugins:b'
  }
]
*/

API

NestedCollections

const collection = new NestedCollections("id");

• NestedCollections(id, options). Returns a collection instance.
  • id (String): Id for the root collection
  • options (Object):
    • Decorator - Custom constructor to be used when creating children collections. Useful to extend the NestedCollections class (read "extending NestedCollections" for further info).

collection instance

• get id: Returns the collection id. Used as setter, sets collection id. Do not use it for changing a child collection id. Use renameCollection instead.
• set id: Sets collection id. Do not use it for changing a child collection id. Use renameCollection instead.
• get path: Returns the collection id joined with all parent collections ids using : (parentCollectionId:parentCollectionId:collectionId).
• removeCollection(collectionId): Removes children collection, including all of its items and possible children collections.
  • collectionId (String): Id of the collection to be removed.
• collection(collectionId): Returns child collection with provided id or creates a new one if it does not exists.
  • collectionId (String): Id of the collection to be returned.
• renameCollection(collectionId, newCollectionId): Changes a collection id. Id id already exists in other collection, then it merges them.
  • collectionId (String): Id of the collection to be changed.
  • newCollectionId (String): New id for the collection
• clean(): Clean items and items in children collections recursively.
• set(id, value): Sets the value for the collection item with the provided id or creates a new one if it does not exists.
  • id (String): Id of the item to set the value.
  • value (Any): Value to be stored in the item.
• get(id): Returns the value of the collection item having the provided id.
  • id (String): Id of the item to get the value.
• remove(id): Removes a collection item.
  • id (String): Id of the item to be removed.
• cleanItems(): Removes all collection items.
• get items: Returns all collection items as an array.
• get flat: Returns all collection items and descendent collection items in a flat array. It adds a collection id to each item. For nested collections, the id is built with all parents ids and self id concated by :.
• onChange(callback): Allows to add a listener that will be executed whenever any descendant collection or item changes. It returns a function that removes the listener once executed.
  • callback(value) (Function): Callback to be executed.

Extending NestedCollections

In order to be able to decorate the NestedCollections methods easily, a Decorator option can be passed as second argument to it. When present, it will be used to create children collections, so you can extend the NestedCollections methods, while nested collections will be still created with your class. For example:

class Alerts extends NestedCollections {
  constructor(id, options) {
    // Nested collections will be created always using this class
    super(id, { ...options, Decorator: Alerts });
  }

  // Set method now accepts three arguments, and it always stores an object
  set(id, message, error) {
    return super.set(id, { message, error });
  }
}