# whenthough

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

Latest version **0.4.0** (published 2020-09-21) · MIT license · 0 weekly downloads

## Install

```sh
npm install whenthough
pnpm add whenthough
yarn add whenthough
bun add whenthough
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.4.0 |
| Published | 2020-09-21 |
| First published | 2019-11-02 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 13.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Hedzer Ferwerda |
| Maintainers | hedzer |
| Keywords | key value, kv, events, promise, esnext, es6, global-cache, global, window, self, cache, global object |

## Links

- npm: https://www.npmjs.com/package/whenthough
- Repository: https://github.com/Hedzer/whenthough
- Homepage: https://github.com/Hedzer/whenthough#readme
- Issues: https://github.com/Hedzer/whenthough/issues
- npm.io page: https://npm.io/package/whenthough

## Dependencies (2)

- [esm](https://npm.io/package/esm.md) ^3.2.25
- [yield-uid](https://npm.io/package/yield-uid.md) ^0.1.0

## Alternatives

- [memory-cache](https://npm.io/package/memory-cache.md) — 795.0K weekly downloads
- [@httptoolkit/proxy-agent](https://npm.io/package/@httptoolkit/proxy-agent.md) — 11.2K weekly downloads
- [express-cache-controller](https://npm.io/package/express-cache-controller.md) — 5.3K weekly downloads
- [http-cache-middleware](https://npm.io/package/http-cache-middleware.md) — 4.5K weekly downloads
- [cache2](https://npm.io/package/cache2.md) — 1.5K weekly downloads

## Recent versions

- 0.4.0 (latest) — 2020-09-21
- 0.3.0 — 2019-11-20
- 0.2.3 — 2019-11-17
- 0.2.2 — 2019-11-02
- 0.2.0 — 2019-11-02
- 0.1.1 — 2019-11-02
- 0.1.0 — 2019-11-02

## 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
```javascript
// ----------- 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
```javascript
// ----------- 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
```javascript
// ----------- 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
```javascript
// ----------- 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.|

---
_Source: https://npm.io/package/whenthough · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._