Add docs and types for exposing asyncLocalStorage instance (#220)

Signed-off-by: Florian Bienefelt <[email protected]>
Signed-off-by: Florian Bienefelt <[email protected]>
Co-authored-by: Florian Bienefelt <[email protected]>

Author: dennemark

README.md

@@ -149,6 +149,20 @@ const bar = requestContext.get('bar')
 
 If you have `"strictNullChecks": true` (or have `"strict": true`, which sets `"strictNullChecks": true`) in your TypeScript configuration, you will notice that the type of the returned value can still be `undefined` even though the `RequestContextData` interface has a specific type. For a discussion about how to work around this and the pros/cons of doing so, please read [this issue (#93)](https://github.com/fastify/fastify-request-context/issues/93).
 
+## Usage outside of a request
+
+If functions depend on requestContext but are not called in a request, i.e. in tests or workers, they can be wrapped in the asyncLocalStorage instance of requestContext:
+
+```
+import { asyncLocalStorage } from '@fastify/request-context';
+
+it('should set request context', () => {
+  asyncLocalStorage.run({}, async () => {
+    requestContext.set('userId', 'some-fake-user-id');
+    someCodeThatUsesRequestContext(); // requestContext.get('userId') will work
+  })
+})
+```
 
 ## License
 

index.js

@@ -66,7 +66,7 @@ module.exports = fp(fastifyRequestContext, {
 })
 module.exports.default = fastifyRequestContext
 module.exports.fastifyRequestContext = fastifyRequestContext
-
+module.exports.asyncLocalStorage = asyncLocalStorage
 module.exports.requestContext = requestContext
 
 // Deprecated

types/index.d.ts

@@ -1,4 +1,4 @@
-import { AsyncResource } from 'node:async_hooks'
+import { AsyncLocalStorage, AsyncResource } from 'node:async_hooks'
 import { FastifyPluginCallback, FastifyRequest } from 'fastify'
 
 type FastifyRequestContext =
@@ -54,7 +54,7 @@ declare namespace fastifyRequestContext {
   }
 
   export const requestContext: RequestContext
-
+  export const asyncLocalStorage: AsyncLocalStorage<RequestContext>
   /**
    * @deprecated Use FastifyRequestContextOptions instead
    */

types/index.test-d.ts

@@ -1,12 +1,14 @@
 import {
   requestContext,
+  asyncLocalStorage,
   fastifyRequestContext,
   FastifyRequestContextOptions,
   RequestContext,
   RequestContextDataFactory,
 } from '..'
 import { expectAssignable, expectType, expectError } from 'tsd'
 import { FastifyBaseLogger, FastifyInstance, RouteHandlerMethod } from 'fastify'
+import { AsyncLocalStorage } from 'node:async_hooks'
 
 const fastify = require('fastify')
 
@@ -61,6 +63,7 @@ expectError<RequestContextDataFactory>(() => ({ log: 'dummy' }))
 
 expectType<RequestContext>(app.requestContext)
 expectType<RequestContext>(requestContext)
+expectType<AsyncLocalStorage<RequestContext>>(asyncLocalStorage)
 
 const getHandler: RouteHandlerMethod = function (request, _reply) {
   expectType<RequestContext>(request.requestContext)