Continuation Local Storage (CLS)
Continuation Local Storage (CLS) works like thread local storage in most threaded programming languages,
but is instead based on chains of asynchronous callbacks rather than threads. This package allows you to set and
get values that are scoped to the lifetime of these asynchronous continuations without having to pass the values
via parameters or use closures, and also provides support for 'disposable' semantics at the end of the asynchronous
callback chain. This is a pattern that will be familiar to Microsoft .NET developers who may have used IDisposable
implementations in conjunction with using
scopes.
This package was heaviliy inspired by https://github.com/othiym23/node-continuation-local-storage
var using = using;var getCurrentObject = getCurrentObject; ;
The using()
function establishes scope for the entire duration of the supplied function, regardless of whether that
function executes synchronously, or makes further asynchronous invocations. Furthermore, if the supplied context
objects define a dispose()
function then it will be invoked when all synchronous and asynchronous functions complete
inside the supplied function.
Exported Functions
using
using(contextItems: Object[], asyncFunction: Function)
Creates scope that will be preserved for the lifetime of the supplied asynchronous invocations.
contextItems: An array of objects that will be scoped.
asyncFunction: The root asynchronous function for which scope is to be preserved.
getCurrentObject
getCurrentObject(objectType: Function): Object
Retrieves an object from the current scope.
objectType: A constructor function representing the type of object that should be returned.
Returns an object from the current scope that is of the supplied type; or undefined
if no object of that type could be
found in the current scope.
bindEventEmitter
bindEventEmitter(emitter: EventEmitter)
Binds the specified EventEmitter to the currently active context stack so that listeners added within that scope may access the context items.
emitter: The EventEmitter to bind.
Nested scopes
Use of the using()
function can be nested to create scope hierarchies, and code can continue to access context objects
that have been established at any level in those scope hierarchies:
;
Example Ambient Context Implementation (TypeScript)
The following code demonstrates a typical class definition for implementing ambient context that will be
preserved across all continuations encountered inside a using()
block.
private _state: any; { this_state = state; } public get : any return this_state; public static get : MyContext return <MyContext>;
EventEmitters
Callbacks registered as listeners for EventEmitters are not processed in the same way that asynchronous functions are.
As such, EventEmitter instances must be explicitly bound within the currently active scope using the bindEventEmitter()
function if they are to require access to it.
For example:
let emitter = ;
should be written to use the bindEventEmitter()
function as follows:
let emitter = ;
It should be noted that any context objects that are bound to EventEmitter's will not be disposed of when all
asynchronous functions complete since the events emitted may occur beyond the scope of the using()
block. As a result,
EventEmitters inside using()
blocks should be used sparingly and with caution.