@peers-app/peers-sdk 0.26.6 → 0.27.0

package/dist/define/observables.d.ts

@@ -0,0 +1,146 @@
+import type { z } from "zod";
+import type { Observable } from "../observable";
+import type { FieldType } from "../types/field-type";
+import type { IPackageContext } from "./context";
+import { type IPackageVarBinding } from "./vars";
+/** Settings every observable declaration shares. */
+interface IPackageObservableOptions {
+    /** Observable name, unique on its contract. */
+    name: string;
+    /** What the value is, for people and agents reading it. */
+    description: string;
+    /** Consumers may write the value. Defaults to `false`. */
+    writable?: boolean;
+    /**
+     * What holds the value. A package variable (`deviceVar`, `groupVar`, …) is stored, and the
+     * provider reads and writes it in its worker. A plain `observable()` is held in memory by
+     * the package's worker: reading it starts the worker, and it starts over when the worker does.
+     */
+    source: Observable<any>;
+}
+/** An observable declared with a zod schema for its value. */
+export interface IPackageObservableSchemaDefinition<S extends z.ZodTypeAny = z.ZodTypeAny> extends IPackageObservableOptions {
+    /**
+     * The value's schema. The manifest carries its type as IR; a consumer's write is parsed
+     * with it before the source takes it.
+     */
+    schema: S;
+}
+/** An observable declared with a Peers IR value type, for a contract defined elsewhere. */
+export interface IPackageObservableTypeDefinition extends IPackageObservableOptions {
+    /** The value's type: `string`, `number`, `boolean`, `object`, `id`, or `any`. */
+    valueType: FieldType;
+}
+/** Either form of observable declaration. */
+export type PackageObservableDefinition = IPackageObservableSchemaDefinition | IPackageObservableTypeDefinition;
+/** An observable's shape from a zod schema, without its source: what {@link declareObservable} takes. */
+export type IPackageObservableSchemaShape<S extends z.ZodTypeAny = z.ZodTypeAny> = Omit<IPackageObservableSchemaDefinition<S>, "source">;
+/** An observable's shape in Peers IR, without its source: what {@link declareObservable} takes. */
+export type IPackageObservableTypeShape = Omit<IPackageObservableTypeDefinition, "source">;
+/** Either form of observable shape. */
+export type PackageObservableShape = IPackageObservableSchemaShape | IPackageObservableTypeShape;
+/**
+ * An observable's shape, from {@link declareObservable}: what a contract declaration lists, with
+ * no source. `T` is its value, `N` its name, and `W` whether consumers may write it.
+ */
+export interface IPackageObservableDeclaration<T = unknown, N extends string = string, W extends boolean = boolean> {
+    /** Marks an observable. */
+    readonly kind: "observable";
+    /** What was passed to {@link declareObservable} (or {@link defineObservable}). */
+    readonly definition: Readonly<PackageObservableShape> & {
+        readonly name: N;
+        readonly writable?: W;
+    };
+    /** Type-only: the value consumers read. Always undefined at runtime. */
+    readonly types?: {
+        value: T;
+    };
+}
+/**
+ * An observable declared with {@link defineObservable}: its shape and its source. List it on a
+ * provided contract. `T` is its value, `N` its name, and `W` whether consumers may write it.
+ */
+export interface IPackageObservable<T = unknown, N extends string = string, W extends boolean = boolean> extends IPackageObservableDeclaration<T, N, W> {
+    /** What was passed to {@link defineObservable}. */
+    readonly definition: Readonly<PackageObservableDefinition> & {
+        readonly name: N;
+        readonly writable?: W;
+    };
+    /** Where the value is stored, when a package variable holds it; undefined for in-memory. */
+    readonly persistentVar?: IPackageVarBinding;
+}
+/**
+ * Apply a consumer's write to an in-memory observable this package serves, as its write handler
+ * does: the schema checks the value, the source takes it, and the stored value is published and
+ * returned. Undefined before the observable is served, or when it isn't writable.
+ *
+ * @param observable - A provided in-memory observable.
+ */
+export declare function inMemoryObservableWriter(observable: IPackageObservable): ((value: unknown) => Promise<unknown>) | undefined;
+/**
+ * Declare an observable from a zod schema for its value.
+ *
+ * @param definition - Name, description, schema, `writable`, and source.
+ */
+export declare function defineObservable<S extends z.ZodTypeAny, N extends string, W extends boolean = false>(definition: IPackageObservableSchemaDefinition<S> & {
+    name: N;
+    writable?: W;
+}): IPackageObservable<z.output<S>, NoInfer<N>, NoInfer<W>>;
+/**
+ * Declare an observable from a Peers IR value type, for a contract defined elsewhere. Consumers
+ * read the source's type.
+ *
+ * @param definition - Name, description, `valueType`, `writable`, and source.
+ */
+export declare function defineObservable<T, N extends string, W extends boolean = false>(definition: IPackageObservableTypeDefinition & {
+    name: N;
+    writable?: W;
+    source: Observable<T>;
+}): IPackageObservable<T, NoInfer<N>, NoInfer<W>>;
+/**
+ * Declare an observable's shape from a zod schema, with no source, for a contract declared with
+ * `declareContract`: each package that implements the contract supplies the source.
+ *
+ * @param definition - Name, description, schema, and `writable`.
+ */
+export declare function declareObservable<S extends z.ZodTypeAny, N extends string, W extends boolean = false>(definition: IPackageObservableSchemaShape<S> & {
+    name: N;
+    writable?: W;
+}): IPackageObservableDeclaration<z.output<S>, NoInfer<N>, NoInfer<W>>;
+/**
+ * Declare an observable's shape from a Peers IR value type, with no source.
+ *
+ * @param definition - Name, description, `valueType`, and `writable`.
+ */
+export declare function declareObservable<N extends string, W extends boolean = false>(definition: IPackageObservableTypeShape & {
+    name: N;
+    writable?: W;
+}): IPackageObservableDeclaration<unknown, NoInfer<N>, NoInfer<W>>;
+/**
+ * True when `observable` has a source: from {@link defineObservable}, not
+ * {@link declareObservable}.
+ *
+ * @param observable - An observable from either.
+ */
+export declare function isImplementedObservable(observable: IPackageObservableDeclaration): observable is IPackageObservable;
+/**
+ * True for an observable from {@link declareObservable} or {@link defineObservable}, as
+ * opposed to Peers IR. Use {@link isImplementedObservable} to check whether it has a source.
+ *
+ * @param value - An entry in a contract's `observables`.
+ */
+export declare function isPackageObservable(value: unknown): value is IPackageObservableDeclaration<any>;
+/**
+ * Publish each in-memory observable's value now and after every change, and take consumers'
+ * writes to the writable ones. Called by `startPackage`; variable-backed observables need
+ * nothing here: their member handlers read and write the package variable.
+ *
+ * @param provides - The package's provided contracts.
+ * @param ctx - The worker's context, bound to no call.
+ */
+export declare function servePackageObservables(provides: readonly {
+    contractId: string;
+    version: number;
+    observables: readonly unknown[];
+}[], ctx: IPackageContext): Promise<void>;
+export {};

package/dist/define/observables.js

@@ -0,0 +1,187 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.inMemoryObservableWriter = inMemoryObservableWriter;
+exports.defineObservable = defineObservable;
+exports.declareObservable = declareObservable;
+exports.isImplementedObservable = isImplementedObservable;
+exports.isPackageObservable = isPackageObservable;
+exports.servePackageObservables = servePackageObservables;
+const empty_fields_1 = require("./empty-fields");
+const vars_1 = require("./vars");
+const wire_value_1 = require("./wire-value");
+/** Stops serving an observable from an earlier start (tests start packages more than once). */
+const serving = new WeakMap();
+/** Each served writable in-memory observable's write: the schema check, the source, a publish. */
+const writers = new WeakMap();
+/**
+ * Apply a consumer's write to an in-memory observable this package serves, as its write handler
+ * does: the schema checks the value, the source takes it, and the stored value is published and
+ * returned. Undefined before the observable is served, or when it isn't writable.
+ *
+ * @param observable - A provided in-memory observable.
+ */
+function inMemoryObservableWriter(observable) {
+    return writers.get(observable);
+}
+/**
+ * Declare an observable a provided contract exposes: one value, read and watched by other
+ * packages and the UI, over a `source` the package already uses. The package reads and writes
+ * the source as usual.
+ *
+ * @param definition - Name, description, schema (or IR `valueType`), `writable`, and source.
+ */
+function defineObservable(definition) {
+    checkObservableShape(definition, "defineObservable");
+    const { name, source } = definition;
+    if (typeof source !== "function" || typeof source.subscribe !== "function") {
+        throw new Error(`Observable ${name} needs a source: a package variable or an observable()`);
+    }
+    const persistentVar = (0, vars_1.packageVarBinding)(source);
+    if (persistentVar && persistentVar.defaultValue === undefined) {
+        throw new Error(`Observable ${name} is stored in variable "${persistentVar.name}", which needs a defaultValue`);
+    }
+    return Object.freeze({
+        kind: "observable",
+        definition: Object.freeze({ ...definition }),
+        ...(persistentVar ? { persistentVar } : {}),
+    });
+}
+/**
+ * Declare an observable's shape, with no source.
+ *
+ * @param definition - Name, description, schema (or IR `valueType`), and `writable`.
+ */
+function declareObservable(definition) {
+    checkObservableShape(definition, "declareObservable");
+    if ("source" in definition) {
+        throw new Error(`Observable ${definition.name}: declareObservable takes no source; implementContract supplies it`);
+    }
+    return Object.freeze({
+        kind: "observable",
+        definition: Object.freeze({ ...definition }),
+    });
+}
+/**
+ * True when `observable` has a source: from {@link defineObservable}, not
+ * {@link declareObservable}.
+ *
+ * @param observable - An observable from either.
+ */
+function isImplementedObservable(observable) {
+    return typeof observable.definition.source === "function";
+}
+/** Check what every observable, declared or defined, needs: a name, a description, one form. */
+function checkObservableShape(definition, what) {
+    if (typeof definition?.name !== "string" || definition.name.trim() === "") {
+        throw new Error(`${what} requires a name`);
+    }
+    const { name } = definition;
+    if (typeof definition.description !== "string") {
+        throw new Error(`Observable ${name} needs a description`);
+    }
+    const withSchema = "schema" in definition && definition.schema !== undefined;
+    const withType = "valueType" in definition && definition.valueType !== undefined;
+    if (withSchema === withType) {
+        throw new Error(`Observable ${name} needs either a schema or a valueType`);
+    }
+    if (withSchema &&
+        typeof definition.schema.safeParse !== "function") {
+        throw new Error(`Observable ${name} schema must be a zod schema`);
+    }
+    if (withType && typeof definition.valueType !== "string") {
+        throw new Error(`Observable ${name} valueType must be a FieldType`);
+    }
+    if (definition.writable !== undefined && typeof definition.writable !== "boolean") {
+        throw new Error(`Observable ${name} writable must be a boolean`);
+    }
+}
+/**
+ * True for an observable from {@link declareObservable} or {@link defineObservable}, as
+ * opposed to Peers IR. Use {@link isImplementedObservable} to check whether it has a source.
+ *
+ * @param value - An entry in a contract's `observables`.
+ */
+function isPackageObservable(value) {
+    return value?.kind === "observable";
+}
+/**
+ * Publish each in-memory observable's value now and after every change, and take consumers'
+ * writes to the writable ones. Called by `startPackage`; variable-backed observables need
+ * nothing here: their member handlers read and write the package variable.
+ *
+ * @param provides - The package's provided contracts.
+ * @param ctx - The worker's context, bound to no call.
+ */
+async function servePackageObservables(provides, ctx) {
+    const targets = new Map();
+    for (const contract of provides) {
+        for (const observable of contract.observables) {
+            if (isPackageObservable(observable) &&
+                isImplementedObservable(observable) &&
+                !observable.persistentVar) {
+                const list = targets.get(observable) ?? [];
+                list.push({ contractId: contract.contractId, version: contract.version });
+                targets.set(observable, list);
+            }
+        }
+    }
+    await Promise.all([...targets].map(([observable, list]) => serveObservable(observable, list, ctx)));
+}
+async function serveObservable(observable, targets, ctx) {
+    serving.get(observable)?.();
+    const { definition } = observable;
+    const { name, source } = definition;
+    const schema = "schema" in definition ? definition.schema : undefined;
+    /** True while a consumer's write is applied: that write publishes once, itself. */
+    let applying = false;
+    let sending = Promise.resolve();
+    // One at a time, so the host sees the values in the order they were set.
+    const publish = (value) => {
+        // Capture now, before waiting for earlier sends: the package may mutate this object again.
+        let stored;
+        try {
+            stored = (0, wire_value_1.snapshotPackageValue)((0, empty_fields_1.withoutEmptySchemaFields)(schema, value));
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+        const sent = sending.then(async () => {
+            await Promise.all(targets.map((target) => ctx.publishOwnedObservable(target.contractId, target.version, name, stored)));
+            return stored;
+        });
+        sending = sent.then(() => undefined, () => undefined);
+        return sent;
+    };
+    const report = (error) => {
+        console.error(`Publishing observable "${name}" failed`, error);
+    };
+    const subscription = source.subscribe((value) => {
+        if (!applying) {
+            publish(value).catch(report);
+        }
+    });
+    serving.set(observable, () => subscription.dispose());
+    if (definition.writable) {
+        // Guest API 3 calls this from its member handler under the caller's authority; guest
+        // API 2 uses onOwnedObservableSet without a caller frame. Both parse before writing.
+        const write = async (value) => {
+            const next = schema ? schema.parse((0, empty_fields_1.withoutEmptySchemaFields)(schema, value)) : value;
+            applying = true;
+            try {
+                source(next);
+            }
+            finally {
+                applying = false;
+            }
+            // Publish what the source holds now: its own subscribers may have adjusted it.
+            return publish(source());
+        };
+        writers.set(observable, write);
+        for (const target of targets) {
+            ctx.onOwnedObservableSet(target.contractId, target.version, name, write);
+        }
+    }
+    // A successful start guarantees readers have a published value. Later background failures
+    // are logged, but a failed initial publish must fail startup rather than silently serve null.
+    await publish(source());
+}

package/dist/define/serve-members.d.ts

@@ -0,0 +1,21 @@
+import type { IPackageContext } from "./context";
+import type { IPackageContract } from "./define-package";
+/** Registers a guest handler the host invokes by name with `(args, ctx)`. */
+type RegisterHandler = (name: string, handler: (args: unknown, ctx: IPackageContext) => unknown) => void;
+/**
+ * Serve one provided contract's tables, observables, and events from this worker (guest API 3):
+ * the host sends every consumer call on them here, under the caller's authority, and passes
+ * every change, event, and observable value bound for a subscriber through here first, under
+ * that subscriber's. Tools have their own handlers.
+ *
+ * Tables answer through their class (`PackageTable` or the package's subclass), so an override
+ * is the logic every caller gets. Observables read and write their source (or, for IR, the package variable they
+ * name). Events pass through unchanged. Rows passed to an override, returned, or sent, and
+ * observable values leave out the empty fields their schema lets them leave out, as stored
+ * rows and reads do. Subscriptions are accepted.
+ *
+ * @param contract - A contract the package provides.
+ * @param register - The worker's `registerHandler`.
+ */
+export declare function serveContractMembers(contract: IPackageContract, register: RegisterHandler): void;
+export {};

package/dist/define/serve-members.js

@@ -0,0 +1,152 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serveContractMembers = serveContractMembers;
+const contract_members_1 = require("../package-loader/contract-members");
+const empty_fields_1 = require("./empty-fields");
+const observables_1 = require("./observables");
+const vars_1 = require("./vars");
+const wire_value_1 = require("./wire-value");
+const TABLE_METHODS = new Set(["get", "list", "count", "findOne", "save", "delete"]);
+const SUBSCRIPTION_OPERATIONS = new Set(["subscribe", "unsubscribe"]);
+/**
+ * Serve one provided contract's tables, observables, and events from this worker (guest API 3):
+ * the host sends every consumer call on them here, under the caller's authority, and passes
+ * every change, event, and observable value bound for a subscriber through here first, under
+ * that subscriber's. Tools have their own handlers.
+ *
+ * Tables answer through their class (`PackageTable` or the package's subclass), so an override
+ * is the logic every caller gets. Observables read and write their source (or, for IR, the package variable they
+ * name). Events pass through unchanged. Rows passed to an override, returned, or sent, and
+ * observable values leave out the empty fields their schema lets them leave out, as stored
+ * rows and reads do. Subscriptions are accepted.
+ *
+ * @param contract - A contract the package provides.
+ * @param register - The worker's `registerHandler`.
+ */
+function serveContractMembers(contract, register) {
+    const tables = new Map();
+    for (const table of contract.tables)
+        tables.set(table.definition.name, table);
+    const observables = new Map();
+    for (const observable of contract.observables) {
+        observables.set((0, observables_1.isPackageObservable)(observable) ? observable.definition.name : observable.name, observable);
+    }
+    const events = new Set(contract.events.map((event) => ("definition" in event ? event.definition.name : event.name)));
+    const label = `${contract.name} (${contract.contractId}@${contract.version})`;
+    register((0, contract_members_1.contractMemberHandlerName)(contract.contractId, contract.version), async (raw, ctx) => {
+        const call = raw;
+        const args = Array.isArray(call.args) ? call.args : [];
+        if (call.member === "table") {
+            const table = tables.get(call.name);
+            if (!table)
+                throw new Error(`${label} has no table '${call.name}'`);
+            if (SUBSCRIPTION_OPERATIONS.has(call.operation))
+                return null;
+            if (!TABLE_METHODS.has(call.operation)) {
+                throw new Error(`Table method '${call.name}.${call.operation}' is not callable`);
+            }
+            const instance = table(ctx);
+            // An override sees the same missing fields as super.save, before it runs package code.
+            const input = call.operation === "save"
+                ? [(0, empty_fields_1.withoutEmptySchemaFields)(table.definition.schema, args[0]), ...args.slice(1)]
+                : args;
+            // An override's reply crosses the bridge, which carries no undefined fields, and leaves
+            // out empty fields as stored rows do.
+            const result = await instance[call.operation](...input);
+            return result === undefined ? null : (0, wire_value_1.snapshotPackageValue)(withoutEmptyRows(table, result));
+        }
+        if (call.member === "observable") {
+            const observable = observables.get(call.name);
+            if (!observable)
+                throw new Error(`${label} has no observable '${call.name}'`);
+            if (SUBSCRIPTION_OPERATIONS.has(call.operation))
+                return null;
+            if (call.operation === "get")
+                return readObservable(observable, ctx);
+            if (call.operation === "set")
+                return writeObservable(observable, args[0], ctx);
+            throw new Error(`Unsupported observable operation '${call.operation}' on '${call.name}'`);
+        }
+        if (call.member === "event") {
+            if (!events.has(call.name))
+                throw new Error(`${label} has no event '${call.name}'`);
+            if (SUBSCRIPTION_OPERATIONS.has(call.operation))
+                return null;
+            throw new Error(`Unsupported event operation '${call.operation}' on '${call.name}'`);
+        }
+        throw new Error(`Unsupported contract member '${String(call.member)}'`);
+    });
+    register((0, contract_members_1.contractDeliveryHandlerName)(contract.contractId, contract.version), async (raw, ctx) => {
+        const delivery = raw;
+        if (delivery.member === "table") {
+            const table = tables.get(delivery.name);
+            if (!table)
+                throw new Error(`${label} has no table '${delivery.name}'`);
+            const change = delivery.value;
+            const event = await table(ctx).dataChanged({
+                ...change,
+                dataObject: withoutEmptyRows(table, change.dataObject),
+            });
+            if (event === undefined || event === null)
+                return { send: false };
+            const dataObject = withoutEmptyRows(table, event.dataObject);
+            return { send: true, value: (0, wire_value_1.snapshotPackageValue)({ ...event, dataObject }) };
+        }
+        if (delivery.member === "observable") {
+            // A package variable's value comes from storage, which the package's own code or an
+            // older build may have written with empty fields: send it as a read returns it.
+            const observable = observables.get(delivery.name);
+            const schema = observable && (0, observables_1.isPackageObservable)(observable) && "schema" in observable.definition
+                ? observable.definition.schema
+                : undefined;
+            return { send: true, value: (0, empty_fields_1.withoutEmptySchemaFields)(schema, delivery.value) };
+        }
+        return { send: true, value: delivery.value };
+    });
+}
+/** A table reply (a row or a list of rows) without the empty fields its schema lets a row leave out. */
+function withoutEmptyRows(table, value) {
+    const { schema } = table.definition;
+    return Array.isArray(value)
+        ? value.map((row) => (0, empty_fields_1.withoutEmptySchemaFields)(schema, row))
+        : (0, empty_fields_1.withoutEmptySchemaFields)(schema, value);
+}
+/** The value a consumer reads: the source the package keeps, or the IR variable's stored value. */
+async function readObservable(observable, ctx) {
+    if ((0, observables_1.isPackageObservable)(observable)) {
+        const { definition } = observable;
+        const source = definition.source;
+        const schema = "schema" in definition ? definition.schema : undefined;
+        // A package variable may still be loading; its first value then comes from storage.
+        const value = observable.persistentVar ? await (0, vars_1.readPackageVar)(source) : source();
+        return (0, wire_value_1.snapshotPackageValue)((0, empty_fields_1.withoutEmptySchemaFields)(schema, value));
+    }
+    const binding = observable.persistentVar;
+    if (!binding)
+        throw new Error(`Observable '${observable.name}' has no source`);
+    const stored = await ctx.getOwnedPersistentVar(binding.scope, binding.name);
+    return stored === undefined || stored === null ? binding.defaultValue : stored;
+}
+/** A consumer's write, after the host checked that it's writable and fits the value type. */
+async function writeObservable(observable, value, ctx) {
+    if (!(0, observables_1.isPackageObservable)(observable)) {
+        const binding = observable.persistentVar;
+        if (!binding)
+            throw new Error(`Observable '${observable.name}' has no source`);
+        await ctx.setOwnedPersistentVar(binding.scope, binding.name, value);
+        return value;
+    }
+    const { definition } = observable;
+    if (!definition.writable)
+        throw new Error(`Observable '${definition.name}' is read-only`);
+    if (!observable.persistentVar) {
+        const write = (0, observables_1.inMemoryObservableWriter)(observable);
+        if (!write)
+            throw new Error(`Observable '${definition.name}' isn't served yet`);
+        return write(value);
+    }
+    const source = definition.source;
+    const schema = "schema" in definition ? definition.schema : undefined;
+    const next = schema ? schema.parse((0, empty_fields_1.withoutEmptySchemaFields)(schema, value)) : value;
+    return (0, wire_value_1.snapshotPackageValue)(await (0, vars_1.writePackageVar)(source, next));
+}

package/dist/define/serve-members.test.d.ts

@@ -0,0 +1 @@
+export {};