yieldstar 0.4.6 → 0.6.0

package/src/internal/runtime-call.ts

@@ -0,0 +1,95 @@
+import {
+  InfrastructureError,
+  StepResponse,
+  StoreValidationError,
+  WorkflowValueError,
+  type ExecutionClient,
+  type StoreClient,
+} from "@yieldstar/core";
+
+export type RuntimeClients = {
+  stores: StoreClient;
+  executions: ExecutionClient;
+};
+
+export type RuntimeCallResult<T> =
+  | { ok: true; value: T }
+  | { ok: false; error: unknown };
+
+/**
+ * Yielded by a step that needs a runtime client. Steps never call runtime
+ * clients themselves: the driver makes the call outside workflow code and
+ * resumes the step with a `RuntimeCallResult`. Only failures that belong to
+ * workflow code (see `isWorkflowFacingError`) resume the step; any other
+ * failure is an infrastructure error and ends the delivery without an outcome.
+ */
+export class StepRuntimeCall<T = unknown> extends StepResponse {
+  static type = "runtime-call";
+  readonly type = "runtime-call";
+  readonly call: (clients: RuntimeClients) => Promise<T>;
+
+  constructor(call: (clients: RuntimeClients) => Promise<T>) {
+    super();
+    this.call = call;
+  }
+}
+
+/** Marks an error thrown by a workflow-supplied callback run by a client. */
+export class StepCallbackError extends Error {
+  constructor(cause: unknown) {
+    super(cause instanceof Error ? cause.message : String(cause), { cause });
+    this.name = "StepCallbackError";
+  }
+}
+
+/**
+ * Wraps a workflow-supplied callback (updater, selector, claim, initial state)
+ * that a runtime client will run, so its errors reach workflow code rather
+ * than being mistaken for infrastructure errors.
+ */
+export function workflowCallback<A extends unknown[], R>(
+  fn: (...args: A) => R,
+  assertResult?: (result: R) => void
+): (...args: A) => R {
+  return (...args) => {
+    try {
+      const result = fn(...args);
+      assertResult?.(result);
+      return result;
+    } catch (err) {
+      throw new StepCallbackError(err);
+    }
+  };
+}
+
+export async function executeRuntimeCall<T>(
+  request: StepRuntimeCall<T>,
+  clients: RuntimeClients
+): Promise<RuntimeCallResult<T>> {
+  try {
+    return { ok: true, value: await request.call(clients) };
+  } catch (err) {
+    if (InfrastructureError.is(err)) throw err;
+    if (err instanceof StepCallbackError) return { ok: false, error: err.cause };
+    if (isWorkflowFacingError(err)) return { ok: false, error: err };
+    throw new InfrastructureError(err);
+  }
+}
+
+/** Store failures caused by the workflow's own data, which it may catch. */
+function isWorkflowFacingError(err: unknown) {
+  return (
+    err instanceof StoreValidationError ||
+    err instanceof WorkflowValueError ||
+    (err instanceof Error && err.name === "StoreValidationError")
+  );
+}
+
+/** Runs a heap operation, tagging its failure as an infrastructure error. */
+export async function infrastructure<T>(fn: () => Promise<T>): Promise<T> {
+  try {
+    return await fn();
+  } catch (err) {
+    throw InfrastructureError.is(err) ? err : new InfrastructureError(err);
+  }
+}

package/src/internal/step-record.ts

@@ -0,0 +1,110 @@
+import {
+  DurableValueError,
+  StepDelay,
+  StepEffectWait,
+  StepError,
+  StepInvalid,
+  StepResult,
+  StepResponse,
+  StepStoreWait,
+  WorkflowResult,
+  WorkflowValueError,
+  decodeParsedValue,
+  durableValueCodec,
+  encodeThrownValue,
+} from "@yieldstar/core";
+
+/**
+ * Encodes a step response for its step record, and returns the response that
+ * workflow code must see: the record decoded again, so that a first run sees
+ * exactly what replay reads. A result the codec rejects is recorded as a step
+ * error with `WorkflowValueError` (`INVALID_STEP_VALUE`).
+ */
+export function encodeStepRecord(
+  response: StepResponse,
+  stepKey: string
+): { json: string; response: StepResponse } {
+  const json = encodeResponse(response, stepKey);
+  return { json, response: decodeStepRecord(json) };
+}
+
+function encodeResponse(response: StepResponse, stepKey: string): string {
+  if (response instanceof StepResult || response instanceof WorkflowResult) {
+    const result = durableValueCodec.encode(response.result);
+    if (result.status === "invalid") {
+      const label =
+        response instanceof WorkflowResult ? "Workflow result" : `Step "${stepKey}" result`;
+      return encodeResponse(
+        new StepError(
+          new WorkflowValueError(
+            "INVALID_STEP_VALUE",
+            stepKey,
+            `${label} is not a durable value: ${result.message}`
+          )
+        ),
+        stepKey
+      );
+    }
+    const schema =
+      response instanceof StepResult && response.schema !== undefined
+        ? `,"schema":${JSON.stringify(response.schema)}`
+        : "";
+    return `{"result":${result.canonical}${schema},"type":${JSON.stringify(response.type)}}`;
+  }
+  if (response instanceof StepError) {
+    return (
+      `{"backOffStrategy":${JSON.stringify(response.backOffStrategy)}` +
+      `,"err":${encodeThrownValue(response.err)}` +
+      `,"maxAttempts":${JSON.stringify(response.maxAttempts)}` +
+      `,"retryInterval":${JSON.stringify(response.retryInterval)}` +
+      `,"type":"step-error"}`
+    );
+  }
+  if (response instanceof StepDelay) {
+    return `{"type":"step-delay","wakeAt":${JSON.stringify(response.wakeAt)}}`;
+  }
+  if (response instanceof StepEffectWait) {
+    return `{"type":"effect-wait","wakeAt":${JSON.stringify(response.wakeAt)}}`;
+  }
+  if (response instanceof StepStoreWait || response instanceof StepInvalid) {
+    return `{"type":${JSON.stringify(response.type)}}`;
+  }
+  throw new Error(`Cannot record a ${response.type} step response`);
+}
+
+export function decodeStepRecord(json: string): StepResponse {
+  const record = JSON.parse(json);
+  try {
+    switch (record.type) {
+      case "step-result":
+        return new StepResult(
+          decodeParsedValue(record.result, "result"),
+          record.schema === "accepted" || record.schema === "rejected"
+            ? record.schema
+            : undefined
+        );
+      case "workflow-result":
+        return new WorkflowResult(decodeParsedValue(record.result, "result"));
+      case "step-error":
+        return new StepError(decodeParsedValue(record.err, "err"), {
+          maxAttempts: record.maxAttempts,
+          retryInterval: record.retryInterval,
+          backoffStrategy: record.backOffStrategy,
+        });
+      case "step-delay":
+        return new StepDelay(record.wakeAt);
+      case "effect-wait":
+        return new StepEffectWait(record.wakeAt);
+      case "store-wait":
+        return new StepStoreWait();
+      case "step-invalid":
+        return new StepInvalid();
+    }
+  } catch (err) {
+    if (err instanceof DurableValueError) {
+      throw new Error(`Invalid step record: ${err.message}`);
+    }
+    throw err;
+  }
+  throw new Error(`Unknown step record type: ${record.type}`);
+}