Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/psenger/async-context-id

A lightweight, powerful correlation ID tracking and context store written for Node.js that automatically propagates context through async operations using Node's `async_hooks`. Perfect for distributed tracing, request tracking, and logging correlation in micro services architectures.
https://github.com/psenger/async-context-id

async-hooks asynchooks context correlation correlation-id correlationid debug distributed-tracing express logging microservices middleware nodejs request-id tracking

Last synced: 4 months ago
JSON representation

A lightweight, powerful correlation ID tracking and context store written for Node.js that automatically propagates context through async operations using Node's `async_hooks`. Perfect for distributed tracing, request tracking, and logging correlation in micro services architectures.

Awesome Lists containing this project

README 

          
# [async-context-id](https://github.com/psenger/async-context-id#readme)



> [!TAG]

> 0.1.1



A lightweight, powerful correlation ID tracking and context store written for Node.js that automatically propagates context through async operations using Node's `async_hooks`. Perfect for distributed tracing, request tracking, and logging correlation in micro services architectures.



## Table of Contents



- [Features](#features)

- [Installation](#installation)

- [How It Works](#how-it-works)

- [Flow Diagram Explanation](#flow-diagram-explanation)

  * [Instance Creation](#instance-creation)

  * [Async Hooks Setup](#async-hooks-setup)

  * [Context Operations](#context-operations)

  * [Context Propagation](#context-propagation)

  * [Cleanup](#cleanup)

  * [Example Flow](#example-flow)

- [API](#api)

  * [Modules](#modules)

  * [Classes](#classes)

  * [@psenger/async-context-id](#psengerasync-context-id)

  * [AsyncContextId](#asynccontextid)

    + [new AsyncContextId([options])](#new-asynccontextidoptions)

    + [asyncContextId.cleanUpFn()](#asynccontextidcleanupfn)

    + [asyncContextId.getCorrelationId() ⇒ string](#asynccontextidgetcorrelationid-%E2%87%92-string)

    + [asyncContextId.setCorrelationId(correlationId)](#asynccontextidsetcorrelationidcorrelationid)

    + [asyncContextId.getContext() ⇒ Object \| string \| number \| Object](#asynccontextidgetcontext-%E2%87%92-object--string--number--object)

    + [asyncContextId.setContext([context])](#asynccontextidsetcontextcontext)

    + [asyncContextId.clear()](#asynccontextidclear)

  * [LruMap ⇐ Map](#lrumap-%E2%87%90-map)

    + [new LruMap(maxSize)](#new-lrumapmaxsize)

    + [lruMap.set(key, value) ⇒ this](#lrumapsetkey-value-%E2%87%92-this)

  * [TimedMap ⇐ Map](#timedmap-%E2%87%90-map)

    + [new TimedMap(ttl)](#new-timedmapttl)

    + [timedMap.set(key, value) ⇒ this](#timedmapsetkey-value-%E2%87%92-this)

    + [timedMap.delete(key) ⇒ boolean](#timedmapdeletekey-%E2%87%92-boolean)

- [Usage](#usage)

  * [Enhanced Logging with Console Monkey Patching](#enhanced-logging-with-console-monkey-patching)

  * [Express Middleware](#express-middleware)

    + [`correlation-middleware.js`](#correlation-middlewarejs)

    + [`app.js`](#appjs)

    + [`simple-controller.js`](#simple-controllerjs)

  * [Winston Logger Integration](#winston-logger-integration)

- [‼️ Caution - Memory Management Strategies](#%E2%80%BC%EF%B8%8F-caution---memory-management-strategies)

- [‼️ Caution - Correlation ID with `UUID`](#%E2%80%BC%EF%B8%8F-caution---correlation-id-with-uuid)

- [‼️ Limitations](#%E2%80%BC%EF%B8%8F-limitations)

  * [Untested pattern - **Process Next Tick**](#untested-pattern---process-next-tick)

  * [Untested pattern - **Node.js Core Module Callbacks** (like fs, http, etc.):](#untested-pattern---nodejs-core-module-callbacks-like-fs-http-etc)

  * [Solution to Untested pattern](#solution-to-untested-pattern)

- [Contributing](#contributing)

  * [Rules](#rules)

  * [Commit Message](#commit-message)

  * [Testing](#testing)

- [License](#license)

- [Acknowledgments](#acknowledgments)

  * [Dependencies](#dependencies)

  * [Development Dependencies](#development-dependencies)



## Features



- Automatic context propagation through async operations

- Thread-local-like storage for Node.js

- UUID v4 based correlation IDs

- ️ Thread-safe context isolation

- Deep cloning of context data

- Automatic cleanup of contexts

- Zero dependencies (uses only Node.js built-ins)



## Installation



**NPM**



```shell

npm install @psenger/async-context-id --save

```

**YARN**



```shell

yarn add @psenger/async-context-id

```



## How It Works



This library uses Node.js's `async_hooks` module to track async operations:



```mermaid

stateDiagram-v2

    [*] --> AsyncContextId: Create Instance



    state AsyncContextId {

        state "Async Hooks Setup" as setup {

            [*] --> Hook

            Hook --> Init: New Async Operation

            Hook --> PromiseResolve: Promise Resolved

            Hook --> Destroy: Operation Complete

        }



        state "Context Operations" as ops {

            state "Context Store (Map)" as store {

                SetContext --> Store: Update Context

                GetContext --> Store: Retrieve Context

                SetCorrelationId --> Store: Update ID

                GetCorrelationId --> Store: Get/Generate ID

                Clear --> Store: Delete Context

            }

        }



        state fork_state <>



        Init --> fork_state

        fork_state --> CopyParentContext: Has Parent Context

        fork_state --> CreateNewContext: No Parent Context



        CopyParentContext --> Store: Set New AsyncID

        CreateNewContext --> Store: Generate New ID



        PromiseResolve --> Store: Copy Context to New AsyncID

        Destroy --> Store: Delete Context for AsyncID

    }



    state "Example Flow" as example {

        Request --> SetCorrelationId: Upstream ID

        SetCorrelationId --> ProcessData: Async Operation

        ProcessData --> GetContext: Get Results

        GetContext --> Clear: Cleanup

    }



    AsyncContextId --> BeforeExit: Process Exit

    BeforeExit --> [*]: Cleanup Hook & Store

```



## Flow Diagram Explanation



### Instance Creation



* Program starts by creating a singleton `AsyncContextId` instance

* Sets up async hooks and initializes the context store (Map)



### Async Hooks Setup



* Hook listens for three main events:

  * `init`: When new async operations are created

  * `promiseResolve`: When promises are resolved

  * `destroy`: When async operations complete



### Context Operations



Custom data is stored in the `meta` attribute. All context / `meta`

operations use deep cloning to ensure isolation between async operations.



* Main operations on the context store:

  * `setContext`: Updates context for current async ID

  * `getContext`: Retrieves context for current async ID

  * `setCorrelationId`: Sets/updates correlation ID

  * `getCorrelationId`: Gets or generates correlation ID

  * `clear`: Removes context for current async ID



### Context Propagation



* When a new async operation starts:

  * If parent context exists, it's copied to new async ID

  * If no parent context, new context is created with generated ID

* When promises resolve, context is copied to new async ID

* When operations complete, context is cleaned up



### Cleanup



* On process exit:

  * Disables async hooks

  * Clears context store

  * Removes event listeners



### Example Flow



* Shows typical request handling:

  * Set correlation ID from upstream

  * Process data asynchronously

  * Retrieve context for logging

  * Clear context when done



## API



### Modules



  

    

      ModuleDescription

    

  

  



    @psenger/async-context-id

    
A lightweight, powerful correlation ID tracking and context store.



    



### Classes



  

    

      GlobalDescription

    

  

  



    AsyncContextId

    
A singleton class that tracks correlation IDs across asynchronous operations in Node.js.

Uses async_hooks to automatically propagate correlation context across async boundaries.



    



    LruMap ⇐ Map

    
A Map extension implementing Least Recently Used (LRU) caching strategy.

Automatically removes oldest entries when size limit is reached.



    



    TimedMap ⇐ Map

    
A Map extension that automatically deletes entries after a specified time-to-live (TTL).



    






### @psenger/async-context-id

A lightweight, powerful correlation ID tracking and context store.






### AsyncContextId

A singleton class that tracks correlation IDs across asynchronous operations in Node.js.

Uses async_hooks to automatically propagate correlation context across async boundaries.



**Kind**: global class  

**Properties**



| Name | Type | Description |

| --- | --- | --- |

| contextStore | Map | Storage for async context data |

| hook | AsyncHook | The async_hooks instance for tracking async operations |

| cleanUpFn | function | Cleanup function registered for process exit |



* [AsyncContextId](#AsyncContextId)

    * [new AsyncContextId([options])](#new_AsyncContextId_new)

    * [.cleanUpFn()](#AsyncContextId+cleanUpFn)

    * [.getCorrelationId()](#AsyncContextId+getCorrelationId) ⇒ string

    * [.setCorrelationId(correlationId)](#AsyncContextId+setCorrelationId)

    * [.getContext()](#AsyncContextId+getContext) ⇒ Object \| string \| number \| Object

    * [.setContext([context])](#AsyncContextId+setContext)

    * [.clear()](#AsyncContextId+clear)






#### new AsyncContextId([options])

This class provides context propagation across async operations in Node.js

applications. It maintains correlation IDs and metadata throughout the async execution chain.



**Returns**: [AsyncContextId](#AsyncContextId) - The singleton instance  



| Param | Type | Default | Description |

| --- | --- | --- | --- |

| [options] | Object | {} | Configuration options |

| [options.store] | Map | new Map() | Optional Map instance for context storage, this package includes both a LRU ( Least Recently Used ) Map and a Timed Map. |

| [options.correlationIdFn] | fn |  | Optional function to override default UUID generation. Should return a string |



**Example**  

```js

// Using default Map and UUID generation

const tracker = new AsyncContextId();

```

**Example**  

```js

// Using custom LRU Map and correlation ID generator

const tracker = new AsyncContextId({

  store: new LruMap(1000),

  correlationIdFn: () => `custom-${Date.now()}`

});

```




#### asyncContextId.cleanUpFn()

remove the listener of itself to prevent memory leaks



**Kind**: instance method of [AsyncContextId](#AsyncContextId)  




#### asyncContextId.getCorrelationId() ⇒ string

Retrieves the correlation ID for the current async context.

Creates a new context with generated ID if none exists.



**Kind**: instance method of [AsyncContextId](#AsyncContextId)  

**Returns**: string - The current correlation ID  

**Throws**:



- Error If async hooks are not enabled



**Example**  

```js

const correlationId = tracker.getCorrelationId();

res.setHeader('x-correlation-id', correlationId);

```




#### asyncContextId.setCorrelationId(correlationId)

Sets the correlation ID for the current async context.

Creates a new context if none exists.



**Kind**: instance method of [AsyncContextId](#AsyncContextId)  

**Throws**:



- Error If the correlationId is not a string

- Error If async hooks are not enabled



| Param | Type | Description |

| --- | --- | --- |

| correlationId | string | The correlation ID to set |



**Example**  

```js

const upstreamId = req.headers['x-correlation-id'];

if (upstreamId) {

  tracker.setCorrelationId(upstreamId);

}

```




#### asyncContextId.getContext() ⇒ Object \| string \| number \| Object

Retrieves the complete context object for the current async operation.

Creates a new context if none exists.



**Kind**: instance method of [AsyncContextId](#AsyncContextId)  

**Returns**: Object - The correlation contextstring - context.correlationId - The correlation IDnumber - context.startTime - Unix timestamp of context creationObject - context.metadata - Custom metadata object  

**Throws**:



- Error If async hooks are not enabled



**Example**  

```js

const context = tracker.getContext();

console.log({

  correlationId: context.correlationId,

  duration: Date.now() - context.startTime,

  metadata: context.metadata

});

```




#### asyncContextId.setContext([context])

Updates the context for the current async operation.

Creates a new context if none exists. Preserves existing correlationId

and startTime unless explicitly overridden.



**Kind**: instance method of [AsyncContextId](#AsyncContextId)  

**Throws**:



- Error If async hooks are not enabled

- Error If context is not an object



| Param | Type | Default | Description |

| --- | --- | --- | --- |

| [context] | Object | {} | The context object to merge |

| [context.correlationId] | string |  | Optional correlation ID override |

| [context.metadata] | Object |  | Optional metadata to merge |



**Example**  

```js

// Add request context

tracker.setContext({

  metadata: {

    operation: 'processData',

    requestId: req.id,

    userId: req.user.id

  }

});

```




#### asyncContextId.clear()

Removes the correlation context for the current async operation.



**Kind**: instance method of [AsyncContextId](#AsyncContextId)  

**Throws**:



- Error If async hooks are not enabled



**Example**  

```js

try {

  await processRequest(data);

} finally {

  tracker.clear();

}

```




### LruMap ⇐ Map

A Map extension implementing Least Recently Used (LRU) caching strategy.

Automatically removes oldest entries when size limit is reached.



**Kind**: global class  

**Extends**: Map  



* [LruMap](#LruMap) ⇐ Map

    * [new LruMap(maxSize)](#new_LruMap_new)

    * [.set(key, value)](#LruMap+set) ⇒ this






#### new LruMap(maxSize)

Creates an LRU cache with specified maximum size.



| Param | Type | Description |

| --- | --- | --- |

| maxSize | number | Maximum number of entries |



**Example**  

```js

const cache = new LruMap(3);

cache.set('a', 1).set('b', 2).set('c', 3);

cache.set('d', 4); // Removes 'a', now contains b,c,d

```




#### lruMap.set(key, value) ⇒ this

Sets a value, removing oldest entry if size limit reached.



**Kind**: instance method of [LruMap](#LruMap)  

**Returns**: this - The LruMap instance for chaining  



| Param | Type | Description |

| --- | --- | --- |

| key | \* | The key to set |

| value | \* | The value to store |



**Example**  

```js

const cache = new LruMap(2);

cache.set('key1', 'value1')

     .set('key2', 'value2')

     .set('key3', 'value3'); // Removes key1

```




### TimedMap ⇐ Map

A Map extension that automatically deletes entries after a specified time-to-live (TTL).



**Kind**: global class  

**Extends**: Map  



* [TimedMap](#TimedMap) ⇐ Map

    * [new TimedMap(ttl)](#new_TimedMap_new)

    * [.set(key, value)](#TimedMap+set) ⇒ this

    * [.delete(key)](#TimedMap+delete) ⇒ boolean






#### new TimedMap(ttl)

Creates a new TimedMap instance.



| Param | Type | Description |

| --- | --- | --- |

| ttl | number | Time-to-live in milliseconds for each key-value pair |



**Example**  

```js

const cache = new TimedMap(5000); // 5 second TTL

cache.set('key1', 'value1');

console.log(cache.get('key1')); // 'value1'

// After 5 seconds:

console.log(cache.get('key1')); // undefined

```

**Example**  

```js

// Resetting TTL on value update

const cache = new TimedMap(2000);

cache.set('user', { name: 'Alice' });

// 1 second later:

cache.set('user', { name: 'Alice', age: 30 }); // Resets the 2-second timer

```




#### timedMap.set(key, value) ⇒ this

Sets a value in the map with an automatic deletion timer.

If the key already exists, its timer is reset.



**Kind**: instance method of [TimedMap](#TimedMap)  

**Returns**: this - The TimedMap instance for chaining  



| Param | Type | Description |

| --- | --- | --- |

| key | \* | The key to set |

| value | \* | The value to store |



**Example**  

```js

const cache = new TimedMap(10000);

cache.set('apiKey', 'xyz123')

     .set('timestamp', Date.now());

```




#### timedMap.delete(key) ⇒ boolean

Deletes a key-value pair and its associated timer.



**Kind**: instance method of [TimedMap](#TimedMap)  

**Returns**: boolean - True if the element was deleted, false if it didn't exist  



| Param | Type | Description |

| --- | --- | --- |

| key | \* | The key to delete |



**Example**  

```js

const cache = new TimedMap(5000);

cache.set('temp', 'data');

cache.delete('temp'); // Manually delete before TTL expires

```



## Usage



### Enhanced Logging with Console Monkey Patching



This example demonstrates how to automatically inject correlation IDs into console logs

using [monkey patching](https://en.wikipedia.org/wiki/Monkey_patch). The code below

intercepts standard console methods and prepends each log message with its log level

and correlation ID.



eg `LOG-LEVEL CORRELATION-ID`



```javascript

const fs = require('fs')

const path = require('path')

const util = require('util')

const {AsyncContextId} = require('../dist/index')

const TRACKER = new AsyncContextId()

const logFile = path.join(__dirname, 'app.log')

const original = {

  log: console.log,

  error: console.error,

  warn: console.warn,

  debug: console.debug,

  info: console.info

}

try {

  if (fs.existsSync(logFile)) {

    fs.writeFileSync(logFile, '')

  }

} catch (err) {

  console.error('Error handling log file:', err)

}

function formatApacheErrorTimestamp(date = new Date()) {

  const days = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat']

  const months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']

  return `[${days[date.getDay()]} ${months[date.getMonth()]} ${String(date.getDate()).padStart(2, '0')} ` +

    `${String(date.getHours()).padStart(2, '0')}:${String(date.getMinutes()).padStart(2, '0')}:` +

    `${String(date.getSeconds()).padStart(2, '0')}.${String(date.getMilliseconds()).padStart(3, '0')} ` +

    `${date.getFullYear()}]`

}

Object.keys(original).forEach(method => {

  console[method] = function (...args) {

    const prefix = `${formatApacheErrorTimestamp()} [${method.toLowerCase()}] [${TRACKER.getContext().correlationId}] ${TRACKER.getContext()?.metadata?.fullName} `

    if (typeof args[0] === 'string') {

      args[0] = prefix + args[0]

    } else {

      args.unshift(prefix)

    }

    original[method].apply(console, args)

    fs.appendFileSync(logFile, util.format(...args) + '\n')

  }

})



```



### Express Middleware



This Express middleware automatically manages correlation IDs across HTTP requests. It

extracts the correlation ID from incoming request headers, propagates it through the

request lifecycle, and includes it in the response headers.



**Note:** Register this middleware early in your Express application's middleware chain

to ensure correlation IDs are available throughout the entire request lifecycle.



#### `correlation-middleware.js`



```javascript

const {AsyncContextId} = require('../dist/index') // '@psenger/async-context-id'

const asyncContextId = new AsyncContextId()

const correlationMiddleware = () => (req, res, next) => {

  try {

    asyncContextId.clear()

    let correlationId = req.headers['x-correlation-id']

    correlationId = asyncContextId.setCorrelationId(correlationId)

    res.setHeader('x-correlation-id', correlationId)

    res.on('finish', () => {

      asyncContextId.clear()

    })

    next()

  } catch (error) {

    next(error)

  }

}

module.exports = correlationMiddleware



```



#### `app.js`



```javascript

const express = require('express')

const app = express()

const router = express.Router()

const {systemTimer} = require('./timer')

const controller = require('./controller')

const correlationMiddleware = require('./correlation-middleware')

require('./monkey-patch-logs')

systemTimer()

app.use(express.json())

app.use(express.urlencoded({extended: false}))

app.use(correlationMiddleware())

router.post('/:id', controller)

app.use('/', router)

module.exports = app



```



#### `simple-controller.js`



```javascript

const {AsyncContextId} = require('../dist/index') // '@psenger/async-context-id'

const TRACKER = new AsyncContextId()

module.exports = function (req, res) {

  const id = req.params.id

  const correlationId = TRACKER.getContext().correlationId

  console.log(`${correlationId} saw ${id} in controller`)

  TRACKER.setContext({

    metadata: {

      id,

    }

  })

  // do something else here which will expose meta upstream

}



```



### Winston Logger Integration



```javascript

const winston = require('winston')

const {AsyncContextId} = require('../dist/index') // '@psenger/async-context-id'



const TRACKER = new AsyncContextId()



const logger = winston.createLogger({

  format: winston.format.combine(

    winston.format.timestamp(),

    winston.format.json(),

    winston.format((info) => {

      const context = TRACKER.getContext();

      return {

        ...info,

        correlationId: context?.correlationId || 'no-correlation-id',

        metadata: context?.metadata || {}

      };

    })()

  ),

  transports: [

    new winston.transports.Console()

  ]

});



```



## ‼️ Caution - Memory Management Strategies



All scaling systems degrade when affected by memory leaks. This module hosts a single map

and addresses such leaks through two configurable Map implementations for context tracking:



* LRU (Least Recently Used) Map

* Timed Map



These maps can be configured during AsyncContextId initialization. As AsyncContextId operates

as a singleton, the map implementation must be set at creation and remains immutable.



## ‼️ Caution - Correlation ID with `UUID`



The default implementation of correlation ID uses non-cryptographic UUID generation to prevent recursive

async hook triggers that would otherwise occur with Node's Crypto module (internal crypto operations

would initiate new async hooks). Since this is based on UUID v4, it may be necessary for consumers

to increase the complexity of the correlation ID. Therefore, this functionality has been exposed as

an option ( `correlationIdFn` ).



e.g.

```javascript

// Safe UUID v4 implementation without Crypto

generateCorrelationId() {

  if (this.correlationIdFn) {

    return this.correlationIdFn()

  }

  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {

    const r = (Math.random() * 16) | 0;

    const v = c === "x" ? r : (r & 0x3) | 0x8;

    return v.toString(16);

  });

}

```



## ‼️ Limitations



The async hooks implementation tracks context through EventEmitters, Timers, and Node.js

core callbacks. However, as async hooks remain experimental, context propagation should be

tested extensively in production like scenarios. In the event that something does not work as

expected, there are some untested patterns and suggested work around. Remember it is better

to error on the side of caution rather than create a memory leak.



### Untested pattern - **Process Next Tick**



```javascript

process.nextTick(() => {

    // context may get lost

    const context = tracker.getContext(); // will create new context

});

```



### Untested pattern - **Node.js Core Module Callbacks** (like fs, http, etc.):



```javascript

const fs = require('fs');

fs.readFile('somefile.txt', (err, data) => {

    // context may get lost

    const context = tracker.getContext(); // will create new context

});

```



### Solution to Untested pattern



Despite the untested patterns, these callbacks can be wrapped and bound. Word of caution, Arrow Functions

can not be bound therefore, you must use `function` declaration.



```javascript

class CorrelationTracker {

    bindCallback(fn) {

        const currentContext = this.getContext();

        return (...args) => {

            const asyncId = asyncHooks.executionAsyncId();

            this.correlationStore.set(asyncId, JSON.parse(JSON.stringify(currentContext)));

            try {

                return fn(...args);

            } finally {

                this.correlationStore.delete(asyncId);

            }

        };

    }

}



// Usage:

emitter.on('someEvent', tracker.bindCallback(() => {

    // context is preserved

    const context = tracker.getContext();

}));

```



2. Or use the async_hooks executionAsyncResource when available:



```javascript

const asyncHooks = require('async_hooks');

const { AsyncResource } = require('async_hooks');



class TrackedEmitter extends EventEmitter {

    emit(event, ...args) {

        const asyncResource = new AsyncResource(event);

        return asyncResource.runInAsyncScope(() => {

            return super.emit(event, ...args);

        });

    }

}

```



## Contributing



Thanks for contributing! 😁 Here are some rules that will make your change to

markdown-fences fruitful.



### Rules



* Raise a ticket to the feature or bug can be discussed

* Pull requests are welcome, but must be accompanied by a ticket approved by the repo owner

* You are expected to add a unit test or two to cover the proposed changes.

* Please run the tests and make sure tests are all passing before submitting your pull request

* Do as the Romans do and stick with existing whitespace and formatting conventions (i.e., tabs instead of spaces, etc)

  * we have provided the following: `.editorconfig` and `.eslintrc`

  * Don't tamper with or change `.editorconfig` and `.eslintrc`

* Please consider adding an example under examples/ that demonstrates any new functionality



### Commit Message



This module uses [release-please](https://github.com/googleapis/release-please) which

needs commit messages to look like the following [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)



```

[optional scope]: 



[optional body]



```



**type** is typically `fix`, `feat`. When **type** ends with a `!` or is `BREAKING CHANGE` it indicates this is a breaking change.



**type** should be followed by a short description, ****



**optional body** can have more detail



### Testing



* All tests are expected to work

* Tests are based off of `dist/index.js` **NOT** your src code. Therefore, you should BUILD it first.

* Coverage should not go down, and I acknowledge it is very difficult to get the tests to 100%



## License



MIT License



Copyright (c) 2025 Philip A Senger



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.



## Acknowledgments



This project directly uses the following open-source packages:



### Dependencies



- None



### Development Dependencies



- [@psenger/markdown-fences](https://github.com/psenger/markdown-fences) - MIT License

- [eslint-config-prettier](https://github.com/prettier/eslint-config-prettier) - MIT License

- [eslint-plugin-jest](https://github.com/jest-community/eslint-plugin-jest) - MIT License

- [eslint-plugin-prettier](https://github.com/prettier/eslint-plugin-prettier) - MIT License

- [eslint](https://github.com/eslint/eslint) - MIT License

- [jest-html-reporters](https://github.com/Hazyzh/jest-html-reporters) - MIT License

- [jest](https://github.com/jestjs/jest) - MIT License

- [jsdoc](https://github.com/jsdoc/jsdoc) - Apache-2.0 License

- [license-checker](https://github.com/davglass/license-checker) - BSD-3-Clause License

- [markdown-toc](https://github.com/jonschlinkert/markdown-toc) - MIT License

- [prettier](https://github.com/prettier/prettier) - MIT License

- [rimraf](https://github.com/isaacs/rimraf) - ISC License

- [rollup](https://github.com/rollup/rollup) - MIT License

- [standard-version](https://github.com/conventional-changelog/standard-version) - ISC License