@rotorsoft/act 0.33.3 → 0.34.0

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

@@ -1,284 +0,0 @@
-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

@@ -1 +0,0 @@
-{"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

@@ -1,39 +0,0 @@
-/**
- * @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

@@ -1 +0,0 @@
-{"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"}