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.

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'
  }
]
*/

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).

• 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.
• get path: Returns the collection id joined with all parent collections ids using : (parentCollectionId:parentCollectionId:collectionId).
• 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.
• removeCollection(collectionId): Removes children collection, including all of its items and possible children collections.
  • collectionId (String): Id of the collection to be removed.
• renameCollection(collectionId, newCollectionId): Changes a collection id. If 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.

For TypeScript users, in order to be able to create NestedCollections with your own set and flat methods, the library also exports a BaseNestedCollections class, allowing to define your own methods by calling to the protected _set and _flat. For example

export class CustomNestedCollections
  extends BaseNestedCollections
  implements CustomNestedCollectionInterface
{
  // Set method now accepts three arguments, and it always stores an object
  public set(id: CollectionId, message: CollectionItemMessage, error: CollectionItemError): CollectionItem {
    // Stores messsage and error as an object using the protected _set method
    return this._set(id, { message, error });
  }

  public get flat(): CollectionFlatItems {
    // You can parse the collection items here at your convenience before returning them
    return this._flat;
  }
};