yieldstar 0.0.0 → 0.1.0-alpha.0

package/dist/index.js

@@ -0,0 +1,326 @@
+// @bun
+// src/exports/sdk-local.ts
+import { randomUUID } from "crypto";
+function createLocalSdk(workflowRouter, invoker) {
+  return {
+    async trigger(workflowId, opts) {
+      const { workflowParams } = opts ?? {};
+      const executionId = opts?.executionId ?? randomUUID();
+      await invoker.execute({
+        executionId,
+        workflowId,
+        params: workflowParams
+      });
+      return { executionId };
+    },
+    async triggerAndWait(workflowId, opts) {
+      const { workflowParams } = opts ?? {};
+      const executionId = opts?.executionId ?? randomUUID();
+      const workflowCompletePromise = new Promise((resolve) => {
+        invoker.workflowEndEmitter.once(executionId, resolve);
+      });
+      await this.trigger(workflowId, { executionId, workflowParams });
+      return workflowCompletePromise;
+    }
+  };
+}
+// src/exports/sdk-http.ts
+import { deserializeError, isErrorLike } from "serialize-error";
+import { randomUUID as randomUUID2 } from "crypto";
+function createHttpSdkFactory(workflowRouter) {
+  return (params) => {
+    return {
+      async trigger(workflowId, opts) {
+        const { workflowParams } = opts ?? {};
+        const executionId = opts?.executionId ?? randomUUID2();
+        const res = await fetch(`${params.host}:${params.port}/trigger`, {
+          method: "POST",
+          body: JSON.stringify({
+            executionId,
+            workflowId,
+            params: workflowParams
+          })
+        });
+        if (res.ok) {
+          return res.json();
+        } else {
+          throw res.statusText;
+        }
+      },
+      async triggerAndWait(workflowId, opts) {
+        const { workflowParams } = opts ?? {};
+        const executionId = opts?.executionId ?? randomUUID2();
+        await this.trigger(workflowId, { executionId, workflowParams });
+        const result = await fetch(`${params.host}:${params.port}/events`, {
+          method: "POST",
+          body: JSON.stringify({ executionId })
+        });
+        const json = await result.json();
+        if (isErrorLike(json)) {
+          throw deserializeError(json);
+        }
+        return json;
+      }
+    };
+  };
+}
+// src/exports/router.ts
+function createWorkflowRouter(workflows) {
+  return workflows;
+}
+// src/exports/errors.ts
+class RetryableError extends Error {
+  maxAttempts;
+  retryInterval;
+  constructor(message, opts) {
+    super(message);
+    this.name = "RetryableError";
+    this.maxAttempts = opts.maxAttempts;
+    this.retryInterval = opts.retryInterval;
+  }
+}
+// src/internal/utils.ts
+var isIterable = (i) => {
+  return typeof i === "object" && i != null && Symbol.iterator in i;
+};
+
+// src/internal/serialise.ts
+import { serializeError, deserializeError as deserializeError2, isErrorLike as isErrorLike2 } from "serialize-error";
+import {
+  StepDelay,
+  StepError,
+  StepResult,
+  WorkflowResult
+} from "@yieldstar/core";
+function serialize(data) {
+  const replaceErrors = (key, value) => {
+    if (value instanceof Error) {
+      return serializeError(value);
+    }
+    return value;
+  };
+  return JSON.stringify(data, replaceErrors);
+}
+function deserialize(jsonString) {
+  const reviveErrors = (key, value) => {
+    if (isErrorLike2(value)) {
+      return deserializeError2(value);
+    }
+    return value;
+  };
+  const stepResponse = JSON.parse(jsonString, reviveErrors);
+  switch (stepResponse.type) {
+    case "step-error":
+      const { err, ...params } = stepResponse;
+      return new StepError(stepResponse.err, params);
+    case "step-delay":
+      return new StepDelay(stepResponse.resumeIn);
+    case "step-result":
+      return new StepResult(stepResponse.result);
+    case "workflow-result":
+      return new WorkflowResult(stepResponse.result);
+    default:
+      throw new Error("Unknown step result type: " + stepResponse.type);
+  }
+}
+
+// src/internal/step-runner.ts
+import {
+  StepKey,
+  StepError as StepError2,
+  StepResult as StepResult2,
+  StepDelay as StepDelay2,
+  StepCacheCheck
+} from "@yieldstar/core";
+async function* run(arg1, arg2) {
+  let key = null;
+  let fn;
+  if (typeof arg1 === "string") {
+    key = arg1;
+    fn = arg2;
+  } else {
+    fn = arg1;
+  }
+  yield new StepKey(key);
+  const cached = yield new StepCacheCheck;
+  if (cached) {
+    yield cached;
+    if (cached instanceof StepError2) {
+      throw cached.err;
+    }
+    return cached.result;
+  }
+  try {
+    const result = await fn();
+    yield new StepResult2(result);
+    return result;
+  } catch (err) {
+    if (err instanceof RetryableError) {
+      yield new StepError2(err, {
+        maxAttempts: err.maxAttempts,
+        retryInterval: err.retryInterval
+      });
+    } else {
+      yield new StepError2(err);
+    }
+    throw err;
+  }
+}
+async function* delay(arg1, arg2) {
+  let key = null;
+  let retryInterval;
+  if (typeof arg1 === "string") {
+    key = arg1;
+    retryInterval = arg2;
+  } else {
+    retryInterval = arg1;
+  }
+  yield new StepKey(key);
+  const cached = yield new StepCacheCheck;
+  if (cached) {
+    yield new StepDelay2(cached.resumeIn);
+  } else {
+    yield new StepDelay2(Date.now() + retryInterval);
+  }
+}
+async function* poll(arg1, arg2, arg3) {
+  let key = null;
+  let opts;
+  let predicate;
+  if (typeof arg1 === "string") {
+    key = arg1;
+    opts = arg2;
+    predicate = arg3;
+  } else {
+    opts = arg1;
+    predicate = arg2;
+  }
+  const task = async () => {
+    if (!await predicate()) {
+      throw new RetryableError("Polling reached max retries", {
+        maxAttempts: opts.maxAttempts,
+        retryInterval: opts.retryInterval
+      });
+    }
+  };
+  if (key) {
+    yield* run(key, task);
+  } else {
+    yield* run(task);
+  }
+}
+var stepRunner = { run, delay, poll };
+
+// src/exports/workflow.ts
+import {
+  StepResponse as StepResponse3,
+  StepKey as StepKey2,
+  StepError as StepError3,
+  StepResult as StepResult3,
+  StepDelay as StepDelay3,
+  StepCacheCheck as StepCacheCheck2,
+  StepInvalid,
+  WorkflowResult as WorkflowResult2
+} from "@yieldstar/core";
+function createWorkflow(workflowFn) {
+  return async function* workflowGenerator(params) {
+    const workflowIterator = workflowFn(stepRunner);
+    const { executionId, heapClient } = params;
+    let keylessStepIndex = -1;
+    let iteratorResult = null;
+    let nextIteratorResult = null;
+    while (true) {
+      let stepAttempt = 0;
+      let stepKey;
+      if (nextIteratorResult) {
+        iteratorResult = nextIteratorResult;
+        nextIteratorResult = null;
+      } else {
+        iteratorResult = await workflowIterator.next();
+      }
+      if (iteratorResult.done) {
+        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}\$\$`;
+      }
+      let cached = await heapClient.readStep({
+        executionId,
+        stepKey
+      });
+      if (cached?.meta) {
+        stepAttempt = cached.meta.attempt + 1;
+      }
+      if (cached?.meta.done === false) {
+        cached = null;
+      }
+      if (!iteratorResult.done) {
+        iteratorResult = await workflowIterator.next();
+      }
+      let stepResponse;
+      if (iteratorResult.done) {
+        stepResponse = new WorkflowResult2(iteratorResult.value);
+      } else {
+        stepResponse = iteratorResult.value;
+      }
+      if (stepResponse instanceof StepCacheCheck2) {
+        const cachedResponse = cached ? deserialize(cached.stepResponseJson) : null;
+        iteratorResult = await workflowIterator.next(cachedResponse);
+        stepResponse = iteratorResult.value;
+      } else if (!(stepResponse instanceof WorkflowResult2)) {
+        throw new Error("Step runners must yield a CacheCheck object");
+      }
+      if (isIterable(stepResponse)) {
+        console.log("[ERR] Steps must be yielded using yield*\n");
+        stepResponse = new StepInvalid;
+      } else if (!(stepResponse instanceof StepResponse3)) {
+        console.log(`[ERR] Iterators should yield a StepResponse. Got ${JSON.stringify(stepResponse)}`);
+        stepResponse = new StepInvalid;
+      }
+      const needsRetry = !cached?.meta.done && stepResponse instanceof StepError3 && stepResponse.maxAttempts > stepAttempt + 1;
+      if (!cached) {
+        await heapClient.writeStep({
+          executionId,
+          stepKey,
+          stepAttempt,
+          stepDone: !needsRetry,
+          stepResponseJson: serialize(stepResponse)
+        });
+      }
+      if (stepResponse instanceof WorkflowResult2) {
+        return stepResponse;
+      }
+      if (stepResponse instanceof StepInvalid) {
+        break;
+      }
+      if (stepResponse instanceof StepError3) {
+        if (needsRetry) {
+          yield new StepDelay3(Date.now() + stepResponse.retryInterval);
+        } else {
+          nextIteratorResult = await workflowIterator.throw(stepResponse.err);
+          continue;
+        }
+      }
+      if (stepResponse instanceof StepDelay3) {
+        if (stepResponse.resumeIn <= Date.now()) {
+          continue;
+        }
+      }
+      if (!(stepResponse instanceof StepResult3)) {
+        yield stepResponse;
+      }
+    }
+    throw new Error("Critical error");
+  };
+}
+export {
+  createWorkflowRouter,
+  createWorkflow,
+  createLocalSdk,
+  createHttpSdkFactory,
+  RetryableError
+};

package/package.json

@@ -1,12 +1,17 @@
 {
   "name": "yieldstar",
-  "version": "0.0.0",
-  "module": "index.ts",
+  "version": "0.1.0-alpha.0",
   "type": "module",
+  "main": "dist/index.js",
+  "types": "src/index.ts",
+  "dependencies": {
+    "serialize-error": "^11.0.3"
+  },
   "devDependencies": {
-    "@types/bun": "latest"
+    "@types/bun": "latest",
+    "@yieldstar/core": "0.1.0"
   },
-  "peerDependencies": {
-    "typescript": "^5.0.0"
+  "scripts": {
+    "build": "bun build src/index.ts --outfile dist/index.js --target bun --packages=external"
   }
-}
+}

package/src/exports/errors.ts

@@ -0,0 +1,13 @@
+export class RetryableError extends Error {
+  maxAttempts: number;
+  retryInterval: number;
+  constructor(
+    message: string,
+    opts: { maxAttempts: number; retryInterval: number }
+  ) {
+    super(message);
+    this.name = "RetryableError";
+    this.maxAttempts = opts.maxAttempts;
+    this.retryInterval = opts.retryInterval;
+  }
+}

package/src/exports/router.ts

@@ -0,0 +1,7 @@
+import type { WorkflowRouter } from "@yieldstar/core";
+
+export function createWorkflowRouter<W extends WorkflowRouter>(
+  workflows: W
+): W {
+  return workflows;
+}

package/src/exports/sdk-http.ts

@@ -0,0 +1,67 @@
+import type {
+  WorkflowRouter,
+  WorkflowGeneratorReturnType,
+} from "@yieldstar/core";
+import { deserializeError, isErrorLike } from "serialize-error";
+import { randomUUID } from "node:crypto";
+
+export function createHttpSdkFactory<W extends WorkflowRouter>(
+  workflowRouter: W
+) {
+  return (params: { host: string; port: number }) => {
+    return {
+      async trigger<K extends keyof W>(
+        workflowId: K,
+        opts?: {
+          executionId?: string;
+          workflowParams?: Parameters<W[K]>[0] extends never
+            ? never
+            : Parameters<W[K]>[0];
+        }
+      ) {
+        const { workflowParams } = opts ?? {};
+        const executionId = opts?.executionId ?? randomUUID();
+        const res = await fetch(`${params.host}:${params.port}/trigger`, {
+          method: "POST",
+          body: JSON.stringify({
+            executionId,
+            workflowId,
+            params: workflowParams,
+          }),
+        });
+        if (res.ok) {
+          return res.json() as Promise<{ executionId: string }>;
+        } else {
+          throw res.statusText;
+        }
+      },
+      async triggerAndWait<K extends keyof W>(
+        workflowId: K,
+        opts?: {
+          executionId?: string;
+          workflowParams?: Parameters<W[K]>[0] extends never
+            ? never
+            : Parameters<W[K]>[0];
+        }
+      ) {
+        const { workflowParams } = opts ?? {};
+        const executionId = opts?.executionId ?? randomUUID();
+        // todo: add timeout and cancel request
+        await this.trigger(workflowId, { executionId, workflowParams });
+        // todo: set up subscription first (maybe just use ws)
+        const result = await fetch(`${params.host}:${params.port}/events`, {
+          method: "POST",
+          body: JSON.stringify({ executionId }),
+        });
+
+        const json = await result.json();
+
+        if (isErrorLike(json)) {
+          throw deserializeError(json);
+        }
+
+        return json as Promise<WorkflowGeneratorReturnType<W[K]>>;
+      },
+    };
+  };
+}

package/src/exports/sdk-local.ts

@@ -0,0 +1,51 @@
+import type {
+  WorkflowRouter,
+  WorkflowGeneratorReturnType,
+  WorkflowInvoker,
+} from "@yieldstar/core";
+import { randomUUID } from "node:crypto";
+
+export function createLocalSdk<W extends WorkflowRouter>(
+  workflowRouter: W,
+  invoker: WorkflowInvoker
+) {
+  return {
+    async trigger<K extends keyof W>(
+      workflowId: K,
+      opts?: {
+        executionId?: string;
+        workflowParams?: Parameters<W[K]>[0] extends never
+          ? never
+          : Parameters<W[K]>[0];
+      }
+    ) {
+      const { workflowParams } = opts ?? {};
+      const executionId = opts?.executionId ?? randomUUID();
+      await invoker.execute({
+        executionId,
+        workflowId: workflowId as string,
+        params: workflowParams,
+      });
+      return { executionId };
+    },
+    async triggerAndWait<K extends keyof W>(
+      workflowId: K,
+      opts?: {
+        executionId?: string;
+        workflowParams?: Parameters<W[K]>[0] extends never
+          ? never
+          : Parameters<W[K]>[0];
+      }
+    ) {
+      const { workflowParams } = opts ?? {};
+      const executionId = opts?.executionId ?? randomUUID();
+      const workflowCompletePromise = new Promise((resolve) => {
+        invoker.workflowEndEmitter.once(executionId, resolve);
+      });
+      await this.trigger(workflowId, { executionId, workflowParams });
+      return workflowCompletePromise as Promise<
+        WorkflowGeneratorReturnType<W[K]>
+      >;
+    },
+  };
+}

package/src/exports/workflow.ts

@@ -0,0 +1,220 @@
+import type { WorkflowGenerator } from "@yieldstar/core";
+import type { StepRunner } from "../internal/step-runner";
+import { isIterable } from "../internal/utils";
+import { deserialize, serialize } from "../internal/serialise";
+import { stepRunner } from "../internal/step-runner";
+import {
+  StepResponse,
+  StepKey,
+  StepError,
+  StepResult,
+  StepDelay,
+  StepCacheCheck,
+  StepInvalid,
+  WorkflowResult,
+} from "@yieldstar/core";
+
+export type WorkflowFn<T> = (step: StepRunner) => AsyncGenerator<any, T>;
+
+export function createWorkflow<T>(
+  workflowFn: WorkflowFn<T>
+): WorkflowGenerator<T> {
+  /**
+   * @description Advances workflow steps, handling any workflow logic, and
+   * yielding control to a workflow executor to do async work
+   * @yields {StepResponse}
+   */
+  return async function* workflowGenerator(params) {
+    const workflowIterator = workflowFn(stepRunner);
+    const { executionId, heapClient } = params;
+
+    let keylessStepIndex = -1;
+    let iteratorResult: IteratorResult<any> | null = null;
+    let nextIteratorResult: IteratorResult<any> | null = null;
+
+    while (true) {
+      let stepAttempt = 0;
+      let stepKey: string;
+
+      /**
+       * If we already have the next iterator result from a previous iteration
+       * (e.g. it threw an error and advanced the workflow), use that, otherwise,
+       * advance the workflow generator
+       */
+      if (nextIteratorResult) {
+        iteratorResult = nextIteratorResult;
+        nextIteratorResult = null;
+      } else {
+        iteratorResult = await workflowIterator.next();
+      }
+
+      /**
+       * 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.
+       */
+      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}$$`;
+      }
+
+      /**
+       * Using the StepKey, retrieve the previous response for this step from
+       * the cache
+       */
+      let cached = await heapClient.readStep({
+        executionId,
+        stepKey,
+      });
+
+      /**
+       * Increment attempt counter. We'll save this after execution.
+       */
+      if (cached?.meta) {
+        stepAttempt = cached.meta.attempt + 1;
+      }
+
+      /**
+       * If the step needs to be retried, ignore the cached value
+       */
+      if (cached?.meta.done === false) {
+        cached = null;
+      }
+
+      /**
+       * If the workflow generator hasn't returned, advance the step runner
+       */
+      if (!iteratorResult.done) {
+        iteratorResult = await workflowIterator.next();
+      }
+
+      /**
+       * We can now get a StepResponse object from the iterator result.
+       * The step runner generator always yields a StepResponse, whereas
+       * the workflow generator return value needs to be wrapped.
+       */
+      let stepResponse: StepResponse;
+
+      if (iteratorResult.done) {
+        stepResponse = new WorkflowResult(iteratorResult.value);
+      } else {
+        stepResponse = iteratorResult.value;
+      }
+
+      /**
+       * If the first yielded value is a cache check, advance to actual step,
+       * passing it the cached value
+       */
+      if (stepResponse instanceof StepCacheCheck) {
+        const cachedResponse = cached
+          ? deserialize(cached.stepResponseJson)
+          : null;
+        iteratorResult = await workflowIterator.next(cachedResponse);
+        stepResponse = iteratorResult.value;
+      } else if (!(stepResponse instanceof WorkflowResult)) {
+        throw new Error("Step runners must yield a CacheCheck object");
+      }
+
+      /**
+       * Check for invalid iterators e.g. developer didn't use yield* or didn't
+       * use a step runner
+       * @todo: iterable check should be before StepKey check
+       * @todo: not throwing here causes a critical error – should workflow break?
+       */
+      if (isIterable(stepResponse)) {
+        console.log("[ERR] Steps must be yielded using yield*\n");
+        stepResponse = new StepInvalid();
+      } else if (!(stepResponse instanceof StepResponse)) {
+        console.log(
+          `[ERR] Iterators should yield a StepResponse. Got ${JSON.stringify(
+            stepResponse
+          )}`
+        );
+        stepResponse = new StepInvalid();
+      }
+
+      /**
+       * Determine if step needs to be retried
+       */
+      const needsRetry =
+        !cached?.meta.done &&
+        stepResponse instanceof StepError &&
+        // 1-indexed vs 0-indexed
+        stepResponse.maxAttempts > stepAttempt + 1;
+
+      /**
+       * If this step attempt is not already cached, cache it
+       */
+      if (!cached) {
+        await heapClient.writeStep({
+          executionId,
+          stepKey,
+          stepAttempt,
+          stepDone: !needsRetry,
+          stepResponseJson: serialize(stepResponse),
+        });
+      }
+
+      /**
+       * Once the WorkflowResult is cached, return the WorkflowResult to the
+       * upstream consumer e.g the worker
+       */
+      if (stepResponse instanceof WorkflowResult) {
+        return stepResponse;
+      }
+
+      /**
+       * Once invalid iterator steps have been cached, stop execution
+       */
+      if (stepResponse instanceof StepInvalid) {
+        break;
+      }
+
+      /**
+       * If step runner yielded a step error, either throw the error back for
+       * user to handle, or yield to worker, if it should be retried.
+       * (Throwing also advances the workflow generator, so, in that case, we
+       * store the next iterator result, and continue to the next step).
+       */
+      if (stepResponse instanceof StepError) {
+        if (needsRetry) {
+          yield new StepDelay(Date.now() + stepResponse.retryInterval);
+        } else {
+          nextIteratorResult = await workflowIterator.throw(stepResponse.err);
+          continue;
+        }
+      }
+
+      /**
+       * If the delay has already elapsed, continue straight to next step
+       */
+      if (stepResponse instanceof StepDelay) {
+        if (stepResponse.resumeIn <= Date.now()) {
+          continue;
+        }
+      }
+
+      /**
+       * Yield control back to the worker if the stepResponse is not a result
+       * i.e. async work is required. (Whenever we receive a StepResult, it's
+       * always possible to continue straight to the next step).
+       */
+      if (!(stepResponse instanceof StepResult)) {
+        yield stepResponse;
+      }
+    }
+
+    /**
+     * If we arrive here, something has gone wrong internally
+     */
+    throw new Error("Critical error");
+  };
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export { createLocalSdk } from "./exports/sdk-local";
+export { createHttpSdkFactory } from "./exports/sdk-http";
+export { createWorkflowRouter } from "./exports/router";
+export { RetryableError } from "./exports/errors";
+export { createWorkflow } from "./exports/workflow";
+export type { WorkflowFn } from "./exports/workflow";

package/src/internal/serialise.ts

@@ -0,0 +1,44 @@
+import { serializeError, deserializeError, isErrorLike } from "serialize-error";
+import {
+  StepDelay,
+  StepError,
+  StepResult,
+  StepResponse,
+  WorkflowResult,
+} from "@yieldstar/core";
+
+export function serialize(data: StepResponse): string {
+  const replaceErrors = (key: string, value: any) => {
+    if (value instanceof Error) {
+      return serializeError(value);
+    }
+    return value;
+  };
+
+  return JSON.stringify(data, replaceErrors);
+}
+
+export function deserialize(jsonString: string): StepResponse {
+  const reviveErrors = (key: string, value: any) => {
+    if (isErrorLike(value)) {
+      return deserializeError(value);
+    }
+    return value;
+  };
+
+  const stepResponse = JSON.parse(jsonString, reviveErrors);
+
+  switch (stepResponse.type) {
+    case "step-error":
+      const { err, ...params } = stepResponse;
+      return new StepError(stepResponse.err, params);
+    case "step-delay":
+      return new StepDelay(stepResponse.resumeIn);
+    case "step-result":
+      return new StepResult(stepResponse.result);
+    case "workflow-result":
+      return new WorkflowResult(stepResponse.result);
+    default:
+      throw new Error("Unknown step result type: " + stepResponse.type);
+  }
+}

package/src/internal/step-runner.ts

@@ -0,0 +1,143 @@
+import {
+  StepResponse,
+  StepKey,
+  StepError,
+  StepResult,
+  StepDelay,
+  StepCacheCheck,
+} from "@yieldstar/core";
+import { RetryableError } from "../exports/errors";
+
+/**
+ * @description A library of step generators, each of which:
+ * @yields a StepResponse to workflow consumers
+ * @returns the result of executing a user-defined function, or
+ * @returns the cached result from a previous run, or
+ * @throws any error caught when running the user-defined function,
+ * once retries have been exhausted, or if there are no retry semantics
+ */
+export const stepRunner = { run, delay, poll };
+
+export type StepRunner = typeof stepRunner;
+
+function run<T extends any>(
+  fn: () => T | Promise<T>
+): AsyncGenerator<StepResponse, T, StepResult | StepError>;
+
+function run<T extends any>(
+  key: string,
+  fn: () => T | Promise<T>
+): AsyncGenerator<StepResponse, T, StepResult | StepError>;
+
+async function* run<T extends any>(
+  arg1: string | (() => T | Promise<T>),
+  arg2?: () => T | Promise<T>
+): AsyncGenerator<StepResponse, T, StepResult | StepError> {
+  let key: string | null = null;
+  let fn: () => T | Promise<T>;
+
+  if (typeof arg1 === "string") {
+    key = arg1;
+    fn = arg2!;
+  } else {
+    fn = arg1;
+  }
+
+  yield new StepKey(key);
+
+  const cached = yield new StepCacheCheck();
+
+  if (cached) {
+    yield cached;
+    if (cached instanceof StepError) {
+      // unreachable – consumer calls throw() on the generator first
+      throw cached.err;
+    }
+    return cached.result;
+  }
+
+  try {
+    const result = await fn();
+    yield new StepResult(result);
+    return result;
+  } catch (err: unknown) {
+    if (err instanceof RetryableError) {
+      yield new StepError(err, {
+        maxAttempts: err.maxAttempts,
+        retryInterval: err.retryInterval,
+      });
+    } else {
+      yield new StepError(err);
+    }
+    // unreachable – consumer calls throw() on the generator first
+    throw err;
+  }
+}
+
+function delay(retryInterval: number): any;
+function delay(key: string, retryInterval: number): any;
+
+async function* delay(
+  arg1: string | number,
+  arg2?: number
+): AsyncGenerator<any, void, StepDelay> {
+  let key: string | null = null;
+  let retryInterval: number;
+
+  if (typeof arg1 === "string") {
+    key = arg1;
+    retryInterval = arg2!;
+  } else {
+    retryInterval = arg1;
+  }
+
+  yield new StepKey(key);
+
+  const cached = yield new StepCacheCheck();
+
+  if (cached) {
+    yield new StepDelay(cached.resumeIn);
+  } else {
+    yield new StepDelay(Date.now() + retryInterval);
+  }
+}
+
+type PollOpts = { maxAttempts: number; retryInterval: number };
+type PollPredicate = () => boolean | Promise<boolean>;
+
+function poll(opts: PollOpts, predicate: PollPredicate): any;
+function poll(key: string, opts: PollOpts, predicate: PollPredicate): any;
+
+async function* poll(
+  arg1: string | PollOpts,
+  arg2: PollOpts | PollPredicate,
+  arg3?: PollPredicate
+) {
+  let key: string | null = null;
+  let opts: PollOpts;
+  let predicate: PollPredicate;
+
+  if (typeof arg1 === "string") {
+    key = arg1;
+    opts = arg2 as PollOpts;
+    predicate = arg3 as PollPredicate;
+  } else {
+    opts = arg1;
+    predicate = arg2 as PollPredicate;
+  }
+
+  const task = async () => {
+    if (!(await predicate())) {
+      throw new RetryableError("Polling reached max retries", {
+        maxAttempts: opts.maxAttempts,
+        retryInterval: opts.retryInterval,
+      });
+    }
+  };
+
+  if (key) {
+    yield* run(key, task);
+  } else {
+    yield* run(task);
+  }
+}

package/src/internal/utils.ts

@@ -0,0 +1,5 @@
+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>)
+  );
+};

package/tsconfig.json

@@ -1,11 +1,10 @@
 {
   "compilerOptions": {
     // Enable latest features
-    "lib": ["ESNext", "DOM"],
+    "lib": ["ESNext"],
     "target": "ESNext",
     "module": "ESNext",
     "moduleDetection": "force",
-    "jsx": "react-jsx",
     "allowJs": true,
 
     // Bundler mode

package/README.md

@@ -1,15 +0,0 @@
-# yieldstar
-
-To install dependencies:
-
-```bash
-bun install
-```
-
-To run:
-
-```bash
-bun run index.ts
-```
-
-This project was created using `bun init` in bun v1.1.20. [Bun](https://bun.sh) is a fast all-in-one JavaScript runtime.

package/index.ts

@@ -1,3 +0,0 @@
-import { version } from "./package.json";
-
-console.log(`yieldstar version ${version}`);