@dalet-oss/express-http-context 1.0.0-DEV

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 Steve Konves
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,86 @@
+[![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)
+
+# 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
+
+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`)
+
+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.
+
+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.
+
+``` js
+var express = require('express');
+var httpContext = require('express-http-context');
+
+var app = express();
+// Use any third party middleware that does not need access to 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
+```
+
+Set values based on the incoming request:
+
+``` 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 them from code that doesn't have access to the express `req` object:
+
+``` js
+var httpContext = require('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);
+}
+```
+
+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;
+```
+
+## 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.
+
+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.
+
+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)
+
+Interesting in contributing? Take a look at the [Contributing Guidlines](/CONTRIBUTING.md)

package/browser.js

@@ -0,0 +1,12 @@
+module.exports = {
+  middleware: function (req, res, next) {
+    throw new Error('`middleware` cannot be called from the browser code.');
+  },
+  get: function () {
+    return null;
+  },
+  set: function (key, value) {
+    // noop
+  },
+  ns: null,
+};

package/index.d.ts

@@ -0,0 +1,24 @@
+import { Request, Response, NextFunction } from "express";
+import { Namespace } from 'cls-hooked';
+
+/** Express.js middleware that is responsible for initializing the context for each request. */
+export declare function middleware(
+  req: Request,
+  res: Response,
+  next: NextFunction
+): void;
+
+/**
+ * Gets a value from the 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.
+ */
+export declare function get(key: string): any;
+
+/**
+ * Adds a value to the 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.
+ */
+export declare function set(key: string, value: any): void;
+
+/**
+ * Gets the underlying continuation namespace.
+ */
+export declare const ns: Namespace;

package/index.js

@@ -0,0 +1,39 @@
+'use strict';
+
+const cls = require('cls-hooked');
+
+const nsid = 'a6a29a6f-6747-4b5f-b99f-07ee96e32f88';
+const ns = cls.createNamespace(nsid);
+
+/** Express.js middleware that is responsible for initializing the context for each request. */
+function middleware(req, res, next) {
+	ns.run(() => next());
+}
+
+/**
+ * Gets a value from the 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.
+ * @param {string} key
+ */
+function get(key) {
+	if (ns && ns.active) {
+		return ns.get(key);
+	}
+}
+
+/**
+ * Adds a value to the 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.
+ * @param {string} key 
+ * @param {*} value 
+ */
+function set(key, value) {
+	if (ns && ns.active) {
+		return ns.set(key, value);
+	}
+}
+
+module.exports = {
+	middleware,
+	get: get,
+	set: set,
+	ns: ns
+};

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@dalet-oss/express-http-context",
+  "version": "1.0.0-DEV",
+  "description": "Get and set request-scoped context anywhere",
+  "main": "index.js",
+  "browser": "browser.js",
+  "types": "./index.d.ts",
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "scripts": {
+    "test": "node --unhandled-rejections=strict ./node_modules/.bin/mocha --config test/.mocharc.json",
+    "cover": "nyc --reporter lcov --reporter text-summary _mocha --config test/.mocharc.json",
+    "coveralls": "npm run cover -- --report lcovonly && cat ./coverage/lcov.info | coveralls"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dalet-oss/express-http-context.git"
+  },
+  "keywords": [
+    "express",
+    "http",
+    "request",
+    "context"
+  ],
+  "author": "Oliver Lockwood",
+  "contributors": [
+    "Oliver Lockwood (@oliverlockwood)",
+    "Steve Konves (@skonves)",
+    "Amiram Korach (@amiram)",
+    "Yoni Rabinovitch (@yonirab)",
+    "DontRelaX (@dontrelax)",
+    "William Durand (@willdurand)"
+  ],
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/dalet-oss/express-http-context/issues"
+  },
+  "homepage": "https://github.com/dalet-oss/express-http-context#readme",
+  "directories": {
+    "test": "test"
+  },
+  "dependencies": {
+    "@types/cls-hooked": "^4.2.1",
+    "@types/express": "^4.17.17",
+    "cls-hooked": "^4.2.2"
+  },
+  "devDependencies": {
+    "chai": "^4.3.7",
+    "coveralls": "^3.1.1",
+    "express": "^4.18.2",
+    "nyc": "^15.1.0",
+    "mocha": "^10.2.0",
+    "mocha-lcov-reporter": "^1.3.0",
+    "supertest": "^6.3.3"
+  }
+}