@nwire/forge 0.10.0 → 0.11.0

package/dist/runtime/forge-plugin.js

@@ -1,55 +1,52 @@
 /**
- * `forgePlugin` — the foundation-form delivery of forge's CQRS engine.
+ * Forge plugin — installs the dispatcher, materialises forge's framework
+ * hooks, pins the action handler step on the dispatch chain, and registers
+ * any domain primitives passed in options.
  *
- * Used two ways:
+ *   import { createApp } from "@nwire/app";
+ *   import { createForgePlugin, FORGE_DISPATCHER_BINDING } from "@nwire/forge";
  *
- *   // Default stores (InMemory*):
- *   createApp({ plugins: [forgePlugin, ...] })
+ *   const app = createApp({
+ *     appName: "orders",
+ *     plugins: [createForgePlugin({
+ *       actors: [Order],
+ *       projections: [OrdersDashboard],
+ *       handlers: [placeOrder, sendReceipt],
+ *     })],
+ *   });
  *
- *   // Custom stores / cross-service bus / persistent timers:
- *   createApp({ plugins: [createForgePlugin({ actorStore, bus }), ...] })
+ *   await app.start();
+ *   const dispatcher = app.container.resolve(FORGE_DISPATCHER_BINDING);
  *
- * Setup work:
- *   1. Construct a `ForgeDispatcher(runtime, opts)`.
- *   2. Bind it on the container as `"forge.dispatcher"`; consumer code
- *      (and forge.createApp's app-handle delegators) resolves it from
- *      there to call `dispatch / publish / fireDueTimers / …`.
- *   3. Materialise the Action* / Event* framework-hook slots forge's
- *      module augmentation declares — kernel pre-instantiates only
- *      App* / Plugin* / Wire* slots; forge's domain slots come in via
- *      the plugin so a non-forge app's runtime stays uncluttered.
- *   4. Pin the action handler chain step on `runtime.dispatchHook$` at
- *      priority `-Infinity` so user-registered `runtime.use()` middleware
- *      stays strictly OUTSIDE the handler invocation.
+ * Handlers and direct registrations land on the dispatcher during the
+ * `AppBooting` chain — after every plugin's setup ran (so the dispatcher
+ * is bound) but before plugin boot queues fire (so downstream plugins'
+ * boot work can reach domain routes already wired).
  *
- * Dispose work:
- *   - Best-effort cleanup of the in-memory workflow timer scheduler if
- *     the dispatcher started one. Persistent stores release through
- *     their own `bind({ dispose })` registrations.
+ * `forgePlugin` is the default-options shortcut for tests, demos, and
+ * single-process apps. For custom stores or a cross-service bus, use
+ * `createForgePlugin(opts)`.
  */
 import { ForgeDispatcher } from "./forge-dispatcher.js";
-/** Canonical container binding name for the forge dispatcher. */
+/** Container binding the forge dispatcher is registered under. */
 export const FORGE_DISPATCHER_BINDING = "forge.dispatcher";
-/** Capability bindings — handler / resolver ctx resolves these by name. */
+/** Capability bindings consumed by handler / resolver ctx via `ctx.resolve(...)`. */
 export const FORGE_EXECUTE_BINDING = "execute";
 export const FORGE_SEND_BINDING = "send";
 export const FORGE_USE_PROJECTION_BINDING = "useProjection";
 /**
- * Default forge plugin — uses in-memory stores for everything.
- * Suitable for tests, demos, and single-process apps. For custom
- * stores or a cross-service bus, use `createForgePlugin(opts)`.
+ * Construct a forge plugin with custom stores, bus, and/or domain
+ * primitives. The plugin's setup is synchronous; domain registration
+ * happens during the App's `AppBooting` chain.
  */
-export const forgePlugin = createForgePlugin();
 export function createForgePlugin(options = {}) {
     return {
         name: "forge",
         setup({ runtime, bind, dispose, hooks }) {
             const dispatcher = new ForgeDispatcher(runtime, options);
-            // 1. Bind the dispatcher on the container so the app handle's
-            //    `dispatch / publish / request / …` delegators can resolve it.
             bind(FORGE_DISPATCHER_BINDING, dispatcher);
-            // 1b. Bind capability factories — what handlers / HTTP resolvers
-            //     reach for via `ctx.resolve("execute" | "send" | "useProjection")`.
+            // Capability factories for handler / HTTP resolver ctx
+            // (`ctx.resolve("execute" | "send" | "useProjection")`).
             const execute = (action, input, envelope) => dispatcher.dispatch(action, input, envelope);
             const send = (action, input, envelope) => {
                 void dispatcher.dispatch(action, input, envelope);
@@ -60,62 +57,78 @@ export function createForgePlugin(options = {}) {
             bind(FORGE_EXECUTE_BINDING, () => execute);
             bind(FORGE_SEND_BINDING, () => send);
             bind(FORGE_USE_PROJECTION_BINDING, () => useProjection);
-            // 2. Materialise forge's Action* / Event* framework-hook slots.
-            //    The kernel pre-instantiates App* / Plugin* / Wire*; forge's
-            //    augmentation gets installed here so a runtime without forge
-            //    doesn't carry empty Action*/Event* hooks.
-            for (const slot of ["ActionDispatching", "ActionCompleted", "ActionFailed", "EventRecording", "EventRecorded"]) {
+            // Materialise forge's Action* / Event* hook slots and the
+            // EventPublishing chain. Apps without forge don't carry these.
+            for (const slot of [
+                "ActionDispatching",
+                "ActionCompleted",
+                "ActionFailed",
+                "EventRecording",
+                "EventRecorded",
+                "EventPublishing",
+            ]) {
                 runtime.defineHook(slot);
             }
-            // 3. Pin the dispatch chain step. priority -Infinity keeps every
-            //    user `runtime.use()` middleware strictly outside it; the
-            //    pinned step calls the dispatcher's prepared `coreFn` and
-            //    writes the result back onto `hctx.result`.
+            // Attach forge's atomic publish chain to the EventPublishing hook.
+            // Each step does its work for one event and calls next() to descend
+            // to the next priority slot. The idempotency step short-circuits
+            // (skips next) when a duplicate is seen.
+            dispatcher.attachPublishChain();
+            // Pin the dispatch chain handler step at priority -Infinity so any
+            // user `runtime.use()` middleware stays strictly outside the
+            // handler invocation.
             runtime.dispatchHook$.use(async (hctx, next) => {
                 hctx.result = await hctx.coreFn();
                 await next();
             }, { name: "handler", priority: -Infinity });
-            // 3a. Forward runtime-registered forge handlers to the dispatcher
-            //     at AppBooting time. createApp's `handlers` option lands them on
-            //     runtime.handlers; the dispatcher needs its own registration to
-            //     route by action name. We pick them up by checking for `$kind
-            //     === "handler"` (forge HandlerDefinition shape) — anything else
-            //     stays on the runtime side.
+            // Domain registration runs at AppBooting — after every plugin's
+            // setup ran (so the dispatcher is bound) but before plugin boot
+            // queues fire (so downstream plugins' boot work can reach domain
+            // routes already wired).
             hooks.AppBooting.use(async (_, next) => {
-                // Forward runtime-registered forge handlers to the dispatcher.
+                // Forward any runtime-registered handlers to the dispatcher.
                 for (const name of runtime.listHandlers()) {
                     const def = runtime.getHandler(name);
                     if (def?.$kind === "handler") {
                         dispatcher.registerActionHandler(def);
                     }
                 }
-                // Register plugin-option domain primitives.
+                // Register option-declared primitives.
+                for (const handler of options.handlers ?? []) {
+                    dispatcher.registerActionHandler(handler);
+                }
                 for (const actor of options.actors ?? []) {
                     dispatcher.registerActor(actor);
                 }
-                for (const workflow of options.workflows ?? []) {
-                    dispatcher.registerWorkflow(workflow);
-                }
                 for (const projection of options.projections ?? []) {
                     dispatcher.registerProjection(projection);
                 }
                 for (const query of options.queries ?? []) {
                     dispatcher.registerQuery(query);
                 }
+                for (const workflow of options.workflows ?? []) {
+                    dispatcher.registerWorkflow(workflow);
+                }
                 for (const call of options.externalCalls ?? []) {
                     dispatcher.registerExternalCall(call);
                 }
                 await next();
-            }, { name: "forge.forward-handlers", priority: 1_000_000 });
-            // 4. Graceful shutdown — close any internally-managed schedulers.
-            //    The in-memory timer store has no thread to stop; durable
-            //    adapters that DO own threads pass themselves in via opts and
-            //    handle their own dispose via `bind(name, store, { dispose })`.
+            }, { name: "forge.register-domain", priority: 1_000_000 });
+            // Cleanup hook — durable adopters with their own dispose schedules
+            // register via `bind(name, store, { dispose })`.
             dispose(async () => {
-                // No-op for in-memory; reserved for future timer-scheduler
-                // ownership semantics.
                 void dispatcher;
             });
         },
     };
 }
+/** Default forge plugin — in-memory stores, no bus, no domain options. */
+export const forgePlugin = createForgePlugin();
+/**
+ * Resolve the forge dispatcher from an app's container. Convenience for
+ * test code and tooling that needs direct dispatcher access; handler code
+ * uses `ctx.execute` / `ctx.send` / `ctx.publish` instead.
+ */
+export function forgeDispatcher(app) {
+    return app.container.resolve(FORGE_DISPATCHER_BINDING);
+}

package/dist/runtime/with-forge.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `withForge(opts)` — App-transformer that installs forge.
+ *
+ * A plain function `App → App` that calls `app.with(createForgePlugin(opts))`
+ * under the hood. Use it as the canonical install path for forge:
+ *
+ *   const app = withForge({
+ *     actors: [Order],
+ *     projections: [OrdersDashboard],
+ *     actions: [placeOrder, sendReceipt],
+ *   })(createApp({ appName: "orders" }));
+ *
+ * Equivalent to writing the chain by hand:
+ *
+ *   const app = createApp({ appName: "orders" })
+ *     .with(createForgePlugin({ actors: [Order], ... }));
+ *
+ * Use whichever reads better at the call site.
+ */
+import type { App } from "@nwire/app";
+import { type ForgePluginOptions } from "./forge-plugin.js";
+/**
+ * Returns an App transformer that installs forge into any App it's
+ * applied to. The transformer preserves the existing `<TCaps>`.
+ */
+export declare function withForge(opts?: ForgePluginOptions): <TCaps>(app: App<TCaps>) => App<TCaps>;

package/dist/runtime/with-forge.js

@@ -0,0 +1,30 @@
+/**
+ * `withForge(opts)` — App-transformer that installs forge.
+ *
+ * A plain function `App → App` that calls `app.with(createForgePlugin(opts))`
+ * under the hood. Use it as the canonical install path for forge:
+ *
+ *   const app = withForge({
+ *     actors: [Order],
+ *     projections: [OrdersDashboard],
+ *     actions: [placeOrder, sendReceipt],
+ *   })(createApp({ appName: "orders" }));
+ *
+ * Equivalent to writing the chain by hand:
+ *
+ *   const app = createApp({ appName: "orders" })
+ *     .with(createForgePlugin({ actors: [Order], ... }));
+ *
+ * Use whichever reads better at the call site.
+ */
+import { createForgePlugin } from "./forge-plugin.js";
+/**
+ * Returns an App transformer that installs forge into any App it's
+ * applied to. The transformer preserves the existing `<TCaps>`.
+ */
+export function withForge(opts = {}) {
+    return (app) => {
+        app.with(createForgePlugin(opts));
+        return app;
+    };
+}

package/dist/stores/idempotency-store.d.ts

@@ -22,11 +22,26 @@ export interface IdempotencyStore {
     record(messageId: string, opts?: {
         ttlMs?: number;
     }): void | Promise<void>;
+    /**
+     * Atomic check-and-record. Returns true on the first call for a given
+     * key and false on subsequent calls. Used by the EventPublishing
+     * idempotency step to dedup correctly under concurrent publishes.
+     *
+     * Adapters backed by Redis / Postgres / etc. should implement this as
+     * a single round-trip (SETNX, INSERT … ON CONFLICT, etc.). The
+     * in-memory default does it synchronously on the underlying Set so
+     * concurrent JS callers can't race.
+     */
+    recordIfNew(messageId: string, opts?: {
+        ttlMs?: number;
+    }): boolean | Promise<boolean>;
 }
 export declare class InMemoryIdempotencyStore implements IdempotencyStore {
     private readonly entries;
     seen(messageId: string): boolean;
     record(messageId: string): void;
+    /** Atomic on a single-threaded event loop: check + add in one synchronous step. */
+    recordIfNew(messageId: string): boolean;
     /** Test seam — count of recorded ids. */
     size(): number;
     /** Test seam — drop all entries. */

package/dist/stores/idempotency-store.js

@@ -20,6 +20,13 @@ export class InMemoryIdempotencyStore {
     record(messageId) {
         this.entries.add(messageId);
     }
+    /** Atomic on a single-threaded event loop: check + add in one synchronous step. */
+    recordIfNew(messageId) {
+        if (this.entries.has(messageId))
+            return false;
+        this.entries.add(messageId);
+        return true;
+    }
     /** Test seam — count of recorded ids. */
     size() {
         return this.entries.size;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nwire/forge",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Nwire — the framework's core primitives. defineAction, defineEvent, defineHandler, defineActor, defineProjection, defineQuery, defineWorkflow, defineModule, defineApp, definePlugin, createApp. MessageEnvelope with correlation/causation. The runtime is the bus.",
   "keywords": [
     "actions",
@@ -34,16 +34,16 @@
     "emittery": "1.0.1",
     "koa": "^2.16.4",
     "zod": "^4.0.0",
-    "@nwire/app": "0.10.0",
-    "@nwire/bus": "0.10.0",
-    "@nwire/dead-letter": "0.10.0",
-    "@nwire/hooks": "0.10.0",
-    "@nwire/container": "0.10.0",
-    "@nwire/handler": "0.10.0",
-    "@nwire/logger": "0.10.0",
-    "@nwire/wires": "0.10.0",
-    "@nwire/messages": "0.10.0",
-    "@nwire/envelope": "0.10.0"
+    "@nwire/app": "0.11.0",
+    "@nwire/bus": "0.11.0",
+    "@nwire/dead-letter": "0.11.0",
+    "@nwire/handler": "0.11.0",
+    "@nwire/container": "0.11.0",
+    "@nwire/messages": "0.11.0",
+    "@nwire/wires": "0.11.0",
+    "@nwire/logger": "0.11.0",
+    "@nwire/envelope": "0.11.0",
+    "@nwire/hooks": "0.11.0"
   },
   "devDependencies": {
     "@types/koa": "^2.15.0",