221 lines
8.9 KiB
Markdown
221 lines
8.9 KiB
Markdown
# @push.rocks/smartcontext
|
||
|
||
A module to enrich logs with context, featuring async log contexts and scope management.
|
||
|
||
Special thanks to Ilias Bhallil for his awesome simple-async-context library.
|
||
|
||
## Install
|
||
|
||
Make sure you have Node.js and npm installed, then run:
|
||
|
||
```bash
|
||
npm install @push.rocks/smartcontext
|
||
```
|
||
|
||
This will install the library and its dependencies into your local `node_modules` folder.
|
||
|
||
## Usage
|
||
|
||
The `@push.rocks/smartcontext` module provides an efficient way to enrich your code (often for logging) with contextual information. It uses asynchronous context management to support hierarchical scopes—particularly helpful in complex or nested asynchronous operations in Node.js.
|
||
|
||
### Basic Setup
|
||
|
||
```typescript
|
||
import { AsyncContext } from '@push.rocks/smartcontext';
|
||
|
||
const asyncContext = new AsyncContext();
|
||
|
||
// The parent store is always accessible through `asyncContext.store`
|
||
asyncContext.store.add('username', 'john_doe');
|
||
console.log(asyncContext.store.get('username')); // 'john_doe'
|
||
```
|
||
|
||
|
||
### `runScoped`
|
||
|
||
When you call `asyncContext.runScoped(async () => { ... })`, the library automatically creates a **child** `AsyncStore`. Inside that scoped function, `asyncContext.store` refers to the child store. Any data you add or delete there is isolated from the parent store. However, you can still read parent data if it hasn’t been overridden.
|
||
|
||
```typescript
|
||
await asyncContext.runScoped(async () => {
|
||
// Inside this callback, `asyncContext.store` is a *child* store
|
||
asyncContext.store.add('transactionId', 'txn_abc123');
|
||
console.log(asyncContext.store.get('transactionId')); // 'txn_abc123'
|
||
|
||
// We can also see parent data like 'username'
|
||
console.log(asyncContext.store.get('username')); // 'john_doe'
|
||
});
|
||
|
||
// Outside `runScoped`, asyncContext.store reverts to the parent store
|
||
console.log(asyncContext.store.get('transactionId')); // undefined
|
||
```
|
||
|
||
|
||
### Isolating Data
|
||
|
||
Because each call to `runScoped` returns control to the parent store afterward, any keys added in a child scope disappear once the scope completes (unless you explicitly move them to the parent). This mechanism keeps data from leaking between scopes.
|
||
|
||
```typescript
|
||
// Parent store
|
||
asyncContext.store.add('someParentKey', 'parentValue');
|
||
|
||
// Child scope
|
||
await asyncContext.runScoped(async () => {
|
||
asyncContext.store.add('scopedKey', 'childValue');
|
||
console.log(asyncContext.store.get('scopedKey')); // 'childValue'
|
||
});
|
||
|
||
// Outside, the child key is gone
|
||
console.log(asyncContext.store.get('scopedKey')); // undefined
|
||
```
|
||
|
||
|
||
### Deleting Data
|
||
|
||
If the child deletes a key that exists in the parent, it will only remove it from the child’s view of the store. Once the scope completes, the parent store is unaffected.
|
||
|
||
```typescript
|
||
asyncContext.store.add('deletableKey', 'originalValue');
|
||
|
||
await asyncContext.runScoped(async () => {
|
||
console.log(asyncContext.store.get('deletableKey')); // 'originalValue'
|
||
asyncContext.store.delete('deletableKey');
|
||
console.log(asyncContext.store.get('deletableKey')); // undefined in child
|
||
});
|
||
|
||
console.log(asyncContext.store.get('deletableKey')); // 'originalValue' remains in parent
|
||
```
|
||
|
||
|
||
### Parallel or Sequential Scopes
|
||
|
||
You can call `runScoped` multiple times, whether sequentially or in parallel (with `Promise.all`). Each invocation creates its own isolated child store, preventing data collisions across asynchronous tasks.
|
||
|
||
```typescript
|
||
await asyncContext.runScoped(async () => {
|
||
asyncContext.store.add('childKey1', 'childValue1');
|
||
console.log(asyncContext.store.get('childKey1')); // 'childValue1'
|
||
});
|
||
|
||
await asyncContext.runScoped(async () => {
|
||
asyncContext.store.add('childKey2', 'childValue2');
|
||
console.log(asyncContext.store.get('childKey2')); // 'childValue2'
|
||
});
|
||
|
||
// Both keys were added in separate scopes, so they won't exist in the parent
|
||
console.log(asyncContext.store.get('childKey1')); // undefined
|
||
console.log(asyncContext.store.get('childKey2')); // undefined
|
||
```
|
||
|
||
|
||
### Testing Example
|
||
|
||
The following is a complete test script (using [tapbundle](https://www.npmjs.com/package/@push.rocks/tapbundle)) demonstrating how child stores inherit data from the parent but remain isolated. After each scoped block, new child keys vanish, and any parent keys deleted inside the child remain intact in the parent.
|
||
|
||
```typescript
|
||
import { tap, expect } from '@push.rocks/tapbundle';
|
||
import { AsyncContext } from '../ts/logcontext.classes.asynccontext.js';
|
||
|
||
const asyncContext = new AsyncContext();
|
||
|
||
tap.test('should run a scoped function and add data to a child store', async () => {
|
||
// Add some default data to the parent store
|
||
asyncContext.store.add('parentKey', 'parentValue');
|
||
expect(asyncContext.store.get('parentKey')).toEqual('parentValue');
|
||
|
||
// Now run a child scope, add some data, and check that parent data is still accessible
|
||
await asyncContext.runScoped(async () => {
|
||
asyncContext.store.add('childKey', 'childValue');
|
||
|
||
// Child sees its own data
|
||
expect(asyncContext.store.get('childKey')).toEqual('childValue');
|
||
// Child also sees parent data
|
||
expect(asyncContext.store.get('parentKey')).toEqual('parentValue');
|
||
});
|
||
});
|
||
|
||
tap.test('should not contaminate the parent store with child-only data', async () => {
|
||
// Create a new child scope
|
||
await asyncContext.runScoped(async () => {
|
||
asyncContext.store.add('temporaryKey', 'temporaryValue');
|
||
expect(asyncContext.store.get('temporaryKey')).toEqual('temporaryValue');
|
||
});
|
||
// After scope finishes, 'temporaryKey' won't exist in the parent
|
||
expect(asyncContext.store.get('temporaryKey')).toBeUndefined();
|
||
});
|
||
|
||
tap.test('should allow adding data in multiple scopes independently', async () => {
|
||
// Add data in the first scope
|
||
await asyncContext.runScoped(async () => {
|
||
asyncContext.store.add('childKey1', 'childValue1');
|
||
expect(asyncContext.store.get('childKey1')).toEqual('childValue1');
|
||
});
|
||
|
||
// Add data in the second scope
|
||
await asyncContext.runScoped(async () => {
|
||
asyncContext.store.add('childKey2', 'childValue2');
|
||
expect(asyncContext.store.get('childKey2')).toEqual('childValue2');
|
||
});
|
||
|
||
// Neither childKey1 nor childKey2 should exist in the parent store
|
||
expect(asyncContext.store.get('childKey1')).toBeUndefined();
|
||
expect(asyncContext.store.get('childKey2')).toBeUndefined();
|
||
});
|
||
|
||
tap.test('should allow deleting data in a child store without removing it from the parent store', async () => {
|
||
// Ensure parent has some data
|
||
asyncContext.store.add('deletableKey', 'iShouldStayInParent');
|
||
|
||
await asyncContext.runScoped(async () => {
|
||
// Child sees the parent's data
|
||
expect(asyncContext.store.get('deletableKey')).toEqual('iShouldStayInParent');
|
||
// Delete it in the child
|
||
asyncContext.store.delete('deletableKey');
|
||
// Child no longer sees it
|
||
expect(asyncContext.store.get('deletableKey')).toBeUndefined();
|
||
});
|
||
// Parent still has it
|
||
expect(asyncContext.store.get('deletableKey')).toEqual('iShouldStayInParent');
|
||
});
|
||
|
||
tap.test('should allow multiple child scopes to share the same parent store data', async () => {
|
||
// Add a key to the parent store
|
||
asyncContext.store.add('sharedKey', 'sharedValue');
|
||
expect(asyncContext.store.get('sharedKey')).toEqual('sharedValue');
|
||
|
||
// First child scope
|
||
await asyncContext.runScoped(async () => {
|
||
expect(asyncContext.store.get('sharedKey')).toEqual('sharedValue');
|
||
});
|
||
|
||
// Second child scope
|
||
await asyncContext.runScoped(async () => {
|
||
expect(asyncContext.store.get('sharedKey')).toEqual('sharedValue');
|
||
});
|
||
});
|
||
|
||
export default tap.start();
|
||
```
|
||
|
||
|
||
With this updated `runScoped` design, there’s no need to explicitly instantiate or manage child stores. The context automatically switches from the parent store to the child store while within the callback, then reverts back to the parent store afterwards. This structure makes it easy to:
|
||
|
||
- Keep each async operation’s state isolated
|
||
- Preserve read-access to parent context data
|
||
- Avoid overwriting or polluting other operations’ data
|
||
|
||
This pattern works particularly well for logging or any scenario where you need to pass metadata through deeply nested async calls without manually juggling that data everywhere in your code.
|
||
|
||
## License and Legal Information
|
||
|
||
This repository is under the [MIT License](./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
|
||
|
||
For any legal inquiries, please contact us at hello@task.vc. By using this repository, you acknowledge that you have read this section and agree to comply with its terms. |