sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ StepFunctions/ Asl/ simulate.ts

/**
 * Local interpreter for Step Functions programs — the payoff of the AST.
 *
 * `simulate` runs the *same* `SfnEffect` a `StateMachine.fromProgram`
 * deploys, in-process, as a real `Effect`: Task states dispatch to
 * caller-provided handler stubs, Choice conditions evaluate against the
 * live variable environment, `catchTag`/`retry` follow the exact ASL error
 * semantics (`{ Error, Cause }` error output, `States.ALL` matching), and
 * `Wait` states are skipped (simulations are instantaneous).
 */
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Result from "effect/Result";
import { inputExpr, isExpr, nodeOf, variableExpr, type ExprNode } from "./Jsonata.ts";
import type { AslNode } from "./Node.ts";
import { isSfnEffect, type SfnEffect } from "./Program.ts";

/**
 * The simulation itself went wrong — a missing handler, an unsupported raw
 * JSONata expression, or a structurally invalid program. Distinct from the
 * program's own typed failures, which flow through the `E` channel.
 */
export class SimulateError extends Data.TaggedError("SimulateError")<{
  readonly message: string;
}> {}

/**
 * Handler stubs for the program's Task states, keyed by:
 * - the function's `LogicalId` for `Sfn.invoke` states,
 * - the integration resource ARN (including any `.waitForTaskToken`
 *   suffix) for `Sfn.integrate` / `Sfn.waitForTaskToken` states.
 */
export interface SimulateHandlers {
  readonly [key: string]: (payload: unknown) => Effect.Effect<any, any>;
}

export interface SimulateOptions {
  /** Task handler stubs. @default {} */
  readonly handlers?: SimulateHandlers;
  /** The task token exposed as `Sfn.taskToken`. @default "SIMULATED_TASK_TOKEN" */
  readonly taskToken?: string;
}

interface Env {
  readonly input: unknown;
  /** Variable scope — prototype chain mirrors ASL variable scoping. */
  vars: Record<string, unknown>;
  readonly taskToken: string;
  readonly handlers: SimulateHandlers;
  counter: { n: number };
}

/**
 * Internal failure wrapper preserving the exact ASL `Error`/`Cause` pair a
 * `Fail` state declares, so `catch` handlers observe the same
 * `$states.errorOutput` the cloud would produce. Unwrapped back to the
 * user's typed failure at the simulation boundary.
 */
class FailStateFailure {
  readonly _sim = "FailStateFailure";
  constructor(
    readonly error: string,
    readonly cause: string,
    readonly failure: unknown,
  ) {}
}

const isFailStateFailure = (value: unknown): value is FailStateFailure =>
  value instanceof FailStateFailure;

/** The ASL error name of a simulated failure (`_tag` convention). */
const errorNameOf = (failure: unknown): string => {
  if (isFailStateFailure(failure)) return failure.error;
  if (
    typeof failure === "object" &&
    failure !== null &&
    "_tag" in failure &&
    typeof (failure as { _tag: unknown })._tag === "string"
  ) {
    return (failure as { _tag: string })._tag;
  }
  return "States.TaskFailed";
};

const causeOf = (failure: unknown): string => {
  if (isFailStateFailure(failure)) return failure.cause;
  if (typeof failure === "object" && failure !== null) {
    const message = (failure as { message?: unknown }).message;
    if (typeof message === "string" && message.length > 0) return message;
    try {
      return JSON.stringify(failure);
    } catch {
      return errorNameOf(failure);
    }
  }
  return String(failure);
};

const evalExprNode = (node: ExprNode, env: Env): unknown => {
  switch (node._) {
    case "root":
      switch (node.root.kind) {
        case "input":
          return env.input;
        case "variable":
          return env.vars[node.root.name];
        case "token":
          return env.taskToken;
      }
    case "prop": {
      const parent = evalExprNode(node.parent, env) as Record<string, unknown> | null | undefined;
      return parent == null ? undefined : parent[node.name];
    }
    case "literal":
      return node.value;
    case "binop": {
      const left = evalExprNode(node.left, env) as any;
      const right = evalExprNode(node.right, env) as any;
      switch (node.op) {
        case "=":
          return left === right;
        case "!=":
          return left !== right;
        case ">":
          return left > right;
        case ">=":
          return left >= right;
        case "<":
          return left < right;
        case "<=":
          return left <= right;
        case "and":
          return Boolean(left) && Boolean(right);
        case "or":
          return Boolean(left) || Boolean(right);
      }
    }
    case "not":
      return !evalExprNode(node.inner, env);
    case "raw":
      throw new SimulateError({
        message: `raw JSONata expressions are not supported by simulate: ${node.jsonata}`,
      });
  }
};

/** Deep-evaluate a payload value: `Expr` references resolve against `env`. */
const evalValue = (value: unknown, env: Env): unknown => {
  if (value === undefined) return null;
  if (isExpr(value)) return evalExprNode(nodeOf(value), env);
  if (Array.isArray(value)) return value.map((entry) => evalValue(entry, env));
  if (typeof value === "object" && value !== null) {
    return Object.fromEntries(
      Object.entries(value).map(([key, entry]) => [key, evalValue(entry, env)]),
    );
  }
  return value;
};

const evalExpr = (value: unknown, env: Env) =>
  Effect.try({
    try: () => evalValue(value, env),
    catch: (error) =>
      error instanceof SimulateError ? error : new SimulateError({ message: String(error) }),
  });

const allocVar = (env: Env): string => `sim${env.counter.n++}`;

/** Child scope with an ASL scope barrier (Parallel branch / Map iteration). */
const childEnv = (env: Env): Env => ({
  ...env,
  vars: Object.create(env.vars) as Record<string, unknown>,
});

const runNode = (node: AslNode, env: Env): Effect.Effect<unknown, any> => {
  switch (node.kind) {
    case "invoke": {
      const handler = env.handlers[node.fn.LogicalId];
      if (handler === undefined) {
        return Effect.fail(
          new SimulateError({
            message: `no simulate handler for function "${node.fn.LogicalId}"`,
          }),
        );
      }
      return evalExpr(node.payload, env).pipe(Effect.flatMap(handler));
    }

    case "integrate": {
      const key = node.waitForTaskToken
        ? `${node.options.resource}.waitForTaskToken`
        : node.options.resource;
      const handler = env.handlers[key];
      if (handler === undefined) {
        return Effect.fail(
          new SimulateError({
            message: `no simulate handler for integration "${key}"`,
          }),
        );
      }
      return evalExpr(node.options.arguments, env).pipe(Effect.flatMap(handler));
    }

    case "all":
      return Effect.forEach(node.branches, (branch) => runNode(branch.node, childEnv(env)));

    case "forEach":
      return evalExpr(node.items, env).pipe(
        Effect.flatMap((items) => {
          if (!Array.isArray(items)) {
            return Effect.fail(
              new SimulateError({
                message: "Sfn.forEach items did not evaluate to an array",
              }),
            );
          }
          return Effect.forEach(items, (item) => {
            // mirror compile: the item is bound to a fresh variable scoped
            // to the iteration
            const scope = childEnv(env);
            const itemVar = allocVar(scope);
            scope.vars[itemVar] = item;
            const body = node.body(variableExpr(itemVar));
            if (!isSfnEffect(body)) {
              return Effect.fail(
                new SimulateError({
                  message: "Sfn.forEach body must return an Sfn effect",
                }),
              );
            }
            return runNode(body.node, scope);
          });
        }),
      );

    case "sleep":
      // simulations are instantaneous — Wait states are skipped
      return Effect.succeed(null);

    case "when":
      return evalExpr(node.condition, env).pipe(
        Effect.flatMap((condition) =>
          condition
            ? runNode(node.onTrue.node, env)
            : node.onFalse !== undefined
              ? runNode(node.onFalse.node, env)
              : Effect.succeed(null),
        ),
      );

    case "match":
      return evalExpr(node.value, env).pipe(
        Effect.flatMap((value) => {
          const program = node.cases[String(value)] ?? node.otherwise;
          if (program === undefined) {
            return Effect.fail(
              new SimulateError({
                message: `States.NoChoiceMatched: no case for ${JSON.stringify(value)}`,
              }),
            );
          }
          return runNode(program.node, env);
        }),
      );

    case "succeed":
      return evalExpr(node.value, env);

    case "fail":
      return Effect.fail(new FailStateFailure(node.error, node.cause, node.failure));

    case "retry": {
      const tags =
        node.options.while === undefined
          ? ["States.ALL"]
          : typeof node.options.while === "string"
            ? [node.options.while]
            : [...node.options.while];
      const maxAttempts = node.options.maxAttempts ?? 3;
      const attempt = (retriesLeft: number): Effect.Effect<unknown, any> =>
        Effect.result(runNode(node.inner.node, env)).pipe(
          Effect.flatMap((result) => {
            if (Result.isSuccess(result)) return Effect.succeed(result.success);
            const failure = result.failure;
            const retryable =
              !(failure instanceof SimulateError) &&
              (tags.includes("States.ALL") || tags.includes(errorNameOf(failure)));
            return retryable && retriesLeft > 0 ? attempt(retriesLeft - 1) : Effect.fail(failure);
          }),
        );
      return attempt(maxAttempts);
    }

    case "catch":
      return Effect.result(runNode(node.inner.node, env)).pipe(
        Effect.flatMap((result) => {
          if (Result.isSuccess(result)) return Effect.succeed(result.success);
          const failure = result.failure;
          const matches =
            !(failure instanceof SimulateError) &&
            (node.tags.includes("States.ALL") || node.tags.includes(errorNameOf(failure)));
          if (!matches) return Effect.fail(failure);
          const errorVar = allocVar(env);
          env.vars[errorVar] = {
            Error: errorNameOf(failure),
            Cause: causeOf(failure),
          };
          const handler = node.handler(variableExpr(errorVar));
          if (!isSfnEffect(handler)) {
            return Effect.fail(
              new SimulateError({
                message: "Sfn.catchTag/catchAll handler must return an Sfn effect",
              }),
            );
          }
          return runNode(handler.node, env);
        }),
      );

    case "gen":
      return Effect.gen(function* () {
        const iterator = node.body(inputExpr());
        let step = iterator.next();
        while (!step.done) {
          const program: unknown = step.value;
          if (!isSfnEffect(program)) {
            return yield* new SimulateError({
              message: "Sfn.gen may only yield Sfn effects",
            });
          }
          const value = yield* runNode(program.node, env);
          const name = allocVar(env);
          env.vars[name] = value;
          step = iterator.next(variableExpr(name));
        }
        return yield* evalExpr(step.value, env);
      });
  }
};

/**
 * Run a Step Functions program in-process as an `Effect` — same AST the
 * cloud executes, interpreted locally for unit tests.
 *
 * ```typescript
 * const result = yield* simulate(program, { value: 6, items: [1, 2, 3] }, {
 *   handlers: {
 *     Doubler: (payload) =>
 *       Effect.succeed({ doubled: (payload as { value: number }).value * 2 }),
 *   },
 * });
 * ```
 */
export const simulate = <A, E>(
  program: SfnEffect<A, E>,
  input: unknown,
  options?: SimulateOptions,
): Effect.Effect<A, E | SimulateError> => {
  const env: Env = {
    input,
    vars: Object.create(null) as Record<string, unknown>,
    taskToken: options?.taskToken ?? "SIMULATED_TASK_TOKEN",
    handlers: options?.handlers ?? {},
    counter: { n: 0 },
  };
  return runNode(program.node, env).pipe(
    Effect.mapError((failure) => (isFailStateFailure(failure) ? failure.failure : failure)),
  ) as Effect.Effect<A, E | SimulateError>;
};