ankka 0.6.0

package/dist/effects/workflow.d.ts

@@ -0,0 +1,99 @@
+import type { Duration } from "../time.ts";
+import { ErrorCode, Outcome, type EffectLike, type ErrorDetail, type Metadata, type ReadOnlyLike } from "./common.ts";
+/** A step to run, by wire name, with its input if it takes one. The step's declared shape encodes the input. */
+export interface StepRef {
+    readonly step: string;
+    readonly input: unknown;
+}
+export type StepOutcome = {
+    readonly kind: "transition";
+    readonly ref: StepRef;
+} | {
+    readonly kind: "pause";
+    readonly after: Duration | null;
+    readonly onTimeout: StepRef | null;
+} | {
+    readonly kind: "end";
+} | {
+    readonly kind: "fail";
+    readonly error: ErrorDetail;
+};
+/** A command handler's effect: a new state, a transition, and a reply. */
+export interface WorkflowEffect<S, R> extends EffectLike<R> {
+    readonly kind: "workflow";
+    readonly newState: S | null;
+    readonly transition: StepRef | null;
+    readonly outcome: Outcome<S, R>;
+}
+export interface WorkflowReadOnlyEffect<S, R> extends ReadOnlyLike<R> {
+    readonly kind: "read-only";
+    readonly newState: null;
+    readonly transition: null;
+    readonly outcome: Outcome<S, R>;
+}
+export type WorkflowCommandEffect<S, R> = WorkflowEffect<S, R> | WorkflowReadOnlyEffect<S, R>;
+/** A step's effect: a new state and what happens next. */
+export interface StepEffect<S> extends EffectLike<never> {
+    readonly kind: "step";
+    readonly newState: S | null;
+    readonly next: StepOutcome;
+}
+export interface PauseOptions {
+    /** How long to pause before `onTimeout` runs; absent, the pause waits for a command. */
+    readonly after?: Duration;
+    /** The step to run when the pause times out. */
+    readonly onTimeout?: string;
+    readonly onTimeoutInput?: unknown;
+}
+export declare class WorkflowUpdateBuilder<S> {
+    #private;
+    constructor(newState: S | null, transition?: StepRef | null);
+    /** Start `step` once this command's state is journaled. */
+    thenTransitionTo(step: string, input?: unknown): WorkflowUpdateBuilder<S>;
+    thenReply<R>(compute: (state: S) => R, metadata?: Metadata): WorkflowEffect<S, R>;
+    thenReplyState(): WorkflowEffect<S, S>;
+    thenNoReply(): WorkflowEffect<S, never>;
+}
+/** Inside a command handler: `this.effects`. */
+export declare class WorkflowEffects<S> {
+    updateState(state: S): WorkflowUpdateBuilder<S>;
+    transitionTo(step: string, input?: unknown): WorkflowUpdateBuilder<S>;
+    reply<R>(value: R, metadata?: Metadata): WorkflowReadOnlyEffect<S, R>;
+    error(message: string, code?: ErrorCode): WorkflowReadOnlyEffect<S, never>;
+}
+export declare class StepUpdateBuilder<S> {
+    #private;
+    constructor(newState: S | null);
+    thenTransitionTo(step: string, input?: unknown): StepEffect<S>;
+    /** Pause until a command moves the workflow on, or `after` passes and `onTimeout` runs. */
+    thenPause(options?: PauseOptions): StepEffect<S>;
+    thenEnd(): StepEffect<S>;
+    /** End the workflow as failed. This is what the step answered on purpose; a *thrown* error is retried and failed over as declared. */
+    thenFail(message: string, code?: ErrorCode): StepEffect<S>;
+}
+/** Inside a step: `this.stepEffects`. */
+export declare class StepEffects<S> {
+    updateState(state: S): StepUpdateBuilder<S>;
+    transitionTo(step: string, input?: unknown): StepEffect<S>;
+    pause(options?: PauseOptions): StepEffect<S>;
+    end(): StepEffect<S>;
+    fail(message: string, code?: ErrorCode): StepEffect<S>;
+}
+/** What the sidecar does when a step throws or times out: retry it, then fail over to a step that takes no input, or fail the workflow. */
+export interface Recovery {
+    readonly maxRetries: number;
+    readonly failoverTo?: string;
+}
+export interface StepSettings {
+    readonly timeout?: Duration;
+    readonly recovery?: Recovery;
+}
+/** Timeouts and recovery, enforced by the sidecar's engine. Absent values are the engine's defaults: no overall limit, 30 seconds a step, a failed step fails the workflow. */
+export interface WorkflowSettings {
+    readonly timeout?: Duration;
+    readonly defaultStepTimeout?: Duration;
+    readonly defaultRecovery?: Recovery;
+    readonly steps?: Readonly<Record<string, StepSettings>>;
+}
+/** Declares a workflow's settings; the registry checks every step it names against the declared steps. */
+export declare function workflowSettings(settings: WorkflowSettings): WorkflowSettings;

package/dist/effects/workflow.js

@@ -0,0 +1,83 @@
+// Effects for workflows: a command may change state and start a step; a step changes state and says
+// what happens next. Timeouts and recovery are declared in `settings` and enforced by the sidecar's
+// engine, since the process cannot enforce them.
+import { ErrorCode, Outcome } from "./common.js";
+export class WorkflowUpdateBuilder {
+    #newState;
+    #transition;
+    constructor(newState, transition = null) {
+        this.#newState = newState;
+        this.#transition = transition;
+    }
+    /** Start `step` once this command's state is journaled. */
+    thenTransitionTo(step, input) {
+        return new WorkflowUpdateBuilder(this.#newState, { step, input });
+    }
+    thenReply(compute, metadata) {
+        return Object.freeze({ kind: "workflow", newState: this.#newState, transition: this.#transition, outcome: Outcome.reply(compute, metadata) });
+    }
+    thenReplyState() {
+        return this.thenReply((state) => state);
+    }
+    thenNoReply() {
+        return Object.freeze({ kind: "workflow", newState: this.#newState, transition: this.#transition, outcome: Outcome.noReply() });
+    }
+}
+/** Inside a command handler: `this.effects`. */
+export class WorkflowEffects {
+    updateState(state) {
+        return new WorkflowUpdateBuilder(state);
+    }
+    transitionTo(step, input) {
+        return new WorkflowUpdateBuilder(null, { step, input });
+    }
+    reply(value, metadata) {
+        return Object.freeze({ kind: "read-only", newState: null, transition: null, outcome: Outcome.reply(() => value, metadata) });
+    }
+    error(message, code = ErrorCode.BadRequest) {
+        return Object.freeze({ kind: "read-only", newState: null, transition: null, outcome: Outcome.fail(message, code) });
+    }
+}
+export class StepUpdateBuilder {
+    #newState;
+    constructor(newState) {
+        this.#newState = newState;
+    }
+    thenTransitionTo(step, input) {
+        return Object.freeze({ kind: "step", newState: this.#newState, next: { kind: "transition", ref: { step, input } } });
+    }
+    /** Pause until a command moves the workflow on, or `after` passes and `onTimeout` runs. */
+    thenPause(options = {}) {
+        const onTimeout = options.onTimeout ? { step: options.onTimeout, input: options.onTimeoutInput } : null;
+        return Object.freeze({ kind: "step", newState: this.#newState, next: { kind: "pause", after: options.after ?? null, onTimeout } });
+    }
+    thenEnd() {
+        return Object.freeze({ kind: "step", newState: this.#newState, next: { kind: "end" } });
+    }
+    /** End the workflow as failed. This is what the step answered on purpose; a *thrown* error is retried and failed over as declared. */
+    thenFail(message, code = ErrorCode.Internal) {
+        return Object.freeze({ kind: "step", newState: this.#newState, next: { kind: "fail", error: { message, code } } });
+    }
+}
+/** Inside a step: `this.stepEffects`. */
+export class StepEffects {
+    updateState(state) {
+        return new StepUpdateBuilder(state);
+    }
+    transitionTo(step, input) {
+        return new StepUpdateBuilder(null).thenTransitionTo(step, input);
+    }
+    pause(options = {}) {
+        return new StepUpdateBuilder(null).thenPause(options);
+    }
+    end() {
+        return new StepUpdateBuilder(null).thenEnd();
+    }
+    fail(message, code = ErrorCode.Internal) {
+        return new StepUpdateBuilder(null).thenFail(message, code);
+    }
+}
+/** Declares a workflow's settings; the registry checks every step it names against the declared steps. */
+export function workflowSettings(settings) {
+    return Object.freeze({ ...settings, steps: settings.steps ? Object.freeze({ ...settings.steps }) : undefined });
+}

package/dist/endpoint.d.ts

@@ -0,0 +1,21 @@
+import type { ComponentClient } from "./client.ts";
+import { type RequestContext } from "./context.ts";
+import type { Acl, RouteTable } from "./routes.ts";
+export declare abstract class Endpoint {
+    #private;
+    /** The request being handled: path parameters, query, headers, principal. Request-scoped. */
+    get request(): RequestContext;
+    /** The component client, scoped to the current request's trace so the sidecar records child spans. */
+    get client(): ComponentClient;
+    /** @internal */
+    _bindClient(client: ComponentClient | undefined): void;
+}
+/** The statics an endpoint class must declare; `register` constrains on this type, so a missing `acl` is a compile error. */
+export interface EndpointClass<C extends Endpoint = Endpoint> {
+    new (): C;
+    /** `/carts`: every route is relative to it. */
+    readonly prefix: string;
+    /** Who may call, for every route unless a route states its own. */
+    readonly acl: Acl;
+    readonly routes: RouteTable<C>;
+}

package/dist/endpoint.js

@@ -0,0 +1,29 @@
+// An HTTP endpoint: a prefix, an access rule and a table of routes. The sidecar serves the routes on
+// the service's HTTP port and forwards each request here; the process never binds an HTTP port. One
+// instance serves every request, so per-request state lives on `this.request`, never on a field.
+//
+//   export class ShoppingCartEndpoint extends Endpoint {
+//     static readonly prefix = "/carts"
+//     static readonly acl = Acl.allowAll                 // required; there is no default
+//     static readonly routes = { getCart: get("/{cartId}", ShoppingCart, (ep: ShoppingCartEndpoint, req) => ep.getCart(req.params.cartId)) }
+//     getCart(cartId: string) { return this.client.of(ShoppingCartEntity, cartId).call(ShoppingCartEntity.handlers.getCart).invoke() }
+//   }
+import { currentRequest, requestIfAny } from "./context.js";
+export class Endpoint {
+    #client;
+    /** The request being handled: path parameters, query, headers, principal. Request-scoped. */
+    get request() {
+        return currentRequest();
+    }
+    /** The component client, scoped to the current request's trace so the sidecar records child spans. */
+    get client() {
+        if (!this.#client)
+            throw new Error("client is only available inside a route handler");
+        const request = requestIfAny();
+        return request ? this.#client.withMetadata(request.metadata) : this.#client;
+    }
+    /** @internal */
+    _bindClient(client) {
+        this.#client = client;
+    }
+}

package/dist/eventSourcedEntity.d.ts

@@ -0,0 +1,40 @@
+import type { Shape } from "./codec.ts";
+import type { CommandContext } from "./context.ts";
+import type { HandlerTable } from "./handlers.ts";
+import type { ComponentClient } from "./client.ts";
+import { EventSourcedEffects } from "./effects/eventSourced.ts";
+export declare abstract class EventSourcedEntity<S, E> {
+    #private;
+    /** The effect builders: `this.effects.persist(...)`, `.reply(...)`, `.error(...)`. */
+    readonly effects: EventSourcedEffects<S, E>;
+    /** The state the entity has now, inside a handler. */
+    get state(): S;
+    /** The id of the instance this object stands for; available in `emptyState` and in handlers. */
+    get entityId(): string;
+    /** The command's context: component id, sequence number, metadata, the clock. */
+    get context(): CommandContext;
+    /** The component client, scoped to the command's trace. */
+    get client(): ComponentClient;
+    /** @internal The kind, read off the prototype by the typed client and the timers. */
+    get _kind(): "event-sourced";
+    /** The state of an instance with no events yet. `this.entityId` is available here. */
+    abstract emptyState(): S;
+    /** The fold: the state after `event`, given the state before it. Must not read `this.state`. */
+    abstract applyEvent(state: S, event: E): S;
+    /** @internal Bound by the runtime and the testkit before `emptyState`. */
+    _bindInstance(entityId: string): void;
+    /** @internal Bound by the runtime and the testkit for the duration of one handler call. */
+    _bindCommand(state: S, context: CommandContext, client: ComponentClient): void;
+    /** @internal */
+    _unbindCommand(): void;
+}
+/** The statics an event sourced entity class must declare; `register` constrains on this type. */
+export interface EventSourcedEntityClass<S = unknown, E = unknown, C extends EventSourcedEntity<S, E> = EventSourcedEntity<S, E>> {
+    new (): C;
+    readonly componentId: string;
+    readonly state: Shape<S>;
+    readonly events: Shape<E>;
+    readonly handlers: HandlerTable<C>;
+    /** Ask for a snapshot every N events; absent or 0: never. */
+    readonly snapshotEvery?: number;
+}

package/dist/eventSourcedEntity.js

@@ -0,0 +1,66 @@
+// An event sourced entity: state derived from a journal of events. The class declares its identity and
+// codecs as statics and its handlers in a static table; the instance holds the state for one command.
+//
+//   export class ShoppingCartEntity extends EventSourcedEntity<ShoppingCart, ShoppingCartEvent> {
+//     static readonly componentId = "shopping-cart"
+//     static readonly state = jsonCodec(ShoppingCart, "shopping-cart")
+//     static readonly events = jsonCodec(ShoppingCartEvent, "shopping-cart-event")
+//     static readonly handlers = { addItem: command("add-item", LineItem, Done, (cart: ShoppingCartEntity, item) => cart.addItem(item)) }
+//     emptyState() { ... }   applyEvent(state, event) { ... }   addItem(item) { return this.effects.persist(...).thenReply(() => done) }
+//   }
+import { EventSourcedEffects } from "./effects/eventSourced.js";
+export class EventSourcedEntity {
+    /** The effect builders: `this.effects.persist(...)`, `.reply(...)`, `.error(...)`. */
+    effects = new EventSourcedEffects();
+    #state;
+    #entityId;
+    #context;
+    #client;
+    #bound = false;
+    /** The state the entity has now, inside a handler. */
+    get state() {
+        if (!this.#bound)
+            throw new Error("state is only available inside a command handler");
+        return this.#state;
+    }
+    /** The id of the instance this object stands for; available in `emptyState` and in handlers. */
+    get entityId() {
+        if (this.#entityId === undefined)
+            throw new Error("entityId is only available once the entity is bound to an instance");
+        return this.#entityId;
+    }
+    /** The command's context: component id, sequence number, metadata, the clock. */
+    get context() {
+        if (!this.#context)
+            throw new Error("context is only available inside a command handler");
+        return this.#context;
+    }
+    /** The component client, scoped to the command's trace. */
+    get client() {
+        if (!this.#client)
+            throw new Error("client is only available inside a command handler");
+        return this.#client;
+    }
+    /** @internal The kind, read off the prototype by the typed client and the timers. */
+    get _kind() {
+        return "event-sourced";
+    }
+    /** @internal Bound by the runtime and the testkit before `emptyState`. */
+    _bindInstance(entityId) {
+        this.#entityId = entityId;
+    }
+    /** @internal Bound by the runtime and the testkit for the duration of one handler call. */
+    _bindCommand(state, context, client) {
+        this.#state = state;
+        this.#context = context;
+        this.#client = client;
+        this.#bound = true;
+    }
+    /** @internal */
+    _unbindCommand() {
+        this.#state = undefined;
+        this.#context = undefined;
+        this.#client = undefined;
+        this.#bound = false;
+    }
+}

package/dist/handlers.d.ts

@@ -0,0 +1,55 @@
+import type { Shape } from "./codec.ts";
+import type { EffectLike, ReadOnlyLike } from "./effects/common.ts";
+export type HandlerKind = "command" | "query" | "stream" | "step" | "action";
+type MaybePromise<T> = T | Promise<T>;
+/** One entry of a handler table. `C` is the component class, `I` the input, `R` the reply. */
+export interface HandlerRef<C = unknown, I = unknown, R = unknown, E extends EffectLike = EffectLike> {
+    readonly kind: HandlerKind;
+    /** The wire name. */
+    readonly name: string;
+    readonly input: Shape<I> | undefined;
+    readonly reply: Shape<R> | undefined;
+    readonly readOnly: boolean;
+    readonly streaming: boolean;
+    readonly run: (self: C, input: I) => MaybePromise<E>;
+}
+/**
+ * A command handler: may persist, update, transition or refuse. `command("add-item", LineItem, Done, (e, item) => e.addItem(item))`,
+ * or without an input: `command("checkout", Done, (e) => e.checkout())`.
+ */
+export declare function command<C, I, R, E extends EffectLike<R>>(name: string, input: Shape<I>, reply: Shape<R>, run: (self: C, input: I) => MaybePromise<E>): HandlerRef<C, I, R, E>;
+export declare function command<C, R, E extends EffectLike<R>>(name: string, reply: Shape<R>, run: (self: C) => MaybePromise<E>): HandlerRef<C, undefined, R, E>;
+/**
+ * A query handler: its function must return a read-only effect, so a query that persists does not
+ * compile. Registration checks the effect's `kind` again at runtime, and the sidecar refuses events
+ * from a read-only handler regardless.
+ */
+export declare function query<C, I, R, E extends ReadOnlyLike<R>>(name: string, input: Shape<I>, reply: Shape<R>, run: (self: C, input: I) => MaybePromise<E>): HandlerRef<C, I, R, E>;
+export declare function query<C, R, E extends ReadOnlyLike<R>>(name: string, reply: Shape<R>, run: (self: C) => MaybePromise<E>): HandlerRef<C, undefined, R, E>;
+/** An agent handler whose reply streams as tokens: `stream("stream", s.string, (a, q) => a.ask(q))`. */
+export declare function stream<C, I, E extends EffectLike>(name: string, input: Shape<I>, run: (self: C, input: I) => MaybePromise<E>): HandlerRef<C, I, string, E>;
+export declare function stream<C, E extends EffectLike>(name: string, run: (self: C) => MaybePromise<E>): HandlerRef<C, undefined, string, E>;
+/** A workflow step: `step("charge", s.int, (w, quantity) => w.charge(quantity))` or `step("reserve", (w) => w.reserve())`. */
+export declare function step<C, I, E extends EffectLike>(name: string, input: Shape<I>, run: (self: C, input: I) => MaybePromise<E>): HandlerRef<C, I, undefined, E>;
+export declare function step<C, E extends EffectLike>(name: string, run: (self: C) => MaybePromise<E>): HandlerRef<C, undefined, undefined, E>;
+/** A timed action: `action("remind", s.string, (t, id) => t.remind(id))`. */
+export declare function action<C, I, E extends EffectLike>(name: string, input: Shape<I>, run: (self: C, input: I) => MaybePromise<E>): HandlerRef<C, I, undefined, E>;
+export declare function action<C, E extends EffectLike>(name: string, run: (self: C) => MaybePromise<E>): HandlerRef<C, undefined, undefined, E>;
+/** An agent tool: the model sees `description` and the JSON Schema of `input`; the process runs `run`. */
+export interface ToolRef<C = unknown, I = unknown> {
+    readonly name: string;
+    readonly description: string;
+    readonly input: Shape<I>;
+    readonly run: (self: C, input: I) => MaybePromise<unknown>;
+}
+export declare function tool<C, I>(name: string, description: string, input: Shape<I>, run: (self: C, input: I) => MaybePromise<unknown>): ToolRef<C, I>;
+export type GuardrailStage = "input" | "output";
+/** An agent guardrail: returns a reason to block, or `null` to let the text through. */
+export interface GuardrailRef {
+    readonly name: string;
+    readonly check: (stage: GuardrailStage, text: string) => MaybePromise<string | null>;
+}
+export declare function guardrail(name: string, check: (stage: GuardrailStage, text: string) => MaybePromise<string | null>): GuardrailRef;
+/** The handler table type a component declares: property names are the developer's, `name` is the wire's. */
+export type HandlerTable<C> = Readonly<Record<string, HandlerRef<C, any, any, any>>>;
+export {};

package/dist/handlers.js

@@ -0,0 +1,64 @@
+// Handler declarations: the entries of a component's static `handlers`, `steps`, `actions`, `tools`
+// and `guardrails` tables. Each carries the wire name, the input and reply schemas, and the function
+// that runs it. The wire name is declared here and nowhere else; renaming the method it calls changes
+// nothing on the wire. These are plain values, so the registry can read them without reflection.
+function ref(kind, name, input, reply, run, flags) {
+    if (typeof name !== "string" || name.trim() === "")
+        throw new TypeError(`a ${kind} needs a wire name`);
+    if (typeof run !== "function")
+        throw new TypeError(`${kind} ${name}: the handler is not a function`);
+    return Object.freeze({ kind, name, input, reply, run, ...flags });
+}
+export function command(name, ...rest) {
+    if (rest.length === 3) {
+        const [input, reply, run] = rest;
+        return ref("command", name, input, reply, run, { readOnly: false, streaming: false });
+    }
+    const [reply, run] = rest;
+    return ref("command", name, undefined, reply, run, { readOnly: false, streaming: false });
+}
+export function query(name, ...rest) {
+    if (rest.length === 3) {
+        const [input, reply, run] = rest;
+        return ref("query", name, input, reply, run, { readOnly: true, streaming: false });
+    }
+    const [reply, run] = rest;
+    return ref("query", name, undefined, reply, run, { readOnly: true, streaming: false });
+}
+export function stream(name, ...rest) {
+    if (rest.length === 2) {
+        const [input, run] = rest;
+        return ref("stream", name, input, undefined, run, { readOnly: false, streaming: true });
+    }
+    const [run] = rest;
+    return ref("stream", name, undefined, undefined, run, { readOnly: false, streaming: true });
+}
+export function step(name, ...rest) {
+    if (rest.length === 2) {
+        const [input, run] = rest;
+        return ref("step", name, input, undefined, run, { readOnly: false, streaming: false });
+    }
+    const [run] = rest;
+    return ref("step", name, undefined, undefined, run, { readOnly: false, streaming: false });
+}
+export function action(name, ...rest) {
+    if (rest.length === 2) {
+        const [input, run] = rest;
+        return ref("action", name, input, undefined, run, { readOnly: false, streaming: false });
+    }
+    const [run] = rest;
+    return ref("action", name, undefined, undefined, run, { readOnly: false, streaming: false });
+}
+export function tool(name, description, input, run) {
+    if (typeof name !== "string" || name.trim() === "")
+        throw new TypeError("a tool needs a name");
+    if (typeof description !== "string" || description.trim() === "") {
+        throw new TypeError(`tool ${name}: a tool needs a description, or the model cannot choose it`);
+    }
+    return Object.freeze({ name, description, input, run });
+}
+export function guardrail(name, check) {
+    if (typeof name !== "string" || name.trim() === "")
+        throw new TypeError("a guardrail needs a name");
+    return Object.freeze({ name, check });
+}

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+export { VERSION } from "./version.ts";
+export { s, Done, done, SchemaError, toJsonSchema, defaultManifest, type Schema, type Infer } from "./schema.ts";
+export { jsonCodec, defaultCodecFor, codecForManifest, textCodecs, binaryCodecs, type Codec, type Shape, type ContentType } from "./codec.ts";
+export { EncodingError, DecodingError, renderDouble } from "./json.ts";
+export { Instant, Duration, LocalDate, LocalDateTime } from "./time.ts";
+export { ErrorCode, CommandError, Outcome, Retention, httpStatusOf, type ErrorDetail, type Metadata, type EffectLike, type ReadOnlyLike } from "./effects/common.ts";
+export { command, query, stream, step, action, tool, guardrail, type HandlerRef, type ToolRef, type GuardrailRef, type GuardrailStage, type HandlerTable } from "./handlers.ts";
+export { PersistBuilder, EventSourcedEffects, type PersistEffect, type ReadOnlyEffect, type EventSourcedEffect } from "./effects/eventSourced.ts";
+export { EventSourcedEntity, type EventSourcedEntityClass } from "./eventSourcedEntity.ts";
+export { UpdateBuilder, KeyValueEffects, type UpdateEffect, type KeyValueReadOnlyEffect, type KeyValueEffect } from "./effects/keyValue.ts";
+export { KeyValueEntity, type KeyValueEntityClass } from "./keyValueEntity.ts";
+export { WorkflowEffects, StepEffects, WorkflowUpdateBuilder, StepUpdateBuilder, workflowSettings, type WorkflowEffect, type WorkflowReadOnlyEffect, type WorkflowCommandEffect, type StepEffect, type StepOutcome, type StepRef, type PauseOptions, type WorkflowSettings, type StepSettings, type Recovery, } from "./effects/workflow.ts";
+export { Workflow, type WorkflowClass } from "./workflow.ts";
+export { ViewEffects, ConsumerEffects, TimedActionEffects, type ViewEffect, type ConsumerEffect, type TimedActionEffect } from "./effects/stateless.ts";
+export { View, type ViewClass } from "./view.ts";
+export { Consumer, type ConsumerClass } from "./consumer.ts";
+export { TimedAction, type TimedActionClass } from "./timedAction.ts";
+export { AgentEffects, type AgentEffect } from "./effects/agent.ts";
+export { Agent, type AgentClass } from "./agent.ts";
+export { Endpoint, type EndpointClass } from "./endpoint.ts";
+export { Acl, HttpProblem, get, post, put, patch, del, sse, type RouteRef, type RouteOptions, type RouteTable, type Params, type ParamNames, type HttpMethod } from "./routes.ts";
+export { type CommandContext, type RequestContext, type Principal, Query, Headers } from "./context.ts";
+export { ComponentClient, Calls, TypedCalls, Invocation, Views, Timers, type TimerTarget, type ComponentRef } from "./client.ts";
+export { Ankka, ServiceBuilder, Registry, RegistrationError, type ServiceOptions, type RegisteredComponent, type RegisteredEndpoint, type Source, type RegisteredEventSourced, type RegisteredKeyValue, type RegisteredWorkflow, type RegisteredView, type RegisteredConsumer, type RegisteredTimedAction, type RegisteredAgent, } from "./service.ts";
+export { Server, type ServerOptions } from "./server/server.ts";
+export { problems as sidecarProblems } from "./server/discovery.ts";
+export { PROTOCOL_VERSION, SDK_NAME } from "./spec.ts";
+export { materialiseEventSourced, materialiseKeyValue, materialiseWorkflowCommand, materialiseStep, type Materialised, type MaterialisedKeyValue, type MaterialisedWorkflowCommand, type MaterialisedStep, } from "./materialise.ts";
+export type { ComponentKind } from "./kinds.ts";

package/dist/index.js

@@ -0,0 +1,39 @@
+// The ankka SDK for TypeScript on Node.js. See https://docs.ankka.cloud/reference/typescript-sdk/.
+// The Node floor, checked before anything else is evaluated, so an old Node fails with a message that
+// names the version rather than a syntax error from a construct it lacks.
+{
+    const required = "22.22.0";
+    const [major, minor, patch] = process.versions.node.split(".").map(Number);
+    const [rMajor, rMinor, rPatch] = required.split(".").map(Number);
+    const ok = major > rMajor || (major === rMajor && (minor > rMinor || (minor === rMinor && patch >= rPatch)));
+    if (!ok)
+        throw new Error(`ankka needs Node.js ${required} or later; this is ${process.versions.node}`);
+}
+export { VERSION } from "./version.js";
+export { s, Done, done, SchemaError, toJsonSchema, defaultManifest } from "./schema.js";
+export { jsonCodec, defaultCodecFor, codecForManifest, textCodecs, binaryCodecs } from "./codec.js";
+export { EncodingError, DecodingError, renderDouble } from "./json.js";
+export { Instant, Duration, LocalDate, LocalDateTime } from "./time.js";
+export { ErrorCode, CommandError, Outcome, Retention, httpStatusOf } from "./effects/common.js";
+export { command, query, stream, step, action, tool, guardrail } from "./handlers.js";
+export { PersistBuilder, EventSourcedEffects } from "./effects/eventSourced.js";
+export { EventSourcedEntity } from "./eventSourcedEntity.js";
+export { UpdateBuilder, KeyValueEffects } from "./effects/keyValue.js";
+export { KeyValueEntity } from "./keyValueEntity.js";
+export { WorkflowEffects, StepEffects, WorkflowUpdateBuilder, StepUpdateBuilder, workflowSettings, } from "./effects/workflow.js";
+export { Workflow } from "./workflow.js";
+export { ViewEffects, ConsumerEffects, TimedActionEffects } from "./effects/stateless.js";
+export { View } from "./view.js";
+export { Consumer } from "./consumer.js";
+export { TimedAction } from "./timedAction.js";
+export { AgentEffects } from "./effects/agent.js";
+export { Agent } from "./agent.js";
+export { Endpoint } from "./endpoint.js";
+export { Acl, HttpProblem, get, post, put, patch, del, sse } from "./routes.js";
+export { Query, Headers } from "./context.js";
+export { ComponentClient, Calls, TypedCalls, Invocation, Views, Timers } from "./client.js";
+export { Ankka, ServiceBuilder, Registry, RegistrationError, } from "./service.js";
+export { Server } from "./server/server.js";
+export { problems as sidecarProblems } from "./server/discovery.js";
+export { PROTOCOL_VERSION, SDK_NAME } from "./spec.js";
+export { materialiseEventSourced, materialiseKeyValue, materialiseWorkflowCommand, materialiseStep, } from "./materialise.js";

package/dist/json.d.ts

@@ -0,0 +1,21 @@
+import { type Schema } from "./schema.ts";
+export declare class EncodingError extends Error {
+    constructor(message: string);
+}
+export declare class DecodingError extends Error {
+    /** Where in the document the refusal is, like `items[2].quantity`; empty at the top level. */
+    readonly path: string;
+    constructor(message: string, path: string);
+}
+/** `Double.toString` as Scala prints it: plain between 1e-3 and 1e7 with at least one fractional digit, scientific outside. */
+export declare function renderDouble(d: number): string;
+/** The JSON text for `value` under `schema`. */
+export declare function writeJson(schema: Schema, value: unknown): string;
+/** Decodes `text` under `schema`. Lenient on unknown fields and field order; strict on what is required. */
+export declare function readJson<T>(schema: Schema<T>, text: string): T;
+/** Applies the schema to a value `JSON.parse` produced (with the same reviver), for callers that hold parsed JSON. */
+export declare function decodeJsonValue<T>(schema: Schema<T>, raw: unknown): T;
+/** The reviver: an integer past 2⁵³ arrives as a `BigInt` made from its source text, everything else as usual. */
+export declare function reviver(this: unknown, _key: string, value: unknown, context?: {
+    source?: string;
+}): unknown;