Documentation navigation

Published API · 0.1.0-rc.1

foldkit · story

Published foldkit API declarations for story.

./story

@wsagency/wseffect-foldkit · MIT · source · MIT license · WS-AGENCY-NOTICE · THIRD-PARTY-NOTICES

This entry point is published in @wsagency/wseffect-foldkit@0.1.0-rc.1. Import it from the package subpath shown below; the signatures and documentation are read from the installed package declarations.

import * as Wseffect from '@wsagency/wseffect-foldkit/story'

Exported declarations

AnyCommand

A Command in a test simulation. Carries `name` and optionally the `args` the runtime captured at construction. Instance matchers (Command values produced by calling a Definition) are matched against this shape; the `effect` field on a real Command is irrelevant for matching, so we only retain `name + args`. `messageMappers` is the Command's message-mapping chain (from `Command.mapMessage`/`mapMessages`). It rides along on pending Commands so `resolve` can apply the parent's wrapping to a substitute result Message without the test restating it. Absent on synthetic matchers built for formatting; treated as empty then. `key` is present on Commands built with an interruptible `Command.define`: such Commands may stay pending across Messages (they model long-running work). `interruptsKey` is present on Interrupt Commands: resolving one drops every pending Command holding that key, mirroring the runtime guarantee that an interrupted Command's result Message never dispatches.

export type AnyCommand = Readonly<{
    name: string;
    args?: Record<string, unknown>;
    key?: string;
    interruptsKey?: string;
    messageMappers?: ReadonlyArray<(message: unknown) => unknown>;
}>;

Command

Steps that operate on the pending Commands of a story simulation. Destructure as `const { Command } = Story` for concise call sites.

Command: {
    /** Resolves a specific pending Command with the given result Message. */
    readonly resolve: {
        <Name extends string, ResultMessage>(definition: ResolvableCommandDefinition<Name, ResultMessage>, resultMessage: ResultMessage): <Model, Message, OutMessage = undefined>(simulation: StorySimulation<Model, Message, OutMessage>) => StorySimulation<Model, Message, OutMessage>;
        <ResultMessage>(instance: AnyCommandInstance<ResultMessage>, resultMessage: ResultMessage): <Model, Message, OutMessage = undefined>(simulation: StorySimulation<Model, Message, OutMessage>) => StorySimulation<Model, Message, OutMessage>;
    };
    /** Resolves listed Commands with their result Messages, cascading through any
     *  Commands the result produces. Each entry resolves exactly one matching
     *  dispatch in declaration order; compose with `Array.makeBy` for N
     *  identical responses. Resolvers carry across calls; a new entry replaces
     *  any leftovers sharing its Definition or Instance shape (latest wins). */
    readonly resolveAll: typeof resolveAllCommands;
    /** Resolves listed Commands and throws unless every resolver matches one
     *  dispatch and no actual Commands remain unresolved. Entries apply only to
     *  this call and never carry forward. */
    readonly resolveAllExact: typeof resolveAllExactCommands;
    /** Asserts that every given Command is among the pending Commands. */
    readonly expectHas: typeof expectHasCommandsStep;
    /** Asserts that the pending Commands match the given definitions exactly (order-independent). */
    readonly expectExact: typeof expectExactCommandsStep;
    /** Asserts that there are no pending Commands. */
    readonly expectNone: typeof expectNoCommandsStep;
}

CommandMatcher

Pattern for matching a Command in test assertions. A Definition matches by name only ("a Command with this identity was dispatched"); an Instance matches by name AND structural-equal args ("a Command with this identity AND these args was dispatched"). Choose the form per assertion based on whether the test cares about the args value. Two modes only: name-only or name + full args. Partial-args matching is intentionally unsupported. If a subset of args carries the meaning the test is verifying, the right assertion is usually against the Model that the Command's result fed through update, not a partial Command shape.

export type CommandMatcher = CommandDefinition<string, unknown> | AnyCommand;

expectNoOutMessage

Asserts that update emitted no OutMessage.

expectNoOutMessage: () => <Model, Message, OutMessage>(simulation: StorySimulation<Model, Message, OutMessage>) => StorySimulation<Model, Message, OutMessage>

expectOutMessage

Asserts by structural equality that update emitted the expected OutMessage, so callers can pass a freshly constructed expected value.

expectOutMessage: <OutMessage>(expected: OutMessage) => OutMessageStep<OutMessage>

given

Sets the initial Model for a test story.

given: <Model>(model: Model) => GivenStep<Model>

GivenStep

A callable step that sets the initial Model. Carries phantom type for compile-time validation.

export type GivenStep<Model> = Readonly<{
    _phantomModel: Model;
}> & (<M, Message, OutMessage = undefined>(simulation: StorySimulation<M, Message, OutMessage>) => StorySimulation<M, Message, OutMessage>);

message

Sends a Message through update. Commands stay pending until resolve or resolveAll.

message: <Message>(message_: Message) => MessageStep<Message>

MessageStep

export type MessageStep<Message> = Readonly<{
    _tag: 'MessageStep';
    message: Message;
}>;

model

Runs an assertion function against the current Model.

model: <Model>(f: (model: Model) => void) => ModelStep<Model>

ModelStep

export type ModelStep<Model> = Readonly<{
    readonly _tag: 'ModelStep';
    readonly assert: (model: Model) => void;
}>;

OutMessageStep

export type OutMessageStep<OutMessage> = Readonly<{
    _tag: 'OutMessageStep';
    expected: OutMessage;
}>;

Resolver

A Command matcher (Definition or Instance) paired with the raw result Message to resolve a pending Command with. Definition matchers resolve by name; an Instance matcher resolves only the pending Command whose name AND args match. The matched Command's own message-mapping chain is applied to the result, so pass the child's raw result Message, not a parent-wrapped one. The result Message must belong to the matched Command.

export type Resolver<Matcher extends ResolvableCommandMatcher = ResolvableCommandMatcher> = readonly [Matcher, ResultMessageForMatcher<Matcher>];

steps

Groups Story steps so a reusable setup can remain type-safe without erasing its Message or OutMessage types through function composition.

steps: <Steps extends ReadonlyArray<StoryStep<any, any, any>>>(...storySteps: Steps) => StoryStepsStep<Steps[number] extends infer Step ? Step extends GivenStep<infer Model> ? Model : Step extends StoryStepsStep<infer Model, any, any, any> ? Model : never : never, Steps[number] extends infer Step ? Step extends ModelStep<infer Model> ? (model: Model) => void : Step extends StoryStepsStep<any, infer ModelAssertion, any, any> ? ModelAssertion : never : never, Steps[number] extends infer Step ? Step extends MessageStep<infer Message> ? Message : Step extends StoryStepsStep<any, any, infer Message, any> ? Message : never : never, Steps[number] extends infer Step ? Step extends OutMessageStep<infer OutMessage> ? OutMessage : Step extends StoryStepsStep<any, any, any, infer OutMessage> ? OutMessage : never : never>

story

Executes a test story. Throws if any Commands remain unresolved.

story: {
    <Model, Message, OutMessage = never>(updateFn: (model: Model, message: Message) => Readonly<{
        model: Model;
        commands?: ReadonlyArray<AnyCommand>;
        outMessage?: OutMessage;
    }>, ...steps: ReadonlyArray<StoryStep<NoInfer<Model>, NoInfer<Message>, NoInfer<OutMessage>>>): void;
    <Model, Message>(updateFn: (model: Model, message: Message) => Readonly<{
        model: Model;
        commands?: ReadonlyArray<AnyCommand>;
        outMessage?: never;
    }>, ...steps: ReadonlyArray<StoryStep<NoInfer<Model>, NoInfer<Message>, undefined>>): void;
}

StorySimulation

An immutable test simulation of a Foldkit program.

export type StorySimulation<Model, Message, OutMessage = undefined> = Readonly<{
    /** @internal Carries the Message type through the step chain. */
    _phantomMessage?: Message;
    model: Model;
    commands: ReadonlyArray<AnyCommand>;
    outMessage: OutMessage | undefined;
}>;

StoryStep

export type StoryStep<Model, Message = unknown, OutMessage = unknown> = GivenStep<NoInfer<Model>> | ModelStep<NoInfer<Model>> | MessageStep<NoInfer<Message>> | OutMessageStep<NoInfer<OutMessage>> | StoryStepsStep<NoInfer<Model>, (model: NoInfer<Model>) => void, NoInfer<Message>, NoInfer<OutMessage>> | ((simulation: StorySimulation<any, any, any>) => StorySimulation<any, any, any>);

StoryStepsStep

export type StoryStepsStep<GivenModel, ModelAssertion, Message, OutMessage> = Readonly<{
    _tag: 'StoryStepsStep';
    /** @internal Carries the produced Model type through a reusable step group. */
    _phantomGivenModel?: GivenModel;
    /** @internal Carries Model assertion types through a reusable step group. */
    _phantomModelAssertion?: ModelAssertion;
    /** @internal Carries the Message type through a reusable step group. */
    _phantomMessage?: Message;
    /** @internal Carries the OutMessage type through a reusable step group. */
    _phantomOutMessage?: OutMessage;
    steps: ReadonlyArray<StoryStep<any, any, any>>;
}>;