@nwire/forge 0.7.0

package/dist/create-app.d.ts

@@ -0,0 +1,131 @@
+/**
+ * `createApp` — declarative app composition.
+ *
+ *   const app = createApp({
+ *     modules:   [submissions, enrollments],
+ *     actorStore: new InMemoryActorStore(),
+ *     projectionStore: new InMemoryProjectionStore()
+ *   })
+ *   await app.start()
+ *
+ * `createApp` walks each module's manifest and registers actions, actors,
+ * handlers, projections, queries, and workflows into a fresh `Runtime`.
+ * The runtime is exposed for transports (HTTP, queue, cron) to bind to.
+ *
+ * Transports are NOT bundled here yet — for now, wires hand-attach Koa
+ * routers using `createDispatchHttp(app)`. Full `expose: [http(...), worker(...)]`
+ * shape lands when the second wire (queue worker) needs it.
+ *
+ * Lifecycle:
+ *   - `start()` — currently a no-op (registration happens at construction).
+ *     Becomes meaningful when transports + timer scheduler join the surface.
+ *   - `stop()` — drains pending work; reserved.
+ *   - `runtime` — escape hatch for transports and tests.
+ */
+import { type Container } from "@nwire/container";
+import type { ModuleDefinition } from "./define-module.js";
+import { Runtime } from "./runtime.js";
+import type { ActorStore } from "./actor-store.js";
+import type { ProjectionStore } from "./projection-store.js";
+import type { Logger } from "@nwire/logger";
+import type { DeadLetterSink } from "@nwire/dead-letter";
+import type { EventBus } from "@nwire/bus";
+import { type PluginDefinition } from "./define-plugin.js";
+export interface TimerSchedulerOptions {
+    /** Polling interval in milliseconds. Default: 60_000 (1 minute). */
+    readonly intervalMs?: number;
+}
+export interface CreateAppOptions {
+    readonly modules: readonly ModuleDefinition[];
+    /**
+     * Plugins — the only extension primitive. A plugin can bind values on
+     * the container, hook framework events, contribute middleware, and own
+     * boot/shutdown lifecycle. Use the closure form for most cases; the
+     * object form is kept for terse "just middleware" / "just lifecycle"
+     * plugins.
+     *
+     * Boot order: declaration order. Shutdown order: reverse declaration.
+     */
+    readonly plugins?: readonly PluginDefinition[];
+    /**
+     * App-level config map — exposed to plugin closures via `PluginContext.config`.
+     * Typically loaded from env at boot.
+     */
+    readonly config?: Record<string, any>;
+    readonly container?: Container;
+    readonly actorStore?: ActorStore;
+    readonly projectionStore?: ProjectionStore;
+    readonly logger?: Logger;
+    readonly deadLetterSink?: DeadLetterSink;
+    /**
+     * Cross-service event bus (`@nwire/bus`). When provided, the runtime
+     * publishes public events (visibility: 'public') to the bus IF
+     * `publishToBus: true`, and auto-subscribes to every event name in any
+     * module's `needs.externalEvents` so cross-service events flow into the
+     * runtime via `applyExternalEvent`.
+     */
+    readonly bus?: EventBus;
+    /**
+     * If true (default false), public events emitted in-process also fan out
+     * to the bus. Services that produce events for others should set this.
+     */
+    readonly publishToBus?: boolean;
+    /**
+     * App / service name. Tagged on bus-published events as `origin` so
+     * subscribers can suppress self-echoes (defensive — well-configured
+     * subscriptions don't pull origin-self anyway).
+     */
+    readonly appName?: string;
+    /**
+     * Enable the in-process polling timer scheduler. When set, `app.start()`
+     * begins polling `runtime.fireDueTimers()` on the configured interval
+     * (default 60s). For tests, omit and call `runtime.fireDueTimers(now)`
+     * directly with a fast-forwarded `now`.
+     *
+     * For multi-process deployments the polling scheduler is the wrong shape
+     * (each replica would fire timers). Use the BullMQ delayed-job transport
+     * (lands when the queue worker wire ships) — only one consumer per timer.
+     */
+    readonly timerScheduler?: TimerSchedulerOptions | true;
+    /**
+     * Console telemetry logger — one colored line per action/event/transition.
+     *
+     * Default: `true` (off only in `NODE_ENV=production` or when a structured
+     * `logger` is provided). Set `false` to silence; pass a `DevLoggerOptions`
+     * object to filter which telemetry `kind`s print.
+     *
+     * Production wires should pipe `runtime.onTelemetry` into pino/winston
+     * via a plugin and pass `devLogs: false` to mute this default.
+     */
+    readonly devLogs?: boolean | import("./dev-logger.js").DevLoggerOptions;
+}
+export interface App {
+    /** Structural marker — satisfies `AppServable` from `@nwire/endpoint`. */
+    readonly $nwireApp: true;
+    readonly runtime: Runtime;
+    readonly modules: readonly ModuleDefinition[];
+    readonly container: Container;
+    readonly appName: string;
+    start(): Promise<void>;
+    /**
+     * Tear down the app — plugins (reverse boot order) — and fire framework
+     * lifecycle events around the sequence. The optional `reason` is passed
+     * to `AppShuttingDown` subscribers so graceful-shutdown observers can log
+     * "why did we stop?".
+     */
+    stop(reason?: string): Promise<void>;
+    /** AppServable conformance — alias for `start()`. */
+    boot(): Promise<void>;
+    /** AppServable conformance — alias for `stop()`. */
+    shutdown(): Promise<void>;
+    /**
+     * Dispatch a framework lifecycle event on the app's bus by name. The
+     * endpoint uses this to fire `nwire.wire.mounting / .mounted /
+     * .unmounted` and `nwire.app.ready` at the right serve-loop points.
+     * Returns `false` when a series-bail subscriber prevented; `true`
+     * otherwise.
+     */
+    dispatchFrameworkEvent(eventName: string, payload: unknown): Promise<boolean>;
+}
+export declare function createApp(options: CreateAppOptions): App;
+//# sourceMappingURL=create-app.d.ts.map

package/dist/create-app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-app.d.ts","sourceRoot":"","sources":["../src/create-app.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAiB,KAAK,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAEjE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAsB,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAoB5E,MAAM,WAAW,qBAAqB;IACpC,oEAAoE;IACpE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC9C;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC/C;;;OAGG;IAEH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACtC,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;IAC/B,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC;IACjC,QAAQ,CAAC,eAAe,CAAC,EAAE,eAAe,CAAC;IAC3C,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,CAAC;IACzC;;;;;;OAMG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAChC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;;;;OASG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,qBAAqB,GAAG,IAAI,CAAC;IACvD;;;;;;;;;OASG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,iBAAiB,EAAE,gBAAgB,CAAC;CACzE;AAED,MAAM,WAAW,GAAG;IAClB,0EAA0E;IAC1E,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC9C,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB;;;;;OAKG;IACH,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,qDAAqD;IACrD,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,oDAAoD;IACpD,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B;;;;;;OAMG;IACH,sBAAsB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC/E;AAED,wBAAgB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,GAAG,CA+axD"}