@warlock.js/context 4.0.174 → 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.
Files changed (42) hide show
  1. package/cjs/index.cjs +239 -0
  2. package/cjs/index.cjs.map +1 -0
  3. package/esm/base-context.d.mts +99 -0
  4. package/esm/base-context.d.mts.map +1 -0
  5. package/esm/base-context.mjs +110 -0
  6. package/esm/base-context.mjs.map +1 -0
  7. package/esm/context-manager.d.mts +106 -0
  8. package/esm/context-manager.d.mts.map +1 -0
  9. package/esm/context-manager.mjs +128 -0
  10. package/esm/context-manager.mjs.map +1 -0
  11. package/esm/index.d.mts +3 -0
  12. package/esm/index.mjs +4 -0
  13. package/llms-full.txt +404 -0
  14. package/llms.txt +11 -0
  15. package/package.json +42 -30
  16. package/skills/define-context/SKILL.md +158 -0
  17. package/skills/orchestrate-contexts/SKILL.md +161 -0
  18. package/skills/overview/SKILL.md +67 -0
  19. package/cjs/base-context.d.ts +0 -96
  20. package/cjs/base-context.d.ts.map +0 -1
  21. package/cjs/base-context.js +0 -105
  22. package/cjs/base-context.js.map +0 -1
  23. package/cjs/context-manager.d.ts +0 -102
  24. package/cjs/context-manager.d.ts.map +0 -1
  25. package/cjs/context-manager.js +0 -132
  26. package/cjs/context-manager.js.map +0 -1
  27. package/cjs/index.d.ts +0 -3
  28. package/cjs/index.d.ts.map +0 -1
  29. package/cjs/index.js +0 -1
  30. package/cjs/index.js.map +0 -1
  31. package/esm/base-context.d.ts +0 -96
  32. package/esm/base-context.d.ts.map +0 -1
  33. package/esm/base-context.js +0 -105
  34. package/esm/base-context.js.map +0 -1
  35. package/esm/context-manager.d.ts +0 -102
  36. package/esm/context-manager.d.ts.map +0 -1
  37. package/esm/context-manager.js +0 -132
  38. package/esm/context-manager.js.map +0 -1
  39. package/esm/index.d.ts +0 -3
  40. package/esm/index.d.ts.map +0 -1
  41. package/esm/index.js +0 -1
  42. 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/`.
@@ -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"}
@@ -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
@@ -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"}