express-async-context

Zero-dependency context-provision for express-application based on the AsyncLocalStorage.
   

- Installation
- Usage
- Motivation
- API Reference

Installation

``shell
npm install express-async-context
`

Usage

Live Demo on Sandbox

`ts
import express from 'express';
import createContext from 'express-async-context';

const Context = createContext(req => ({
traceId: req.headers['x-request-id'] ?? Math.random().toFixed(20).slice(2),
}));

const app = express();

app.use(Context.provider);

app.get('/trace-id', Context.consumer(
(req, res) => ({ traceId }) => res.json({ traceId }),
));

app.listen(8080, () => {
console.log('Server is listening on port: 8080');
console.log('Follow: http://localhost:8080/trace-id');
});
`

`shell
curl -H "X-Request-Id: 58895124899023443277" http://localhost:8080/trace-id
`

Motivation

The express-async-context library is designed to aproach context provision to the
chain of request handling in the express-application without mutation of the
request or/and response.

Under the hood library uses AsyncLocalStorage
and is based on the thunk-idiom
that means calculation postponed until it will be provided with the context.

The main benifit of context we can get when we use IoC-container as a context.
To make such injection safe the static type-safe containers required, as instance:
true-di.


See Live DI Demo on Sandbox

!DI Through Context

API Reference

- function createContext
- type ContextFactory
- interface ContextManager
- type HandlerThunk
- type ErrorHandlerThunk
- type Thunk
- type RunFn

$3

`typescript
(contextFactory: ContextFactory): ContextManager;
`

Accepts contextFactory function and creates a ContextManager.

$3

`ts
(req: express.Request, res: express.Response) => T;
`

The type describes function that accepts express.Request, express.Response and returns context data of any type T.

$3

`ts
interface ContextManager {
provider: (req: express.Request, res: express.Response, next: express.NextFunction) => void;
consumer: {
(handler: express.RequestHandler | HandlerThunk): express.RequestHandler;
(handler: express.ErrorRequestHandler | ErrorHandlerThunk): express.ErrorRequestHandler;
}
`

The interface contains two members:

- provider - is an usual express middleware that creates context data
for each request using contextFactory and "_binds_" this data to the request

- consumer - is a decorator for HandlerThunk and ErrorHandlerThunk that converts them
to usual express.RequestHandler and express.ErrorRequestHandler.

$3

`ts
(req: express.Request, res: express.Response, next: express.NextFunction) =>
(context: T, run: RunFn) => void;
`

The curried request handler that requires two-times application.

HandlerThunk could be considered as an express.RequestHandler
that returns a postponed handling of the request -- the Thunk

$3

`ts
(err: any, req: express.Request, res: express.Response, next: express.NextFunction) =>
(context: T, run: RunFn) => void;
`

The curried handler of error trhown during the request processing.

ErrorHandlerThunk could be considered as an express.ErrorRequestHandler that
returns a postponed handling of the error -- the Thunk

$3

`ts
(context: T, run: RunFn) => R
`

The postponed calculation, including handler of the request or an error.
The correspondent function receives context data and the run-function,
that runs any other Thunk.

$3

`ts
(fn: Thunk) => R
`

Runs and injects the context data and itself to the postponed calculation
that accepts as a single argument.

RunFn` returns the result of execution of its argument-function.