@hile/context 3.0.1

package/README.md

@@ -0,0 +1,161 @@
+# @hile/context
+
+Typed async context propagation primitives for Hile applications.
+
+`@hile/context` does not define business fields. It stores whatever context shape the application declares and keeps that data isolated across async work. Adapters can seed context from HTTP, model pipelines, logger bindings, and `@hile/micro` calls without adding fields to business payloads.
+
+## Install
+
+```bash
+pnpm add @hile/context
+```
+
+## Quick Start
+
+```typescript
+import { getContext, runWithContext } from '@hile/context'
+
+type AppContext = {
+  shopId: string
+  memberId: string
+  channel: 'web' | 'wechat'
+}
+
+await runWithContext<AppContext>({
+  shopId: 'shop-1',
+  memberId: 'member-1',
+  channel: 'web',
+}, async () => {
+  const context = getContext<AppContext>()
+  console.log(context.shopId)
+})
+```
+
+Outside `runWithContext()`, `getContext()` returns an empty object.
+
+## Core API
+
+### runWithContext(context, callback, options?)
+
+Runs `callback` inside an `AsyncLocalStorage` scope.
+
+```typescript
+await runWithContext<AppContext>({ shopId: 'shop-1' }, async () => {
+  await doWork()
+})
+```
+
+Nested calls merge with the parent context by default:
+
+```typescript
+await runWithContext<AppContext>({ shopId: 'shop-1', channel: 'web' }, async () => {
+  await runWithContext<AppContext>({ channel: 'wechat' }, async () => {
+    getContext<AppContext>() // { shopId: 'shop-1', channel: 'wechat' }
+  })
+})
+```
+
+Pass `{ merge: false }` to replace the parent context.
+
+### getContext()
+
+Returns a readonly shallow snapshot of the active context. Mutating the returned object does not mutate the store.
+
+### snapshotContext()
+
+Returns a readonly shallow snapshot for propagation. Cross-process transports should only put JSON-serializable values into context.
+
+### requireContext(keys)
+
+Asserts that selected application-defined keys are present.
+
+```typescript
+const context = requireContext<AppContext>(['shopId', 'channel'])
+```
+
+It throws `MissingContextError` when a selected key is missing.
+
+## HTTP Adapter
+
+`contextHttp()` is mapping-only. The package does not prescribe header names.
+
+```typescript
+import { contextHttp } from '@hile/context'
+
+app.use(contextHttp<AppContext, Koa.Context>({
+  read: ctx => ({
+    shopId: ctx.get('x-shop'),
+    channel: ctx.get('x-channel') as AppContext['channel'],
+  }),
+  write: (context, ctx) => {
+    if (context.shopId) ctx.set('x-current-shop', context.shopId)
+  },
+}))
+```
+
+## Model Adapter
+
+```typescript
+import { contextModel, requireContextModel } from '@hile/context'
+import { defineModel } from '@hile/model'
+
+const model = defineModel({
+  pipelines: [
+    contextModel<{ store: string; source: 'web' | 'wechat' }, AppContext>({
+      read: input => ({
+        shopId: input.store,
+        channel: input.source,
+      }),
+    }),
+    requireContextModel<{ store: string; source: 'web' | 'wechat' }, AppContext>(['shopId']),
+  ],
+  async main(input) {
+    return getContext<AppContext>()
+  },
+})
+```
+
+## Logger Binding
+
+Logger bindings are opt-in. Without `pick` or `map`, no context fields are logged.
+
+```typescript
+import { withContextLogger } from '@hile/context'
+
+const logger = withContextLogger<AppContext>(baseLogger, {
+  pick: ['shopId', 'channel'],
+})
+
+logger.info({ event: 'checkout' }, 'checkout created')
+```
+
+## @hile/micro Propagation
+
+When `@hile/micro` depends on `@hile/context`, calls made inside `runWithContext()` propagate the current context through message metadata:
+
+```typescript
+await runWithContext<AppContext>({ shopId: 'shop-1', channel: 'web' }, async () => {
+  await app.call('inventory', '/reserve', { sku: 'sku-1' })
+})
+```
+
+The receiving handler can call `getContext<AppContext>()`. The business `data` payload remains unchanged; context travels separately in `metadata.context`.
+
+## Boundaries
+
+- No field names are built into this package.
+- Context is a request/work-unit scope, not a process-level configuration store.
+- `getContext()` returns a shallow snapshot, not a deep clone.
+- Cross-process propagation should use JSON-serializable values.
+- Logger integration logs only fields selected by the application.
+
+## Testing
+
+```bash
+pnpm --filter @hile/context test
+pnpm --filter @hile/context build
+```
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: context
+description: Use when implementing typed async context propagation, request/work-unit context, HTTP context mapping, model pipeline context, logger context bindings, or @hile/micro context propagation.
+---
+
+# Context
+
+Use `@hile/context` when a Hile app needs request/work-unit data to flow through async code and microservice calls without passing it through every function argument.
+
+## Core Rule
+
+Never bake business fields into the package. The library owns storage and propagation only; applications own the context shape.
+
+```typescript
+type AppContext = {
+  shopId: string
+  channel: 'web' | 'wechat'
+}
+
+await runWithContext<AppContext>({ shopId, channel }, async () => {
+  await doWork()
+})
+```
+
+## Design Boundaries
+
+- Core storage is an `AsyncLocalStorage<Record<string, unknown>>`.
+- `getContext()` and `snapshotContext()` return readonly shallow snapshots.
+- Nested `runWithContext()` calls merge by default; pass `{ merge: false }` to replace.
+- `requireContext(keys)` validates only keys selected by the application.
+- Do not add fixed fields like organization, user, or request dimensions to core types.
+- Cross-process propagation should use JSON-serializable context values.
+
+## Adapters
+
+- Use `contextHttp({ read, write })` to map arbitrary HTTP request/response details to and from context. The package must not prescribe header names.
+- Use `contextModel({ read })` inside `@hile/model` pipelines to seed context from model input.
+- Use `requireContextModel(keys)` to enforce selected application-owned keys inside model pipelines.
+- Use `withContextLogger(logger, { pick })` or `{ map }` to opt into logger bindings. Never log the whole context by default.
+- `@hile/micro` propagates context in `metadata.context`; business payloads remain unchanged.

package/dist/errors.d.ts

@@ -0,0 +1,4 @@
+export declare class MissingContextError extends Error {
+    readonly keys: readonly string[];
+    constructor(keys: readonly string[]);
+}

package/dist/errors.js

@@ -0,0 +1,9 @@
+export class MissingContextError extends Error {
+    keys;
+    constructor(keys) {
+        super(`Missing required context keys: ${keys.join(', ')}`);
+        this.name = 'MissingContextError';
+        this.keys = [...keys];
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}

package/dist/http.d.ts

@@ -0,0 +1,7 @@
+import type { ContextData, ContextInput, MaybePromise, RunWithContextOptions } from './types';
+export type ContextHttpOptions<TContext extends object = ContextData, THttpContext = unknown> = RunWithContextOptions & {
+    read: (ctx: THttpContext) => MaybePromise<ContextInput<TContext>>;
+    write?: (context: Readonly<Partial<TContext>>, ctx: THttpContext) => MaybePromise<void>;
+};
+export type ContextHttpMiddleware<THttpContext = unknown> = (ctx: THttpContext, next: () => Promise<unknown>) => Promise<void>;
+export declare function contextHttp<TContext extends object = ContextData, THttpContext = unknown>(options: ContextHttpOptions<TContext, THttpContext>): ContextHttpMiddleware<THttpContext>;

package/dist/http.js

@@ -0,0 +1,26 @@
+import { getContext, runWithContext } from './store.js';
+export function contextHttp(options) {
+    return async (ctx, next) => {
+        const context = await options.read(ctx);
+        await runWithContext(context, async () => {
+            let nextError;
+            try {
+                await next();
+            }
+            catch (err) {
+                nextError = err;
+            }
+            if (options.write) {
+                try {
+                    await options.write(getContext(), ctx);
+                }
+                catch (writeError) {
+                    if (nextError === undefined)
+                        throw writeError;
+                }
+            }
+            if (nextError !== undefined)
+                throw nextError;
+        }, { merge: options.merge });
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from './errors.js';
+export * from './http.js';
+export * from './logger.js';
+export * from './model.js';
+export * from './store.js';
+export type * from './types.js';

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from './errors.js';
+export * from './http.js';
+export * from './logger.js';
+export * from './model.js';
+export * from './store.js';

package/dist/logger.d.ts

@@ -0,0 +1,10 @@
+import type { ContextData, ContextKey, ContextSnapshot } from './types';
+export type ContextLoggerOptions<TContext extends object = ContextData> = {
+    pick?: readonly ContextKey<TContext>[];
+    map?: (context: ContextSnapshot<TContext>) => Record<string, unknown>;
+};
+export type ContextLoggerLike = object & {
+    child?: (bindings: Record<string, unknown>) => unknown;
+};
+export declare function contextBindings<TContext extends object = ContextData>(options?: ContextLoggerOptions<TContext>, context?: ContextSnapshot<TContext>): Record<string, unknown>;
+export declare function withContextLogger<TContext extends object = ContextData, TLogger extends object = any>(logger: TLogger, options?: ContextLoggerOptions<TContext>): TLogger;

package/dist/logger.js

@@ -0,0 +1,50 @@
+import { getContext } from './store.js';
+const LOG_METHODS = new Set(['trace', 'debug', 'info', 'warn', 'error', 'fatal']);
+export function contextBindings(options = {}, context = getContext()) {
+    const bindings = {};
+    const source = context;
+    for (const key of options.pick ?? []) {
+        if (source[key] !== undefined) {
+            bindings[key] = source[key];
+        }
+    }
+    if (options.map) {
+        Object.assign(bindings, options.map(context));
+    }
+    return bindings;
+}
+export function withContextLogger(logger, options = {}) {
+    return new Proxy(logger, {
+        get(target, property, receiver) {
+            const value = Reflect.get(target, property, receiver);
+            if (typeof property !== 'string' || !LOG_METHODS.has(property) || typeof value !== 'function') {
+                return typeof value === 'function' ? value.bind(target) : value;
+            }
+            return (...args) => {
+                const bindings = contextBindings(options);
+                if (Object.keys(bindings).length === 0) {
+                    return value.apply(target, args);
+                }
+                const targetLogger = target;
+                if (typeof targetLogger.child === 'function') {
+                    const child = targetLogger.child(bindings);
+                    const method = child[property];
+                    if (typeof method === 'function') {
+                        return method.apply(child, args);
+                    }
+                }
+                const [first, ...rest] = args;
+                if (isMergeableLogObject(first)) {
+                    return value.call(target, { ...bindings, ...first }, ...rest);
+                }
+                return value.call(target, bindings, ...args);
+            };
+        },
+    });
+}
+function isMergeableLogObject(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        !Array.isArray(value) &&
+        !(value instanceof Error));
+}

package/dist/model.d.ts

@@ -0,0 +1,7 @@
+import type { PipelineContext, PipelineMiddleware } from '@hile/model';
+import type { ContextData, ContextInput, ContextKey, MaybePromise, RunWithContextOptions } from './types';
+export type ContextModelOptions<TInput extends object = Record<string, unknown>, TContext extends object = ContextData> = RunWithContextOptions & {
+    read: (input: TInput, ctx: PipelineContext<TInput>) => MaybePromise<ContextInput<TContext>>;
+};
+export declare function contextModel<TInput extends object = Record<string, unknown>, TContext extends object = ContextData>(options: ContextModelOptions<TInput, TContext>): PipelineMiddleware<TInput>;
+export declare function requireContextModel<TInput extends object = Record<string, unknown>, TContext extends object = ContextData>(keys: readonly ContextKey<TContext>[]): PipelineMiddleware<TInput>;

package/dist/model.js

@@ -0,0 +1,13 @@
+import { requireContext, runWithContext } from './store.js';
+export function contextModel(options) {
+    return async (ctx, next) => {
+        const context = await options.read(ctx.args, ctx);
+        await runWithContext(context, () => next(), { merge: options.merge });
+    };
+}
+export function requireContextModel(keys) {
+    return async (_ctx, next) => {
+        requireContext(keys);
+        await next();
+    };
+}

package/dist/store.d.ts

@@ -0,0 +1,11 @@
+import type { ContextData, ContextInput, ContextKey, ContextSnapshot, RunWithContextOptions } from './types';
+export declare function isContextData(value: unknown): value is ContextData;
+export declare function hasContext(): boolean;
+export declare function getContext<TContext extends object = ContextData>(): ContextSnapshot<TContext>;
+export declare function snapshotContext<TContext extends object = ContextData>(): ContextSnapshot<TContext>;
+export declare function runWithContext<TContext extends object = ContextData, TResult = any>(context: ContextInput<TContext>, callback: () => TResult, options?: RunWithContextOptions): TResult;
+type RequiredContext<TContext extends object, TKey extends ContextKey<TContext>> = Readonly<Partial<TContext>> & {
+    readonly [K in TKey]-?: Exclude<TContext[K], undefined>;
+};
+export declare function requireContext<TContext extends object = ContextData, const TKeys extends readonly ContextKey<TContext>[] = readonly ContextKey<TContext>[]>(keys: TKeys): RequiredContext<TContext, TKeys[number]>;
+export {};

package/dist/store.js

@@ -0,0 +1,38 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { MissingContextError } from './errors.js';
+const storage = new AsyncLocalStorage();
+function toStore(context) {
+    if (!isContextData(context))
+        return {};
+    return { ...context };
+}
+function freezeSnapshot(store) {
+    return Object.freeze({ ...(store ?? {}) });
+}
+export function isContextData(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function hasContext() {
+    return storage.getStore() !== undefined;
+}
+export function getContext() {
+    return freezeSnapshot(storage.getStore());
+}
+export function snapshotContext() {
+    return getContext();
+}
+export function runWithContext(context, callback, options = {}) {
+    const parent = storage.getStore();
+    const current = toStore(context);
+    const next = options.merge === false ? current : { ...(parent ?? {}), ...current };
+    return storage.run(next, callback);
+}
+export function requireContext(keys) {
+    const context = getContext();
+    const source = context;
+    const missing = keys.filter(key => source[key] === undefined);
+    if (missing.length > 0) {
+        throw new MissingContextError(missing);
+    }
+    return context;
+}

package/dist/types.d.ts

@@ -0,0 +1,11 @@
+export type ContextData = Record<string, unknown>;
+export type ContextInput<TContext extends object = ContextData> = Readonly<Partial<TContext>>;
+export type ContextSnapshot<TContext extends object = ContextData> = Readonly<Partial<TContext>>;
+export type ContextKey<TContext extends object = ContextData> = Extract<keyof TContext, string>;
+export type MaybePromise<T> = T | Promise<T>;
+export type RunWithContextOptions = {
+    /**
+     * Merge with the current async context. Defaults to true.
+     */
+    merge?: boolean;
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@hile/context",
+  "version": "3.0.1",
+  "description": "Typed async context propagation primitives for Hile applications",
+  "type": "module",
+  "main": "./dist/index.js",
+  "scripts": {
+    "build": "tsc -b && fix-esm-import-path --preserve-import-type ./dist",
+    "dev": "tsc -b --watch",
+    "test": "vitest run"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "SKILL.md"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.1",
+    "fix-esm-import-path": "^1.10.3",
+    "vitest": "^4.0.18"
+  },
+  "dependencies": {
+    "@hile/model": "^3.0.1"
+  },
+  "gitHead": "14b55afba0e9af80a782eaa84f6f48c1e66861a1"
+}