@peers-app/peers-sdk 0.26.6 → 0.27.1

package/dist/observable.d.ts

@@ -2,6 +2,7 @@ type ObservableFn<T> = {
     (): T;
     (newValue: T): T;
 };
+/** Handle returned by `subscribe`; `dispose` stops the notifications. */
 export type Subscription = {
     dispose: () => void;
 };
@@ -10,14 +11,53 @@ type ObservableProps<T> = {
     notifySubscribers: () => void;
     subscriberCount: () => number;
 };
-export type Observable<T> = ObservableFn<T> & ObservableProps<T>;
+declare const writableObservable: unique symbol;
+declare const observableValue: unique symbol;
+/** A subscribable value that consumers can read with `obs()`. */
+export type ReadonlyObservable<T> = (() => T) & ObservableProps<T> & {
+    readonly [writableObservable]?: boolean;
+};
+/** A readable, writable, subscribable value: `obs()` reads it and `obs(value)` writes it. */
+export type Observable<T> = ObservableFn<T> & ReadonlyObservable<T> & {
+    readonly [writableObservable]?: true;
+    readonly [observableValue]?: {
+        accept(value: T): T;
+    };
+};
+/**
+ * A writable observable that must accept exactly `T`, including in its subscribers. Use for
+ * a declared writable source; unlike ordinary observable assignments, this checks writes
+ * strictly and rejects a source whose value type is narrower than the declaration.
+ */
+export type InvariantObservable<T> = Observable<T> & {
+    readonly [observableValue]?: {
+        accept: (value: T) => T;
+    };
+};
+/**
+ * Create an observable. Writing a value that isn't `===` the current one notifies subscribers.
+ *
+ * @param initialValue - The starting value.
+ */
 export declare function observable<T>(initialValue: T): Observable<T>;
+/** Create an observable that starts `undefined`. */
 export declare function observable<T = undefined>(): Observable<T | undefined>;
+/**
+ * An observable derived from other observables: `read` runs again when any observable it read
+ * changes. Pass `{ read, write }` to make it writable.
+ *
+ * @param fn - The read function, or read and write functions.
+ */
 export declare function computed<T>(fn: {
     read: () => T;
     write?: (val: T) => void;
 } | (() => T)): Observable<T>;
+/** Test an observable while preserving a known read-only view. */
+export declare function isSubscribable<T>(obj: ReadonlyObservable<T>): obj is ReadonlyObservable<T>;
+/** True when an untyped value is an observable. */
 export declare function isSubscribable(obj: any): obj is Observable<any>;
-export declare function unwrapObservable<T>(obj: T | Observable<T>): T;
+/** The observable's current value, or `obj` itself when it isn't an observable. */
+export declare function unwrapObservable<T>(obj: T | ReadonlyObservable<T>): T;
+/** Keep two observables equal: a change to either is written to the other. */
 export declare function linkObservables<T>(obs1: Observable<T>, obs2: Observable<T>): Subscription;
 export {};

package/dist/observable.js

@@ -5,10 +5,19 @@ exports.computed = computed;
 exports.isSubscribable = isSubscribable;
 exports.unwrapObservable = unwrapObservable;
 exports.linkObservables = linkObservables;
-const lodash_1 = require("lodash");
-const utils_1 = require("./utils");
-const _ = require("lodash");
+/**
+ * Observables: a value you call to read (`obs()`) or write (`obs(value)`), with subscribers
+ * notified on each change. Persistent variables and computed values build on them.
+ *
+ * This module has no dependency beyond peer ids, so isolated package bundles can use it.
+ */
+const peer_id_1 = require("./peer-id");
 const runningComputes = {};
+/**
+ * Create an observable, starting at `initialValue`.
+ *
+ * @param initialValue - The starting value.
+ */
 function observable(initialValue) {
     let value = initialValue;
     const subscribers = [];
@@ -46,12 +55,18 @@ function observable(initialValue) {
     obs.subscriberCount = () => subscribers.length;
     return obs;
 }
+/**
+ * An observable derived from other observables: `read` runs again when any observable it read
+ * changes. Pass `{ read, write }` to make it writable.
+ *
+ * @param fn - The read function, or read and write functions.
+ */
 function computed(fn) {
-    const read = _.isFunction(fn) ? fn : fn.read;
-    const write = _.isFunction(fn) ? undefined : fn.write;
+    const read = typeof fn === "function" ? fn : fn.read;
+    const write = typeof fn === "function" ? undefined : fn.write;
     // compute dependencies and initial value;
     const dependencies = [];
-    const runId = (0, utils_1.newid)();
+    const runId = (0, peer_id_1.newid)();
     runningComputes[runId] = dependencies;
     const _obs = observable(read());
     delete runningComputes[runId];
@@ -84,18 +99,21 @@ function computed(fn) {
         }
     };
     // subscribe to dependencies
-    (0, lodash_1.uniq)(dependencies).forEach((dep) => {
+    [...new Set(dependencies)].forEach((dep) => {
         dep.subscribe(onDepChange);
     });
     Object.assign(obs, _obs);
     return obs;
 }
+/** True when `obj` is an observable. */
 function isSubscribable(obj) {
     return obj && typeof obj === "function" && obj.subscribe && obj.notifySubscribers;
 }
+/** The observable's current value, or `obj` itself when it isn't an observable. */
 function unwrapObservable(obj) {
     return isSubscribable(obj) ? obj() : obj;
 }
+/** Keep two observables equal: a change to either is written to the other. */
 function linkObservables(obs1, obs2) {
     const sub1 = obs1.subscribe((value) => {
         if (value !== obs2()) {

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

@@ -0,0 +1,60 @@
+import { type IIsolatedPackageManifest } from "../package-loader/isolated-artifact";
+/** Where the package is and where its build goes. */
+export interface IPackageBuildOptions {
+    /** The package's root, holding its `package.json`. Defaults to the current directory. */
+    root?: string;
+    /** The declaration module, relative to `root`. Defaults to `src/package.ts`. */
+    entry?: string;
+    /** The output directory, relative to `root`. Defaults to `dist`. */
+    outDir?: string;
+}
+/** What {@link buildPackage} wrote. */
+export interface IPackageBuildResult {
+    manifest: IIsolatedPackageManifest;
+    manifestPath: string;
+    artifactPath: string;
+    /** Size of the bundled provider source, in characters. */
+    providerChars: number;
+}
+/** A running package watcher. Dispose it to stop watching and release esbuild. */
+export interface IPackageWatcher {
+    dispose(): Promise<void>;
+}
+/**
+ * Bundle a TypeScript or JavaScript module for Node, the way the build loads `src/package.ts`,
+ * and return its exports. Its installed imports resolve from the package at `root`.
+ *
+ * @param root - The package root, whose esbuild compiles the module.
+ * @param entry - The module's path.
+ */
+export declare function loadPackageModule(root: string, entry: string): Promise<unknown>;
+/**
+ * The generate-manifest step: write `dist/manifest.json` from the package's declarations.
+ *
+ * @param buildOptions - Package root, declaration entry, and output directory.
+ */
+export declare function generatePackageManifest(buildOptions?: IPackageBuildOptions): Promise<{
+    manifest: IIsolatedPackageManifest;
+    manifestPath: string;
+}>;
+/**
+ * Build the package's manifest from its declarations, validated, without writing it or checking
+ * it against `frozen-contracts.json` (`peers-package contract freeze` does that itself).
+ *
+ * @param buildOptions - Package root and declaration entry.
+ */
+export declare function packageManifest(buildOptions?: IPackageBuildOptions): Promise<IIsolatedPackageManifest>;
+/**
+ * Generate the manifest, bundle the provider for the sandbox, and write `dist/package.bundle.js`.
+ *
+ * @param buildOptions - Package root, declaration entry, and output directory.
+ */
+export declare function buildPackage(buildOptions?: IPackageBuildOptions): Promise<IPackageBuildResult>;
+/**
+ * Build once, then rebuild whenever a source file changes. Resolves once watching starts.
+ *
+ * @param buildOptions - Package root, declaration entry, and output directory.
+ * @param onBuild - Called after each build, with its result or error.
+ * @returns A handle that stops watching when disposed.
+ */
+export declare function watchPackage(buildOptions?: IPackageBuildOptions, onBuild?: (result: IPackageBuildResult | Error) => void): Promise<IPackageWatcher>;

package/dist/package-build/build-package.js

@@ -0,0 +1,312 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadPackageModule = loadPackageModule;
+exports.generatePackageManifest = generatePackageManifest;
+exports.packageManifest = packageManifest;
+exports.buildPackage = buildPackage;
+exports.watchPackage = watchPackage;
+/**
+ * `peers-package`: build an isolated package from its declarations (Node only).
+ *
+ * `manifest` is the generate-manifest step: it loads `src/package.ts` in Node and writes the
+ * manifest, plain JSON in Peers IR, to `dist/manifest.json`. `build` also bundles the same
+ * `src/package.ts` for the sandbox and writes `dist/package.bundle.js`, the artifact the
+ * Runtime installs. esbuild comes from the package's own dependencies.
+ */
+const promises_1 = require("node:fs/promises");
+const node_module_1 = require("node:module");
+const path = require("node:path");
+const manifest_1 = require("../define/manifest");
+const isolated_artifact_1 = require("../package-loader/isolated-artifact");
+const freeze_contracts_1 = require("./freeze-contracts");
+/** Source text SES rejects before running it, with what to tell the author. */
+const SES_REJECTED_PATTERNS = [
+    { pattern: /(?:<!--|-->)/, what: "an HTML comment token (<!-- or -->)" },
+    {
+        pattern: /(^|[^.]|\.\.\.)\bimport(\s*(?:\(|\/[/*]))/,
+        what: "import( or import followed by a comment",
+    },
+    { pattern: /(^|[^.])\beval(\s*\()/, what: "a direct eval(...) call" },
+];
+const NODE_BUILTINS = [...node_module_1.builtinModules, ...node_module_1.builtinModules.map((name) => `node:${name}`)];
+function resolveOptions(options) {
+    const root = path.resolve(options.root ?? process.cwd());
+    const packageRequire = (0, node_module_1.createRequire)(path.join(root, "package.json"));
+    let esbuild;
+    try {
+        esbuild = packageRequire("esbuild");
+    }
+    catch {
+        throw new Error(`peers-package needs esbuild in ${root}. Install it: npm install --save-dev esbuild`);
+    }
+    return {
+        root,
+        entry: path.resolve(root, options.entry ?? "src/package.ts"),
+        outDir: path.resolve(root, options.outDir ?? "dist"),
+        esbuild,
+        require: packageRequire,
+    };
+}
+/** Node compilation used to load the declaration without bundling its installed libraries. */
+function definitionBuildOptions(entry, outfile) {
+    return {
+        entryPoints: [entry],
+        outfile,
+        bundle: true,
+        platform: "node",
+        format: "cjs",
+        target: "node20",
+        packages: "external",
+        logLevel: "silent",
+    };
+}
+/** Bundle the declaration module for Node and load its default export. */
+async function loadDefinition(options) {
+    const loaded = (await loadModule(options, options.entry));
+    const definition = loaded.default;
+    if (definition?.kind !== "package") {
+        throw new Error(`${path.relative(options.root, options.entry)} must export default definePackage(...)`);
+    }
+    return definition;
+}
+/**
+ * Bundle a TypeScript or JavaScript module for Node, the way the build loads `src/package.ts`,
+ * and return its exports. Its installed imports resolve from the package at `root`.
+ *
+ * @param root - The package root, whose esbuild compiles the module.
+ * @param entry - The module's path.
+ */
+async function loadPackageModule(root, entry) {
+    const options = resolveOptions({ root });
+    return loadModule(options, path.resolve(entry));
+}
+/** Bundle one module for Node and load it, then forget it and its installed imports. */
+async function loadModule(options, entry) {
+    // External imports must resolve from the package, even when --out-dir is elsewhere, so the
+    // compiled declaration goes under the package's node_modules/.cache: git and npm ignore it,
+    // so a build killed before cleanup (Ctrl-C while watching) leaves nothing in the source tree.
+    // Use a unique directory so concurrent builds cannot overwrite or remove each other's code.
+    const cacheDir = path.join(options.root, "node_modules", ".cache", "peers-package");
+    await (0, promises_1.mkdir)(cacheDir, { recursive: true });
+    const temporaryDir = await (0, promises_1.mkdtemp)(path.join(cacheDir, "definition-"));
+    const outfile = path.join(temporaryDir, "definition.cjs");
+    const definitionRequire = (0, node_module_1.createRequire)(outfile);
+    let cacheKey;
+    let previousModules;
+    try {
+        await options.esbuild.build(definitionBuildOptions(entry, outfile));
+        cacheKey = definitionRequire.resolve(outfile);
+        previousModules = new Set(Object.keys(definitionRequire.cache));
+        return definitionRequire(outfile);
+    }
+    finally {
+        const previous = previousModules;
+        if (previous) {
+            // The entry is bundled, but its installed dependencies are external. A watch rebuild
+            // must reload those too, including dependencies loaded before an evaluation failed.
+            const cache = definitionRequire.cache;
+            const pending = Object.keys(cache).filter((key) => !previous.has(key));
+            if (cacheKey)
+                pending.push(cacheKey);
+            const seen = new Set();
+            while (pending.length) {
+                const key = pending.pop();
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                for (const child of cache[key]?.children ?? [])
+                    pending.push(child.id);
+                delete cache[key];
+            }
+        }
+        await (0, promises_1.rm)(temporaryDir, { recursive: true, force: true });
+    }
+}
+/**
+ * Check a manifest without changing it: validation fills in defaults on what it's given. Strict,
+ * so a field key this SDK doesn't know (a typo in hand-written IR) fails the build.
+ */
+function validateManifest(manifest, providerSource = "void 0;") {
+    (0, isolated_artifact_1.validateIsolatedPackageArtifact)({ manifest: structuredClone(manifest), providerSource }, { strict: true });
+}
+/** The package's manifest from its declarations, validated. */
+async function validManifest(options) {
+    // frozen-contracts.json gives the shapes of older versions a contract also implements.
+    const manifest = (0, manifest_1.buildPackageManifest)(await loadDefinition(options), {
+        frozen: await (0, freeze_contracts_1.readFrozenContracts)(options.root),
+    });
+    validateManifest(manifest);
+    return manifest;
+}
+/** The package's manifest, validated and checked against the contracts it froze. */
+async function checkedManifest(options) {
+    const manifest = await validManifest(options);
+    await (0, freeze_contracts_1.assertFrozenContracts)(options.root, manifest);
+    return manifest;
+}
+async function writeManifest(options) {
+    return saveManifest(options, await checkedManifest(options));
+}
+async function saveManifest(options, manifest) {
+    const manifestPath = path.join(options.outDir, "manifest.json");
+    await (0, promises_1.mkdir)(options.outDir, { recursive: true });
+    await (0, promises_1.writeFile)(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+    return { manifest, manifestPath };
+}
+/** esbuild options for the provider bundle: the declaration plus `servePackage`. */
+function providerBuildOptions(options, manifest, plugins = []) {
+    const sandbox = manifest.executionMode !== "privileged";
+    const sdkRoot = path.dirname(options.require.resolve("@peers-app/peers-sdk/package.json"));
+    const zodPath = (0, node_module_1.createRequire)(path.join(sdkRoot, "package.json")).resolve("zod");
+    const singleZod = {
+        name: "peers-package-single-zod",
+        setup(build) {
+            // One zod for the package and the SDK, so schemas from both mix.
+            build.onResolve({ filter: /^zod$/ }, () => ({ path: zodPath }));
+        },
+    };
+    return {
+        stdin: {
+            contents: [
+                `import definition from ${JSON.stringify(options.entry)};`,
+                `import { servePackage } from "@peers-app/peers-sdk/define";`,
+                "servePackage(definition);",
+            ].join("\n"),
+            resolveDir: options.root,
+            sourcefile: "peers-package-provider.js",
+            loader: "js",
+        },
+        bundle: true,
+        write: false,
+        format: "iife",
+        target: "es2022",
+        // The sandbox is a worker with web globals and no Node builtins. A privileged provider runs
+        // in Node with `require`.
+        platform: sandbox ? "browser" : "node",
+        // Leave Node builtins to libraries' own guarded `require`s; the sandbox has none.
+        external: sandbox ? NODE_BUILTINS : [],
+        define: { "process.env.NODE_ENV": '"production"' },
+        // Also strips comments: SES rejects some text even inside a comment.
+        minifyWhitespace: true,
+        legalComments: "none",
+        logLevel: "silent",
+        plugins: [singleZod, ...plugins],
+    };
+}
+function assertSesCompatible(source, manifest) {
+    if (manifest.executionMode === "privileged") {
+        return;
+    }
+    for (const { pattern, what } of SES_REJECTED_PATTERNS) {
+        const match = pattern.exec(source);
+        if (match) {
+            const at = match.index + match[0].length;
+            const snippet = source.slice(Math.max(0, at - 60), at + 20).replace(/\s+/g, " ");
+            throw new Error(`The provider bundle contains ${what}, which the sandbox rejects even inside a string. Near: …${snippet}…`);
+        }
+    }
+}
+async function writeArtifact(options, manifest, providerSource) {
+    assertSesCompatible(providerSource, manifest);
+    validateManifest(manifest, providerSource);
+    const artifactPath = path.join(options.outDir, "package.bundle.js");
+    await (0, promises_1.mkdir)(options.outDir, { recursive: true });
+    await (0, promises_1.writeFile)(artifactPath, `${isolated_artifact_1.ISOLATED_PACKAGE_MAGIC}\n${JSON.stringify({ manifest, providerSource })}\n`, "utf8");
+    return artifactPath;
+}
+/**
+ * The generate-manifest step: write `dist/manifest.json` from the package's declarations.
+ *
+ * @param buildOptions - Package root, declaration entry, and output directory.
+ */
+async function generatePackageManifest(buildOptions = {}) {
+    return writeManifest(resolveOptions(buildOptions));
+}
+/**
+ * Build the package's manifest from its declarations, validated, without writing it or checking
+ * it against `frozen-contracts.json` (`peers-package contract freeze` does that itself).
+ *
+ * @param buildOptions - Package root and declaration entry.
+ */
+async function packageManifest(buildOptions = {}) {
+    return validManifest(resolveOptions(buildOptions));
+}
+/**
+ * Generate the manifest, bundle the provider for the sandbox, and write `dist/package.bundle.js`.
+ *
+ * @param buildOptions - Package root, declaration entry, and output directory.
+ */
+async function buildPackage(buildOptions = {}) {
+    const options = resolveOptions(buildOptions);
+    const manifest = await checkedManifest(options);
+    const output = await options.esbuild.build(providerBuildOptions(options, manifest));
+    const providerSource = output.outputFiles?.[0]?.text ?? "";
+    const artifactPath = await writeArtifact(options, manifest, providerSource);
+    const { manifestPath } = await saveManifest(options, manifest);
+    return { manifest, manifestPath, artifactPath, providerChars: providerSource.length };
+}
+/**
+ * Build once, then rebuild whenever a source file changes. Resolves once watching starts.
+ *
+ * @param buildOptions - Package root, declaration entry, and output directory.
+ * @param onBuild - Called after each build, with its result or error.
+ * @returns A handle that stops watching when disposed.
+ */
+async function watchPackage(buildOptions = {}, onBuild = () => undefined) {
+    const options = resolveOptions(buildOptions);
+    const manifest = await validManifest(options);
+    let mode = manifest.executionMode ?? "sandbox";
+    let disposed = false;
+    let restart = Promise.resolve();
+    let context;
+    const rebuild = {
+        name: "peers-package-write",
+        setup(build) {
+            build.onEnd(async () => {
+                if (disposed)
+                    return;
+                try {
+                    // Recreate the provider's options from the current declaration on every rebuild:
+                    // executionMode can change which platform and dependency exports must be bundled.
+                    const latest = await buildPackage(buildOptions);
+                    onBuild(latest);
+                    const nextMode = latest.manifest.executionMode ?? "sandbox";
+                    if (nextMode !== mode) {
+                        mode = nextMode;
+                        // Dispose after this onEnd returns: awaiting disposal here would deadlock it.
+                        // Recreate the watch graph too, so browser/node conditional dependencies are watched.
+                        restart = restart
+                            .then(async () => {
+                            await context.dispose();
+                            if (disposed)
+                                return;
+                            context = await options.esbuild.context(providerBuildOptions(options, latest.manifest, [rebuild]));
+                            await context.watch();
+                        })
+                            .catch((error) => {
+                            onBuild(error instanceof Error ? error : new Error(String(error)));
+                        });
+                    }
+                }
+                catch (error) {
+                    onBuild(error instanceof Error ? error : new Error(String(error)));
+                }
+            });
+        },
+    };
+    context = await options.esbuild.context(providerBuildOptions(options, manifest, [rebuild]));
+    try {
+        await context.watch();
+        return {
+            async dispose() {
+                disposed = true;
+                await restart;
+                await context.dispose();
+            },
+        };
+    }
+    catch (error) {
+        await context.dispose();
+        throw error;
+    }
+}

package/dist/package-build/build-package.test.d.ts

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