WhenMap

WhenMap is an extension of Map that contains only promise instances, inspired by customElements.whenDefined(). WhenMap is particularly useful for decoupling uses of a value from code that initalizes the value.

WhenMap API

import { WhenMap } from 'whenmap'

let when_db = new WhenMap()

let p_ready = when_db.when('example_key')
p_ready.then(v => console.log('Ready!', {v}))

when_db.set('example_key', example_init())

async function example_init() {
  // async initialize process
  return {example: 42}
}

• when_db.when(key) returns a promise for the newly tracked key. The promise may or may not be resolved.

• when_db.ref(key, p) is a observation hook for newly tracked keys.

• when_db.get(key) is an alias for when_db.when(key)

• when_db.set(key, value) resolves the promise for the specified key, returning this.

• when_db.has(key) returns false for untracked keys, true for resolved tracked keys, and 1 for unresolved tracked keys.

• when_db.delete(key) resolves a tracked key as undefined before removing it.

• when_db.clear() resolves any outstanding tracked keys as undefined before clearing all tracked keys.

aiter_pipe API

aiter_pipe(opt) returns a connected [send, recv] pair where send is a function and recv is an async iterable.

• send(value) adds value to the internal queue, after awaiting it if a promisable.

  • opt.on_error(err) is an optional promise .catch() handler.

• send.stop() terminates the async iterable stream from within the init_arg closure.

• send.ready is a promise to provide overflow backpressure.

  • opt.max_size manages the send.ready promise, default of 5

• recv extends the optional prototype

• recv.size returns the interal queue size

• recv supports async iterable protocol: for await (let each of when_stream) {}

  • recv.next() returns the next resolved value
    • if opt.batch, returns list of all resolved values
  • recv.return()
  • recv.throw()
  • recv[Symbol.asyncIterator]()

• an AbortSignal instance is aborted when the stream is stopped.

  • assigned into recv.signal and send.signal

WhenAiter API

WhenAiter is a Promise-like wrapper around aiter_pipe to transform callback events into async iteratable.

import { WhenAiter } from 'whenmap'

// For streaming events
let when_stream = new WhenAiter(send => {
  document.body.addEventListener(
    'some_custom_event',
    evt => send(evt.detail),
    {signal: send.signal})
})

for await (let detail of when_stream) {
  console.log('use aiter event stream:', detail)
}

WhenAiter can also transform a collection promises into an async iteratable.

import { WhenAiter } from 'whenmap'
const sleep = new Promise(done => setTimeout(done, ms, `delay: ${ms}`) )
// For streaming promises as they are settled
let misc_promises = [ sleep(100), sleep(20), sleep(50) ]

for await (let each of WhenAiter.from(misc_promises)) {
  console.log('stream resolved:', detail)
}

• new WhenAiter(init_arg, opt) returns an async iterable.

  • If init_arg is iterable, send() is called on each item.
  • other init_arg(send) is invoked.

• WhenAiter.from(init_arg, opt) is an alias for new WhenAiter

Install

$ npm install whenmap

License

BSD 2-clause