@hardlydifficult/workflow-engine 1.0.3 → 1.0.5

package/README.md

@@ -75,9 +75,25 @@ engine.isTerminal; // true
 | `transition(to, updater?)` | Change status, optionally mutate data. Validates transition, persists immediately. |
 | `update(updater)` | Mutate data without changing status. Persists immediately. |
 | `save()` | Force-save current state to disk. |
+| `cursor(selector)` | Create a `DataCursor` for safe nested data access with `get()`, `find()`, `update()`. |
 | `canTransition(to)` | Check if a transition is allowed from current status. |
 | `allowedTransitions()` | List statuses reachable from current status. |
 
+### `cursor<TItem>(selector)`
+
+Creates a reusable cursor for safe navigation into nested engine data. Define the selector once, then use `get()`, `find()`, or `update()` without repeating navigation logic.
+
+```typescript
+interface Data { items: Array<{ name: string; done: boolean }>; currentIndex?: number; }
+
+const item = engine.cursor((d) => d.items[d.currentIndex ?? -1]);
+
+item.get();       // returns item or throws "Cursor target not found"
+item.find();      // returns item or undefined
+await item.update((it) => { it.done = true; });            // persists, no-op if undefined
+await item.update((it, d) => { d.currentIndex = undefined; }); // access parent data too
+```
+
 ### Updater Pattern
 
 `transition()` and `update()` accept an updater callback that receives a `structuredClone` of the data. Mutate it directly — if the updater throws, nothing changes.

package/dist/DataCursor.d.ts

@@ -0,0 +1,22 @@
+import type { WorkflowEngine } from "./WorkflowEngine.js";
+/**
+ * Reusable cursor for safe navigation into nested engine data.
+ *
+ * Define a selector once, then use `get()` / `find()` / `update()` to
+ * interact with the selected item without repeating navigation logic.
+ */
+export declare class DataCursor<TStatus extends string, TData, TItem> {
+    private readonly engine;
+    private readonly selector;
+    constructor(engine: WorkflowEngine<TStatus, TData>, selector: (data: TData) => TItem | undefined);
+    /** Get the selected item. Throws if the selector returns undefined. */
+    get(): TItem;
+    /** Get the selected item, or undefined. */
+    find(): TItem | undefined;
+    /**
+     * Update the selected item (and optionally the parent data).
+     * No-op if the selector returns undefined.
+     */
+    update(updater: (item: TItem, data: TData) => void): Promise<void>;
+}
+//# sourceMappingURL=DataCursor.d.ts.map

package/dist/DataCursor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DataCursor.d.ts","sourceRoot":"","sources":["../src/DataCursor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D;;;;;GAKG;AACH,qBAAa,UAAU,CAAC,OAAO,SAAS,MAAM,EAAE,KAAK,EAAE,KAAK;IAC1D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiC;IACxD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqC;gBAG5D,MAAM,EAAE,cAAc,CAAC,OAAO,EAAE,KAAK,CAAC,EACtC,QAAQ,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,KAAK,GAAG,SAAS;IAM9C,uEAAuE;IACvE,GAAG,IAAI,KAAK;IAQZ,2CAA2C;IAC3C,IAAI,IAAI,KAAK,GAAG,SAAS;IAIzB;;;OAGG;IACG,MAAM,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;CAQzE"}

package/dist/DataCursor.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DataCursor = void 0;
+/**
+ * Reusable cursor for safe navigation into nested engine data.
+ *
+ * Define a selector once, then use `get()` / `find()` / `update()` to
+ * interact with the selected item without repeating navigation logic.
+ */
+class DataCursor {
+    engine;
+    selector;
+    constructor(engine, selector) {
+        this.engine = engine;
+        this.selector = selector;
+    }
+    /** Get the selected item. Throws if the selector returns undefined. */
+    get() {
+        const item = this.selector(this.engine.data);
+        if (item === undefined) {
+            throw new Error("Cursor target not found");
+        }
+        return item;
+    }
+    /** Get the selected item, or undefined. */
+    find() {
+        return this.selector(this.engine.data);
+    }
+    /**
+     * Update the selected item (and optionally the parent data).
+     * No-op if the selector returns undefined.
+     */
+    async update(updater) {
+        await this.engine.update((d) => {
+            const item = this.selector(d);
+            if (item !== undefined) {
+                updater(item, d);
+            }
+        });
+    }
+}
+exports.DataCursor = DataCursor;
+//# sourceMappingURL=DataCursor.js.map

package/dist/DataCursor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DataCursor.js","sourceRoot":"","sources":["../src/DataCursor.ts"],"names":[],"mappings":";;;AAEA;;;;;GAKG;AACH,MAAa,UAAU;IACJ,MAAM,CAAiC;IACvC,QAAQ,CAAqC;IAE9D,YACE,MAAsC,EACtC,QAA4C;QAE5C,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;IAED,uEAAuE;IACvE,GAAG;QACD,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,IAAa,CAAC,CAAC;QACtD,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;QAC7C,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,2CAA2C;IAC3C,IAAI;QACF,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,IAAa,CAAC,CAAC;IAClD,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,MAAM,CAAC,OAA2C;QACtD,MAAM,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE;YAC7B,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;YAC9B,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;gBACvB,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;YACnB,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;CACF;AAtCD,gCAsCC"}

package/dist/WorkflowEngine.d.ts

@@ -1,4 +1,5 @@
-import type { DataUpdater, WorkflowEngineOptions } from "./types.js";
+import { DataCursor } from "./DataCursor.js";
+import type { ChangeListener, DataUpdater, WorkflowEngineOptions, WorkflowSnapshot } from "./types.js";
 /**
  * General-purpose state machine with typed statuses, validated transitions,
  * and persistent state via StateTracker.
@@ -7,6 +8,7 @@ export declare class WorkflowEngine<TStatus extends string, TData> {
     private readonly tracker;
     private readonly transitions;
     private readonly onTransitionCb?;
+    private readonly listeners;
     private loaded;
     constructor(options: WorkflowEngineOptions<TStatus, TData>);
     /** Current status */
@@ -42,6 +44,15 @@ export declare class WorkflowEngine<TStatus extends string, TData> {
      * On success, state is persisted immediately.
      */
     update(updater: DataUpdater<TData>): Promise<void>;
+    /** Create a cursor for safe navigation into nested data. */
+    cursor<TItem>(selector: (data: TData) => TItem | undefined): DataCursor<TStatus, TData, TItem>;
+    /**
+     * Register a listener for all engine events (transition, update, load).
+     * Returns an unsubscribe function.
+     */
+    on(listener: ChangeListener<TStatus, TData>): () => void;
+    /** Return a read-only snapshot of the engine's current state. */
+    toSnapshot(): WorkflowSnapshot<TStatus, TData>;
     /** Check if a specific transition is allowed from current status */
     canTransition(to: TStatus): boolean;
     /** Get statuses reachable from current status */

package/dist/WorkflowEngine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WorkflowEngine.d.ts","sourceRoot":"","sources":["../src/WorkflowEngine.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,WAAW,EAIX,qBAAqB,EACtB,MAAM,YAAY,CAAC;AAEpB;;;GAGG;AACH,qBAAa,cAAc,CAAC,OAAO,SAAS,MAAM,EAAE,KAAK;IACvD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA+C;IACvE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAyB;IACrD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAEtB;IACV,OAAO,CAAC,MAAM,CAAS;gBAEX,OAAO,EAAE,qBAAqB,CAAC,OAAO,EAAE,KAAK,CAAC;IAwB1D,qBAAqB;IACrB,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED,+BAA+B;IAC/B,IAAI,IAAI,IAAI,QAAQ,CAAC,KAAK,CAAC,CAE1B;IAED,qCAAqC;IACrC,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,wCAAwC;IACxC,IAAI,YAAY,IAAI,OAAO,CAE1B;IAED,qDAAqD;IACrD,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,uEAAuE;IACvE,IAAI,UAAU,IAAI,OAAO,CAExB;IAED;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAM3B;;;;;;OAMG;IACG,UAAU,CAAC,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,WAAW,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IA+B1E;;;;;;OAMG;IACG,MAAM,CAAC,OAAO,EAAE,WAAW,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAexD,oEAAoE;IACpE,aAAa,CAAC,EAAE,EAAE,OAAO,GAAG,OAAO;IAInC,iDAAiD;IACjD,kBAAkB,IAAI,SAAS,OAAO,EAAE;IAIxC,uCAAuC;IACjC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B,OAAO,CAAC,SAAS;CAclB"}
+{"version":3,"file":"WorkflowEngine.d.ts","sourceRoot":"","sources":["../src/WorkflowEngine.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,KAAK,EACV,cAAc,EACd,WAAW,EAIX,qBAAqB,EACrB,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAEpB;;;GAGG;AACH,qBAAa,cAAc,CAAC,OAAO,SAAS,MAAM,EAAE,KAAK;IACvD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA+C;IACvE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAyB;IACrD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAEtB;IACV,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA6C;IACvE,OAAO,CAAC,MAAM,CAAS;gBAEX,OAAO,EAAE,qBAAqB,CAAC,OAAO,EAAE,KAAK,CAAC;IAwB1D,qBAAqB;IACrB,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED,+BAA+B;IAC/B,IAAI,IAAI,IAAI,QAAQ,CAAC,KAAK,CAAC,CAE1B;IAED,qCAAqC;IACrC,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,wCAAwC;IACxC,IAAI,YAAY,IAAI,OAAO,CAE1B;IAED,qDAAqD;IACrD,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,uEAAuE;IACvE,IAAI,UAAU,IAAI,OAAO,CAExB;IAED;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAM3B;;;;;;OAMG;IACG,UAAU,CAAC,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,WAAW,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IA+B1E;;;;;;OAMG;IACG,MAAM,CAAC,OAAO,EAAE,WAAW,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAexD,4DAA4D;IAC5D,MAAM,CAAC,KAAK,EACV,QAAQ,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,KAAK,GAAG,SAAS,GAC3C,UAAU,CAAC,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC;IAIpC;;;OAGG;IACH,EAAE,CAAC,QAAQ,EAAE,cAAc,CAAC,OAAO,EAAE,KAAK,CAAC,GAAG,MAAM,IAAI;IAOxD,iEAAiE;IACjE,UAAU,IAAI,gBAAgB,CAAC,OAAO,EAAE,KAAK,CAAC;IAS9C,oEAAoE;IACpE,aAAa,CAAC,EAAE,EAAE,OAAO,GAAG,OAAO;IAInC,iDAAiD;IACjD,kBAAkB,IAAI,SAAS,OAAO,EAAE;IAIxC,uCAAuC;IACjC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B,OAAO,CAAC,SAAS;CAkBlB"}

package/dist/WorkflowEngine.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WorkflowEngine = void 0;
 const state_tracker_1 = require("@hardlydifficult/state-tracker");
+const DataCursor_js_1 = require("./DataCursor.js");
 /**
  * General-purpose state machine with typed statuses, validated transitions,
  * and persistent state via StateTracker.
@@ -10,6 +11,7 @@ class WorkflowEngine {
     tracker;
     transitions;
     onTransitionCb;
+    listeners = new Set();
     loaded = false;
     constructor(options) {
         const { transitions, initialStatus } = options;
@@ -109,6 +111,29 @@ class WorkflowEngine {
         await this.tracker.saveAsync();
         this.emitEvent("update");
     }
+    /** Create a cursor for safe navigation into nested data. */
+    cursor(selector) {
+        return new DataCursor_js_1.DataCursor(this, selector);
+    }
+    /**
+     * Register a listener for all engine events (transition, update, load).
+     * Returns an unsubscribe function.
+     */
+    on(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    /** Return a read-only snapshot of the engine's current state. */
+    toSnapshot() {
+        return {
+            status: this.status,
+            data: structuredClone(this.data),
+            updatedAt: this.updatedAt,
+            isTerminal: this.isTerminal,
+        };
+    }
     /** Check if a specific transition is allowed from current status */
     canTransition(to) {
         return this.transitions[this.status].includes(to);
@@ -122,14 +147,18 @@ class WorkflowEngine {
         await this.tracker.saveAsync();
     }
     emitEvent(type, from, to) {
-        this.onTransitionCb?.({
+        const event = {
             type,
             from,
             to,
             status: this.status,
             data: this.data,
             timestamp: new Date().toISOString(),
-        });
+        };
+        this.onTransitionCb?.(event);
+        for (const listener of this.listeners) {
+            listener(event);
+        }
     }
 }
 exports.WorkflowEngine = WorkflowEngine;

package/dist/WorkflowEngine.js.map

@@ -1 +1 @@
-{"version":3,"file":"WorkflowEngine.js","sourceRoot":"","sources":["../src/WorkflowEngine.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"WorkflowEngine.js","sourceRoot":"","sources":["../src/WorkflowEngine.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+export { DataCursor } from "./DataCursor.js";
 export { WorkflowEngine } from "./WorkflowEngine.js";
-export type { WorkflowEngineOptions, TransitionEvent, TransitionMap, DataUpdater, } from "./types.js";
+export type { ChangeListener, WorkflowEngineOptions, WorkflowSnapshot, TransitionEvent, TransitionMap, DataUpdater, } from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,YAAY,EACV,qBAAqB,EACrB,eAAe,EACf,aAAa,EACb,WAAW,GACZ,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,YAAY,EACV,cAAc,EACd,qBAAqB,EACrB,gBAAgB,EAChB,eAAe,EACf,aAAa,EACb,WAAW,GACZ,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WorkflowEngine = void 0;
+exports.WorkflowEngine = exports.DataCursor = void 0;
+var DataCursor_js_1 = require("./DataCursor.js");
+Object.defineProperty(exports, "DataCursor", { enumerable: true, get: function () { return DataCursor_js_1.DataCursor; } });
 var WorkflowEngine_js_1 = require("./WorkflowEngine.js");
 Object.defineProperty(exports, "WorkflowEngine", { enumerable: true, get: function () { return WorkflowEngine_js_1.WorkflowEngine; } });
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,yDAAqD;AAA5C,mHAAA,cAAc,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,iDAA6C;AAApC,2GAAA,UAAU,OAAA;AACnB,yDAAqD;AAA5C,mHAAA,cAAc,OAAA"}

package/dist/types.d.ts

@@ -39,6 +39,21 @@ export interface WorkflowEngineOptions<TStatus extends string, TData> {
     /** Called on transitions, updates, and loads */
     onTransition?: (event: TransitionEvent<TStatus, TData>) => void;
 }
+/**
+ * Listener callback for engine change events.
+ * Receives the same event as onTransition.
+ */
+export type ChangeListener<TStatus extends string, TData> = (event: TransitionEvent<TStatus, TData>) => void;
+/**
+ * Read-only snapshot of an engine's current state.
+ * Useful for serialization or external consumers.
+ */
+export interface WorkflowSnapshot<TStatus extends string, TData> {
+    status: TStatus;
+    data: Readonly<TData>;
+    updatedAt: string;
+    isTerminal: boolean;
+}
 /**
  * Internal persisted shape: status + data + updatedAt together.
  */

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,aAAa,CAAC,OAAO,SAAS,MAAM,IAAI,MAAM,CACxD,OAAO,EACP,SAAS,OAAO,EAAE,CACnB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,WAAW,CAAC,KAAK,IAAI,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;AAExD;;GAEG;AACH,MAAM,WAAW,eAAe,CAAC,OAAO,SAAS,MAAM,EAAE,KAAK;IAC5D,IAAI,EAAE,YAAY,GAAG,QAAQ,GAAG,MAAM,CAAC;IACvC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB,CAAC,OAAO,SAAS,MAAM,EAAE,KAAK;IAClE,8CAA8C;IAC9C,GAAG,EAAE,MAAM,CAAC;IACZ,kDAAkD;IAClD,aAAa,EAAE,OAAO,CAAC;IACvB,gDAAgD;IAChD,WAAW,EAAE,KAAK,CAAC;IACnB,kEAAkE;IAClE,WAAW,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;IACpC,sCAAsC;IACtC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,8CAA8C;IAC9C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gDAAgD;IAChD,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,eAAe,CAAC,OAAO,EAAE,KAAK,CAAC,KAAK,IAAI,CAAC;CACjE;AAED;;GAEG;AACH,MAAM,WAAW,cAAc,CAAC,OAAO,SAAS,MAAM,EAAE,KAAK;IAC3D,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,KAAK,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;CACnB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,aAAa,CAAC,OAAO,SAAS,MAAM,IAAI,MAAM,CACxD,OAAO,EACP,SAAS,OAAO,EAAE,CACnB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,WAAW,CAAC,KAAK,IAAI,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;AAExD;;GAEG;AACH,MAAM,WAAW,eAAe,CAAC,OAAO,SAAS,MAAM,EAAE,KAAK;IAC5D,IAAI,EAAE,YAAY,GAAG,QAAQ,GAAG,MAAM,CAAC;IACvC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB,CAAC,OAAO,SAAS,MAAM,EAAE,KAAK;IAClE,8CAA8C;IAC9C,GAAG,EAAE,MAAM,CAAC;IACZ,kDAAkD;IAClD,aAAa,EAAE,OAAO,CAAC;IACvB,gDAAgD;IAChD,WAAW,EAAE,KAAK,CAAC;IACnB,kEAAkE;IAClE,WAAW,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;IACpC,sCAAsC;IACtC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,8CAA8C;IAC9C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gDAAgD;IAChD,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,eAAe,CAAC,OAAO,EAAE,KAAK,CAAC,KAAK,IAAI,CAAC;CACjE;AAED;;;GAGG;AACH,MAAM,MAAM,cAAc,CAAC,OAAO,SAAS,MAAM,EAAE,KAAK,IAAI,CAC1D,KAAK,EAAE,eAAe,CAAC,OAAO,EAAE,KAAK,CAAC,KACnC,IAAI,CAAC;AAEV;;;GAGG;AACH,MAAM,WAAW,gBAAgB,CAAC,OAAO,SAAS,MAAM,EAAE,KAAK;IAC7D,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,OAAO,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc,CAAC,OAAO,SAAS,MAAM,EAAE,KAAK;IAC3D,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,KAAK,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;CACnB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hardlydifficult/workflow-engine",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
@@ -15,7 +15,7 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@hardlydifficult/state-tracker": "2.0.2"
+    "@hardlydifficult/state-tracker": "file:../state-tracker"
   },
   "devDependencies": {
     "@types/node": "20.19.31",
@@ -23,7 +23,7 @@
     "vitest": "1.6.1"
   },
   "peerDependencies": {
-    "@hardlydifficult/state-tracker": "2.0.2"
+    "@hardlydifficult/state-tracker": ">=2.0.0"
   },
   "engines": {
     "node": ">=18.0.0"