ankka 0.9.1 → 0.11.0

package/dist/effects/keyed.js

@@ -0,0 +1,41 @@
+// Effects for a keyed view: the rows one change writes and deletes, each named by its key.
+function rows(changes) {
+    return Object.freeze({ kind: "rows", changes: Object.freeze([...changes]) });
+}
+function checkedKey(key) {
+    if (typeof key !== "string" || key === "")
+        throw new TypeError("a row key is a string of one character or more");
+    return key;
+}
+export class KeyedViewEffects {
+    updateRow(key, row) {
+        return rows([{ key: checkedKey(key), row }]);
+    }
+    deleteRow(key) {
+        return rows([{ key: checkedKey(key), deleted: true }]);
+    }
+    /** Several rows written, each under its key. */
+    updateRows(entries) {
+        return rows([...entries].map(([key, row]) => ({ key: checkedKey(key), row })));
+    }
+    deleteRows(keys) {
+        return rows([...keys].map((key) => ({ key: checkedKey(key), deleted: true })));
+    }
+    ignore() {
+        return rows([]);
+    }
+    /** Several effects as one, in the order given. */
+    all(...effects) {
+        return rows(effects.flatMap((e) => e.changes));
+    }
+}
+/**
+ * The final change for each key, a later change to a key winning, keys in the order they first
+ * appear; `undefined` is a deletion. How the test kit applies an effect, as the runtime does.
+ */
+export function reduceRowChanges(changes) {
+    const last = new Map();
+    for (const change of changes)
+        last.set(change.key, "deleted" in change ? undefined : change.row);
+    return [...last.entries()];
+}

package/dist/effects/stateless.d.ts

@@ -12,10 +12,25 @@ export declare class ViewEffects<Row> {
     deleteRow(): ViewEffect<Row>;
     ignore(): ViewEffect<Row>;
 }
+/**
+ * One message of several: what to publish, optionally the record key it is published under, and its
+ * headers. A message with no key is keyed by its subject — the source instance's id unless the
+ * metadata sets `ce-subject` — which keeps everything about one instance on one partition, in order.
+ * A key is for a message about something else: a line item, an element of a graph. Naming one does
+ * not change the subject.
+ */
+export interface OutgoingMessage<Out> {
+    readonly payload: Out;
+    readonly key?: string;
+    readonly metadata?: Metadata;
+}
 export type ConsumerEffect<Out> = ({
     readonly kind: "produce";
     readonly payload: Out;
     readonly metadata: Metadata;
+} & EffectLike<never>) | ({
+    readonly kind: "produceAll";
+    readonly messages: readonly OutgoingMessage<Out>[];
 } & EffectLike<never>) | ({
     readonly kind: "done";
 } & EffectLike<never>) | ({
@@ -24,6 +39,12 @@ export type ConsumerEffect<Out> = ({
 export declare class ConsumerEffects<Out> {
     /** Produce onward to the topic the consumer declares in `producesTo`. */
     produce(payload: Out, metadata?: Metadata): ConsumerEffect<Out>;
+    /**
+     * Produce several messages for this change, in the order given. The change is handled when the
+     * broker has accepted every one; if one is refused the change comes again and all are published
+     * again. An empty list publishes nothing and is handled at once.
+     */
+    produceAll(messages: readonly OutgoingMessage<Out>[]): ConsumerEffect<Out>;
     done(): ConsumerEffect<Out>;
     ignore(): ConsumerEffect<Out>;
 }

package/dist/effects/stateless.js

@@ -17,6 +17,25 @@ export class ConsumerEffects {
     produce(payload, metadata = {}) {
         return Object.freeze({ kind: "produce", payload, metadata });
     }
+    /**
+     * Produce several messages for this change, in the order given. The change is handled when the
+     * broker has accepted every one; if one is refused the change comes again and all are published
+     * again. An empty list publishes nothing and is handled at once.
+     */
+    produceAll(messages) {
+        if (!Array.isArray(messages))
+            throw new TypeError("produceAll takes a list of messages");
+        const checked = messages.map((m, i) => {
+            if (typeof m !== "object" || m === null || !("payload" in m))
+                throw new TypeError(`produceAll: message ${i} is not a message: { payload, key?, metadata? }`);
+            if (m.key !== undefined && typeof m.key !== "string")
+                throw new TypeError(`produceAll: message ${i} has a record key that is not a string`);
+            if (m.key === "")
+                throw new TypeError(`produceAll: message ${i} has an empty record key; leave the key out to key the message by its subject`);
+            return Object.freeze({ ...m });
+        });
+        return Object.freeze({ kind: "produceAll", messages: Object.freeze(checked) });
+    }
     done() {
         return Object.freeze({ kind: "done" });
     }

package/dist/endpoint.d.ts

@@ -1,12 +1,21 @@
-import type { ComponentClient } from "./client.ts";
+import { type ComponentClient, type Secrets } from "./client.ts";
 import { type RequestContext } from "./context.ts";
 import type { Acl, RouteTable } from "./routes.ts";
+import { type Services } from "./services.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;
+    /** The service's secret store: values kept encrypted in the service's own database, never in a journal or a view. */
+    get secrets(): Secrets;
+    /** A unit test's store in place of the runtime's: `component.secrets = new InMemorySecrets()`. */
+    set secrets(store: Secrets);
+    /** Other services, called as this one, through the runtime: `this.services.service("orders")`. */
+    get services(): Services;
+    /** A unit test's in place of the runtime's: `component.services = new ScriptedServices()`. */
+    set services(services: Services);
     /** @internal */
     _bindClient(client: ComponentClient | undefined): void;
 }

package/dist/endpoint.js

@@ -8,7 +8,9 @@
 //     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 { secretsFor } from "./client.js";
 import { currentRequest, requestIfAny } from "./context.js";
+import { servicesFor } from "./services.js";
 export class Endpoint {
     #client;
     /** The request being handled: path parameters, query, headers, principal. Request-scoped. */
@@ -22,6 +24,24 @@ export class Endpoint {
         const request = requestIfAny();
         return request ? this.#client.withMetadata(request.metadata) : this.#client;
     }
+    #secrets;
+    /** The service's secret store: values kept encrypted in the service's own database, never in a journal or a view. */
+    get secrets() {
+        return this.#secrets ?? secretsFor(this.client);
+    }
+    /** A unit test's store in place of the runtime's: `component.secrets = new InMemorySecrets()`. */
+    set secrets(store) {
+        this.#secrets = store;
+    }
+    #services;
+    /** Other services, called as this one, through the runtime: `this.services.service("orders")`. */
+    get services() {
+        return this.#services ?? servicesFor(this.client);
+    }
+    /** A unit test's in place of the runtime's: `component.services = new ScriptedServices()`. */
+    set services(services) {
+        this.#services = services;
+    }
     /** @internal */
     _bindClient(client) {
         this.#client = client;

package/dist/graph.d.ts

@@ -0,0 +1,171 @@
+import type { StartFrom } from "./startFrom.ts";
+import { type Codec, type Shape } from "./codec.ts";
+import type { EffectLike, Metadata } from "./effects/common.ts";
+import { type ComponentClient, type ComponentRef, type Secrets } from "./client.ts";
+import { type Services } from "./services.ts";
+type MaybePromise<T> = T | Promise<T>;
+/** The contract's name: the manifest and the `ce-type` of every delta. */
+export declare const GRAPH_DELTA_SCHEMA = "ankka.graph-delta.v1";
+/** The record key of every delta for the node `id`. */
+export declare function nodeKey(id: string): string;
+/** The record key of every delta for the edge `id`. Nodes and edges are separate id spaces. */
+export declare function edgeKey(id: string): string;
+/** A property's scalar: an integral `number` must be a safe integer; a larger integer is a `bigint`. */
+export type Scalar = string | boolean | number | bigint;
+/** A scalar, or a non-empty list of scalars of one kind. */
+export type PropertyValue = Scalar | readonly Scalar[];
+export type Properties = Readonly<Record<string, PropertyValue>>;
+/** A version: a whole number of at least 1, as a safe-integer `number` or a `bigint` within 64 bits. */
+export type Version = number | bigint;
+/** An element as the author describes it. Without a `version` it takes its change's sequence number. */
+export type Element = {
+    readonly kind: "node";
+    readonly id: string;
+    readonly version?: Version;
+    readonly labels: readonly string[];
+    readonly properties: Properties;
+} | {
+    readonly kind: "edge";
+    readonly id: string;
+    readonly version?: Version;
+    readonly type: string;
+    readonly from: string;
+    readonly to: string;
+    readonly properties: Properties;
+} | {
+    readonly kind: "tombstone";
+    readonly element: "node";
+    readonly id: string;
+    readonly version?: Version;
+} | {
+    readonly kind: "tombstone";
+    readonly element: "edge";
+    readonly id: string;
+    readonly version?: Version;
+    readonly type: string;
+    readonly from: string;
+    readonly to: string;
+};
+/** An element at a version: what is written and read. */
+export type Delta = Element & {
+    readonly version: Version;
+};
+/** Why an element or a result was refused; the names the shared fixture `refused.json` uses. */
+export type GraphFault = "id" | "endpoints" | "identifier" | "reserved" | "property-value" | "integer-range" | "version" | "duplicate" | "no-sequence";
+/** Thrown where an element is built, or when a result is returned, for something the merge sink would refuse. */
+export declare class GraphError extends Error {
+    readonly why: GraphFault;
+    constructor(why: GraphFault, message: string);
+}
+/** The element key: `node:<id>` or `edge:<id>`; a tombstone has the key of the element it marks. */
+export declare function elementKey(element: Element): string;
+/** `this.graph` in a graph consumer: builds elements, refusing where they are built what the sink would refuse. */
+export declare class Graph {
+    node(id: string, options?: {
+        readonly labels?: readonly string[];
+        readonly properties?: Properties;
+        readonly version?: Version;
+    }): Element;
+    edge(id: string, options: {
+        readonly type: string;
+        readonly from: string;
+        readonly to: string;
+        readonly properties?: Properties;
+        readonly version?: Version;
+    }): Element;
+    /** Marks a node deleted. The node stays in the graph, marked, so a straggling older delta cannot bring it back. */
+    tombstoneNode(id: string, options?: {
+        readonly version?: Version;
+    }): Element;
+    /** Marks an edge deleted; it names the edge's type and endpoints so the edge is found without a scan. */
+    tombstoneEdge(id: string, options: {
+        readonly type: string;
+        readonly from: string;
+        readonly to: string;
+        readonly version?: Version;
+    }): Element;
+}
+export type GraphEffect = ({
+    readonly kind: "publish";
+    readonly elements: readonly Element[];
+} & EffectLike<never>) | ({
+    readonly kind: "done";
+} & EffectLike<never>) | ({
+    readonly kind: "ignore";
+} & EffectLike<never>);
+/** `this.effects` in a graph consumer: there is nothing here that publishes anything but elements. */
+export declare class GraphEffects {
+    /** Publish these elements, each as a delta under its own key. An empty list publishes nothing. */
+    publish(elements: readonly Element[]): GraphEffect;
+    done(): GraphEffect;
+    ignore(): GraphEffect;
+}
+/**
+ * Reads a delta's value back into an element, for tests and for a consumer of a delta topic. Given a
+ * `key` it also holds the contract's rule that the key is the delta's element key. It accepts a
+ * version of 0, which the contract allows and the builder does not write. An integer past 2⁵³ comes
+ * back as a `bigint`.
+ */
+export declare function readDelta(value: Uint8Array, key?: string): Delta;
+/** The codec of a delta: JSON under the manifest `ankka.graph-delta.v1`. Hand-written, since a delta's properties have no fixed shape. */
+export declare const graphDeltaCodec: Codec<Delta>;
+/** One record a graph consumer's result comes to: the element key, the delta's bytes, and the delta. */
+export interface DeltaRecord {
+    readonly key: string;
+    readonly value: Uint8Array;
+    readonly delta: Delta;
+}
+/**
+ * What a graph consumer's effect publishes for the change `metadata` describes: every element at its
+ * stated version, else the change's sequence number, refusing a result that names an element twice or
+ * leaves a version to a change that has no sequence number. The server and the test kit both read an
+ * effect through this, so they cannot disagree about what a handler published.
+ *
+ * @internal
+ */
+export declare function deltaRecords(effect: GraphEffect, metadata: Metadata): readonly DeltaRecord[];
+/**
+ * A consumer that publishes a graph. Its handlers return elements; each is published to `producesTo`
+ * as a delta under its element key. It has no `produce` and no way to set a key, and it is discovered
+ * and hosted as an ordinary consumer.
+ */
+export declare abstract class GraphConsumer<M> {
+    #private;
+    readonly graph: Graph;
+    readonly effects: GraphEffects;
+    /** The change's metadata: `ce-subject` is the source instance's id, `ankka.sequence` its sequence number. */
+    get metadata(): Metadata;
+    get subject(): string;
+    /** The change's sequence number, which is the version of every element that states none. */
+    get sequenceNumber(): bigint | undefined;
+    get client(): ComponentClient;
+    /** The service's secret store: values kept encrypted in the service's own database, never in a journal or a view. */
+    get secrets(): Secrets;
+    /** A unit test's store in place of the runtime's: `component.secrets = new InMemorySecrets()`. */
+    set secrets(store: Secrets);
+    /** Other services, called as this one, through the runtime: `this.services.service("orders")`. */
+    get services(): Services;
+    /** A unit test's in place of the runtime's: `component.services = new ScriptedServices()`. */
+    set services(services: Services);
+    /** @internal */
+    get _kind(): "consumer";
+    abstract onMessage(message: M): MaybePromise<GraphEffect>;
+    /** The source was deleted. Ignored unless this says otherwise; publish tombstones here. */
+    onDelete(): MaybePromise<GraphEffect>;
+    /** @internal */
+    _bind(metadata: Metadata, client: ComponentClient): void;
+}
+export interface GraphConsumerClass<M = unknown, C extends GraphConsumer<M> = GraphConsumer<M>> {
+    new (): C;
+    readonly componentId: string;
+    readonly source?: ComponentRef;
+    readonly topic?: string;
+    /** Where a topic source starts the first time its group reads the topic. */
+    readonly startFrom?: StartFrom;
+    /** Raised to read the topic again from the start position, under a group of its own. Absent is 1. */
+    readonly version?: number;
+    readonly message: Shape<M>;
+    /** The delta topic. It must be compacted to hold the graph; the pipeline that reads it creates it so. */
+    readonly producesTo: string;
+}
+export {};