yieldstar 0.4.4 → 0.4.6

package/README.md

@@ -0,0 +1,408 @@
+# YieldStar 🤘
+
+JavaScript‑native distributed workflows.
+
+Write workflows as async generator functions that yield steps. Use first‑class primitives for retries, delays, and polling. .
+
+Currently supports running on Bun and Sqlite. Postgres support will be added next.
+
+## Install
+
+Install the core package:
+
+```sh
+bun add yieldstar
+```
+
+Depending on how you run workflows, also install:
+
+- Local (recommended): `@yieldstar/bun-worker-invoker` and `@yieldstar/bun-sqlite-runtime`
+- HTTP server (Bun): `@yieldstar/bun-http-server` and `@yieldstar/bun-worker-invoker`
+
+Note: `@yieldstar/test-utils` is an internal testing helper used by this repository. For local application use, prefer the SQLite runtime.
+
+## Quick Start: Local (SQLite)
+
+Run a workflow locally with persistence and timers using a Bun worker and the SQLite runtime.
+
+```ts
+// router.ts
+import { workflow, createWorkflowRouter } from "yieldstar";
+
+export const simple = workflow(async function* (step, event, logger) {
+  const n = yield* step.run(() => 1);
+  yield* step.delay(1000);
+  return yield* step.run(() => n * 2);
+});
+
+export const router = createWorkflowRouter({ "simple-workflow": simple });
+export type Router = typeof router;
+```
+
+```ts
+// worker.ts
+import pino from "pino";
+import { WorkflowRunner } from "@yieldstar/core";
+import { createWorkflowWorker } from "@yieldstar/bun-worker-invoker";
+import { SqliteHeapClient, SqliteTimersClient, SqliteTaskQueueClient, SqliteSchedulerClient, createSqliteDb } from "@yieldstar/bun-sqlite-runtime";
+import { router } from "./router";
+
+const logger = pino();
+const db = createSqliteDb({ path: "./.db/local.sqlite" });
+
+const runner = new WorkflowRunner({
+  router,
+  heapClient: new SqliteHeapClient(db),
+  schedulerClient: new SqliteSchedulerClient({
+    taskQueueClient: new SqliteTaskQueueClient(db),
+    timersClient: new SqliteTimersClient(db),
+  }),
+  logger,
+});
+
+createWorkflowWorker(runner, logger).listen();
+```
+
+```ts
+// app.ts
+import pino from "pino";
+import { createWorkflowInvoker } from "@yieldstar/bun-worker-invoker";
+import { createLocalSdk } from "yieldstar";
+import { SqliteEventLoop, createSqliteDb } from "@yieldstar/bun-sqlite-runtime";
+
+const logger = pino();
+const workerPath = new URL("./worker.ts", import.meta.url).href;
+const invoker = createWorkflowInvoker({ workerPath, logger });
+
+const db = createSqliteDb({ path: "./.db/local.sqlite" });
+const loop = new SqliteEventLoop(db);
+loop.start({ onNewEvent: invoker.execute, logger });
+
+const sdk = createLocalSdk<import("./router").Router>(invoker);
+const result = await sdk.triggerAndWait({ workflowId: "simple-workflow" });
+console.log(result); // 2
+```
+
+## Pick Your Runtime
+
+### Option A: Local Worker + SQLite (single process)
+
+Use a Bun worker to execute steps and a SQLite‑backed runtime for persistence, timers, and a task queue.
+
+1) Define workflows and a router:
+
+```ts
+import { workflow, createWorkflowRouter } from "yieldstar";
+
+export const dynamic = workflow<{ msg: string }, void>(async function* (step, event, logger) {
+  const n = yield* step.run(() => Math.random());
+  yield* step.delay(1000);
+  yield* step.run(() => logger.info(`Hello ${event.params.msg}: ${n}`));
+});
+
+export const router = createWorkflowRouter({ "dynamic-workflow": dynamic });
+```
+
+2) Create worker and runtime wiring (worker thread):
+
+```ts
+// worker.ts
+import pino from "pino";
+import { WorkflowRunner } from "@yieldstar/core";
+import { createWorkflowWorker } from "@yieldstar/bun-worker-invoker";
+import { SqliteHeapClient, SqliteTimersClient, SqliteTaskQueueClient, SqliteSchedulerClient } from "@yieldstar/bun-sqlite-runtime";
+import { router } from "./router";
+import { createSqliteDb } from "@yieldstar/bun-sqlite-runtime";
+
+const logger = pino();
+const db = createSqliteDb({ path: "./.db/local.sqlite" });
+
+const runner = new WorkflowRunner({
+  router,
+  heapClient: new SqliteHeapClient(db),
+  schedulerClient: new SqliteSchedulerClient({
+    taskQueueClient: new SqliteTaskQueueClient(db),
+    timersClient: new SqliteTimersClient(db),
+  }),
+  logger,
+});
+
+createWorkflowWorker(runner, logger).listen();
+```
+
+3) Drive the worker from your app and call workflows locally:
+
+```ts
+// app.ts
+import pino from "pino";
+import { createWorkflowInvoker } from "@yieldstar/bun-worker-invoker";
+import { createLocalSdk } from "yieldstar";
+import { SqliteEventLoop, createSqliteDb } from "@yieldstar/bun-sqlite-runtime";
+
+const logger = pino();
+const workerPath = new URL("./worker.ts", import.meta.url).href;
+const invoker = createWorkflowInvoker({ workerPath, logger });
+
+const db = createSqliteDb({ path: "./.db/local.sqlite" });
+const eventLoop = new SqliteEventLoop(db);
+eventLoop.start({ onNewEvent: invoker.execute, logger });
+
+const sdk = createLocalSdk<{ "dynamic-workflow": any }>(invoker);
+const res = await sdk.triggerAndWait({ workflowId: "dynamic-workflow", params: { msg: "hello" } });
+console.log(res);
+```
+
+See a working reference in `examples/local-execution/`.
+
+### Option B: HTTP Server (Bun)
+
+Expose routes to trigger and await workflow results. Use the HTTP SDK as a client.
+
+Server:
+
+```ts
+import pino from "pino";
+import { createRoutes, createMiddleware } from "@yieldstar/bun-http-server";
+import { createWorkflowInvoker } from "@yieldstar/bun-worker-invoker";
+import { SqliteEventLoop, createSqliteDb } from "@yieldstar/bun-sqlite-runtime";
+import { router } from "./router";
+
+const logger = pino();
+const workerPath = new URL("./worker.ts", import.meta.url).href;
+const invoker = createWorkflowInvoker({ workerPath, logger });
+
+const db = createSqliteDb({ path: "./.db/http.sqlite" });
+new SqliteEventLoop(db).start({ onNewEvent: invoker.execute, logger });
+
+const auth = createMiddleware(async (req, event, next) => {
+  if (!req.headers.get("Authorization")) return new Response("Unauthorized", { status: 401 });
+  return next();
+});
+
+Bun.serve({
+  port: 8080,
+  routes: { "/status": new Response("OK"), ...createRoutes({ invoker, logger, middleware: [auth] }) },
+});
+```
+
+Client:
+
+```ts
+import { createHttpSdkFactory } from "yieldstar";
+const createSdk = createHttpSdkFactory<{ "dynamic-workflow": any }>();
+const sdk = createSdk({ url: "http://localhost:8080" });
+
+const exec = await sdk.trigger({ workflowId: "dynamic-workflow", params: { msg: "world" } });
+await exec.ack();
+const result = await exec.waitForResult();
+```
+
+See `examples/http-server/` for a complete setup.
+
+## Patterns You’ll Use
+
+### Parameters
+
+Pass data into a run and access it inside the workflow via `event.params`.
+
+```ts
+const result = await sdk.triggerAndWait({ workflowId: "w", params: { userId: "123" } });
+
+export const w = workflow(async function* (step, event, logger) {
+  logger.info("user:", event.params?.userId);
+  return yield* step.run(() => event.params);
+});
+```
+
+See: `test/params.test.ts`.
+
+### Retries
+
+Throw `RetryableError` inside `step.run` to retry the step with the configured policy.
+
+```ts
+import { RetryableError } from "yieldstar";
+
+yield* step.run(async () => {
+  // e.g. flaky fetch
+  throw new RetryableError("temporary", { maxAttempts: 4, retryInterval: 1000 });
+});
+```
+
+See: `test/retries.test.ts`.
+
+### Delays and Resumption
+
+Pause until a time in the future and automatically resume.
+
+```ts
+yield* step.delay(5000);
+```
+
+See: `test/async.test.ts`.
+
+### Polling
+
+Keep checking a predicate until it passes or times out using structured retries.
+
+```ts
+yield* step.poll({ retryInterval: 1000, maxAttempts: 10 }, () => isReady());
+```
+
+See: `test/polling.test.ts`.
+
+### Cache Keys and Loops
+
+In loops, add explicit cache keys so each iteration is distinct.
+
+```ts
+for (let i = 0; i < 2; i++) {
+  yield* step.run(`step:${i}`, () => i);
+}
+```
+
+If omitted, loop detection will raise: “Each step in a loop must have a unique cache key.” See: `test/loop-detection.test.ts`, `test/cache-keys.test.ts`.
+
+### Custom Step‑Like Helpers
+
+Compose your own helpers by yielding built‑in steps under the hood.
+
+```ts
+const waitForState = (step: any, logger: any) => async function* (state: string) {
+  yield* step.poll({ maxAttempts: 10, retryInterval: 1000 }, () => /* check */ true);
+};
+
+export const coordinator = workflow(async function* (step) {
+  const a = yield* step.run(() => 2);
+  yield* (waitForState(step, console) as any)("enabled");
+  return yield* step.run(() => a * 3);
+});
+```
+
+See: `examples/workflows/coordinator.ts`.
+
+## API Reference
+
+Top‑level exports from `yieldstar`:
+
+```ts
+export { createLocalSdk } from "yieldstar";
+export { createHttpSdkFactory } from "yieldstar";
+export { createWorkflowRouter } from "yieldstar";
+export { RetryableError } from "yieldstar";
+export { createWorkflow, workflow } from "yieldstar";
+export type { WorkflowFn } from "yieldstar";
+```
+
+### `workflow(fn)` / `createWorkflow(fn)`
+
+Define a workflow. The function receives `(step, event, logger)` and must be an async generator that yields steps.
+
+```ts
+type WorkflowFn<Params, Result, Context> = (
+  step: StepRunner,
+  event: WorkflowEvent<Params, Context>,
+  logger: Logger
+) => AsyncGenerator<any, Result>;
+```
+
+Return type is inferred; type parameters allow strong typing of `params` and `result`.
+
+### Step Runner
+
+Available on the first argument of a workflow:
+
+```ts
+// run
+yield* step.run(fn);
+yield* step.run("key", fn);
+
+// delay
+yield* step.delay(ms);
+yield* step.delay("key", ms);
+
+// poll
+yield* step.poll({ retryInterval, maxAttempts }, predicate);
+yield* step.poll("key", { retryInterval, maxAttempts }, predicate);
+```
+
+`RetryableError` inside `fn` signals structured retries:
+
+```ts
+new RetryableError(message, { maxAttempts: number, retryInterval: number });
+```
+
+### Local SDK
+
+Create a client that triggers workflows using an in‑process `WorkflowInvoker`.
+
+```ts
+const sdk = createLocalSdk<Router>(invoker);
+await sdk.triggerAndWait({ workflowId, params? });
+```
+
+### HTTP SDK
+
+Factory returning a client bound to a base URL.
+
+```ts
+const createSdk = createHttpSdkFactory<Router>();
+const sdk = createSdk({ url, fetchOptions? });
+
+const exec = await sdk.trigger({ workflowId, params?, context?, executionId? });
+await exec.ack();
+const result = await exec.waitForResult();
+```
+
+### Router
+
+Register your workflows with IDs:
+
+```ts
+const router = createWorkflowRouter({ "id": workflow, ... });
+type Router = typeof router;
+```
+
+Use `Router` to type your SDKs so `workflowId` and `params` are enforced.
+
+## Testing Your Workflows
+
+For repository development we use an in‑memory runtime driven by `@yieldstar/test-utils` to `triggerAndWait` in tests. This package is internal; application users should test against the same runtime they use in production where possible. Example (internal):
+
+```ts
+import { test, expect } from "bun:test";
+import { createTestSdkFactory } from "@yieldstar/test-utils";
+import { createWorkflow } from "yieldstar";
+
+test("data flow between steps", async () => {
+  const w = createWorkflow(async function* (step) {
+    let n = yield* step.run(() => 1);
+    n = yield* step.run(() => n * 2);
+    return n;
+  });
+  const createSdk = createTestSdkFactory();
+  const sdk = createSdk({ workflow: w });
+  expect(await sdk.triggerAndWait({ workflowId: "workflow" })).toBe(2);
+});
+```
+
+See more examples in `test/*.test.ts`.
+
+## Notes
+
+- In loops, always add cache keys. Missing keys trigger loop detection.
+- `logger` is a Pino logger passed into workflows for observability.
+- HTTP middleware can read/set `event.context` before invoking your workflow.
+
+## Contributing
+
+- Please open an issue to discuss significant changes before submitting a PR.
+- See CONTRIBUTING.md for repo layout, dev workflow, testing, and release details.
+
+## License
+
+MIT
+
+## Author
+
+[Daniel Grant](danielgrant.co)

package/dist/exports/sdk-http.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sdk-http.d.ts","sourceRoot":"","sources":["../../src/exports/sdk-http.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,cAAc,EACd,YAAY,EAEZ,2BAA2B,EAC5B,MAAM,iBAAiB,CAAC;AAKzB,KAAK,UAAU,GAAG;IAChB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,KAAK,eAAe,CAAC,CAAC,SAAS,cAAc,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,CAAC,IAAI;IAC3E,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,MAAM,OAAO,CAAC,UAAU,CAAC,CAAC;IAC/B,aAAa,EAAE,MAAM,OAAO,CAAC,2BAA2B,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CACjE,CAAC;AAEF,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,cAAc,cAC3C;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,QAAQ,CAAC,CAAC;CACrD;YAEiB,CAAC,SAAS,MAAM,GAAG,MAAM,CAAC,SAC/B,YAAY,CAAC,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAC1C,OAAO,CAAC,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;kBA2Bb,CAAC,SAAS,MAAM,GAAG,MAAM,CAAC,OACvC,UAAU,GACd,OAAO,CAAC,2BAA2B,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;EAoBlD"}
+{"version":3,"file":"sdk-http.d.ts","sourceRoot":"","sources":["../../src/exports/sdk-http.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,cAAc,EACd,YAAY,EAEZ,2BAA2B,EAC5B,MAAM,iBAAiB,CAAC;AAKzB,KAAK,UAAU,GAAG;IAChB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,KAAK,eAAe,CAAC,CAAC,SAAS,cAAc,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,CAAC,IAAI;IAC3E,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,MAAM,OAAO,CAAC,UAAU,CAAC,CAAC;IAC/B,aAAa,EAAE,MAAM,OAAO,CAAC,2BAA2B,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CACjE,CAAC;AAEF,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,cAAc,MACnD,QAAQ;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,QAAQ,CAAC,CAAC;CACrD;YAEiB,CAAC,SAAS,MAAM,GAAG,MAAM,CAAC,SAC/B,YAAY,CAAC,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAC1C,OAAO,CAAC,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;kBA2Bb,CAAC,SAAS,MAAM,GAAG,MAAM,CAAC,OACvC,UAAU,GACd,OAAO,CAAC,2BAA2B,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;EAoBlD"}

package/dist/index.js

@@ -84,9 +84,22 @@ class RetryableError extends Error {
   }
 }
 // src/internal/utils.ts
+import { createHash } from "crypto";
 var isIterable = (i) => {
   return typeof i === "object" && i != null && Symbol.iterator in i;
 };
+function getCallSiteHash(stepFn) {
+  const originalStack = stepFn.stack;
+  Error.captureStackTrace(stepFn, getCallSiteHash);
+  const stack = stepFn.stack;
+  const stepFnCallSite = stack.split(")")[1];
+  if (originalStack === undefined) {
+    delete stepFn.stack;
+  } else {
+    stepFn.stack = originalStack;
+  }
+  return createHash("sha1").update(stepFnCallSite).digest("hex");
+}
 
 // src/internal/serialise.ts
 import {
@@ -146,6 +159,8 @@ async function* run(arg1, arg2) {
   } else {
     fn = arg1;
   }
+  if (!key)
+    key = getCallSiteHash(run);
   yield new StepKey(key);
   const cached = yield new StepCacheCheck;
   if (cached) {
@@ -180,6 +195,8 @@ async function* delay(arg1, arg2) {
   } else {
     retryInterval = arg1;
   }
+  if (!key)
+    key = getCallSiteHash(delay);
   yield new StepKey(key);
   const cached = yield new StepCacheCheck;
   if (cached) {
@@ -200,6 +217,8 @@ async function* poll(arg1, arg2, arg3) {
     opts = arg1;
     predicate = arg2;
   }
+  if (!key)
+    key = getCallSiteHash(poll);
   const task = async () => {
     if (!await predicate()) {
       throw new RetryableError("Polling reached max retries", {
@@ -208,11 +227,7 @@ async function* poll(arg1, arg2, arg3) {
       });
     }
   };
-  if (key) {
-    yield* run(key, task);
-  } else {
-    yield* run(task);
-  }
+  yield* run(key, task);
 }
 
 // src/exports/workflow.ts
@@ -230,9 +245,9 @@ function workflow(workflowFn) {
   return async function* workflowGenerator({ event, heapClient, logger }) {
     const workflowIterator = workflowFn(stepRunner, event, logger);
     const { executionId } = event;
-    let keylessStepIndex = -1;
     let iteratorResult = null;
     let nextIteratorResult = null;
+    const stepKeys = new Set;
     while (true) {
       let stepAttempt = 0;
       let stepKey;
@@ -246,11 +261,12 @@ function workflow(workflowFn) {
         stepKey = "$$workflow-result$$";
       } else if (!(iteratorResult.value instanceof StepKey2)) {
         throw new Error("Step runners must yield a StepKey object");
-      } else if (iteratorResult.value.key) {
-        stepKey = iteratorResult.value.key;
       } else {
-        keylessStepIndex++;
-        stepKey = `$$step-index-${keylessStepIndex}$$`;
+        stepKey = iteratorResult.value.key;
+        if (stepKeys.has(stepKey)) {
+          throw new Error("Each step in a loop must have a unique cache key.");
+        }
+        stepKeys.add(stepKey);
       }
       let cached = await heapClient.readStep({
         executionId,

package/dist/internal/step-runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"step-runner.d.ts","sourceRoot":"","sources":["../../src/internal/step-runner.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EAEZ,SAAS,EACT,UAAU,EAGX,MAAM,iBAAiB,CAAC;AAGzB;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU;;;;CAAuB,CAAC;AAE/C,MAAM,MAAM,UAAU,GAAG,OAAO,UAAU,CAAC;AAE3C,iBAAS,GAAG,CAAC,CAAC,SAAS,GAAG,EACxB,EAAE,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GACvB,cAAc,CAAC,YAAY,EAAE,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC,CAAC;AAE3D,iBAAS,GAAG,CAAC,CAAC,SAAS,GAAG,EACxB,GAAG,EAAE,MAAM,EACX,EAAE,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GACvB,cAAc,CAAC,YAAY,EAAE,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC,CAAC;AA+C3D,iBAAS,KAAK,CAAC,aAAa,EAAE,MAAM,GAAG,GAAG,CAAC;AAC3C,iBAAS,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,GAAG,CAAC;AA2BxD,KAAK,QAAQ,GAAG;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,CAAC;AAC/D,KAAK,aAAa,GAAG,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEtD,iBAAS,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,aAAa,GAAG,GAAG,CAAC;AAC7D,iBAAS,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,aAAa,GAAG,GAAG,CAAC"}
+{"version":3,"file":"step-runner.d.ts","sourceRoot":"","sources":["../../src/internal/step-runner.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EAEZ,SAAS,EACT,UAAU,EAGX,MAAM,iBAAiB,CAAC;AAIzB;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU;;;;CAAuB,CAAC;AAE/C,MAAM,MAAM,UAAU,GAAG,OAAO,UAAU,CAAC;AAE3C,iBAAS,GAAG,CAAC,CAAC,SAAS,GAAG,EACxB,EAAE,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GACvB,cAAc,CAAC,YAAY,EAAE,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC,CAAC;AAE3D,iBAAS,GAAG,CAAC,CAAC,SAAS,GAAG,EACxB,GAAG,EAAE,MAAM,EACX,EAAE,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GACvB,cAAc,CAAC,YAAY,EAAE,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC,CAAC;AAiD3D,iBAAS,KAAK,CAAC,aAAa,EAAE,MAAM,GAAG,GAAG,CAAC;AAC3C,iBAAS,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,GAAG,CAAC;AA6BxD,KAAK,QAAQ,GAAG;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,CAAC;AAC/D,KAAK,aAAa,GAAG,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEtD,iBAAS,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,aAAa,GAAG,GAAG,CAAC;AAC7D,iBAAS,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,aAAa,GAAG,GAAG,CAAC"}

package/dist/internal/utils.d.ts

@@ -1,2 +1,3 @@
 export declare const isIterable: <T>(i: T | Iterable<T>) => i is Iterable<T>;
+export declare function getCallSiteHash(stepFn: Function): string;
 //# sourceMappingURL=utils.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/internal/utils.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,UAAU,GAAI,CAAC,KAAK,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,KAAG,CAAC,IAAI,QAAQ,CAAC,CAAC,CAIjE,CAAC"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/internal/utils.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,UAAU,GAAI,CAAC,EAAE,GAAG,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,KAAG,CAAC,IAAI,QAAQ,CAAC,CAAC,CAIjE,CAAC;AAGF,wBAAgB,eAAe,CAAC,MAAM,EAAE,QAAQ,UAe/C"}

package/package.json

@@ -1,17 +1,19 @@
 {
   "name": "yieldstar",
-  "version": "0.4.4",
+  "version": "0.4.6",
+  "license": "MIT",
+  "author": "Daniel Grant",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "dependencies": {
-    "nanoid": "^5.1.3",
-    "pino": "^9.6.0",
+    "nanoid": "^5.1.5",
+    "pino": "^9.9.0",
     "serialize-error": "^11.0.3",
-    "@yieldstar/core": "0.4.4"
+    "@yieldstar/core": "0.4.6"
   },
   "devDependencies": {
-    "@types/node": "^22.13.10"
+    "@types/node": "^22.18.0"
   },
   "scripts": {
     "build": "bun build src/index.ts --outfile dist/index.js --target bun --packages=external"

package/src/exports/workflow.ts

@@ -49,9 +49,9 @@ export function workflow<
     const workflowIterator = workflowFn(stepRunner, event, logger);
     const { executionId } = event;
 
-    let keylessStepIndex = -1;
     let iteratorResult: IteratorResult<any> | null = null;
     let nextIteratorResult: IteratorResult<any> | null = null;
+    const stepKeys = new Set<string>();
 
     while (true) {
       let stepAttempt = 0;
@@ -71,20 +71,20 @@ export function workflow<
 
       /**
        * Get the StepKey from the step runner.
-       * If the StepKey value is null, assume deterministic ordering, and use
-       * the step index as a key.
        * If the generator is done, the workflow has returned, so we set a
        * special key for that.
+       * Finally, check that this call site wasn't reached before.
        */
       if (iteratorResult.done) {
         stepKey = "$$workflow-result$$";
       } else if (!(iteratorResult.value instanceof StepKey)) {
         throw new Error("Step runners must yield a StepKey object");
-      } else if (iteratorResult.value.key) {
-        stepKey = iteratorResult.value.key;
       } else {
-        keylessStepIndex++;
-        stepKey = `$$step-index-${keylessStepIndex}$$`;
+        stepKey = iteratorResult.value.key;
+        if (stepKeys.has(stepKey)) {
+          throw new Error("Each step in a loop must have a unique cache key.");
+        }
+        stepKeys.add(stepKey)
       }
 
       /**

package/src/internal/step-runner.ts

@@ -7,6 +7,7 @@ import {
   StepCacheCheck,
 } from "@yieldstar/core";
 import { RetryableError } from "../exports/errors";
+import { getCallSiteHash } from "./utils";
 
 /**
  * @description A library of step generators, each of which:
@@ -21,28 +22,30 @@ export const stepRunner = { run, delay, poll };
 export type StepRunner = typeof stepRunner;
 
 function run<T extends any>(
-  fn: () => T | Promise<T>
+  fn: () => T | Promise<T>,
 ): AsyncGenerator<StepResponse, T, StepResult | StepError>;
 
 function run<T extends any>(
   key: string,
-  fn: () => T | Promise<T>
+  fn: () => T | Promise<T>,
 ): AsyncGenerator<StepResponse, T, StepResult | StepError>;
 
 async function* run<T extends any>(
   arg1: string | (() => T | Promise<T>),
-  arg2?: () => T | Promise<T>
+  arg2?: (() => T | Promise<T>) | string,
 ): AsyncGenerator<StepResponse, T, StepResult | StepError> {
   let key: string | null = null;
   let fn: () => T | Promise<T>;
 
   if (typeof arg1 === "string") {
     key = arg1;
-    fn = arg2!;
+    fn = arg2 as () => T | Promise<T>;
   } else {
     fn = arg1;
   }
 
+  if (!key) key = getCallSiteHash(run);
+
   yield new StepKey(key);
 
   const cached = yield new StepCacheCheck();
@@ -91,6 +94,8 @@ async function* delay(
     retryInterval = arg1;
   }
 
+  if (!key) key = getCallSiteHash(delay);
+
   yield new StepKey(key);
 
   const cached = yield new StepCacheCheck();
@@ -126,6 +131,8 @@ async function* poll(
     predicate = arg2 as PollPredicate;
   }
 
+  if (!key) key  = getCallSiteHash(poll);
+
   const task = async () => {
     if (!(await predicate())) {
       throw new RetryableError("Polling reached max retries", {
@@ -135,9 +142,5 @@ async function* poll(
     }
   };
 
-  if (key) {
-    yield* run(key, task);
-  } else {
-    yield* run(task);
-  }
+  yield* run(key, task, );
 }

package/src/internal/utils.ts

@@ -1,5 +1,25 @@
+import { createHash } from "crypto";
+
 export const isIterable = <T>(i: T | Iterable<T>): i is Iterable<T> => {
   return (
     typeof i === "object" && i != null && Symbol.iterator in (i as Iterable<T>)
   );
 };
+
+
+export function getCallSiteHash(stepFn: Function) {
+  const originalStack = (stepFn as any).stack;
+
+  Error.captureStackTrace(stepFn, getCallSiteHash);
+
+  const stack = (stepFn as any).stack
+  const stepFnCallSite = stack.split(')')[1]
+
+  if (originalStack === undefined) {
+    delete (stepFn as any).stack;
+  } else {
+    (stepFn as any).stack = originalStack;
+  }
+
+  return createHash("sha1").update(stepFnCallSite).digest("hex");
+}