@rotorsoft/act 0.5.1 → 0.5.2

package/dist/index.js

@@ -1,6 +1,5 @@
-// src/config.ts
-import * as fs from "fs";
-import { z as z2 } from "zod/v4";
+// src/ports.ts
+import { pino } from "pino";
 
 // src/types/errors.ts
 var Errors = {
@@ -37,6 +36,13 @@ var ConcurrencyError = class extends Error {
   }
 };
 
+// src/utils.ts
+import { prettifyError } from "zod/v4";
+
+// src/config.ts
+import * as fs from "fs";
+import { z as z2 } from "zod/v4";
+
 // src/types/schemas.ts
 import { z } from "zod/v4";
 var ZodEmpty = z.record(z.string(), z.never());
@@ -115,8 +121,36 @@ var LogLevels = [
   "trace"
 ];
 
+// src/config.ts
+var PackageSchema = z2.object({
+  name: z2.string().min(1),
+  version: z2.string().min(1),
+  description: z2.string().min(1).optional(),
+  author: z2.object({ name: z2.string().min(1), email: z2.string().optional() }).optional().or(z2.string().min(1)).optional(),
+  license: z2.string().min(1).optional(),
+  dependencies: z2.record(z2.string(), z2.string()).optional()
+});
+var getPackage = () => {
+  const pkg2 = fs.readFileSync("package.json");
+  return JSON.parse(pkg2.toString());
+};
+var BaseSchema = PackageSchema.extend({
+  env: z2.enum(Environments),
+  logLevel: z2.enum(LogLevels),
+  logSingleLine: z2.boolean(),
+  sleepMs: z2.number().int().min(0).max(5e3)
+});
+var { NODE_ENV, LOG_LEVEL, LOG_SINGLE_LINE, SLEEP_MS } = process.env;
+var env = NODE_ENV || "development";
+var logLevel = LOG_LEVEL || (NODE_ENV === "test" ? "error" : LOG_LEVEL === "production" ? "info" : "trace");
+var logSingleLine = (LOG_SINGLE_LINE || "true") === "true";
+var sleepMs = parseInt(NODE_ENV === "test" ? "0" : SLEEP_MS ?? "100");
+var pkg = getPackage();
+var config = () => {
+  return extend({ ...pkg, env, logLevel, logSingleLine, sleepMs }, BaseSchema);
+};
+
 // src/utils.ts
-import { prettifyError } from "zod/v4";
 var UNMERGEABLES = [
   RegExp,
   Date,
@@ -173,38 +207,6 @@ async function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms ?? config().sleepMs));
 }
 
-// src/config.ts
-var PackageSchema = z2.object({
-  name: z2.string().min(1),
-  version: z2.string().min(1),
-  description: z2.string().min(1),
-  author: z2.object({ name: z2.string().min(1), email: z2.string().optional() }).or(z2.string().min(1)),
-  license: z2.string().min(1),
-  dependencies: z2.record(z2.string(), z2.string())
-});
-var getPackage = () => {
-  const pkg2 = fs.readFileSync("package.json");
-  return JSON.parse(pkg2.toString());
-};
-var BaseSchema = PackageSchema.extend({
-  env: z2.enum(Environments),
-  logLevel: z2.enum(LogLevels),
-  logSingleLine: z2.boolean(),
-  sleepMs: z2.number().int().min(0).max(5e3)
-});
-var { NODE_ENV, LOG_LEVEL, LOG_SINGLE_LINE, SLEEP_MS } = process.env;
-var env = NODE_ENV || "development";
-var logLevel = LOG_LEVEL || (NODE_ENV === "test" ? "error" : LOG_LEVEL === "production" ? "info" : "trace");
-var logSingleLine = (LOG_SINGLE_LINE || "true") === "true";
-var sleepMs = parseInt(NODE_ENV === "test" ? "0" : SLEEP_MS ?? "100");
-var pkg = getPackage();
-var config = () => {
-  return extend({ ...pkg, env, logLevel, logSingleLine, sleepMs }, BaseSchema);
-};
-
-// src/ports.ts
-import { pino } from "pino";
-
 // src/adapters/InMemoryStore.ts
 var InMemoryStream = class {
   constructor(stream) {
@@ -214,12 +216,21 @@ var InMemoryStream = class {
   _retry = -1;
   _lease;
   _blocked = false;
+  /**
+   * Attempt to lease this stream for processing.
+   * @param lease - Lease request.
+   * @returns The granted lease or undefined if blocked.
+   */
   lease(lease) {
     if (!this._blocked && lease.at > this._at) {
       this._lease = { ...lease, retry: this._retry + 1 };
       return this._lease;
     }
   }
+  /**
+   * Acknowledge completion of processing for this stream.
+   * @param lease - Lease to acknowledge.
+   */
   ack(lease) {
     if (this._lease && lease.at >= this._at) {
       this._retry = lease.retry;
@@ -237,17 +248,35 @@ var InMemoryStore = class {
   _events = [];
   // stored stream positions and other metadata
   _streams = /* @__PURE__ */ new Map();
+  /**
+   * Dispose of the store and clear all events.
+   * @returns Promise that resolves when disposal is complete.
+   */
   async dispose() {
     await sleep();
     this._events.length = 0;
   }
+  /**
+   * Seed the store with initial data (no-op for in-memory).
+   * @returns Promise that resolves when seeding is complete.
+   */
   async seed() {
     await sleep();
   }
+  /**
+   * Drop all data from the store.
+   * @returns Promise that resolves when the store is cleared.
+   */
   async drop() {
     await sleep();
     this._events.length = 0;
   }
+  /**
+   * Query events in the store, optionally filtered by query options.
+   * @param callback - Function to call for each event.
+   * @param query - Optional query options.
+   * @returns The number of events processed.
+   */
   async query(callback, query) {
     await sleep();
     const {
@@ -275,10 +304,19 @@ var InMemoryStore = class {
     }
     return count;
   }
+  /**
+   * Commit one or more events to a stream.
+   * @param stream - The stream name.
+   * @param msgs - The events/messages to commit.
+   * @param meta - Event metadata.
+   * @param expectedVersion - Optional optimistic concurrency check.
+   * @returns The committed events with metadata.
+   * @throws ConcurrencyError if expectedVersion does not match.
+   */
   async commit(stream, msgs, meta, expectedVersion) {
     await sleep();
     const instance = this._events.filter((e) => e.stream === stream);
-    if (expectedVersion && instance.length - 1 !== expectedVersion)
+    if (typeof expectedVersion === "number" && instance.length - 1 !== expectedVersion)
       throw new ConcurrencyError(
         instance.length - 1,
         msgs,
@@ -301,7 +339,9 @@ var InMemoryStore = class {
     });
   }
   /**
-   * Fetches new events from stream watermarks
+   * Fetches new events from stream watermarks for processing.
+   * @param limit - Maximum number of streams to fetch.
+   * @returns Fetched streams and events.
    */
   async fetch(limit) {
     const streams = [...this._streams.values()].filter((s) => !s._blocked).sort((a, b) => a._at - b._at).slice(0, limit);
@@ -316,6 +356,11 @@ var InMemoryStore = class {
     });
     return { streams: streams.map(({ stream }) => stream), events };
   }
+  /**
+   * Lease streams for processing (e.g., for distributed consumers).
+   * @param leases - Lease requests.
+   * @returns Granted leases.
+   */
   async lease(leases) {
     await sleep();
     return leases.map((lease) => {
@@ -324,6 +369,10 @@ var InMemoryStore = class {
       return stream.lease(lease);
     }).filter((l) => !!l);
   }
+  /**
+   * Acknowledge completion of processing for leased streams.
+   * @param leases - Leases to acknowledge.
+   */
   async ack(leases) {
     await sleep();
     leases.forEach((lease) => this._streams.get(lease.stream)?.ack(lease));
@@ -376,6 +425,24 @@ var store = port(function store2(adapter) {
   return adapter || new InMemoryStore();
 });
 
+// src/signals.ts
+process.once("SIGINT", async (arg) => {
+  logger.info(arg, "SIGINT");
+  await disposeAndExit("EXIT");
+});
+process.once("SIGTERM", async (arg) => {
+  logger.info(arg, "SIGTERM");
+  await disposeAndExit("EXIT");
+});
+process.once("uncaughtException", async (arg) => {
+  logger.error(arg, "Uncaught Exception");
+  await disposeAndExit("ERROR");
+});
+process.once("unhandledRejection", async (arg) => {
+  logger.error(arg, "Unhandled Rejection");
+  await disposeAndExit("ERROR");
+});
+
 // src/act.ts
 import { randomUUID as randomUUID2 } from "crypto";
 import EventEmitter from "events";
@@ -491,6 +558,12 @@ async function action(me, action2, target, payload, reactingTo, skipValidation =
 
 // src/act.ts
 var Act = class {
+  /**
+   * Create a new Act orchestrator.
+   *
+   * @param registry The registry of state, event, and action schemas
+   * @param drainLimit The maximum number of events to drain per cycle
+   */
   constructor(registry, drainLimit) {
     this.registry = registry;
     this.drainLimit = drainLimit;
@@ -508,17 +581,18 @@ var Act = class {
     return this;
   }
   /**
-   * Executes an action and emits an event to be committed by the store.
+   * Executes an action (command) against a state machine, emitting and committing the resulting event(s).
    *
    * @template K The type of action to execute
-   * @template T The type of target
-   * @template P The type of payloads
-   * @param action The action to execute
-   * @param target The target of the action
-   * @param payload The payload of the action
-   * @param reactingTo The event that the action is reacting to
-   * @param skipValidation Whether to skip validation
-   * @returns The snapshot of the committed Event
+   * @param action The action name (key of the action schema)
+   * @param target The target (stream and actor) for the action
+   * @param payload The action payload (validated against the schema)
+   * @param reactingTo (Optional) The event this action is reacting to
+   * @param skipValidation (Optional) If true, skips schema validation (not recommended)
+   * @returns The snapshot of the committed event
+   *
+   * @example
+   * await app.do("increment", { stream: "counter1", actor }, { by: 1 });
    */
   async do(action2, target, payload, reactingTo, skipValidation = false) {
     const snapshot = await action(
@@ -533,25 +607,31 @@ var Act = class {
     return snapshot;
   }
   /**
-   * Loads a snapshot of the state from the store.
+   * Loads the current state snapshot for a given state machine and stream.
    *
    * @template SX The type of state
    * @template EX The type of events
    * @template AX The type of actions
-   * @param state The state to load
-   * @param stream The stream to load
-   * @param callback The callback to call with the snapshot
+   * @param state The state machine definition
+   * @param stream The stream (instance) to load
+   * @param callback (Optional) Callback to receive the loaded snapshot
    * @returns The snapshot of the loaded state
+   *
+   * @example
+   * const snapshot = await app.load(Counter, "counter1");
    */
   async load(state2, stream, callback) {
     return await load(state2, stream, callback);
   }
   /**
-   * Queries the store for events.
+   * Query the event store for events matching a filter.
+   *
+   * @param query The query filter (e.g., by stream, event name, or time range)
+   * @param callback (Optional) Callback for each event found
+   * @returns An object with the first and last event found, and the total count
    *
-   * @param query The query to execute
-   * @param callback The callback to call with the events
-   * @returns The query result
+   * @example
+   * const { count } = await app.query({ stream: "counter1" }, (event) => console.log(event));
    */
   async query(query, callback) {
     let first = void 0, last = void 0;
@@ -565,6 +645,7 @@ var Act = class {
   /**
    * Handles leased reactions.
    *
+   * @internal
    * @param lease The lease to handle
    * @param reactions The reactions to handle
    * @returns The lease
@@ -594,9 +675,14 @@ var Act = class {
   }
   drainLocked = false;
   /**
-   * Drains events from the store.
+   * Drains and processes events from the store, triggering reactions and updating state.
    *
-   * @returns The number of drained events
+   * This is typically called in a background loop or after committing new events.
+   *
+   * @returns The number of events drained and processed
+   *
+   * @example
+   * await app.drain();
    */
   async drain() {
     if (this.drainLocked) return 0;
@@ -819,24 +905,6 @@ function action_builder(state2) {
     }
   };
 }
-
-// src/index.ts
-process.once("SIGINT", async (arg) => {
-  logger.info(arg, "SIGINT");
-  await disposeAndExit("EXIT");
-});
-process.once("SIGTERM", async (arg) => {
-  logger.info(arg, "SIGTERM");
-  await disposeAndExit("EXIT");
-});
-process.once("uncaughtException", async (arg) => {
-  logger.error(arg, "Uncaught Exception");
-  await disposeAndExit("ERROR");
-});
-process.once("unhandledRejection", async (arg) => {
-  logger.error(arg, "Unhandled Rejection");
-  await disposeAndExit("ERROR");
-});
 export {
   Act,
   ActorSchema,
@@ -849,6 +917,7 @@ export {
   ExitCodes,
   InvariantError,
   LogLevels,
+  PackageSchema,
   QuerySchema,
   SNAP_EVENT,
   TargetSchema,