@peers-app/peers-sdk 0.26.5 → 0.27.0

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

@@ -0,0 +1,203 @@
+import type { IExposedContract } from "../contracts/types";
+import type { IIsolatedContractEvent, IIsolatedContractObservable, IIsolatedPackageNetwork } from "../package-loader/isolated-artifact";
+import type { IAppNav } from "../types/app-nav";
+import type { IPackageContext } from "./context";
+import type { IContractRef } from "./contract-ref";
+import type { IContractDeclaration } from "./declare-contract";
+import { type IPackageEvent } from "./events";
+import { type IPackageObservable, type IPackageObservableDeclaration } from "./observables";
+import type { IPackageTable } from "./table";
+import { type IPackageTool, type IPackageToolDeclaration } from "./tool";
+/**
+ * An observable on a provided contract: from `defineObservable`, or Peers IR (with its
+ * `persistentVar` binding) for a contract defined elsewhere.
+ */
+export type PackageContractObservable = IPackageObservable | IIsolatedContractObservable;
+/**
+ * An observable on a declared contract: from `declareObservable` (or `defineObservable`), or
+ * Peers IR.
+ */
+export type PackageContractObservableDeclaration = IPackageObservableDeclaration | IIsolatedContractObservable;
+/** An event on a provided contract: from `defineEvent`, or Peers IR for a contract defined elsewhere. */
+export type PackageContractEvent = IPackageEvent<any> | IIsolatedContractEvent;
+/** Options for {@link PackageBuilder.consumes}. */
+export interface IPackageConsumeOptions {
+    /** The package works without a provider; calls fail until one is installed. */
+    optional?: boolean;
+    /** Accept only these providers. */
+    providerPackageIds?: string[];
+    /** Fall back to the group's default provider when none of `providerPackageIds` is installed. */
+    fallbackToDefaultProvider?: boolean;
+}
+/** A contract the package consumes. */
+export interface IPackageConsumedContract extends IPackageConsumeOptions {
+    /** The reference handlers call it through. */
+    readonly ref: IContractRef<unknown>;
+}
+/**
+ * A contract version this contract also implements, so its consumers are served by this
+ * contract's handlers: an older version of the same contract, by number (the package's
+ * `frozen-contracts.json` gives its shape when the package builds), or another contract's
+ * declaration from `declareContract`. The contract's shape must satisfy each one.
+ */
+export type AlsoImplementsTarget = number | IContractDeclaration<any, any, any, any, any, any>;
+/** What {@link defineContract} takes. Omitted member lists are empty. */
+export interface IPackageContractDefinition<Id extends string = string, V extends number = number, Tables extends readonly IPackageTable<any>[] = readonly IPackageTable<any>[], Tools extends readonly IPackageTool<any, any>[] = readonly IPackageTool<any, any>[], Observables extends readonly PackageContractObservable[] = readonly PackageContractObservable[], Events extends readonly PackageContractEvent[] = readonly PackageContractEvent[]> {
+    /** The contract's id, from `newid()`. */
+    contractId: Id;
+    /** The contract's version, a positive integer. */
+    version: V;
+    /** Human-readable name. */
+    name: string;
+    /** What the contract is for. */
+    description?: string;
+    /** Tables the contract exposes. Each becomes one of the providing package's tables. */
+    tables?: Tables;
+    /** Tools the contract provides. */
+    tools?: Tools;
+    /** Observables the contract exposes, from `defineObservable` (or IR with a `persistentVar`). */
+    observables?: Observables;
+    /** Events the contract may emit, from `defineEvent` (or IR). */
+    events?: Events;
+    /**
+     * Older versions of this contract (by number) or other contracts (by declaration) whose
+     * consumers this contract's handlers also serve: a backwards-compatible change keeps serving
+     * the versions before it. Each must be satisfied by this contract's shape.
+     */
+    alsoImplements?: readonly AlsoImplementsTarget[];
+}
+/**
+ * A contract's id, version, and members: what a contract from {@link defineContract} and a
+ * declaration from `declareContract` share. Contract references are typed from it.
+ */
+export interface IContractMembers<Id extends string = string, V extends number = number, Tables extends readonly IPackageTable<any>[] = readonly IPackageTable<any>[], Tools extends readonly IPackageToolDeclaration<any, any>[] = readonly IPackageToolDeclaration<any, any>[], Observables extends readonly PackageContractObservableDeclaration[] = readonly PackageContractObservableDeclaration[], Events extends readonly PackageContractEvent[] = readonly PackageContractEvent[]> {
+    /** The contract's id. */
+    readonly contractId: Id;
+    /** The contract's version. */
+    readonly version: V;
+    /** Human-readable name. */
+    readonly name: string;
+    /** What the contract is for. */
+    readonly description?: string;
+    /** Tables the contract exposes. */
+    readonly tables: Readonly<Tables>;
+    /** Tools the contract provides. */
+    readonly tools: Readonly<Tools>;
+    /** Observables the contract exposes. */
+    readonly observables: Readonly<Observables>;
+    /** Events the contract may emit. */
+    readonly events: Readonly<Events>;
+}
+/**
+ * A contract declared with {@link defineContract}: its id, version, and members, implemented.
+ * A package provides it with `pkg.provides(contract)`. Its type carries every member's name and
+ * shape, so `contractRef<typeof Contract>(contractId, version)` gives consumers (the package's
+ * UIs, other packages) typed calls without importing the handlers.
+ */
+export interface IPackageContract<Id extends string = string, V extends number = number, Tables extends readonly IPackageTable<any>[] = readonly IPackageTable<any>[], Tools extends readonly IPackageTool<any, any>[] = readonly IPackageTool<any, any>[], Observables extends readonly PackageContractObservable[] = readonly PackageContractObservable[], Events extends readonly PackageContractEvent[] = readonly PackageContractEvent[]> extends IContractMembers<Id, V, Tables, Tools, Observables, Events> {
+    /** Marks a provided contract. */
+    readonly kind: "contract";
+    /**
+     * Other contracts the package provides whose tools this contract's consumers may call on it,
+     * from `implementContract(declaration, { exposes })`. Not part of the contract's shape.
+     */
+    readonly exposes?: readonly IExposedContract[];
+    /** Contract versions this contract also implements (see {@link AlsoImplementsTarget}). */
+    readonly alsoImplements?: readonly AlsoImplementsTarget[];
+}
+/**
+ * Declare a contract: its id, version, name, and the tables, tools, observables, and events it
+ * exposes. Export it from `src/package.ts` and provide it with `pkg.provides(contract)`; a UI or
+ * another package references it with `contractRef<typeof Contract>(contractId, version)`.
+ *
+ * @param definition - Id, version, name, description, and members.
+ */
+export declare function defineContract<Id extends string, V extends number, Tables extends readonly IPackageTable<any>[] = [], Tools extends readonly IPackageTool<any, any>[] = [], Observables extends readonly PackageContractObservable[] = [], Events extends readonly PackageContractEvent[] = []>(definition: IPackageContractDefinition<Id, V, Tables, Tools, Observables, Events>): IPackageContract<Id, V, Tables, Tools, Observables, Events>;
+/**
+ * True for a contract from {@link defineContract}.
+ *
+ * @param value - What was passed to `pkg.provides`.
+ */
+export declare function isPackageContract(value: unknown): value is IPackageContract;
+/**
+ * Everything the Runtime needs to know about a package: its tools, events, observables, and
+ * tables, the contracts it provides, and the contracts it consumes. `peers-package` turns it
+ * into the manifest; inside the worker, `servePackage` registers its tools.
+ */
+export interface IPackageDefinition {
+    /** Marks a package definition. */
+    readonly kind: "package";
+    readonly packageId: string;
+    readonly version: string;
+    /** `sandbox` (the default) or `privileged`. */
+    readonly executionMode?: "sandbox" | "privileged";
+    /** Hosts System HTTP may reach for this package, and its credentials. */
+    readonly network?: IIsolatedPackageNetwork;
+    readonly appNavs: readonly IAppNav[];
+    /** Every table the package owns: private ones and the ones its contracts expose. */
+    readonly tables: readonly IPackageTable[];
+    readonly provides: readonly IPackageContract[];
+    readonly consumes: readonly IPackageConsumedContract[];
+    /** Run when the package's worker starts, in the order they were added. */
+    readonly startHooks: readonly PackageStartHook[];
+}
+/**
+ * Background work for when the package's worker starts. Its `ctx` belongs to no call: it can use
+ * the package's own tables and variables, but calls to other contracts are refused.
+ */
+export type PackageStartHook = (ctx: IPackageContext) => unknown;
+/** The builder {@link definePackage} passes its callback. */
+export declare class PackageBuilder {
+    /** The package's id, from `newid()`. */
+    packageId: string;
+    /** The package's version, usually from `package.json`. */
+    version: string;
+    /** `sandbox` (the default) or `privileged`, which needs an operator's trust. */
+    executionMode?: "sandbox" | "privileged";
+    /** Hosts System HTTP may reach for this package. */
+    network?: IIsolatedPackageNetwork;
+    /** Entries in the app's navigation. */
+    appNavs: IAppNav[];
+    /** Tables only this package uses. Tables a contract exposes don't need listing here. */
+    tables: IPackageTable<any>[];
+    private readonly provided;
+    private readonly consumed;
+    private readonly starts;
+    /**
+     * Run `fn` each time the package's worker starts, after the package's variables load and
+     * before its in-memory observables publish, so a value set here is the first one readers
+     * see. The worker waits for it, and a failure fails the start, so catch what can fail and
+     * don't await long-running work.
+     *
+     * `ctx` belongs to no call: use it for the package's own tables, and to watch or load
+     * state. Calls to other contracts, such as System HTTP, are refused outside a call; to fetch
+     * in the background, schedule one of the package's own tools with System Scheduler.
+     *
+     * @param fn - Called with the worker's `ctx`.
+     */
+    onStart(fn: PackageStartHook): void;
+    /**
+     * Provide a contract: this package serves its tools and holds its tables, observables, and
+     * events.
+     *
+     * @param contract - From {@link defineContract}.
+     */
+    provides(contract: IPackageContract<any, any, any, any, any, any>): void;
+    /**
+     * Consume a contract another package provides. Handlers call it through `ref(ctx)`.
+     *
+     * @param ref - From `contractRef(contractId, version)`.
+     * @param options - Optional dependency and provider selection.
+     */
+    consumes(ref: IContractRef<any>, options?: IPackageConsumeOptions): void;
+    /** @internal Check and freeze the definition. */
+    _build(): IPackageDefinition;
+}
+/**
+ * Declare a package: the contracts it provides (from {@link defineContract}), the contracts it
+ * consumes, and its private tables. Export the result as the default export of
+ * `src/package.ts`.
+ *
+ * @param fn - Fills in the {@link PackageBuilder}.
+ */
+export declare function definePackage(fn: (pkg: PackageBuilder) => void): IPackageDefinition;

package/dist/define/define-package.js

@@ -0,0 +1,289 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PackageBuilder = void 0;
+exports.defineContract = defineContract;
+exports.isPackageContract = isPackageContract;
+exports.definePackage = definePackage;
+const peer_id_1 = require("../peer-id");
+const events_1 = require("./events");
+const observables_1 = require("./observables");
+const tool_1 = require("./tool");
+/**
+ * Declare a contract: its id, version, name, and the tables, tools, observables, and events it
+ * exposes. Export it from `src/package.ts` and provide it with `pkg.provides(contract)`; a UI or
+ * another package references it with `contractRef<typeof Contract>(contractId, version)`.
+ *
+ * @param definition - Id, version, name, description, and members.
+ */
+function defineContract(definition) {
+    const { contractId, version, name, description } = definition ?? {};
+    if (typeof name !== "string" || name.trim() === "") {
+        throw new Error("defineContract requires a name");
+    }
+    const label = `Contract ${name} (${contractId}@${version})`;
+    if (!(0, peer_id_1.isid)(contractId)) {
+        throw new Error(`${label} needs a 25-character contract id from newid()`);
+    }
+    if (!Number.isInteger(version) || version < 1) {
+        throw new Error(`${label} version must be a positive integer`);
+    }
+    if (description !== undefined && typeof description !== "string") {
+        throw new Error(`${label} description must be a string`);
+    }
+    const members = (list, what) => {
+        if (list === undefined) {
+            return [];
+        }
+        if (!Array.isArray(list)) {
+            throw new Error(`${label} ${what} must be an array`);
+        }
+        return list;
+    };
+    const alsoImplements = alsoImplementsTargets(definition.alsoImplements, contractId, version, label);
+    const tables = members(definition.tables, "tables");
+    const tools = members(definition.tools, "tools");
+    const observables = members(definition.observables, "observables");
+    const events = members(definition.events, "events");
+    const unique = (names, kind, memberName) => {
+        if (names.has(memberName)) {
+            throw new Error(`${label} declares ${kind} "${memberName}" twice`);
+        }
+        names.add(memberName);
+    };
+    const tableNames = new Set();
+    for (const table of tables) {
+        if (table?.kind !== "table") {
+            throw new Error(`${label} lists something that isn't a table from defineTable`);
+        }
+        unique(tableNames, "table", table.definition.name);
+    }
+    const toolNames = new Set();
+    for (const tool of tools) {
+        if (tool?.kind !== "tool") {
+            throw new Error(`${label} lists something that isn't a tool from defineTool`);
+        }
+        if (!(0, tool_1.isImplementedTool)(tool)) {
+            throw new Error(`${label} tool "${tool.definition.name}" has no handler; to declare a contract other packages implement, use declareContract and implementContract`);
+        }
+        unique(toolNames, "tool", tool.definition.name);
+    }
+    const observableNames = new Set();
+    for (const observable of observables) {
+        const observableName = (0, observables_1.isPackageObservable)(observable)
+            ? observable.definition.name
+            : observable?.name;
+        if (typeof observableName !== "string") {
+            throw new Error(`${label} lists an observable that isn't from defineObservable or Peers IR`);
+        }
+        if (!(0, observables_1.isPackageObservable)(observable) && !observable.persistentVar) {
+            throw new Error(`${label} observable "${observableName}" is IR without a persistentVar; declare an in-memory observable with defineObservable`);
+        }
+        if ((0, observables_1.isPackageObservable)(observable) && !(0, observables_1.isImplementedObservable)(observable)) {
+            throw new Error(`${label} observable "${observableName}" has no source; to declare a contract other packages implement, use declareContract and implementContract`);
+        }
+        unique(observableNames, "observable", observableName);
+    }
+    const eventNames = new Set();
+    for (const event of events) {
+        const eventName = (0, events_1.isPackageEvent)(event)
+            ? event.definition.name
+            : event?.name;
+        if (typeof eventName !== "string") {
+            throw new Error(`${label} lists an event that isn't from defineEvent or Peers IR`);
+        }
+        unique(eventNames, "event", eventName);
+    }
+    return Object.freeze({
+        kind: "contract",
+        contractId,
+        version,
+        name,
+        ...(description === undefined ? {} : { description }),
+        tables: Object.freeze([...tables]),
+        tools: Object.freeze([...tools]),
+        observables: Object.freeze([...observables]),
+        events: Object.freeze([...events]),
+        ...(alsoImplements.length ? { alsoImplements: Object.freeze(alsoImplements) } : {}),
+    });
+}
+/** Check a contract's `alsoImplements`: older versions by number, or other contracts' declarations. */
+function alsoImplementsTargets(value, contractId, version, label) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value)) {
+        throw new Error(`${label} alsoImplements must be a list of versions or declarations`);
+    }
+    const seen = new Set();
+    return value.map((target) => {
+        let key;
+        if (typeof target === "number") {
+            if (!Number.isInteger(target) || target < 1) {
+                throw new Error(`${label} alsoImplements version ${target} must be a positive integer`);
+            }
+            key = `${contractId}@${target}`;
+        }
+        else {
+            const declaration = target;
+            if (declaration?.kind !== "contract-ref" ||
+                declaration.declaration?.kind !== "contract-declaration") {
+                throw new Error(`${label} alsoImplements takes version numbers and declarations from declareContract`);
+            }
+            key = `${declaration.contractId}@${declaration.version}`;
+        }
+        if (key === `${contractId}@${version}`) {
+            throw new Error(`${label} can't also implement itself`);
+        }
+        // Its own older versions come from frozen-contracts.json, the shapes its releases froze.
+        if (typeof target !== "number" && target.contractId === contractId) {
+            throw new Error(`${label} alsoImplements takes its own contract's older versions by number, not by declaration`);
+        }
+        if (typeof target === "number" && target > version) {
+            throw new Error(`${label} alsoImplements v${target} must be older than v${version}`);
+        }
+        if (seen.has(key)) {
+            throw new Error(`${label} also implements ${key} twice`);
+        }
+        seen.add(key);
+        return target;
+    });
+}
+/**
+ * True for a contract from {@link defineContract}.
+ *
+ * @param value - What was passed to `pkg.provides`.
+ */
+function isPackageContract(value) {
+    return value?.kind === "contract";
+}
+/** The builder {@link definePackage} passes its callback. */
+class PackageBuilder {
+    /** The package's id, from `newid()`. */
+    packageId = "";
+    /** The package's version, usually from `package.json`. */
+    version = "";
+    /** `sandbox` (the default) or `privileged`, which needs an operator's trust. */
+    executionMode;
+    /** Hosts System HTTP may reach for this package. */
+    network;
+    /** Entries in the app's navigation. */
+    appNavs = [];
+    /** Tables only this package uses. Tables a contract exposes don't need listing here. */
+    tables = [];
+    provided = [];
+    consumed = [];
+    starts = [];
+    /**
+     * Run `fn` each time the package's worker starts, after the package's variables load and
+     * before its in-memory observables publish, so a value set here is the first one readers
+     * see. The worker waits for it, and a failure fails the start, so catch what can fail and
+     * don't await long-running work.
+     *
+     * `ctx` belongs to no call: use it for the package's own tables, and to watch or load
+     * state. Calls to other contracts, such as System HTTP, are refused outside a call; to fetch
+     * in the background, schedule one of the package's own tools with System Scheduler.
+     *
+     * @param fn - Called with the worker's `ctx`.
+     */
+    onStart(fn) {
+        if (typeof fn !== "function") {
+            throw new Error("pkg.onStart takes a function");
+        }
+        this.starts.push(fn);
+    }
+    /**
+     * Provide a contract: this package serves its tools and holds its tables, observables, and
+     * events.
+     *
+     * @param contract - From {@link defineContract}.
+     */
+    provides(contract) {
+        if (!isPackageContract(contract)) {
+            throw new Error(contract?.declaration
+                ? "pkg.provides takes a contract: implement a declaration with implementContract first"
+                : "pkg.provides takes a contract from defineContract or implementContract");
+        }
+        this.provided.push(contract);
+    }
+    /**
+     * Consume a contract another package provides. Handlers call it through `ref(ctx)`.
+     *
+     * @param ref - From `contractRef(contractId, version)`.
+     * @param options - Optional dependency and provider selection.
+     */
+    consumes(ref, options = {}) {
+        this.consumed.push({ ref, ...options });
+    }
+    /** @internal Check and freeze the definition. */
+    _build() {
+        if (!(0, peer_id_1.isid)(this.packageId)) {
+            throw new Error(`packageId must be a 25-character peer id from newid(), got "${this.packageId}"`);
+        }
+        if (typeof this.version !== "string" || this.version.trim() === "") {
+            throw new Error("A package must set version");
+        }
+        const tables = new Map();
+        const addTable = (table, where) => {
+            if (table?.kind !== "table") {
+                throw new Error(`${where} lists something that isn't a table from defineTable`);
+            }
+            const existing = tables.get(table.definition.name);
+            if (existing && existing !== table) {
+                throw new Error(`Two different tables are named "${table.definition.name}"`);
+            }
+            tables.set(table.definition.name, table);
+        };
+        for (const table of this.tables) {
+            addTable(table, "pkg.tables");
+        }
+        const contractKeys = new Set();
+        for (const contract of this.provided) {
+            const key = `${contract.contractId}@${contract.version}`;
+            if (contractKeys.has(key)) {
+                throw new Error(`Contract ${contract.name} (${key}) is provided twice`);
+            }
+            contractKeys.add(key);
+            for (const table of contract.tables) {
+                addTable(table, `Contract ${contract.name} (${key})`);
+            }
+        }
+        const provides = [...this.provided];
+        for (const contract of provides) {
+            for (const exposed of contract.exposes ?? []) {
+                const exposedKey = `${exposed.contractId}@${exposed.version}`;
+                if (!contractKeys.has(exposedKey)) {
+                    throw new Error(`Contract ${contract.name} (${contract.contractId}@${contract.version}) exposes ${exposedKey}, which the package doesn't provide; add it with pkg.provides`);
+                }
+            }
+        }
+        for (const { ref } of this.consumed) {
+            if (ref?.kind !== "contract-ref") {
+                throw new Error("pkg.consumes takes a reference from contractRef(contractId, version)");
+            }
+        }
+        return Object.freeze({
+            kind: "package",
+            packageId: this.packageId,
+            version: this.version,
+            ...(this.executionMode === undefined ? {} : { executionMode: this.executionMode }),
+            ...(this.network === undefined ? {} : { network: this.network }),
+            appNavs: Object.freeze([...this.appNavs]),
+            tables: Object.freeze([...tables.values()]),
+            provides: Object.freeze(provides),
+            consumes: Object.freeze(this.consumed.map((consumed) => Object.freeze({ ...consumed }))),
+            startHooks: Object.freeze([...this.starts]),
+        });
+    }
+}
+exports.PackageBuilder = PackageBuilder;
+/**
+ * Declare a package: the contracts it provides (from {@link defineContract}), the contracts it
+ * consumes, and its private tables. Export the result as the default export of
+ * `src/package.ts`.
+ *
+ * @param fn - Fills in the {@link PackageBuilder}.
+ */
+function definePackage(fn) {
+    const pkg = new PackageBuilder();
+    fn(pkg);
+    return pkg._build();
+}

package/dist/define/define.test.d.ts

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