@peers-app/peers-sdk 0.26.6 → 0.27.1

package/dist/package-build/contract-source.js

@@ -0,0 +1,471 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.contractSourceFromManifest = contractSourceFromManifest;
+exports.contractSourceFromDefinition = contractSourceFromDefinition;
+exports.parseContractSelector = parseContractSelector;
+exports.generateContractDeclaration = generateContractDeclaration;
+const access_level_1 = require("../data/access-level");
+const field_type_1 = require("../types/field-type");
+const RESERVED_NAMES = new Set([
+    ..."await break case catch class const continue debugger default delete do else enum export extends false finally for function if implements import in instanceof interface let new null package private protected public return static super switch this throw true try typeof var void while with yield".split(" "),
+    "AccessLevel",
+    "arguments",
+    "ContractEventPayloadsOf",
+    "ContractObservableValuesOf",
+    "ContractTableRowsOf",
+    "FieldType",
+    "Uint8Array",
+    "declareContract",
+    "declareObservable",
+    "declareTool",
+    "defineEvent",
+    "defineTable",
+    "eval",
+    "generatedField",
+    "z",
+    "zodPeerId",
+]);
+/**
+ * The contract in a provider's manifest, by `contractId@version` (or the only one).
+ *
+ * @param manifest - A package's manifest.
+ * @param selector - `contractId@version`; optional when the package provides one contract.
+ */
+function contractSourceFromManifest(manifest, selector) {
+    const provided = manifest.provides ?? [];
+    const wanted = selector ? parseContractSelector(selector) : undefined;
+    const matches = wanted
+        ? provided.filter((contract) => contract.contractId === wanted.contractId && contract.version === wanted.version)
+        : provided;
+    if (matches.length !== 1) {
+        const listed = provided.map((contract) => `${contract.contractId}@${contract.version}`);
+        throw new Error(wanted
+            ? `The manifest doesn't provide ${selector}; it provides ${listed.join(", ") || "nothing"}`
+            : `The manifest provides ${listed.length} contracts; choose one with --contract ${listed[0] ?? "<id>@<version>"}`);
+    }
+    const [contract] = matches;
+    const tables = (contract.tables ?? []).map((ref) => {
+        const table = (manifest.tables ?? []).find((candidate) => candidate.name === ref.name);
+        if (!table) {
+            throw new Error(`The manifest's contract lists table "${ref.name}" but doesn't define it`);
+        }
+        return table;
+    });
+    return { contract, tables };
+}
+/**
+ * A registered contract definition, with the active provider's tool policy, as the generator
+ * reads it.
+ *
+ * @param input - `getContractDefinition`'s result.
+ */
+function contractSourceFromDefinition(input) {
+    const { definition } = input ?? {};
+    if (!definition ||
+        typeof definition.contractId !== "string" ||
+        !Array.isArray(definition.tools)) {
+        throw new Error("Expected getContractDefinition's result: { definition, tools }");
+    }
+    const policy = new Map((input.tools ?? []).map((tool) => [tool.name, tool]));
+    const tools = definition.tools.map((tool) => {
+        const toolPolicy = policy.get(tool.name);
+        if (toolPolicy?.accessLevel === undefined) {
+            throw new Error(input.tools
+                ? `The Runtime reported no access level for tool "${tool.name}" (is its active provider loaded?); generate from that provider's manifest or artifact instead`
+                : `Tool "${tool.name}" has no access level in the definition; generate from getContractDefinition's result, which carries the active provider's`);
+        }
+        return {
+            name: tool.name,
+            usageDescription: tool.usageDescription,
+            inputFields: tool.inputFields,
+            outputFields: tool.outputFields,
+            suggestedAccessLevel: toolPolicy.accessLevel,
+            ...(toolPolicy.authorityPropagation
+                ? { authorityPropagation: toolPolicy.authorityPropagation }
+                : {}),
+            ...(tool.remoteAccessLevel === undefined
+                ? {}
+                : { remoteAccessLevel: tool.remoteAccessLevel }),
+        };
+    });
+    return {
+        contract: {
+            contractId: definition.contractId,
+            version: definition.version,
+            name: definition.name,
+            ...(definition.description ? { description: definition.description } : {}),
+            tools,
+            ...(definition.tables?.length
+                ? { tables: definition.tables.map((table) => ({ name: table.name })) }
+                : {}),
+            ...(definition.observables?.length ? { observables: definition.observables } : {}),
+            ...(definition.events?.length ? { events: definition.events } : {}),
+        },
+        tables: (definition.tables ?? []).map((table) => ({
+            name: table.name,
+            description: table.description,
+            primaryKeyName: table.primaryKeyName,
+            fields: table.fields,
+        })),
+    };
+}
+/**
+ * Parse `contractId@version`.
+ *
+ * @param selector - The contract's id and version.
+ */
+function parseContractSelector(selector) {
+    const match = /^([0-9a-z]{25})@([1-9][0-9]*)$/i.exec(selector);
+    if (!match || !Number.isSafeInteger(Number(match[2]))) {
+        throw new Error(`Expected <contractId>@<version>, got "${selector}"`);
+    }
+    return { contractId: match[1], version: Number(match[2]) };
+}
+/**
+ * Write a contract's declaration as TypeScript: a `declareContract(...)` call whose zod schemas
+ * give the same IR, for a package that implements or calls a contract it doesn't own. The file
+ * is meant to be checked in and regenerated, not edited.
+ *
+ * What the IR carries comes through: names, types, optional fields, arrays, nested object
+ * fields, enum and literal values, descriptions, and each tool's access level and authority
+ * propagation. Refinements (a regex, a minimum) and defaults made by code aren't in the IR, so
+ * generated schemas check only what the IR describes. Objects keep keys their fields don't list.
+ *
+ * @param input - The contract and its tables.
+ * @param options - Where it came from (for the file's header), and an export name to use
+ *   instead of the one made from the contract's name.
+ */
+function generateContractDeclaration(input, options) {
+    const { contract, tables } = input;
+    assertVersion(contract.version, "Contract version");
+    const exportName = options.exportName ?? pascalCase(contract.name);
+    if (!/^[A-Za-z_$][\w$]*$/.test(exportName) || RESERVED_NAMES.has(exportName)) {
+        throw new Error(`"${exportName}" isn't a usable export name; pass --name`);
+    }
+    const imports = new Set(["declareContract"]);
+    const code = new Code(imports);
+    const lines = [];
+    lines.push(`// Generated by \`peers-package contract add\` from ${docText(options.from)}.`, "// Regenerate it rather than edit it; a stable package release freezes the contract's shape.", "");
+    const eventNames = new Map();
+    for (const event of contract.events ?? []) {
+        const name = uniqueName(`${camelCase(exportName)}${pascalCase(event.name)}`, new Set([...RESERVED_NAMES, exportName, ...eventNames.values()]));
+        eventNames.set(event.name, name);
+        imports.add("defineEvent");
+        const fields = event.payloadFields ?? [];
+        lines.push(`/** ${docText(event.description)} */`, `export const ${name} = defineEvent({`, `  name: ${JSON.stringify(event.name)},`, `  description: ${JSON.stringify(event.description)},`, ...(fields.length ? [`  payloadSchema: ${code.objectSchema(fields, 1)},`] : []), "});", "");
+    }
+    const members = [];
+    if (tables.length) {
+        imports.add("defineTable");
+        // Local constants preserve defineTable's inferred row type in declareContract's list.
+        const taken = new Set([...RESERVED_NAMES, exportName, ...eventNames.values()]);
+        const names = tables.map((table) => {
+            const name = uniqueName(`${camelCase(exportName)}${pascalCase(table.name)}`, taken);
+            taken.add(name);
+            lines.push(`const ${name} = ${code.table(table, 0)};`, "");
+            return name;
+        });
+        members.push(`  tables: [${names.join(", ")}],`);
+    }
+    const publicTools = contract.tools.filter((tool) => !tool.private);
+    if (publicTools.length) {
+        imports.add("declareTool");
+        members.push("  tools: [", ...publicTools.map((tool) => `    ${code.tool(tool, 2)},`), "  ],");
+    }
+    if (contract.observables?.length) {
+        imports.add("declareObservable");
+        members.push("  observables: [", ...contract.observables.map((observable) => `    ${code.observable(observable, 2)},`), "  ],");
+    }
+    if (contract.events?.length) {
+        members.push(`  events: [${[...eventNames.values()].join(", ")}],`);
+    }
+    lines.push(`/** ${docText(contract.description || `${contract.name} v${contract.version}.`)} */`, `export const ${exportName} = declareContract({`, `  contractId: ${JSON.stringify(contract.contractId)},`, `  version: ${contract.version},`, `  name: ${JSON.stringify(contract.name)},`, ...(contract.description ? [`  description: ${JSON.stringify(contract.description)},`] : []), ...members, "});");
+    const types = [];
+    if (contract.observables?.length) {
+        imports.add("type ContractObservableValuesOf");
+        types.push("", `/** ${docText(`Each observable's value, by name: \`${exportName}Observables[${JSON.stringify(contract.observables[0].name)}]\`.`)} */`, `export type ${exportName}Observables = ContractObservableValuesOf<typeof ${exportName}>;`);
+    }
+    if (contract.events?.length) {
+        imports.add("type ContractEventPayloadsOf");
+        types.push("", "/** Each event's payload, by name. */", `export type ${exportName}Events = ContractEventPayloadsOf<typeof ${exportName}>;`);
+    }
+    if (tables.length) {
+        imports.add("type ContractTableRowsOf");
+        types.push("", "/** Each table's rows, by name. */", `export type ${exportName}Rows = ContractTableRowsOf<typeof ${exportName}>;`);
+    }
+    lines.push(...types, "");
+    const sorted = [...imports].sort((a, b) => a.replace(/^type /, "").localeCompare(b.replace(/^type /, ""), "en", { sensitivity: "base" }));
+    const header = lines.slice(0, 3);
+    const body = lines.slice(3);
+    const source = [
+        ...header,
+        `import { ${sorted.join(", ")} } from "@peers-app/peers-sdk/define";`,
+        "",
+        ...body,
+    ].join("\n");
+    return {
+        fileName: `${kebabCase(contract.name) || kebabCase(exportName) || "contract"}.v${contract.version}.ts`,
+        exportName,
+        source,
+    };
+}
+/** Builds the zod source for IR, noting the SDK names it uses. */
+class Code {
+    imports;
+    constructor(imports) {
+        this.imports = imports;
+    }
+    table(table, depth) {
+        if (table.versionNumber !== undefined)
+            assertVersion(table.versionNumber, "Table version");
+        return this.call("defineTable", depth, [
+            ["name", JSON.stringify(table.name)],
+            ["description", JSON.stringify(table.description ?? "")],
+            ["primaryKeyName", JSON.stringify(table.primaryKeyName)],
+            ["schema", this.objectSchema(table.fields, depth + 1)],
+            ...(table.versionNumber === undefined
+                ? []
+                : [["versionNumber", String(table.versionNumber)]]),
+            ...(table.localOnly ? [["localOnly", "true"]] : []),
+        ]);
+    }
+    tool(tool, depth) {
+        // An omitted level is the Runtime's default: None for a preserving tool, else Self.
+        const level = tool.suggestedAccessLevel ??
+            (tool.authorityPropagation === "preserve" ? access_level_1.AccessLevel.None : access_level_1.AccessLevel.Self);
+        return this.call("declareTool", depth, [
+            ["name", JSON.stringify(tool.name)],
+            ["usageDescription", JSON.stringify(tool.usageDescription)],
+            ["accessLevel", this.accessLevel(level)],
+            ...(tool.authorityPropagation
+                ? [["authorityPropagation", JSON.stringify(tool.authorityPropagation)]]
+                : []),
+            ...(tool.remoteAccessLevel === undefined
+                ? []
+                : [["remoteAccessLevel", this.accessLevel(tool.remoteAccessLevel)]]),
+            ["inputSchema", this.objectSchema(tool.inputFields ?? [], depth + 1)],
+            ["outputSchema", this.objectSchema(tool.outputFields ?? [], depth + 1)],
+        ]);
+    }
+    observable(observable, depth) {
+        const shape = observable.value
+            ? [["schema", this.valueSchema(observable.value, observable.valueType, depth + 1)]]
+            : [["valueType", this.fieldType(observable.valueType)]];
+        return this.call("declareObservable", depth, [
+            ["name", JSON.stringify(observable.name)],
+            ["description", JSON.stringify(observable.description)],
+            ...shape,
+            ...(observable.writable ? [["writable", "true"]] : []),
+        ]);
+    }
+    objectSchema(fields, depth) {
+        this.imports.add("z");
+        if (!fields.length) {
+            return "z.object({}).passthrough()";
+        }
+        const pad = "  ".repeat(depth + 1);
+        const entries = fields.map((field) => `${pad}${propertyKey(field.name)}: ${this.field(field, depth + 1)},`);
+        return `z.object({\n${entries.join("\n")}\n${"  ".repeat(depth)}}).passthrough()`;
+    }
+    /** An observable's whole value: an empty one is `null` on the wire. */
+    valueSchema(value, valueType, depth) {
+        const { optional, ...rest } = value;
+        const schema = this.field(rest, depth);
+        const result = optional ? `${schema}.nullable()` : schema;
+        // valueType describes what the host admits, independently of the detailed value shape.
+        // Transforms and numeric native enums can make it wider than the schema's scalar type.
+        const inferred = optional
+            ? field_type_1.FieldType.any
+            : value.isArray
+                ? field_type_1.FieldType.object
+                : value.type === field_type_1.FieldType.number && (value.enumValues?.length ?? 0) > 1
+                    ? field_type_1.FieldType.any
+                    : value.type;
+        return inferred === valueType && optional !== false
+            ? result
+            : this.annotate(result, value, valueType);
+    }
+    field(field, depth) {
+        let schema = this.base(field, depth);
+        if (field.isArray)
+            schema = `z.array(${schema})`;
+        if (field.defaultValue !== undefined && isPlainData(field.defaultValue)) {
+            schema = `${schema}.default(${dataSource(field.defaultValue)})`;
+        }
+        else if (field.optional) {
+            schema = `${schema}.optional()`;
+        }
+        if (field.description)
+            schema = `${schema}.describe(${JSON.stringify(field.description)})`;
+        // Preserve IR that normal schema inference cannot express. This also keeps opaque objects
+        // opaque (rather than adding fields: []) and event any fields' original requiredness.
+        if (field.type === field_type_1.FieldType.any ||
+            field.type === field_type_1.FieldType.blob ||
+            (field.type === field_type_1.FieldType.number && (field.enumValues?.length ?? 0) > 1) ||
+            (field.type === field_type_1.FieldType.object && field.fields === undefined) ||
+            (field.type === field_type_1.FieldType.id && field.enumValues !== undefined) ||
+            (field.type === field_type_1.FieldType.boolean && (field.enumValues?.length ?? 0) > 1) ||
+            (field.enumValues !== undefined &&
+                new Set(field.enumValues).size !== field.enumValues.length) ||
+            field.defaultValue !== undefined ||
+            field.subType !== undefined ||
+            field.optional === false ||
+            field.isArray === false ||
+            field.description === "") {
+            schema = this.annotate(schema, field);
+        }
+        return schema;
+    }
+    annotate(schema, shape, valueType) {
+        this.imports.add("generatedField");
+        // A field's name belongs to the enclosing object, not its schema's shape.
+        const { name: _name, ...metadata } = shape;
+        return `generatedField(${schema}, ${this.shapeSource(metadata)}${valueType === undefined ? "" : `, ${this.fieldType(valueType)}`})`;
+    }
+    shapeSource(shape) {
+        const entries = Object.entries(shape).map(([key, value]) => {
+            const source = key === "type"
+                ? this.fieldType(value)
+                : key === "fields"
+                    ? `[${value.map((field) => this.shapeSource(field)).join(", ")}]`
+                    : dataSource(value);
+            return `${propertyKey(key)}: ${source}`;
+        });
+        return `{ ${entries.join(", ")} }`;
+    }
+    base(field, depth) {
+        if (field.type !== field_type_1.FieldType.id)
+            this.imports.add("z");
+        const values = field.enumValues;
+        switch (field.type) {
+            case field_type_1.FieldType.string:
+                if (values?.length === 1)
+                    return `z.literal(${JSON.stringify(values[0])})`;
+                if (values?.length)
+                    return `z.enum(${JSON.stringify(values)})`;
+                return "z.string()";
+            case field_type_1.FieldType.number:
+                if (values?.length === 1)
+                    return `z.literal(${JSON.stringify(values[0])})`;
+                if (values?.length) {
+                    const entries = values.map((value, index) => `v${index}: ${JSON.stringify(value)}`);
+                    return `z.nativeEnum({ ${entries.join(", ")} } as const)`;
+                }
+                return "z.number()";
+            case field_type_1.FieldType.boolean:
+                return values?.length && new Set(values).size === 1
+                    ? `z.literal(${JSON.stringify(values[0])})`
+                    : "z.boolean()";
+            case field_type_1.FieldType.id:
+                this.imports.add("zodPeerId");
+                return values?.length
+                    ? `zodPeerId.refine((value) => ${JSON.stringify(values)}.includes(value))`
+                    : "zodPeerId";
+            case field_type_1.FieldType.Date:
+                return "z.date()";
+            case field_type_1.FieldType.blob:
+                return "z.instanceof(Uint8Array)";
+            case field_type_1.FieldType.object:
+                // The Runtime keeps keys an object's fields don't list, and so does this schema.
+                return this.objectSchema(field.fields ?? [], depth);
+            default:
+                // The annotation keeps the IR's any type even when enum values narrow the schema.
+                if (values?.length === 1)
+                    return `z.literal(${JSON.stringify(values[0])})`;
+                if (values && values.length > 1) {
+                    return `z.union([${values.map((value) => `z.literal(${JSON.stringify(value)})`).join(", ")}])`;
+                }
+                // z.unknown() admits an omitted key and makes it optional in zod's object types.
+                // A required scalar any still needs a value; array elements aren't record fields.
+                if (!field.optional && !field.isArray && field.defaultValue === undefined) {
+                    return "z.custom<NonNullable<unknown> | null>((value) => value !== undefined)";
+                }
+                return "z.unknown()";
+        }
+    }
+    fieldType(type) {
+        this.imports.add("FieldType");
+        const key = Object.entries(field_type_1.FieldType).find(([, value]) => value === type)?.[0];
+        return key ? `FieldType.${key}` : JSON.stringify(type);
+    }
+    accessLevel(level) {
+        if (!Number.isInteger(level) || level < 0 || level > 100) {
+            throw new Error("Tool access level must be an integer 0–100");
+        }
+        const named = Object.entries(access_level_1.AccessLevel).find(([, value]) => value === level)?.[0];
+        if (!named)
+            return String(level);
+        this.imports.add("AccessLevel");
+        return `AccessLevel.${named}`;
+    }
+    call(name, depth, entries) {
+        const pad = "  ".repeat(depth + 1);
+        const body = entries.map(([key, value]) => `${pad}${key}: ${value},`).join("\n");
+        return `${name}({\n${body}\n${"  ".repeat(depth)}})`;
+    }
+}
+/** Versions become numeric literals and file names, so JSON sources must supply safe integers. */
+function assertVersion(value, label) {
+    if (!Number.isSafeInteger(value) || value < 1) {
+        throw new Error(`${label} must be a positive safe integer`);
+    }
+}
+/** A property name as written in an object literal. */
+function propertyKey(name) {
+    if (name === "__proto__")
+        return '["__proto__"]';
+    return /^[A-Za-z_$][\w$]*$/.test(name) ? name : JSON.stringify(name);
+}
+/** JSON data as a source expression, preserving an own __proto__ key in stored defaults. */
+function dataSource(value) {
+    if (Array.isArray(value))
+        return `[${value.map(dataSource).join(", ")}]`;
+    if (value && typeof value === "object") {
+        return `{ ${Object.entries(value)
+            .map(([key, entry]) => `${propertyKey(key)}: ${dataSource(entry)}`)
+            .join(", ")} }`;
+    }
+    return JSON.stringify(value);
+}
+function isPlainData(value) {
+    try {
+        return JSON.stringify(value) !== undefined;
+    }
+    catch {
+        return false;
+    }
+}
+/** Text for a one-line JSDoc comment. */
+function docText(text) {
+    return text.replace(/\*\//g, "* /").replace(/\s+/g, " ").trim();
+}
+function words(name) {
+    return name
+        .replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2")
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .split(/[^A-Za-z0-9]+/)
+        .filter(Boolean);
+}
+function pascalCase(name) {
+    const joined = words(name)
+        .map((word) => word[0].toUpperCase() + word.slice(1))
+        .join("");
+    return /^[0-9]/.test(joined) ? `Contract${joined}` : joined;
+}
+function camelCase(name) {
+    const [first, ...rest] = words(name);
+    if (!first)
+        return name;
+    return first.toLowerCase() + rest.map((word) => word[0].toUpperCase() + word.slice(1)).join("");
+}
+function kebabCase(name) {
+    return words(name)
+        .map((word) => word.toLowerCase())
+        .join("-");
+}
+function uniqueName(name, taken) {
+    let candidate = name;
+    for (let index = 2; taken.has(candidate); index++)
+        candidate = `${name}${index}`;
+    return candidate;
+}

package/dist/package-build/freeze-contracts.d.ts

@@ -0,0 +1,56 @@
+import { type IFrozenContract, type IFrozenContracts, type IFrozenContractsCheck } from "../contracts/frozen-contracts";
+import { type IIsolatedPackageManifest } from "../package-loader/isolated-artifact";
+/** What {@link freezePackageContracts} takes. */
+export interface IContractFreezeOptions {
+    /** Package root, holding `frozen-contracts.json`. Defaults to the current directory. */
+    root?: string;
+    /** The declaration module, relative to `root`, for a `/define` package. Defaults to `src/package.ts`. */
+    entry?: string;
+    /**
+     * A built bundle to read the provided contracts from instead of the declaration module: an
+     * isolated package's `package.bundle.js`, or a host-backed (legacy) package's CommonJS bundle.
+     * Relative paths are resolved from the current directory, like `contract add`'s source.
+     */
+    bundle?: string;
+    /** Write nothing; report whether a frozen contract version changed. */
+    check?: boolean;
+}
+/** What {@link freezePackageContracts} found and did. */
+export interface IContractFreezeResult {
+    /** `frozen-contracts.json`'s path. */
+    path: string;
+    /** The package version the contracts were read from. */
+    packageVersion: string;
+    /** Contract versions frozen by this run (none with `check`, or when a frozen version changed). */
+    added: IFrozenContract[];
+    /**
+     * Frozen versions changed, and those no longer served: neither provided nor named by a
+     * provided contract's `alsoImplements`.
+     */
+    check: IFrozenContractsCheck;
+    /** The file was written. */
+    written: boolean;
+}
+/**
+ * Freeze the contract versions a package provides, before releasing it as stable: add each one
+ * not yet in `frozen-contracts.json`, as frozen by the package's version. With `check`, or when a
+ * frozen version's shape changed, write nothing.
+ *
+ * @param options - The package, where its contracts come from, and whether only to check.
+ */
+export declare function freezePackageContracts(options: IContractFreezeOptions): Promise<IContractFreezeResult>;
+/**
+ * Refuse a manifest that changes a contract version the package's stable releases froze, as
+ * `peers-package build` does. A package without `frozen-contracts.json` passes.
+ *
+ * @param root - The package root.
+ * @param manifest - The manifest about to be built.
+ */
+export declare function assertFrozenContracts(root: string, manifest: IIsolatedPackageManifest): Promise<void>;
+/**
+ * Read a package's `frozen-contracts.json`.
+ *
+ * @param root - The package root.
+ * @returns Its content, or undefined when the package has none.
+ */
+export declare function readFrozenContracts(root: string): Promise<IFrozenContracts | undefined>;