ankka 0.6.0

package/dist/client.d.ts

@@ -0,0 +1,92 @@
+import { type Client as ConnectClient, type Transport } from "@connectrpc/connect";
+import { Client } from "./_proto/ankka/protocol/v1/client_pb.ts";
+import { jsonCodec, type Shape } from "./codec.ts";
+import { type Metadata } from "./effects/common.ts";
+import type { HandlerRef } from "./handlers.ts";
+import { type ComponentKind } from "./kinds.ts";
+import type { Duration } from "./time.ts";
+/** A component class as the typed client sees it: an id and, on its prototype, its kind. */
+export interface ComponentRef {
+    readonly componentId: string;
+    readonly prototype: {
+        readonly _kind: ComponentKind;
+    };
+}
+interface Connection {
+    address: string;
+    transport: Transport | undefined;
+    stub: ConnectClient<typeof Client> | undefined;
+}
+/** One call, ready to invoke or stream. */
+export declare class Invocation<I, R> {
+    #private;
+    constructor(connection: Connection, metadata: Metadata, kind: ComponentKind, componentId: string, entityId: string, name: string, input: Shape<I> | undefined, reply: Shape<R> | undefined);
+    /** Invokes and decodes the reply; a refusal rejects with `CommandError`. */
+    invoke(input?: I): Promise<R>;
+    /** Invokes a streaming handler; yields tokens in order; a failure rejects with `CommandError`. */
+    stream(input?: I): AsyncIterable<string>;
+}
+/** Calls on one component instance, by wire name. */
+export declare class Calls {
+    #private;
+    constructor(connection: Connection, metadata: Metadata, kind: ComponentKind, componentId: string, entityId: string);
+    /** `call("add-item", LineItem, Done)`: the wire name, the input shape (omit for none) and the reply shape (omit for `done`). */
+    call<I = undefined, R = unknown>(name: string, input?: Shape<I>, reply?: Shape<R>): Invocation<I, R>;
+}
+/** Calls on one component instance through its class's handler table, fully typed. */
+export declare class TypedCalls<C> {
+    #private;
+    constructor(calls: Calls);
+    /** `call(ShoppingCartEntity.handlers.addItem)`: the handler's wire name and shapes come from the declaration. */
+    call<I, R>(handler: HandlerRef<C, I, R, any>): Invocation<I, R>;
+}
+/** View queries: rows come back as a JSON array decoded with the row shape. */
+export declare class Views {
+    #private;
+    constructor(connection: Connection);
+    get<Row>(viewId: string, key: string, row: Shape<Row>): Promise<Row | null>;
+    all<Row>(viewId: string, row: Shape<Row>): Promise<Row[]>;
+    query<Row>(viewId: string, name: string, key: string | null, row: Shape<Row>): Promise<Row[]>;
+}
+/** What a timer fires: a component class and one of its handlers, or the same by name. */
+export type TimerTarget = {
+    readonly component: ComponentRef;
+    readonly handler: HandlerRef<any, any, any, any>;
+    readonly entityId?: string;
+} | {
+    readonly kind: ComponentKind;
+    readonly componentId: string;
+    readonly name: string;
+    readonly input?: Shape<any>;
+    readonly entityId?: string;
+};
+export declare class Timers {
+    #private;
+    constructor(connection: Connection);
+    /** Schedules `target` after `delay`. Scheduling twice under one id replaces the earlier schedule. */
+    schedule(timerId: string, delay: Duration, target: TimerTarget, input?: unknown): Promise<void>;
+    cancel(timerId: string): Promise<void>;
+}
+export declare class ComponentClient {
+    #private;
+    readonly views: Views;
+    readonly timers: Timers;
+    constructor(address?: string, connection?: Connection, metadata?: Metadata);
+    /** Points every client sharing this connection at a new sidecar address (the integration testkit's mapped port). */
+    reconnect(address: string): void;
+    /** The sidecar address this client dials. */
+    get address(): string;
+    /** A client whose calls carry `metadata` (the current request's trace), sharing this one's connection. */
+    withMetadata(metadata: Metadata): ComponentClient;
+    forEventSourcedEntity(componentId: string, entityId: string): Calls;
+    forKeyValueEntity(componentId: string, entityId: string): Calls;
+    forWorkflow(componentId: string, workflowId: string): Calls;
+    forAgent(componentId: string, sessionId: string): Calls;
+    /** Typed calls through a component class's handler table: `client.of(ShoppingCartEntity, cartId).call(ShoppingCartEntity.handlers.addItem).invoke(item)`. */
+    of<C>(component: ComponentRef & {
+        new (): C;
+    }, entityId: string): TypedCalls<C>;
+}
+/** A client for unit tests: every call throws, naming what was attempted. */
+export declare function noClient(): ComponentClient;
+export { jsonCodec };

package/dist/client.js

@@ -0,0 +1,239 @@
+// The component client: how a handler calls other components, queries views and schedules timers. Every
+// call is a request on the sidecar's `Client` service at `ANKKA_SIDECAR_ADDRESS`; the sidecar routes it.
+// One channel per process, opened on first use so the integration testkit can learn the sidecar's
+// mapped port after construction. A client handed to a handler is scoped to that request's metadata,
+// so the sidecar records the call as a child span.
+import { createClient } from "@connectrpc/connect";
+import { createGrpcTransport } from "@connectrpc/connect-node";
+import { Client } from "./_proto/ankka/protocol/v1/client_pb.js";
+import { codecFor, jsonCodec, isCodec, textCodecs, binaryCodecs, codecForManifest } from "./codec.js";
+import { CommandError } from "./effects/common.js";
+import { decodeJsonValue, reviver } from "./json.js";
+import { errorCodeFromProto, kindToProto } from "./kinds.js";
+import { metadataToProto } from "./context.js";
+import { encodePayload, decodePayload, EMPTY_PAYLOAD } from "./server/payloads.js";
+function stubOf(connection) {
+    if (!connection.stub) {
+        connection.transport = createGrpcTransport({ baseUrl: `http://${connection.address}` });
+        connection.stub = createClient(Client, connection.transport);
+    }
+    return connection.stub;
+}
+function errorOf(error) {
+    return { message: error.message, code: errorCodeFromProto(error.code) };
+}
+function inputPayload(shape, input) {
+    if (shape === undefined) {
+        if (input !== undefined)
+            throw new TypeError("this handler takes no input");
+        return EMPTY_PAYLOAD;
+    }
+    return encodePayload(codecFor(shape), input);
+}
+function decodeReply(shape, payload) {
+    if (shape !== undefined)
+        return decodePayload(codecFor(shape), payload);
+    // No reply shape named: a primitive by its manifest, `done` otherwise.
+    const codec = payload ? codecForManifest(payload.manifest) : undefined;
+    return (codec ?? binaryCodecs.done).decode(payload?.data ?? new Uint8Array());
+}
+/** One call, ready to invoke or stream. */
+export class Invocation {
+    #connection;
+    #metadata;
+    #kind;
+    #componentId;
+    #entityId;
+    #name;
+    #input;
+    #reply;
+    constructor(connection, metadata, kind, componentId, entityId, name, input, reply) {
+        this.#connection = connection;
+        this.#metadata = metadata;
+        this.#kind = kind;
+        this.#componentId = componentId;
+        this.#entityId = entityId;
+        this.#name = name;
+        this.#input = input;
+        this.#reply = reply;
+    }
+    #request(input) {
+        return {
+            kind: kindToProto(this.#kind),
+            componentId: this.#componentId,
+            entityId: this.#entityId,
+            name: this.#name,
+            payload: inputPayload(this.#input, input),
+            metadata: metadataToProto(this.#metadata),
+        };
+    }
+    /** Invokes and decodes the reply; a refusal rejects with `CommandError`. */
+    async invoke(input) {
+        const answer = await stubOf(this.#connection).invoke(this.#request(input));
+        switch (answer.result.case) {
+            case "reply":
+                return decodeReply(this.#reply, answer.result.value.payload);
+            case "error":
+                throw new CommandError(errorOf(answer.result.value));
+            default:
+                throw new CommandError({ message: "the sidecar answered nothing", code: "INTERNAL" });
+        }
+    }
+    /** Invokes a streaming handler; yields tokens in order; a failure rejects with `CommandError`. */
+    async *stream(input) {
+        for await (const token of stubOf(this.#connection).invokeStream(this.#request(input))) {
+            switch (token.token.case) {
+                case "text":
+                    yield token.token.value;
+                    break;
+                case "completed":
+                    return;
+                case "failed":
+                    throw new CommandError(errorOf(token.token.value));
+            }
+        }
+    }
+}
+/** Calls on one component instance, by wire name. */
+export class Calls {
+    #connection;
+    #metadata;
+    #kind;
+    #componentId;
+    #entityId;
+    constructor(connection, metadata, kind, componentId, entityId) {
+        this.#connection = connection;
+        this.#metadata = metadata;
+        this.#kind = kind;
+        this.#componentId = componentId;
+        this.#entityId = entityId;
+    }
+    /** `call("add-item", LineItem, Done)`: the wire name, the input shape (omit for none) and the reply shape (omit for `done`). */
+    call(name, input, reply) {
+        return new Invocation(this.#connection, this.#metadata, this.#kind, this.#componentId, this.#entityId, name, input, reply);
+    }
+}
+/** Calls on one component instance through its class's handler table, fully typed. */
+export class TypedCalls {
+    #calls;
+    constructor(calls) {
+        this.#calls = calls;
+    }
+    /** `call(ShoppingCartEntity.handlers.addItem)`: the handler's wire name and shapes come from the declaration. */
+    call(handler) {
+        return this.#calls.call(handler.name, handler.input, handler.reply);
+    }
+}
+/** View queries: rows come back as a JSON array decoded with the row shape. */
+export class Views {
+    #connection;
+    constructor(connection) {
+        this.#connection = connection;
+    }
+    async get(viewId, key, row) {
+        const rows = await this.query(viewId, "get", key, row);
+        return rows[0] ?? null;
+    }
+    async all(viewId, row) {
+        return this.query(viewId, "all", null, row);
+    }
+    async query(viewId, name, key, row) {
+        const answer = await stubOf(this.#connection).query({ viewId, name, payload: encodePayload(textCodecs.string, key ?? "") });
+        switch (answer.result.case) {
+            case "rows": {
+                const text = new TextDecoder().decode(answer.result.value.data);
+                const documents = JSON.parse(text, reviver);
+                if (!Array.isArray(documents))
+                    throw new CommandError({ message: "the view answered something other than a JSON array", code: "INTERNAL" });
+                if (isCodec(row)) {
+                    const utf8 = new TextEncoder();
+                    return documents.map((d) => row.decode(utf8.encode(JSON.stringify(d, (_k, v) => (typeof v === "bigint" ? JSON.rawJSON(v.toString()) : v)))));
+                }
+                return documents.map((d) => decodeJsonValue(row, d));
+            }
+            case "error":
+                throw new CommandError(errorOf(answer.result.value));
+            default:
+                throw new CommandError({ message: "the sidecar answered nothing", code: "INTERNAL" });
+        }
+    }
+}
+export class Timers {
+    #connection;
+    constructor(connection) {
+        this.#connection = connection;
+    }
+    /** Schedules `target` after `delay`. Scheduling twice under one id replaces the earlier schedule. */
+    async schedule(timerId, delay, target, input) {
+        const t = "component" in target
+            ? { kind: target.component.prototype._kind, componentId: target.component.componentId, name: target.handler.name, input: target.handler.input, entityId: target.entityId }
+            : target;
+        await stubOf(this.#connection).schedule({
+            timerId,
+            delayMillis: BigInt(delay.toMillis()),
+            kind: kindToProto(t.kind),
+            componentId: t.componentId,
+            ...(t.entityId !== undefined ? { entityId: t.entityId } : {}),
+            name: t.name,
+            payload: inputPayload(t.input, input),
+        });
+    }
+    async cancel(timerId) {
+        await stubOf(this.#connection).cancel({ timerId });
+    }
+}
+export class ComponentClient {
+    #connection;
+    #metadata;
+    views;
+    timers;
+    constructor(address = process.env.ANKKA_SIDECAR_ADDRESS ?? "127.0.0.1:9011", connection, metadata = {}) {
+        this.#connection = connection ?? { address, transport: undefined, stub: undefined };
+        this.#metadata = metadata;
+        this.views = new Views(this.#connection);
+        this.timers = new Timers(this.#connection);
+    }
+    /** Points every client sharing this connection at a new sidecar address (the integration testkit's mapped port). */
+    reconnect(address) {
+        this.#connection.address = address;
+        this.#connection.transport = undefined;
+        this.#connection.stub = undefined;
+    }
+    /** The sidecar address this client dials. */
+    get address() {
+        return this.#connection.address;
+    }
+    /** A client whose calls carry `metadata` (the current request's trace), sharing this one's connection. */
+    withMetadata(metadata) {
+        return new ComponentClient(this.#connection.address, this.#connection, metadata);
+    }
+    forEventSourcedEntity(componentId, entityId) {
+        return new Calls(this.#connection, this.#metadata, "event-sourced", componentId, entityId);
+    }
+    forKeyValueEntity(componentId, entityId) {
+        return new Calls(this.#connection, this.#metadata, "key-value", componentId, entityId);
+    }
+    forWorkflow(componentId, workflowId) {
+        return new Calls(this.#connection, this.#metadata, "workflow", componentId, workflowId);
+    }
+    forAgent(componentId, sessionId) {
+        return new Calls(this.#connection, this.#metadata, "agent", componentId, sessionId);
+    }
+    /** Typed calls through a component class's handler table: `client.of(ShoppingCartEntity, cartId).call(ShoppingCartEntity.handlers.addItem).invoke(item)`. */
+    of(component, entityId) {
+        return new TypedCalls(new Calls(this.#connection, this.#metadata, component.prototype._kind, component.componentId, entityId));
+    }
+}
+/** A client for unit tests: every call throws, naming what was attempted. */
+export function noClient() {
+    const fail = () => {
+        throw new Error("this component called another component; the unit testkit has no sidecar. Pass a stub ComponentClient to the kit.");
+    };
+    const connection = {
+        address: "unit-test",
+        transport: undefined,
+        stub: new Proxy({}, { get: () => fail }),
+    };
+    return new ComponentClient("unit-test", connection);
+}
+export { jsonCodec };

package/dist/codec.d.ts

@@ -0,0 +1,44 @@
+import { Duration } from "./time.ts";
+import { type Schema } from "./schema.ts";
+export type ContentType = "application/json" | "text/plain" | "application/octet-stream";
+export declare const JSON_CONTENT: ContentType;
+export declare const TEXT_CONTENT: ContentType;
+export declare const BINARY_CONTENT: ContentType;
+export interface Codec<T> {
+    readonly manifest: string;
+    readonly contentType: ContentType;
+    encode(value: T): Uint8Array;
+    decode(bytes: Uint8Array): T;
+}
+/** Where a schema is expected, a codec is accepted too. */
+export type Shape<T> = Schema<T> | Codec<T>;
+export declare function isCodec<T>(shape: Shape<T>): shape is Codec<T>;
+/** The codec for a shape: the codec itself, or the schema's default. */
+export declare function codecFor<T>(shape: Shape<T>): Codec<T>;
+/** The default JSON codec for a schema, under `manifest` (the schema's name when omitted). */
+export declare function jsonCodec<T>(schema: Schema<T>, manifest?: string): Codec<T>;
+/** The `text/plain` codecs for top-level primitives. */
+export declare const textCodecs: Readonly<{
+    string: Codec<string>;
+    int: Codec<number>;
+    short: Codec<number>;
+    byte: Codec<number>;
+    long: Codec<bigint>;
+    double: Codec<number>;
+    float: Codec<number>;
+    boolean: Codec<boolean>;
+    durationMillis: Codec<Duration>;
+}>;
+/** The binary codecs: `done`, `unit`, raw bytes, and a top-level option over another codec. */
+export declare const binaryCodecs: Readonly<{
+    done: Codec<Readonly<{
+        readonly done: true;
+    }>>;
+    unit: Codec<undefined>;
+    bytes: Codec<Uint8Array<ArrayBufferLike>>;
+    option<T>(inner: Codec<T>): Codec<T | null>;
+}>;
+/** The default codec for a schema: text for a top-level scalar, binary for done/unit/bytes/option, JSON otherwise. */
+export declare function defaultCodecFor<T>(schema: Schema<T>): Codec<T>;
+/** The primitive codec a manifest names, including `option[<inner>]`, or `undefined` for a domain manifest. */
+export declare function codecForManifest(manifest: string): Codec<unknown> | undefined;

package/dist/codec.js

@@ -0,0 +1,215 @@
+// Codecs: a manifest, a content type, and the bytes for a value (protocol/ENCODING.md). The default
+// codec for a schema is derived from it — a record or sum type is JSON under the schema's name; a
+// top-level scalar is `text/plain` under its primitive manifest; `Done`, `unit`, bytes and a top-level
+// option are the binary payloads. A developer may hand over any object satisfying `Codec<T>` where a
+// schema is expected; then portability is their contract.
+import { Duration } from "./time.js";
+import { done, defaultManifest, describe, resolve } from "./schema.js";
+import { readJson, renderDouble, writeJson, DecodingError } from "./json.js";
+export const JSON_CONTENT = "application/json";
+export const TEXT_CONTENT = "text/plain";
+export const BINARY_CONTENT = "application/octet-stream";
+export function isCodec(shape) {
+    return typeof shape.encode === "function" && typeof shape.decode === "function";
+}
+/** The codec for a shape: the codec itself, or the schema's default. */
+export function codecFor(shape) {
+    return isCodec(shape) ? shape : defaultCodecFor(shape);
+}
+const utf8 = new TextEncoder();
+const utf8Decoder = new TextDecoder("utf-8", { fatal: true });
+function text(bytes) {
+    return utf8Decoder.decode(bytes);
+}
+function frozen(codec) {
+    return Object.freeze(codec);
+}
+/** The default JSON codec for a schema, under `manifest` (the schema's name when omitted). */
+export function jsonCodec(schema, manifest = defaultManifest(schema)) {
+    if (typeof manifest !== "string" || manifest.trim() === "")
+        throw new TypeError(`jsonCodec(${describe(schema)}): a manifest is required`);
+    return frozen({
+        manifest,
+        contentType: JSON_CONTENT,
+        encode: (value) => utf8.encode(writeJson(schema, value)),
+        decode: (bytes) => readJson(schema, text(bytes)),
+    });
+}
+function textCodec(manifest, parse, render) {
+    return frozen({
+        manifest,
+        contentType: TEXT_CONTENT,
+        encode: (value) => utf8.encode(render(value)),
+        decode: (bytes) => parse(text(bytes)),
+    });
+}
+function parseInteger(manifest, min, max) {
+    return (s) => {
+        if (!/^-?\d+$/.test(s.trim()))
+            throw new DecodingError(`not a whole number for ${manifest}: ${JSON.stringify(s)}`, "");
+        const n = Number(s);
+        if (!Number.isSafeInteger(n) || n < min || n > max)
+            throw new DecodingError(`${s} does not fit ${manifest}`, "");
+        return n;
+    };
+}
+function renderInteger(manifest) {
+    return (v) => {
+        if (!Number.isSafeInteger(v))
+            throw new TypeError(`${manifest}: expected a whole number, got ${String(v)}`);
+        return String(v);
+    };
+}
+function parseDouble(s) {
+    const t = s.trim();
+    if (t === "NaN")
+        return NaN;
+    if (t === "Infinity")
+        return Infinity;
+    if (t === "-Infinity")
+        return -Infinity;
+    const n = Number(t);
+    if (t === "" || Number.isNaN(n))
+        throw new DecodingError(`not a number: ${JSON.stringify(s)}`, "");
+    return n;
+}
+function renderDoubleText(d) {
+    if (Number.isNaN(d))
+        return "NaN";
+    if (d === Infinity)
+        return "Infinity";
+    if (d === -Infinity)
+        return "-Infinity";
+    return renderDouble(d);
+}
+/** The `text/plain` codecs for top-level primitives. */
+export const textCodecs = Object.freeze({
+    string: textCodec("string", (s) => s, (v) => v),
+    int: textCodec("int", parseInteger("int", -2147483648, 2147483647), renderInteger("int")),
+    short: textCodec("short", parseInteger("short", -32768, 32767), renderInteger("short")),
+    byte: textCodec("byte", parseInteger("byte", -128, 127), renderInteger("byte")),
+    long: textCodec("long", (s) => {
+        if (!/^-?\d+$/.test(s.trim()))
+            throw new DecodingError(`not a whole number for long: ${JSON.stringify(s)}`, "");
+        return BigInt(s.trim());
+    }, (v) => {
+        if (typeof v === "bigint")
+            return v.toString();
+        if (typeof v === "number" && Number.isSafeInteger(v))
+            return String(v);
+        throw new TypeError(`long: expected a bigint, got ${String(v)}`);
+    }),
+    double: textCodec("double", parseDouble, renderDoubleText),
+    float: textCodec("float", parseDouble, renderDoubleText),
+    boolean: textCodec("boolean", (s) => {
+        const t = s.trim();
+        if (t === "true")
+            return true;
+        if (t === "false")
+            return false;
+        throw new DecodingError(`not a boolean: ${JSON.stringify(s)}`, "");
+    }, (v) => (v ? "true" : "false")),
+    durationMillis: textCodec("duration-millis", (s) => {
+        if (!/^-?\d+$/.test(s.trim()))
+            throw new DecodingError(`not a millisecond count: ${JSON.stringify(s)}`, "");
+        return Duration.ofMillis(Number(s.trim()));
+    }, (v) => String(v.toMillis())),
+});
+const EMPTY = new Uint8Array(0);
+/** The binary codecs: `done`, `unit`, raw bytes, and a top-level option over another codec. */
+export const binaryCodecs = Object.freeze({
+    done: frozen({
+        manifest: "done",
+        contentType: BINARY_CONTENT,
+        encode: () => EMPTY,
+        decode: () => done,
+    }),
+    unit: frozen({
+        manifest: "unit",
+        contentType: BINARY_CONTENT,
+        encode: () => EMPTY,
+        decode: () => undefined,
+    }),
+    bytes: frozen({
+        manifest: "bytes",
+        contentType: BINARY_CONTENT,
+        encode: (v) => v,
+        decode: (b) => b,
+    }),
+    option(inner) {
+        return frozen({
+            manifest: `option[${inner.manifest}]`,
+            contentType: BINARY_CONTENT,
+            encode: (value) => {
+                if (value === null || value === undefined)
+                    return EMPTY;
+                const encoded = inner.encode(value);
+                const out = new Uint8Array(encoded.length + 1);
+                out[0] = 1;
+                out.set(encoded, 1);
+                return out;
+            },
+            decode: (bytes) => {
+                if (bytes.length === 0)
+                    return null;
+                if (bytes[0] !== 1)
+                    throw new DecodingError(`option[${inner.manifest}]: expected a 0x01 marker, got ${bytes[0]}`, "");
+                return inner.decode(bytes.subarray(1));
+            },
+        });
+    },
+});
+/** The default codec for a schema: text for a top-level scalar, binary for done/unit/bytes/option, JSON otherwise. */
+export function defaultCodecFor(schema) {
+    const r = resolve(schema);
+    switch (r.kind) {
+        case "string":
+            return textCodecs.string;
+        case "int":
+            return textCodecs.int;
+        case "long":
+            return textCodecs.long;
+        case "double":
+            return textCodecs.double;
+        case "boolean":
+            return textCodecs.boolean;
+        case "duration":
+            return textCodecs.durationMillis;
+        case "bytes":
+            return binaryCodecs.bytes;
+        case "done":
+            return binaryCodecs.done;
+        case "unit":
+            return binaryCodecs.unit;
+        case "option":
+            return binaryCodecs.option(defaultCodecFor(r.inner));
+        default:
+            return jsonCodec(schema);
+    }
+}
+const primitives = Object.freeze({
+    string: textCodecs.string,
+    int: textCodecs.int,
+    long: textCodecs.long,
+    short: textCodecs.short,
+    byte: textCodecs.byte,
+    double: textCodecs.double,
+    float: textCodecs.float,
+    boolean: textCodecs.boolean,
+    "duration-millis": textCodecs.durationMillis,
+    done: binaryCodecs.done,
+    unit: binaryCodecs.unit,
+    bytes: binaryCodecs.bytes,
+});
+/** The primitive codec a manifest names, including `option[<inner>]`, or `undefined` for a domain manifest. */
+export function codecForManifest(manifest) {
+    const direct = primitives[manifest];
+    if (direct)
+        return direct;
+    const m = /^option\[(.+)\]$/.exec(manifest);
+    if (m) {
+        const inner = codecForManifest(m[1]);
+        return inner ? binaryCodecs.option(inner) : undefined;
+    }
+    return undefined;
+}

package/dist/consumer.d.ts

@@ -0,0 +1,31 @@
+import type { Shape } from "./codec.ts";
+import type { Metadata } from "./effects/common.ts";
+import type { ComponentClient, ComponentRef } from "./client.ts";
+import { ConsumerEffects, type ConsumerEffect } from "./effects/stateless.ts";
+type MaybePromise<T> = T | Promise<T>;
+export declare abstract class Consumer<M, Out = never> {
+    #private;
+    readonly effects: ConsumerEffects<Out>;
+    /** The message's metadata: `ce-subject` is the source instance's id, `ankka.sequence` its sequence number. */
+    get metadata(): Metadata;
+    get subject(): string;
+    get client(): ComponentClient;
+    /** @internal */
+    get _kind(): "consumer";
+    abstract onMessage(message: M): MaybePromise<ConsumerEffect<Out>>;
+    /** The source was deleted. Ignored unless this says otherwise. */
+    onDelete(): MaybePromise<ConsumerEffect<Out>>;
+    /** @internal */
+    _bind(metadata: Metadata, client: ComponentClient): void;
+}
+export interface ConsumerClass<M = unknown, Out = unknown, C extends Consumer<M, Out> = Consumer<M, Out>> {
+    new (): C;
+    readonly componentId: string;
+    readonly source?: ComponentRef;
+    readonly topic?: string;
+    readonly message: Shape<M>;
+    /** The shape of what `produce` sends onward; required with `producesTo`. */
+    readonly out?: Shape<Out>;
+    readonly producesTo?: string;
+}
+export {};

package/dist/consumer.js

@@ -0,0 +1,32 @@
+// A consumer: reacts to a source's changes, optionally producing onward to a topic.
+import { ConsumerEffects } from "./effects/stateless.js";
+export class Consumer {
+    effects = new ConsumerEffects();
+    #metadata = {};
+    #client;
+    /** The message's metadata: `ce-subject` is the source instance's id, `ankka.sequence` its sequence number. */
+    get metadata() {
+        return this.#metadata;
+    }
+    get subject() {
+        return this.#metadata["ce-subject"] ?? "";
+    }
+    get client() {
+        if (!this.#client)
+            throw new Error("client is only available inside onMessage or onDelete");
+        return this.#client;
+    }
+    /** @internal */
+    get _kind() {
+        return "consumer";
+    }
+    /** The source was deleted. Ignored unless this says otherwise. */
+    onDelete() {
+        return this.effects.ignore();
+    }
+    /** @internal */
+    _bind(metadata, client) {
+        this.#metadata = metadata;
+        this.#client = client;
+    }
+}