@dalet-oss/express-http-context 1.2.0 → 1.2.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2017 Steve Konves
+Copyright (c) 2025 Dalet
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,86 +1,150 @@
-[![travis](https://img.shields.io/travis/dalet-oss/express-http-context.svg)](https://travis-ci.org/dalet-oss/express-http-context)
-[![coveralls](https://img.shields.io/coveralls/dalet-oss/express-http-context.svg)](https://coveralls.io/github/dalet-oss/express-http-context)
-[![npm](https://img.shields.io/npm/v/dalet-oss/express-http-context.svg)](https://www.npmjs.com/package/@dalet-oss/express-http-context)
-[![npm](https://img.shields.io/npm/dm/dalet-oss/express-http-context.svg)](https://www.npmjs.com/package/@dalet-oss/express-http-context)
-[![david](https://img.shields.io/dalet-oss/express-http-context.svg)](https://david-dm.org/dalet-oss/express-http-context)
+[![NPM Version](https://img.shields.io/npm/v/%40dalet-oss%2Fexpress-http-context)](https://www.npmjs.com/package/@dalet-oss/express-http-context)
+[![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/dalet-oss/express-http-context/ci-publish.yml)](https://github.com/dalet-oss/express-http-context/actions)
 
-# Express HTTP Context
-Get and set request-scoped context anywhere.  This is just an unopinionated, idiomatic ExpressJS implementation of
-[cls-hooked](https://github.com/Jeff-Lewis/cls-hooked) (forked from [continuation-local-storage](https://www.npmjs.com/package/continuation-local-storage)).
-It's a great place to store user state, claims from a JWT, request/correlation IDs, and any other request-scoped data.
-Context is preserved even over async/await (in node 8+).
 
-## How to use it
+# Express HTTP Context
+Modern request-scoped storage support for Express.js, based on native Node.js
+Asynchronous Local Storage. It's a great place to store user state, claims from
+a JWT, request/correlation IDs, and any other request-scoped data.
+
+This package is a drop-in replacement and has been inspired by the work done in
+[express-http-context](https://github.com/skonves/express-http-context), but
+with ESM support, no dependencies, and only supporting modern versions of
+Node.js (+v14).
+
+The implementation is derived from the start made in
+[express-http-context2](https://github.com/artberri/express-http-context2).
+We diverged to support our own implementation because the bug highlighted in
+[artberri/express-http-context2#1](https://github.com/artberri/express-http-context2/issues/1)
+was ultimately ignored and the repository apparently abandoned by its maintainer.
+
+
+## Installation
+
+```bash
+npm install @dalet-oss/express-http-context
+# or
+yarn add @dalet-oss/express-http-context
+# or
+pnpm add @dalet-oss/express-http-context
+```
 
-Install: `npm install --save @dalet-oss/express-http-context`  
-(Note: For node v4-7, use the legacy version: `npm install --save express-http-context@<1.0.0`)
+> **Requirements**
+>
+> `@dalet-oss/express-http-context` is a middleware intended for `express`, so
+> although it is not explicitly declared as a dependency or peer dependency, it
+> requires `express` to work, as well as `@types/express` if you are using
+> Typescript. The reason the dependency is not explicitly declared is that it
+> could also eventually be used with `fastify` or other Node.js HTTP servers.
 
-Use the middleware immediately before the first middleware that needs to have access to the context.
-You won't have access to the context in any middleware "used" before this one.
+## Configuration
 
-Note that some popular middlewares (such as body-parser, express-jwt) may cause context to get lost.
-To workaround such issues, you are advised to use any third party middleware that does NOT need the context
-BEFORE you use this middleware.
+Use the middleware immediately before the first middleware that needs to have access to the context. You won't have access to the context in any middleware "used" before this one.
 
-``` js
-var express = require('express');
-var httpContext = require('express-http-context');
+```js
+const express = require('express')
+const httpContext = require('@dalet-oss/express-http-context')
 
-var app = express();
-// Use any third party middleware that does not need access to the context here, e.g. 
+const app = express()
+// Use any third party middleware that does not need to access the context here, e.g.
 // app.use(some3rdParty.middleware);
-app.use(httpContext.middleware);
-// all code from here on has access to the same context for each request
+app.use(httpContext.middleware)
+// All code from this point on will have access to the per-request context
 ```
 
-Set values based on the incoming request:
+Note that some popular middlewares (such as `body-parser`, `express-jwt`) can
+cause the context to be lost. To work around such problems, it is recommended
+that you use any third-party middleware that does NOT require the context
+BEFORE using this middleware.
+
+## Usage
+
+Examples of setting values:
+
+```js
+const httpContext = require('@dalet-oss/express-http-context')
+const { nanoid } = require('nanoid') // This is just an example, nanoid is not included in this lib
 
-``` js
-// Example authorization middleware
 app.use((req, res, next) => {
-	userService.getUser(req.get('Authorization'), (err, result) => {
-		if (err) {
-			next(err);
-		} else {
-			httpContext.set('user', result.user)
-			next();
-		}
-	});
-});
+	// Get the user ID from wherever and save it for later use...
+	httpContext.set('userId', userId)
+	// Create a request ID to be able to trace/correlate everything that happens within the same request
+	httpContext.set('requestId', nanoid())
+})
 ```
 
-Get them from code that doesn't have access to the express `req` object:
+Get them from anywhere in your code:
 
-``` js
-var httpContext = require('express-http-context');
+```js
+var httpContext = require('@dalet-oss/express-http-context')
 
-// Somewhere deep in the Todo Service
-function createTodoItem(title, content, callback) {
-	var user = httpContext.get('user');
-	db.insert({ title, content, userId: user.id }, callback);
+function logError(error) {
+	const userId = httpContext.get('userId')
+	const requestId = httpContext.get('requestId')
+	console.error(error, { userId, requestId })
 }
 ```
 
-You can access cls namespace directly as (it may be useful if you want to apply some patch to it, for example https://github.com/TimBeyer/cls-bluebird):
-``` js
-var ns = require('express-http-context').ns;
+## API
+
+### middleware
+
+It is an Express.js middleware that is responsible for initializing the
+independent context for each request. The `get` and `set` calls will operate on
+a set of keys/values unique to those contexts.
+
+#### Example
+
+```js
+import { middleware } from '@dalet-oss/express-http-context'
+
+app.use(middleware)
+```
+
+### set
+
+Adds a value to the request context by key.
+If the key already exists, its value will be overwritten.
+No value will persist if the context has not yet been initialized.
+
+#### Parameters
+
+- `key` a string key to store the variable by
+- `value` any value to store under the key for the later lookup.
+
+#### Example
+
+```js
+import { set } from '@dalet-oss/express-http-context'
+
+set('user', { id: 'overwrittenUser', email: 'foo@bar.com' })
+```
+
+### get
+
+Gets a value from the request context by key.
+Will return `undefined` if the context has not yet been initialized for this
+request or if a value is not found for the specified key.
+
+#### Parameters
+
+- `key` a string key to retrieve the stored value for
+
+#### Example
+
+```js
+import { get } from '@dalet-oss/express-http-context'
+
+const user = get('user')
 ```
 
-## Troubleshooting
-To avoid weird behavior with express:
-1. Make sure you require `express-http-context` in the first row of your app. Some popular packages use async which breaks CLS.
+## License
 
-For users of Node 10
-1. Node 10.0.x - 10.3.x are not supported.  V8 version 6.6 introduced a bug that breaks async_hooks during async/await.  Node 10.4.x uses V8 v6.7 in which the bug is fixed.  See: https://github.com/nodejs/node/issues/20274.
+MIT License.  See [LICENSE](LICENSE).
 
-See [Issue #4](https://github.com/dalet-oss/express-http-context/issues/4) for more context.  If you find any other weird behaviors, please feel free to open an issue.
 
 ## Contributors
 * Oliver Lockwood (@oliverlockwood)
-* Steve Konves (@skonves)
-* Amiram Korach (@amiram)
-* Yoni Rabinovitch (@yonirab)
-* DontRelaX (@dontrelax)
-* William Durand (@willdurand)
+* Alberto Varela Sánchez (@artberri)
 
 Interesting in contributing? Take a look at the [Contributing Guidlines](/CONTRIBUTING.md)

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@dalet-oss/express-http-context",
-    "version": "1.2.0",
+    "version": "1.2.1",
     "description": "Modern request-scoped storage support for Express.js based on Asynchronous Local Storage.",
     "author": {
         "name": "Dalet OSS",