@yieldstar/core 0.4.5 → 0.5.0

package/dist/index.js

@@ -1,4 +1,368 @@
-// @bun
+// src/base/store.ts
+function defineStore(name, schema) {
+  return { name, schema };
+}
+
+class StoreClient {
+  store(definition, id) {
+    return {
+      get: () => this.getStore({
+        definition,
+        id
+      }),
+      update: (updater) => this.updateStore({
+        definition,
+        id,
+        updater
+      }),
+      updateFrom: (snapshot, updater) => this.updateStoreFrom({
+        definition,
+        id,
+        snapshot,
+        updater
+      }),
+      deleteFrom: (snapshot) => this.deleteStoreFrom({
+        definition,
+        id,
+        snapshot
+      })
+    };
+  }
+}
+
+class CasStoreClient extends StoreClient {
+  async updateStore(params) {
+    const applied = await this.getAppliedResult(params);
+    if (applied) {
+      return applied.result;
+    }
+    let snapshot = await this.getStore({
+      definition: params.definition,
+      id: params.id
+    });
+    while (true) {
+      const prepared = await prepareStoreUpdate(params.definition, snapshot, params.updater);
+      const result = {
+        state: cloneStoreState(prepared.nextState),
+        previousVersion: snapshot.version,
+        version: snapshot.version + 1
+      };
+      const committed = await this.commitStoreMutation({
+        definition: params.definition,
+        id: params.id,
+        expected: snapshot,
+        nextState: prepared.nextState,
+        changedPaths: prepared.changedPaths,
+        stepId: params.stepId,
+        result
+      });
+      if (committed.status === "committed")
+        return result;
+      if (committed.status === "already-applied") {
+        return committed.result;
+      }
+      snapshot = committed.snapshot;
+    }
+  }
+  async updateStoreFrom(params) {
+    const applied = await this.getAppliedResult(params);
+    if (applied) {
+      return applied.result;
+    }
+    assertStoreSnapshotInstanceId(params.snapshot);
+    const current = await this.getStore({
+      definition: params.definition,
+      id: params.id
+    });
+    if (!sameStoreVersion(current, params.snapshot)) {
+      return storeUpdateConflict(params.snapshot, current);
+    }
+    const prepared = await prepareStoreUpdate(params.definition, params.snapshot, params.updater);
+    const result = {
+      updated: true,
+      state: cloneStoreState(prepared.nextState),
+      previousVersion: params.snapshot.version,
+      version: params.snapshot.version + 1
+    };
+    const committed = await this.commitStoreMutation({
+      definition: params.definition,
+      id: params.id,
+      expected: params.snapshot,
+      nextState: prepared.nextState,
+      changedPaths: prepared.changedPaths,
+      stepId: params.stepId,
+      result
+    });
+    if (committed.status === "committed")
+      return result;
+    if (committed.status === "already-applied") {
+      return committed.result;
+    }
+    return storeUpdateConflict(params.snapshot, committed.snapshot);
+  }
+  async takeFromStore(params) {
+    const applied = await this.getAppliedResult(params);
+    if (applied)
+      return applied.result;
+    let snapshot = await this.getStore({
+      definition: params.definition,
+      id: params.id
+    });
+    while (true) {
+      const previousState = cloneStoreState(snapshot.state);
+      const draft = cloneStoreState(previousState);
+      const tracked = trackStoreUpdater(draft);
+      const { result: selectedResult, readPaths } = trackStoreSelector(tracked.draft, params.selector);
+      if (!isStoreSelectorMatch(selectedResult)) {
+        return {
+          matched: false,
+          instanceId: snapshot.instanceId,
+          version: snapshot.version,
+          readPaths
+        };
+      }
+      const selected = unwrapTrackedValue(selectedResult);
+      assertSynchronousClaim(params.claim(tracked.draft, selected));
+      const prepared = await finalizeStoreMutation({
+        definition: params.definition,
+        previousState,
+        draft,
+        tracked
+      });
+      const selectedSnapshot = cloneStoreState(selected);
+      const result = {
+        matched: true,
+        selected: selectedSnapshot,
+        instanceId: snapshot.instanceId,
+        version: snapshot.version + 1
+      };
+      const committed = await this.commitStoreMutation({
+        definition: params.definition,
+        id: params.id,
+        expected: snapshot,
+        nextState: prepared.nextState,
+        changedPaths: prepared.changedPaths,
+        stepId: params.stepId,
+        result
+      });
+      if (committed.status === "committed")
+        return result;
+      if (committed.status === "already-applied") {
+        return committed.result;
+      }
+      snapshot = committed.snapshot;
+    }
+  }
+  getAppliedResult(params) {
+    return params.stepId ? this.getAppliedStoreStep({
+      definition: params.definition,
+      id: params.id,
+      stepId: params.stepId
+    }) : Promise.resolve(undefined);
+  }
+}
+async function prepareStoreUpdate(definition, snapshot, updater) {
+  const previousState = cloneStoreState(snapshot.state);
+  const draft = cloneStoreState(previousState);
+  const tracked = trackStoreUpdater(draft);
+  const updated = updater(tracked.draft);
+  assertSynchronousUpdater(updated);
+  const returned = updated === undefined ? undefined : unwrapTrackedValue(updated);
+  return finalizeStoreMutation({
+    definition,
+    previousState,
+    draft,
+    tracked,
+    replacement: returned
+  });
+}
+async function finalizeStoreMutation(params) {
+  const isReplacement = params.replacement !== undefined && params.replacement !== params.draft;
+  const nextState = await validateStoreState(params.definition, isReplacement ? params.replacement : params.draft);
+  const changedPaths = !isReplacement && nextState === params.draft ? params.tracked.writePaths() : diffStorePaths(params.previousState, nextState);
+  return { nextState, changedPaths };
+}
+function sameStoreVersion(left, right) {
+  return left.instanceId === right.instanceId && left.version === right.version;
+}
+function assertStoreSnapshotInstanceId(snapshot) {
+  if (!snapshot.instanceId) {
+    throw new Error("Store snapshot is missing instanceId; read a fresh snapshot");
+  }
+}
+function storeUpdateConflict(expected, actual) {
+  return {
+    updated: false,
+    expectedInstanceId: expected.instanceId,
+    actualInstanceId: actual.instanceId,
+    expectedVersion: expected.version,
+    actualVersion: actual.version
+  };
+}
+function isStoreSelectorMatch(result) {
+  return result !== undefined && result !== null && result !== false;
+}
+function assertSynchronousClaim(claimResult) {
+  if (claimResult && typeof claimResult.then === "function") {
+    throw new Error("Store take claims must be synchronous");
+  }
+}
+function assertSynchronousUpdater(updaterResult) {
+  if (updaterResult && typeof updaterResult.then === "function") {
+    throw new Error("Store updaters must be synchronous");
+  }
+}
+async function validateStoreState(definition, state) {
+  const result = await definition.schema["~standard"].validate(state);
+  if ("issues" in result && result.issues) {
+    const messages = result.issues.map((issue) => issue.message).join("; ");
+    throw new Error(`Invalid store state for "${definition.name}": ${messages}`);
+  }
+  return result.value;
+}
+function cloneStoreState(state) {
+  if (typeof structuredClone === "function") {
+    try {
+      return structuredClone(state);
+    } catch {}
+  }
+  return JSON.parse(JSON.stringify(state));
+}
+function diffStorePaths(previous, next) {
+  const paths = [];
+  function visit(left, right, path) {
+    if (Object.is(left, right))
+      return;
+    if (!isDiffableObject(left) || !isDiffableObject(right)) {
+      paths.push(path);
+      return;
+    }
+    const keys = new Set([...Object.keys(left), ...Object.keys(right)]);
+    for (const key of keys) {
+      visit(left[key], right[key], [...path, arrayKeyToPathSegment(key)]);
+    }
+  }
+  visit(previous, next, []);
+  return collapseStorePaths(paths);
+}
+var TRACKING_TARGET = Symbol("yieldstar.trackingTarget");
+function unwrapTrackedValue(value) {
+  if (isDiffableObject(value)) {
+    const target = value[TRACKING_TARGET];
+    if (target !== undefined)
+      return target;
+  }
+  return value;
+}
+function trackStoreSelector(state, selector) {
+  const paths = [];
+  const proxies = new WeakMap;
+  function track(value, path) {
+    if (!isDiffableObject(value))
+      return value;
+    const cached = proxies.get(value);
+    if (cached)
+      return cached;
+    const proxy = new Proxy(value, {
+      get(target, property, receiver) {
+        if (typeof property === "symbol") {
+          if (property === TRACKING_TARGET)
+            return target;
+          return Reflect.get(target, property, receiver);
+        }
+        const nextPath = [...path, arrayKeyToPathSegment(property)];
+        if (nextPath.length > 0) {
+          paths.push(nextPath);
+        }
+        const child = Reflect.get(target, property, receiver);
+        return track(child, nextPath);
+      },
+      set() {
+        throw new Error("Store selectors must not mutate state");
+      },
+      deleteProperty() {
+        throw new Error("Store selectors must not mutate state");
+      }
+    });
+    proxies.set(value, proxy);
+    return proxy;
+  }
+  const result = selector(track(state, []));
+  return {
+    result,
+    readPaths: collapseStorePaths(paths)
+  };
+}
+function trackStoreUpdater(target) {
+  const paths = [];
+  const proxies = new WeakMap;
+  function record(path, property) {
+    if (typeof property === "symbol") {
+      paths.push(path);
+      return;
+    }
+    paths.push([...path, arrayKeyToPathSegment(String(property))]);
+  }
+  function track(value, path) {
+    if (!isDiffableObject(value))
+      return value;
+    const cached = proxies.get(value);
+    if (cached)
+      return cached;
+    const proxy = new Proxy(value, {
+      get(target2, property, receiver) {
+        if (typeof property === "symbol") {
+          if (property === TRACKING_TARGET)
+            return target2;
+          return Reflect.get(target2, property, receiver);
+        }
+        const child = Reflect.get(target2, property);
+        return track(child, [...path, arrayKeyToPathSegment(property)]);
+      },
+      set(target2, property, value2) {
+        record(path, property);
+        return Reflect.set(target2, property, unwrapTrackedValue(value2));
+      },
+      deleteProperty(target2, property) {
+        record(path, property);
+        return Reflect.deleteProperty(target2, property);
+      },
+      defineProperty(target2, property, descriptor) {
+        record(path, property);
+        if ("value" in descriptor) {
+          descriptor = { ...descriptor, value: unwrapTrackedValue(descriptor.value) };
+        }
+        return Reflect.defineProperty(target2, property, descriptor);
+      }
+    });
+    proxies.set(value, proxy);
+    return proxy;
+  }
+  return {
+    draft: track(target, []),
+    writePaths: () => collapseStorePaths(paths)
+  };
+}
+function storePathsIntersect(readPaths, writePaths) {
+  return readPaths.some((readPath) => writePaths.some((writePath) => isPathPrefix(readPath, writePath) || isPathPrefix(writePath, readPath)));
+}
+function collapseStorePaths(paths) {
+  const unique = new Map(paths.map((path) => [path.join("\x00"), path]));
+  return [...unique.values()];
+}
+function isPathPrefix(prefix, path) {
+  if (prefix.length > path.length)
+    return false;
+  return prefix.every((segment, index) => segment === path[index]);
+}
+function isDiffableObject(value) {
+  return typeof value === "object" && value !== null;
+}
+function arrayKeyToPathSegment(key) {
+  if (/^(0|[1-9]\d*)$/.test(key))
+    return Number(key);
+  return key;
+}
 // src/base/step.ts
 class StepResponse {
 }
@@ -53,6 +417,14 @@ class WorkflowDelay extends StepResponse {
   }
 }
 
+class StepStoreWait extends StepResponse {
+  static type = "store-wait";
+  type = "store-wait";
+  constructor() {
+    super();
+  }
+}
+
 class WorkflowRestart extends StepResponse {
   static type = "workflow-restart";
   type = "workflow-restart";
@@ -90,10 +462,12 @@ class StepDelay extends StepResponse {
 class WorkflowRunner {
   heapClient;
   schedulerClient;
+  storeClient;
   router;
   constructor(params) {
     this.heapClient = params.heapClient;
     this.schedulerClient = params.schedulerClient;
+    this.storeClient = params.storeClient;
     this.router = params.router;
   }
   run = async (event, logger) => {
@@ -113,6 +487,8 @@ class WorkflowRunner {
         case "workflow-delay":
           this.schedulerClient.requestWakeUp(event, response.resumeIn);
           break;
+        case "store-wait":
+          break;
       }
     } catch (err) {
       throw err;
@@ -123,6 +499,7 @@ class WorkflowRunner {
     const workflowIterator = workflow({
       event,
       heapClient: this.heapClient,
+      storeClient: this.storeClient,
       logger
     });
     const iteratorResult = await workflowIterator.next();
@@ -133,6 +510,9 @@ class WorkflowRunner {
     if (stageResponse instanceof StepDelay) {
       return new WorkflowDelay(stageResponse.resumeIn - Date.now());
     }
+    if (stageResponse instanceof StepStoreWait) {
+      return stageResponse;
+    }
     throw new Error("Workflow runner critical error. This is likely because your worklow and worker are referencing different versions of @yieldstar/core.");
   }
 }
@@ -148,7 +528,13 @@ function errorWithOriginalStack(error, fn) {
 class ReadOnlyMap {
   sourceMap;
   constructor(sourceMap) {
-    this.sourceMap = sourceMap;
+    if (sourceMap instanceof Map) {
+      this.sourceMap = sourceMap;
+    } else if (typeof sourceMap === "object" && sourceMap !== null) {
+      this.sourceMap = new Map(Object.entries(sourceMap));
+    } else {
+      this.sourceMap = new Map;
+    }
   }
   get(key) {
     return this.sourceMap.get(key);
@@ -207,11 +593,24 @@ class FreezableMap extends Map {
   }
 }
 export {
+  validateStoreState,
+  unwrapTrackedValue,
+  trackStoreUpdater,
+  trackStoreSelector,
+  storePathsIntersect,
+  isStoreSelectorMatch,
   errorWithOriginalStack,
+  diffStorePaths,
+  defineStore,
+  cloneStoreState,
+  assertSynchronousUpdater,
+  assertSynchronousClaim,
   WorkflowRunner,
   WorkflowResult,
   WorkflowRestart,
   WorkflowDelay,
+  StoreClient,
+  StepStoreWait,
   StepResult,
   StepResponse,
   StepKey,
@@ -220,5 +619,6 @@ export {
   StepDelay,
   StepCacheCheck,
   ReadOnlyMap,
-  FreezableMap
+  FreezableMap,
+  CasStoreClient
 };

package/dist/lib/workflow-runner.d.ts

@@ -1,12 +1,14 @@
 import type { Logger } from "pino";
-import type { WorkflowGenerator, HeapClient, SchedulerClient, EventProcessor } from "..";
+import type { WorkflowGenerator, HeapClient, SchedulerClient, StoreClient, EventProcessor } from "..";
 export declare class WorkflowRunner<Router extends Record<string, WorkflowGenerator<any, any, any>>> {
     private heapClient;
     private schedulerClient;
+    private storeClient;
     private router;
     constructor(params: {
         heapClient: HeapClient;
         schedulerClient: SchedulerClient;
+        storeClient: StoreClient;
         router: Router;
         logger: Logger;
     });

package/dist/lib/workflow-runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workflow-runner.d.ts","sourceRoot":"","sources":["../../src/lib/workflow-runner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AACnC,OAAO,KAAK,EACV,iBAAiB,EACjB,UAAU,EACV,eAAe,EACf,cAAc,EAGf,MAAM,IAAI,CAAC;AAIZ,qBAAa,cAAc,CACzB,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;IAE/D,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,MAAM,CAAS;gBAEX,MAAM,EAAE;QAClB,UAAU,EAAE,UAAU,CAAC;QACvB,eAAe,EAAE,eAAe,CAAC;QACjC,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,CAAC;KAChB;IAMD,GAAG,EAAE,cAAc,CA0BjB;YAEY,YAAY;CAiC3B"}
+{"version":3,"file":"workflow-runner.d.ts","sourceRoot":"","sources":["../../src/lib/workflow-runner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AACnC,OAAO,KAAK,EACV,iBAAiB,EACjB,UAAU,EACV,eAAe,EACf,WAAW,EACX,cAAc,EAGf,MAAM,IAAI,CAAC;AAIZ,qBAAa,cAAc,CACzB,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;IAE/D,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,MAAM,CAAS;gBAEX,MAAM,EAAE;QAClB,UAAU,EAAE,UAAU,CAAC;QACvB,eAAe,EAAE,eAAe,CAAC;QACjC,WAAW,EAAE,WAAW,CAAC;QACzB,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,CAAC;KAChB;IAOD,GAAG,EAAE,cAAc,CA6BjB;YAEY,YAAY;CAsC3B"}

package/dist/utils/map.d.ts

@@ -1,6 +1,6 @@
 export declare class ReadOnlyMap<K, V> implements ReadonlyMap<K, V> {
     private sourceMap;
-    constructor(sourceMap: Map<K, V>);
+    constructor(sourceMap: Map<K, V> | Record<any, any> | undefined);
     get(key: K): V | undefined;
     has(key: K): boolean;
     get size(): number;

package/dist/utils/map.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"map.d.ts","sourceRoot":"","sources":["../../src/utils/map.ts"],"names":[],"mappings":"AAEA,qBAAa,WAAW,CAAC,CAAC,EAAE,CAAC,CAAE,YAAW,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC;IACzD,OAAO,CAAC,SAAS,CAAY;gBAEjB,SAAS,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC;IAIhC,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS;IAI1B,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,OAAO;IAIpB,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,OAAO,IAAI,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAI9B,IAAI,IAAI,WAAW,CAAC,CAAC,CAAC;IAItB,MAAM,IAAI,WAAW,CAAC,CAAC,CAAC;IAIxB,OAAO,CACL,UAAU,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,IAAI,EACtD,OAAO,CAAC,EAAE,GAAG,GACZ,IAAI;IAIP,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;CAGzC;AAED,qBAAa,YAAY,CAAC,CAAC,EAAE,CAAC,CAAE,SAAQ,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC;IAC/C,OAAO,CAAC,MAAM,CAAS;IAEvB,MAAM,IAAI,IAAI;IAId,QAAQ,IAAI,OAAO;IAInB,GAAG,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI;IAQ3B,MAAM,CAAC,GAAG,EAAE,CAAC,GAAG,OAAO;IAQvB,KAAK,IAAI,IAAI;CAOd"}
+{"version":3,"file":"map.d.ts","sourceRoot":"","sources":["../../src/utils/map.ts"],"names":[],"mappings":"AAEA,qBAAa,WAAW,CAAC,CAAC,EAAE,CAAC,CAAE,YAAW,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC;IACzD,OAAO,CAAC,SAAS,CAAY;gBAEjB,SAAS,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,SAAS;IAU/D,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS;IAI1B,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,OAAO;IAIpB,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,OAAO,IAAI,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAI9B,IAAI,IAAI,WAAW,CAAC,CAAC,CAAC;IAItB,MAAM,IAAI,WAAW,CAAC,CAAC,CAAC;IAIxB,OAAO,CACL,UAAU,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,IAAI,EACtD,OAAO,CAAC,EAAE,GAAG,GACZ,IAAI;IAIP,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;CAGzC;AAED,qBAAa,YAAY,CAAC,CAAC,EAAE,CAAC,CAAE,SAAQ,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC;IAC/C,OAAO,CAAC,MAAM,CAAS;IAEvB,MAAM,IAAI,IAAI;IAId,QAAQ,IAAI,OAAO;IAInB,GAAG,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI;IAQ3B,MAAM,CAAC,GAAG,EAAE,CAAC,GAAG,OAAO;IAQvB,KAAK,IAAI,IAAI;CAOd"}

package/package.json

@@ -1,14 +1,24 @@
 {
   "name": "@yieldstar/core",
-  "version": "0.4.5",
+  "version": "0.5.0",
+  "license": "MIT",
+  "author": "Daniel Grant",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/notationlabs/yieldstar.git",
+    "directory": "packages/core"
+  },
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "dependencies": {
+    "@standard-schema/spec": "^1.1.0"
+  },
   "devDependencies": {
-    "@types/bun": "latest",
+    "@types/node": "^22.18.0",
     "pino": "^9.9.0"
   },
   "scripts": {
-    "build": "bun build src/index.ts --outfile dist/index.js --target bun --packages=external"
+    "build": "bun build src/index.ts --outfile dist/index.js --target node --packages=external"
   }
 }

package/src/base/step.ts

@@ -52,6 +52,14 @@ export class WorkflowDelay extends StepResponse {
   }
 }
 
+export class StepStoreWait extends StepResponse {
+  static type = "store-wait";
+  readonly type = "store-wait";
+  constructor() {
+    super();
+  }
+}
+
 export class WorkflowRestart extends StepResponse {
   static type = "workflow-restart";
   readonly type = "workflow-restart";