ankka 0.6.0

package/dist/json.js

@@ -0,0 +1,362 @@
+// The JSON encoding, schema-directed, byte for byte what the Scala codecs write (protocol/ENCODING.md).
+//
+// Writing is the SDK's own: fields in declaration order, every field written, `null` for an absent
+// option, doubles rendered as `Double.toString` does (`1.0`, `1.0E10`), a `long` as digits however
+// large. `JSON.stringify` could do none of that. Reading is `JSON.parse` with the reviver's source-text
+// access (Node 21+) so an integer past 2⁵³ becomes a `BigInt` instead of a rounded number, followed by a
+// schema-directed decode that converts, checks and names the path of anything it refuses.
+import { Duration, Instant, LocalDate, LocalDateTime } from "./time.js";
+import { done, resolve, describe } from "./schema.js";
+export class EncodingError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "EncodingError";
+    }
+}
+export class DecodingError extends Error {
+    /** Where in the document the refusal is, like `items[2].quantity`; empty at the top level. */
+    path;
+    constructor(message, path) {
+        super(path ? `${path}: ${message}` : message);
+        this.name = "DecodingError";
+        this.path = path;
+    }
+}
+/** `Double.toString` as Scala prints it: plain between 1e-3 and 1e7 with at least one fractional digit, scientific outside. */
+export function renderDouble(d) {
+    if (!Number.isFinite(d))
+        throw new EncodingError("NaN and infinities are not JSON");
+    if (d === 0)
+        return Object.is(d, -0) ? "-0.0" : "0.0";
+    const magnitude = Math.abs(d);
+    if (magnitude >= 1e-3 && magnitude < 1e7) {
+        const plain = String(d);
+        if (plain.includes("e"))
+            return fromExponential(d); // not reachable in this range for finite doubles, kept for safety
+        return plain.includes(".") ? plain : plain + ".0";
+    }
+    return fromExponential(d);
+}
+function fromExponential(d) {
+    const [mantissa, exponent] = d.toExponential().split("e");
+    const m = mantissa.includes(".") ? mantissa : mantissa + ".0";
+    return `${m}E${Number(exponent)}`;
+}
+function base64Encode(bytes) {
+    return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString("base64");
+}
+function base64Decode(text) {
+    return new Uint8Array(Buffer.from(text, "base64"));
+}
+/** The JSON text for `value` under `schema`. */
+export function writeJson(schema, value) {
+    const out = [];
+    write(schema, value, out, "");
+    return out.join("");
+}
+function write(schema, value, out, path) {
+    const r = resolve(schema);
+    switch (r.kind) {
+        case "string":
+            if (typeof value !== "string")
+                throw new EncodingError(`${at(path)}expected a string, got ${kindOf(value)}`);
+            out.push(JSON.stringify(value));
+            return;
+        case "int":
+            if (typeof value === "bigint" && value >= BigInt(Number.MIN_SAFE_INTEGER) && value <= BigInt(Number.MAX_SAFE_INTEGER)) {
+                out.push(value.toString());
+                return;
+            }
+            if (typeof value !== "number" || !Number.isSafeInteger(value)) {
+                throw new EncodingError(`${at(path)}expected a whole number within ±2^53 for int, got ${kindOf(value)}`);
+            }
+            out.push(String(value));
+            return;
+        case "long":
+            if (typeof value === "bigint") {
+                out.push(value.toString());
+                return;
+            }
+            if (typeof value === "number" && Number.isSafeInteger(value)) {
+                out.push(String(value));
+                return;
+            }
+            throw new EncodingError(`${at(path)}expected a bigint (or a safe integer) for long, got ${kindOf(value)}`);
+        case "double":
+            if (typeof value === "bigint") {
+                out.push(renderDouble(Number(value)));
+                return;
+            }
+            if (typeof value !== "number")
+                throw new EncodingError(`${at(path)}expected a number for double, got ${kindOf(value)}`);
+            out.push(renderDouble(value));
+            return;
+        case "boolean":
+            if (typeof value !== "boolean")
+                throw new EncodingError(`${at(path)}expected a boolean, got ${kindOf(value)}`);
+            out.push(value ? "true" : "false");
+            return;
+        case "instant": {
+            const instant = value instanceof Instant ? value : value instanceof Date ? Instant.fromDate(value) : undefined;
+            if (!instant)
+                throw new EncodingError(`${at(path)}expected an Instant (or a Date), got ${kindOf(value)}`);
+            out.push(JSON.stringify(instant.toString()));
+            return;
+        }
+        case "duration":
+            if (!(value instanceof Duration))
+                throw new EncodingError(`${at(path)}expected a Duration, got ${kindOf(value)}`);
+            out.push(JSON.stringify(value.toString()));
+            return;
+        case "localDate":
+            if (!(value instanceof LocalDate))
+                throw new EncodingError(`${at(path)}expected a LocalDate, got ${kindOf(value)}`);
+            out.push(JSON.stringify(value.toString()));
+            return;
+        case "localDateTime":
+            if (!(value instanceof LocalDateTime))
+                throw new EncodingError(`${at(path)}expected a LocalDateTime, got ${kindOf(value)}`);
+            out.push(JSON.stringify(value.toString()));
+            return;
+        case "bytes":
+            if (!(value instanceof Uint8Array))
+                throw new EncodingError(`${at(path)}expected a Uint8Array, got ${kindOf(value)}`);
+            out.push(JSON.stringify(base64Encode(value)));
+            return;
+        case "unit":
+        case "done":
+            out.push("null");
+            return;
+        case "option":
+            if (value === null || value === undefined)
+                out.push("null");
+            else
+                write(r.inner, value, out, path);
+            return;
+        case "list": {
+            if (!Array.isArray(value))
+                throw new EncodingError(`${at(path)}expected an array, got ${kindOf(value)}`);
+            out.push("[");
+            value.forEach((item, i) => {
+                if (i > 0)
+                    out.push(",");
+                write(r.inner, item, out, `${path}[${i}]`);
+            });
+            out.push("]");
+            return;
+        }
+        case "stringMap": {
+            if (!isPlainObject(value))
+                throw new EncodingError(`${at(path)}expected an object for a string-keyed map, got ${kindOf(value)}`);
+            out.push("{");
+            let first = true;
+            for (const [k, v] of Object.entries(value)) {
+                if (!first)
+                    out.push(",");
+                first = false;
+                out.push(JSON.stringify(k), ":");
+                write(r.inner, v, out, path ? `${path}.${k}` : k);
+            }
+            out.push("}");
+            return;
+        }
+        case "record": {
+            if (!isPlainObject(value))
+                throw new EncodingError(`${at(path)}expected an object for ${describe(r)}, got ${kindOf(value)}`);
+            out.push("{");
+            writeFields(r.fields, value, out, path, false);
+            out.push("}");
+            return;
+        }
+        case "sumType": {
+            if (!isPlainObject(value) || typeof value["type"] !== "string") {
+                throw new EncodingError(`${at(path)}expected an object with a "type" for ${describe(r)}, got ${kindOf(value)}`);
+            }
+            const caseName = value["type"];
+            const fields = r.cases[caseName];
+            if (!fields)
+                throw new EncodingError(`${at(path)}${describe(r)} has no case ${JSON.stringify(caseName)}`);
+            out.push("{", JSON.stringify("type"), ":", JSON.stringify(caseName));
+            writeFields(fields, value, out, path, true);
+            out.push("}");
+            return;
+        }
+        case "enumeration": {
+            if (typeof value !== "string" || !r.values.includes(value)) {
+                throw new EncodingError(`${at(path)}expected one of ${r.values.map((v) => JSON.stringify(v)).join(", ")} for ${describe(r)}, got ${kindOf(value)}`);
+            }
+            out.push(`{"type":${JSON.stringify(value)}}`);
+            return;
+        }
+    }
+}
+function writeFields(fields, value, out, path, continuing) {
+    let first = !continuing;
+    for (const [name, field] of Object.entries(fields)) {
+        if (!first)
+            out.push(",");
+        first = false;
+        out.push(JSON.stringify(name), ":");
+        const v = value[name];
+        if (v === undefined && resolve(field).kind !== "option") {
+            throw new EncodingError(`${at(path ? `${path}.${name}` : name)}missing required field`);
+        }
+        write(field, v, out, path ? `${path}.${name}` : name);
+    }
+}
+/** Decodes `text` under `schema`. Lenient on unknown fields and field order; strict on what is required. */
+export function readJson(schema, text) {
+    let raw;
+    try {
+        raw = JSON.parse(text, reviver);
+    }
+    catch (e) {
+        throw new DecodingError(`not JSON: ${e.message}`, "");
+    }
+    return decode(schema, raw, "");
+}
+/** Applies the schema to a value `JSON.parse` produced (with the same reviver), for callers that hold parsed JSON. */
+export function decodeJsonValue(schema, raw) {
+    return decode(schema, raw, "");
+}
+/** The reviver: an integer past 2⁵³ arrives as a `BigInt` made from its source text, everything else as usual. */
+export function reviver(_key, value, context) {
+    if (typeof value === "number" && Number.isInteger(value) && !Number.isSafeInteger(value)) {
+        const source = context?.source;
+        if (source && /^-?\d+$/.test(source))
+            return BigInt(source);
+    }
+    return value;
+}
+function decode(schema, raw, path) {
+    const r = resolve(schema);
+    switch (r.kind) {
+        case "string":
+            if (typeof raw !== "string")
+                throw new DecodingError(`expected a string, got ${kindOf(raw)}`, path);
+            return raw;
+        case "int":
+            if (typeof raw === "bigint") {
+                if (raw < BigInt(Number.MIN_SAFE_INTEGER) || raw > BigInt(Number.MAX_SAFE_INTEGER)) {
+                    throw new DecodingError(`${raw} does not fit an int (declare the field as long)`, path);
+                }
+                return Number(raw);
+            }
+            if (typeof raw !== "number" || !Number.isInteger(raw))
+                throw new DecodingError(`expected a whole number, got ${kindOf(raw)}`, path);
+            return raw;
+        case "long":
+            if (typeof raw === "bigint")
+                return raw;
+            if (typeof raw === "number" && Number.isInteger(raw))
+                return BigInt(raw);
+            throw new DecodingError(`expected a whole number, got ${kindOf(raw)}`, path);
+        case "double":
+            if (typeof raw === "bigint")
+                return Number(raw);
+            if (typeof raw !== "number")
+                throw new DecodingError(`expected a number, got ${kindOf(raw)}`, path);
+            return raw;
+        case "boolean":
+            if (typeof raw !== "boolean")
+                throw new DecodingError(`expected a boolean, got ${kindOf(raw)}`, path);
+            return raw;
+        case "instant":
+            return parseWith(raw, path, "an ISO-8601 instant", Instant.parse);
+        case "duration":
+            return parseWith(raw, path, "an ISO-8601 duration", Duration.parse);
+        case "localDate":
+            return parseWith(raw, path, "an ISO-8601 date", LocalDate.parse);
+        case "localDateTime":
+            return parseWith(raw, path, "an ISO-8601 date-time", LocalDateTime.parse);
+        case "bytes":
+            if (typeof raw !== "string")
+                throw new DecodingError(`expected base64 text, got ${kindOf(raw)}`, path);
+            return base64Decode(raw);
+        case "unit":
+            return undefined;
+        case "done":
+            return done;
+        case "option":
+            return raw === null || raw === undefined ? null : decode(r.inner, raw, path);
+        case "list":
+            if (!Array.isArray(raw))
+                throw new DecodingError(`expected an array, got ${kindOf(raw)}`, path);
+            return raw.map((item, i) => decode(r.inner, item, `${path}[${i}]`));
+        case "stringMap": {
+            if (!isPlainObject(raw))
+                throw new DecodingError(`expected an object, got ${kindOf(raw)}`, path);
+            const out = {};
+            for (const [k, v] of Object.entries(raw))
+                out[k] = decode(r.inner, v, path ? `${path}.${k}` : k);
+            return out;
+        }
+        case "record": {
+            if (!isPlainObject(raw))
+                throw new DecodingError(`expected an object for ${describe(r)}, got ${kindOf(raw)}`, path);
+            return decodeFields(r.fields, raw, path);
+        }
+        case "sumType": {
+            if (!isPlainObject(raw))
+                throw new DecodingError(`expected an object for ${describe(r)}, got ${kindOf(raw)}`, path);
+            const caseName = raw["type"];
+            if (typeof caseName !== "string")
+                throw new DecodingError(`${describe(r)} needs a "type"`, path);
+            const fields = r.cases[caseName];
+            if (!fields)
+                throw new DecodingError(`${describe(r)} has no case ${JSON.stringify(caseName)}`, path);
+            return { type: caseName, ...decodeFields(fields, raw, path) };
+        }
+        case "enumeration": {
+            const name = typeof raw === "string" ? raw : isPlainObject(raw) ? raw["type"] : undefined;
+            if (typeof name !== "string" || !r.values.includes(name)) {
+                throw new DecodingError(`expected one of ${r.values.map((v) => JSON.stringify(v)).join(", ")} for ${describe(r)}, got ${JSON.stringify(raw)}`, path);
+            }
+            return name;
+        }
+    }
+}
+function decodeFields(fields, raw, path) {
+    const out = {};
+    for (const [name, field] of Object.entries(fields)) {
+        const fieldPath = path ? `${path}.${name}` : name;
+        const v = raw[name];
+        if (v === undefined) {
+            if (resolve(field).kind === "option")
+                out[name] = null;
+            else
+                throw new DecodingError("missing required field", fieldPath);
+        }
+        else {
+            out[name] = decode(field, v, fieldPath);
+        }
+    }
+    return out;
+}
+function parseWith(raw, path, what, parse) {
+    if (typeof raw !== "string")
+        throw new DecodingError(`expected ${what}, got ${kindOf(raw)}`, path);
+    try {
+        return parse(raw);
+    }
+    catch (e) {
+        throw new DecodingError(e.message, path);
+    }
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function kindOf(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "an array";
+    if (value instanceof Uint8Array)
+        return "bytes";
+    if (typeof value === "object")
+        return "an object";
+    return typeof value === "bigint" ? "a bigint" : `${/^[aeiou]/.test(typeof value) ? "an" : "a"} ${typeof value}`;
+}
+function at(path) {
+    return path ? `${path}: ` : "";
+}

package/dist/keyValueEntity.d.ts

@@ -0,0 +1,29 @@
+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 { KeyValueEffects } from "./effects/keyValue.ts";
+export declare abstract class KeyValueEntity<S> {
+    #private;
+    readonly effects: KeyValueEffects<S>;
+    get state(): S;
+    get entityId(): string;
+    get context(): CommandContext;
+    get client(): ComponentClient;
+    /** @internal */
+    get _kind(): "key-value";
+    /** The state of an instance that has never been written. `this.entityId` is available here. */
+    abstract emptyState(): S;
+    /** @internal */
+    _bindInstance(entityId: string): void;
+    /** @internal */
+    _bindCommand(state: S, context: CommandContext, client: ComponentClient): void;
+    /** @internal */
+    _unbindCommand(): void;
+}
+export interface KeyValueEntityClass<S = unknown, C extends KeyValueEntity<S> = KeyValueEntity<S>> {
+    new (): C;
+    readonly componentId: string;
+    readonly state: Shape<S>;
+    readonly handlers: HandlerTable<C>;
+}

package/dist/keyValueEntity.js

@@ -0,0 +1,52 @@
+// A key value entity: one durable state per instance, replaced whole by `updateState`.
+import { KeyValueEffects } from "./effects/keyValue.js";
+export class KeyValueEntity {
+    effects = new KeyValueEffects();
+    #state;
+    #entityId;
+    #context;
+    #client;
+    #bound = false;
+    get state() {
+        if (!this.#bound)
+            throw new Error("state is only available inside a command handler");
+        return this.#state;
+    }
+    get entityId() {
+        if (this.#entityId === undefined)
+            throw new Error("entityId is only available once the entity is bound to an instance");
+        return this.#entityId;
+    }
+    get context() {
+        if (!this.#context)
+            throw new Error("context is only available inside a command handler");
+        return this.#context;
+    }
+    get client() {
+        if (!this.#client)
+            throw new Error("client is only available inside a command handler");
+        return this.#client;
+    }
+    /** @internal */
+    get _kind() {
+        return "key-value";
+    }
+    /** @internal */
+    _bindInstance(entityId) {
+        this.#entityId = entityId;
+    }
+    /** @internal */
+    _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/kinds.d.ts

@@ -0,0 +1,8 @@
+import { Kind as ProtoKind } from "./_proto/ankka/protocol/v1/discovery_pb.ts";
+import { ErrorCode as ProtoErrorCode } from "./_proto/ankka/protocol/v1/payload_pb.ts";
+import { ErrorCode } from "./effects/common.ts";
+export type ComponentKind = "event-sourced" | "key-value" | "workflow" | "view" | "consumer" | "timed-action" | "agent";
+export declare function kindToProto(kind: ComponentKind): ProtoKind;
+export declare function kindFromProto(kind: ProtoKind): ComponentKind;
+export declare function errorCodeToProto(code: ErrorCode): ProtoErrorCode;
+export declare function errorCodeFromProto(code: ProtoErrorCode): ErrorCode;

package/dist/kinds.js

@@ -0,0 +1,41 @@
+// The component kinds, and the mappings between the SDK's words and the protocol's numbers.
+import { Kind as ProtoKind } from "./_proto/ankka/protocol/v1/discovery_pb.js";
+import { ErrorCode as ProtoErrorCode } from "./_proto/ankka/protocol/v1/payload_pb.js";
+import { ErrorCode } from "./effects/common.js";
+const KIND_TO_PROTO = Object.freeze({
+    "event-sourced": ProtoKind.EVENT_SOURCED_ENTITY,
+    "key-value": ProtoKind.KEY_VALUE_ENTITY,
+    workflow: ProtoKind.WORKFLOW,
+    view: ProtoKind.VIEW,
+    consumer: ProtoKind.CONSUMER,
+    "timed-action": ProtoKind.TIMED_ACTION,
+    agent: ProtoKind.AGENT,
+});
+export function kindToProto(kind) {
+    return KIND_TO_PROTO[kind];
+}
+export function kindFromProto(kind) {
+    for (const [k, v] of Object.entries(KIND_TO_PROTO))
+        if (v === kind)
+            return k;
+    throw new RangeError(`unknown component kind ${kind}`);
+}
+const CODE_TO_PROTO = Object.freeze({
+    INTERNAL: ProtoErrorCode.INTERNAL,
+    BAD_REQUEST: ProtoErrorCode.BAD_REQUEST,
+    UNAUTHORIZED: ProtoErrorCode.UNAUTHORIZED,
+    FORBIDDEN: ProtoErrorCode.FORBIDDEN,
+    NOT_FOUND: ProtoErrorCode.NOT_FOUND,
+    CONFLICT: ProtoErrorCode.CONFLICT,
+    TIMEOUT: ProtoErrorCode.TIMEOUT,
+    UNAVAILABLE: ProtoErrorCode.UNAVAILABLE,
+});
+export function errorCodeToProto(code) {
+    return CODE_TO_PROTO[code];
+}
+export function errorCodeFromProto(code) {
+    for (const [k, v] of Object.entries(CODE_TO_PROTO))
+        if (v === code)
+            return k;
+    return ErrorCode.Internal;
+}

package/dist/materialise.d.ts

@@ -0,0 +1,33 @@
+import type { ErrorDetail, Retention } from "./effects/common.ts";
+import type { EventSourcedEffect } from "./effects/eventSourced.ts";
+import type { KeyValueEffect } from "./effects/keyValue.ts";
+import type { StepEffect, StepOutcome, StepRef, WorkflowCommandEffect } from "./effects/workflow.ts";
+/** What an effect amounts to, as values a test can assert on and the server can encode. */
+export interface Materialised<S, E, R> {
+    readonly events: readonly E[];
+    readonly newState: S;
+    readonly retention: Retention | null;
+    /** The reply, when the outcome was a reply. */
+    readonly reply: R | undefined;
+    /** The refusal, when the outcome was one. */
+    readonly error: ErrorDetail | undefined;
+    /** True when the handler answered nothing. */
+    readonly noReply: boolean;
+}
+export declare function materialiseEventSourced<S, E, R>(effect: EventSourcedEffect<S, E, R>, state: S, applyEvent: (state: S, event: E) => S): Materialised<S, E, R>;
+/** A key value effect: `newState` is the state to keep (unchanged when the effect only replied or deleted). `changed` says whether to send it. */
+export interface MaterialisedKeyValue<S, R> extends Materialised<S, never, R> {
+    readonly changed: boolean;
+}
+export declare function materialiseKeyValue<S, R>(effect: KeyValueEffect<S, R>, state: S): MaterialisedKeyValue<S, R>;
+export interface MaterialisedWorkflowCommand<S, R> extends Materialised<S, never, R> {
+    readonly changed: boolean;
+    readonly transition: StepRef | null;
+}
+export declare function materialiseWorkflowCommand<S, R>(effect: WorkflowCommandEffect<S, R>, state: S): MaterialisedWorkflowCommand<S, R>;
+export interface MaterialisedStep<S> {
+    readonly newState: S;
+    readonly changed: boolean;
+    readonly next: StepOutcome;
+}
+export declare function materialiseStep<S>(effect: StepEffect<S>, state: S): MaterialisedStep<S>;

package/dist/materialise.js

@@ -0,0 +1,55 @@
+// One reduction per kind, shared by the server and the unit testkit, so a test and a deployment cannot
+// disagree about what an effect means. This is the SDK's copy of the rule that puts
+// `EventSourcedEffect.materialise` in `modules/core`: the reply is computed from the state *after* the
+// events, and a refusal leaves everything as it was.
+function outcomeOf(outcome, state) {
+    switch (outcome.kind) {
+        case "reply":
+            return { reply: outcome.compute(state), error: undefined, noReply: false };
+        case "no-reply":
+            return { reply: undefined, error: undefined, noReply: true };
+        case "fail":
+            return { reply: undefined, error: outcome.error, noReply: false };
+    }
+}
+export function materialiseEventSourced(effect, state, applyEvent) {
+    switch (effect.kind) {
+        case "persist": {
+            const after = effect.events.reduce(applyEvent, state);
+            return Object.freeze({ events: effect.events, newState: after, retention: effect.retention, ...outcomeOf(effect.outcome, after) });
+        }
+        case "read-only":
+            return Object.freeze({ events: [], newState: state, retention: effect.retention, ...outcomeOf(effect.outcome, state) });
+        default:
+            throw new TypeError(`not an event sourced effect: ${JSON.stringify(effect.kind)}`);
+    }
+}
+export function materialiseKeyValue(effect, state) {
+    switch (effect.kind) {
+        case "update": {
+            const after = effect.newState === null ? state : effect.newState;
+            return Object.freeze({ events: [], newState: after, changed: effect.newState !== null, retention: effect.retention, ...outcomeOf(effect.outcome, after) });
+        }
+        case "read-only":
+            return Object.freeze({ events: [], newState: state, changed: false, retention: null, ...outcomeOf(effect.outcome, state) });
+        default:
+            throw new TypeError(`not a key value effect: ${JSON.stringify(effect.kind)}`);
+    }
+}
+export function materialiseWorkflowCommand(effect, state) {
+    switch (effect.kind) {
+        case "workflow": {
+            const after = effect.newState === null ? state : effect.newState;
+            return Object.freeze({ events: [], newState: after, changed: effect.newState !== null, transition: effect.transition, retention: null, ...outcomeOf(effect.outcome, after) });
+        }
+        case "read-only":
+            return Object.freeze({ events: [], newState: state, changed: false, transition: null, retention: null, ...outcomeOf(effect.outcome, state) });
+        default:
+            throw new TypeError(`not a workflow effect: ${JSON.stringify(effect.kind)}`);
+    }
+}
+export function materialiseStep(effect, state) {
+    if (effect.kind !== "step")
+        throw new TypeError(`not a step effect: ${JSON.stringify(effect.kind)}`);
+    return Object.freeze({ newState: effect.newState === null ? state : effect.newState, changed: effect.newState !== null, next: effect.next });
+}

package/dist/routes.d.ts

@@ -0,0 +1,71 @@
+import type { Shape } from "./codec.ts";
+import type { RequestContext } from "./context.ts";
+import type { Infer, Schema } from "./schema.ts";
+/** Who may call: everyone, no one, or authenticated callers only. There is no default. */
+export declare const Acl: Readonly<{
+    readonly allowAll: "allow-all";
+    readonly denyAll: "deny-all";
+    readonly authenticated: "authenticated";
+}>;
+export type Acl = (typeof Acl)[keyof typeof Acl];
+/** Thrown from a route handler to answer a status other than 200 with a plain-text message. */
+export declare class HttpProblem extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+export type HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+type MaybePromise<T> = T | Promise<T>;
+/** The parameter names in a template: `ParamNames<"/{cartId}/items/{productId}">` is `"cartId" | "productId"`. */
+export type ParamNames<T extends string> = T extends `${string}{${infer P}}${infer Rest}` ? P | ParamNames<Rest> : never;
+/** The typed parameters of a template, each a `string` unless `params` narrows it with a schema. */
+export type Params<T extends string, PS> = {
+    readonly [K in ParamNames<T>]: K extends keyof PS ? Infer<PS[K]> : string;
+};
+/** Options on a route: an access rule for this route alone, and schemas narrowing path parameters. */
+export interface RouteOptions<PS extends Readonly<Record<string, Schema>> = {}> {
+    readonly acl?: Acl;
+    readonly params?: PS;
+}
+/** One entry of an endpoint's `routes` table. */
+export interface RouteRef<Ep = unknown, P = unknown, B = unknown, R = unknown> {
+    readonly method: HttpMethod;
+    /** As declared: `/{cartId}/items`, relative to the endpoint's prefix. */
+    readonly template: string;
+    /** Parameter names in template order. */
+    readonly paramNames: readonly string[];
+    /** Schemas narrowing parameters; a parameter not named here is a string. */
+    readonly paramShapes: Readonly<Record<string, Schema>>;
+    readonly body: Shape<B> | undefined;
+    readonly reply: Shape<R> | undefined;
+    readonly streaming: boolean;
+    readonly acl: Acl | undefined;
+    readonly run: (self: Ep, request: RequestContext<P>, body: B) => MaybePromise<R> | AsyncIterable<string>;
+}
+export declare function parseTemplate(template: string): string[];
+type NoBodyRun<Ep, T extends string, PS, R> = (self: Ep, request: RequestContext<Params<T, PS>>) => MaybePromise<R>;
+type BodyRun<Ep, T extends string, PS, B, R> = (self: Ep, request: RequestContext<Params<T, PS>>, body: B) => MaybePromise<R>;
+/** A GET route: `get("/{cartId}", ShoppingCart, (ep: CartEndpoint, req) => ep.getCart(req.params.cartId))`. */
+export declare function get<Ep, T extends string, R, PS extends Readonly<Record<string, Schema>> = {}>(template: T, reply: Shape<R>, run: NoBodyRun<Ep, T, PS, R>, options?: RouteOptions<PS>): RouteRef<Ep, Params<T, PS>, undefined, R>;
+/** A POST route, with a body (`post(template, Body, Reply, run)`) or without (`post(template, Reply, run)`). */
+export declare const post: {
+    <Ep, T extends string, B, R, PS extends Readonly<Record<string, Schema>> = {}>(template: T, body: Shape<B>, reply: Shape<R>, run: BodyRun<Ep, T, PS, B, R>, options?: RouteOptions<PS>): RouteRef<Ep, Params<T, PS>, B, R>;
+    <Ep, T extends string, R, PS extends Readonly<Record<string, Schema>> = {}>(template: T, reply: Shape<R>, run: NoBodyRun<Ep, T, PS, R>, options?: RouteOptions<PS>): RouteRef<Ep, Params<T, PS>, undefined, R>;
+};
+export declare const put: {
+    <Ep, T extends string, B, R, PS extends Readonly<Record<string, Schema>> = {}>(template: T, body: Shape<B>, reply: Shape<R>, run: BodyRun<Ep, T, PS, B, R>, options?: RouteOptions<PS>): RouteRef<Ep, Params<T, PS>, B, R>;
+    <Ep, T extends string, R, PS extends Readonly<Record<string, Schema>> = {}>(template: T, reply: Shape<R>, run: NoBodyRun<Ep, T, PS, R>, options?: RouteOptions<PS>): RouteRef<Ep, Params<T, PS>, undefined, R>;
+};
+export declare const patch: {
+    <Ep, T extends string, B, R, PS extends Readonly<Record<string, Schema>> = {}>(template: T, body: Shape<B>, reply: Shape<R>, run: BodyRun<Ep, T, PS, B, R>, options?: RouteOptions<PS>): RouteRef<Ep, Params<T, PS>, B, R>;
+    <Ep, T extends string, R, PS extends Readonly<Record<string, Schema>> = {}>(template: T, reply: Shape<R>, run: NoBodyRun<Ep, T, PS, R>, options?: RouteOptions<PS>): RouteRef<Ep, Params<T, PS>, undefined, R>;
+};
+/** A DELETE route; `delete` is a reserved word, so `del`. */
+export declare const del: {
+    <Ep, T extends string, B, R, PS extends Readonly<Record<string, Schema>> = {}>(template: T, body: Shape<B>, reply: Shape<R>, run: BodyRun<Ep, T, PS, B, R>, options?: RouteOptions<PS>): RouteRef<Ep, Params<T, PS>, B, R>;
+    <Ep, T extends string, R, PS extends Readonly<Record<string, Schema>> = {}>(template: T, reply: Shape<R>, run: NoBodyRun<Ep, T, PS, R>, options?: RouteOptions<PS>): RouteRef<Ep, Params<T, PS>, undefined, R>;
+};
+/** A server-sent-events route: the handler returns an `AsyncIterable<string>`, one frame per string. */
+export declare function sse<Ep, T extends string, PS extends Readonly<Record<string, Schema>> = {}>(template: T, run: (self: Ep, request: RequestContext<Params<T, PS>>) => AsyncIterable<string> | Promise<AsyncIterable<string>>, options?: RouteOptions<PS>): RouteRef<Ep, Params<T, PS>, undefined, never>;
+/** The routes table type an endpoint declares. */
+export type RouteTable<Ep> = Readonly<Record<string, RouteRef<Ep, any, any, any>>>;
+export {};