@unlaxer/tramli 1.8.0 → 1.9.0

package/dist/cjs/flow-engine.d.ts

@@ -1,12 +1,39 @@
 import type { FlowDefinition } from './flow-definition.js';
 import { FlowInstance } from './flow-instance.js';
 import type { InMemoryFlowStore } from './in-memory-flow-store.js';
+/** Log entry types for tramli's pluggable logger API. */
+export interface TransitionLogEntry {
+    flowId: string;
+    from: string | null;
+    to: string;
+    trigger: string;
+}
+export interface StateLogEntry {
+    flowId: string;
+    state: string;
+    key: string;
+    value: unknown;
+}
+export interface ErrorLogEntry {
+    flowId: string;
+    from: string | null;
+    to: string | null;
+    trigger: string;
+    cause: Error | null;
+}
 export declare class FlowEngine {
     private readonly store;
     private readonly strictMode;
+    private transitionLogger?;
+    private stateLogger?;
+    private errorLogger?;
     constructor(store: InMemoryFlowStore, options?: {
         strictMode?: boolean;
     });
+    setTransitionLogger(logger: ((entry: TransitionLogEntry) => void) | null): void;
+    setStateLogger(logger: ((entry: StateLogEntry) => void) | null): void;
+    setErrorLogger(logger: ((entry: ErrorLogEntry) => void) | null): void;
+    removeAllLoggers(): void;
     startFlow<S extends string>(definition: FlowDefinition<S>, sessionId: string, initialData: Map<string, unknown>): Promise<FlowInstance<S>>;
     resumeAndExecute<S extends string>(flowId: string, definition: FlowDefinition<S>, externalData?: Map<string, unknown>): Promise<FlowInstance<S>>;
     private executeAutoChain;

package/dist/cjs/flow-engine.js

@@ -8,10 +8,27 @@ const MAX_CHAIN_DEPTH = 10;
 class FlowEngine {
     store;
     strictMode;
+    transitionLogger;
+    stateLogger;
+    errorLogger;
     constructor(store, options) {
         this.store = store;
         this.strictMode = options?.strictMode ?? false;
     }
+    setTransitionLogger(logger) {
+        this.transitionLogger = logger ?? undefined;
+    }
+    setStateLogger(logger) {
+        this.stateLogger = logger ?? undefined;
+    }
+    setErrorLogger(logger) {
+        this.errorLogger = logger ?? undefined;
+    }
+    removeAllLoggers() {
+        this.transitionLogger = undefined;
+        this.stateLogger = undefined;
+        this.errorLogger = undefined;
+    }
     async startFlow(definition, sessionId, initialData) {
         const flowId = crypto.randomUUID();
         const ctx = new flow_context_js_1.FlowContext(flowId);
@@ -239,8 +256,16 @@ class FlowEngine {
         }
     }
     handleError(flow, fromState, cause) {
-        if (cause)
+        if (cause) {
             flow.setLastError(`${cause.constructor.name}: ${cause.message}`);
+            if (cause instanceof flow_error_js_1.FlowError) {
+                const available = new Set();
+                for (const [k] of flow.context.snapshot())
+                    available.add(k);
+                cause.withContextSnapshot(available, new Set());
+            }
+        }
+        this.errorLogger?.({ flowId: flow.id, from: fromState, to: null, trigger: 'error', cause: cause ?? null });
         const errorTarget = flow.definition.errorTransitions.get(fromState);
         if (errorTarget) {
             const from = flow.currentState;

package/dist/cjs/index.d.ts

@@ -1,5 +1,6 @@
 export { Tramli } from './tramli.js';
 export { FlowEngine } from './flow-engine.js';
+export type { TransitionLogEntry, StateLogEntry, ErrorLogEntry } from './flow-engine.js';
 export { FlowContext } from './flow-context.js';
 export { FlowInstance } from './flow-instance.js';
 export { FlowDefinition, Builder, FromBuilder, BranchBuilder, SubFlowBuilder } from './flow-definition.js';

package/dist/esm/flow-engine.d.ts

@@ -1,12 +1,39 @@
 import type { FlowDefinition } from './flow-definition.js';
 import { FlowInstance } from './flow-instance.js';
 import type { InMemoryFlowStore } from './in-memory-flow-store.js';
+/** Log entry types for tramli's pluggable logger API. */
+export interface TransitionLogEntry {
+    flowId: string;
+    from: string | null;
+    to: string;
+    trigger: string;
+}
+export interface StateLogEntry {
+    flowId: string;
+    state: string;
+    key: string;
+    value: unknown;
+}
+export interface ErrorLogEntry {
+    flowId: string;
+    from: string | null;
+    to: string | null;
+    trigger: string;
+    cause: Error | null;
+}
 export declare class FlowEngine {
     private readonly store;
     private readonly strictMode;
+    private transitionLogger?;
+    private stateLogger?;
+    private errorLogger?;
     constructor(store: InMemoryFlowStore, options?: {
         strictMode?: boolean;
     });
+    setTransitionLogger(logger: ((entry: TransitionLogEntry) => void) | null): void;
+    setStateLogger(logger: ((entry: StateLogEntry) => void) | null): void;
+    setErrorLogger(logger: ((entry: ErrorLogEntry) => void) | null): void;
+    removeAllLoggers(): void;
     startFlow<S extends string>(definition: FlowDefinition<S>, sessionId: string, initialData: Map<string, unknown>): Promise<FlowInstance<S>>;
     resumeAndExecute<S extends string>(flowId: string, definition: FlowDefinition<S>, externalData?: Map<string, unknown>): Promise<FlowInstance<S>>;
     private executeAutoChain;

package/dist/esm/flow-engine.js

@@ -5,10 +5,27 @@ const MAX_CHAIN_DEPTH = 10;
 export class FlowEngine {
     store;
     strictMode;
+    transitionLogger;
+    stateLogger;
+    errorLogger;
     constructor(store, options) {
         this.store = store;
         this.strictMode = options?.strictMode ?? false;
     }
+    setTransitionLogger(logger) {
+        this.transitionLogger = logger ?? undefined;
+    }
+    setStateLogger(logger) {
+        this.stateLogger = logger ?? undefined;
+    }
+    setErrorLogger(logger) {
+        this.errorLogger = logger ?? undefined;
+    }
+    removeAllLoggers() {
+        this.transitionLogger = undefined;
+        this.stateLogger = undefined;
+        this.errorLogger = undefined;
+    }
     async startFlow(definition, sessionId, initialData) {
         const flowId = crypto.randomUUID();
         const ctx = new FlowContext(flowId);
@@ -236,8 +253,16 @@ export class FlowEngine {
         }
     }
     handleError(flow, fromState, cause) {
-        if (cause)
+        if (cause) {
             flow.setLastError(`${cause.constructor.name}: ${cause.message}`);
+            if (cause instanceof FlowError) {
+                const available = new Set();
+                for (const [k] of flow.context.snapshot())
+                    available.add(k);
+                cause.withContextSnapshot(available, new Set());
+            }
+        }
+        this.errorLogger?.({ flowId: flow.id, from: fromState, to: null, trigger: 'error', cause: cause ?? null });
         const errorTarget = flow.definition.errorTransitions.get(fromState);
         if (errorTarget) {
             const from = flow.currentState;

package/dist/esm/index.d.ts

@@ -1,5 +1,6 @@
 export { Tramli } from './tramli.js';
 export { FlowEngine } from './flow-engine.js';
+export type { TransitionLogEntry, StateLogEntry, ErrorLogEntry } from './flow-engine.js';
 export { FlowContext } from './flow-context.js';
 export { FlowInstance } from './flow-instance.js';
 export { FlowDefinition, Builder, FromBuilder, BranchBuilder, SubFlowBuilder } from './flow-definition.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unlaxer/tramli",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "Constrained flow engine — state machines that prevent invalid transitions at build time",
   "type": "module",
   "exports": {