@peers-app/peers-sdk 0.26.6 → 0.27.0

package/dist/define/declare-contract.js

@@ -0,0 +1,220 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.declareContract = declareContract;
+exports.implementContract = implementContract;
+exports.isContractDeclaration = isContractDeclaration;
+const peer_id_1 = require("../peer-id");
+const contract_ref_1 = require("./contract-ref");
+const define_package_1 = require("./define-package");
+const observables_1 = require("./observables");
+const tool_1 = require("./tool");
+/**
+ * Declare a contract's shape without providing it: its id, version, name, and the tables,
+ * tools, observables, and events it exposes, with no handlers. Use it for a contract several
+ * packages implement (Voice Skill, which every skill provides). Each provider implements it
+ * with {@link implementContract}; consumers use the declaration itself as the reference.
+ *
+ * Tools come from `declareTool` and observables from `declareObservable`: `defineTool` and
+ * `defineObservable` without the handler or source. Events (`defineEvent`) and tables
+ * (`defineTable`) are listed as they are; a table can't have a `tableClass` here.
+ *
+ * @param definition - Id, version, name, description, and members.
+ */
+function declareContract(definition) {
+    const { contractId, version, name } = definition ?? {};
+    const label = `Contract ${name} (${contractId}@${version})`;
+    const members = (list, what) => {
+        if (list === undefined) {
+            return [];
+        }
+        if (!Array.isArray(list)) {
+            throw new Error(`${label} ${what} must be an array`);
+        }
+        return list;
+    };
+    for (const tool of members(definition?.tools, "tools")) {
+        if (tool?.kind !== "tool") {
+            throw new Error(`${label} lists something that isn't a tool from declareTool`);
+        }
+        if ((0, tool_1.isImplementedTool)(tool)) {
+            throw new Error(`${label} tool "${tool.definition.name}" has a handler; a declaration lists tools from declareTool`);
+        }
+    }
+    for (const observable of members(definition?.observables, "observables")) {
+        if (!(0, observables_1.isPackageObservable)(observable)) {
+            throw new Error(`${label} lists an observable that isn't from declareObservable`);
+        }
+        if ((0, observables_1.isImplementedObservable)(observable)) {
+            throw new Error(`${label} observable "${observable.definition.name}" has a source; a declaration lists observables from declareObservable`);
+        }
+    }
+    for (const table of members(definition?.tables, "tables")) {
+        if (table?.kind === "table" && table.definition.tableClass !== undefined) {
+            throw new Error(`${label} table "${table.definition.name}" has a tableClass; a declaration's tables have none`);
+        }
+    }
+    // The same checks as a provided contract: id, version, names, and member kinds. Handlers and
+    // sources are checked above; a placeholder stands in for each so the checks can run.
+    checkMembers(definition);
+    const declaration = Object.freeze({
+        kind: "contract-declaration",
+        contractId,
+        version,
+        name,
+        ...(definition.description === undefined ? {} : { description: definition.description }),
+        tables: Object.freeze([...members(definition.tables, "tables")]),
+        tools: Object.freeze([...members(definition.tools, "tools")]),
+        observables: Object.freeze([...members(definition.observables, "observables")]),
+        events: Object.freeze([...members(definition.events, "events")]),
+    });
+    return (0, contract_ref_1.createContractRef)(contractId, version, { declaration });
+}
+/** Run {@link defineContract}'s checks on a declaration, with stand-in handlers and sources. */
+function checkMembers(definition) {
+    const handler = () => undefined;
+    const source = Object.assign(() => undefined, { subscribe: () => ({ dispose() { } }) });
+    (0, define_package_1.defineContract)({
+        contractId: definition.contractId,
+        version: definition.version,
+        name: definition.name,
+        description: definition.description,
+        tables: definition.tables,
+        tools: (definition.tools ?? []).map((tool) => Object.freeze({ ...tool, definition: { ...tool.definition, handler } })),
+        observables: (definition.observables ?? []).map((observable) => Object.freeze({ ...observable, definition: { ...observable.definition, source } })),
+        events: definition.events,
+    });
+}
+/**
+ * Implement a declared contract: a handler for each of its tools and a source for each of its
+ * observables, by name. Returns the contract for `pkg.provides`, as {@link defineContract}
+ * would; its manifest shape comes from the declaration, so it can't drift from it.
+ *
+ * ```ts
+ * export const TimersVoiceSkill = implementContract(VoiceSkill, {
+ *   tools: { invoke: async ({ tool, args }, ctx) => ({ speech: "Done." }) },
+ *   observables: { skill: deviceVar<VoiceSkillCatalog>("skill", { defaultValue: catalog }) },
+ * });
+ * pkg.provides(TimersVoiceSkill);
+ * ```
+ *
+ * A tool's entry may also set this provider's deadline: `{ handler, timeoutMs }`. The
+ * declaration's events are emitted with their own `emit`.
+ *
+ * For a hub's contract, `exposes` lists other contracts the package provides whose tools the
+ * hub contract's consumers may call on this provider: `exposes: [News]`. Each must also be in
+ * `pkg.provides`. The hub reaches only their tools, each at its own access level, as the user.
+ *
+ * @param declaration - From {@link declareContract}.
+ * @param implementation - Handlers and sources, by member name, and the contracts it exposes.
+ */
+function implementContract(declaration, implementation) {
+    const members = declaration
+        ?.declaration;
+    if (declaration?.kind !== "contract-ref" || members?.kind !== "contract-declaration") {
+        throw new Error("implementContract takes a declaration from declareContract");
+    }
+    const label = `Contract ${members.name} (${members.contractId}@${members.version})`;
+    const given = (implementation ?? {});
+    for (const key of Object.keys(given)) {
+        if (!["tools", "observables", "exposes", "alsoImplements"].includes(key)) {
+            throw new Error(`${label}: implementContract takes tools, observables, exposes, and alsoImplements, not ${key}`);
+        }
+    }
+    const exposes = exposedContracts(given.exposes, members, label);
+    const entries = (what, declared) => {
+        const map = given[what] ?? {};
+        if (typeof map !== "object" || Array.isArray(map)) {
+            throw new Error(`${label}: implementation ${what} must be an object by name`);
+        }
+        for (const name of Object.keys(map)) {
+            if (!declared.includes(name)) {
+                throw new Error(`${label} declares no ${what === "tools" ? "tool" : "observable"} "${name}"`);
+            }
+        }
+        return map;
+    };
+    const toolNames = members.tools.map((tool) => tool.definition.name);
+    const handlers = entries("tools", toolNames);
+    const tools = members.tools.map((tool) => {
+        const { name } = tool.definition;
+        const entry = Object.hasOwn(handlers, name) ? handlers[name] : undefined;
+        const { handler, timeoutMs, ...rest } = typeof entry === "function"
+            ? { handler: entry, timeoutMs: undefined }
+            : (entry ?? {});
+        if (typeof handler !== "function") {
+            throw new Error(`${label}: implement tool "${name}" with a handler`);
+        }
+        if (Object.keys(rest).length > 0) {
+            throw new Error(`${label} tool "${name}": an implementation sets handler and timeoutMs only, not ${Object.keys(rest).join(", ")}`);
+        }
+        return tool_1.defineTool({
+            ...tool.definition,
+            ...(timeoutMs === undefined ? {} : { timeoutMs }),
+            handler,
+        });
+    });
+    const observableNames = members.observables.map((observable) => observable.definition.name);
+    const sources = entries("observables", observableNames);
+    const observables = members.observables.map((member) => {
+        const observable = member;
+        const { name } = observable.definition;
+        const source = Object.hasOwn(sources, name) ? sources[name] : undefined;
+        if (source === undefined) {
+            throw new Error(`${label}: implement observable "${name}" with a source`);
+        }
+        return observables_1.defineObservable({
+            ...observable.definition,
+            source,
+        });
+    });
+    const contract = (0, define_package_1.defineContract)({
+        contractId: members.contractId,
+        version: members.version,
+        name: members.name,
+        ...(members.description === undefined ? {} : { description: members.description }),
+        tables: members.tables,
+        tools,
+        observables,
+        events: members.events,
+        ...(given.alsoImplements === undefined
+            ? {}
+            : { alsoImplements: given.alsoImplements }),
+    });
+    return (exposes.length
+        ? Object.freeze({ ...contract, exposes: Object.freeze(exposes) })
+        : contract);
+}
+/** Check an implementation's `exposes` and keep each contract's id and version. */
+function exposedContracts(value, members, label) {
+    if (value === undefined) {
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        throw new Error(`${label}: exposes must be a list of contracts`);
+    }
+    const seen = new Set();
+    return value.map((item) => {
+        const { contractId, version } = item ?? {};
+        if (!(0, peer_id_1.isid)(contractId) || !Number.isInteger(version) || version < 1) {
+            throw new Error(`${label}: exposes takes contracts (or their references) with an id and version`);
+        }
+        const key = `${contractId}@${version}`;
+        if (key === `${members.contractId}@${members.version}`) {
+            throw new Error(`${label} can't expose itself`);
+        }
+        if (seen.has(key)) {
+            throw new Error(`${label} exposes ${key} twice`);
+        }
+        seen.add(key);
+        return Object.freeze({ contractId: contractId, version: version });
+    });
+}
+/**
+ * True for a declaration from {@link declareContract}.
+ *
+ * @param value - A contract reference, contract, or anything else.
+ */
+function isContractDeclaration(value) {
+    return (value?.kind === "contract-ref" &&
+        value.declaration?.kind === "contract-declaration");
+}

package/dist/define/declare-contract.test.d.ts

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