whenthough
v0.4.0
Published
An abstraction for passing around global objects and singletons with multi-paradigm resolution. Minimal, built using esnext, with no imports or shims. Inspired by global-cache.
Downloads
22
Maintainers
Readme
WhenThough (Window)
What is it?
whenthough
is meant to substitute and abstract the use of window
or global
. It offers multiple resolution paradigms, such as resolving through promises, yielded generator values, or by event emission. whenthough
is built using ES6 technologies, includes no shims or polyfills, and is less than 1kb minified and gzipped.
Installation
npm install --save whenthough
Key-Value Sync Usage
// ----------- Acme Module -------------
global.set('acme-module', module); // must happen before importing module calls get
// ----------- Importing Module -------------
import global from 'whenthough';
const acme = global.get('acme-module'); // returns what the value at this point in time
// use acme module here
note: if set
is called after get
then get
will return undefined
.
Key-Value Promise Usage
// ----------- Importing Module -------------
import global from 'whenthough';
const acme = await global.request('acme-module'); // returns a promise
// use acme module here
// ----------- Acme Module -------------
global.set('acme-module', module); // previous await is resolved
Event Usage
// ----------- Importing Module -------------
import global from 'whenthough';
global.on('acme-module', (acme) => {
// use acme module here
});
// ----------- Acme Module -------------
global.set('acme-module', module); // previous event is triggered
note: if an event is defined after set
has been called, then the event will not be triggered.
Generator Usage
// ----------- Importing Module -------------
import global from 'whenthough';
const generator = global.pull('acme-module');
const acme = await generator.next().value; // generates a promise
// use acme module here
// ----------- Acme Module -------------
global.set('acme-module', module); // acme is fullfilled
note: this pattern is useful when the value is changed more than once.
Available Functionality
note: Key
type is type Key = string | symbol
| Member | Description |
| :------------ | ------------ |
| get | get(key: Key): any
Returns the value at this point in time. If set
or upsert
has not been called for the given key then this method returns undefined
. |
| request | request(key: Key): Promise<any>
. Returns a promise. This promise will be resolved with the value of set
or upsert
when either is called. If the value was already resolved and upsert
is called with a new value, a new promise is created and emitted when request
is called. |
| set | set(key: Key, value: any): any
. Sets a value. Calling this method will resolve any existing promises and will trigger any listeners added using the on
or one
method. Any new values retrieved by a generator created through pull
will be resolved by this method. This method cannot change an already set
value; it returns the current stored value, or the provided one if none were previously set before. |
| upsert | upsert(key: Key, value: any): any
. Is the same as set
if no value exists, updates the value otherwise. If a value is changed, rather than set, promises dispensed before the change will still resolve to the previous value. |
| has | has(key: Key): boolean
. Checks to see if a value has been set, this is not a promise. If no value has been set or upserted for the given key then this method returns undefined
. |
| delete | delete(key: Key)
. Deletes a value if it exists; this causes existing unresolved promises to be rejected. |
| clear | clear()
. Deletes all values and promises, causing unfulfilled promises to be rejected. |
| pull | * pull(key: Key): Iterator<Promise<any>>
. Creates a generator method that yields promises which resolve when set
or upsert
are called. |
| on | on(eventName: Key, listener: Function): this
. Assigns a listener to be called when the the value of a key is changed. If a listener is assigned after a change in value, the listener will not be called. |
| once | once(eventName: Key, listener: Function): this
. Like on
, but will only be called once. |
| removeListener | removeListener(eventName: Key, listener: Function): this
. Removes an existing listener set by on
or once
. |
| eventNames | eventNames()
. Returns an array with the names of existing events. |
| emit | emit(eventName: Key, ...data: any): this
. Triggers any on
or once
for a Key
with provided data.|