@warlock.js/context 4.0.171 → 4.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/cjs/index.cjs +239 -0
- package/cjs/index.cjs.map +1 -0
- package/esm/base-context.d.mts +99 -0
- package/esm/base-context.d.mts.map +1 -0
- package/esm/base-context.mjs +110 -0
- package/esm/base-context.mjs.map +1 -0
- package/esm/context-manager.d.mts +106 -0
- package/esm/context-manager.d.mts.map +1 -0
- package/esm/context-manager.mjs +128 -0
- package/esm/context-manager.mjs.map +1 -0
- package/esm/index.d.mts +3 -0
- package/esm/index.mjs +4 -0
- package/llms-full.txt +404 -0
- package/llms.txt +11 -0
- package/package.json +42 -30
- package/skills/define-context/SKILL.md +158 -0
- package/skills/orchestrate-contexts/SKILL.md +161 -0
- package/skills/overview/SKILL.md +67 -0
- package/cjs/base-context.d.ts +0 -96
- package/cjs/base-context.d.ts.map +0 -1
- package/cjs/base-context.js +0 -105
- package/cjs/base-context.js.map +0 -1
- package/cjs/context-manager.d.ts +0 -102
- package/cjs/context-manager.d.ts.map +0 -1
- package/cjs/context-manager.js +0 -132
- package/cjs/context-manager.js.map +0 -1
- package/cjs/index.d.ts +0 -3
- package/cjs/index.d.ts.map +0 -1
- package/cjs/index.js +0 -1
- package/cjs/index.js.map +0 -1
- package/esm/base-context.d.ts +0 -96
- package/esm/base-context.d.ts.map +0 -1
- package/esm/base-context.js +0 -105
- package/esm/base-context.js.map +0 -1
- package/esm/context-manager.d.ts +0 -102
- package/esm/context-manager.d.ts.map +0 -1
- package/esm/context-manager.js +0 -132
- package/esm/context-manager.js.map +0 -1
- package/esm/index.d.ts +0 -3
- package/esm/index.d.ts.map +0 -1
- package/esm/index.js +0 -1
- package/esm/index.js.map +0 -1
|
@@ -0,0 +1,158 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: define-context
|
|
3
|
+
description: 'Extend Context<TStore> to define an AsyncLocalStorage-backed typed context — implement buildStore, use run / enter / update / get / set / getStore / clear / hasContext. Triggers: `Context`, `Context<TStore>`, `buildStore`, `run`, `enter`, `update`, `get`, `set`, `getStore`, `clear`, `hasContext`; "share user/tenant/trace id across async calls", "AsyncLocalStorage typed wrapper", "request-scoped store without thread-through"; typical import `import { Context } from "@warlock.js/context"`. Skip: orchestrating multiple contexts — `@warlock.js/context/orchestrate-contexts/SKILL.md`; native `AsyncLocalStorage`, `cls-hooked`, `nest-context`, React Context.'
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Define a context
|
|
7
|
+
|
|
8
|
+
`@warlock.js/context` is a tiny wrapper on Node.js's `AsyncLocalStorage`. You extend the abstract `Context<TStore>` class to declare what your context stores, and you get a typed get/set/run API that propagates through every async call inside the scope.
|
|
9
|
+
|
|
10
|
+
## Install
|
|
11
|
+
|
|
12
|
+
```bash
|
|
13
|
+
yarn add @warlock.js/context
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
## Shape
|
|
17
|
+
|
|
18
|
+
```ts
|
|
19
|
+
import { Context } from "@warlock.js/context";
|
|
20
|
+
|
|
21
|
+
interface UserContextStore {
|
|
22
|
+
userId: string;
|
|
23
|
+
role: "admin" | "user";
|
|
24
|
+
tenantId: string;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
class UserContext extends Context<UserContextStore> {
|
|
28
|
+
/**
|
|
29
|
+
* Called by `contextManager.buildStores(payload)` for each registered context.
|
|
30
|
+
* Override to provide initialization logic for this context's store.
|
|
31
|
+
*/
|
|
32
|
+
public buildStore(payload?: Record<string, any>): UserContextStore {
|
|
33
|
+
return {
|
|
34
|
+
userId: payload?.userId ?? "",
|
|
35
|
+
role: payload?.role ?? "user",
|
|
36
|
+
tenantId: payload?.tenantId ?? "",
|
|
37
|
+
};
|
|
38
|
+
}
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
export const userContext = new UserContext();
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
`buildStore` is the **only** abstract method. Everything else is provided by `Context<TStore>`.
|
|
45
|
+
|
|
46
|
+
## Usage modes
|
|
47
|
+
|
|
48
|
+
### `run()` — scoped execution
|
|
49
|
+
|
|
50
|
+
```ts
|
|
51
|
+
await userContext.run(
|
|
52
|
+
{ userId: "123", role: "admin", tenantId: "acme" },
|
|
53
|
+
async () => {
|
|
54
|
+
// Context is available throughout this async scope and any awaited calls inside it.
|
|
55
|
+
const userId = userContext.get("userId"); // "123"
|
|
56
|
+
const role = userContext.get("role"); // "admin"
|
|
57
|
+
|
|
58
|
+
await someAsyncOperation(); // context propagates through awaits
|
|
59
|
+
},
|
|
60
|
+
);
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
Use `run()` when you have a clear scope boundary (a request handler, a job, a CLI command). The context is auto-cleaned when the callback returns.
|
|
64
|
+
|
|
65
|
+
### `enter()` — middleware-style, no callback
|
|
66
|
+
|
|
67
|
+
```ts
|
|
68
|
+
function authMiddleware(req, res, next) {
|
|
69
|
+
userContext.enter({
|
|
70
|
+
userId: req.user.id,
|
|
71
|
+
role: req.user.role,
|
|
72
|
+
tenantId: req.headers["x-tenant-id"],
|
|
73
|
+
});
|
|
74
|
+
|
|
75
|
+
next(); // context lives for the rest of the request
|
|
76
|
+
}
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
Use `enter()` when the framework doesn't give you a callback to wrap (Express-style middleware). Under the hood it's `AsyncLocalStorage.enterWith(store)`.
|
|
80
|
+
|
|
81
|
+
### `update()` — merge into the current context
|
|
82
|
+
|
|
83
|
+
```ts
|
|
84
|
+
userContext.update({ role: "admin" });
|
|
85
|
+
// existing store: { userId, role, tenantId } → { userId, role: "admin", tenantId }
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
If there's no current store, `update` creates one with the partial (cast to the full type). Use for incremental enrichment as the request flows through layers.
|
|
89
|
+
|
|
90
|
+
## Reading
|
|
91
|
+
|
|
92
|
+
```ts
|
|
93
|
+
const userId = userContext.get("userId"); // TStore[K] | undefined
|
|
94
|
+
const store = userContext.getStore(); // TStore | undefined
|
|
95
|
+
const inside = userContext.hasContext(); // boolean
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
`get` is the daily-use accessor. `getStore` returns the whole record. `hasContext` distinguishes "key absent" from "no context at all" (which matters for safety checks at the framework boundary).
|
|
99
|
+
|
|
100
|
+
## Writing within a context
|
|
101
|
+
|
|
102
|
+
```ts
|
|
103
|
+
userContext.set("role", "admin"); // sugar for update({ role: "admin" })
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
Only call `set` inside an active context. Outside one, it enters a new context with just that key set — usually not what you want.
|
|
107
|
+
|
|
108
|
+
## Clearing
|
|
109
|
+
|
|
110
|
+
```ts
|
|
111
|
+
userContext.clear();
|
|
112
|
+
// replaces the current store with an empty object of TStore
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
Rare in app code. The auto-cleanup at the end of `run()` is the normal path.
|
|
116
|
+
|
|
117
|
+
## Convenience getters via subclass
|
|
118
|
+
|
|
119
|
+
Add domain-friendly getters on the subclass when a key is read a lot:
|
|
120
|
+
|
|
121
|
+
```ts
|
|
122
|
+
class TenantContext extends Context<TenantStore> {
|
|
123
|
+
public buildStore(payload?: Record<string, any>): TenantStore {
|
|
124
|
+
return {
|
|
125
|
+
tenantId: payload?.tenantId ?? "",
|
|
126
|
+
tenantName: payload?.tenantName ?? "",
|
|
127
|
+
config: payload?.config ?? {},
|
|
128
|
+
};
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
public get tenantId() {
|
|
132
|
+
return this.get("tenantId");
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
public get config() {
|
|
136
|
+
return this.get("config");
|
|
137
|
+
}
|
|
138
|
+
}
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
Now `tenantContext.tenantId` reads better than `tenantContext.get("tenantId")` at the call site.
|
|
142
|
+
|
|
143
|
+
## What it's NOT for
|
|
144
|
+
|
|
145
|
+
- **Persistent state across requests.** AsyncLocalStorage is per-call-tree; data dies when the scope ends. Use a cache, a database, or a singleton for cross-request data.
|
|
146
|
+
- **Thread-safe shared mutable state.** Each `run()` gets a fresh store. Two parallel `run()` calls don't see each other's updates.
|
|
147
|
+
- **Sync code that doesn't `await` anything.** Works, but if there's no async boundary the context add-overhead is wasted — just pass the data as a parameter.
|
|
148
|
+
|
|
149
|
+
## See also
|
|
150
|
+
|
|
151
|
+
- [`@warlock.js/context/orchestrate-contexts/SKILL.md`](@warlock.js/context/orchestrate-contexts/SKILL.md) — running multiple contexts together via the `contextManager` singleton.
|
|
152
|
+
|
|
153
|
+
## Things NOT to do
|
|
154
|
+
|
|
155
|
+
- Don't make every cross-cutting concern a context. Build one when it has its own lifecycle (request, db transaction, trace span). For one-off data, a function argument is clearer.
|
|
156
|
+
- Don't capture the store reference outside the scope — it's freed when `run()` ends. Read the value out before exiting the scope if you need it later.
|
|
157
|
+
- Don't mutate the store object directly without `update`/`set` — works, but obscures intent. The methods exist to make state changes searchable.
|
|
158
|
+
- Don't share one context instance across unrelated concerns. One typed context per domain concept reads better than one fat `globalContext`.
|
|
@@ -0,0 +1,161 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: orchestrate-contexts
|
|
3
|
+
description: 'Orchestrate multiple Context<TStore> instances via the contextManager singleton — register, buildStores, runAll, enterAll, clearAll. Triggers: `contextManager`, `register`, `buildStores`, `runAll`, `enterAll`, `clearAll`, `unregister`, `getContext`, `hasContext`; "run multiple contexts active for the same scope", "register contexts at boot", "avoid nested run() calls for request + database + tenant"; typical import `import { contextManager } from "@warlock.js/context"`. Skip: defining a single context class — `@warlock.js/context/define-context/SKILL.md`; native `AsyncLocalStorage` nesting, `cls-hooked` namespaces.'
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Orchestrate contexts — `contextManager`
|
|
7
|
+
|
|
8
|
+
`contextManager` is a singleton that knows about every registered `Context` and runs them all together so you don't write nested `run()` calls by hand.
|
|
9
|
+
|
|
10
|
+
## Why use it
|
|
11
|
+
|
|
12
|
+
You can call `context.run(store, fn)` directly when you only have one context. With two or more, the manager handles the nesting:
|
|
13
|
+
|
|
14
|
+
```ts
|
|
15
|
+
// ❌ Without the manager — fragile, easy to forget a layer
|
|
16
|
+
await requestContext.run(reqStore, async () =>
|
|
17
|
+
databaseContext.run(dbStore, async () =>
|
|
18
|
+
tenantContext.run(tenantStore, async () => handle()),
|
|
19
|
+
),
|
|
20
|
+
);
|
|
21
|
+
|
|
22
|
+
// ✅ With the manager — one call, deterministic order
|
|
23
|
+
await contextManager.runAll({ request: reqStore, database: dbStore, tenant: tenantStore }, handle);
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
## Register contexts at boot
|
|
27
|
+
|
|
28
|
+
```ts
|
|
29
|
+
import { contextManager } from "@warlock.js/context";
|
|
30
|
+
import { requestContext } from "./request-context";
|
|
31
|
+
import { databaseContext } from "./database-context";
|
|
32
|
+
import { tenantContext } from "./tenant-context";
|
|
33
|
+
|
|
34
|
+
contextManager
|
|
35
|
+
.register("request", requestContext)
|
|
36
|
+
.register("database", databaseContext)
|
|
37
|
+
.register("tenant", tenantContext);
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
Returns the manager — chain registrations. Names must be unique; re-registering with the same name overwrites.
|
|
41
|
+
|
|
42
|
+
## Build stores + run
|
|
43
|
+
|
|
44
|
+
The typical flow is two-step: build initial stores from a request-like payload, then run.
|
|
45
|
+
|
|
46
|
+
```ts
|
|
47
|
+
app.use(async (req, res, next) => {
|
|
48
|
+
const stores = contextManager.buildStores({
|
|
49
|
+
request: req,
|
|
50
|
+
response: res,
|
|
51
|
+
tenantId: req.headers["x-tenant-id"],
|
|
52
|
+
});
|
|
53
|
+
|
|
54
|
+
await contextManager.runAll(stores, async () => {
|
|
55
|
+
await next();
|
|
56
|
+
});
|
|
57
|
+
});
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
`buildStores(payload)` calls each registered context's `buildStore(payload)` (the abstract method on `Context<TStore>` — see [`@warlock.js/context/define-context/SKILL.md`](@warlock.js/context/define-context/SKILL.md)) and returns `{ [contextName]: store }`.
|
|
61
|
+
|
|
62
|
+
`runAll(stores, fn)` nests every context's `run()` in registration order, then invokes `fn` at the innermost layer. All contexts are active inside `fn`.
|
|
63
|
+
|
|
64
|
+
## `enterAll()` — middleware without a callback
|
|
65
|
+
|
|
66
|
+
When the framework doesn't give you a callback to wrap (e.g. Express middleware where you call `next()` and return):
|
|
67
|
+
|
|
68
|
+
```ts
|
|
69
|
+
function contextMiddleware(req, res, next) {
|
|
70
|
+
const stores = contextManager.buildStores({ request: req, response: res });
|
|
71
|
+
contextManager.enterAll(stores);
|
|
72
|
+
next();
|
|
73
|
+
}
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
`enterAll` calls `enter()` on each registered context whose name has a **truthy** store value — a `name` with no key (or a falsy value like `undefined`) is skipped, leaving any already-active store for that context untouched. The entered contexts live for the rest of the request. Each can still be `clear()`-ed later. Use `runAll` when you can — `enterAll` doesn't auto-clean.
|
|
77
|
+
|
|
78
|
+
## Lookup + introspection
|
|
79
|
+
|
|
80
|
+
```ts
|
|
81
|
+
contextManager.hasContext("tenant"); // boolean
|
|
82
|
+
const tenant = contextManager.getContext<TenantContext>("tenant");
|
|
83
|
+
// returns the registered instance or undefined
|
|
84
|
+
contextManager.unregister("debug"); // remove a context
|
|
85
|
+
contextManager.clearAll(); // clear stores on every context
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
`getContext<T>` returns the registered instance cast to `T` (the generic is constrained to `Context<any>`, so pass the concrete context class — `getContext<TenantContext>("tenant")`). It's an unchecked cast: an unknown `name` returns `undefined`, and a wrong type argument won't be caught at runtime. Useful in shared utilities that want to read from a context without importing it at the call site.
|
|
89
|
+
|
|
90
|
+
## Order matters
|
|
91
|
+
|
|
92
|
+
`runAll` nests in **registration order**. The first-registered context is the outermost layer. If contexts have ordering constraints (database before tenant because tenant resolves via the db), register them in that order.
|
|
93
|
+
|
|
94
|
+
```ts
|
|
95
|
+
contextManager
|
|
96
|
+
.register("trace", traceContext) // outermost — runs first
|
|
97
|
+
.register("request", requestContext)
|
|
98
|
+
.register("database", databaseContext)
|
|
99
|
+
.register("tenant", tenantContext); // innermost — runs last, inside all others
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
## Real-world: multi-tenant request lifecycle
|
|
103
|
+
|
|
104
|
+
```ts
|
|
105
|
+
import { Context, contextManager } from "@warlock.js/context";
|
|
106
|
+
import { randomUUID } from "crypto";
|
|
107
|
+
|
|
108
|
+
class TraceContext extends Context<{ traceId: string; startTime: number }> {
|
|
109
|
+
public buildStore(): { traceId: string; startTime: number } {
|
|
110
|
+
return { traceId: randomUUID(), startTime: Date.now() };
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
public get traceId() {
|
|
114
|
+
return this.get("traceId");
|
|
115
|
+
}
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
class RequestContext extends Context<{ request: any; response: any }> {
|
|
119
|
+
public buildStore(payload?: any) {
|
|
120
|
+
return { request: payload?.request, response: payload?.response };
|
|
121
|
+
}
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
class TenantContext extends Context<{ tenantId: string }> {
|
|
125
|
+
public buildStore(payload?: any) {
|
|
126
|
+
return { tenantId: payload?.tenantId ?? "" };
|
|
127
|
+
}
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
export const traceContext = new TraceContext();
|
|
131
|
+
export const requestContext = new RequestContext();
|
|
132
|
+
export const tenantContext = new TenantContext();
|
|
133
|
+
|
|
134
|
+
contextManager
|
|
135
|
+
.register("trace", traceContext)
|
|
136
|
+
.register("request", requestContext)
|
|
137
|
+
.register("tenant", tenantContext);
|
|
138
|
+
|
|
139
|
+
// In your HTTP layer:
|
|
140
|
+
async function handleRequest(req: any, res: any) {
|
|
141
|
+
const stores = contextManager.buildStores({
|
|
142
|
+
request: req,
|
|
143
|
+
response: res,
|
|
144
|
+
tenantId: req.headers["x-tenant-id"],
|
|
145
|
+
});
|
|
146
|
+
|
|
147
|
+
return contextManager.runAll(stores, async () => {
|
|
148
|
+
// All three contexts active here:
|
|
149
|
+
console.log(`Trace ${traceContext.get("traceId")} — tenant ${tenantContext.get("tenantId")}`);
|
|
150
|
+
|
|
151
|
+
await routeAndDispatch(req, res);
|
|
152
|
+
});
|
|
153
|
+
}
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
## Things NOT to do
|
|
157
|
+
|
|
158
|
+
- Don't register the same context under two names — every context is its own singleton and shares its store across registrations, but multiple names confuse `buildStores` (the payload is split per name).
|
|
159
|
+
- Don't `runAll` an empty stores map — every key without a registered context is silently ignored, and missing contexts get `{}` as their store. Better to construct the stores explicitly and fail loudly when a key is missing.
|
|
160
|
+
- Don't use the manager when only one context applies. `context.run(store, fn)` is shorter and has the same semantics.
|
|
161
|
+
- Don't expect `enterAll()` to auto-clean. It's a one-way setup — pair with `clearAll()` at the end of the request, or just use `runAll` when you can.
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: overview
|
|
3
|
+
description: 'Front-door orientation for `@warlock.js/context` — typed AsyncLocalStorage wrappers for sharing data (user, tenant, trace, request) across async calls without thread-through. Extend `Context<TStore>` for a single context; use `contextManager` to orchestrate several at once. TRIGGER when: code imports anything from `@warlock.js/context`; user asks "what does @warlock.js/context do", "AsyncLocalStorage but typed", "share user/tenant across async without thread-through", "compare context vs cls-hooked / nest-context"; package.json adds `@warlock.js/context`. Skip: specific task already known — load the matching task skill directly (`@warlock.js/context/define-context/SKILL.md`, `@warlock.js/context/orchestrate-contexts/SKILL.md`); plain `AsyncLocalStorage` usage with no `Context<>` wrapper; React Context (this package is server-side / Node-only).'
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# `@warlock.js/context` — overview
|
|
7
|
+
|
|
8
|
+
Two-file package: a typed wrapper over Node's `AsyncLocalStorage` and a singleton that runs several of them together. That's it. The entire surface fits in two skills below — most callers only need the first one.
|
|
9
|
+
|
|
10
|
+
## When to reach for it
|
|
11
|
+
|
|
12
|
+
- You have request-scoped data (user, tenant, trace id, db transaction) that you'd otherwise thread through every function as a parameter. One `userContext.get("userId")` anywhere down the call tree replaces five layers of plumbing.
|
|
13
|
+
- You're inside a `@warlock.js/*` project and want consistent context handling across modules. The framework already uses this package internally for request + user + tenant contexts.
|
|
14
|
+
- You'd reach for `cls-hooked`, `nest-context`, or a bare `AsyncLocalStorage<T>` and want a typed wrapper with `run` / `enter` / `update` / `get` / `set` semantics out of the box.
|
|
15
|
+
|
|
16
|
+
Skip if your call chain is a single function with no `await` boundaries — just pass the data as a parameter. Skip if you need cross-request shared state — that's a cache or database, not a context.
|
|
17
|
+
|
|
18
|
+
## What it is in one sentence
|
|
19
|
+
|
|
20
|
+
Each `Context<TStore>` subclass declares a typed store shape and what payload builds it; the framework uses Node's `AsyncLocalStorage` under the hood so the store propagates through every `await` inside the scope and disappears when the scope ends.
|
|
21
|
+
|
|
22
|
+
## Skills index
|
|
23
|
+
|
|
24
|
+
Two task skills cover everything. The first one is the daily-use one; the second is for when you have multiple contexts active at the same time.
|
|
25
|
+
|
|
26
|
+
### [`define-context/`](../define-context/SKILL.md)
|
|
27
|
+
|
|
28
|
+
Extend `Context<TStore>` to declare what your context stores and how it's
|
|
29
|
+
built. Implement `buildStore(payload?)`; use `run` / `enter` / `update` /
|
|
30
|
+
`get` / `set` / `getStore` / `clear` / `hasContext` to interact with the
|
|
31
|
+
store from anywhere in the async scope.
|
|
32
|
+
|
|
33
|
+
Load when sharing data (user, tenant, trace id) across async calls
|
|
34
|
+
without threading it through every function — i.e. ~90% of the time you
|
|
35
|
+
use this package.
|
|
36
|
+
|
|
37
|
+
### [`orchestrate-contexts/`](../orchestrate-contexts/SKILL.md)
|
|
38
|
+
|
|
39
|
+
Register multiple `Context<TStore>` instances on the `contextManager`
|
|
40
|
+
singleton and run them all together with a single call. Covers
|
|
41
|
+
`register` / `unregister`, `buildStores`, `runAll` / `enterAll`,
|
|
42
|
+
`clearAll`, `getContext` / `hasContext`.
|
|
43
|
+
|
|
44
|
+
Load when several contexts apply to the same scope (request + database
|
|
45
|
+
+ trace + tenant) and you'd otherwise nest `run()` calls by hand.
|
|
46
|
+
|
|
47
|
+
## Two operating modes — when to pick which
|
|
48
|
+
|
|
49
|
+
| Situation | Reach for |
|
|
50
|
+
| --- | --- |
|
|
51
|
+
| Framework gives you a callback to wrap | `context.run(store, callback)` |
|
|
52
|
+
| Framework expects middleware that returns synchronously (Express, etc.) | `context.enter(store)` |
|
|
53
|
+
| You have 2+ contexts active for the same request | `contextManager.runAll(stores, callback)` |
|
|
54
|
+
| Middleware-style with 2+ contexts | `contextManager.enterAll(stores)` then `clearAll()` at end |
|
|
55
|
+
| You only have one context and the framework cooperates | Single `context.run(...)`. Skip the manager. |
|
|
56
|
+
|
|
57
|
+
## What this package deliberately doesn't do
|
|
58
|
+
|
|
59
|
+
- **Persist data across requests.** AsyncLocalStorage dies with the scope. For cross-request state, reach for `@warlock.js/cache` or a database.
|
|
60
|
+
- **Cross-thread context.** Worker threads don't share AsyncLocalStorage with the main thread. Serialize the data you need across the boundary and re-enter on the other side.
|
|
61
|
+
- **Browser context.** Server-side only. The browser equivalent is React Context or a state library.
|
|
62
|
+
- **Implicit context for non-async code.** If your call stack has no `await`, the storage works but there's no propagation benefit — just pass the value as a parameter.
|
|
63
|
+
|
|
64
|
+
## See also
|
|
65
|
+
|
|
66
|
+
- [`@warlock.js/core/overview/SKILL.md`](@warlock.js/core/overview/SKILL.md) — the parent framework; `context` is one of its foundation packages.
|
|
67
|
+
- `mongez-agent-kit-authoring-skills` (load via agent-kit sync) — how this `overview/SKILL.md` becomes the front-door skill in `.claude/skills/warlock-js-context-overview/`.
|
package/cjs/base-context.d.ts
DELETED
|
@@ -1,96 +0,0 @@
|
|
|
1
|
-
/// <reference types="node" />
|
|
2
|
-
import { AsyncLocalStorage } from "async_hooks";
|
|
3
|
-
/**
|
|
4
|
-
* Base class for all AsyncLocalStorage-based contexts
|
|
5
|
-
*
|
|
6
|
-
* Provides a consistent API for managing context across async operations.
|
|
7
|
-
* All framework contexts (request, storage, database) extend this class.
|
|
8
|
-
*
|
|
9
|
-
* @template TStore - The type of data stored in context
|
|
10
|
-
*
|
|
11
|
-
* @example
|
|
12
|
-
* ```typescript
|
|
13
|
-
* interface MyContextStore {
|
|
14
|
-
* userId: string;
|
|
15
|
-
* tenant: string;
|
|
16
|
-
* }
|
|
17
|
-
*
|
|
18
|
-
* class MyContext extends Context<MyContextStore> {}
|
|
19
|
-
* const myContext = new MyContext();
|
|
20
|
-
*
|
|
21
|
-
* // Use it
|
|
22
|
-
* await myContext.run({ userId: '123', tenant: 'acme' }, async () => {
|
|
23
|
-
* const userId = myContext.get('userId'); // '123'
|
|
24
|
-
* });
|
|
25
|
-
* ```
|
|
26
|
-
*/
|
|
27
|
-
export declare abstract class Context<TStore extends Record<string, any>> {
|
|
28
|
-
protected readonly storage: AsyncLocalStorage<TStore>;
|
|
29
|
-
/**
|
|
30
|
-
* Run a callback within a new context
|
|
31
|
-
*
|
|
32
|
-
* Creates a new async context with the provided store data.
|
|
33
|
-
* All operations within the callback will have access to this context.
|
|
34
|
-
*
|
|
35
|
-
* @param store - Initial context data
|
|
36
|
-
* @param callback - Async function to execute
|
|
37
|
-
* @returns Result of the callback
|
|
38
|
-
*/
|
|
39
|
-
run<T>(store: TStore, callback: () => Promise<T>): Promise<T>;
|
|
40
|
-
/**
|
|
41
|
-
* Enter a new context without a callback
|
|
42
|
-
*
|
|
43
|
-
* Useful for middleware where you want to set context for the rest of the request.
|
|
44
|
-
* Unlike `run()`, this doesn't require a callback.
|
|
45
|
-
*
|
|
46
|
-
* @param store - Context data to set
|
|
47
|
-
*/
|
|
48
|
-
enter(store: TStore): void;
|
|
49
|
-
/**
|
|
50
|
-
* Update the current context
|
|
51
|
-
*
|
|
52
|
-
* Merges new data into existing context, or enters new context if none exists.
|
|
53
|
-
*
|
|
54
|
-
* @param updates - Partial context data to merge
|
|
55
|
-
*/
|
|
56
|
-
update(updates: Partial<TStore>): void;
|
|
57
|
-
/**
|
|
58
|
-
* Get the current context store
|
|
59
|
-
*
|
|
60
|
-
* @returns Current context or undefined if not in context
|
|
61
|
-
*/
|
|
62
|
-
getStore(): TStore | undefined;
|
|
63
|
-
/**
|
|
64
|
-
* Get a specific value from context
|
|
65
|
-
*
|
|
66
|
-
* @param key - Key to retrieve
|
|
67
|
-
* @returns Value or undefined
|
|
68
|
-
*/
|
|
69
|
-
get<K extends keyof TStore>(key: K): TStore[K] | undefined;
|
|
70
|
-
/**
|
|
71
|
-
* Set a specific value in context
|
|
72
|
-
*
|
|
73
|
-
* @param key - Key to set
|
|
74
|
-
* @param value - Value to store
|
|
75
|
-
*/
|
|
76
|
-
set<K extends keyof TStore>(key: K, value: TStore[K]): void;
|
|
77
|
-
/**
|
|
78
|
-
* Clear the context
|
|
79
|
-
*/
|
|
80
|
-
clear(): void;
|
|
81
|
-
/**
|
|
82
|
-
* Check if currently in a context
|
|
83
|
-
*/
|
|
84
|
-
hasContext(): boolean;
|
|
85
|
-
/**
|
|
86
|
-
* Build the initial store for this context
|
|
87
|
-
*
|
|
88
|
-
* Override this method to provide custom initialization logic.
|
|
89
|
-
* Called by ContextManager.buildStores() for each registered context.
|
|
90
|
-
*
|
|
91
|
-
* @param payload - Generic payload (e.g., { request, response } for HTTP contexts)
|
|
92
|
-
* @returns Initial store data
|
|
93
|
-
*/
|
|
94
|
-
abstract buildStore(payload?: Record<string, any>): TStore;
|
|
95
|
-
}
|
|
96
|
-
//# sourceMappingURL=base-context.d.ts.map
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"base-context.d.ts","sourceRoot":"","sources":["../src/base-context.ts"],"names":[],"mappings":";AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,8BAAsB,OAAO,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAC9D,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC,MAAM,CAAC,CAAmC;IAExF;;;;;;;;;OASG;IACI,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAIpE;;;;;;;OAOG;IACI,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAIjC;;;;;;OAMG;IACI,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG,IAAI;IAU7C;;;;OAIG;IACI,QAAQ,IAAI,MAAM,GAAG,SAAS;IAIrC;;;;;OAKG;IACI,GAAG,CAAC,CAAC,SAAS,MAAM,MAAM,EAAE,GAAG,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,SAAS;IAIjE;;;;;OAKG;IACI,GAAG,CAAC,CAAC,SAAS,MAAM,MAAM,EAAE,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,GAAG,IAAI;IAIlE;;OAEG;IACI,KAAK,IAAI,IAAI;IAIpB;;OAEG;IACI,UAAU,IAAI,OAAO;IAI5B;;;;;;;;OAQG;aACa,UAAU,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM;CAClE"}
|
package/cjs/base-context.js
DELETED
|
@@ -1,105 +0,0 @@
|
|
|
1
|
-
'use strict';var async_hooks=require('async_hooks');/**
|
|
2
|
-
* Base class for all AsyncLocalStorage-based contexts
|
|
3
|
-
*
|
|
4
|
-
* Provides a consistent API for managing context across async operations.
|
|
5
|
-
* All framework contexts (request, storage, database) extend this class.
|
|
6
|
-
*
|
|
7
|
-
* @template TStore - The type of data stored in context
|
|
8
|
-
*
|
|
9
|
-
* @example
|
|
10
|
-
* ```typescript
|
|
11
|
-
* interface MyContextStore {
|
|
12
|
-
* userId: string;
|
|
13
|
-
* tenant: string;
|
|
14
|
-
* }
|
|
15
|
-
*
|
|
16
|
-
* class MyContext extends Context<MyContextStore> {}
|
|
17
|
-
* const myContext = new MyContext();
|
|
18
|
-
*
|
|
19
|
-
* // Use it
|
|
20
|
-
* await myContext.run({ userId: '123', tenant: 'acme' }, async () => {
|
|
21
|
-
* const userId = myContext.get('userId'); // '123'
|
|
22
|
-
* });
|
|
23
|
-
* ```
|
|
24
|
-
*/
|
|
25
|
-
class Context {
|
|
26
|
-
storage = new async_hooks.AsyncLocalStorage();
|
|
27
|
-
/**
|
|
28
|
-
* Run a callback within a new context
|
|
29
|
-
*
|
|
30
|
-
* Creates a new async context with the provided store data.
|
|
31
|
-
* All operations within the callback will have access to this context.
|
|
32
|
-
*
|
|
33
|
-
* @param store - Initial context data
|
|
34
|
-
* @param callback - Async function to execute
|
|
35
|
-
* @returns Result of the callback
|
|
36
|
-
*/
|
|
37
|
-
run(store, callback) {
|
|
38
|
-
return this.storage.run(store, callback);
|
|
39
|
-
}
|
|
40
|
-
/**
|
|
41
|
-
* Enter a new context without a callback
|
|
42
|
-
*
|
|
43
|
-
* Useful for middleware where you want to set context for the rest of the request.
|
|
44
|
-
* Unlike `run()`, this doesn't require a callback.
|
|
45
|
-
*
|
|
46
|
-
* @param store - Context data to set
|
|
47
|
-
*/
|
|
48
|
-
enter(store) {
|
|
49
|
-
this.storage.enterWith(store);
|
|
50
|
-
}
|
|
51
|
-
/**
|
|
52
|
-
* Update the current context
|
|
53
|
-
*
|
|
54
|
-
* Merges new data into existing context, or enters new context if none exists.
|
|
55
|
-
*
|
|
56
|
-
* @param updates - Partial context data to merge
|
|
57
|
-
*/
|
|
58
|
-
update(updates) {
|
|
59
|
-
const current = this.storage.getStore();
|
|
60
|
-
if (current) {
|
|
61
|
-
Object.assign(current, updates);
|
|
62
|
-
}
|
|
63
|
-
else {
|
|
64
|
-
this.enter(updates);
|
|
65
|
-
}
|
|
66
|
-
}
|
|
67
|
-
/**
|
|
68
|
-
* Get the current context store
|
|
69
|
-
*
|
|
70
|
-
* @returns Current context or undefined if not in context
|
|
71
|
-
*/
|
|
72
|
-
getStore() {
|
|
73
|
-
return this.storage.getStore();
|
|
74
|
-
}
|
|
75
|
-
/**
|
|
76
|
-
* Get a specific value from context
|
|
77
|
-
*
|
|
78
|
-
* @param key - Key to retrieve
|
|
79
|
-
* @returns Value or undefined
|
|
80
|
-
*/
|
|
81
|
-
get(key) {
|
|
82
|
-
return this.storage.getStore()?.[key];
|
|
83
|
-
}
|
|
84
|
-
/**
|
|
85
|
-
* Set a specific value in context
|
|
86
|
-
*
|
|
87
|
-
* @param key - Key to set
|
|
88
|
-
* @param value - Value to store
|
|
89
|
-
*/
|
|
90
|
-
set(key, value) {
|
|
91
|
-
this.update({ [key]: value });
|
|
92
|
-
}
|
|
93
|
-
/**
|
|
94
|
-
* Clear the context
|
|
95
|
-
*/
|
|
96
|
-
clear() {
|
|
97
|
-
this.storage.enterWith({});
|
|
98
|
-
}
|
|
99
|
-
/**
|
|
100
|
-
* Check if currently in a context
|
|
101
|
-
*/
|
|
102
|
-
hasContext() {
|
|
103
|
-
return this.storage.getStore() !== undefined;
|
|
104
|
-
}
|
|
105
|
-
}exports.Context=Context;//# sourceMappingURL=base-context.js.map
|
package/cjs/base-context.js.map
DELETED
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"base-context.js","sources":["../src/base-context.ts"],"sourcesContent":[null],"names":["AsyncLocalStorage"],"mappings":"oDAEA;;;;;;;;;;;;;;;;;;;;;;;AAuBG;MACmB,OAAO,CAAA;AACR,IAAA,OAAO,GAA8B,IAAIA,6BAAiB,EAAU,CAAC;AAExF;;;;;;;;;AASG;IACI,GAAG,CAAI,KAAa,EAAE,QAA0B,EAAA;QACrD,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;KAC1C;AAED;;;;;;;AAOG;AACI,IAAA,KAAK,CAAC,KAAa,EAAA;AACxB,QAAA,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;KAC/B;AAED;;;;;;AAMG;AACI,IAAA,MAAM,CAAC,OAAwB,EAAA;QACpC,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;AAExC,QAAA,IAAI,OAAO,EAAE;AACX,YAAA,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;AACjC,SAAA;AAAM,aAAA;AACL,YAAA,IAAI,CAAC,KAAK,CAAC,OAAiB,CAAC,CAAC;AAC/B,SAAA;KACF;AAED;;;;AAIG;IACI,QAAQ,GAAA;AACb,QAAA,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;KAChC;AAED;;;;;AAKG;AACI,IAAA,GAAG,CAAyB,GAAM,EAAA;QACvC,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,GAAG,GAAG,CAAC,CAAC;KACvC;AAED;;;;;AAKG;IACI,GAAG,CAAyB,GAAM,EAAE,KAAgB,EAAA;QACzD,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,GAAG,GAAG,KAAK,EAAS,CAAC,CAAC;KACtC;AAED;;AAEG;IACI,KAAK,GAAA;AACV,QAAA,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,EAAY,CAAC,CAAC;KACtC;AAED;;AAEG;IACI,UAAU,GAAA;QACf,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,KAAK,SAAS,CAAC;KAC9C;AAYF"}
|