import * as Cause from "effect/Cause";
import * as Context from "effect/Context";
import * as Data from "effect/Data";
import * as DateTime from "effect/DateTime";
import * as Deferred from "effect/Deferred";
import * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as Exit from "effect/Exit";
import * as Formatter from "effect/Formatter";
import * as Layer from "effect/Layer";
import * as Option from "effect/Option";
import * as Redacted from "effect/Redacted";
import * as Schema from "effect/Schema";
import type { DurableDeferred, WorkflowEngine } from "effect/workflow";
import * as Aggregate from "./Aggregate.ts";
import type * as Command from "./Command.ts";
import * as ExternalSystem from "./ExternalSystem.ts";
import * as InMemory from "./InMemory.ts";
import type * as Key from "./Key.ts";
import * as Model from "./Model.ts";
import type * as Saga from "./Saga.ts";
import type * as DomainStream from "./Stream.ts";
import type * as View from "./View.ts";
/** How far a story got with one step. */
export interface StepReport {
/** The step's number, from 1. */
readonly step: number;
/** The step's kind: `Given`, `When`, `Then`, ... */
readonly kind: Step["_tag"];
readonly status: "passed" | "failed" | "not-run";
/** A one-line summary of the step. Redacted values print as `<redacted>`. */
readonly summary: string;
}
/**
* A failed story expectation. `message` starts with `reason`, then lists every
* step (✓ passed, ✗ failed, blank: not run) and the events each touched
* aggregate committed so far.
*/
export class StoryFailure extends Data.TaggedError("StoryFailure")<{
/** The step that failed (the last step for a failure at the end of the story). */
readonly step: number;
readonly message: string;
/** Why the story failed, without the step list. */
readonly reason: string;
readonly steps: ReadonlyArray<StepReport>;
/** The tags of the events committed so far, per touched aggregate (`Aggregate/id`). */
readonly events: Readonly<Record<string, ReadonlyArray<string>>>;
}> {}
/** A failure inside the runner, before it is turned into a {@link StoryFailure}. */
class StepFailed extends Data.TaggedError("StepFailed")<{
readonly step: number;
readonly message: string;
/** The failure is about the whole story, not one step. */
readonly atEnd?: boolean;
/** What the step expected and what it got, as short summaries. */
readonly expected?: string;
readonly actual?: string;
/** What the expected / actual pair is about, e.g. `Counter/c-1`. */
readonly label?: string;
/** A line to print under the failed step. */
readonly detail?: string;
}> {}
/** Marker for "the view key does not exist". */
const none: unique symbol = Symbol.for("alchemy/Domain/Story.none") as any;
/**
* One step of a story. Build steps with the step constructors in this module.
*/
export type Step =
| {
readonly _tag: "Given";
readonly ref: Aggregate.Ref;
readonly events: ReadonlyArray<{ readonly _tag: string }>;
}
| {
readonly _tag: "When";
readonly ref: Aggregate.Ref;
readonly command: { readonly _tag: string };
readonly commandId?: string;
}
| {
readonly _tag: "Then";
readonly ref: Aggregate.Ref;
readonly events: ReadonlyArray<{ readonly _tag: string }>;
}
| { readonly _tag: "Rejected"; readonly rejection: { readonly _tag: string } }
| { readonly _tag: "Replied"; readonly reply: unknown }
| { readonly _tag: "State"; readonly ref: Aggregate.Ref; readonly expected: unknown }
| {
readonly _tag: "View";
readonly view: View.Any;
/** A ref, or the value of a Schema key. */
readonly key: Key.RefOf<Key.Any>;
readonly expected: unknown;
}
| {
readonly _tag: "Emitted";
readonly view: View.Any;
/** A ref, or the value of a Schema key. */
readonly key: Key.RefOf<Key.Any>;
readonly expected: unknown;
}
| {
readonly _tag: "Streamed";
readonly stream: DomainStream.Any;
/** A ref, or the value of a Schema key. */
readonly key: Key.RefOf<Key.Any>;
readonly events: ReadonlyArray<{ readonly _tag: string }>;
}
| {
readonly _tag: "Call";
readonly tag: string | undefined;
readonly op: ExternalSystem.Op;
readonly args: unknown;
}
| {
readonly _tag: "Answer";
readonly tag: string | undefined;
readonly op: ExternalSystem.Op;
readonly exit: Exit.Exit<unknown, unknown>;
}
| {
readonly _tag: "Returned";
readonly tag: string | undefined;
readonly op: ExternalSystem.Op;
readonly expected:
| { readonly _tag: "Success"; readonly value: unknown }
| { readonly _tag: "Failure"; readonly error: unknown }
| { readonly _tag: "Died" };
}
| { readonly _tag: "Clock"; readonly at: string | number | DateTime.DateTime }
| { readonly _tag: "Advance"; readonly by: Duration.Input }
| {
readonly _tag: "Signal";
readonly saga: Saga.Any;
readonly key: unknown;
readonly deferred: DurableDeferred.Any;
readonly value: unknown;
}
| {
readonly _tag: "Saga";
readonly saga: Saga.Any;
readonly key: unknown;
readonly expected: Saga.Status<unknown, unknown> | { readonly _tag: "Died" };
}
| {
readonly _tag: "Provide";
readonly service: Context.Key<unknown, unknown>;
readonly value: unknown;
};
/** The step with this `_tag`. */
export type StepOf<Tag extends Step["_tag"]> = Extract<Step, { readonly _tag: Tag }>;
/**
* A `when` step. Its type carries the command's class, so the steps after it
* are checked against what the command declares.
*/
export interface WhenStep<C = unknown> extends StepOf<"When"> {
readonly "~command"?: C;
}
/** A `rejected` step; its type carries the rejection. */
export interface RejectedStep<R = unknown> extends StepOf<"Rejected"> {
readonly "~rejection"?: R;
}
/** A `replied` step; its type carries the reply. */
export interface RepliedStep<A = unknown> extends StepOf<"Replied"> {
readonly "~reply"?: A;
}
/** A `provide` step; its type carries the service it provides. */
export interface ProvideStep<I = unknown> extends StepOf<"Provide"> {
readonly "~provides"?: I;
}
type CommandClassOf<A extends Aggregate.Any, Cmd> = Extract<
A["definition"]["commands"][number],
{ readonly tag: Cmd extends { readonly _tag: infer T } ? T : never }
>;
type RejectionOf<C extends Command.Any> = Aggregate.InstanceOf<C["rejects"][number]>;
type ReplyOf<C extends Command.Any> = C["reply"] extends Schema.Top ? C["reply"]["Type"] : void;
type NameOf<X, Key extends string, Fallback extends string> = X extends {
readonly [K in Key]: infer N extends string;
}
? N
: Fallback;
/** What a `when` step must be: an error message when a service it needs is not provided yet. */
type CheckWhen<H, K extends Command.Any, P> = [Exclude<Command.ContextOf<K>, P>] extends [never]
? H
: `${K["tag"]} needs Story.provide(${NameOf<Exclude<Command.ContextOf<K>, P>, "key", "its service">}) before it`;
/** What a `rejected` step must be: an error message when the last command does not declare it. */
type CheckRejected<H, R, C> = C extends Command.Any
? [R] extends [RejectionOf<C>]
? H
: `${C["tag"]} does not reject with ${NameOf<R, "_tag", "this rejection">}`
: H;
/** What a `replied` step must be: the last command's reply, or an error message when it declares none. */
type CheckReplied<H, A, C> = C extends Command.Any
? [A] extends [ReplyOf<C>]
? H
: C["reply"] extends Schema.Top
? RepliedStep<ReplyOf<C>>
: `${C["tag"]} declares no reply`
: H;
/**
* The steps of a story, checked in order: a `rejected` step takes only a
* rejection the last `when` command declares, a `replied` step only its reply
* type, and a `when` needs a `provide` step before it for every service its
* command's middleware provides. A failing step is replaced by a message
* saying what is wrong, so the type error names it. A step typed as plain
* {@link Step} turns the checks off until the next `when`, since it may be any
* step.
*/
export type Checked<
S extends ReadonlyArray<Step>,
C = unknown,
P = never,
Out extends ReadonlyArray<unknown> = [],
> = S extends readonly [infer H extends Step, ...infer T extends ReadonlyArray<Step>]
? [H] extends [WhenStep<infer K>]
? K extends Command.Any
? Checked<T, K, P, [...Out, CheckWhen<H, K, P>]>
: Checked<T, unknown, P, [...Out, H]>
: [H] extends [ProvideStep<infer I>]
? Checked<T, C, P | I, [...Out, H]>
: [H] extends [RejectedStep<infer R>]
? Checked<T, C, P, [...Out, CheckRejected<H, R, C>]>
: [H] extends [RepliedStep<infer A>]
? Checked<T, C, P, [...Out, CheckReplied<H, A, C>]>
: [Step] extends [H]
? Checked<T, unknown, any, [...Out, H]>
: Checked<T, C, P, [...Out, H]>
: [...Out, ...S];
/** History: events already committed on a stream before the story starts. */
const given = <A extends Aggregate.Any>(
ref: Aggregate.Ref<A>,
...events: ReadonlyArray<Aggregate.EventOf<A>>
): StepOf<"Given"> => ({
_tag: "Given",
ref,
events: events as ReadonlyArray<{ readonly _tag: string }>,
});
/** Send a command. Its policies run until they finish or suspend on an external system call. */
const when = <A extends Aggregate.Any, Cmd extends Aggregate.CommandOf<A>>(
ref: Aggregate.Ref<A>,
command: Cmd,
options?: { readonly commandId?: string },
): WhenStep<CommandClassOf<A, Cmd>> => ({
_tag: "When",
ref,
command: command as { readonly _tag: string },
commandId: options?.commandId,
});
/** The next events committed on a stream. With no events: nothing new was committed. */
const then = <A extends Aggregate.Any>(
ref: Aggregate.Ref<A>,
...events: ReadonlyArray<Aggregate.EventOf<A>>
): StepOf<"Then"> => ({
_tag: "Then",
ref,
events: events as ReadonlyArray<{ readonly _tag: string }>,
});
/**
* The last command was rejected with exactly this rejection. It must be one
* the last `when` command declares in `rejects`.
*/
const rejected = <R extends { readonly _tag: string }>(rejection: R): RejectedStep<R> => ({
_tag: "Rejected",
rejection,
});
/** The last command's reply, of the type the last `when` command declares. */
const replied = <A>(reply: A): RepliedStep<A> => ({ _tag: "Replied", reply });
/** Assert on an aggregate instance's current state: an expected (partial) state, or a function. */
const state = <A extends Aggregate.Any>(
ref: Aggregate.Ref<A>,
expected: Partial<Aggregate.StateOf<A>> | ((state: Aggregate.StateOf<A>) => void),
): StepOf<"State"> => ({ _tag: "State", ref, expected });
/** Assert on a view key: an expected (partial) state, a function, or {@link none}. */
const view = <V extends View.Any>(
view: V,
key: Key.RefOf<View.KeyOf<V>>,
expected: Partial<View.StateOf<V>> | ((state: View.StateOf<V>) => void) | typeof none,
): StepOf<"View"> => ({ _tag: "View", view, key, expected });
/**
* Assert on every event a view key has emitted: the expected (partial) events
* in order, or a function over the entries (each event with the state after it).
*/
const emitted = <V extends View.Any>(
view: V,
key: Key.RefOf<View.KeyOf<V>>,
expected:
| ReadonlyArray<Partial<View.EventOf<V>>>
| ((entries: ReadonlyArray<View.Entry<View.StateOf<V>, View.EventOf<V>>>) => void),
): StepOf<"Emitted"> => ({ _tag: "Emitted", view, key, expected });
/**
* The next entries appended to a stream key (by its projection). With no
* events: nothing new was appended.
*/
const streamed = <S extends DomainStream.Any>(
stream: S,
key: Key.RefOf<DomainStream.KeyOf<S>>,
...events: ReadonlyArray<DomainStream.EventOf<S>>
): StepOf<"Streamed"> => ({
_tag: "Streamed",
stream,
key,
events: events as ReadonlyArray<{ readonly _tag: string }>,
});
/**
* A call to an external system was made with these (partial) arguments:
* `Story.call(Payments.refund, { settlementId: "st_1" })`. Every call needs
* one: a stubbed call before it's answered, a real call before it's asserted.
* Each call is matched once, earliest first. With a tag first, the tag names
* that call, so a later step can answer or assert exactly it.
*/
const callStep: {
<Args>(op: ExternalSystem.Op<Args, any>, args: Partial<Args>): StepOf<"Call">;
<Args>(tag: string, op: ExternalSystem.Op<Args, any>, args: Partial<Args>): StepOf<"Call">;
} = (...a: ReadonlyArray<any>): StepOf<"Call"> =>
typeof a[0] === "string"
? { _tag: "Call", tag: a[0], op: a[1], args: a[2] }
: { _tag: "Call", tag: undefined, op: a[0], args: a[1] };
/** Answer a pending call with an exit; the tag, when given, comes first. */
const answer = (
a: ReadonlyArray<any>,
exit: (value: any) => Exit.Exit<unknown, unknown>,
): StepOf<"Answer"> =>
typeof a[0] === "string"
? { _tag: "Answer", tag: a[0], op: a[1], exit: exit(a[2]) }
: { _tag: "Answer", tag: undefined, op: a[0], exit: exit(a[1]) };
/**
* Answer an external system call a `call` step has checked. With a tag
* first, answers the call a `call` step tagged; without one, answers the only
* pending call to the operation, and fails if several are pending.
*/
const succeed: {
<Success>(op: ExternalSystem.Op<any, Success>, value: Success): StepOf<"Answer">;
<Success>(tag: string, op: ExternalSystem.Op<any, Success>, value: Success): StepOf<"Answer">;
} = (...a: ReadonlyArray<any>): StepOf<"Answer"> => answer(a, Exit.succeed);
/**
* Fail an external system call with one of the operation's declared errors,
* as when the vendor refuses. Finds the call the same way `succeed` does.
*/
const fail: {
<Error>(op: ExternalSystem.Op<any, any, Error>, error: NoInfer<Error>): StepOf<"Answer">;
<Error>(
tag: string,
op: ExternalSystem.Op<any, any, Error>,
error: NoInfer<Error>,
): StepOf<"Answer">;
} = (...a: ReadonlyArray<any>): StepOf<"Answer"> => answer(a, Exit.fail);
/**
* Fail an external system call with a defect, as when the transport breaks.
* Finds the call the same way `succeed` does.
*/
const die: {
(op: ExternalSystem.Op, defect: unknown): StepOf<"Answer">;
(tag: string, op: ExternalSystem.Op, defect: unknown): StepOf<"Answer">;
} = (...a: ReadonlyArray<any>): StepOf<"Answer"> => answer(a, Exit.die);
/** Assert how a real call to a system that is not stubbed ended; the tag, when given, comes first. */
const outcome = (a: ReadonlyArray<any>, expected: (value: any) => any): StepOf<"Returned"> =>
typeof a[0] === "string"
? { _tag: "Returned", tag: a[0], op: a[1], expected: expected(a[2]) }
: { _tag: "Returned", tag: undefined, op: a[0], expected: expected(a[1]) };
/**
* A real call to an external system that is not stubbed returned this value.
* Finds the call the way `succeed` does: by tag, or the only unasserted call
* to the operation. Every real call needs a `call` step, then one of
* `returned`, `failed` or `died`.
*/
const returned: {
<Success>(op: ExternalSystem.Op<any, Success>, value: Success): StepOf<"Returned">;
<Success>(tag: string, op: ExternalSystem.Op<any, Success>, value: Success): StepOf<"Returned">;
} = (...a: ReadonlyArray<any>): StepOf<"Returned"> =>
outcome(a, (value) => ({ _tag: "Success", value }));
/** A real call to an external system that is not stubbed failed with this declared error. */
const failed: {
<Error>(op: ExternalSystem.Op<any, any, Error>, error: NoInfer<Error>): StepOf<"Returned">;
<Error>(
tag: string,
op: ExternalSystem.Op<any, any, Error>,
error: NoInfer<Error>,
): StepOf<"Returned">;
} = (...a: ReadonlyArray<any>): StepOf<"Returned"> =>
outcome(a, (error) => ({ _tag: "Failure", error }));
/** A real call to an external system that is not stubbed died with a defect. */
const died: {
(op: ExternalSystem.Op): StepOf<"Returned">;
(tag: string, op: ExternalSystem.Op): StepOf<"Returned">;
} = (...a: ReadonlyArray<any>): StepOf<"Returned"> =>
typeof a[0] === "string"
? { _tag: "Returned", tag: a[0], op: a[1], expected: { _tag: "Died" } }
: { _tag: "Returned", tag: undefined, op: a[0], expected: { _tag: "Died" } };
/** Move the clock: later commands are stamped with it, and scheduled commands now due fire. */
const clock = (at: string | number | DateTime.DateTime): StepOf<"Clock"> => ({ _tag: "Clock", at });
/** Move the clock forward by a duration, like `"1 day"`: the same as `clock` at the current time plus `by`. */
const advance = (by: Duration.Input): StepOf<"Advance"> => ({ _tag: "Advance", by });
type SagaClientOf<S> = S extends Context.Key<any, infer C> ? C : never;
type SagaKeyOf<S> =
SagaClientOf<S> extends Saga.Client<infer K, any, any, any> ? K | { readonly id: K } : never;
type SagaStatusOf<S> =
SagaClientOf<S> extends Saga.Client<any, any, infer A, infer E> ? Saga.Status<A, E> : never;
/** Complete a `DurableDeferred` a saga run waits on, then let it run. */
const signal = <S extends Saga.Any, Success extends Schema.Constraint>(
saga: S,
key: SagaKeyOf<S>,
deferred: DurableDeferred.DurableDeferred<Success, any>,
value: Success["Type"],
): StepOf<"Signal"> => ({ _tag: "Signal", saga, key, deferred, value });
/**
* Check where a saga run is: running, completed with a result, rejected,
* interrupted, or died. `{ _tag: "Died" }` matches any defect; with a
* `defect`, it must read the same.
*/
const saga = <S extends Saga.Any>(
saga: S,
key: SagaKeyOf<S>,
expected: SagaStatusOf<S> | { readonly _tag: "Died" },
): StepOf<"Saga"> => ({
_tag: "Saga",
saga,
key,
expected: expected as Saga.Status<unknown, unknown>,
});
/** A saga status, in a form to compare: rejections encoded, defects as text. */
const statusJson = (status: Saga.Status<unknown, unknown> | { readonly _tag: "Died" }) =>
status._tag === "Rejected"
? { _tag: "Rejected", rejection: encodeInstance(status.rejection as { readonly _tag: string }) }
: status._tag === "Died"
? "defect" in status
? { _tag: "Died", defect: String(status.defect) }
: { _tag: "Died" }
: status;
/**
* Provide a service to subsequent commands, as their middleware would (for
* example the current actor). Replaces any earlier value of the same service.
*/
const provide = <I, S>(service: Context.Key<I, S>, value: S): ProvideStep<I> => ({
_tag: "Provide",
service: service as unknown as Context.Key<unknown, unknown>,
value,
});
const normalize = (value: unknown, redact = false): unknown => {
if (redact && Redacted.isRedacted(value)) return "<redacted>";
if (DateTime.isDateTime(value)) return DateTime.formatIso(value);
if (Array.isArray(value)) return value.map((v) => normalize(v, redact));
if (value !== null && typeof value === "object") {
const out: Record<string, unknown> = {};
for (const key of Object.keys(value)) out[key] = normalize((value as any)[key], redact);
return out;
}
return value;
};
/** JSON for a failure message: redacted values print as `<redacted>`. */
const show = (value: unknown) => JSON.stringify(normalize(value, true));
const clip = (text: string, max: number) =>
text.length > max ? `${text.slice(0, max - 1)}…` : text;
/** A short, one-line form of a value: `Tag { field: value }`, nested values elided. */
const brief = (value: unknown, depth = 0): string => {
if (Redacted.isRedacted(value)) return "<redacted>";
if (DateTime.isDateTime(value)) return DateTime.formatIso(value);
if (value instanceof Date) return value.toISOString();
if (typeof value === "string") return JSON.stringify(clip(value, 24));
if (typeof value === "bigint") return `${value}n`;
if (value === null || typeof value !== "object") return String(value);
if (Array.isArray(value))
return depth > 0 ? `[${value.length}]` : `[${value.map((v) => brief(v, 1)).join(", ")}]`;
const tag = typeof (value as any)._tag === "string" ? ((value as any)._tag as string) : undefined;
if (depth > 1) return tag ?? "{…}";
const fields = Object.keys(value)
.filter((key) => key !== "_tag")
.map((key) => `${key}: ${brief((value as any)[key], depth + 1)}`);
const body = fields.length > 0 ? `{ ${fields.join(", ")} }` : tag ? "" : "{}";
return tag && body ? `${tag} ${body}` : (tag ?? body);
};
const summarize = (value: unknown) => clip(brief(value), 80);
const summarizeAll = (values: ReadonlyArray<unknown>, none = "nothing new") =>
values.length === 0 ? none : clip(values.map((v) => brief(v)).join(", "), 80);
const refName = (ref: Aggregate.Ref) => `${ref.aggregate}/${ref.id}`;
const callName = (tag: string | undefined, op: ExternalSystem.Op) =>
`${tag === undefined ? "" : `"${tag}" `}${op.system}.${op.op}`;
/** A `clock` step's time in epoch milliseconds; `NaN` for a string that is not a time. */
const clockMillis = (at: string | number | DateTime.DateTime) =>
typeof at === "number"
? at
: typeof at === "string"
? Date.parse(at)
: DateTime.toEpochMillis(at);
/** An `advance` step's duration; `undefined` for an input that is not a finite duration. */
const advanceDuration = (by: Duration.Input) =>
Option.getOrUndefined(Option.filter(Duration.fromInput(by), Duration.isFinite));
const showDurationInput = (by: Duration.Input): string =>
typeof by === "string" ? by : Formatter.format(by);
/** A one-line summary of a step, before it runs. */
const describeStep = (s: Step): string => {
switch (s._tag) {
case "Advance": {
const by = advanceDuration(s.by);
if (by === undefined) return showDurationInput(s.by);
return `${Duration.isNegative(by) ? "" : "+"}${Duration.format(by)}`;
}
case "Clock": {
const at = clockMillis(s.at);
return Number.isNaN(at) ? String(s.at) : new Date(at).toISOString();
}
case "Provide":
return `${s.service.key} = ${summarize(s.value)}`;
case "Given":
case "Then":
return `${refName(s.ref)}: ${summarizeAll(s.events)}`;
case "When":
return `${refName(s.ref)}: ${summarize(s.command)}`;
case "Rejected":
return summarize(s.rejection);
case "Replied":
return summarize(s.reply);
case "State":
return `${refName(s.ref)}${typeof s.expected === "function" ? "" : `: ${summarize(s.expected)}`}`;
case "View":
return `${s.view.viewName}(${Aggregate.targetId(s.key)})${s.expected === none ? ": none" : typeof s.expected === "function" ? "" : `: ${summarize(s.expected)}`}`;
case "Emitted":
return `${s.view.viewName}(${Aggregate.targetId(s.key)})${typeof s.expected === "function" ? "" : `: ${summarizeAll(s.expected as ReadonlyArray<unknown>)}`}`;
case "Streamed":
return `${s.stream.streamName}/${Aggregate.targetId(s.key)}: ${summarizeAll(s.events)}`;
case "Call":
return `${callName(s.tag, s.op)} ${summarize(s.args)}`;
case "Answer":
return `${callName(s.tag, s.op)} → ${
Exit.isSuccess(s.exit)
? summarize(s.exit.value)
: Option.match(Cause.findErrorOption(s.exit.cause), {
onSome: (error) => `fail ${summarize(error)}`,
onNone: () => "die",
})
}`;
case "Returned":
return `${callName(s.tag, s.op)} → ${
s.expected._tag === "Success"
? summarize(s.expected.value)
: s.expected._tag === "Failure"
? `failed ${summarize(s.expected.error)}`
: "died"
}`;
case "Signal":
return `${s.saga.sagaName} ${summarize(s.key)}: ${summarize(s.value)}`;
case "Saga":
return `${s.saga.sagaName} ${summarize(s.key)}: ${s.expected._tag}`;
}
};
/** The story, step by step, with the failed step marked: the tail of a failure message. */
const renderReport = (
failure: StepFailed,
steps: ReadonlyArray<StepReport>,
events: Readonly<Record<string, ReadonlyArray<string>>>,
): string => {
const width = String(steps.length).length;
const lines: Array<string> = [];
for (const s of steps) {
const mark = s.status === "passed" ? "✓" : s.status === "failed" ? "✗" : " ";
const head = ` ${mark} ${String(s.step).padStart(width)} ${s.kind.padEnd(10)} `;
const indent = " ".repeat(head.length);
if (s.status !== "failed") {
lines.push(head + s.summary);
continue;
}
if (failure.expected !== undefined && failure.actual !== undefined) {
// `Ref: expected X` / ` got Y`, with the ref (if any) kept in front.
const label = failure.label === undefined ? "" : `${failure.label}: `;
lines.push(`${head}${label}expected ${failure.expected}`);
lines.push(`${indent}${" ".repeat(label.length)}got ${failure.actual}`);
} else {
lines.push(head + s.summary);
}
if (failure.detail !== undefined) lines.push(indent + failure.detail);
}
if (failure.atEnd) {
const head = ` ✗ ${" ".repeat(width)} ${"end".padEnd(10)} `;
const detail = failure.detail?.split("\n") ?? [];
lines.push(detail.length > 0 ? head + detail[0] : head.trimEnd());
for (const line of detail.slice(1)) lines.push(" ".repeat(head.length) + line);
}
lines.push(" events so far");
const streams = Object.entries(events);
if (streams.length === 0) lines.push(" nothing");
for (const [stream, tags] of streams)
lines.push(` ${stream}: ${tags.length === 0 ? "nothing" : clip(tags.join(" → "), 120)}`);
return lines.join("\n");
};
const encodeInstance = (value: { readonly _tag: string }): unknown => {
const schema = (value as any).constructor as Schema.Top;
// oxlint-disable-next-line effecttsgo/schema-sync -- encodes a value for a sync story report
return Schema.encodeUnknownSync(Schema.toCodecJson(schema as any) as any)(value);
};
const equal = (a: unknown, b: unknown) => show(a) === show(b);
/** A tagged error by its encoded fields; anything else as it is. */
const errorJson = (error: unknown): unknown => {
if (error !== null && typeof error === "object" && "_tag" in error) {
try {
return encodeInstance(error as { readonly _tag: string });
} catch {
return normalize(error);
}
}
return normalize(error);
};
const exitJson = (
exit: Exit.Exit<unknown, unknown>,
):
| { readonly _tag: "Success"; readonly value: unknown }
| { readonly _tag: "Failure"; readonly error: unknown }
| { readonly _tag: "Died"; readonly defect: string } => {
if (Exit.isSuccess(exit)) return { _tag: "Success", value: normalize(exit.value) };
const error = Cause.findErrorOption(exit.cause);
return Option.isSome(error)
? { _tag: "Failure", error: errorJson(error.value) }
: { _tag: "Died", defect: String(Cause.squash(exit.cause)) };
};
const partial = (expected: unknown, actual: unknown): boolean => {
const e = normalize(expected);
const a = normalize(actual);
if (e !== null && typeof e === "object" && !Array.isArray(e)) {
if (a === null || typeof a !== "object") return false;
return Object.keys(e).every((k) => partial((e as any)[k], (a as any)[k]));
}
return JSON.stringify(e) === JSON.stringify(a);
};
interface PendingCall {
readonly system: string;
readonly op: string;
readonly args: unknown;
readonly deferred: Deferred.Deferred<unknown, unknown>;
/** The name its `call` step gave it, if any. */
tag: string | undefined;
/** Whether a `call` step checked its arguments. */
expected: boolean;
}
interface ObservedCall {
readonly system: string;
readonly op: string;
readonly args: unknown;
/** How the call ended; undefined while it runs. */
exit: Exit.Exit<unknown, unknown> | undefined;
readonly done: Deferred.Deferred<void>;
/** The name its `call` step gave it, if any. */
tag: string | undefined;
/** Whether a `call` step matched it. */
expected: boolean;
}
/** Options for {@link make}. */
interface StoryOptions<Policies, LE, LR, Systems> {
/** The policies' and projections' Layers. Required when the model has either. */
readonly layer?: Layer.Layer<Policies, LE, LR>;
/**
* External systems to fake. Each call to one waits until the story answers it
* with `succeed`, `fail` or `die`. Systems not listed are called for real,
* through the Layers you provide to the story, and the story asserts what
* each call returned with `returned`, `failed` or `died`.
*/
readonly stub?: ReadonlyArray<Systems>;
}
/**
* Create a story runner for a Domain. A story is a sequence of steps run
* against an in-memory host: policies run for real, calls to stubbed external
* systems suspend until the story answers them, and calls to the others run
* through the Layers you provide while the story records them.
*
* **Example:** A story
* ```typescript
* const story = Story.make(Bank, {
* layer: BankPolicies,
* stub: [FraudCheck, Payments],
* });
*
* it.effect("withdraw replies with the new balance", () =>
* story(
* Story.given(a1, new AccountOpened({ ... }), new MoneyDeposited({ amount: 100, balanceAfter: 100 })),
* Story.provide(CurrentActor, sam),
* Story.when(a1, new WithdrawMoney({ amount: 30 })),
* Story.then(a1, new MoneyWithdrawn({ amount: 30, balanceAfter: 70 })),
* Story.replied({ balance: 70 }),
* ),
* );
* ```
*/
const make =
<
Name extends string,
Provided,
Policies,
LE = never,
LR = never,
Systems extends ExternalSystem.Any = never,
>(
domain: Model.ModelClass<Name, Provided, Policies>,
...[options = {}]: [Policies] extends [never]
? [options?: StoryOptions<Policies, LE, LR, Systems>]
: [options: StoryOptions<Policies, LE, LR, Systems> & { readonly layer: unknown }]
) =>
<const S extends ReadonlyArray<Step>>(
...steps: S & Checked<S>
): Effect.Effect<
void,
StoryFailure | LE,
Exclude<LR, Provided | ExternalSystem.Identifier<Systems> | WorkflowEngine.WorkflowEngine>
> =>
Effect.gen(function* () {
const clockState = { now: Date.parse("2026-01-01T00:00:00.000Z") };
const platform = InMemory.make({ manual: true, now: () => clockState.now });
const calls: Array<PendingCall> = [];
const observed: Array<ObservedCall> = [];
const stubbed = new Set((options.stub ?? []).map((system) => system.systemName));
const recorder: ExternalSystem.CallRecorder = {
record: (system, op, args, call) =>
Effect.gen(function* () {
const entry: ObservedCall = {
system,
op,
args,
exit: undefined,
done: yield* Deferred.make<void>(),
tag: undefined,
expected: false,
};
observed.push(entry);
return yield* call.pipe(
Effect.onExit((exit) =>
Effect.suspend(() => {
entry.exit = exit;
return Deferred.succeed(entry.done, undefined);
}),
),
);
}),
};
const systemLayers = (options.stub ?? []).map((system) =>
Layer.effect(
system as Context.Key<unknown, unknown>,
Effect.map(
ExternalSystem.compileChecks(system.systemName, system.ops),
(checks) =>
ExternalSystem.observeOps(
system.systemName,
// The story's answers are checked like an adapter's.
ExternalSystem.validateOps(
checks,
Object.fromEntries(
Object.keys(system.ops).map((op) => [
op,
(args: unknown) =>
platform.control.suspended(
Effect.gen(function* () {
const deferred = yield* Deferred.make<unknown, unknown>();
calls.push({
system: system.systemName,
op,
args,
deferred,
tag: undefined,
expected: false,
});
return yield* Deferred.await(deferred);
}),
),
]),
),
),
) as never,
),
),
);
const systems = Layer.mergeAll(Layer.empty, ...systemLayers);
const policies = (
options.layer ?? (Layer.empty as unknown as Layer.Layer<Policies, LE, LR>)
).pipe(Layer.provide(systems));
const hosted = domain
.layer(policies)
.pipe(Layer.provide(Layer.mergeAll(platform.layer, systems)));
// The aggregates the story touched, for the report's "events so far".
const touched = new Map<string, Aggregate.Ref>();
const run = Effect.gen(function* () {
const internals = yield* Model.Internals;
const cursors = new Map<string, number>();
// The step that committed each event, by `Aggregate/id#index`.
const committedAt = new Map<string, number>();
const attribute = (step: number) => {
for (const { aggregate, id, index } of platform.control.commits.slice(committedAt.size))
committedAt.set(`${aggregate}/${id}#${index}`, step);
};
let last:
| { readonly _tag: "Accepted"; readonly receipt: Aggregate.Receipt }
| { readonly _tag: "Rejected"; readonly rejection: { readonly _tag: string } }
| undefined;
let unassertedRejection:
| { readonly step: number; readonly rejection: { readonly _tag: string } }
| undefined;
let provided = Context.empty() as Context.Context<unknown>;
const assertedDeaths = new Set<string>();
const storeOf = (ref: Aggregate.Ref) => internals.aggregates.get(ref.aggregate)!;
const committed = (ref: Aggregate.Ref) =>
storeOf(ref).events?.(ref.id as string) ?? Effect.succeed([]);
const settle = (step: number) =>
Effect.gen(function* () {
for (let i = 0; i < 10_000; i++) {
// Real calls take real time: wait for them instead of spinning.
for (const call of observed) {
if (call.exit === undefined) yield* Deferred.await(call.done);
}
yield* platform.control.drain;
yield* Effect.yieldNow;
if (yield* platform.control.idle) {
yield* Effect.yieldNow;
yield* platform.control.drain;
if (yield* platform.control.idle) {
if (platform.control.failures.length > 0) {
return yield* new StepFailed({
step,
message: `a policy or projection failed: ${String(platform.control.failures[0])}`,
});
}
return;
}
}
}
return yield* new StepFailed({
step,
message: "the domain did not settle (a policy or projection is looping?)",
});
});
const rejectionNotAsserted = (rejected: NonNullable<typeof unassertedRejection>) =>
new StepFailed({
step: rejected.step,
message: `the command was rejected with ${rejected.rejection._tag}, which no step asserts`,
detail: `rejected ${summarize(rejected.rejection)}`,
});
for (const [index, s] of steps.entries()) {
const step = index + 1;
attribute(index);
const fail = (
message: string,
compared?: {
readonly expected: string;
readonly actual: string;
readonly label?: string;
},
) => new StepFailed({ step, message: `${s._tag}: ${message}`, ...compared });
if (unassertedRejection && s._tag !== "Rejected") {
return yield* rejectionNotAsserted(unassertedRejection);
}
if ("ref" in s) touched.set(refName(s.ref), s.ref);
switch (s._tag) {
case "Clock": {
const at = clockMillis(s.at);
if (Number.isNaN(at)) return yield* fail(`${String(s.at)} is not a time`);
// Once a step has run at the current time, the clock only moves forward.
const started = steps.slice(0, index).some((earlier) => earlier._tag !== "Provide");
if (started && at < clockState.now) {
const now = new Date(clockState.now).toISOString();
return yield* fail(
`the clock cannot move back, from ${now} to ${new Date(at).toISOString()}`,
{ expected: `${now} or later`, actual: new Date(at).toISOString() },
);
}
clockState.now = at;
// Scheduled commands that are now due fire, and their policies run.
yield* settle(step);
break;
}
case "Advance": {
const by = advanceDuration(s.by);
if (by === undefined)
return yield* fail(`${showDurationInput(s.by)} is not a duration`);
if (Duration.isNegative(by)) {
return yield* fail(`the clock only moves forward, not by ${Duration.format(by)}`);
}
clockState.now += Duration.toMillis(by);
yield* settle(step);
break;
}
case "Provide": {
provided = Context.add(provided, s.service, s.value);
break;
}
case "Given": {
const store = storeOf(s.ref);
if (!store.seed) return yield* fail("the platform cannot seed events");
yield* store.seed(
s.ref.id as string,
yield* Effect.forEach(s.events, internals.kernel.encodeEvent),
);
cursors.set(`${s.ref.aggregate}/${s.ref.id}`, (yield* committed(s.ref)).length);
yield* settle(step);
break;
}
case "When": {
const client = yield* Aggregate.refClass(s.ref) as unknown as Context.Key<
never,
Aggregate.ClientImpl
>;
const result = yield* client
.send(s.ref, s.command, { commandId: s.commandId ?? `story:${step}` })
.pipe(Effect.provide(provided), Effect.result);
if (result._tag === "Success") {
last = { _tag: "Accepted", receipt: result.success };
} else {
last = { _tag: "Rejected", rejection: result.failure as { readonly _tag: string } };
unassertedRejection = { step, rejection: last.rejection };
}
yield* settle(step);
break;
}
case "Then": {
const stream = `${s.ref.aggregate}/${s.ref.id}`;
const events = yield* committed(s.ref);
const from = cursors.get(stream) ?? 0;
const actual = events
.slice(from, from + Math.max(s.events.length, 1))
.map((e) => e.event);
const expected = s.events.map(encodeInstance);
// Decoded, so redacted fields stay redacted in the message.
const got = yield* Effect.forEach(events.slice(from), (e) =>
internals.kernel.decodeEvent(e.event),
);
const compared = {
label: stream,
expected: summarizeAll(s.events),
actual: summarizeAll(got),
};
if (s.events.length === 0) {
if (events.length > from) {
return yield* fail(
`expected no new events on ${stream}, got ${show(got)}`,
compared,
);
}
break;
}
if (!equal(actual.slice(0, expected.length), expected)) {
return yield* fail(
`on ${stream}\n expected ${show(s.events)}\n actual ${show(got)}`,
compared,
);
}
cursors.set(stream, from + expected.length);
break;
}
case "Rejected": {
if (last?._tag !== "Rejected")
return yield* fail(
`expected a rejection, the command was ${last ? "accepted" : "never sent"}`,
{
expected: summarize(s.rejection),
actual: last ? `accepted ${summarize(last.receipt.reply)}` : "never sent",
},
);
const expected = encodeInstance(s.rejection);
const actual = encodeInstance(last.rejection);
if (!equal(expected, actual))
return yield* fail(`expected ${show(s.rejection)}, got ${show(last.rejection)}`, {
expected: summarize(s.rejection),
actual: summarize(last.rejection),
});
unassertedRejection = undefined;
break;
}
case "Replied": {
if (last?._tag !== "Accepted")
return yield* fail("the last command was not accepted");
if (!equal(last.receipt.reply, s.reply)) {
return yield* fail(`expected ${show(s.reply)}, got ${show(last.receipt.reply)}`, {
expected: summarize(s.reply),
actual: summarize(last.receipt.reply),
});
}
break;
}
case "State": {
const client = yield* Aggregate.refClass(s.ref) as unknown as Context.Key<
never,
Aggregate.ClientImpl
>;
const current = yield* client.state(s.ref);
if (typeof s.expected === "function") {
const assert = s.expected as (state: unknown) => void;
yield* Effect.try({ try: () => assert(current), catch: (e) => fail(String(e)) });
} else if (!partial(s.expected, current)) {
const label = refName(s.ref);
return yield* fail(
`${label}\n expected ${show(s.expected)}\n actual ${show(current)}`,
{ label, expected: summarize(s.expected), actual: summarize(current) },
);
}
break;
}
case "View": {
const host = yield* s.view as unknown as Context.Key<
never,
View.Host<unknown, Key.Any, unknown>
>;
const current = yield* host.query(s.key).pipe(Effect.orDie);
if (s.expected === none) {
if (Option.isSome(current))
return yield* fail(
`expected ${s.view.viewName}(${Aggregate.targetId(s.key)}) to not exist, got ${show(current.value)}`,
{
label: `${s.view.viewName}(${Aggregate.targetId(s.key)})`,
expected: "none",
actual: summarize(current.value),
},
);
break;
}
const viewLabel = `${s.view.viewName}(${Aggregate.targetId(s.key)})`;
if (Option.isNone(current))
return yield* fail(`${viewLabel} does not exist`, {
label: viewLabel,
expected: typeof s.expected === "function" ? "a state" : summarize(s.expected),
actual: "none",
});
if (typeof s.expected === "function") {
const assert = s.expected as (state: unknown) => void;
yield* Effect.try({
try: () => assert(current.value),
catch: (e) => fail(String(e)),
});
} else if (!partial(s.expected, current.value)) {
return yield* fail(
`${viewLabel}\n expected ${show(s.expected)}\n actual ${show(current.value)}`,
{
label: viewLabel,
expected: summarize(s.expected),
actual: summarize(current.value),
},
);
}
break;
}
case "Emitted": {
const host = yield* s.view as unknown as Context.Key<
never,
View.Host<unknown, Key.Any, unknown>
>;
const { entries } = yield* host.list(s.key);
if (typeof s.expected === "function") {
const assert = s.expected as (entries: ReadonlyArray<unknown>) => void;
yield* Effect.try({ try: () => assert(entries), catch: (e) => fail(String(e)) });
} else {
const expected = s.expected as ReadonlyArray<unknown>;
const events = entries.map((entry) => entry.event);
const ok =
expected.length === events.length &&
expected.every((e, i) => partial(e, events[i]));
if (!ok)
return yield* fail(
`${s.view.viewName}(${Aggregate.targetId(s.key)})\n expected ${show(expected)}\n actual ${show(events)}`,
);
}
break;
}
case "Streamed": {
const store = internals.streams.get(s.stream.streamName)!;
const key = Aggregate.targetId(s.key);
const id = `${s.stream.streamName}/${key}`;
const entries = yield* store.list(key);
const from = cursors.get(id) ?? 0;
const actual = entries.slice(from).map((e) => e.event);
const expected = s.events.map(encodeInstance);
if (s.events.length === 0) {
if (actual.length > 0)
return yield* fail(`expected nothing new on ${id}, got ${show(actual)}`);
break;
}
if (!equal(actual.slice(0, expected.length), expected)) {
return yield* fail(
`on ${id}\n expected ${show(expected)}\n actual ${show(actual)}`,
);
}
cursors.set(id, from + expected.length);
break;
}
case "Call": {
const name = `${s.op.system}.${s.op.op}`;
if (s.tag !== undefined && observed.some((c) => c.tag === s.tag)) {
return yield* fail(`"${s.tag}" already names a call`);
}
if (!stubbed.has(s.op.system)) {
const made = observed.filter((c) => c.system === s.op.system && c.op === s.op.op);
// Each real call is matched once, in the order calls were made.
const match = made.find((c) => !c.expected && partial(s.args, c.args));
if (!match) {
return yield* fail(
`no unmatched call to ${name} matches ${show(s.args)}; made: ${show(made.map((c) => c.args))}`,
);
}
match.expected = true;
match.tag = s.tag;
break;
}
const pending = calls.filter((c) => c.system === s.op.system && c.op === s.op.op);
// Calls are kept in the order they were made: each is matched once, earliest first.
const match = pending.find((c) => !c.expected && partial(s.args, c.args));
if (!match) {
return yield* fail(
`no unmatched pending call to ${name} matches ${show(s.args)}; pending: ${show(pending.map((c) => c.args))}`,
);
}
if (s.tag !== undefined) {
if (calls.some((c) => c.tag === s.tag)) {
return yield* fail(`"${s.tag}" already names a pending call`);
}
match.tag = s.tag;
}
match.expected = true;
break;
}
case "Signal": {
const client = yield* s.saga as unknown as Context.Key<
never,
Saga.Client<unknown, unknown, unknown, unknown>
>;
yield* client.get(s.key).signal(s.deferred as never, s.value);
yield* settle(step);
break;
}
case "Saga": {
const client = yield* s.saga as unknown as Context.Key<
never,
Saga.Client<unknown, unknown, unknown, unknown>
>;
const run = client.get(s.key);
const actual = yield* run.status;
// `{ _tag: "Died" }` matches any defect.
const compared =
actual._tag === "Died" && !("defect" in s.expected)
? { _tag: "Died" as const }
: actual;
if (!equal(statusJson(compared), statusJson(s.expected))) {
return yield* fail(
`${s.saga.sagaName}\n expected ${show(statusJson(s.expected))}\n actual ${show(statusJson(actual))}`,
);
}
if (actual._tag === "Died")
// The engine names a model's sagas `<model>/<saga>`.
assertedDeaths.add(`${domain.modelName}/${s.saga.sagaName}/${run.executionId}`);
break;
}
case "Answer": {
const name = `${s.op.system}.${s.op.op}`;
if (!stubbed.has(s.op.system)) {
return yield* fail(
`${s.op.system} is not stubbed, so its calls run for real; assert how one ended with returned, failed or died`,
);
}
let call: PendingCall | undefined;
if (s.tag !== undefined) {
call = calls.find((c) => c.tag === s.tag);
if (!call) {
const tags = calls.flatMap((c) => (c.tag === undefined ? [] : [`"${c.tag}"`]));
return yield* fail(
`no pending call is named "${s.tag}"; named: ${tags.length > 0 ? tags.join(", ") : "none"}`,
);
}
if (call.system !== s.op.system || call.op !== s.op.op) {
return yield* fail(
`"${s.tag}" names a call to ${call.system}.${call.op}, not ${name}`,
);
}
} else {
const pending = calls.filter((c) => c.system === s.op.system && c.op === s.op.op);
if (pending.length === 0) return yield* fail(`no pending call to ${name}`);
if (pending.length > 1) {
return yield* fail(
`${pending.length} pending calls to ${name}; name each with call("<tag>", ...) and answer it by tag`,
);
}
call = pending[0];
}
if (!call!.expected) {
return yield* fail(
`${name}(${show(call!.args)}) is answered before a call step checks its arguments`,
);
}
calls.splice(calls.indexOf(call!), 1);
yield* Deferred.done(call!.deferred, s.exit);
yield* settle(step);
break;
}
case "Returned": {
const name = `${s.op.system}.${s.op.op}`;
if (stubbed.has(s.op.system)) {
return yield* fail(
`${s.op.system} is stubbed; answer its calls with succeed, fail or die`,
);
}
let call: ObservedCall | undefined;
if (s.tag !== undefined) {
call = observed.find((c) => c.tag === s.tag);
if (!call) return yield* fail(`no call is named "${s.tag}"`);
if (call.system !== s.op.system || call.op !== s.op.op) {
return yield* fail(
`"${s.tag}" names a call to ${call.system}.${call.op}, not ${name}`,
);
}
} else {
const made = observed.filter((c) => c.system === s.op.system && c.op === s.op.op);
if (made.length === 0) return yield* fail(`no unasserted call to ${name}`);
if (made.length > 1) {
return yield* fail(
`${made.length} unasserted calls to ${name}; name each with call("<tag>", ...) and assert it by tag`,
);
}
call = made[0]!;
}
if (!call.expected) {
return yield* fail(
`${name}(${show(call.args)}) is asserted before a call step checks its arguments`,
);
}
const actual = exitJson(call.exit!);
const expected =
s.expected._tag === "Success"
? { _tag: "Success", value: normalize(s.expected.value) }
: s.expected._tag === "Failure"
? { _tag: "Failure", error: errorJson(s.expected.error) }
: { _tag: "Died" };
const compared = actual._tag === "Died" ? { _tag: "Died" } : actual;
if (!equal(expected, compared)) {
return yield* fail(
`${name}(${show(call.args)})\n expected ${show(expected)}\n actual ${show(actual)}`,
);
}
observed.splice(observed.indexOf(call), 1);
break;
}
}
}
if (unassertedRejection) return yield* rejectionNotAsserted(unassertedRejection);
const death = platform.control.deaths.find(
({ saga, executionId }) => !assertedDeaths.has(`${saga}/${executionId}`),
);
if (death) {
return yield* new StepFailed({
step: steps.length,
atEnd: true,
message: `saga ${death.saga.slice(`${domain.modelName}/`.length)} run ${death.executionId} died with ${String(death.defect)}, which no step asserts`,
});
}
if (observed.length > 0) {
return yield* new StepFailed({
step: steps.length,
atEnd: true,
message: `real external system calls no step asserts (use returned, failed or died): ${show(observed.map((c) => `${c.system}.${c.op}(${show(c.args)})`))}`,
});
}
if (calls.length > 0) {
return yield* new StepFailed({
step: steps.length,
atEnd: true,
message: `unanswered external system calls at the end of the story: ${show(calls.map((c) => `${c.system}.${c.op}(${show(c.args)})`))}`,
});
}
attribute(steps.length);
// Every committed event past its stream's cursor is one no `then` asserts.
const unasserted: Array<string> = [];
const streams = new Map<string, Aggregate.Ref>();
for (const { aggregate, id } of platform.control.commits)
streams.set(`${aggregate}/${id}`, { aggregate, id } as Aggregate.Ref);
for (const [stream, ref] of streams) {
const events = yield* committed(ref);
const from = cursors.get(stream) ?? 0;
if (events.length <= from) continue;
touched.set(stream, ref);
// Decoded, so redacted fields stay redacted in the message.
const rest = yield* Effect.forEach(events.slice(from), (e) =>
internals.kernel.decodeEvent(e.event),
);
const first = committedAt.get(`${stream}#${from}`);
unasserted.push(
`${stream}: ${summarizeAll(rest)}${first === undefined ? "" : ` (from step ${first})`}`,
);
}
if (unasserted.length > 0) {
return yield* new StepFailed({
step: steps.length,
atEnd: true,
message: `committed events no step asserts (assert them with then): ${unasserted.join("; ")}`,
detail: unasserted.join("\n"),
});
}
});
// Turn a failed step into a failure that shows the whole story.
const report = (failure: StepFailed) =>
Effect.gen(function* () {
const internals = yield* Model.Internals;
const events: Record<string, ReadonlyArray<string>> = {};
for (const [name, ref] of touched) {
const committed =
internals.aggregates.get(ref.aggregate)!.events?.(ref.id as string) ??
Effect.succeed([]);
events[name] = (yield* committed).map(
(e) => (e.event as { readonly _tag: string })._tag,
);
}
const reports = steps.map((s, index): StepReport => ({
step: index + 1,
kind: s._tag,
status:
index + 1 < failure.step || (failure.atEnd && index + 1 === failure.step)
? "passed"
: index + 1 === failure.step
? "failed"
: "not-run",
summary: describeStep(s),
}));
return yield* new StoryFailure({
step: failure.step,
reason: failure.message,
message: `${failure.message}\n\n${renderReport(failure, reports, events)}`,
steps: reports,
events,
});
});
// `hosted` satisfies the Domain, the platform and the stubbed external systems; what
// remains is whatever the policy Layers need from outside (`LR`'s rest).
return yield* run.pipe(
Effect.catchTag("StepFailed", report),
Effect.provide(
Layer.mergeAll(hosted, Layer.succeed(ExternalSystem.CallRecorder, recorder)),
),
);
}) as Effect.Effect<
void,
StoryFailure | LE,
Exclude<LR, Provided | ExternalSystem.Identifier<Systems> | WorkflowEngine.WorkflowEngine>
>;
/**
* Given / when / then specifications of a domain model, run against the real
* model in memory: policies run for real, calls to stubbed external systems
* wait until you answer them, calls to the others run through their adapters
* while the story records them, and a clock you control stamps commands and
* fires scheduled ones. A story fails on any committed event, rejection,
* external system call or saga defect it doesn't account for.
*
* ### Writing a story
* **Example:** A withdrawal and an overdraft
* ```typescript
* import { it } from "@effect/vitest";
* import { Story } from "@alchemy.run/domain/Story";
* import { Account, InsufficientFunds, MoneyDeposited, MoneyWithdrawn, WithdrawMoney } from "../src/Account.ts";
* import { Bank, BankPolicies } from "../src/Bank.ts";
*
* const story = Story.make(Bank, { layer: BankPolicies });
* const account = Account.ref("a-1");
*
* it.effect("withdraws within the balance, and refuses beyond it", () =>
* story(
* Story.given(account, new MoneyDeposited({ amount: 100, balanceAfter: 100 })),
* Story.when(account, new WithdrawMoney({ amount: 30 })),
* Story.then(account, new MoneyWithdrawn({ amount: 30, balanceAfter: 70 })),
* Story.replied({ balance: 70 }),
* Story.when(account, new WithdrawMoney({ amount: 100 })),
* Story.rejected(new InsufficientFunds({ balance: 70, requested: 100 })),
* ),
* );
* ```
*
* ### External systems and the clock
* **Example:** Answer an external system call, then move the clock
* ```typescript
* Story.call(FraudCheck.score, { accountId: account.id, amount: 60_000 }),
* Story.succeed(FraudCheck.score, { risk: 0.95 }),
* Story.clock("2026-01-02T09:00:00Z"),
* Story.advance("1 day"),
* ```
*
* **Example:** Name calls when several are waiting
* ```typescript
* Story.call("a-1", FraudCheck.score, { accountId: a1.id }),
* Story.call("a-2", FraudCheck.score, { accountId: a2.id }),
* Story.succeed("a-2", FraudCheck.score, { risk: 0.1 }),
* Story.succeed("a-1", FraudCheck.score, { risk: 0.95 }),
* ```
*
* **Example:** Assert a real call to a system that is not stubbed
* ```typescript
* const story = Story.make(Bank, { layer: BankHandlers, stub: [FraudCheck] });
*
* story(
* Story.when(account, new RecordSettlement({ settlementId: "st_1", amount: 500 })),
* Story.call(Payments.refund, { settlementId: "st_1", amount: 500 }),
* Story.returned(Payments.refund, { refundId: "re_st_1" }),
* ).pipe(Effect.provide(StripePayments));
* ```
*
* **Example:** Fail a call with the operation's declared error, or a defect
* ```typescript
* Story.call(LockVendor.deleteCode, { codeId: "pc_1" }),
* Story.fail(LockVendor.deleteCode, new LockVendorRefused({ reason: "gateway-lost" })),
* Story.call(LockVendor.deleteCode, { codeId: "pc_2" }),
* Story.die(LockVendor.deleteCode, new Error("socket closed")),
* ```
*
* ### Sagas
* **Example:** Check where a saga run is, and send it a signal
* ```typescript
* Story.saga(ExecuteTransfer, transfer, { _tag: "Running" }),
* Story.signal(ExecuteTransfer, transfer, Decision, "approved"),
* ```
*
* @primitive
*/
// The steps live on this object rather than as module exports: a module that
// exports `then` is "thenable", and loaders that await module namespaces
// would hang on it.
export const Story = {
make,
given,
when,
// oxlint-disable-next-line unicorn/no-thenable -- `then` is the given/when/then vocabulary
then,
rejected,
replied,
state,
view,
emitted,
streamed,
call: callStep,
succeed,
fail,
die,
returned,
failed,
died,
clock,
advance,
provide,
signal,
saga,
/** Marker for "the view key does not exist". */
none,
} as const;