sailfork / t3code-github / .repos/ alchemy-effect/ packages/ integration-tests/ test/ AWS/ StepFunctions/ Simulate.test.ts

/**
 * In-process unit tests for the Step Functions program DSL: `Sfn.simulate`
 * interprets the SAME program the live `FromProgram.test.ts` deploys, plus
 * the ASL error semantics (`catchTag`, `retry`, `match`) and compile
 * determinism (the `normalizeDefinition` drift obligation).
 */
import { Sfn } from "@alchemy.run/aws/StepFunctions";
import { describe, expect, it } from "@alchemy.run/test";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Result from "effect/Result";
import { makeOrderProgram, OrderRejected, type OrderInput } from "./fixtures/order-program.ts";

const doubler: Sfn.InvokableFunction = {
  LogicalId: "SfnDoubler",
  functionArn: "arn:aws:lambda:us-east-1:000000000000:function:doubler",
};

const doublerHandlers: Sfn.SimulateHandlers = {
  SfnDoubler: (payload) =>
    Effect.succeed({ doubled: ((payload as { value: number }).value ?? 0) * 2 }),
};

describe(
  "Sfn.simulate",
  { tags: ["unit", "provider:aws", "provider:aws:stepfunctions", "local"] },
  () => {
    it.effect("runs the order program in-process", () =>
      Effect.gen(function* () {
        const result = yield* Sfn.simulate(
          makeOrderProgram(doubler),
          { value: 6, items: [1, 2, 3] } satisfies OrderInput,
          { handlers: doublerHandlers },
        );
        expect(result).toEqual({
          doubled: 12,
          items: [2, 4, 6],
          size: "big",
          recovered: "no stock",
        });
      }),
    );

    it.effect("takes the false Choice branch for small inputs", () =>
      Effect.gen(function* () {
        const result = yield* Sfn.simulate(
          makeOrderProgram(doubler),
          { value: 2, items: [] } satisfies OrderInput,
          { handlers: doublerHandlers },
        );
        expect(result.size).toBe("small");
        expect(result.items).toEqual([]);
      }),
    );

    it.effect("uncaught Sfn.fail surfaces as the typed failure", () =>
      Effect.gen(function* () {
        const result = yield* Effect.result(
          Sfn.simulate(Sfn.fail(new OrderRejected({ reason: "nope" })), {}),
        );
        expect(Result.isFailure(result)).toBe(true);
        if (Result.isFailure(result) && !(result.failure instanceof Sfn.SimulateError)) {
          expect(result.failure._tag).toBe("OrderRejected");
          expect(result.failure.reason).toBe("nope");
        }
      }),
    );

    it.effect("catchTag ignores non-matching tags", () =>
      Effect.gen(function* () {
        const program = Sfn.fail(new OrderRejected({ reason: "nope" })).pipe(
          Sfn.catchTag("SomethingElse", () => Sfn.succeed("recovered")),
        );
        const result = yield* Effect.result(Sfn.simulate(program, {}));
        expect(Result.isFailure(result)).toBe(true);
      }),
    );

    it.effect("retry re-runs matching tags up to maxAttempts", () =>
      Effect.gen(function* () {
        class Transient extends Data.TaggedError("Transient")<{}> {}
        let calls = 0;
        const program = Sfn.invoke<{ ok: boolean }, Transient>(doubler).pipe(
          Sfn.retry({ while: "Transient", maxAttempts: 5 }),
        );
        const result = yield* Sfn.simulate(program, null, {
          handlers: {
            SfnDoubler: () =>
              Effect.suspend(() => {
                calls++;
                return calls < 3 ? Effect.fail(new Transient()) : Effect.succeed({ ok: true });
              }),
          },
        });
        expect(result).toEqual({ ok: true });
        expect(calls).toBe(3);
      }),
    );

    it.effect("retry does not retry non-matching tags", () =>
      Effect.gen(function* () {
        let calls = 0;
        const program = Sfn.invoke(doubler).pipe(Sfn.retry({ while: "Transient", maxAttempts: 5 }));
        const result = yield* Effect.result(
          Sfn.simulate(program, null, {
            handlers: {
              SfnDoubler: () =>
                Effect.suspend(() => {
                  calls++;
                  return Effect.fail(new OrderRejected({ reason: "permanent" }));
                }),
            },
          }),
        );
        expect(Result.isFailure(result)).toBe(true);
        expect(calls).toBe(1);
      }),
    );

    it.effect("match dispatches on literal cases with a fallback", () =>
      Effect.gen(function* () {
        const program = Sfn.gen(function* (input: Sfn.Expr<{ kind: string }>) {
          return yield* Sfn.match(
            input.kind,
            { a: Sfn.succeed(1), b: Sfn.succeed(2) },
            Sfn.succeed(0),
          );
        });
        expect(yield* Sfn.simulate(program, { kind: "b" })).toBe(2);
        expect(yield* Sfn.simulate(program, { kind: "z" })).toBe(0);
      }),
    );

    it.effect("all runs branches and returns the tuple", () =>
      Effect.gen(function* () {
        const program = Sfn.all([
          Sfn.succeed("left"),
          Sfn.invoke<{ doubled: number }>(doubler, { value: 4 }),
        ]);
        const result = yield* Sfn.simulate(program, null, { handlers: doublerHandlers });
        expect(result).toEqual(["left", { doubled: 8 }]);
      }),
    );

    it.effect("waitForTaskToken dispatches to the integration handler", () =>
      Effect.gen(function* () {
        const program = Sfn.waitForTaskToken<{ approved: boolean }>({
          resource: "arn:aws:states:::sqs:sendMessage",
          arguments: { MessageBody: { token: Sfn.taskToken } },
        });
        const result = yield* Sfn.simulate(program, null, {
          taskToken: "tok-123",
          handlers: {
            "arn:aws:states:::sqs:sendMessage.waitForTaskToken": (payload) =>
              Effect.succeed({
                approved:
                  (payload as { MessageBody: { token: string } }).MessageBody.token === "tok-123",
              }),
          },
        });
        expect(result).toEqual({ approved: true });
      }),
    );

    it.effect("missing handler fails with SimulateError", () =>
      Effect.gen(function* () {
        const result = yield* Effect.result(Sfn.simulate(Sfn.invoke(doubler), null));
        expect(Result.isFailure(result)).toBe(true);
        if (Result.isFailure(result)) {
          expect(result.failure._tag).toBe("SimulateError");
        }
      }),
    );
  },
);

describe(
  "Sfn.compileProgram",
  { tags: ["unit", "provider:aws", "provider:aws:stepfunctions", "local"] },
  () => {
    it("compiles deterministically (drift-stable definitions)", () => {
      const first = Sfn.compileProgram(makeOrderProgram(doubler));
      const second = Sfn.compileProgram(makeOrderProgram(doubler));
      expect(JSON.stringify(first.definition)).toBe(JSON.stringify(second.definition));
      expect(first.definition.QueryLanguage).toBe("JSONata");
      expect(typeof first.definition.StartAt).toBe("string");
      // one lambda:InvokeFunction statement per invoked function (deduped)
      expect(first.policyStatements).toHaveLength(1);
    });

    it("rejects unreachable steps after an unconditional Sfn.fail", () => {
      const program = Sfn.gen(function* () {
        yield* Sfn.fail(new OrderRejected({ reason: "always" }));
        yield* Sfn.succeed("unreachable");
        return null;
      });
      expect(() => Sfn.compileProgram(program)).toThrow(/unreachable steps/);
    });

    it("rejects yielding a non-Sfn value at compile time", () => {
      const program = Sfn.gen(function* () {
        // a real Effect is a compile-time type error; simulate the runtime
        // guard with a plain value smuggled past the types
        yield* Effect.succeed(1) as unknown as Sfn.SfnEffect<number>;
        return null;
      });
      expect(() => Sfn.compileProgram(program)).toThrow(/may only yield Sfn effects/);
    });
  },
);