Getting started with @d-cat/digital-data-manager

The Digital Data Manager (DDM) provides an API for centralized access to DDM Core's event emitter and state tree.

Install

npm i @d-cat/digital-data-manager

Usage

import * as _ddm from '@d-cat/digital-data-manager';

import { emit, subscribe } from '@d-cat/digital-data-manager';

General working

All methods in this package subscribe to 3 events and execute after these events are emitted in DDM Core. These events are:

• _ddm.loaded
• _dd.loaded
• _ddm.core.initiated.ready

Hooks

Emitter Hooks

Hooks that access DDM's Event Emitter.

emit <T>({ event: string, data?: IPayload & T }): Promise<void>

emit emits an event in DDM's event emitter. Subscribers to the emitted event will execute in subscribed order.

Parameters

| parameter | type | description | | --------- | ------ | --------------------------------------------------------------------------------------- | | event | string | Name of the event (dot notated, wildcards apply). | | data | T | The payload of the event. Payload contains data or dd key. Defaults to an empty object. |

Examples

interface IData {
  foo: string;
}

const myAsyncTriggerFunction = async (): Promise<void> => {
  const event = 'ziggo.loaded';
  const data: IData = {
    foo: 'bar',
  };

  return await emit<IData>({ event, data }); // Promise<undefined>
};

isEmitted (event: string): Promise<boolean>

isEmitted returns if an event is already emitted.

Parameters

| parameter | type | description | | --------- | ------ | ------------------------------------------------- | | event | string | Name of the event (dot notated, wildcards apply). |

Examples

const myAsyncFunction = async (): Promise<void> => {
  const event = 'ziggo.loaded';

  return await isEmitted(event); // Promise<boolean>
};

subscribe <T>({ event: string[]|string, invokeHandlerOnHistoricalEvents: boolean, handler: (e?: IPayload & T) => void, id: string} ): void

Subscribes to an event. By default, the handler function will be called for historical events as well. It is possible to provide multiple eventnames as an array. All the events in the array must have been emitted before the handler is being called.

Parameters

| parameter | type | description | | --------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------- | | event | string|string[] | Name of event(s) to subscribe to (dot notated, wildcards apply). | | invokeHandlerOnHistoricalEvents | boolean | Boolean that indicates if the handler should also be invoked for historical events. Default is true. | | handler | function | The handler that has to be invoked. | | id | string | The unique identifier given to this handler. This is used for error handling to aid in debugging. |

Examples

const mySyncFunction = (): void => {
  const event = 'event.to.subscribe.to';

  // there is always a data prop in the object with your props
  // for your own data.
  const handler = ({ data }) => {
    return data;
  };

  return subscribe({ event, handler });
};

State Hooks

Hooks that access DDM's state tree.

set <T>({ path: string, value: T, persist?: boolean, ttl?: int }): Promise<T>

Set dispatches an action. This is the only way to set a value in DDM's store. It stores an object at a given dot notated path. Existing properties with the same name will be overwritten; except if an object already exists at the given path, the provided data will be merged with the existing object.

Parameters

Object with the following parameters:

| parameter | type | description | | --------- | --------- | ------------------------------------------------------------------- | | path | string | The dot notated path of the object/property that you want to store. | | value | * | The value that you want to store. | | persist | {Boolean} | Whether to persist this key or not. Defaults to false. | | ttl | {Integer} | Number of minutes to persist the value. Defaults to 30 minutes. |

Example

const myAsyncSetFunction = async <T>(): Promise<T> => {
  const path = 'dot.notated.path';
  const value = 1;

  return await set<number>({ path, value }); // Promise<1>
};

get <T>({ path?: string, defaultValue?: T, createNonExisting?: boolean }): Promise<T>

Returns the current readonly state tree of DDM. It is equal to the last value returned by the store's reducer. You can either retreive data for a dot-notated path, or entire state when no path is given. If no value/object is available at the path, you can optionally create the value/object at that path using a provided value. The later is merely for convenience.

For convenience, the readonly state tree is always written to window._dd.

Parameters

| parameter | type | description | | ------------------- | --------- | --------------------------------------------------------------------------------------------------------------- | | path | {String} | The dot notated path of the object/property that you want to retrieve. Or leave empty to retreive state tree. | | defaultValue | * | An optional defaultValue that you want to use if no object/property is available at the provided path. | | createNonExisting | {Boolean} | Determines if the object/property should be added to DigitalData, using the defaultValue, if it does not exist. |

Example

const myAsyncSetFunction = async <T>(): Promise<T> => {
  const path = 'dot.notated.path';
  const value = 1;

  return await set<number>({ path, value }); // Promise<1>
};

const myAsyncGetFunction = async () => {
  const path = 'dot.notated.path';
  return await get<number>({ path }); // Promise<1>
};

push <T>({ path: string, value: T }): Promise<T>

Push dispatches an action. This is the only way to set an array value in DDM's store.

Parameters

| parameter | type | description | | --------- | ------ | ------------------------------------------------------------------- | | path | String | The dot notated path of the object/property that you want to store. | | value | Array | The value that you want to store. |

Example

const myAsyncPushFunction = async (): Promise<any[]> => {
  const path = 'dot.notated.path.to.array';
  const value = 10;

  return await push({ path, value }); // Promise<[10]>
};

has (path: string): Promise<boolean>

Validates if a dot notated path exists in the dataLayer.

Parameters

| parameter | type | description | | --------- | ------ | ------------------------------------------------------------------- | | path | String | The dot notated path of the object/property that you want to validate. |

Example

const myAsyncHashFunction = async (): Promise<boolean> => {
  const path = 'dot.notated.path';

  return await has(path); // boolean
};

change <T>({ path: string, onlyInvokeOnChanges: boolean, handler: (e?: T) => void, id: string }): Promise<{ unlisten: () => void }>

Change adds a subscriber to a state value. Those listeners are being invoked whenever there is a dispatch on the path we listen to. Wildcards do apply (* and **).

Parameters

| parameter | type | description | | --------------------- | --------- | ------------------------------------------------------------------------------- | | path | String | The dot notated path of the object/property that you want to listen to. | | onlyInvokeOnChanges | {Boolean} | Boolean to indicate that the handler should only be invoked when changes occur. | | handler | Function | TThe handler that has to be invoked. | | id | {String} | Descriptive name. |

Example

interface IMyObject {
  foo: string;
}

const myAsyncChangeFunction = async (): Promise<{ unlisten: () => void }> => {
  const path = 'dot.notated.path';

  const handler = ({ foo }: IMyObject = { foo: 'bar' }) => {
    return foo;
  };

  return await change<IMyObject>({ path, handler }); // Promise<{ unlisten: () => void }>
};

erase (path: string): Promise<void>

Erase dispatches an erase action at the provided path. It also erases both change and persistency listeners.

Parameters

| parameter | type | description | | --------- | ------ | ------------------------------------------------------------------- | | path | string | The dot notated path of the object/property that you want to erase. |

Example

const myAsyncPushFunction = async (): Promise<void> => {
  const path = 'dot.notated.path';
  return await erase(path); // Promise<void>
};

persist ({ path: string, ttl?: number }): Promise<void>

Dispatches a state value as persisted. A TTL can be provided in minutes how long the value should be persisted. Defaults to 30 minutes.

Parameters

| parameter | type | description | | --------- | ------ | ------------------------------------------- | | path | string | Dot-notated path into DDM Core's datalayer. | | ttl | number | Expiration in minutes. Default is 30. |

Examples

const myAsyncPersistFunction = async (): Promise<void> => {
  const path = 'dot.notated.path';
  const ttl = 500;

  return await persist({ path, ttl }); // Promise<void>
};

unpersist (path: string): Promise<void>

Erases a persisted state value from the persistency object.

Parameters

| parameter | type | description | | --------- | ------ | -------------------------------------------------------- | | path | string | Dot-notated path into DDM Core's datalayer to unpersist. |

Examples

const myAsyncUnpersistFunction = async (): Promise<void> => {
  const path = 'dot.notated.path';
  return await unpersist(path); // Promise<void>
};