@promistream/hold-marker

A utility for holding back EndOfStream/Aborted markers in custom Promistreams from being processed, until all preceding reads have completed. This implements required behaviour for streams that behave specially when encountering end markers; it ensures that those markers are the very last thing to be processed, so that eg. your stream doesn't get finalized prematurely while there are still in-flight reads.

Usage

To use this package, you wrap (the Promise returned from) an upstream read call in a holdMarkers call, the function for which you receive after initializing a "marker holder" instance. Like so:

const createMarkerHolder = require("@promistream/hold-markers");

// ...

let holdMarkers = createMarkerHolder();

// ...

// at the point where you're reading:
let result = await holdMarkers(source.read());

It is important that you immediately wrap the read Promise in the holdMarkers call; it must happen in the same tick that you initiated the call, so you cannot do the wrapping at some later (asynchronous) time. Likewise, you must use the wrapped Promise, and not the original one that you passed in, which you should consider to have been 'consumed'. If you get either of these wrong, you will run into unpredictable "unhandled rejection" errors that crash your process.

You will typically need a separate "marker holder" instance per stream instance; if you try to reuse one, you'll get the reads of different streams or stream instances mixed up.

Example

TODO

API

let holdMarkers = createMarkerHolder(contextName)

Creates a new 'marker holder'. You need to create a separate one for every stream instance.

• contextName: Optional. A name that describes the context in which this library is used; usually the name of the stream. This is used in debug logs.

holdMarkers(promise)

Returns a 'wrapped' version of the Promise that holds back EndOfStream/Aborted markers (if any) until all non-marker reads have completed.

• promise: Required. The promise to wrap.