@push.rocks/smartcontext

A module to enrich logs with context, featuring async log contexts and scope management.

readme.md for @push.rocks/smartcontext

A zero-dependency module for hierarchical async context management in Node.js, built on AsyncLocalStorage.

Install

npm install @push.rocks/smartcontext
# or
pnpm install @push.rocks/smartcontext

Usage

@push.rocks/smartcontext provides scoped, hierarchical key-value stores that follow async execution flow. Child scopes inherit parent data, can add or delete keys without affecting the parent, and automatically clean up when the scope exits.

This is useful for log enrichment, request-scoped metadata, transaction tracking, and any scenario where contextual data needs to flow through deeply nested async calls.

Basic Setup

import { AsyncContext } from '@push.rocks/smartcontext';

const ctx = new AsyncContext();

// Add data to the root store
ctx.store.add('userId', 'u_123');
console.log(ctx.store.get('userId')); // 'u_123'

Scoped Execution with runScoped

runScoped creates an isolated child store for the duration of the callback. Inside the callback, ctx.store transparently points to the child store. The child inherits all parent data but any additions or deletions are local to the child.

ctx.store.add('requestId', 'req_abc');

await ctx.runScoped(async () => {
  // Child store sees parent data
  console.log(ctx.store.get('requestId')); // 'req_abc'

  // Add child-only data
  ctx.store.add('spanId', 'span_001');
  console.log(ctx.store.get('spanId')); // 'span_001'
});

// After scope exits, child data is gone
console.log(ctx.store.get('spanId')); // undefined
// Parent data is untouched
console.log(ctx.store.get('requestId')); // 'req_abc'

Deleting Keys in a Child Scope

Deleting a parent key inside a child scope only shadows it within that scope. The parent retains the original value.

ctx.store.add('token', 'secret_value');

await ctx.runScoped(async () => {
  ctx.store.delete('token');
  console.log(ctx.store.get('token')); // undefined (shadowed)
});

console.log(ctx.store.get('token')); // 'secret_value' (parent unaffected)

Parallel Scopes

Multiple concurrent runScoped calls each get their own isolated child store, preventing data collisions across async tasks.

await Promise.all([
  ctx.runScoped(async () => {
    ctx.store.add('worker', 'A');
    // Only this scope sees worker=A
  }),
  ctx.runScoped(async () => {
    ctx.store.add('worker', 'B');
    // Only this scope sees worker=B
  }),
]);

console.log(ctx.store.get('worker')); // undefined

Retrieving All Data

store.getAll() returns a merged view of the store hierarchy, with child values overriding parent values and deleted keys excluded.

ctx.store.add('env', 'production');
ctx.store.add('region', 'eu-west-1');

await ctx.runScoped(async () => {
  ctx.store.add('traceId', 'tr_xyz');
  console.log(ctx.store.getAll());
  // { env: 'production', region: 'eu-west-1', traceId: 'tr_xyz' }
});

API Reference

AsyncContext

Method / Property Description
store The current AsyncStore (root or scoped child)
runScoped(fn) Execute fn with an isolated child store

AsyncStore

Method Description
add(key, value) Set a key-value pair
get(key) Get a value (checks local store, then parent chain)
delete(key) Remove a key (shadows parent key if inherited)
getAll() Get all key-value pairs merged from the full parent chain

This repository is under the MIT License. Please note that the MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as necessary for reasonable use in describing the origin of the work.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Usage must be approved in writing by Task Venture Capital GmbH.

Company Information

Task Venture Capital GmbH Registered at District Court Bremen HRB 35230 HB, Germany

changelog.md for @push.rocks/smartcontext

2026-02-15 - 2.3.0 - feat(asynccontext)

replace simple-async-context with Node's AsyncLocalStorage and update implementation, tests, docs, and devDependencies

2025-01-25 - 2.2.1 - fix(core)

Remove unused logcontext classes and update exports

2025-01-25 - 2.2.0 - feat(tests)

Added a new test script to demonstrate and validate AsyncContext functionality

2025-01-23 - 2.1.8 - fix(core)

Refactor and clean up class imports and exports

2025-01-23 - 2.1.7 - fix(core)

Enhanced debugging and improved dependency tracking

2025-01-19 - 2.1.6 - fix(core)

Updated dependencies and improved AsyncStore debugging and cleanup

2025-01-19 - 2.1.5 - fix(dependencies)

Update dependencies for improved compatibility

2025-01-19 - 2.1.4 - fix(documentation)

Remove unnecessary conclusion section from the README for better clarity.

2025-01-19 - 2.1.3 - fix(readme)

Update README.md for better clarity and examples.

2025-01-19 - 2.1.2 - fix(core)

Improve scope handling in async contexts.

2025-01-18 - 2.1.1 - fix(build)

Fix tsbuild script to include missing flag

2025-01-18 - 2.1.0 - feat(ci)

Add GitHub Actions workflows for CI/CD

2024-05-29 to 2024-03-30 - 2.0.0 - Configuration Updates

Improvements and updates to configuration files.

2023-07-11 to 2023-07-10 - 2.0.0 - Organizational Change

Transitioned to a new organizational scheme for improved project structure.

2023-01-12 - 1.0.29 - Breaking Change

Important breaking changes introduced, switched project to ECMAScript Module (ESM) format.

2021-09-17 to 2020-07-20 - 1.0.28 to 1.0.23 - Core Fixes

Multiple core improvements and bug fixes across several versions.

2018-03-09 to 2018-03-05 - 1.0.21 to 1.0.20 - Documentation Updates

Enhancements and updates to project documentation.

2018-03-05 - 1.0.19 - Standards Update

Updated project to comply with the latest coding standards.

2018-03-03 - 1.0.18 - Initial Working Version

Initial release with all dependencies configured.

2017-10-16 - 1.0.2 - Documentation

Initial project documentation added.

2017-10-16 - 1.0.1 - Initial Release

The initial release of the project.