@rotorsoft/act 0.35.0 → 0.35.2

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

@@ -0,0 +1,284 @@
+import type { Actor, Message, Schema, Schemas, Snapshot, Target } from "./action.js";
+/**
+ * @packageDocumentation
+ * @module act/types
+ * @category Types
+ * Application error type constants and error classes for the Act Framework.
+ *
+ * - `ERR_VALIDATION`: Schema validation error
+ * - `ERR_INVARIANT`: Invariant validation error
+ * - `ERR_CONCURRENCY`: Optimistic concurrency validation error on commits
+ */
+export declare const Errors: {
+    readonly ValidationError: "ERR_VALIDATION";
+    readonly InvariantError: "ERR_INVARIANT";
+    readonly ConcurrencyError: "ERR_CONCURRENCY";
+    readonly StreamClosedError: "ERR_STREAM_CLOSED";
+};
+/**
+ * Thrown when an action or event payload fails Zod schema validation.
+ *
+ * This error indicates that data doesn't match the expected schema defined
+ * for an action or event. The `details` property contains the Zod validation
+ * error with specific information about what failed.
+ *
+ * @example Catching validation errors
+ * ```typescript
+ * import { ValidationError } from "@rotorsoft/act";
+ *
+ * try {
+ *   await app.do("createUser", target, {
+ *     email: "invalid-email",  // Missing @ symbol
+ *     age: -5                  // Negative age
+ *   });
+ * } catch (error) {
+ *   if (error instanceof ValidationError) {
+ *     console.error("Validation failed for:", error.target);
+ *     console.error("Invalid payload:", error.payload);
+ *     console.error("Validation details:", error.details);
+ *     // details contains Zod error with field-level info
+ *   }
+ * }
+ * ```
+ *
+ * @example Logging validation details
+ * ```typescript
+ * try {
+ *   await app.do("updateProfile", target, payload);
+ * } catch (error) {
+ *   if (error instanceof ValidationError) {
+ *     error.details.errors.forEach((err) => {
+ *       console.error(`Field ${err.path.join(".")}: ${err.message}`);
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link https://zod.dev | Zod documentation} for validation details
+ */
+export declare class ValidationError extends Error {
+    /** The type of target being validated (e.g., "action", "event") */
+    readonly target: string;
+    /** The invalid payload that failed validation */
+    readonly payload: any;
+    /** Zod validation error details */
+    readonly details: any;
+    constructor(
+    /** The type of target being validated (e.g., "action", "event") */
+    target: string, 
+    /** The invalid payload that failed validation */
+    payload: any, 
+    /** Zod validation error details */
+    details: any);
+}
+/**
+ * Thrown when a business rule (invariant) is violated during action execution.
+ *
+ * Invariants are conditions that must hold true for an action to succeed.
+ * They're checked after loading the current state but before emitting events.
+ * This error provides complete context about what action was attempted and
+ * why it was rejected.
+ *
+ * @template TState - State schema type
+ * @template TEvents - Event schemas type
+ * @template TActions - Action schemas type
+ * @template TKey - Action name
+ * @template TActor - Actor type extending base Actor
+ *
+ * @example Catching invariant violations
+ * ```typescript
+ * import { InvariantError } from "@rotorsoft/act";
+ *
+ * try {
+ *   await app.do("withdraw",
+ *     { stream: "account-123", actor: { id: "user1", name: "Alice" } },
+ *     { amount: 1000 }
+ *   );
+ * } catch (error) {
+ *   if (error instanceof InvariantError) {
+ *     console.error("Action:", error.action);
+ *     console.error("Reason:", error.description);
+ *     console.error("Current state:", error.snapshot.state);
+ *     console.error("Attempted payload:", error.payload);
+ *   }
+ * }
+ * ```
+ *
+ * @example User-friendly error messages
+ * ```typescript
+ * try {
+ *   await app.do("closeTicket", target, payload);
+ * } catch (error) {
+ *   if (error instanceof InvariantError) {
+ *     // Present friendly message to user
+ *     if (error.description === "Ticket must be open") {
+ *       return { error: "This ticket is already closed" };
+ *     } else if (error.description === "Not authorized") {
+ *       return { error: "You don't have permission to close this ticket" };
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @example Logging with context
+ * ```typescript
+ * try {
+ *   await app.do("transfer", target, { to: "account2", amount: 500 });
+ * } catch (error) {
+ *   if (error instanceof InvariantError) {
+ *     logger.error({
+ *       action: error.action,
+ *       stream: error.target.stream,
+ *       actor: error.target.actor,
+ *       reason: error.description,
+ *       balance: error.snapshot.state.balance,
+ *       attempted: error.payload.amount
+ *     }, "Invariant violation");
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link Invariant} for defining business rules
+ */
+export declare class InvariantError<TState extends Schema, TEvents extends Schemas, TActions extends Schemas, TKey extends keyof TActions, TActor extends Actor = Actor> extends Error {
+    /** The action that was attempted */
+    readonly action: TKey;
+    /** The action payload that was provided */
+    readonly payload: Readonly<TActions[TKey]>;
+    /** The target stream and actor context */
+    readonly target: Target<TActor>;
+    /** The current state snapshot when invariant was checked */
+    readonly snapshot: Snapshot<TState, TEvents>;
+    /** Human-readable description of why the invariant failed */
+    readonly description: string;
+    constructor(
+    /** The action that was attempted */
+    action: TKey, 
+    /** The action payload that was provided */
+    payload: Readonly<TActions[TKey]>, 
+    /** The target stream and actor context */
+    target: Target<TActor>, 
+    /** The current state snapshot when invariant was checked */
+    snapshot: Snapshot<TState, TEvents>, 
+    /** Human-readable description of why the invariant failed */
+    description: string);
+}
+/**
+ * Thrown when optimistic concurrency control detects a conflict.
+ *
+ * This error occurs when trying to commit events to a stream that has been
+ * modified by another process since it was last loaded. The version number
+ * doesn't match expectations, indicating a concurrent modification.
+ *
+ * This is a normal occurrence in distributed systems and should be handled
+ * by reloading the current state and retrying the action.
+ *
+ * @example Handling concurrency conflicts with retry
+ * ```typescript
+ * import { ConcurrencyError } from "@rotorsoft/act";
+ *
+ * async function transferWithRetry(from, to, amount, maxRetries = 3) {
+ *   for (let attempt = 0; attempt < maxRetries; attempt++) {
+ *     try {
+ *       await app.do("transfer",
+ *         { stream: from, actor: currentUser },
+ *         { to, amount }
+ *       );
+ *       return { success: true };
+ *     } catch (error) {
+ *       if (error instanceof ConcurrencyError) {
+ *         if (attempt < maxRetries - 1) {
+ *           console.log(`Concurrent modification detected, retrying... (${attempt + 1}/${maxRetries})`);
+ *           await sleep(100 * Math.pow(2, attempt)); // Exponential backoff
+ *           continue;
+ *         }
+ *       }
+ *       throw error;
+ *     }
+ *   }
+ *   return { success: false, reason: "Too many concurrent modifications" };
+ * }
+ * ```
+ *
+ * @example Logging concurrency conflicts
+ * ```typescript
+ * try {
+ *   await app.do("updateInventory", target, payload);
+ * } catch (error) {
+ *   if (error instanceof ConcurrencyError) {
+ *     logger.warn({
+ *       stream: error.stream,
+ *       expectedVersion: error.expectedVersion,
+ *       actualVersion: error.lastVersion,
+ *       events: error.events.map(e => e.name)
+ *     }, "Concurrent modification detected");
+ *   }
+ * }
+ * ```
+ *
+ * @example User feedback for conflicts
+ * ```typescript
+ * try {
+ *   await app.do("editDocument", target, { content: newContent });
+ * } catch (error) {
+ *   if (error instanceof ConcurrencyError) {
+ *     return {
+ *       error: "This document was modified by another user. Please refresh and try again.",
+ *       code: "CONCURRENT_MODIFICATION"
+ *     };
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link Store.commit} for version checking details
+ */
+export declare class ConcurrencyError extends Error {
+    /** The stream that had the concurrent modification */
+    readonly stream: string;
+    /** The actual current version in the store */
+    readonly lastVersion: number;
+    /** The events that were being committed */
+    readonly events: Message<Schemas, keyof Schemas>[];
+    /** The version number that was expected */
+    readonly expectedVersion: number;
+    constructor(
+    /** The stream that had the concurrent modification */
+    stream: string, 
+    /** The actual current version in the store */
+    lastVersion: number, 
+    /** The events that were being committed */
+    events: Message<Schemas, keyof Schemas>[], 
+    /** The version number that was expected */
+    expectedVersion: number);
+}
+/**
+ * Thrown when attempting to write to a stream that has been closed
+ * with a tombstone event.
+ *
+ * A tombstoned stream is permanently closed — no further actions can
+ * be executed against it. The only way to reopen a tombstoned stream
+ * is through `Act.close()` with a `restart` callback.
+ *
+ * @example
+ * ```typescript
+ * import { StreamClosedError } from "@rotorsoft/act";
+ *
+ * try {
+ *   await app.do("updateTicket", target, payload);
+ * } catch (error) {
+ *   if (error instanceof StreamClosedError) {
+ *     console.error(`Stream ${error.stream} is closed`);
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link Act.close} for closing streams
+ */
+export declare class StreamClosedError extends Error {
+    /** The stream that is closed */
+    readonly stream: string;
+    constructor(
+    /** The stream that is closed */
+    stream: string);
+}
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/types/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,KAAK,EACL,OAAO,EACP,MAAM,EACN,OAAO,EACP,QAAQ,EACR,MAAM,EACP,MAAM,aAAa,CAAC;AAErB;;;;;;;;;GASG;AACH,eAAO,MAAM,MAAM;;;;;CAKT,CAAC;AAEX;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IAEtC,mEAAmE;aACnD,MAAM,EAAE,MAAM;IAC9B,iDAAiD;aACjC,OAAO,EAAE,GAAG;IAC5B,mCAAmC;aACnB,OAAO,EAAE,GAAG;;IAL5B,mEAAmE;IACnD,MAAM,EAAE,MAAM;IAC9B,iDAAiD;IACjC,OAAO,EAAE,GAAG;IAC5B,mCAAmC;IACnB,OAAO,EAAE,GAAG;CAK/B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoEG;AACH,qBAAa,cAAc,CACzB,MAAM,SAAS,MAAM,EACrB,OAAO,SAAS,OAAO,EACvB,QAAQ,SAAS,OAAO,EACxB,IAAI,SAAS,MAAM,QAAQ,EAC3B,MAAM,SAAS,KAAK,GAAG,KAAK,CAC5B,SAAQ,KAAK;IAEX,oCAAoC;IACpC,QAAQ,CAAC,MAAM,EAAE,IAAI;IACrB,2CAA2C;IAC3C,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC1C,0CAA0C;IAC1C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC;IAC/B,4DAA4D;IAC5D,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IAC5C,6DAA6D;IAC7D,QAAQ,CAAC,WAAW,EAAE,MAAM;;IAT5B,oCAAoC;IAC3B,MAAM,EAAE,IAAI;IACrB,2CAA2C;IAClC,OAAO,EAAE,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC1C,0CAA0C;IACjC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC;IAC/B,4DAA4D;IACnD,QAAQ,EAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IAC5C,6DAA6D;IACpD,WAAW,EAAE,MAAM;CAK/B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoEG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IAEvC,sDAAsD;aACtC,MAAM,EAAE,MAAM;IAC9B,8CAA8C;aAC9B,WAAW,EAAE,MAAM;IACnC,2CAA2C;aAC3B,MAAM,EAAE,OAAO,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,EAAE;IACzD,2CAA2C;aAC3B,eAAe,EAAE,MAAM;;IAPvC,sDAAsD;IACtC,MAAM,EAAE,MAAM;IAC9B,8CAA8C;IAC9B,WAAW,EAAE,MAAM;IACnC,2CAA2C;IAC3B,MAAM,EAAE,OAAO,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,EAAE;IACzD,2CAA2C;IAC3B,eAAe,EAAE,MAAM;CAe1C;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAExC,gCAAgC;aAChB,MAAM,EAAE,MAAM;;IAD9B,gCAAgC;IAChB,MAAM,EAAE,MAAM;CAKjC"}

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

@@ -0,0 +1,39 @@
+/**
+ * @packageDocumentation
+ * @module act/types
+ * Barrel file for Act Framework core types.
+ *
+ * Re-exports all major type definitions for actions, errors, ports, reactions, registries, and schemas.
+ * Also defines common environment and log level types/constants for configuration and logging.
+ *
+ * @remarks
+ * Import from this module to access all core framework types in one place.
+ */
+export type * from "./action.js";
+export * from "./errors.js";
+export type * from "./ports.js";
+export type * from "./reaction.js";
+export type * from "./registry.js";
+export * from "./schemas.js";
+/**
+ * Supported runtime environments for the framework.
+ * - `development`: Local development
+ * - `test`: Automated testing
+ * - `staging`: Pre-production
+ * - `production`: Live/production
+ */
+export declare const Environments: readonly ["development", "test", "staging", "production"];
+/**
+ * Type representing a valid environment string.
+ */
+export type Environment = (typeof Environments)[number];
+/**
+ * Supported log levels for framework logging.
+ * - `fatal`, `error`, `warn`, `info`, `debug`, `trace`
+ */
+export declare const LogLevels: readonly ["fatal", "error", "warn", "info", "debug", "trace"];
+/**
+ * Type representing a valid log level string.
+ */
+export type LogLevel = (typeof LogLevels)[number];
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,mBAAmB,aAAa,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,mBAAmB,YAAY,CAAC;AAChC,mBAAmB,eAAe,CAAC;AACnC,mBAAmB,eAAe,CAAC;AACnC,cAAc,cAAc,CAAC;AAE7B;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,2DAKf,CAAC;AAEX;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAExD;;;GAGG;AACH,eAAO,MAAM,SAAS,+DAOZ,CAAC;AAEX;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC"}