ankka 0.11.0 → 0.12.0

package/dist/testkit/unit.js

@@ -7,7 +7,8 @@ import { create } from "@bufbuild/protobuf";
 import { HttpRequestSchema, SocketInSchema } from "../_proto/ankka/protocol/v1/endpoint_pb.js";
 import { ComponentClient, noClient } from "../client.js";
 import { binaryCodecs, codecFor } from "../codec.js";
-import { commandContext } from "../context.js";
+import { commandContext, eventContext } from "../context.js";
+import { ErrorCode } from "../effects/common.js";
 import { EventSourcedEntity } from "../eventSourcedEntity.js";
 import { materialiseEventSourced } from "../materialise.js";
 import { Ankka } from "../service.js";
@@ -22,19 +23,24 @@ function findHandler(handlers, handler, who) {
         throw new Error(`${who} has no handler ${JSON.stringify(name)}; declared: ${[...handlers.keys()].sort().join(", ")}`);
     return found;
 }
-/** Drives one event sourced entity instance through its handlers, folding events as it goes. */
 export class EventSourcedTestKit {
     #registered;
     #entity;
     #client;
+    #mode;
+    #here;
     entityId;
+    /** The handover or change to the replication set the last call asked for, if any. */
+    lastReplication = undefined;
     /** The state now, after every call so far. */
     state;
     /** The sequence number of the last event, `0n` before any. */
     sequence = 0n;
     /** Every event persisted so far, in order. */
     allEvents = [];
-    constructor(cls, entityId, client) {
+    constructor(cls, entityId, client, mode = { kind: "unreplicated" }) {
+        this.#mode = mode;
+        this.#here = mode.kind === "unreplicated" ? null : (mode.installation ?? "test");
         const registry = Ankka.service({ client, log: () => { } })
             .register(cls)
             .validate();
@@ -46,15 +52,36 @@ export class EventSourcedTestKit {
         this.state = this.#entity.emptyState();
     }
     /** A kit for `cls` as instance `entityId`. Calls to other components reach `client`, which by default refuses them. */
-    static of(cls, entityId = "test", client = noClient()) {
-        return new EventSourcedTestKit(cls, entityId, client);
+    static of(cls, entityId = "test", client = noClient(), 
+    /**
+     * How a replicated entity's copy stands (1.19): `{ kind: "home" }`, where every command runs, or
+     * `{ kind: "follower", home }`, where a command that may persist is refused `NOT_HOME` and a query is
+     * answered from what `replay` gave it. Not replicated by default.
+     */
+    mode = { kind: "unreplicated" }) {
+        return new EventSourcedTestKit(cls, entityId, client, mode);
+    }
+    /**
+     * Applies `events` as history the copy already holds, written at `writtenAt` (this installation by
+     * default): for a follower, what it has mirrored from its home.
+     */
+    replay(events, writtenAt = this.#here) {
+        for (const event of events) {
+            this.sequence += 1n;
+            this.state = this.#entity.applyEvent(this.state, event, eventContext(writtenAt, writtenAt === this.#here, this.sequence));
+        }
     }
     /** Sends a command or query and returns what its effect amounts to. */
     async call(handler, input, metadata = {}) {
         const ref = findHandler(this.#registered.handlers, handler, this.#registered.cls.name);
+        if (this.#mode.kind === "follower" && !ref.readOnly) {
+            // The runtime forwards such a command to the home; here there is no home to forward to.
+            const error = { message: `the home of '${this.entityId}' is '${this.#mode.home}'; a follower handles no command that may persist`, code: ErrorCode.NotHome };
+            return Object.freeze({ events: [], newState: this.state, retention: null, reply: undefined, error, noReply: false });
+        }
         const inputCodec = ref.input ? codecFor(ref.input) : undefined;
         const wireInput = inputCodec ? roundTrip(inputCodec, input) : undefined;
-        const context = commandContext(this.#registered.id, this.entityId, this.sequence, metadata);
+        const context = commandContext(this.#registered.id, this.entityId, this.sequence, metadata, undefined, this.#here, this.#mode.kind !== "follower");
         this.#entity._bindCommand(this.state, context, this.#client.withMetadata(metadata));
         let effect;
         try {
@@ -65,7 +92,20 @@ export class EventSourcedTestKit {
         }
         if (ref.readOnly && effect.kind !== "read-only")
             throw new Error(`${this.#registered.id}/${ref.name} is a query and returned a persisting effect`);
-        const m = materialiseEventSourced(effect, this.state, (s, e) => this.#entity.applyEvent(s, e));
+        let applied = this.sequence;
+        const m = materialiseEventSourced(effect, this.state, (s, e) => {
+            applied += 1n;
+            return this.#entity.applyEvent(s, e, eventContext(this.#here, true, applied));
+        });
+        const replication = effect.kind === "persist" ? effect.replication : undefined;
+        if (!m.error && replication && this.#mode.kind === "unreplicated") {
+            const error = {
+                message: `${this.#registered.id} is not replicated in this test kit; drive it with { kind: "home" } to see the handover or the change to the replication set it asks for`,
+                code: ErrorCode.BadRequest,
+            };
+            return Object.freeze({ events: [], newState: this.state, retention: null, reply: undefined, error, noReply: false });
+        }
+        this.lastReplication = m.error ? undefined : replication;
         const eventCodec = this.#registered.eventCodec;
         const stateCodec = this.#registered.stateCodec;
         const events = m.events.map((e) => roundTrip(eventCodec, e));

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.11.0";
+export declare const VERSION = "0.12.0";

package/dist/version.js

@@ -1,2 +1,2 @@
 // Written by scripts/proto.ts from package.json; do not edit. 0.0.0 in the tree, the tag's version in a release.
-export const VERSION = "0.11.0";
+export const VERSION = "0.12.0";

package/dist/view.d.ts

@@ -5,6 +5,7 @@ import type { Metadata } from "./effects/common.ts";
 import type { ComponentClient } from "./client.ts";
 import type { ComponentRef } from "./client.ts";
 import { ViewEffects, type ViewEffect } from "./effects/stateless.ts";
+import type { Standing } from "./standing.ts";
 type MaybePromise<T> = T | Promise<T>;
 /**
  * A question a view can be asked by name: one SQL statement over the view's own table, whose values
@@ -16,9 +17,16 @@ type MaybePromise<T> = T | Promise<T>;
 export interface DeclaredQuery {
     readonly name: string;
     readonly statement: string;
+    /** Whether it may be watched: its statement selects `row_key` beside `payload`, with no limit and no aggregate. */
+    readonly watched?: boolean;
 }
-/** Declares a query for a view's `static declared`. The SDK sends the statement as written. */
-export declare function declaredQuery(name: string, statement: string): DeclaredQuery;
+/**
+ * Declares a query for a view's `static declared`. The SDK sends the statement as written.
+ * `{ watched: true }` declares that it may also be watched, which the platform checks at start.
+ */
+export declare function declaredQuery(name: string, statement: string, options?: {
+    readonly watched?: boolean;
+}): DeclaredQuery;
 /** The table a view's rows are kept in, for a declared query's statement to name. */
 export declare function tableOf(componentId: string): string;
 export declare abstract class View<E, Row> {
@@ -30,6 +38,8 @@ export declare abstract class View<E, Row> {
     get metadata(): Metadata;
     /** The id of the source instance the change came from. */
     get subject(): string;
+    /** Of a change from a workflow: where it stood once the effect that recorded the state was applied. `undefined` for a change from an entity or a topic. */
+    get standing(): Standing | undefined;
     get client(): ComponentClient;
     /** @internal */
     get _kind(): "view";
@@ -38,7 +48,7 @@ export declare abstract class View<E, Row> {
     /** The source was deleted. The row goes with it unless this says otherwise — an order history keeps a checked-out cart's row. */
     onDelete(): MaybePromise<ViewEffect<Row>>;
     /** @internal */
-    _bind(row: Row | null, metadata: Metadata, client: ComponentClient): void;
+    _bind(row: Row | null, metadata: Metadata, client: ComponentClient, standing?: Standing): void;
 }
 export interface ViewClass<E = unknown, Row = unknown, C extends View<E, Row> = View<E, Row>> {
     new (): C;
@@ -57,6 +67,11 @@ export interface ViewClass<E = unknown, Row = unknown, C extends View<E, Row> =
     readonly contract?: Contract;
     /** The declared broker the topic read is on; absent is the installation's. */
     readonly broker?: string;
+    /**
+     * Another project's topic (1.15): the id of the project whose topic `topic` is. The broker serves it
+     * while that project grants this service consume on it.
+     */
+    readonly project?: string;
     /** Whether the partitions an instance holds are handled at once, each in order. */
     readonly parallel?: boolean;
     readonly events: Shape<E>;

package/dist/view.js

@@ -9,9 +9,12 @@
 //     onChange(event) { ... return this.effects.updateRow(...) }
 //   }
 import { ViewEffects } from "./effects/stateless.js";
-/** Declares a query for a view's `static declared`. The SDK sends the statement as written. */
-export function declaredQuery(name, statement) {
-    return Object.freeze({ name, statement });
+/**
+ * Declares a query for a view's `static declared`. The SDK sends the statement as written.
+ * `{ watched: true }` declares that it may also be watched, which the platform checks at start.
+ */
+export function declaredQuery(name, statement, options = {}) {
+    return Object.freeze({ name, statement, watched: options.watched ?? false });
 }
 /** The table a view's rows are kept in, for a declared query's statement to name. */
 export function tableOf(componentId) {
@@ -21,6 +24,7 @@ export class View {
     effects = new ViewEffects();
     #row = null;
     #metadata = {};
+    #standing = undefined;
     #client;
     #bound = false;
     /** The current row, or `null` when there is none yet. */
@@ -37,6 +41,10 @@ export class View {
     get subject() {
         return this.#metadata["ce-subject"] ?? "";
     }
+    /** Of a change from a workflow: where it stood once the effect that recorded the state was applied. `undefined` for a change from an entity or a topic. */
+    get standing() {
+        return this.#standing;
+    }
     get client() {
         if (!this.#client)
             throw new Error("client is only available inside onChange or onDelete");
@@ -51,9 +59,10 @@ export class View {
         return this.effects.deleteRow();
     }
     /** @internal */
-    _bind(row, metadata, client) {
+    _bind(row, metadata, client, standing) {
         this.#row = row;
         this.#metadata = metadata;
+        this.#standing = standing;
         this.#client = client;
         this.#bound = true;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ankka",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Build services on ankka in TypeScript: entities, views, workflows, agents and endpoints hosted by the ankka sidecar.",
   "license": "Apache-2.0",
   "type": "module",