@peers-app/peers-sdk 0.26.6 → 0.27.0

package/dist/define/vars.d.ts

@@ -0,0 +1,82 @@
+import type { PersistentVarScope } from "../data/persistent-var-identity";
+import { type Observable } from "../observable";
+import type { IPackageContext } from "./context";
+/**
+ * A package's own persistent variable: an observable kept in step with the stored value. Read it
+ * with `v()`, write it with `v(value)`, and `subscribe` to changes, including changes from other
+ * devices. Use it at module scope; it needs no `ctx`.
+ */
+export type PersistentVar<T> = Observable<T> & {
+    /**
+     * Resolves once the stored value is loaded, and again once the writes made so far are saved.
+     * In a package worker, variables declared at module scope are loaded before the first call.
+     */
+    loadingPromise: Promise<PersistentVar<T>>;
+    /** Clear the stored value and go back to the default. */
+    delete: () => Promise<void>;
+};
+/** Options for a package variable with a default. */
+export interface IPackageVarOptions<T> {
+    /** Read while the variable is unset (or `null`). It isn't stored by itself. */
+    defaultValue: T;
+}
+/** Declares a package variable in one scope. */
+export interface IPackageVarFactory {
+    /** A variable that reads `defaultValue` while unset. */
+    <T = string>(name: string, opts: IPackageVarOptions<T>): PersistentVar<T>;
+    /** A variable that reads `undefined` while unset. */
+    <T = string>(name: string, opts?: {
+        defaultValue?: undefined;
+    }): PersistentVar<T | undefined>;
+}
+/** Where a package variable is stored, for an observable it backs. */
+export interface IPackageVarBinding {
+    scope: PersistentVarScope;
+    name: string;
+    /** Undefined when the variable was declared without one. */
+    defaultValue: unknown;
+}
+/**
+ * Read a package variable, refreshing its stored value and propagating
+ * storage failures to the caller. Returns this read's value even if a newer refresh is still
+ * pending. Background variable operations still log their failures.
+ *
+ * @param variable - A package variable; also used by contract observable handlers.
+ */
+export declare function readPackageVar<T>(variable: PersistentVar<T>): Promise<T>;
+/**
+ * Write a package variable and wait for persistence. Unlike callable background
+ * writes, a failed save rejects, including when the value was unchanged.
+ * Replies with this write's value, independent of later concurrent writes.
+ *
+ * @param variable - A package variable; also used by contract observable handlers.
+ * @param value - The value to store; contract handlers parse it with the observable's schema first.
+ */
+export declare function writePackageVar<T>(variable: PersistentVar<T>, value: T): Promise<T>;
+/**
+ * Load every package variable and keep it current through `ctx`. `startPackage` runs this when
+ * the worker starts, before any call. Variables declared later bind as they're declared.
+ *
+ * @param ctx - The worker's context, bound to no call.
+ */
+export declare function bindPackageVars(ctx: IPackageContext): Promise<void>;
+/**
+ * Where `value` is stored, if it's a variable from {@link deviceVar} or another scope.
+ *
+ * @param value - Anything; usually an observable's source.
+ */
+export declare function packageVarBinding(value: unknown): IPackageVarBinding | undefined;
+/**
+ * A variable stored only on this device.
+ *
+ * `const refreshSchedule = deviceVar("refreshSchedule", { defaultValue: "" });`
+ */
+export declare const deviceVar: IPackageVarFactory;
+/** A variable stored for the user and synced across all of their devices. */
+export declare const userVar: IPackageVarFactory;
+/** A variable shared by everyone in the group, synced across all of its users and devices. */
+export declare const groupVar: IPackageVarFactory;
+/** A variable for this device in the group: a different value per group, not synced. */
+export declare const groupDeviceVar: IPackageVarFactory;
+/** A variable for the user in the group, synced across the user's devices. */
+export declare const groupUserVar: IPackageVarFactory;

package/dist/define/vars.js

@@ -0,0 +1,256 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.groupUserVar = exports.groupDeviceVar = exports.groupVar = exports.userVar = exports.deviceVar = void 0;
+exports.readPackageVar = readPackageVar;
+exports.writePackageVar = writePackageVar;
+exports.bindPackageVars = bindPackageVars;
+exports.packageVarBinding = packageVarBinding;
+const observable_1 = require("../observable");
+const wire_value_1 = require("./wire-value");
+const worker_state_1 = require("./worker-state");
+const registered = new Map();
+const bindings = new WeakMap();
+const contractOperations = new WeakMap();
+/**
+ * Read a package variable, refreshing its stored value and propagating
+ * storage failures to the caller. Returns this read's value even if a newer refresh is still
+ * pending. Background variable operations still log their failures.
+ *
+ * @param variable - A package variable; also used by contract observable handlers.
+ */
+async function readPackageVar(variable) {
+    const operations = contractOperations.get(variable);
+    if (!operations)
+        throw new Error("readPackageVar takes a package variable");
+    return (await operations.read());
+}
+/**
+ * Write a package variable and wait for persistence. Unlike callable background
+ * writes, a failed save rejects, including when the value was unchanged.
+ * Replies with this write's value, independent of later concurrent writes.
+ *
+ * @param variable - A package variable; also used by contract observable handlers.
+ * @param value - The value to store; contract handlers parse it with the observable's schema first.
+ */
+async function writePackageVar(variable, value) {
+    const operations = contractOperations.get(variable);
+    if (!operations)
+        throw new Error("writePackageVar takes a package variable");
+    return (await operations.write(value));
+}
+/** Equal JSON-like values (what the host stores), so an unchanged value notifies no one. */
+function sameValue(left, right) {
+    if (left === right) {
+        return true;
+    }
+    if (left instanceof Date || right instanceof Date) {
+        return left instanceof Date && right instanceof Date && left.getTime() === right.getTime();
+    }
+    if (!left || !right || typeof left !== "object" || typeof right !== "object") {
+        return false;
+    }
+    if (Array.isArray(left) !== Array.isArray(right)) {
+        return false;
+    }
+    const leftRecord = left;
+    const rightRecord = right;
+    const keys = Object.keys(leftRecord);
+    return (keys.length === Object.keys(rightRecord).length &&
+        keys.every((key) => Object.hasOwn(rightRecord, key) && sameValue(leftRecord[key], rightRecord[key])));
+}
+function packageVar(scope, name, defaultValue) {
+    if (typeof name !== "string" || name.trim() === "") {
+        throw new Error("A package variable needs a name");
+    }
+    const key = JSON.stringify([scope, name]);
+    const existing = registered.get(key);
+    if (existing) {
+        return existing.variable;
+    }
+    const variable = (0, observable_1.observable)(defaultValue);
+    // Outside a worker (tests, the manifest build) the variable is in memory and already loaded.
+    variable.loadingPromise = Promise.resolve(variable);
+    let ctx;
+    /** True while a stored value is written into the observable, so it isn't saved back. */
+    let applying = false;
+    /** Writes not yet saved. A stored value read meanwhile is stale. */
+    let pending = 0;
+    /** Reads issued so far; only the latest one applies. */
+    let reads = 0;
+    /** Capture the first save issued by a contract write, before subscribers can write again. */
+    let contractWrite;
+    const apply = (stored) => {
+        const next = (stored === null || stored === undefined ? defaultValue : stored);
+        if (sameValue(next, variable())) {
+            return;
+        }
+        applying = true;
+        try {
+            variable(next);
+        }
+        finally {
+            applying = false;
+        }
+    };
+    // Notifications carry no value and can arrive out of order, so read the value again.
+    const refresh = async () => {
+        const bound = ctx;
+        if (!bound) {
+            return { failed: false, value: variable() };
+        }
+        const read = ++reads;
+        try {
+            const stored = await bound.getOwnedPersistentVar(scope, name);
+            if (read === reads && pending === 0) {
+                apply(stored);
+            }
+            return { failed: false, value: stored ?? defaultValue };
+        }
+        catch (error) {
+            console.error(`Reading package variable "${name}" failed`, error);
+            return { failed: true, error };
+        }
+    };
+    const queueSave = (stored) => {
+        const bound = ctx;
+        if (!bound) {
+            return;
+        }
+        // Capture before waiting for earlier saves: the package may mutate its source again.
+        // Report an unsupported value through the usual save result, including for background writes.
+        let captured;
+        try {
+            captured = { value: (0, wire_value_1.snapshotPackageValue)(stored) };
+        }
+        catch (error) {
+            captured = { error };
+        }
+        pending += 1;
+        const saved = variable.loadingPromise.then(async () => {
+            let result = { failed: false };
+            try {
+                if ("error" in captured)
+                    throw captured.error;
+                await bound.setOwnedPersistentVar(scope, name, captured.value);
+            }
+            catch (error) {
+                console.error(`Saving package variable "${name}" failed`, error);
+                result = { failed: true, error };
+            }
+            finally {
+                pending -= 1;
+            }
+            // The outcome is the save's. A failed refresh after it only leaves the mirror stale,
+            // and refresh logs that itself.
+            if (pending === 0) {
+                await refresh();
+            }
+            return result;
+        });
+        if (contractWrite && !contractWrite.saved)
+            contractWrite.saved = saved;
+        variable.loadingPromise = saved.then(() => variable);
+    };
+    // Registered first, so it sees the applied value before any package subscriber. Only that
+    // value is skipped; a package subscriber's write in response is saved like any other.
+    variable.subscribe((value) => {
+        if (applying) {
+            applying = false;
+            return;
+        }
+        queueSave(value ?? null);
+    });
+    variable.delete = async () => {
+        await variable.loadingPromise;
+        queueSave(null);
+        apply(null);
+        await variable.loadingPromise;
+    };
+    const bind = (bound) => {
+        ctx = bound;
+        const load = (async () => {
+            try {
+                // Watch first, so a change between the read and the watch isn't missed.
+                await bound.watchOwnedPersistentVar(scope, name, refresh);
+            }
+            catch (error) {
+                console.error(`Watching package variable "${name}" failed`, error);
+            }
+            return refresh();
+        })();
+        variable.loadingPromise = load.then(() => variable);
+        return load.then(() => undefined);
+    };
+    contractOperations.set(variable, {
+        async read() {
+            await variable.loadingPromise;
+            const result = await refresh();
+            if (result.failed)
+                throw result.error;
+            return result.value;
+        },
+        async write(value) {
+            const written = (0, wire_value_1.snapshotPackageValue)(value);
+            const previous = contractWrite;
+            const operation = {};
+            contractWrite = operation;
+            try {
+                variable(value);
+                // Observables need not notify for an unchanged value. An explicit contract write
+                // still persists it, and can recover from an earlier failed save.
+                if (!operation.saved)
+                    queueSave(value ?? null);
+            }
+            finally {
+                contractWrite = previous;
+            }
+            // A subscriber may have queued more saves synchronously. Only this write's save
+            // determines its result; later package writes have their own outcomes.
+            const result = await operation.saved;
+            if (result?.failed)
+                throw result.error;
+            return written;
+        },
+    });
+    registered.set(key, { variable: variable, bind });
+    bindings.set(variable, Object.freeze({ scope, name, defaultValue }));
+    const started = (0, worker_state_1.packageContext)();
+    if (started) {
+        void bind(started);
+    }
+    return variable;
+}
+function scopedVar(scope) {
+    return ((name, opts) => packageVar(scope, name, opts?.defaultValue));
+}
+/**
+ * Load every package variable and keep it current through `ctx`. `startPackage` runs this when
+ * the worker starts, before any call. Variables declared later bind as they're declared.
+ *
+ * @param ctx - The worker's context, bound to no call.
+ */
+async function bindPackageVars(ctx) {
+    await Promise.all([...registered.values()].map((entry) => entry.bind(ctx)));
+}
+/**
+ * Where `value` is stored, if it's a variable from {@link deviceVar} or another scope.
+ *
+ * @param value - Anything; usually an observable's source.
+ */
+function packageVarBinding(value) {
+    return typeof value === "function" ? bindings.get(value) : undefined;
+}
+/**
+ * A variable stored only on this device.
+ *
+ * `const refreshSchedule = deviceVar("refreshSchedule", { defaultValue: "" });`
+ */
+exports.deviceVar = scopedVar("device");
+/** A variable stored for the user and synced across all of their devices. */
+exports.userVar = scopedVar("user");
+/** A variable shared by everyone in the group, synced across all of its users and devices. */
+exports.groupVar = scopedVar("group");
+/** A variable for this device in the group: a different value per group, not synced. */
+exports.groupDeviceVar = scopedVar("groupDevice");
+/** A variable for the user in the group, synced across the user's devices. */
+exports.groupUserVar = scopedVar("groupUser");

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

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

package/dist/define/vars.test.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("./index");
+const vars_1 = require("./vars");
+test("the public variable helpers retain value types and reject persistence failures", async () => {
+    const variable = (0, index_1.deviceVar)("awaited", { defaultValue: 0 });
+    let stored = 0;
+    let failRead = false;
+    let failWrite = false;
+    const ctx = {
+        watchOwnedPersistentVar: async () => () => undefined,
+        getOwnedPersistentVar: async () => {
+            if (failRead)
+                throw new Error("durable read failed");
+            return stored;
+        },
+        setOwnedPersistentVar: async (_scope, _name, value) => {
+            if (failWrite)
+                throw new Error("durable save failed");
+            stored = value;
+        },
+    };
+    await (0, vars_1.bindPackageVars)(ctx);
+    const saved = await (0, index_1.writePackageVar)(variable, 7);
+    const read = await (0, index_1.readPackageVar)(variable);
+    expect([saved, read]).toEqual([7, 7]);
+    const errors = jest.spyOn(console, "error").mockImplementation(() => undefined);
+    try {
+        failWrite = true;
+        await expect((0, index_1.writePackageVar)(variable, 8)).rejects.toThrow("durable save failed");
+        failWrite = false;
+        await expect((0, index_1.writePackageVar)(variable, 9)).resolves.toBe(9);
+        failRead = true;
+        await expect((0, index_1.readPackageVar)(variable)).rejects.toThrow("durable read failed");
+    }
+    finally {
+        errors.mockRestore();
+    }
+});

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

@@ -0,0 +1,12 @@
+/**
+ * Snapshot a package value for the worker bridge, as the bridge carries
+ * it. Missing object fields are omitted, and missing array entries (or a missing root value)
+ * become null, as in JSON. Dates and Uint8Arrays are copied. A value the bridge can't carry (a
+ * function, symbol, bigint, non-finite number, cycle, or an object other than a plain object,
+ * array, Date, or Uint8Array) throws here, so it fails the same way in a worker and in tests.
+ * The source value is never changed. This doesn't use `structuredClone`, which some test
+ * environments (jsdom) lack.
+ *
+ * @param value - The value to send: arguments, a result, a row, an event, or an observable value.
+ */
+export declare function snapshotPackageValue(value: unknown): unknown;

package/dist/define/wire-value.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.snapshotPackageValue = snapshotPackageValue;
+/**
+ * Snapshot a package value for the worker bridge, as the bridge carries
+ * it. Missing object fields are omitted, and missing array entries (or a missing root value)
+ * become null, as in JSON. Dates and Uint8Arrays are copied. A value the bridge can't carry (a
+ * function, symbol, bigint, non-finite number, cycle, or an object other than a plain object,
+ * array, Date, or Uint8Array) throws here, so it fails the same way in a worker and in tests.
+ * The source value is never changed. This doesn't use `structuredClone`, which some test
+ * environments (jsdom) lack.
+ *
+ * @param value - The value to send: arguments, a result, a row, an event, or an observable value.
+ */
+function snapshotPackageValue(value) {
+    const ancestors = new Set();
+    const copy = (current, path) => {
+        if (current === null || typeof current === "string" || typeof current === "boolean") {
+            return current;
+        }
+        if (typeof current === "number") {
+            if (!Number.isFinite(current)) {
+                throw new TypeError(`${path} is ${current}; only finite numbers can be sent`);
+            }
+            return current;
+        }
+        if (typeof current !== "object") {
+            throw new TypeError(`${path} is a ${typeof current}, which can't be sent`);
+        }
+        const tag = Object.prototype.toString.call(current);
+        if (tag === "[object Date]") {
+            const time = Date.prototype.getTime.call(current);
+            if (!Number.isFinite(time)) {
+                throw new TypeError(`${path} is an invalid Date, which can't be sent`);
+            }
+            return new Date(time);
+        }
+        if (tag === "[object Uint8Array]") {
+            return new Uint8Array(current);
+        }
+        if (ancestors.has(current)) {
+            throw new TypeError(`${path} contains itself; cycles can't be sent`);
+        }
+        ancestors.add(current);
+        try {
+            if (Array.isArray(current)) {
+                const items = [];
+                for (let index = 0; index < current.length; index += 1) {
+                    const item = current[index];
+                    items.push(item === undefined ? null : copy(item, `${path}[${index}]`));
+                }
+                return items;
+            }
+            if (tag !== "[object Object]") {
+                throw new TypeError(`${path} is a ${tag.slice(8, -1)}, which can't be sent`);
+            }
+            const record = {};
+            for (const [key, field] of Object.entries(current)) {
+                if (field !== undefined) {
+                    // Define rather than assign, so a "__proto__" key stays a field.
+                    Object.defineProperty(record, key, {
+                        value: copy(field, `${path}.${key}`),
+                        enumerable: true,
+                        writable: true,
+                        configurable: true,
+                    });
+                }
+            }
+            return record;
+        }
+        finally {
+            ancestors.delete(current);
+        }
+    };
+    return value === undefined ? null : copy(value, "value");
+}

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

@@ -0,0 +1,15 @@
+import type { IPackageContext } from "./context";
+/**
+ * Record the context the worker started with, for the package's variables, events, and
+ * observables. Called by `startPackage`.
+ *
+ * @param ctx - The worker's context, bound to no call.
+ */
+export declare function setPackageContext(ctx: IPackageContext): void;
+/** The started worker's context, or undefined before the start and outside a worker. */
+export declare function packageContext(): IPackageContext | undefined;
+/**
+ * Resolves with the worker's context once it starts. Undefined outside a worker, where there's
+ * nothing to wait for.
+ */
+export declare function whenPackageStarts(): Promise<IPackageContext> | undefined;

package/dist/define/worker-state.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setPackageContext = setPackageContext;
+exports.packageContext = packageContext;
+exports.whenPackageStarts = whenPackageStarts;
+/** The context the package worker started with; undefined until then, and outside a worker. */
+let context;
+let started;
+let resolveStarted;
+/** True in a package worker: the Runtime defines `onWorkerStart` before the package's code runs. */
+function inPackageWorker() {
+    return typeof globalThis.onWorkerStart === "function";
+}
+/**
+ * Record the context the worker started with, for the package's variables, events, and
+ * observables. Called by `startPackage`.
+ *
+ * @param ctx - The worker's context, bound to no call.
+ */
+function setPackageContext(ctx) {
+    context = ctx;
+    resolveStarted?.(ctx);
+    resolveStarted = undefined;
+    started = Promise.resolve(ctx);
+}
+/** The started worker's context, or undefined before the start and outside a worker. */
+function packageContext() {
+    return context;
+}
+/**
+ * Resolves with the worker's context once it starts. Undefined outside a worker, where there's
+ * nothing to wait for.
+ */
+function whenPackageStarts() {
+    if (context) {
+        return Promise.resolve(context);
+    }
+    if (!inPackageWorker()) {
+        return undefined;
+    }
+    started ??= new Promise((resolve) => {
+        resolveStarted = resolve;
+    });
+    return started;
+}

package/dist/device/tx-encoding.test.js

@@ -149,6 +149,16 @@ describe("tx-encode-decode", () => {
             expect(() => (0, tx_encoding_1.txDecode)(invalidPayload)).toThrow("Unknown tx flag: 255");
         });
     });
+    describe("untrusted input", () => {
+        afterEach(() => {
+            delete Object.prototype.polluted;
+        });
+        it("does not let a decoded message write onto Object.prototype", () => {
+            const decoded = (0, tx_encoding_1.txDecode)((0, tx_encoding_1.txEncode)({ __this_ref: "__proto__", polluted: "yes" }));
+            expect({}.polluted).toBeUndefined();
+            expect(decoded).toEqual({ polluted: "yes" });
+        });
+    });
     describe("round-trip consistency", () => {
         it("should handle empty objects", () => {
             const emptyObj = {};

package/dist/index.d.ts

@@ -5,6 +5,9 @@ export * as data from "./data";
 export * from "./data/orm";
 export * as orm from "./data/orm";
 export { getLogger, type IWorkflowLog, WorkflowLogs, workflowLogSchema, } from "./data/workflow-logs";
+export { type AnyContractTools, type ContractClientTool, type ContractClientTools, type ContractEventPayloadsOf, type ContractIdOf, type ContractObservableValuesOf, type ContractObservableWritabilityOf, type ContractTableInputsOf, type ContractTableRowsOf, type ContractToolsOf, type ContractVersionOf, contractRef, type IContractClient, type IContractRef, } from "./define/contract-ref";
+export type { IPackageContract, IPackageDefinition, } from "./define/define-package";
+export { buildPackageManifest } from "./define/manifest";
 export * from "./device/binary-peer-connection-v2";
 export * from "./device/connection";
 export * from "./device/device";

package/dist/index.js

@@ -14,7 +14,7 @@ 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.workflowLogSchema = exports.WorkflowLogs = exports.getLogger = exports.orm = exports.data = void 0;
+exports.buildPackageManifest = exports.contractRef = exports.workflowLogSchema = exports.WorkflowLogs = exports.getLogger = exports.orm = exports.data = void 0;
 __exportStar(require("./context"), exports);
 __exportStar(require("./contracts"), exports);
 __exportStar(require("./data"), exports);
@@ -26,6 +26,10 @@ var workflow_logs_1 = require("./data/workflow-logs");
 Object.defineProperty(exports, "getLogger", { enumerable: true, get: function () { return workflow_logs_1.getLogger; } });
 Object.defineProperty(exports, "WorkflowLogs", { enumerable: true, get: function () { return workflow_logs_1.WorkflowLogs; } });
 Object.defineProperty(exports, "workflowLogSchema", { enumerable: true, get: function () { return workflow_logs_1.workflowLogSchema; } });
+var contract_ref_1 = require("./define/contract-ref");
+Object.defineProperty(exports, "contractRef", { enumerable: true, get: function () { return contract_ref_1.contractRef; } });
+var manifest_1 = require("./define/manifest");
+Object.defineProperty(exports, "buildPackageManifest", { enumerable: true, get: function () { return manifest_1.buildPackageManifest; } });
 __exportStar(require("./device/binary-peer-connection-v2"), exports);
 __exportStar(require("./device/connection"), exports);
 __exportStar(require("./device/device"), exports);

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 {};