Documentation navigation

Published API · 0.1.0-rc.1

foldkit · command

Published foldkit API declarations for command.

./command

@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/command'

Exported declarations

Command

A named Effect that produces a message, optionally carrying the args used to construct it. `key` is present on Commands built by `define` with `interrupt`: it addresses the invocation in the runtime's interrupt registry so a later Interrupt Command can stop it.

export type Command<T, E = never, R = never> = [T] extends [Schema.Top] ? Readonly<{
    name: string;
    args?: Record<string, unknown>;
    key?: string;
    effect: Effect.Effect<Schema.Schema.Type<T>, E, R>;
}> : Readonly<{
    name: string;
    args?: Record<string, unknown>;
    key?: string;
    effect: Effect.Effect<T, E, R>;
}>;

CommandDefinition

A Command definition created with `Command.define`. Union over the no-args and with-args shapes; consumers that only need name/identity can accept this.

export type CommandDefinition<Name extends string = string, ResultMessage = any> = CommandDefinitionNoArgs<Name, Effect.Effect<ResultMessage, any, any>> | CommandDefinitionWithArgs<Name, any, Effect.Effect<ResultMessage, any, any>>;

CommandDefinitionNoArgs

A Command definition for a Command with no declared args. Call as `Definition()` to produce a Command instance.

export interface CommandDefinitionNoArgs<Name extends string, Eff extends Effect.Effect<any, any, any>> {
    readonly [CommandDefinitionTypeId]: CommandDefinitionTypeId;
    readonly name: Name;
    (): Readonly<{
        name: Name;
        effect: Eff;
    }>;
}

CommandDefinitionTypeId

Type-level brand for CommandDefinition values.

CommandDefinitionTypeId: unique symbol

CommandDefinitionTypeId

Type-level brand for CommandDefinition values.

export type CommandDefinitionTypeId = typeof CommandDefinitionTypeId;

CommandDefinitionWithArgs

A Command definition for a Command with declared args. Call as `Definition(args)` to produce a Command instance.

export interface CommandDefinitionWithArgs<Name extends string, Fields extends Schema.Struct.Fields, Eff extends Effect.Effect<any, any, any>> {
    readonly [CommandDefinitionTypeId]: CommandDefinitionTypeId;
    readonly name: Name;
    (args: Schema.Schema.Type<Schema.Struct<Fields>>): Readonly<{
        name: Name;
        args: Schema.Schema.Type<Schema.Struct<Fields>>;
        effect: Eff;
    }>;
}

define

export declare function define<const Name extends string, const Messages extends ReadonlyArray<Schema.Top>, Eff extends Effect.Effect<Schema.Schema.Type<Messages[number]>, any, any>>(name: Name, config: Readonly<{
    messages: Messages;
    interrupt: true;
    execute: Eff;
}>): Interruptible.DefinitionNoArgs<Name, Eff>;

define

export declare function define<const Name extends string, const Messages extends ReadonlyArray<Schema.Top>, Eff extends Effect.Effect<Schema.Schema.Type<Messages[number]>, any, any>>(name: Name, config: Readonly<{
    messages: Messages;
    interrupt?: never;
    execute: Eff;
}>): CommandDefinitionNoArgs<Name, Eff>;

define

export declare function define<const Name extends string, Fields extends Schema.Struct.Fields, const Messages extends ReadonlyArray<Schema.Top>, const KeyField extends keyof Schema.Schema.Type<Schema.Struct<Fields>> & string, Eff extends Effect.Effect<Schema.Schema.Type<Messages[number]>, any, any>>(name: Name, config: Readonly<{
    args: Fields;
    messages: Messages;
    interrupt: Readonly<{
        keyFields: Array.NonEmptyReadonlyArray<KeyField>;
        toKey: (keyArgs: Pick<Schema.Schema.Type<Schema.Struct<Fields>>, KeyField>) => string;
    }>;
    execute: (args: Schema.Schema.Type<Schema.Struct<Fields>>) => Eff;
}>): Interruptible.DefinitionWithArgs<Name, Fields, Pick<Schema.Schema.Type<Schema.Struct<Fields>>, KeyField>, Eff>;

define

export declare function define<const Name extends string, Fields extends Schema.Struct.Fields, const Messages extends ReadonlyArray<Schema.Top>, Eff extends Effect.Effect<Schema.Schema.Type<Messages[number]>, any, any>>(name: Name, config: Readonly<{
    args: Fields;
    messages: Messages;
    interrupt: true;
    execute: (args: Schema.Schema.Type<Schema.Struct<Fields>>) => Eff;
}>): Interruptible.DefinitionWithArgsNameKeyed<Name, Fields, Eff>;

define

export declare function define<const Name extends string, Fields extends Schema.Struct.Fields, const Messages extends ReadonlyArray<Schema.Top>, Eff extends Effect.Effect<Schema.Schema.Type<Messages[number]>, any, any>>(name: Name, config: Readonly<{
    args: Fields;
    messages: Messages;
    interrupt?: never;
    execute: (args: Schema.Schema.Type<Schema.Struct<Fields>>) => Eff;
}>): CommandDefinitionWithArgs<Name, Fields, Eff>;

Interruptible

export type { DefinitionNoArgs, DefinitionWithArgs, DefinitionWithArgsNameKeyed, InterruptDefinitionNoArgs, InterruptDefinitionWithArgs, } from './index.js';
export { Outcome } from './index.js';

InterruptOption

Makes a Command interruptible. `true` keys every invocation by the Command name, which is what you want when at most one invocation is meaningfully in flight. `{ keyFields, toKey }` derives the key part from declared args, so invocations that run concurrently can be interrupted independently. `keyFields` declares the exact args the Interrupt constructor requires. Derive the key part from the Model identity that owns the in-flight work (a list item id, an entity id), never from a generated value: update is pure, and any invocation you can meaningfully target is already distinguished by data in the Model.

export type InterruptOption<Args, KeyField extends keyof Args & string = keyof Args & string> = true | Readonly<{
    keyFields: Array.NonEmptyReadonlyArray<KeyField>;
    toKey: (keyArgs: Pick<Args, KeyField>) => string;
}>;

mapEffect

mapEffect: {
    <A, E1, R1, E2, R2>(f: (effect: Effect.Effect<A, E1, R1>) => Effect.Effect<NoInfer<A>, E2, R2>): (command: Command<A, E1, R1>) => Command<A, E2, R2>;
    <A, E1, R1, E2, R2>(command: Command<A, E1, R1>, f: (effect: Effect.Effect<A, E1, R1>) => Effect.Effect<NoInfer<A>, E2, R2>): Command<A, E2, R2>;
}

mapMessage

mapMessage: {
    <FromMessage, ToMessage, E = never, R = never>(command: Command<FromMessage, E, R>, f: (message: FromMessage) => ToMessage): Command<ToMessage, E, R>;
    <FromMessage, ToMessage>(f: (message: FromMessage) => ToMessage): <E = never, R = never>(command: Command<FromMessage, E, R>) => Command<ToMessage, E, R>;
}

mapMessages

mapMessages: {
    <FromMessage, ToMessage, E = never, R = never>(commands: ReadonlyArray<Command<FromMessage, E, R>> | undefined, f: (message: FromMessage) => ToMessage): ReadonlyArray<Command<ToMessage, E, R>>;
    <FromMessage, ToMessage>(f: (message: FromMessage) => ToMessage): <E = never, R = never>(commands: ReadonlyArray<Command<FromMessage, E, R>> | undefined) => ReadonlyArray<Command<ToMessage, E, R>>;
}