wool-store

A module to provide a basic in-memory key-value Store with Pub/Sub mechanism for project build with Wool.

The interface is mainly async to enable future implementation working with persistent Database backends (MongoDB, Redis, Postgres, MariaDB, ...).

Usages

import { Store } from 'wool-store'

const store = Store.build()

await store.set('key', { foo: 'bar' })
const value = await store.get('key')

API Doc

Table of Contents

• Store
  • has
  • get
  • set
  • del
  • find
  • findOne
  • hasSub
  • pub
  • sub
  • unsub
  • hasSubGlobal
  • subGlobal
  • unsubGlobal
  • unsubEveryWhere
  • build
• PubSubType
  • Examples
• PubSub
  • hasGlobal
  • subGlobal
  • has
  • sub
  • unsubGlobal
  • unsub
  • unsubEveryWhere
  • pub
  • pubTo
• StoreError
  • Parameters

Store

An in-memory key-value Store with Pub/Sub mechanism

has

Checks presence of one entry in the key-value store

Parameters

• k string The key of the entry

Returns Promise<boolean> Resolves with the presence when the operation is complete

get

Gets one entry in the key-value store

Parameters

• k string The key of the entry

Returns Promise<any> Resolves with the value when the operation is complete

set

Sets one entry in the key-value store.

Also publish with PubSubType.set type to subscribers.

Parameters

• k string The key of the entry
• v any The value of the entry

Returns Promise<void> Resolves when the operation is complete

del

Deletes one entry in the key-value store.

Also unsubscribe any subscriber and publish the entry with PubSubType.del type.

Parameters

• k string The key of the entry

Returns Promise<void> Resolves when the operation is complete

find

Find entries in the key-value store matching a query.

Returns an async iterable of [key, value] pairs, where each value is mapped by the provided function and filtered by the query predicate or regular expression.

Parameters

• q (function ([string, any]): boolean | RegExp)? A predicate function that receives a [key, value] pair and returns true to include it, or a RegExp to match keys. If omitted, all entries are included. (optional, default undefined)
• f function (any): any? A mapping function applied to each value before filtering. Defaults to the identity function. (optional, default x=>x)

Examples

// Find all keys matching /^foo/ and uppercase the values
for await (const [k, v] of store.find(/^foo/, v => v.toUpperCase())) {
  console.log(k, v);
}

Returns AsyncIterable<[string, any]> Async iterable of filtered [key, mappedValue] pairs.

findOne

Finds the first entry in key-value store matching a query and returns its value

Parameters

• q (function ([string, any]): boolean | RegExp)? A predicate function that receives a [key, value] pair and returns true to include it, or a RegExp to match keys. If omitted, all entries are included. (optional, default undefined)

Returns Promise<(any | undefined)> The value if found, undefined otherwise

hasSub

Checks if a subscription exists on a key for a source

Parameters

• src string The source of the subscription
• k string The key of the subscribed value

Returns Promise<boolean> Resolves with the presence of a subscription when the operation is complete

pub

Triggers a Publish on the entry for a given key with PubSubType.pub type.

Parameters

• k string The key of the entry

Returns Promise<void> Resolves when the operation is complete

sub

Subscribes to an entry on a key for a source with a callback on changes.

Parameters

• src string The source of the subscription
• k string The key of the subscribed value
• cb function (k: string, v: any, t: PubSubType): void The callback triggered when a publish is triggered on a subscribed entry* k The key of the subscribed value
  • v The subscribed value
  • t The type of trigger
• now boolean Triggers a publish with PubSubType.sub type

Returns Promise<void> Resolves when the operation is complete

unsub

Unsubscribes to an entry on a key for a source

Parameters

• src string The source of the subscription
• k string The key of the subscribed value

Returns Promise<void> Resolves when the operation is complete

hasSubGlobal

Checks if a global subscription exists for a source

Parameters

• src string The source of the subscription

Returns Promise<boolean> Resolves with the presence of a subscription when the operation is complete

subGlobal

Subscribes globally for a source with a callback on changes

Parameters

• src string The source of the subscription
• cb function (k: string, v: any, t: PubSubType): void The callback triggered when a publish is triggered on the store* k The key of the subscribed value
  • v The subscribed value
  • t The type of trigger

Returns Promise<void> Resolves when the operation is complete

unsubGlobal

Unsubscribes globally for a source

Parameters

• src string The source of the subscription

Returns Promise<void> Resolves when the operation is complete

unsubEveryWhere

Unsubscribes everywhere for a source

Parameters

• src string The source of the subscription

Returns Promise<void> Resolves when the operation is complete

build

A static Store builder

Returns Store a new Store

PubSubType

An Enum of string, with following valid values :

• sub: triggered on subscription (with now param to true)
• pub: triggered on force publish
• set: triggered on setting a new value
• del: triggered on deleting the key

Type: string

Examples

if (t === PubSubType.sub) {
  ...
}

PubSub

A Pub/Sub utility for Store

hasGlobal

Checks if a global subscription exists for a source

Parameters

• src string The source of the subscription

Returns Promise<boolean> Resolves with the presence of a subscription when the operation is complete

subGlobal

Subscribes globally for a source with a callback on changes

Parameters

• src string The source of the subscription
• cb function (k: string, v: any, t: PubSubType): void The callback triggered when a publish is triggered on the store* k The key of the subscribed value
  • v The subscribed value
  • t The type of trigger

Returns Promise<void> Resolves when the operation is complete

has

Checks if a subscription exists on a key for a source

Parameters

• src string The source of the subscription
• k string The key of the subscribed value

Returns Promise<boolean> Resolves with the presence of a subscription when the operation is complete

sub

Subscribes to an entry on a key for a source with a callback on changes

Parameters

• src string The source of the subscription
• k string The key of the subscribed value
• cb function (k: string, v: any, t: PubSubType): void The callback triggered when a publish is triggered on a subscribed entry* k The key of the subscribed value
  • v The subscribed value
  • t The type of trigger

Returns Promise<void> Resolves when the operation is complete

unsubGlobal

Unsubscribes globally for a source

Parameters

• src string The source of the subscription

Returns Promise<void> Resolves when the operation is complete

unsub

Unsubscribes to an entry on a key for a source

Parameters

• src string The source of the subscription
• k string The key of the subscribed value

Returns Promise<void> Resolves when the operation is complete

unsubEveryWhere

Unsubscribes everywhere for a source

Parameters

• src string The source of the subscription

Returns Promise<void> Resolves when the operation is complete

pub

Triggers a Publish on the entry for a given key

Parameters

• k string The key of the entry
• v any The value of the entry
• t PubSubType The type of publish to send to callback

Returns Promise<void> Resolves when the operation is complete

pubTo

Triggers a Publish on the entry for a given key for a source

Parameters

• src string The source of the subscription
• k string The key of the entry
• v any The value of the entry
• t PubSubType The type of publish to send to callback

Returns Promise<void> Resolves when the operation is complete

StoreError

A custom Error for this module

Parameters

• message string a base message
• params ...any interesting parameters for error analysis