ankka 0.6.0

package/dist/context.d.ts

@@ -0,0 +1,61 @@
+import { Instant } from "./time.ts";
+import type { Metadata } from "./effects/common.ts";
+import type { Metadata as ProtoMetadata } from "./_proto/ankka/protocol/v1/payload_pb.ts";
+/** The context of one command on a stateful component. */
+export interface CommandContext {
+    readonly componentId: string;
+    readonly entityId: string;
+    /** The sequence number of the last event applied before this command; `0n` for a fresh entity. */
+    readonly sequenceNumber: bigint;
+    readonly metadata: Metadata;
+    /** The current instant; a seam a test can replace. */
+    now(): Instant;
+}
+export declare function commandContext(componentId: string, entityId: string, sequenceNumber: bigint, metadata: Metadata, now?: () => Instant): CommandContext;
+export declare function metadataFromProto(proto: ProtoMetadata | undefined): Metadata;
+export declare function metadataToProto(metadata: Metadata | undefined): {
+    entries: {
+        key: string;
+        value: string;
+    }[];
+};
+/** The caller an authenticated route was invoked by. */
+export interface Principal {
+    readonly subject: string;
+    readonly name: string | null;
+    readonly email: string | null;
+    readonly emailVerified: boolean;
+    readonly roles: readonly string[];
+}
+/** Query parameters in request order; a name may repeat. */
+export declare class Query {
+    private readonly pairs;
+    constructor(pairs: readonly (readonly [string, string])[]);
+    get(name: string): string | null;
+    getAll(name: string): string[];
+    has(name: string): boolean;
+    entries(): readonly (readonly [string, string])[];
+}
+/** Request headers; names are matched case-insensitively. */
+export declare class Headers {
+    private readonly pairs;
+    constructor(pairs: readonly (readonly [string, string])[]);
+    get(name: string): string | null;
+    getAll(name: string): string[];
+    entries(): readonly (readonly [string, string])[];
+}
+/** What an endpoint handler sees of its request: `this.request` on the endpoint. `P` is the typed path parameters. */
+export interface RequestContext<P = Readonly<Record<string, unknown>>> {
+    readonly params: P;
+    readonly query: Query;
+    readonly headers: Headers;
+    /** The caller, when the route's access rule is `authenticated`; `null` otherwise. */
+    readonly principal: Principal | null;
+    readonly metadata: Metadata;
+}
+/** Runs `fn` with `request` as the current request, for the asynchronous work it starts. */
+export declare function withRequest<T>(request: RequestContext, fn: () => T): T;
+/** The current request, or `undefined` outside one. */
+export declare function requestIfAny(): RequestContext | undefined;
+/** The current request, or a clear error when called outside one. */
+export declare function currentRequest(): RequestContext;

package/dist/context.js

@@ -0,0 +1,75 @@
+// What a handler can see about the request it is running for. A `CommandContext` is bound on the
+// component instance for one call; an HTTP `RequestContext` lives in an `AsyncLocalStorage`, the Node
+// equivalent of the thread-local the Scala SDK uses and the `ContextVar` the Python SDK uses: one
+// request per asynchronous context, and work handed to another context cannot see it.
+import { AsyncLocalStorage } from "node:async_hooks";
+import { Instant } from "./time.js";
+export function commandContext(componentId, entityId, sequenceNumber, metadata, now = Instant.now) {
+    return Object.freeze({ componentId, entityId, sequenceNumber, metadata, now });
+}
+export function metadataFromProto(proto) {
+    const out = {};
+    for (const e of proto?.entries ?? [])
+        out[e.key] = e.value;
+    return Object.freeze(out);
+}
+export function metadataToProto(metadata) {
+    return { entries: Object.entries(metadata ?? {}).map(([key, value]) => ({ key, value })) };
+}
+/** Query parameters in request order; a name may repeat. */
+export class Query {
+    pairs;
+    constructor(pairs) {
+        this.pairs = pairs;
+        Object.freeze(this);
+    }
+    get(name) {
+        const hit = this.pairs.find(([n]) => n === name);
+        return hit ? hit[1] : null;
+    }
+    getAll(name) {
+        return this.pairs.filter(([n]) => n === name).map(([, v]) => v);
+    }
+    has(name) {
+        return this.pairs.some(([n]) => n === name);
+    }
+    entries() {
+        return this.pairs;
+    }
+}
+/** Request headers; names are matched case-insensitively. */
+export class Headers {
+    pairs;
+    constructor(pairs) {
+        this.pairs = pairs;
+        Object.freeze(this);
+    }
+    get(name) {
+        const lower = name.toLowerCase();
+        const hit = this.pairs.find(([n]) => n.toLowerCase() === lower);
+        return hit ? hit[1] : null;
+    }
+    getAll(name) {
+        const lower = name.toLowerCase();
+        return this.pairs.filter(([n]) => n.toLowerCase() === lower).map(([, v]) => v);
+    }
+    entries() {
+        return this.pairs;
+    }
+}
+const requestStorage = new AsyncLocalStorage();
+/** Runs `fn` with `request` as the current request, for the asynchronous work it starts. */
+export function withRequest(request, fn) {
+    return requestStorage.run(request, fn);
+}
+/** The current request, or `undefined` outside one. */
+export function requestIfAny() {
+    return requestStorage.getStore();
+}
+/** The current request, or a clear error when called outside one. */
+export function currentRequest() {
+    const r = requestStorage.getStore();
+    if (!r)
+        throw new Error("request is only available inside an endpoint handler");
+    return r;
+}

package/dist/effects/agent.d.ts

@@ -0,0 +1,37 @@
+import { ErrorCode, type EffectLike, type ErrorDetail } from "./common.ts";
+export interface AgentEffect<R = string> extends EffectLike<R> {
+    readonly kind: "agent";
+    /** A model by the name the sidecar configured; absent, the sidecar's default. */
+    readonly model: string | null;
+    readonly system: string | null;
+    readonly user: string | null;
+    readonly context: readonly string[];
+    readonly sessionMemory: boolean;
+    readonly toolNames: readonly string[];
+    readonly guardrailNames: readonly string[];
+    readonly jsonReply: boolean;
+    readonly schemaHint: string;
+    /** `effects.error(...)`: a refusal before any model call. */
+    readonly failure: ErrorDetail | null;
+    withModel(name: string): AgentEffect<R>;
+    systemMessage(text: string): AgentEffect<R>;
+    userMessage(text: string): AgentEffect<R>;
+    /** Context the user did not type — retrieved documents, an entity's state — kept apart from the user message so memory records what the user said. */
+    withContext(text: string): AgentEffect<R>;
+    /** `false`: no memory at all, for a one-shot classification. */
+    memory(session: boolean): AgentEffect<R>;
+    tools(...names: string[]): AgentEffect<R>;
+    guardrails(...names: string[]): AgentEffect<R>;
+    /** Reply with the model's text. */
+    thenReply(): AgentEffect<string>;
+    /** Reply with the model's JSON, decoded by the caller's reply shape `R`. The schema is not sent to the model — say what you want in the system message. */
+    thenReplyJson<J = unknown>(schemaHint?: string): AgentEffect<J>;
+}
+/** Inside an agent's handler: `this.effects`. */
+export declare class AgentEffects {
+    model(name: string): AgentEffect<string>;
+    systemMessage(text: string): AgentEffect<string>;
+    userMessage(text: string): AgentEffect<string>;
+    /** Reject the request without calling a model. */
+    error(message: string, code?: ErrorCode): AgentEffect<never>;
+}

package/dist/effects/agent.js

@@ -0,0 +1,48 @@
+// Effects for agents: a description of one interaction with a model — which model, what instructions,
+// which tools and guardrails, what memory — as data. Building one calls no model; the sidecar's loop
+// interprets it, calling back for tools and guardrails. The model's key never lives in this process.
+import { ErrorCode } from "./common.js";
+const EMPTY = {
+    model: null,
+    system: null,
+    user: null,
+    context: [],
+    sessionMemory: true,
+    toolNames: [],
+    guardrailNames: [],
+    jsonReply: false,
+    schemaHint: "",
+    failure: null,
+};
+function make(fields) {
+    const f = { ...fields, context: Object.freeze([...fields.context]), toolNames: Object.freeze([...fields.toolNames]), guardrailNames: Object.freeze([...fields.guardrailNames]) };
+    return Object.freeze({
+        kind: "agent",
+        ...f,
+        withModel: (name) => make({ ...f, model: name }),
+        systemMessage: (text) => make({ ...f, system: text }),
+        userMessage: (text) => make({ ...f, user: text }),
+        withContext: (text) => make({ ...f, context: [...f.context, text] }),
+        memory: (session) => make({ ...f, sessionMemory: session }),
+        tools: (...names) => make({ ...f, toolNames: [...f.toolNames, ...names] }),
+        guardrails: (...names) => make({ ...f, guardrailNames: [...f.guardrailNames, ...names] }),
+        thenReply: () => make({ ...f, jsonReply: false }),
+        thenReplyJson: (schemaHint = "JSON") => make({ ...f, jsonReply: true, schemaHint }),
+    });
+}
+/** Inside an agent's handler: `this.effects`. */
+export class AgentEffects {
+    model(name) {
+        return make({ ...EMPTY, model: name });
+    }
+    systemMessage(text) {
+        return make({ ...EMPTY, system: text });
+    }
+    userMessage(text) {
+        return make({ ...EMPTY, user: text });
+    }
+    /** Reject the request without calling a model. */
+    error(message, code = ErrorCode.BadRequest) {
+        return make({ ...EMPTY, failure: { message, code } });
+    }
+}

package/dist/effects/common.d.ts

@@ -0,0 +1,68 @@
+import type { Duration } from "../time.ts";
+/** The refusal codes a handler may answer with, and the HTTP status each becomes at an endpoint. */
+export declare const ErrorCode: Readonly<{
+    readonly Internal: "INTERNAL";
+    readonly BadRequest: "BAD_REQUEST";
+    readonly Unauthorized: "UNAUTHORIZED";
+    readonly Forbidden: "FORBIDDEN";
+    readonly NotFound: "NOT_FOUND";
+    readonly Conflict: "CONFLICT";
+    readonly Timeout: "TIMEOUT";
+    readonly Unavailable: "UNAVAILABLE";
+}>;
+export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
+export declare function httpStatusOf(code: ErrorCode): number;
+/** A refusal, as a value: what `effects.error(message, code)` carries and what a caller's `CommandError` holds. */
+export interface ErrorDetail {
+    readonly message: string;
+    readonly code: ErrorCode;
+}
+/** Thrown by the component client when the callee refused. */
+export declare class CommandError extends Error {
+    readonly code: ErrorCode;
+    constructor(detail: ErrorDetail);
+    get detail(): ErrorDetail;
+}
+/** Metadata on a request or a reply: trace and span ids, the source's id, a timer's name. */
+export type Metadata = Readonly<Record<string, string>>;
+/**
+ * The three cases of an effect's outcome. A `Reply` computes its value from the state *after* the
+ * effect's events, which is why it is a function and not a value.
+ */
+export type Outcome<S, R> = {
+    readonly kind: "reply";
+    readonly compute: (state: S) => R;
+    readonly metadata?: Metadata;
+} | {
+    readonly kind: "no-reply";
+} | {
+    readonly kind: "fail";
+    readonly error: ErrorDetail;
+};
+export declare const Outcome: Readonly<{
+    reply<S, R>(compute: (state: S) => R, metadata?: Metadata): Outcome<S, R>;
+    noReply<S>(): Outcome<S, never>;
+    fail<S>(message: string, code?: ErrorCode): Outcome<S, never>;
+}>;
+/** What an entity asks the runtime to do with it after this effect: delete now, or expire after a while. */
+export type Retention = {
+    readonly kind: "delete-now";
+} | {
+    readonly kind: "expire-after";
+    readonly after: Duration;
+};
+export declare const Retention: Readonly<{
+    deleteNow: Retention;
+    expireAfter(after: Duration): Retention;
+}>;
+/**
+ * Every effect has a `kind`; read-only effects have `kind: "read-only"`, which is what lets `query`
+ * refuse a persisting handler at compile time. `_reply` is a phantom carrying the reply type.
+ */
+export interface EffectLike<R = unknown> {
+    readonly kind: string;
+    readonly _reply?: R;
+}
+export interface ReadOnlyLike<R = unknown> extends EffectLike<R> {
+    readonly kind: "read-only";
+}

package/dist/effects/common.js

@@ -0,0 +1,55 @@
+// What every kind's effects share: the outcome of a request (a reply, no reply, or a refusal), the
+// retention a handler may ask for, and the error codes. Inert values; nothing here performs I/O.
+/** The refusal codes a handler may answer with, and the HTTP status each becomes at an endpoint. */
+export const ErrorCode = Object.freeze({
+    Internal: "INTERNAL",
+    BadRequest: "BAD_REQUEST",
+    Unauthorized: "UNAUTHORIZED",
+    Forbidden: "FORBIDDEN",
+    NotFound: "NOT_FOUND",
+    Conflict: "CONFLICT",
+    Timeout: "TIMEOUT",
+    Unavailable: "UNAVAILABLE",
+});
+const HTTP_STATUS = Object.freeze({
+    INTERNAL: 500,
+    BAD_REQUEST: 400,
+    UNAUTHORIZED: 401,
+    FORBIDDEN: 403,
+    NOT_FOUND: 404,
+    CONFLICT: 409,
+    TIMEOUT: 504,
+    UNAVAILABLE: 503,
+});
+export function httpStatusOf(code) {
+    return HTTP_STATUS[code];
+}
+/** Thrown by the component client when the callee refused. */
+export class CommandError extends Error {
+    code;
+    constructor(detail) {
+        super(detail.message);
+        this.name = "CommandError";
+        this.code = detail.code;
+    }
+    get detail() {
+        return { message: this.message, code: this.code };
+    }
+}
+export const Outcome = Object.freeze({
+    reply(compute, metadata) {
+        return Object.freeze({ kind: "reply", compute, ...(metadata ? { metadata } : {}) });
+    },
+    noReply() {
+        return Object.freeze({ kind: "no-reply" });
+    },
+    fail(message, code = ErrorCode.Internal) {
+        return Object.freeze({ kind: "fail", error: Object.freeze({ message, code }) });
+    },
+});
+export const Retention = Object.freeze({
+    deleteNow: Object.freeze({ kind: "delete-now" }),
+    expireAfter(after) {
+        return Object.freeze({ kind: "expire-after", after });
+    },
+});

package/dist/effects/eventSourced.d.ts

@@ -0,0 +1,50 @@
+import type { Duration } from "../time.ts";
+import { done, type Done } from "../schema.ts";
+import { ErrorCode, Outcome, Retention, type EffectLike, type Metadata, type ReadOnlyLike } from "./common.ts";
+export interface PersistEffect<S, E, R> extends EffectLike<R> {
+    readonly kind: "persist";
+    readonly events: readonly E[];
+    readonly retention: Retention | null;
+    readonly outcome: Outcome<S, R>;
+}
+export interface ReadOnlyEffect<S, E, R> extends ReadOnlyLike<R> {
+    readonly kind: "read-only";
+    readonly retention: Retention | null;
+    readonly outcome: Outcome<S, R>;
+    /** Phantom: the entity's event type, so a read-only effect is tied to its entity. */
+    readonly _events?: E;
+}
+export type EventSourcedEffect<S, E, R> = PersistEffect<S, E, R> | ReadOnlyEffect<S, E, R>;
+/** `effects.persist(e)` returns one of these; finish it with `thenReply`, `thenReplyState` or `thenNoReply`. */
+export declare class PersistBuilder<S, E> {
+    #private;
+    constructor(events: readonly E[], retention?: Retention | null);
+    /** Delete the entity once these events are persisted. */
+    deleteEntity(): PersistBuilder<S, E>;
+    /** Expire the entity a while after these events are persisted. */
+    expireAfter(after: Duration): PersistBuilder<S, E>;
+    /** Reply with a value computed from the state *after* the events. */
+    thenReply<R>(compute: (state: S) => R, metadata?: Metadata): PersistEffect<S, E, R>;
+    /** Reply with the state after the events. */
+    thenReplyState(): PersistEffect<S, E, S>;
+    /** Persist and answer nothing. */
+    thenNoReply(): PersistEffect<S, E, never>;
+}
+/** The factory a handler reaches as `this.effects`. */
+export declare class EventSourcedEffects<S, E> {
+    /** Persist one or more events. */
+    persist(event: E, ...more: E[]): PersistBuilder<S, E>;
+    /** Persist a list of events; an empty list is allowed and persists nothing. */
+    persistAll(events: readonly E[]): PersistBuilder<S, E>;
+    /** Answer without persisting. */
+    reply<R>(value: R, metadata?: Metadata): ReadOnlyEffect<S, E, R>;
+    /** Refuse the command: nothing is persisted and the caller sees the code. */
+    error(message: string, code?: ErrorCode): ReadOnlyEffect<S, E, never>;
+    /** Answer nothing and persist nothing. */
+    noReply(): ReadOnlyEffect<S, E, never>;
+    /** Delete the entity, persisting nothing more; finish with `thenReply(() => done)` or `thenNoReply()`. */
+    deleteEntity(): PersistBuilder<S, E>;
+    /** Expire the entity after a while, persisting nothing more. */
+    expireAfter(after: Duration): PersistBuilder<S, E>;
+}
+export { done, type Done };

package/dist/effects/eventSourced.js

@@ -0,0 +1,66 @@
+// The effects an event sourced entity's handlers return: persist these events and then reply from the
+// state after them, or answer without persisting. Inert values. `ReadOnlyEffect` is a distinct type
+// with `kind: "read-only"`, which is what lets `query` refuse a persisting handler at compile time.
+import { done } from "../schema.js";
+import { ErrorCode, Outcome, Retention } from "./common.js";
+/** `effects.persist(e)` returns one of these; finish it with `thenReply`, `thenReplyState` or `thenNoReply`. */
+export class PersistBuilder {
+    #events;
+    #retention;
+    constructor(events, retention = null) {
+        this.#events = events;
+        this.#retention = retention;
+    }
+    /** Delete the entity once these events are persisted. */
+    deleteEntity() {
+        return new PersistBuilder(this.#events, Retention.deleteNow);
+    }
+    /** Expire the entity a while after these events are persisted. */
+    expireAfter(after) {
+        return new PersistBuilder(this.#events, Retention.expireAfter(after));
+    }
+    /** Reply with a value computed from the state *after* the events. */
+    thenReply(compute, metadata) {
+        return Object.freeze({ kind: "persist", events: this.#events, retention: this.#retention, outcome: Outcome.reply(compute, metadata) });
+    }
+    /** Reply with the state after the events. */
+    thenReplyState() {
+        return this.thenReply((state) => state);
+    }
+    /** Persist and answer nothing. */
+    thenNoReply() {
+        return Object.freeze({ kind: "persist", events: this.#events, retention: this.#retention, outcome: Outcome.noReply() });
+    }
+}
+/** The factory a handler reaches as `this.effects`. */
+export class EventSourcedEffects {
+    /** Persist one or more events. */
+    persist(event, ...more) {
+        return new PersistBuilder(Object.freeze([event, ...more]));
+    }
+    /** Persist a list of events; an empty list is allowed and persists nothing. */
+    persistAll(events) {
+        return new PersistBuilder(Object.freeze([...events]));
+    }
+    /** Answer without persisting. */
+    reply(value, metadata) {
+        return Object.freeze({ kind: "read-only", retention: null, outcome: Outcome.reply(() => value, metadata) });
+    }
+    /** Refuse the command: nothing is persisted and the caller sees the code. */
+    error(message, code = ErrorCode.BadRequest) {
+        return Object.freeze({ kind: "read-only", retention: null, outcome: Outcome.fail(message, code) });
+    }
+    /** Answer nothing and persist nothing. */
+    noReply() {
+        return Object.freeze({ kind: "read-only", retention: null, outcome: Outcome.noReply() });
+    }
+    /** Delete the entity, persisting nothing more; finish with `thenReply(() => done)` or `thenNoReply()`. */
+    deleteEntity() {
+        return new PersistBuilder(Object.freeze([]), Retention.deleteNow);
+    }
+    /** Expire the entity after a while, persisting nothing more. */
+    expireAfter(after) {
+        return new PersistBuilder(Object.freeze([]), Retention.expireAfter(after));
+    }
+}
+export { done };

package/dist/effects/keyValue.d.ts

@@ -0,0 +1,36 @@
+import type { Duration } from "../time.ts";
+import { done, type Done } from "../schema.ts";
+import { ErrorCode, Outcome, Retention, type EffectLike, type Metadata, type ReadOnlyLike } from "./common.ts";
+export interface UpdateEffect<S, R> extends EffectLike<R> {
+    readonly kind: "update";
+    /** The state to store; `null` when the effect only deletes. */
+    readonly newState: S | null;
+    readonly retention: Retention | null;
+    readonly outcome: Outcome<S, R>;
+}
+export interface KeyValueReadOnlyEffect<S, R> extends ReadOnlyLike<R> {
+    readonly kind: "read-only";
+    readonly retention: null;
+    readonly outcome: Outcome<S, R>;
+}
+export type KeyValueEffect<S, R> = UpdateEffect<S, R> | KeyValueReadOnlyEffect<S, R>;
+export declare class UpdateBuilder<S> {
+    #private;
+    constructor(newState: S | null, retention?: Retention | null);
+    deleteEntity(): UpdateBuilder<S>;
+    expireAfter(after: Duration): UpdateBuilder<S>;
+    /** Reply with a value computed from the new state. */
+    thenReply<R>(compute: (state: S) => R, metadata?: Metadata): UpdateEffect<S, R>;
+    thenReplyState(): UpdateEffect<S, S>;
+    thenNoReply(): UpdateEffect<S, never>;
+}
+/** The factory a key value entity's handler reaches as `this.effects`. */
+export declare class KeyValueEffects<S> {
+    updateState(state: S): UpdateBuilder<S>;
+    /** Delete the entity, keeping the state as it is until then. */
+    deleteEntity(): UpdateBuilder<S>;
+    reply<R>(value: R, metadata?: Metadata): KeyValueReadOnlyEffect<S, R>;
+    error(message: string, code?: ErrorCode): KeyValueReadOnlyEffect<S, never>;
+    noReply(): KeyValueReadOnlyEffect<S, never>;
+}
+export { done, type Done };

package/dist/effects/keyValue.js

@@ -0,0 +1,47 @@
+// Effects for key value entities: replace the state, then decide what to reply.
+import { done } from "../schema.js";
+import { ErrorCode, Outcome, Retention } from "./common.js";
+export class UpdateBuilder {
+    #newState;
+    #retention;
+    constructor(newState, retention = null) {
+        this.#newState = newState;
+        this.#retention = retention;
+    }
+    deleteEntity() {
+        return new UpdateBuilder(this.#newState, Retention.deleteNow);
+    }
+    expireAfter(after) {
+        return new UpdateBuilder(this.#newState, Retention.expireAfter(after));
+    }
+    /** Reply with a value computed from the new state. */
+    thenReply(compute, metadata) {
+        return Object.freeze({ kind: "update", newState: this.#newState, retention: this.#retention, outcome: Outcome.reply(compute, metadata) });
+    }
+    thenReplyState() {
+        return this.thenReply((state) => state);
+    }
+    thenNoReply() {
+        return Object.freeze({ kind: "update", newState: this.#newState, retention: this.#retention, outcome: Outcome.noReply() });
+    }
+}
+/** The factory a key value entity's handler reaches as `this.effects`. */
+export class KeyValueEffects {
+    updateState(state) {
+        return new UpdateBuilder(state);
+    }
+    /** Delete the entity, keeping the state as it is until then. */
+    deleteEntity() {
+        return new UpdateBuilder(null, Retention.deleteNow);
+    }
+    reply(value, metadata) {
+        return Object.freeze({ kind: "read-only", retention: null, outcome: Outcome.reply(() => value, metadata) });
+    }
+    error(message, code = ErrorCode.BadRequest) {
+        return Object.freeze({ kind: "read-only", retention: null, outcome: Outcome.fail(message, code) });
+    }
+    noReply() {
+        return Object.freeze({ kind: "read-only", retention: null, outcome: Outcome.noReply() });
+    }
+}
+export { done };

package/dist/effects/stateless.d.ts

@@ -0,0 +1,40 @@
+import { ErrorCode, type EffectLike, type ErrorDetail, type Metadata } from "./common.ts";
+export type ViewEffect<Row> = ({
+    readonly kind: "update-row";
+    readonly row: Row;
+} & EffectLike<never>) | ({
+    readonly kind: "delete-row";
+} & EffectLike<never>) | ({
+    readonly kind: "ignore";
+} & EffectLike<never>);
+export declare class ViewEffects<Row> {
+    updateRow(row: Row): ViewEffect<Row>;
+    deleteRow(): ViewEffect<Row>;
+    ignore(): ViewEffect<Row>;
+}
+export type ConsumerEffect<Out> = ({
+    readonly kind: "produce";
+    readonly payload: Out;
+    readonly metadata: Metadata;
+} & EffectLike<never>) | ({
+    readonly kind: "done";
+} & EffectLike<never>) | ({
+    readonly kind: "ignore";
+} & EffectLike<never>);
+export declare class ConsumerEffects<Out> {
+    /** Produce onward to the topic the consumer declares in `producesTo`. */
+    produce(payload: Out, metadata?: Metadata): ConsumerEffect<Out>;
+    done(): ConsumerEffect<Out>;
+    ignore(): ConsumerEffect<Out>;
+}
+export type TimedActionEffect = ({
+    readonly kind: "done";
+} & EffectLike<never>) | ({
+    readonly kind: "fail";
+    readonly error: ErrorDetail;
+} & EffectLike<never>);
+export declare class TimedActionEffects {
+    done(): TimedActionEffect;
+    /** Failed: the sweeper retries on its schedule with the attempt count incremented. */
+    fail(message: string, code?: ErrorCode): TimedActionEffect;
+}

package/dist/effects/stateless.js

@@ -0,0 +1,35 @@
+// Effects for the stateless kinds: a view says what an event does to a row, a consumer acknowledges
+// or produces onward, a timed action is done or failed (and retried by the sweeper).
+import { ErrorCode } from "./common.js";
+export class ViewEffects {
+    updateRow(row) {
+        return Object.freeze({ kind: "update-row", row });
+    }
+    deleteRow() {
+        return Object.freeze({ kind: "delete-row" });
+    }
+    ignore() {
+        return Object.freeze({ kind: "ignore" });
+    }
+}
+export class ConsumerEffects {
+    /** Produce onward to the topic the consumer declares in `producesTo`. */
+    produce(payload, metadata = {}) {
+        return Object.freeze({ kind: "produce", payload, metadata });
+    }
+    done() {
+        return Object.freeze({ kind: "done" });
+    }
+    ignore() {
+        return Object.freeze({ kind: "ignore" });
+    }
+}
+export class TimedActionEffects {
+    done() {
+        return Object.freeze({ kind: "done" });
+    }
+    /** Failed: the sweeper retries on its schedule with the attempt count incremented. */
+    fail(message, code = ErrorCode.Internal) {
+        return Object.freeze({ kind: "fail", error: { message, code } });
+    }
+}