@peers-app/peers-sdk 0.26.6 → 0.27.0

package/dist/define/events.d.ts

@@ -0,0 +1,81 @@
+import type { z } from "zod";
+import type { IField } from "../types/field-type";
+/** An event declared with a zod payload schema. */
+export interface IPackageEventSchemaDefinition<P extends z.AnyZodObject = z.AnyZodObject> {
+    /** Event name, unique on its contract. */
+    name: string;
+    /** What the event signals, for people and agents subscribing to it. */
+    description: string;
+    /** Payload schema. `emit` parses the payload with it; the manifest carries its fields as IR. */
+    payloadSchema: P;
+}
+/** An event declared directly in Peers IR, for a contract defined elsewhere. */
+export interface IPackageEventFieldsDefinition {
+    /** Event name, unique on its contract. */
+    name: string;
+    /** What the event signals, for people and agents subscribing to it. */
+    description: string;
+    /** Payload fields. Omit for an event without a payload. */
+    payloadFields?: IField[];
+}
+/** Either form of event declaration. */
+export type PackageEventDefinition = IPackageEventSchemaDefinition | IPackageEventFieldsDefinition;
+/**
+ * An event declared with {@link defineEvent}. List it on a provided contract's `events`. `P` is
+ * what `emit` takes, `N` the event's name, and `O` what subscribers receive (the parsed payload).
+ */
+export interface IPackageEvent<P = unknown, N extends string = string, O = P> {
+    /** Marks an event declaration. */
+    readonly kind: "event";
+    /** What was passed to {@link defineEvent}. */
+    readonly definition: Readonly<PackageEventDefinition> & {
+        readonly name: N;
+    };
+    /** Type-only: what subscribers receive. Always undefined at runtime. */
+    readonly types?: {
+        payload: O;
+    };
+    /**
+     * Send the event on every provided contract that lists it. The payload is parsed with the
+     * schema first, so a bad one fails here. Resolves once the host has accepted it. Needs no
+     * `ctx`: the package emits for itself, from a handler or from background work. Outside a
+     * worker (tests, the manifest build) it checks the payload and sends nothing. Captures a
+     * snapshot, omitting undefined object fields and mapping undefined array entries to null; a
+     * value the bridge can't carry (a function, a Map, a cycle) fails, in a worker or not.
+     */
+    emit(...args: undefined extends P ? [payload?: P] : [payload: P]): Promise<void>;
+}
+/**
+ * Declare an event from a zod payload schema.
+ *
+ * @param definition - Name, description, and payload schema.
+ */
+export declare function defineEvent<P extends z.AnyZodObject, N extends string>(definition: IPackageEventSchemaDefinition<P> & {
+    name: N;
+}): IPackageEvent<z.input<P>, NoInfer<N>, z.output<P>>;
+/**
+ * Declare an event from Peers IR fields, for a contract defined elsewhere. Its payload isn't
+ * parsed with a schema; the host checks the emitted snapshot against the fields.
+ *
+ * @param definition - Name, description, and payload fields.
+ */
+export declare function defineEvent<N extends string>(definition: IPackageEventFieldsDefinition & {
+    name: N;
+}): IPackageEvent<unknown, NoInfer<N>>;
+/**
+ * True for an event from {@link defineEvent}, as opposed to an IR declaration.
+ *
+ * @param value - An entry in a contract's `events`.
+ */
+export declare function isPackageEvent(value: unknown): value is IPackageEvent<any, string, any>;
+/**
+ * Record which provided contracts list each event, so `emit` knows where to send it. Called by
+ * `startPackage`.
+ *
+ * @param provides - The package's provided contracts.
+ */
+export declare function bindPackageEvents(provides: readonly {
+    contractId: string;
+    version: number;
+    events: readonly unknown[];
+}[]): void;

package/dist/define/events.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineEvent = defineEvent;
+exports.isPackageEvent = isPackageEvent;
+exports.bindPackageEvents = bindPackageEvents;
+const empty_fields_1 = require("./empty-fields");
+const wire_value_1 = require("./wire-value");
+const worker_state_1 = require("./worker-state");
+/** Contracts each event is listed on, set when the worker starts. */
+let eventTargets = new WeakMap();
+/**
+ * Declare an event a provided contract may emit.
+ *
+ * @param definition - Name, description, and payload schema (or IR fields).
+ */
+function defineEvent(definition) {
+    if (typeof definition?.name !== "string" || definition.name.trim() === "") {
+        throw new Error("defineEvent requires a name");
+    }
+    const { name } = definition;
+    if (typeof definition.description !== "string") {
+        throw new Error(`Event ${name} needs a description`);
+    }
+    const schema = "payloadSchema" in definition ? definition.payloadSchema : undefined;
+    if (schema !== undefined && "payloadFields" in definition) {
+        throw new Error(`Event ${name} needs either payloadSchema or payloadFields, not both`);
+    }
+    if (schema !== undefined && typeof schema?.shape !== "object") {
+        throw new Error(`Event ${name} payloadSchema must be a zod object`);
+    }
+    if ("payloadFields" in definition &&
+        definition.payloadFields !== undefined &&
+        !Array.isArray(definition.payloadFields)) {
+        throw new Error(`Event ${name} payloadFields must be an array`);
+    }
+    const event = Object.freeze({
+        kind: "event",
+        definition: Object.freeze({ ...definition }),
+        async emit(payload) {
+            const value = (0, wire_value_1.snapshotPackageValue)(schema ? schema.parse((0, empty_fields_1.withoutEmptySchemaFields)(schema, payload)) : payload);
+            // Read synchronously when started, so emits reach the host in the order they were made.
+            const ctx = (0, worker_state_1.packageContext)() ?? (await (0, worker_state_1.whenPackageStarts)());
+            if (!ctx) {
+                return;
+            }
+            const targets = eventTargets.get(event);
+            if (!targets?.length) {
+                throw new Error(`Event "${name}" isn't listed on a contract this package provides`);
+            }
+            await Promise.all(targets.map((target) => ctx.emitContractEvent(target.contractId, target.version, name, value)));
+        },
+    });
+    return event;
+}
+/**
+ * True for an event from {@link defineEvent}, as opposed to an IR declaration.
+ *
+ * @param value - An entry in a contract's `events`.
+ */
+function isPackageEvent(value) {
+    return value?.kind === "event";
+}
+/**
+ * Record which provided contracts list each event, so `emit` knows where to send it. Called by
+ * `startPackage`.
+ *
+ * @param provides - The package's provided contracts.
+ */
+function bindPackageEvents(provides) {
+    const targets = new WeakMap();
+    for (const contract of provides) {
+        for (const event of contract.events) {
+            if (isPackageEvent(event)) {
+                const list = targets.get(event) ?? [];
+                list.push({ contractId: contract.contractId, version: contract.version });
+                targets.set(event, list);
+            }
+        }
+    }
+    eventTargets = targets;
+}

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

@@ -0,0 +1,20 @@
+import type { z } from "zod";
+import type { FieldType, IFieldShape } from "../types/field-type";
+interface IGeneratedField {
+    shape: IFieldShape;
+    valueType?: FieldType;
+}
+/**
+ * Keep the original IR on a generated schema when zod's inferred IR would lose information
+ * (such as a stored default or a blob's type). The schema still validates the described value;
+ * this annotation only controls its manifest. Used by `peers-package contract add`.
+ *
+ * @internal
+ * @param schema - The generated schema, retaining its inferred TypeScript type.
+ * @param shape - The original field shape, without its name.
+ * @param valueType - An observable's separate host-facing value type, when needed.
+ */
+export declare function generatedField<S extends z.ZodTypeAny>(schema: S, shape: IFieldShape, valueType?: FieldType): S;
+/** Read the original IR annotation of a generated schema. Internal to manifest generation. */
+export declare function generatedFieldMetadata(schema: z.ZodTypeAny): IGeneratedField | undefined;
+export {};

package/dist/define/generated-field.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generatedField = generatedField;
+exports.generatedFieldMetadata = generatedFieldMetadata;
+const generatedShape = Symbol.for("@peers-app/peers-sdk/generated-field");
+/**
+ * Keep the original IR on a generated schema when zod's inferred IR would lose information
+ * (such as a stored default or a blob's type). The schema still validates the described value;
+ * this annotation only controls its manifest. Used by `peers-package contract add`.
+ *
+ * @internal
+ * @param schema - The generated schema, retaining its inferred TypeScript type.
+ * @param shape - The original field shape, without its name.
+ * @param valueType - An observable's separate host-facing value type, when needed.
+ */
+function generatedField(schema, shape, valueType) {
+    // describe clones the schema, including shared schemas such as zodPeerId.
+    const copy = schema.describe(schema.description ?? "");
+    Object.defineProperty(copy, generatedShape, { value: { shape, valueType } });
+    return copy;
+}
+/** Read the original IR annotation of a generated schema. Internal to manifest generation. */
+function generatedFieldMetadata(schema) {
+    return schema[generatedShape];
+}

package/dist/define/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `@peers-app/peers-sdk/define`: declare an isolated package.
+ *
+ * A package is its tools, events, observables, and tables, plus the contracts it consumes and
+ * provides. Declare them in `src/package.ts` with {@link definePackage}; `peers-package` turns
+ * the declaration into the manifest and bundles the same code for the sandbox. This entry stays
+ * small so a provider bundle doesn't carry the whole SDK.
+ */
+export { z } from "zod";
+export { AccessLevel } from "../data/access-level";
+export type { DataFilter, IDataQueryParams } from "../data/orm/data-query";
+export type { IDataChangedEvent } from "../data/orm/subscribable.data-source";
+export { type Observable, observable, type Subscription } from "../observable";
+export { isid, newid } from "../peer-id";
+export { FieldType, type IField } from "../types/field-type";
+export { zodPeerId } from "../types/zod-types";
+export * from "./context";
+export * from "./contract-ref";
+export * from "./declare-contract";
+export * from "./define-package";
+export { defineEvent, type IPackageEvent, type IPackageEventFieldsDefinition, type IPackageEventSchemaDefinition, type PackageEventDefinition, } from "./events";
+export { generatedField } from "./generated-field";
+export { declareObservable, defineObservable, type IPackageObservable, type IPackageObservableDeclaration, type IPackageObservableSchemaDefinition, type IPackageObservableSchemaShape, type IPackageObservableTypeDefinition, type IPackageObservableTypeShape, isImplementedObservable, type PackageObservableDefinition, type PackageObservableShape, } from "./observables";
+export * from "./serve";
+export * from "./system-contracts";
+export * from "./table";
+export * from "./tool";
+export { deviceVar, groupDeviceVar, groupUserVar, groupVar, type IPackageVarBinding, type IPackageVarFactory, type IPackageVarOptions, type PersistentVar, readPackageVar, userVar, writePackageVar, } from "./vars";

package/dist/define/index.js

@@ -0,0 +1,62 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writePackageVar = exports.userVar = exports.readPackageVar = exports.groupVar = exports.groupUserVar = exports.groupDeviceVar = exports.deviceVar = exports.isImplementedObservable = exports.defineObservable = exports.declareObservable = exports.generatedField = exports.defineEvent = exports.zodPeerId = exports.FieldType = exports.newid = exports.isid = exports.observable = exports.AccessLevel = exports.z = void 0;
+/**
+ * `@peers-app/peers-sdk/define`: declare an isolated package.
+ *
+ * A package is its tools, events, observables, and tables, plus the contracts it consumes and
+ * provides. Declare them in `src/package.ts` with {@link definePackage}; `peers-package` turns
+ * the declaration into the manifest and bundles the same code for the sandbox. This entry stays
+ * small so a provider bundle doesn't carry the whole SDK.
+ */
+var zod_1 = require("zod");
+Object.defineProperty(exports, "z", { enumerable: true, get: function () { return zod_1.z; } });
+var access_level_1 = require("../data/access-level");
+Object.defineProperty(exports, "AccessLevel", { enumerable: true, get: function () { return access_level_1.AccessLevel; } });
+var observable_1 = require("../observable");
+Object.defineProperty(exports, "observable", { enumerable: true, get: function () { return observable_1.observable; } });
+var peer_id_1 = require("../peer-id");
+Object.defineProperty(exports, "isid", { enumerable: true, get: function () { return peer_id_1.isid; } });
+Object.defineProperty(exports, "newid", { enumerable: true, get: function () { return peer_id_1.newid; } });
+var field_type_1 = require("../types/field-type");
+Object.defineProperty(exports, "FieldType", { enumerable: true, get: function () { return field_type_1.FieldType; } });
+var zod_types_1 = require("../types/zod-types");
+Object.defineProperty(exports, "zodPeerId", { enumerable: true, get: function () { return zod_types_1.zodPeerId; } });
+__exportStar(require("./context"), exports);
+__exportStar(require("./contract-ref"), exports);
+__exportStar(require("./declare-contract"), exports);
+__exportStar(require("./define-package"), exports);
+var events_1 = require("./events");
+Object.defineProperty(exports, "defineEvent", { enumerable: true, get: function () { return events_1.defineEvent; } });
+var generated_field_1 = require("./generated-field");
+Object.defineProperty(exports, "generatedField", { enumerable: true, get: function () { return generated_field_1.generatedField; } });
+var observables_1 = require("./observables");
+Object.defineProperty(exports, "declareObservable", { enumerable: true, get: function () { return observables_1.declareObservable; } });
+Object.defineProperty(exports, "defineObservable", { enumerable: true, get: function () { return observables_1.defineObservable; } });
+Object.defineProperty(exports, "isImplementedObservable", { enumerable: true, get: function () { return observables_1.isImplementedObservable; } });
+__exportStar(require("./serve"), exports);
+__exportStar(require("./system-contracts"), exports);
+__exportStar(require("./table"), exports);
+__exportStar(require("./tool"), exports);
+var vars_1 = require("./vars");
+Object.defineProperty(exports, "deviceVar", { enumerable: true, get: function () { return vars_1.deviceVar; } });
+Object.defineProperty(exports, "groupDeviceVar", { enumerable: true, get: function () { return vars_1.groupDeviceVar; } });
+Object.defineProperty(exports, "groupUserVar", { enumerable: true, get: function () { return vars_1.groupUserVar; } });
+Object.defineProperty(exports, "groupVar", { enumerable: true, get: function () { return vars_1.groupVar; } });
+Object.defineProperty(exports, "readPackageVar", { enumerable: true, get: function () { return vars_1.readPackageVar; } });
+Object.defineProperty(exports, "userVar", { enumerable: true, get: function () { return vars_1.userVar; } });
+Object.defineProperty(exports, "writePackageVar", { enumerable: true, get: function () { return vars_1.writePackageVar; } });

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

@@ -0,0 +1,8 @@
+/**
+ * A bag whose every other property is made by `member` on first access, then kept. Members
+ * can't be replaced, added, or deleted.
+ * Inspection and `await` see nothing.
+ *
+ * @param member - Makes the member for a name.
+ */
+export declare function lazyMembers<M>(member: (name: string) => M): Readonly<Record<string, M>>;

package/dist/define/lazy-members.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lazyMembers = lazyMembers;
+// Names JavaScript looks up on any object (`await`, `JSON.stringify`, string conversion). As
+// members they would turn `await client.tools` or logging a client into host calls.
+const NOT_MEMBERS = new Set(["then", "toJSON", "toString", "valueOf", "constructor"]);
+/**
+ * A bag whose every other property is made by `member` on first access, then kept. Members
+ * can't be replaced, added, or deleted.
+ * Inspection and `await` see nothing.
+ *
+ * @param member - Makes the member for a name.
+ */
+function lazyMembers(member) {
+    const made = new Map();
+    return new Proxy(Object.create(null), {
+        get(_target, name) {
+            if (typeof name !== "string" || NOT_MEMBERS.has(name)) {
+                return undefined;
+            }
+            let value = made.get(name);
+            if (value === undefined) {
+                value = member(name);
+                made.set(name, value);
+            }
+            return value;
+        },
+        set() {
+            return false;
+        },
+        defineProperty() {
+            return false;
+        },
+        deleteProperty() {
+            return false;
+        },
+    });
+}

package/dist/define/manifest.d.ts

@@ -0,0 +1,63 @@
+import { z } from "zod";
+import type { IFrozenContracts } from "../contracts/frozen-contracts";
+import { type IIsolatedPackageManifest, type IIsolatedPackageTable, type IIsolatedProvidedContract } from "../package-loader/isolated-artifact";
+import { FieldType, type IField } from "../types/field-type";
+import type { IContractMembers, IPackageDefinition } from "./define-package";
+/**
+ * A zod object schema as Peers IR. Defaults stay in the package. Defaulted tool inputs may be
+ * omitted; table fields describe complete stored rows, after the provider parses a save. Shared
+ * with the mock host; not a public SDK export.
+ *
+ * @internal
+ * @param schema - A tool's input or output, a table's row, or an event's payload schema.
+ * @param input - True for tool inputs, where a defaulted field may be omitted.
+ * @param depth - How deep this field list nests in object `fields` (top level is 1).
+ * @param parent - The path of the object field these fields belong to, for error messages.
+ */
+export declare function irFields(schema: z.AnyZodObject, input?: boolean, depth?: number, parent?: string): IField[];
+/**
+ * The IR value type for an observable's schema, which the host checks values against.
+ * Values are JSON, so a Date can't be one. Shared with the mock host; not a public SDK export.
+ *
+ * @internal
+ * @param name - The observable's name, for schema errors.
+ * @param schema - The observable's value schema.
+ */
+export declare function schemaValueType(name: string, schema: z.ZodTypeAny): FieldType;
+/**
+ * True when the host's observable `valueType` check accepts `value`. Shared with the mock host;
+ * not a public SDK export.
+ *
+ * @internal
+ * @param value - An incoming observable write or published value.
+ * @param type - The manifest's declared value type.
+ */
+export declare function fitsValueType(value: unknown, type: FieldType): boolean;
+/**
+ * A contract's manifest entry and its tables' definitions, from a contract or a declaration:
+ * the IR a provider of it would register. Used to generate a declaration from another one; not
+ * a public SDK export.
+ *
+ * @internal
+ * @param contract - From `defineContract`, `implementContract`, or a declaration's members.
+ */
+export declare function contractManifest(contract: IContractMembers): {
+    contract: IIsolatedProvidedContract;
+    tables: IIsolatedPackageTable[];
+};
+/** What {@link buildPackageManifest} needs besides the package definition. */
+export interface IPackageManifestOptions {
+    /**
+     * The package's `frozen-contracts.json`. A contract that also implements an older version of
+     * itself, by number, takes that version's shape from here.
+     */
+    frozen?: IFrozenContracts;
+}
+/**
+ * Turn a package definition into its manifest: plain JSON in Peers IR, which the Runtime reads
+ * without running any package code. `peers-package manifest` writes it to `dist/manifest.json`.
+ *
+ * @param definition - The default export of the package's `src/package.ts`.
+ * @param options - The package's frozen contracts, for `alsoImplements` by version number.
+ */
+export declare function buildPackageManifest(definition: IPackageDefinition, options?: IPackageManifestOptions): IIsolatedPackageManifest;