@rotorsoft/act 0.35.1 → 0.36.0

package/dist/@types/internal/settle.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @module settle
+ * @category Internal
+ *
+ * Debounced correlate→drain loop. Sits one level above both correlation
+ * and drain: schedule() coalesces rapid callers into a single cycle, then
+ * runs correlate+drain in a loop until a pass produces no progress.
+ *
+ * Owns the debounce timer and the reentrancy flag. Everything else is
+ * supplied via the `SettleDeps` callbacks so this module stays free of
+ * orchestrator state.
+ *
+ * @internal
+ */
+import type { Drain, DrainOptions, Logger, Query, Schemas, SettleOptions } from "../types/index.js";
+/**
+ * Callbacks the settle loop needs from the orchestrator. Modeled as an
+ * input bag so this file doesn't import `Act` (avoids a cycle) and stays
+ * independently testable.
+ *
+ * @internal
+ */
+export type SettleDeps<TEvents extends Schemas> = {
+    readonly logger: Logger;
+    readonly init: () => Promise<void>;
+    readonly checkpoint: () => number;
+    readonly correlate: (query: Query) => Promise<{
+        subscribed: number;
+        last_id: number;
+    }>;
+    readonly drain: (options: DrainOptions) => Promise<Drain<TEvents>>;
+    readonly onSettled: (drain: Drain<TEvents>) => void;
+};
+/**
+ * Drives the debounced correlate→drain catch-up cycle. One instance per
+ * Act orchestrator.
+ *
+ * @internal
+ */
+export declare class SettleLoop<TEvents extends Schemas> {
+    private readonly deps;
+    /** Debounce window applied when the caller doesn't override via `SettleOptions.debounceMs`. */
+    private readonly defaultDebounceMs;
+    private _timer;
+    private _running;
+    constructor(deps: SettleDeps<TEvents>, 
+    /** Debounce window applied when the caller doesn't override via `SettleOptions.debounceMs`. */
+    defaultDebounceMs: number);
+    /**
+     * Schedule a settle pass. Multiple calls inside the debounce window
+     * coalesce into one cycle. The cycle runs correlate→drain in a loop
+     * until no progress is made (no new subscriptions, no acks, no blocks)
+     * or `maxPasses` is reached, then emits the `"settled"` lifecycle event
+     * via {@link SettleDeps.onSettled}.
+     */
+    schedule(options?: SettleOptions): void;
+    /** Cancel any pending or active settle cycle. Idempotent. */
+    stop(): void;
+}
+//# sourceMappingURL=settle.d.ts.map

package/dist/@types/internal/settle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settle.d.ts","sourceRoot":"","sources":["../../../src/internal/settle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EACV,KAAK,EACL,YAAY,EACZ,MAAM,EACN,KAAK,EACL,OAAO,EACP,aAAa,EACd,MAAM,mBAAmB,CAAC;AAE3B;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,CAAC,OAAO,SAAS,OAAO,IAAI;IAChD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,QAAQ,CAAC,UAAU,EAAE,MAAM,MAAM,CAAC;IAClC,QAAQ,CAAC,SAAS,EAAE,CAClB,KAAK,EAAE,KAAK,KACT,OAAO,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACtD,QAAQ,CAAC,KAAK,EAAE,CAAC,OAAO,EAAE,YAAY,KAAK,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;IACnE,QAAQ,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC;CACrD,CAAC;AAEF;;;;;GAKG;AACH,qBAAa,UAAU,CAAC,OAAO,SAAS,OAAO;IAK3C,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,+FAA+F;IAC/F,OAAO,CAAC,QAAQ,CAAC,iBAAiB;IANpC,OAAO,CAAC,MAAM,CAAwD;IACtE,OAAO,CAAC,QAAQ,CAAS;gBAGN,IAAI,EAAE,UAAU,CAAC,OAAO,CAAC;IAC1C,+FAA+F;IAC9E,iBAAiB,EAAE,MAAM;IAG5C;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,GAAE,aAAkB,GAAG,IAAI;IA0C3C,6DAA6D;IAC7D,IAAI,IAAI,IAAI;CAMb"}

package/dist/@types/internal/tracing.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @module tracing
+ * @category Internal
+ *
+ * Centralized observability for the framework's internal pipelines.
+ *
+ * Trace decorators wrap a bare implementation with `logger.trace(...)` calls
+ * at well-defined moments — entry points for {@link "event-sourcing"} (`load`,
+ * `snap`, `action`) and exit points for the {@link "drain"} pipeline (`claim`,
+ * `fetch`, `ack`, `block`, `subscribe`). `action` carries both an entry log
+ * and a post-commit log to preserve the diagnostic value of the historical
+ * mid-function trace points.
+ *
+ * Output styles:
+ * - **Pretty mode** (`config().env !== "production"`) — event-sourcing logs
+ *   show only the colored target body (color carries the operation/phase),
+ *   drain logs keep a colored caption.
+ * - **Plain mode** (production / log aggregators) — every log gets a textual
+ *   prefix; event-sourcing uses `caption: body`, drain uses `caption body`.
+ *
+ * The two factories — {@link buildEs} and {@link buildDrain} — let the
+ * orchestrator choose bare or traced variants once at `.build()` time based
+ * on the configured log level. Outside this module, no other source file
+ * imports tracing primitives.
+ *
+ * @internal
+ */
+import type { Logger, Schemas } from "../types/index.js";
+import type { DrainOps } from "./drain.js";
+import type { EsOps } from "./event-sourcing.js";
+/**
+ * Selects bare or traced event-sourcing handlers. Called once by the
+ * orchestrator constructor.
+ *
+ * @internal
+ */
+export declare function buildEs(logger: Logger): EsOps;
+/**
+ * Selects bare or traced drain-pipeline ops. Called once by the orchestrator
+ * constructor.
+ *
+ * @internal
+ */
+export declare function buildDrain<TEvents extends Schemas>(logger: Logger): DrainOps<TEvents>;
+//# sourceMappingURL=tracing.d.ts.map

package/dist/@types/internal/tracing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracing.d.ts","sourceRoot":"","sources":["../../../src/internal/tracing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,OAAO,KAAK,EAAQ,MAAM,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AA4GjD;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,KAAK,CA+D7C;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,OAAO,SAAS,OAAO,EAChD,MAAM,EAAE,MAAM,GACb,QAAQ,CAAC,OAAO,CAAC,CAyDnB"}

package/dist/@types/lru-map.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @module lru-map
+ * @category Internal
+ *
+ * Tiny bounded LRU map / set built on insertion-ordered `Map`. Used to cap
+ * memory in long-running orchestrators that mint large numbers of keys —
+ * notably:
+ *
+ * - {@link InMemoryCache}: stream → state checkpoint
+ * - `Act._subscribed_streams`: stream → presence (LruSet)
+ *
+ * Apps with millions of dynamic streams (one target per aggregate) can't
+ * afford an unbounded `Set<string>` — eviction is required.
+ *
+ * @internal
+ */
+/**
+ * Bounded LRU map. `get()` promotes; `has()` does not. `set()` always
+ * promotes and evicts the oldest entry when at capacity.
+ *
+ * @internal
+ */
+export declare class LruMap<K, V> {
+    private readonly _maxSize;
+    private readonly _entries;
+    constructor(_maxSize: number);
+    get(key: K): V | undefined;
+    has(key: K): boolean;
+    set(key: K, value: V): void;
+    delete(key: K): boolean;
+    clear(): void;
+    get size(): number;
+}
+/**
+ * Bounded LRU set built on top of {@link LruMap}. `has()` does not promote;
+ * `add()` does (re-inserting if already present, evicting the oldest at
+ * capacity).
+ *
+ * @internal
+ */
+export declare class LruSet<T> {
+    private readonly _map;
+    constructor(maxSize: number);
+    has(value: T): boolean;
+    add(value: T): void;
+    delete(value: T): boolean;
+    clear(): void;
+    get size(): number;
+}
+//# sourceMappingURL=lru-map.d.ts.map

package/dist/@types/lru-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lru-map.d.ts","sourceRoot":"","sources":["../../src/lru-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH;;;;;GAKG;AACH,qBAAa,MAAM,CAAC,CAAC,EAAE,CAAC;IAGV,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAFrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmB;gBAEf,QAAQ,EAAE,MAAM;IAE7C,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS;IAS1B,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,OAAO;IAIpB,GAAG,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI;IAW3B,MAAM,CAAC,GAAG,EAAE,CAAC,GAAG,OAAO;IAIvB,KAAK,IAAI,IAAI;IAIb,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF;AAED;;;;;;GAMG;AACH,qBAAa,MAAM,CAAC,CAAC;IACnB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAkB;gBAE3B,OAAO,EAAE,MAAM;IAI3B,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO;IAItB,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI;IAInB,MAAM,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO;IAIzB,KAAK,IAAI,IAAI;IAIb,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF"}

package/dist/@types/ports.d.ts

@@ -0,0 +1,196 @@
+import { ConsoleLogger } from "./adapters/console-logger.js";
+import type { Cache, Disposable, Disposer, Logger, Store } from "./types/index.js";
+/**
+ * Port/adapter infrastructure for the Act framework.
+ *
+ * All infrastructure concerns (logging, storage, caching) are managed as
+ * singleton adapters injected via port functions. Each port follows the same
+ * pattern: first call wins with a sensible default, optional adapter injection.
+ *
+ * - `log()` — structured logging (default: ConsoleLogger)
+ * - `store()` — event persistence (default: InMemoryStore)
+ * - `cache()` — state checkpoints (default: InMemoryCache)
+ * - `dispose()` — register cleanup functions for graceful shutdown
+ *
+ * @module ports
+ */
+/**
+ * List of exit codes for process termination. Consumed by signal handlers
+ * and {@link disposeAndExit}; not part of the user-facing surface.
+ *
+ * @internal
+ */
+export declare const ExitCodes: readonly ["ERROR", "EXIT"];
+/**
+ * Type for allowed exit codes.
+ *
+ * - `"ERROR"` — abnormal termination (uncaught exception, unhandled rejection)
+ * - `"EXIT"` — clean shutdown (SIGINT, SIGTERM, or manual trigger)
+ *
+ * @internal
+ */
+export type ExitCode = (typeof ExitCodes)[number];
+/**
+ * Factory function that creates or returns the injected adapter.
+ * @internal
+ */
+type Injector<Port extends Disposable> = (adapter?: Port) => Port;
+/**
+ * Creates a singleton port with optional adapter injection.
+ *
+ * The first call initializes the adapter (using the provided adapter or the
+ * injector's default). Subsequent calls return the cached singleton. Adapters
+ * are disposed in reverse registration order during {@link disposeAndExit}.
+ *
+ * @param injector - Named function that creates the default adapter
+ * @returns Port function: call with no args to get the singleton, or pass an
+ *          adapter on the first call to override the default
+ *
+ * @example
+ * ```typescript
+ * const store = port(function store(adapter?: Store) {
+ *   return adapter || new InMemoryStore();
+ * });
+ * const s = store(); // InMemoryStore
+ * ```
+ */
+export declare function port<Port extends Disposable>(injector: Injector<Port>): (adapter?: Port) => Port;
+/**
+ * Gets or injects the singleton logger.
+ *
+ * By default, Act uses a built-in {@link ConsoleLogger} that emits JSON lines
+ * in production (compatible with GCP, AWS CloudWatch, Datadog) and colorized
+ * output in development — zero external dependencies.
+ *
+ * For pino, inject a `PinoLogger` from `@rotorsoft/act-pino` before building
+ * your application.
+ *
+ * @param adapter - Optional logger implementation to inject
+ * @returns The singleton logger instance
+ *
+ * @example Default console logger
+ * ```typescript
+ * import { log } from "@rotorsoft/act";
+ * const logger = log();
+ * logger.info("Application started");
+ * ```
+ *
+ * @example Injecting pino
+ * ```typescript
+ * import { log } from "@rotorsoft/act";
+ * import { PinoLogger } from "@rotorsoft/act-pino";
+ * log(new PinoLogger({ level: "debug", pretty: true }));
+ * ```
+ *
+ * @see {@link Logger} for the interface contract
+ * @see {@link ConsoleLogger} for the default implementation
+ */
+export declare const log: (adapter?: Logger | ConsoleLogger | undefined) => Logger | ConsoleLogger;
+/**
+ * Gets or injects the singleton event store.
+ *
+ * By default, Act uses an {@link InMemoryStore} suitable for development and
+ * testing. For production, inject a persistent store like `PostgresStore` from
+ * `@rotorsoft/act-pg` before building your application.
+ *
+ * **Important:** Store injection must happen before creating any Act instances.
+ * Once set, the store cannot be changed without restarting the application.
+ *
+ * @param adapter - Optional store implementation to inject
+ * @returns The singleton store instance
+ *
+ * @example Default in-memory store
+ * ```typescript
+ * import { store } from "@rotorsoft/act";
+ * const s = store();
+ * ```
+ *
+ * @example Injecting PostgreSQL
+ * ```typescript
+ * import { store } from "@rotorsoft/act";
+ * import { PostgresStore } from "@rotorsoft/act-pg";
+ *
+ * store(new PostgresStore({
+ *   host: "localhost",
+ *   port: 5432,
+ *   database: "myapp",
+ *   user: "postgres",
+ *   password: "secret",
+ * }));
+ * ```
+ *
+ * @see {@link Store} for the interface contract
+ * @see {@link InMemoryStore} for the default implementation
+ */
+export declare const store: (adapter?: Store | undefined) => Store;
+/**
+ * Gets or injects the singleton cache.
+ *
+ * By default, Act uses an {@link InMemoryCache} (LRU, maxSize 1000). For
+ * distributed deployments, inject a Redis-backed cache before building your
+ * application.
+ *
+ * @param adapter - Optional cache implementation to inject
+ * @returns The singleton cache instance
+ *
+ * @see {@link Cache} for the interface contract
+ * @see {@link InMemoryCache} for the default implementation
+ */
+export declare const cache: (adapter?: Cache | undefined) => Cache;
+/**
+ * Disposes all registered adapters and disposers, then exits the process.
+ *
+ * Execution order:
+ * 1. Custom disposers (registered via {@link dispose}) — in reverse order
+ * 2. Port adapters (log, store, cache) — in reverse registration order
+ * 3. Adapter registry is cleared
+ * 4. Process exits (skipped in test environment)
+ *
+ * In production, `"ERROR"` exits are silently ignored to avoid crashing on
+ * transient failures (e.g. an uncaught promise in a non-critical path).
+ *
+ * @param code - Exit code: `"EXIT"` for clean shutdown (exit 0),
+ *               `"ERROR"` for abnormal termination (exit 1)
+ */
+export declare function disposeAndExit(code?: ExitCode): Promise<void>;
+/**
+ * Registers a cleanup function for graceful shutdown.
+ *
+ * Disposers are called automatically on SIGINT, SIGTERM, uncaught exceptions,
+ * and unhandled rejections. They execute in reverse registration order before
+ * port adapters are disposed.
+ *
+ * @param disposer - Async function to call during cleanup. Omit to get a
+ *                   reference to {@link disposeAndExit} without registering.
+ * @returns Function to manually trigger disposal and exit
+ *
+ * @example
+ * ```typescript
+ * import { dispose } from "@rotorsoft/act";
+ *
+ * const db = connectDatabase();
+ * dispose(async () => await db.close());
+ *
+ * // In tests
+ * afterAll(async () => await dispose()());
+ * ```
+ *
+ * @see {@link disposeAndExit} for the full shutdown sequence
+ */
+export declare function dispose(disposer?: Disposer): (code?: ExitCode) => Promise<void>;
+/**
+ * Event name used internally for snapshot events in the event store.
+ * Snapshot events store a full state checkpoint, enabling efficient cold-start
+ * recovery without replaying the entire event stream.
+ */
+export declare const SNAP_EVENT = "__snapshot__";
+/**
+ * Event name used internally for tombstone events in the event store.
+ * A tombstone marks a stream as permanently closed — no further writes
+ * are permitted until the stream is explicitly restarted via `close()`.
+ *
+ * @see {@link Act.close} for the close-the-books API
+ */
+export declare const TOMBSTONE_EVENT = "__tombstone__";
+export {};
+//# sourceMappingURL=ports.d.ts.map

package/dist/@types/ports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ports.d.ts","sourceRoot":"","sources":["../../src/ports.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAI7D,OAAO,KAAK,EACV,KAAK,EACL,UAAU,EACV,QAAQ,EACR,MAAM,EACN,KAAK,EACN,MAAM,kBAAkB,CAAC;AAE1B;;;;;;;;;;;;;GAaG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,SAAS,4BAA6B,CAAC;AAEpD;;;;;;;GAOG;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC;AAMlD;;;GAGG;AACH,KAAK,QAAQ,CAAC,IAAI,SAAS,UAAU,IAAI,CAAC,OAAO,CAAC,EAAE,IAAI,KAAK,IAAI,CAAC;AAKlE;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,IAAI,CAAC,IAAI,SAAS,UAAU,EAAE,QAAQ,EAAE,QAAQ,CAAC,IAAI,CAAC,IAC5D,UAAU,IAAI,KAAG,IAAI,CAW9B;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,GAAG,0EASd,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,KAAK,wCAEhB,CAAC;AAEH;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,KAAK,wCAEhB,CAAC;AASH;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,cAAc,CAAC,IAAI,GAAE,QAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuB3E;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,OAAO,CACrB,QAAQ,CAAC,EAAE,QAAQ,GAClB,CAAC,IAAI,CAAC,EAAE,QAAQ,KAAK,OAAO,CAAC,IAAI,CAAC,CAGpC;AAMD;;;;GAIG;AACH,eAAO,MAAM,UAAU,iBAAiB,CAAC;AAEzC;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,kBAAkB,CAAC"}

package/dist/@types/signals.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=signals.d.ts.map

package/dist/@types/signals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signals.d.ts","sourceRoot":"","sources":["../../src/signals.ts"],"names":[],"mappings":""}