@alpamayo-solutions/colca-client 0.0.0 → 0.1.9

package/dist/generated/contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.js","sourceRoot":"","sources":["../../src/generated/contracts.ts"],"names":[],"mappings":"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"}

package/dist/ids.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Derived record ids.
+ *
+ * An annotation's id is computed, not drawn: create, update and delete of one
+ * annotation are appends under the same id, so a producer that runs again
+ * overwrites its own record instead of doubling it. Every client must therefore
+ * compute it exactly as `colca-data-contracts` does — `spec/vectors.json` holds
+ * the cases that prove it, including the one where the microseconds decide.
+ */
+export interface AnnotationIdInput {
+    annotationTypeId: string;
+    source: string;
+    /** Unix seconds. Six decimals are part of the identity; the seventh is not. */
+    timeStart: number;
+    /** The set is sorted before hashing, so the order it arrives in does not matter. */
+    signalIds: readonly string[];
+}
+/**
+ * `SHA-256("{type}|{source}|{time:.6f}|{sorted,signals}")`, first 16 bytes,
+ * ULID-encoded.
+ *
+ * Async because it hashes with WebCrypto, the one digest both Node and a
+ * browser have without a dependency.
+ */
+export declare function deriveAnnotationId(input: AnnotationIdInput): Promise<string>;
+/** The string that gets hashed. Exported for the conformance test's error messages. */
+export declare function annotationIdMaterial({ annotationTypeId, source, timeStart, signalIds, }: AnnotationIdInput): string;
+/**
+ * A new ULID: 48 bits of unix milliseconds, then 80 random bits. Ids made later
+ * sort later, which is the shape the node's own ids have — use it for command ids
+ * and correlation ids.
+ */
+export declare function newUlid(now?: number): string;
+/** Crockford base32 over 128 bits, the 26-character ULID text. */
+export declare function ulidFromBytes(bytes: Uint8Array): string;
+//# sourceMappingURL=ids.d.ts.map

package/dist/ids.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.d.ts","sourceRoot":"","sources":["../src/ids.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,MAAM,WAAW,iBAAiB;IAChC,gBAAgB,EAAE,MAAM,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,+EAA+E;IAC/E,SAAS,EAAE,MAAM,CAAC;IAClB,oFAAoF;IACpF,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9B;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CAIlF;AAED,uFAAuF;AACvF,wBAAgB,oBAAoB,CAAC,EACnC,gBAAgB,EAChB,MAAM,EACN,SAAS,EACT,SAAS,GACV,EAAE,iBAAiB,GAAG,MAAM,CAM5B;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,GAAG,GAAE,MAAmB,GAAG,MAAM,CAYxD;AAED,kEAAkE;AAClE,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAYvD"}

package/dist/ids.js

@@ -0,0 +1,64 @@
+/**
+ * Derived record ids.
+ *
+ * An annotation's id is computed, not drawn: create, update and delete of one
+ * annotation are appends under the same id, so a producer that runs again
+ * overwrites its own record instead of doubling it. Every client must therefore
+ * compute it exactly as `colca-data-contracts` does — `spec/vectors.json` holds
+ * the cases that prove it, including the one where the microseconds decide.
+ */
+const CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+/**
+ * `SHA-256("{type}|{source}|{time:.6f}|{sorted,signals}")`, first 16 bytes,
+ * ULID-encoded.
+ *
+ * Async because it hashes with WebCrypto, the one digest both Node and a
+ * browser have without a dependency.
+ */
+export async function deriveAnnotationId(input) {
+    const material = annotationIdMaterial(input);
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(material));
+    return ulidFromBytes(new Uint8Array(digest, 0, 16));
+}
+/** The string that gets hashed. Exported for the conformance test's error messages. */
+export function annotationIdMaterial({ annotationTypeId, source, timeStart, signalIds, }) {
+    if (!Number.isFinite(timeStart)) {
+        throw new Error(`timeStart must be a finite unix time, got ${String(timeStart)}`);
+    }
+    const signals = [...signalIds].sort().join(",");
+    return `${annotationTypeId}|${source}|${timeStart.toFixed(6)}|${signals}`;
+}
+/**
+ * A new ULID: 48 bits of unix milliseconds, then 80 random bits. Ids made later
+ * sort later, which is the shape the node's own ids have — use it for command ids
+ * and correlation ids.
+ */
+export function newUlid(now = Date.now()) {
+    if (!Number.isInteger(now) || now < 0 || now >= 2 ** 48) {
+        throw new Error(`a ULID time is whole milliseconds between 0 and 2^48, got ${String(now)}`);
+    }
+    const bytes = new Uint8Array(16);
+    let time = now;
+    for (let i = 5; i >= 0; i -= 1) {
+        bytes[i] = time % 256;
+        time = Math.floor(time / 256);
+    }
+    crypto.getRandomValues(bytes.subarray(6));
+    return ulidFromBytes(bytes);
+}
+/** Crockford base32 over 128 bits, the 26-character ULID text. */
+export function ulidFromBytes(bytes) {
+    if (bytes.length !== 16) {
+        throw new Error(`a ULID is 16 bytes, got ${String(bytes.length)}`);
+    }
+    let value = 0n;
+    for (const byte of bytes)
+        value = (value << 8n) | BigInt(byte);
+    let out = "";
+    for (let i = 0; i < 26; i += 1) {
+        out = CROCKFORD[Number(value & 31n)] + out;
+        value >>= 5n;
+    }
+    return out;
+}
+//# sourceMappingURL=ids.js.map

package/dist/ids.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.js","sourceRoot":"","sources":["../src/ids.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,SAAS,GAAG,kCAAkC,CAAC;AAWrD;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,KAAwB;IAC/D,MAAM,QAAQ,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAAC;IAC7C,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;IACzF,OAAO,aAAa,CAAC,IAAI,UAAU,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;AACtD,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,oBAAoB,CAAC,EACnC,gBAAgB,EAChB,MAAM,EACN,SAAS,EACT,SAAS,GACS;IAClB,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,KAAK,CAAC,6CAA6C,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;IACpF,CAAC;IACD,MAAM,OAAO,GAAG,CAAC,GAAG,SAAS,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAChD,OAAO,GAAG,gBAAgB,IAAI,MAAM,IAAI,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,OAAO,EAAE,CAAC;AAC5E,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,OAAO,CAAC,MAAc,IAAI,CAAC,GAAG,EAAE;IAC9C,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;QACxD,MAAM,IAAI,KAAK,CAAC,6DAA6D,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC9F,CAAC;IACD,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,EAAE,CAAC,CAAC;IACjC,IAAI,IAAI,GAAG,GAAG,CAAC;IACf,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QAC/B,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,GAAG,CAAC;QACtB,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,GAAG,CAAC,CAAC;IAChC,CAAC;IACD,MAAM,CAAC,eAAe,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1C,OAAO,aAAa,CAAC,KAAK,CAAC,CAAC;AAC9B,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,aAAa,CAAC,KAAiB;IAC7C,IAAI,KAAK,CAAC,MAAM,KAAK,EAAE,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CAAC,2BAA2B,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACrE,CAAC;IACD,IAAI,KAAK,GAAG,EAAE,CAAC;IACf,KAAK,MAAM,IAAI,IAAI,KAAK;QAAE,KAAK,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;IAC/D,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QAC/B,GAAG,GAAG,SAAS,CAAC,MAAM,CAAC,KAAK,GAAG,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC;QAC3C,KAAK,KAAK,EAAE,CAAC;IACf,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * colca-client — the door, in TypeScript.
+ *
+ * ```ts
+ * const door = new Door({ baseUrl: "http://colca", service: "my-app" });
+ * const stream = new Stream(door, "annotations", door.cursorName("panels"));
+ * for await (const record of stream.follow()) {
+ *   console.log(record.topic, record.payload);
+ * }
+ * ```
+ */
+export { Door, DoorError } from "./door.js";
+export type { Attribution, DoorOptions, DoorRecord, FetchOptions, Gap, KvEntry, Page, PublishResult, SelfInfo, } from "./door.js";
+export { Stream } from "./stream.js";
+export type { FollowOptions, StreamOptions } from "./stream.js";
+export { DEFAULT_ROOT, TOPIC_VERSION, parseTopic, topic, topicMatches, topicPrefix } from "./topics.js";
+export type { TopicOptions, TopicParts } from "./topics.js";
+export { annotationIdMaterial, deriveAnnotationId, newUlid, ulidFromBytes } from "./ids.js";
+export type { AnnotationIdInput } from "./ids.js";
+export * from "./generated/contracts.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC5C,YAAY,EACV,WAAW,EACX,WAAW,EACX,UAAU,EACV,YAAY,EACZ,GAAG,EACH,OAAO,EACP,IAAI,EACJ,aAAa,EACb,QAAQ,GACT,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEhE,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACxG,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE5D,OAAO,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC5F,YAAY,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAGlD,cAAc,0BAA0B,CAAC"}

package/dist/index.js

@@ -0,0 +1,18 @@
+/**
+ * colca-client — the door, in TypeScript.
+ *
+ * ```ts
+ * const door = new Door({ baseUrl: "http://colca", service: "my-app" });
+ * const stream = new Stream(door, "annotations", door.cursorName("panels"));
+ * for await (const record of stream.follow()) {
+ *   console.log(record.topic, record.payload);
+ * }
+ * ```
+ */
+export { Door, DoorError } from "./door.js";
+export { Stream } from "./stream.js";
+export { DEFAULT_ROOT, TOPIC_VERSION, parseTopic, topic, topicMatches, topicPrefix } from "./topics.js";
+export { annotationIdMaterial, deriveAnnotationId, newUlid, ulidFromBytes } from "./ids.js";
+// The 32 contracts, straight from the bundle the node validates against.
+export * from "./generated/contracts.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAa5C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAGrC,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAGxG,OAAO,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAG5F,yEAAyE;AACzE,cAAc,0BAA0B,CAAC"}

package/dist/live.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Live values over MQTT, for a page or a service that wants them pushed.
+ *
+ * Colca retains the current value of every data and entity path, so a
+ * subscription brings the present state first and the changes after it. There
+ * is no snapshot to fetch and nothing to merge. What this module adds is what a
+ * long-lived client needs around that:
+ *
+ * - one connection, however many parts of a page subscribe, and an unsubscribe
+ *   that ends only its own subscription;
+ * - the last value of every topic, so a second subscriber to a topic gets it at
+ *   once instead of waiting for the next change;
+ * - a fresh token before the old one runs out — the node ends a session when
+ *   its token expires — and every subscription sent again on the new connection;
+ * - growing, jittered waits between attempts after a drop, each with a fresh
+ *   token;
+ * - commands that wait for their acknowledgement.
+ *
+ * These are values, not a log: a change that happens while the connection is
+ * being replaced is superseded by the retained value that follows. Anything that
+ * must see every record reads a stream through the door instead.
+ *
+ * mqtt.js is loaded on first use and is an optional dependency of this package.
+ */
+export type LiveState = "connecting" | "online" | "offline" | "closed";
+export type Qos = 0 | 1;
+export interface LiveValue<T = unknown> {
+    topic: string;
+    /** `undefined` when the path was retired with an empty payload. */
+    payload: T | undefined;
+    /** The value the node held when the subscription started, rather than a change. */
+    retained: boolean;
+    /** Local clock, unix milliseconds — for showing age, not for ordering records. */
+    receivedAt: number;
+}
+export interface SubscribeOptions {
+    /** 1 for records that must not get lost in flight, acknowledgements for instance. */
+    qos?: Qos;
+}
+/** A command's answer, `_Ack`. `result_code` reads like HTTP: 200 means done. */
+export interface CommandAck {
+    correlation_id: string;
+    result_code: number;
+    message?: string;
+    performed_at?: number | null;
+    [field: string]: unknown;
+}
+export interface CommandOptions {
+    /** How long the command stays valid at the node, and how long to wait for its answer. */
+    timeoutMs?: number;
+    /** Where the answer arrives: every `_Ack` under the command's root, unless given. */
+    ackFilter?: string;
+}
+/** Nobody answered a command before it expired. */
+export declare class CommandTimeout extends Error {
+    readonly topic: string;
+    readonly correlationId: string;
+    constructor(topic: string, correlationId: string);
+}
+/** What is handed to the MQTT client for each connection. */
+export interface MqttConnectOptions {
+    clientId: string;
+    username: string;
+    password: string;
+    protocolVersion: 5;
+    clean: true;
+    keepalive: number;
+    /** Zero: reconnecting is this module's job, because every attempt needs a fresh token. */
+    reconnectPeriod: 0;
+    connectTimeout: number;
+    [option: string]: unknown;
+}
+/** The part of an MQTT client this module uses; mqtt.js's client fits. */
+export interface MqttLike {
+    on(event: "connect" | "close", listener: () => void): unknown;
+    on(event: "error", listener: (error: Error) => void): unknown;
+    on(event: "message", listener: (topic: string, payload: Uint8Array, packet: {
+        retain: boolean;
+    }) => void): unknown;
+    subscribe(filters: string[], options: {
+        qos: Qos;
+    }, callback?: (error: Error | null, granted?: {
+        topic: string;
+        qos: number;
+    }[]) => void): unknown;
+    unsubscribe(filters: string[]): unknown;
+    publish(topic: string, message: string, options: {
+        qos: Qos;
+        retain: false;
+    }, callback?: (error?: Error) => void): unknown;
+    end(force?: boolean): unknown;
+}
+export interface LiveOptions {
+    /** The node's WebSocket door for people and applications, e.g. `wss://node:8885`. */
+    url: string;
+    /** Asked before every connection attempt; hand back a token that is valid now. */
+    token: () => string | Promise<string>;
+    /** The node requires the token's `sub` here, which is the default. Set it for a token that is not a JWT. */
+    username?: string;
+    /** Reconnect with a new token this long before the current one expires. */
+    renewBeforeMs?: number;
+    /** The first wait after a failed attempt. It doubles up to `maxRetryMs`. */
+    retryMs?: number;
+    maxRetryMs?: number;
+    clientIdPrefix?: string;
+    /** Passed to the MQTT client as they are — TLS settings for a service, for instance. */
+    mqttOptions?: Readonly<Record<string, unknown>>;
+    /** Problems the client lives through: refused connections, unreadable payloads, throwing listeners. */
+    onError?: (error: Error) => void;
+    /** How a connection is made. mqtt.js by default. */
+    connect?: (url: string, options: MqttConnectOptions) => MqttLike | Promise<MqttLike>;
+}
+export declare class Live {
+    #private;
+    constructor(options: LiveOptions);
+    get state(): LiveState;
+    /**
+     * Values under `filter` (MQTT wildcards allowed), the current ones first. Returns
+     * the function that ends this subscription and no other.
+     */
+    subscribe<T = unknown>(filter: string, listener: (value: LiveValue<T>) => void, options?: SubscribeOptions): () => void;
+    /** The last value seen on a topic, if anyone is subscribed to it. */
+    latest<T = unknown>(topic: string): LiveValue<T> | undefined;
+    /** Every last value under a filter. */
+    values<T = unknown>(filter: string): LiveValue<T>[];
+    /**
+     * One record, as JSON, under this caller's identity. Nothing is queued: offline
+     * it fails at once, because a command sent minutes later is a different command.
+     * A person's session may only send commands; the node refuses anything else.
+     */
+    publish(topic: string, payload: unknown, options?: {
+        qos?: Qos;
+    }): Promise<void>;
+    /**
+     * Send a command and wait for its acknowledgement.
+     *
+     * `body` is the command's own fields — `params` for a `_CmdParam`, say. The
+     * correlation id and the expiry are added here, and the answer is matched by
+     * the id, wherever in the tree the executor publishes it. The promise settles
+     * with the `_Ack`, whatever its `result_code`; it rejects when nothing answers
+     * in `timeoutMs`, when the node refuses the publish, or when the client closes.
+     */
+    command(topic: string, body?: Record<string, unknown>, options?: CommandOptions): Promise<CommandAck>;
+    /** Called on every change of the connection state; returns the function that stops it. */
+    onState(listener: (state: LiveState) => void): () => void;
+    close(): void;
+}
+//# sourceMappingURL=live.d.ts.map

package/dist/live.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"live.d.ts","sourceRoot":"","sources":["../src/live.ts"],"names":[],"mappings":"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"}