@peers-app/peers-sdk 0.26.5 → 0.27.0

package/dist/testing/mock-host-contract.js

@@ -0,0 +1,434 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mockHostContract = mockHostContract;
+const contract_proxy_1 = require("../contracts/contract-proxy");
+const contract_transport_1 = require("../contracts/contract-transport");
+const host_contract_client_1 = require("../contracts/host-contract-client");
+const host_contract_transport_1 = require("../contracts/host-contract-transport");
+const types_1 = require("../data/orm/types");
+const declare_contract_1 = require("../define/declare-contract");
+const define_package_1 = require("../define/define-package");
+const empty_fields_1 = require("../define/empty-fields");
+const manifest_1 = require("../define/manifest");
+const events_1 = require("../events");
+const observable_1 = require("../observable");
+const isolated_value_1 = require("../package-loader/isolated-value");
+const peer_id_1 = require("../peer-id");
+let active;
+/**
+ * Stand in for the local host in a UI test: `hostContract` clients for this contract (including
+ * a package's shared `news`-style client) connect to it, with no signed-in user and no
+ * provider. Tables hold rows in memory and send `dataChanged`; tools answer with fakes.
+ *
+ * ```ts
+ * const host = mockHostContract(News, {
+ *   tables: { Headlines: [{ headlineId: newid(), title: "Hello", ... }] },
+ *   tools: { refresh: async () => ({ errors: [] }) },
+ * });
+ * // render the UI; it reads and writes through `news` as usual
+ * await host.tables.Headlines.save(nextHeadline); // the UI sees the change
+ * host.dispose();
+ * ```
+ *
+ * A UI's table calls go through the table's class (`PackageTable` or the package's subclass),
+ * as on the host, with a test context: its `callOwnedTable` reaches the mock's rows, and its
+ * other calls fail. So a save runs the class's overrides and the schema, defaults included,
+ * and each change reaches subscribers through the class's `dataChanged`. Writes through
+ * `host.tables` are storage writes, with no class or schema in between; the class still
+ * filters the changes they send.
+ *
+ * Table filters are equality (`{ feedId }`) and `$in` (`{ status: { $in: ["a", "b"] } }`); a
+ * filter with other operators (`$or`, `$matchWords`, ...) or a text search fails; test those
+ * reads against a real host.
+ * `onCall` can delay or fail calls, but cannot replace their answers. Paging and `sortBy` work.
+ * Stored rows validate the manifest's fields, as host storage does. UI
+ * writes to an observable must fit its manifest value type, then any declared schema. Tool
+ * access levels aren't checked (UI calls act as the signed-in user); private tools refuse UI
+ * calls, as on the host. Disposing rejects calls still waiting for an answer. One mock host
+ * runs at a time.
+ *
+ * @param contract - The contract value from `defineContract` (tests can import it; UI code
+ *   imports only its type), or a declaration from `declareContract`, whose observables start
+ *   empty unless `observables` gives them values.
+ * @param options - Tool fakes, starting rows and values, data context, and a call hook.
+ */
+function mockHostContract(contract, options = {}) {
+    if (!(0, define_package_1.isPackageContract)(contract) && !(0, declare_contract_1.isContractDeclaration)(contract)) {
+        throw new Error("mockHostContract takes a contract from defineContract or declareContract");
+    }
+    // A declaration's members have no handlers or sources: fakes and start values stand in.
+    const members = ((0, define_package_1.isPackageContract)(contract) ? contract : contract.declaration);
+    if (active) {
+        throw new Error(`mockHostContract: a mock host for ${active.contractId} is still running; dispose it first`);
+    }
+    const { contractId, version } = members;
+    const fakes = (options.tools ?? {});
+    const startRows = (options.tables ?? {});
+    const startValues = (options.observables ?? {});
+    const tables = {};
+    for (const table of members.tables) {
+        const mock = mockTable(contractId, definitionOf(table), startRows[nameOf(table)] ?? []);
+        tables[mock.name] = mock;
+    }
+    for (const name of Object.keys(startRows)) {
+        if (!tables[name])
+            throw new Error(`mockHostContract: ${contractId} has no table '${name}'`);
+    }
+    // UI calls reach each table's class, as on the host; its storage calls reach these rows.
+    const providerContext = mockProviderContext(contractId, tables);
+    const servedTables = {};
+    for (const table of members.tables) {
+        const mock = tables[nameOf(table)];
+        servedTables[mock.name] =
+            typeof table === "function"
+                ? servedThroughClass(table, mock, providerContext)
+                : mock.source;
+    }
+    const tools = {};
+    for (const tool of members.tools) {
+        const definition = definitionOf(tool);
+        const name = definition.name;
+        tools[name] = {
+            tool: {
+                name,
+                usageDescription: definition.usageDescription ?? "",
+                // No access checks: there is no signed-in user, and UI calls act as the full user.
+                accessLevel: 0,
+            },
+            toolFn: async (input) => {
+                // The host lets only the owning package's checked dispatcher reach a private tool.
+                if (definition.private) {
+                    throw new Error(`mockHostContract: tool '${name}' is private; the host refuses UI calls`);
+                }
+                const fake = fakes[name];
+                if (!fake)
+                    throw new Error(`mockHostContract: no fake for tool '${name}'`);
+                const schema = definition.inputSchema;
+                const result = await fake(schema ? schema.parse((0, empty_fields_1.withoutEmptySchemaFields)(schema, input ?? {})) : input);
+                return (0, empty_fields_1.withoutEmptySchemaFields)(definition.outputSchema, result);
+            },
+        };
+    }
+    for (const name of Object.keys(fakes)) {
+        if (!tools[name])
+            throw new Error(`mockHostContract: ${contractId} has no tool '${name}'`);
+    }
+    const observables = {};
+    const servedObservables = {};
+    const observableWritability = {};
+    for (const member of members.observables) {
+        const definition = definitionOf(member);
+        const value = (0, observable_1.observable)(Object.hasOwn(startValues, definition.name)
+            ? startValues[definition.name]
+            : servedAtStart(member, definition));
+        observables[definition.name] = value;
+        servedObservables[definition.name] = checkedWrites(value, definition.name, definition.schema
+            ? (0, manifest_1.schemaValueType)(definition.name, definition.schema)
+            : definition.valueType, definition.schema);
+        observableWritability[definition.name] = definition.writable === true;
+    }
+    for (const name of Object.keys(startValues)) {
+        if (!Object.hasOwn(observables, name)) {
+            throw new Error(`mockHostContract: ${contractId} has no observable '${name}'`);
+        }
+    }
+    const events = {};
+    for (const member of members.events) {
+        const name = nameOf(member);
+        events[name] = new events_1.Emitter(`mock-host:${contractId}:${name}:${(0, peer_id_1.newid)()}`);
+    }
+    const [consumerSide, providerSide] = (0, contract_transport_1.inProcessTransportPair)();
+    const session = (0, contract_proxy_1.createContractProviderSession)({
+        contractId,
+        version,
+        // Only the methods a contract table serves over the wire, plus `dataChanged`.
+        tables: servedTables,
+        tools,
+        observables: servedObservables,
+        observableWritability,
+        events: Object.fromEntries(Object.entries(events).map(([name, e]) => [name, e.event])),
+    }, providerSide);
+    let disposed = false;
+    const disposedError = () => new Error(`Mock host for ${contractId} is disposed`);
+    const assertActive = () => {
+        if (disposed)
+            throw disposedError();
+    };
+    /** Rejects each call still waiting (on `onCall` or a fake) when the host is disposed. */
+    const waiting = new Set();
+    const untilDisposed = (answer) => new Promise((resolve, reject) => {
+        waiting.add(reject);
+        answer()
+            .then(resolve, reject)
+            .finally(() => waiting.delete(reject));
+    });
+    // Copy supported wire values without requiring structuredClone (absent in Jest's jsdom).
+    const transport = {
+        emit: async (channel, ...args) => {
+            // Disconnect cleanup is harmless even after the provider session has ended.
+            if (channel === contract_transport_1.CONTRACT_REQUEST_CHANNEL && args[0]?.operation === "unsubscribe" && disposed)
+                return;
+            assertActive();
+            return untilDisposed(async () => {
+                const sent = (0, isolated_value_1.copyIsolatedValue)(args);
+                if (channel === contract_transport_1.CONTRACT_REQUEST_CHANNEL && options.onCall) {
+                    const call = sent[0];
+                    await options.onCall({
+                        member: call.member,
+                        name: call.name,
+                        operation: call.operation,
+                        args: call.args ?? [],
+                    });
+                }
+                assertActive();
+                const answer = await consumerSide.emit(channel, ...sent);
+                assertActive();
+                return (0, isolated_value_1.copyIsolatedValue)(answer);
+            });
+        },
+        on: (channel, handler) => consumerSide.on(channel, (...args) => handler(...(0, isolated_value_1.copyIsolatedValue)(args))),
+    };
+    const dataContextId = options.dataContextId ?? (0, peer_id_1.newid)();
+    active = { contractId };
+    (0, host_contract_client_1.setDefaultHostDataContextId)(async () => dataContextId);
+    const unregister = (0, host_contract_transport_1.registerHostContractTransport)(transport);
+    return Object.freeze({
+        tables: Object.freeze(Object.fromEntries(Object.entries(tables).map(([name, t]) => [name, t.handle]))),
+        observables: Object.freeze({ ...observables }),
+        events: Object.freeze(Object.fromEntries(Object.entries(events).map(([name, emitter]) => [
+            name,
+            Object.freeze({
+                emit: async (payload) => {
+                    await emitter.emit(payload);
+                },
+            }),
+        ]))),
+        dispose: () => {
+            if (disposed)
+                return;
+            disposed = true;
+            for (const reject of [...waiting])
+                reject(disposedError());
+            waiting.clear();
+            unregister();
+            session.dispose();
+            (0, host_contract_client_1.setDefaultHostDataContextId)(undefined);
+            active = undefined;
+        },
+    });
+}
+/**
+ * The context a mock host's table classes run with: `callOwnedTable` reaches the mock's rows;
+ * anything else a class might call isn't available in a mock host.
+ */
+function mockProviderContext(contractId, tables) {
+    const callOwnedTable = async (tableName, operation, args = []) => {
+        const table = tables[tableName];
+        if (!table) {
+            throw new Error(`mockHostContract: ${contractId} has no table '${tableName}'; a mock host holds only its contract's tables`);
+        }
+        const method = table.source[operation];
+        if (typeof method !== "function") {
+            throw new Error(`mockHostContract: table '${tableName}' has no method '${operation}'`);
+        }
+        return method(...args);
+    };
+    return new Proxy({ callOwnedTable }, {
+        get(_target, property) {
+            if (property === "callOwnedTable")
+                return callOwnedTable;
+            if (typeof property !== "string" || property === "then")
+                return undefined;
+            return () => {
+                throw new Error(`mockHostContract: ctx.${property} isn't available in a mock host`);
+            };
+        },
+    });
+}
+/**
+ * A table as the host serves it from a guest API 3 provider: each call goes to the table's
+ * class, and each stored change passes through the class's `dataChanged`, in order.
+ */
+function servedThroughClass(table, mock, ctx) {
+    const instance = () => table(ctx);
+    const served = {
+        dataChanged: {
+            subscribe(handler) {
+                let active = true;
+                let tail = Promise.resolve();
+                const subscription = mock.source.dataChanged.subscribe((event) => {
+                    const snapshot = (0, isolated_value_1.copyIsolatedValue)(event);
+                    tail = tail.then(async () => {
+                        if (!active)
+                            return;
+                        try {
+                            const sent = await table(ctx).dataChanged(snapshot);
+                            if (active && sent !== undefined && sent !== null)
+                                await handler(sent);
+                        }
+                        catch (error) {
+                            console.error(`mockHostContract: '${mock.name}' dataChanged failed`, error);
+                        }
+                    });
+                });
+                return {
+                    unsubscribe() {
+                        active = false;
+                        subscription.unsubscribe();
+                    },
+                };
+            },
+        },
+    };
+    for (const method of ["get", "list", "count", "findOne", "save", "delete"]) {
+        served[method] = (...args) => instance()[method](...args);
+    }
+    return served;
+}
+/** A member's definition: `defineTable` and the rest keep it on `definition`; IR is the member. */
+function definitionOf(member) {
+    const value = member;
+    return value.definition ?? member;
+}
+function nameOf(member) {
+    return definitionOf(member).name;
+}
+/**
+ * An observable's value before anything writes it, as the host serves it: a stored one's
+ * default, or what an in-memory one's source holds, which its worker publishes when it starts.
+ */
+function servedAtStart(member, definition) {
+    const stored = member.persistentVar;
+    if (stored)
+        return (0, isolated_value_1.copyIsolatedValue)(stored.defaultValue);
+    const source = definition.source;
+    return typeof source === "function" ? (0, isolated_value_1.copyIsolatedValue)(source()) : undefined;
+}
+/**
+ * What the provider session serves for one observable: the host's value, with UI writes checked
+ * against the manifest's value type before any declared schema, so defaults and coercion
+ * cannot bypass the host's type check. The observable then keeps the parsed value, as the
+ * package does when the write reaches it (an optional field sent empty left out); IR
+ * declarations keep the value as sent. Reads and publications clean schema-described fields
+ * too, without changing the underlying source, as the package's dispatcher does.
+ */
+function checkedWrites(value, name, valueType, schema) {
+    const served = ((...args) => {
+        if (args.length === 0)
+            return (0, empty_fields_1.withoutEmptySchemaFields)(schema, value());
+        if (!(0, manifest_1.fitsValueType)(args[0], valueType)) {
+            throw new Error(`Observable '${name}' value must match ${valueType}`);
+        }
+        const parsed = schema ? schema.parse((0, empty_fields_1.withoutEmptySchemaFields)(schema, args[0])) : args[0];
+        return (0, empty_fields_1.withoutEmptySchemaFields)(schema, value(parsed));
+    });
+    served.subscribe = (subscriber) => value.subscribe((next) => subscriber((0, empty_fields_1.withoutEmptySchemaFields)(schema, next)));
+    served.notifySubscribers = value.notifySubscribers;
+    served.subscriberCount = value.subscriberCount;
+    return served;
+}
+function mockTable(contractId, definition, start) {
+    const name = definition.name;
+    const key = definition.primaryKeyName;
+    // Match isolated storage: the fields the manifest carries, never executable Zod defaults.
+    const fields = definition.schema ? (0, manifest_1.irFields)(definition.schema) : definition.fields;
+    const schema = (0, types_1.fieldsToSchema)(fields);
+    // As in host storage, an optional field that is null or undefined is left out.
+    const parse = (row) => {
+        const copied = (0, types_1.withoutEmptyFields)(fields, (0, isolated_value_1.copyIsolatedValue)(row));
+        return { ...schema.parse(copied), ...copied };
+    };
+    const rows = start.map(parse);
+    const changes = new events_1.Emitter(`mock-host:${contractId}:${name}:${(0, peer_id_1.newid)()}`);
+    const indexOf = (id) => rows.findIndex((row) => row[key] === id);
+    const query = (filter, params = {}) => {
+        for (const option of Object.keys(params)) {
+            if (!["page", "pageSize", "sortBy"].includes(option) && params[option] !== undefined) {
+                throw new Error(`mockHostContract: table '${name}' does not support query option '${option}'`);
+            }
+        }
+        const matched = rows.filter(matches(name, filter));
+        for (const field of [...(params.sortBy ?? [])].reverse()) {
+            const desc = field.startsWith("-");
+            const by = desc ? field.slice(1) : field;
+            matched.sort((a, b) => compare(a[by], b[by]) * (desc ? -1 : 1));
+        }
+        if (params.page || params.pageSize) {
+            const page = Math.round(params.page || 1);
+            const pageSize = Math.round(params.pageSize || 100);
+            return matched.slice(pageSize * (page - 1), pageSize * page);
+        }
+        return matched;
+    };
+    const save = async (record) => {
+        const row = parse(record);
+        const at = indexOf(row[key]);
+        if (at >= 0)
+            rows[at] = row;
+        else
+            rows.push(row);
+        await changes.emit({ dataObject: row, op: at >= 0 ? "update" : "insert", source: "local" });
+        return (0, isolated_value_1.copyIsolatedValue)(row);
+    };
+    const remove = async (target) => {
+        const id = target && typeof target === "object" ? target[key] : target;
+        const at = indexOf(id);
+        if (at < 0)
+            return;
+        const [row] = rows.splice(at, 1);
+        await changes.emit({ dataObject: row, op: "delete", source: "local" });
+    };
+    const methods = {
+        list: async (filter, params) => (0, isolated_value_1.copyIsolatedValue)(query(filter, params)),
+        get: async (id) => {
+            const at = indexOf(id);
+            return at >= 0 ? (0, isolated_value_1.copyIsolatedValue)(rows[at]) : undefined;
+        },
+        count: async (filter) => query(filter).length,
+        findOne: async (filter) => (0, isolated_value_1.copyIsolatedValue)(query(filter)[0]),
+        save,
+        delete: remove,
+    };
+    const handle = Object.freeze({
+        ...methods,
+        get rows() {
+            return (0, isolated_value_1.copyIsolatedValue)(rows);
+        },
+    });
+    return { name, source: { ...methods, dataChanged: changes.event }, handle };
+}
+/** Equality filters only: a filter with operators is refused rather than guessed at. */
+function matches(table, filter) {
+    if (filter === undefined || filter === null)
+        return () => true;
+    const tests = Object.entries(filter).map(([field, value]) => {
+        if (!field.startsWith("$")) {
+            if (value === null || typeof value !== "object" || value instanceof Date) {
+                return (row) => same(row[field], value);
+            }
+            const candidates = value.$in;
+            if (Object.keys(value).length === 1 && Array.isArray(candidates)) {
+                return (row) => candidates.some((candidate) => same(row[field], candidate));
+            }
+        }
+        throw new Error(`mockHostContract: table '${table}' supports equality and $in filters only, got ${JSON.stringify(filter)}`);
+    });
+    return (row) => tests.every((test) => test(row));
+}
+function same(a, b) {
+    // Optional fields are stored as SQL NULL, whether omitted or explicitly undefined.
+    if (a == null && b == null)
+        return true;
+    if (a instanceof Date && b instanceof Date)
+        return a.getTime() === b.getTime();
+    return a === b;
+}
+function compare(a, b) {
+    if (a === b)
+        return 0;
+    if (a === undefined || a === null)
+        return -1;
+    if (b === undefined || b === null)
+        return 1;
+    return a < b ? -1 : 1;
+}

package/dist/testing/mock-host-contract.test.d.ts

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