"description":"A module providing advanced asynchronous context management to enrich logs with context and manage scope effectively in Node.js applications.",
"description":"A module providing advanced asynchronous context management to enrich logs with context and manage scope effectively in Node.js applications.",
@ -14,156 +14,196 @@ This will install the library and its dependencies into your local `node_modules
## Usage
## Usage
The `@push.rocks/smartcontext` module provides an efficient way to enrich your logging (or any functionality) with contextual information. It uses asynchronous context management to support hierarchical scopes—particularly handy when dealing with complex or nested asynchronous operations in Node.js.
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.
The `runScoped` method now creates a child store *automatically* and makes that child store accessible via `asyncContext.store`**only** within the passed-in function. Once that scoped function completes, `asyncContext.store` reverts to the original (parent) store.
### `runScoped`
#### Example
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
```typescript
awaitasyncContext.runScoped(async()=>{
awaitasyncContext.runScoped(async()=>{
// While in this scope, asyncContext.store refers to the child store.
// Inside this callback, `asyncContext.store` is a *child* store
1.**Child Store Access**: Within the scope, `asyncContext.store` points to a *child* store.
2.**Parent Data**: Any keys from the parent are still visible in the child (unless overridden).
3.**No Cross-Contamination**: Keys added in the child store don’t persist in the parent after the scope ends.
### Isolating and Deleting Data
### Isolating Data
If you add a key within a `runScoped` block, it stays there unless you intentionally move it to the parent. Also, if you delete a key in the child, it won’t remove it from the parent store:
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.
You can create multiple scopes, each maintaining its own data isolation. That way, concurrent or sequential operations don’t overwrite or “contaminate” each other’s data in the shared context.
### 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.
If you nest `runScoped` calls, each subsequent call creates another child store, which inherits from the store that’s currently active. This allows you to build deeper context layers when needed.
### 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.
Below is a simplified test example using [tapbundle](https://www.npmjs.com/package/@push.rocks/tapbundle). It demonstrates `runScoped()` creating isolated child stores and verifying behavior such as data inheritance and cleanup:
### 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.
The updated `runScoped`usage makes child store management more intuitive by dynamically switching `asyncContext.store` to a child store inside the scope, then reverting back to the parent store afterwards. This design ensures:
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:
-**Scoped Modifications**: Data added or removed in a child scope stays in that scope.
-Keep each async operation’s state isolated
-**Parent Inheritance**: Child scopes still read the parent’s data.
-Preserve read-access to parent context data
-**Easy Syntax**: No need to pass the child store around; simply call `asyncContext.store` within `runScoped`.
-Avoid overwriting or polluting other operations’ data
With `@push.rocks/smartcontext`, you can maintain clear boundaries between different parts of your asynchronous code. This not only enriches your logging with context but also simplifies tracking data across nested or concurrent operations.
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.
description:'A module providing advanced asynchronous context management to enrich logs with context and manage scope effectively in Node.js applications.'
description:'A module providing advanced asynchronous context management to enrich logs with context and manage scope effectively in Node.js applications.'
}
}
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
