Async Hooks Context


This library is designed to create a request scoped context, in which any data about the request can be stored. This was
initially created to store a request scoped correlation ID for logging purposes but exposes more generic functionality
to allow it to be used for multiple purposes. The library is powered by the native async_hooks lib.

Getting Started

This is how to get a copy of this working locally. The only requirement is that Node is installed on the base machine.

``bash
$ git clone git@github.com:ToeFungi/async-hooks-context.git
$ cd async-hooks-context
$ npm i
`

Installation

Install this Async Hooks Context library via npm.

`bash
$ npm i --save async-hooks-context
`

Usage

To ensure that the context is available, it should be created at the top level of your function.

#### Correlation IDs - Get / Set

Call the setCorrelationId() function in the global or parent scope. This will generate a new UUID v4 string as the
correlation ID for all downstream scopes and become available in all child calls. In some cases, the function might need
to be wrapped to ensure the context is set correctly.

`typeScript
import { getCorrelationId, setCorrelationId } from './AsyncHooksContext'

// Generates a new UUID v4 string and sets it to the request scope as the correlation ID
setCorrelationId()

const foo = () => {
// Returns the correlation ID for the request scope or undefined if not set
return getCorrelationId()
}

// UUID v4 string
console.log(foo())
`

In the case that you want to set the correlation ID based on an incoming object, the top level function should be
wrapped and the correlation ID set within the wrapper. This ensures that the context is available in the scope of the
child function.

`typeScript
import { getCorrelationId, setCorrelationId } from './AsyncHooksContext'

const data = {
correlationId: 'xxxx-xxxx-xxxx-xxxx'
}

const foo = (data: object) => {
return getCorrelationId()
}

// Wrapper to ensure that the context is in the proper scope for the child function
const wrapper = (data: object) => {
// Explicitly set a correlation ID
setCorrelationId(data.correlationId)
return foo(data)
}

// UUID v4 string
console.log(wrapper(data))
`

#### Context Objects - Get / Set

Call the updateRequestContext() function in the global or parent scope and pass in the object that should be stored.
This will create or update the existing context with the new data provided. An object that is passed with the same keys
will overwrite duplicate keys. The correlation ID will also be available in the returned context.

`typeScript
import { getRequestContext, updateRequestContext } from './AsyncHooksContext'

const data = {
meta: 'data'
}

const foo = () => {
// Returns the current request scoped context
return getRequestContext()
}

// Wrapper to ensure that the context is in the proper scope for the child function
const wrapper = (data: object) => {
// Pass the data required in the context, into the update function
updateRequestContext(data)
return foo()
}

console.log(wrapper(data))
`

#### Cleaning Up

When the request ends, the context will be removed from the current stored contexts. If however, a use case arises in
which the current request context needs to be removed, call the cleanContext() function.

`typeScript
import { cleanContext, getCorrelationId, setCorrelationId } from './AsyncHooksContext'

const foo = () => {
console.log(getCorrelationId()) // UUID v4 string
cleanContext()
console.log(getCorrelationId()) // undefined
}

const wrapper = () => {
setCorrelationId()
return foo()
}
`

Running Tests

To run tests, you should be able to simply run be able to run

`bash
$ npm run test
$ npm run coverage
``

Testing tools that are used includes Mocha, Chai, Sinon, and nyc.

Contributions

This project is completely open source and as such, you are invited to make contributions. Fork the project, make some
changes and make the pull request. Should you have any feedback regarding the functionality, please don't hesitate to
open an issue so this can be resolved. Please ensure that any pull requests have unit tests that cover any additional
functionality.

License

MIT License

Copyright (c) 2021 Alex Pickering