@nwire/test-kit 0.12.0 → 0.13.0

package/dist/harness-extensions.js

@@ -19,7 +19,7 @@
  * and the optional deps (`@nwire/auth`, `@nwire/rbac`, `koa`) stay opt-in.
  */
 import supertest from "supertest";
-import { forgeDispatcher } from "@nwire/forge";
+import { FORGE_ACTION_RUNNER_BINDING, FORGE_QUERY_RUNNER_BINDING, } from "@nwire/forge";
 /**
  * Return a thin proxy that pins `envelope.user` (and `envelope.userId`,
  * `envelope.tenant` derived from the user) on every dispatch/query.
@@ -33,11 +33,12 @@ export function asUser(harness, user) {
     // `user` too, which is on MessageEnvelope but not on the public dispatch
     // overload. Going through runtime.dispatch with a hand-seeded envelope
     // keeps the type contract honest without widening the public Harness API.
-    const dispatcher = forgeDispatcher(harness.app);
+    const actionRunner = harness.app.container.resolve(FORGE_ACTION_RUNNER_BINDING);
+    const queryRunner = harness.app.container.resolve(FORGE_QUERY_RUNNER_BINDING);
     return {
         async dispatch(action, input, envelope) {
             if (!user)
-                return dispatcher.dispatch(action, input);
+                return actionRunner.dispatch(action, input);
             const { seedEnvelope } = await import("@nwire/envelope");
             const seeded = seedEnvelope({
                 tenant: envelope?.tenant ?? user.tenant,
@@ -45,10 +46,10 @@ export function asUser(harness, user) {
                 user,
                 correlationId: envelope?.correlationId,
             });
-            return dispatcher.dispatch(action, input, seeded);
+            return actionRunner.dispatch(action, input, seeded);
         },
         async query(queryDef, input, tenant) {
-            return dispatcher.query(queryDef.name, input, tenant ?? user?.tenant ?? "");
+            return queryRunner.run(queryDef.name, input, tenant ?? user?.tenant ?? "");
         },
     };
 }

package/dist/harness.d.ts

@@ -3,7 +3,7 @@
  * dispatch helpers, idle-wait, and a buffered telemetry probe.
  *
  *   const app = createApp({ appName: "submissions",
- *     plugins: [createForgePlugin({ handlers, actors })] });
+ *     handlers, plugins: [...forgePlugins({ actors })] });
  *   const h = await harness({ app });
  *   await h.dispatch(submitAnswer, { … });
  *   await h.idle();

package/dist/harness.js

@@ -3,21 +3,22 @@
  * dispatch helpers, idle-wait, and a buffered telemetry probe.
  *
  *   const app = createApp({ appName: "submissions",
- *     plugins: [createForgePlugin({ handlers, actors })] });
+ *     handlers, plugins: [...forgePlugins({ actors })] });
  *   const h = await harness({ app });
  *   await h.dispatch(submitAnswer, { … });
  *   await h.idle();
  *   expect(h.telemetry.count("event.published")).toBeGreaterThan(0);
  *   await h.stop();
  */
-import { forgeDispatcher } from "@nwire/forge";
+import { FORGE_ACTION_RUNNER_BINDING, FORGE_QUERY_RUNNER_BINDING } from "@nwire/forge";
 import { TelemetryProbe } from "./telemetry-probe.js";
 export async function harness(options) {
     const app = options.app;
     const probe = new TelemetryProbe();
     const unsubscribe = app.runtime.onTelemetry((rec) => probe.record(rec));
     await app.start();
-    const dispatcher = forgeDispatcher(app);
+    const actionRunner = app.container.resolve(FORGE_ACTION_RUNNER_BINDING);
+    const queryRunner = app.container.resolve(FORGE_QUERY_RUNNER_BINDING);
     let pending = 0;
     let lastRecordAt = Date.now();
     app.runtime.onTelemetry(() => {
@@ -36,16 +37,16 @@ export async function harness(options) {
                         userId: envelope.userId,
                         correlationId: envelope.correlationId,
                     });
-                    return await dispatcher.dispatch(action, input, seeded);
+                    return await actionRunner.dispatch(action, input, seeded);
                 }
-                return await dispatcher.dispatch(action, input);
+                return await actionRunner.dispatch(action, input);
             }
             finally {
                 pending--;
             }
         },
         async query(queryDef, input, tenant = "") {
-            return dispatcher.query(queryDef.name, input, tenant);
+            return queryRunner.run(queryDef.name, input, tenant);
         },
         async idle(graceMs = 25, timeoutMs = 5000) {
             const deadline = Date.now() + timeoutMs;

package/dist/invoke.d.ts

@@ -0,0 +1,51 @@
+/**
+ * `invoke(handler, input)` / `invokeQuery(query, input)` — exercise a single
+ * handler or query without hand-assembling an app or a ctx.
+ *
+ * A read or a command always needs a ctx (container + tenant + observability),
+ * so there is no ctx-less call path in production — but in a unit test you
+ * shouldn't have to build one. `invoke` boots a minimal in-memory forge app
+ * around just your handler (plus any deps it reaches for), dispatches once
+ * through the real pipeline, returns the result, and tears the app down.
+ *
+ *   const ev = await invoke(submitAnswer, { id: "a-1" });
+ *   const user = await invoke(createUser, { email }, { providers: { db } });
+ *   const rows = await invokeQuery(listUsers, { tenantId }, { providers: { db } });
+ *
+ * Pass `actors` / `projections` / `queries` / `handlers` when the handler
+ * reaches for them via `ctx.actor` / `ctx.query` / `ctx.send`; pass `providers`
+ * for DI bindings it resolves. For multi-dispatch scenarios or telemetry
+ * assertions, use `harness({ app })` instead.
+ */
+import { type ActionDefinition, type ActionInput, type ActionResult, type QueryDefinition } from "@nwire/forge";
+import type { ZodTypeAny } from "@nwire/messages";
+export interface InvokeOptions {
+    /** DI bindings the handler resolves via `ctx.resolve(name)`. */
+    readonly providers?: Record<string, unknown>;
+    /** Extra handlers the target reaches via `ctx.send` / `ctx.execute`. */
+    readonly handlers?: readonly ActionDefinition<any>[];
+    /** Actors the target reads via `ctx.actor`. */
+    readonly actors?: readonly any[];
+    /** Projections backing queries / folded by emitted events. */
+    readonly projections?: readonly any[];
+    /** Queries the target reads via `ctx.query`. */
+    readonly queries?: readonly QueryDefinition<any, any, any>[];
+    /** Envelope seed — tenant / userId / correlationId for the dispatch. */
+    readonly envelope?: {
+        tenant?: string;
+        userId?: string;
+        correlationId?: string;
+    };
+}
+/**
+ * Boot a minimal app around `handler`, dispatch `input` once through the real
+ * forge pipeline (validation, hooks, retry, event publish), return the
+ * handler's result, and stop the app.
+ */
+export declare function invoke<TSchema extends ZodTypeAny>(action: ActionDefinition<TSchema>, input: ActionInput<ActionDefinition<TSchema>>, opts?: InvokeOptions): Promise<ActionResult<ActionDefinition<TSchema>>>;
+/**
+ * Boot a minimal app around `query`, run it once (projection- or handler-form),
+ * return the result, and stop the app. Pass `projections` for a projection-
+ * backed query and `providers` for a handler-form query's DI deps.
+ */
+export declare function invokeQuery<TResult = unknown>(query: QueryDefinition<any, any, TResult>, input: unknown, opts?: InvokeOptions): Promise<TResult>;

package/dist/invoke.js

@@ -0,0 +1,87 @@
+/**
+ * `invoke(handler, input)` / `invokeQuery(query, input)` — exercise a single
+ * handler or query without hand-assembling an app or a ctx.
+ *
+ * A read or a command always needs a ctx (container + tenant + observability),
+ * so there is no ctx-less call path in production — but in a unit test you
+ * shouldn't have to build one. `invoke` boots a minimal in-memory forge app
+ * around just your handler (plus any deps it reaches for), dispatches once
+ * through the real pipeline, returns the result, and tears the app down.
+ *
+ *   const ev = await invoke(submitAnswer, { id: "a-1" });
+ *   const user = await invoke(createUser, { email }, { providers: { db } });
+ *   const rows = await invokeQuery(listUsers, { tenantId }, { providers: { db } });
+ *
+ * Pass `actors` / `projections` / `queries` / `handlers` when the handler
+ * reaches for them via `ctx.actor` / `ctx.query` / `ctx.send`; pass `providers`
+ * for DI bindings it resolves. For multi-dispatch scenarios or telemetry
+ * assertions, use `harness({ app })` instead.
+ */
+import { createApp } from "@nwire/app";
+import { forgePlugins, FORGE_ACTION_RUNNER_BINDING, FORGE_QUERY_RUNNER_BINDING, } from "@nwire/forge";
+function providerPlugin(providers) {
+    return {
+        name: "test.providers",
+        setup({ bind }) {
+            for (const [name, value] of Object.entries(providers ?? {})) {
+                bind(name, value);
+            }
+        },
+    };
+}
+function buildApp(target, opts, asQuery) {
+    return createApp({
+        appName: "invoke",
+        handlers: [
+            ...(!asQuery ? [target] : []),
+            ...(opts.handlers ?? []),
+            ...(asQuery ? [target] : []),
+            ...(opts.queries ?? []),
+        ],
+        plugins: [
+            providerPlugin(opts.providers),
+            ...forgePlugins({
+                actors: opts.actors,
+                projections: opts.projections,
+            }),
+        ],
+    });
+}
+/**
+ * Boot a minimal app around `handler`, dispatch `input` once through the real
+ * forge pipeline (validation, hooks, retry, event publish), return the
+ * handler's result, and stop the app.
+ */
+export async function invoke(action, input, opts = {}) {
+    const app = buildApp(action, opts, false);
+    await app.start();
+    try {
+        const runner = app.container.resolve(FORGE_ACTION_RUNNER_BINDING);
+        if (opts.envelope) {
+            const { seedEnvelope } = await import("@nwire/envelope");
+            return (await runner.dispatch(action, input, seedEnvelope(opts.envelope)));
+        }
+        return (await runner.dispatch(action, input));
+    }
+    finally {
+        await app.stop();
+    }
+}
+/**
+ * Boot a minimal app around `query`, run it once (projection- or handler-form),
+ * return the result, and stop the app. Pass `projections` for a projection-
+ * backed query and `providers` for a handler-form query's DI deps.
+ */
+export async function invokeQuery(
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+query, input, opts = {}) {
+    const app = buildApp(query, opts, true);
+    await app.start();
+    try {
+        const runner = app.container.resolve(FORGE_QUERY_RUNNER_BINDING);
+        return await runner.run(query.name, input, opts.envelope?.tenant ?? "");
+    }
+    finally {
+        await app.stop();
+    }
+}

package/dist/test-kit.d.ts

@@ -16,6 +16,7 @@
  * Plus existing helpers: zod fixture factory, supertest agent.
  */
 export { harness, type Harness, type HarnessOptions } from "./harness.js";
+export { invoke, invokeQuery, type InvokeOptions } from "./invoke.js";
 export { asUser, simulateRequest, checkPolicy, onLog, type UserLike, type ScopedHarness, type SimulatedRequest, type SimulatedResponse, type PolicyCheck, type LogLevel, type LogEntry, } from "./harness-extensions.js";
 export { TelemetryProbe, type TelemetryFilter } from "./telemetry-probe.js";
 export { dockerCompose, PRESETS as DOCKER_COMPOSE_PRESETS, type ComposeStack, type ComposePreset, } from "./docker-compose.js";

package/dist/test-kit.js

@@ -16,6 +16,7 @@
  * Plus existing helpers: zod fixture factory, supertest agent.
  */
 export { harness } from "./harness.js";
+export { invoke, invokeQuery } from "./invoke.js";
 export { asUser, simulateRequest, checkPolicy, onLog, } from "./harness-extensions.js";
 export { TelemetryProbe } from "./telemetry-probe.js";
 export { dockerCompose, PRESETS as DOCKER_COMPOSE_PRESETS, } from "./docker-compose.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nwire/test-kit",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Shared test helpers and zod-driven fixture factories",
   "keywords": [
     "fixtures",
@@ -28,20 +28,20 @@
   "dependencies": {
     "supertest": "^7.2.2",
     "zod": "^4.0.0",
-    "@nwire/envelope": "0.12.0",
-    "@nwire/logger": "0.12.0",
-    "@nwire/messages": "0.12.0",
-    "@nwire/forge": "0.12.0"
+    "@nwire/logger": "0.13.0",
+    "@nwire/messages": "0.13.0",
+    "@nwire/envelope": "0.13.0",
+    "@nwire/forge": "0.13.0"
   },
   "devDependencies": {
     "@types/koa": "^2.15.0",
     "@types/node": "^22.19.9",
     "@types/supertest": "^6.0.3",
     "typescript": "^5.9.3",
-    "@nwire/app": "0.12.0",
-    "@nwire/endpoint": "0.12.0",
-    "@nwire/koa": "0.12.0",
-    "@nwire/wires": "0.12.0"
+    "@nwire/app": "0.13.0",
+    "@nwire/endpoint": "0.13.0",
+    "@nwire/koa": "0.13.0",
+    "@nwire/wires": "0.13.0"
   },
   "peerDependencies": {
     "@amiceli/vitest-cucumber": "^4.0.0",