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>>;
}>;