@cero-base/cero 1.18.2 → 2.0.0

package/types/handle/index.d.ts

@@ -1,4 +1,131 @@
-export { Ref } from "../lib/utils.js";
+import AbortController from 'bare-abort-controller';
+import ReadyResource from 'ready-resource';
+import { Identity } from '@cero-base/core/identity';
+import { Database } from '@cero-base/core/database';
+import { Pairing } from '@cero-base/core/pairing';
+import { Blobs } from '@cero-base/core/blobs';
+import { FileServer } from '@cero-base/core/blobs/server';
+export { Ref } from '../lib/refs.js';
+export type Network = import('@cero-base/core/network').Network;
+export type Local = import('../local/index.js').Local;
+export type KeyPair = import('@cero-base/core/identity').KeyPair;
+export type HandleOpts = {
+    /**
+     * Parent handle when this is a child slot.
+     */
+    parent?: Handle;
+    /**
+     * Long-lived user identity. Inherited from `parent` if omitted.
+     */
+    identity?: Identity;
+    /**
+     * Shared swarm. Inherited from `parent` if omitted.
+     */
+    network?: Network;
+    /**
+     * Pre-existing Corestore. Falls back to `parent.store.store`.
+     */
+    store?: any;
+    /**
+     * Built cero spec.
+     */
+    spec?: any;
+    /**
+     * Local store for per-handle keypairs.
+     */
+    local?: Local;
+    /**
+     * Owned HypercoreStorage to close on shutdown.
+     */
+    storage?: any;
+    /**
+     * Owned identity Discovery to destroy on shutdown.
+     */
+    discovery?: any;
+    /**
+     * Data directory (root handles only).
+     */
+    dir?: string;
+    /**
+     * Pass-through cero(...) options.
+     */
+    opts?: any;
+    routes?: Record<string, Function>;
+    /**
+     * Existing database key.
+     */
+    key?: Uint8Array;
+    /**
+     * Existing encryption key.
+     */
+    encryptionKey?: Uint8Array;
+    /**
+     * Rotation epochs delivered at join.
+     */
+    epochs?: Array<{
+        epoch: number;
+        entropy: Uint8Array;
+    }>;
+    /**
+     * Corestore namespace.
+     */
+    namespace?: string;
+    /**
+     * Writer keypair.
+     */
+    keyPair?: KeyPair;
+    /**
+     * Join discovery server-only; flip later with `setActive`.
+     */
+    passive?: boolean;
+    /**
+     * When `false`, skips creating a `Pairing` session.
+     */
+    pair?: boolean;
+};
+export type CreateChildOpts = {
+    name?: string | null;
+    routes?: Record<string, Function>;
+    role?: string;
+    accept?: boolean;
+};
+export type JoinChildOpts = {
+    routes?: Record<string, Function>;
+    timeout?: number;
+};
+export type StaticJoinOpts = {
+    parent?: Handle;
+    network?: Network;
+    identity?: Identity;
+    store?: any;
+    spec?: any;
+    namespace?: string;
+    routes?: Record<string, Function>;
+    timeout?: number;
+};
+export type AcceptOpts = {
+    /**
+     * Role to grant the joining peer. Falls back to the invite's role, then `'member'`.
+     */
+    role?: string;
+    name?: string | null;
+};
+export type HandleExtra = {
+    /**
+     * Display name; set on child handles by the owner flow.
+     */
+    name?: string | null;
+    /**
+     * `profile` ref, attached dynamically when the schema declares one.
+     */
+    profile?: import('../lib/refs.js').Ref;
+    /**
+     * `members` ref, attached dynamically when the schema declares one.
+     */
+    members?: import('../lib/refs.js').Ref;
+};
+export type Child = Handle & HandleExtra;
+export type CeroHandle = Handle & Record<string, import('../lib/refs.js').Ref>;
 /**
  * @typedef {import('@cero-base/core/network').Network} Network
  * @typedef {import('../local/index.js').Local} Local
@@ -48,37 +175,19 @@ export { Ref } from "../lib/utils.js";
  * @property {string} [role]   Role to grant the joining peer. Falls back to the invite's role, then `'member'`.
  * @property {string | null} [name]
  *
- * @typedef {object} RecoverOpts
- * @property {number} [timeout]
- *
  * @typedef {object} HandleExtra
  * @property {string | null} [name]                       Display name; set on child handles by the owner flow.
- * @property {import('../lib/utils.js').Ref} [profile]    `profile` ref, attached dynamically when the schema declares one.
- * @property {import('../lib/utils.js').Ref} [members]    `members` ref, attached dynamically when the schema declares one.
+ * @property {import('../lib/refs.js').Ref} [profile]    `profile` ref, attached dynamically when the schema declares one.
+ * @property {import('../lib/refs.js').Ref} [members]    `members` ref, attached dynamically when the schema declares one.
  *
  * @typedef {Handle & HandleExtra} Child  A child handle plus its dynamically-attached refs.
  *
- * @typedef {Handle & Record<string, import('../lib/utils.js').Ref>} CeroHandle  A handle with every schema ref reachable as a `Ref` property (e.g. `me.profile`, `room.messages`).
+ * @typedef {Handle & Record<string, import('../lib/refs.js').Ref>} CeroHandle  A handle with every schema ref reachable as a `Ref` property (e.g. `me.profile`, `room.messages`).
  */
 /**
  * A cero handle — a single writable database session attached to a swarm.
- * The "root" handle is the user's facade; child handles (created via
- * `_create`/`_join`/`_load`) live under it and share the same identity,
- * network and corestore. Ref properties (`profile`, `members`, ...) are
- * attached dynamically per the schema; child handles also carry a `name`.
  */
-export class Handle extends ReadyResource {
-    /**
-     * Pair into an existing handle via an invite, returning a brand-new
-     * `Handle` already configured with the resolved key + encryption key.
-     *
-     * @param {string} invite
-     * @param {StaticJoinOpts} [opts]
-     * @returns {Promise<Handle>}
-     */
-    static join(invite: string, { parent, network, identity, store, spec, namespace, routes, timeout }?: StaticJoinOpts): Promise<Handle>;
-    /** @param {HandleOpts} [opts] */
-    constructor(opts?: HandleOpts);
+export declare class Handle extends ReadyResource {
     identity: any;
     network: any;
     spec: any;
@@ -101,11 +210,45 @@ export class Handle extends ReadyResource {
     store: Database;
     pair: Pairing;
     _wantsPair: boolean;
+    _ac: AbortController;
     _invitesSync: () => Promise<void>;
+    /** @param {HandleOpts} [opts] */
+    constructor(opts?: HandleOpts);
+    /**
+     * An `AbortSignal` that fires when this handle closes.
+     *
+     * @returns {AbortSignal}
+     */
+    get signal(): AbortSignal;
+    /** The top-most handle in the parent chain — itself for a root handle. */
+    get root(): this;
+    /**
+     * Lazily-built file server for this identity. Root-only — child handles
+     * reach it through `this.root.fileServer`.
+     *
+     * @returns {FileServer}
+     */
+    get fileServer(): FileServer;
     /**
-     * Tie a destroyable resource (a `watch` stream, a timer, any `{ destroy }`)
-     * to this handle's lifecycle — it's destroyed automatically on close, so
-     * callers don't track cleanup. De-registers itself if destroyed earlier.
+     * Lazily-built blob store for THIS handle's writing device, at the current rotation epoch.
+     *
+     * @returns {Blobs}
+     */
+    get blobs(): Blobs;
+    /** Canonical id — identity id for the root handle, store key for children. */
+    get id(): any;
+    /** This device's id + name. `null` on child handles. */
+    get device(): {
+        id: any;
+        name: any;
+    };
+    get suspended(): boolean;
+    _open(): Promise<void>;
+    _close(): Promise<void>;
+    /**
+     * Tie a destroyable resource (a `watch` stream, a timer, any `{ destroy }`) to this
+     * handle's lifecycle — it's destroyed automatically on close, so callers don't track
+     * cleanup.
      *
      * @template {{ destroy?: Function, once?: Function }} T
      * @param {T} resource
@@ -115,15 +258,6 @@ export class Handle extends ReadyResource {
         destroy?: Function;
         once?: Function;
     }>(resource: T): T;
-    /**
-     * An `AbortSignal` that fires when this handle closes. Pass it as
-     * `{ signal }` to `on`/`after`/`before`/`watch` to drop a subscription on
-     * close — or use your own `AbortController` for a finer scope.
-     *
-     * @returns {AbortSignal}
-     */
-    get signal(): AbortSignal;
-    _ac: AbortController;
     /**
      * `EventEmitter.on` plus an optional `{ signal }` that removes the listener
      * when the signal aborts — e.g. `me.on('handle', fn, { signal: me.signal })`.
@@ -136,24 +270,6 @@ export class Handle extends ReadyResource {
     on(event: string, fn: (...args: any[]) => void, opts?: {
         signal?: AbortSignal;
     }): this;
-    /** The top-most handle in the parent chain — itself for a root handle. */
-    get root(): this;
-    /**
-     * Lazily-built file server for this identity. Root-only — child handles
-     * reach it through `this.root.fileServer`.
-     *
-     * @returns {FileServer}
-     */
-    get fileServer(): FileServer;
-    /**
-     * @param {Uint8Array} coreKey
-     * @param {object} info
-     * @returns {{ key: Uint8Array, encryptionKey: Uint8Array } | null}
-     */
-    _resolveCore(coreKey: Uint8Array, info: object): {
-        key: Uint8Array;
-        encryptionKey: Uint8Array;
-    } | null;
     /**
      * Resolve a durable file id to an ephemeral download url via this identity's
      * file server.
@@ -162,38 +278,6 @@ export class Handle extends ReadyResource {
      * @returns {string}
      */
     getLink(id: string): string;
-    /**
-     * Lazily-built blob store for THIS handle's writing device, at the current
-     * rotation epoch. One core per writer per epoch that writes files: the base
-     * era uses the handle's encryptionKey, rotated epochs use a key derived
-     * from the epoch entropy — so a removed member cannot decrypt files added
-     * after the rotation. Instances carry `.stamp` so the file row records
-     * which era its core belongs to.
-     *
-     * @returns {Blobs}
-     */
-    get blobs(): Blobs;
-    _baseBlobs(): Blobs;
-    _makeBlobs(name: any, encryptionKey: any, stamp: any): Blobs;
-    /**
-     * Remember the blob-core key a file id points at so the file server can
-     * open the core. Lives on the Handle (not the shared operators) because the
-     * epoch-key derivation pulls native crypto — the RPC client must stay
-     * bundleable without it.
-     *
-     * @param {string} id
-     * @param {number} [stamp]
-     */
-    _registerBlobCore(id: string, stamp?: number): void;
-    _blobCoreKey(stamp: any): Uint8Array<ArrayBufferLike>;
-    /** Canonical id — identity id for the root handle, store key for children. */
-    get id(): any;
-    /** This device's id + name. `null` on child handles. */
-    get device(): {
-        id: string;
-        name: any;
-    };
-    get suspended(): boolean;
     /**
      * Initialise a fresh database: write the genesis claim, derive the writer.
      * Forwards to `Database.bootstrap`.
@@ -210,17 +294,9 @@ export class Handle extends ReadyResource {
      */
     claim(): Promise<void>;
     /**
-     * Claim + wait until this peer becomes a writer + bring the bee up to date.
-     * Used by `restore()` after wiping local state.
-     *
-     * @param {RecoverOpts} [opts]
-     * @returns {Promise<void>}
-     */
-    recover({ timeout }?: RecoverOpts): Promise<void>;
-    /**
-     * Flip this handle's swarm announce mode — `setActive(false)` demotes an
-     * idle/background room to server-only (still reachable, stops searching);
-     * `setActive(true)` promotes it back on focus. Cheap, safe to call often.
+     * Flip this handle's swarm announce mode — `setActive(false)` demotes an idle/background
+     * room to server-only (still reachable, stops searching); `setActive(true)` promotes it
+     * back on focus.
      *
      * @param {boolean} active
      * @returns {Promise<void>}
@@ -237,7 +313,6 @@ export class Handle extends ReadyResource {
         expiresIn?: number;
         data?: any;
     }): Promise<string>;
-    _syncInvites(): Promise<void>;
     /**
      * Revoke a previously-minted invite by its string form.
      *
@@ -254,7 +329,6 @@ export class Handle extends ReadyResource {
      * @returns {Promise<void>}
      */
     accept(candidate: any, { role, name }?: AcceptOpts): Promise<void>;
-    _checkGrant(role: any): Promise<void>;
     /**
      * Leave a child handle — removes it from the parent's `handles` collection
      * and closes the session. No-op on root handles.
@@ -263,9 +337,41 @@ export class Handle extends ReadyResource {
      */
     leave(): Promise<void>;
     /**
-     * Create a new child handle of `type`. Owner-flow — generates a fresh
-     * writer, adds it as a writer + member, and registers the child on the
-     * parent's `handles` collection.
+     * Pause networking + storage. Idempotent; no-op on child handles.
+     *
+     * @returns {Promise<void>}
+     */
+    suspend(): Promise<void>;
+    /**
+     * Resume a suspended root handle. Idempotent; no-op on child handles.
+     *
+     * @returns {Promise<void>}
+     */
+    resume(): Promise<void>;
+    /**
+     * @param {Uint8Array} coreKey
+     * @param {object} info
+     * @returns {{ key: Uint8Array, encryptionKey: Uint8Array } | null}
+     */
+    _resolveCore(coreKey: Uint8Array, info: object): {
+        key: Uint8Array;
+        encryptionKey: Uint8Array;
+    } | null;
+    _baseBlobs(): Blobs;
+    _makeBlobs(name: any, encryptionKey: any, stamp: any): Blobs;
+    /**
+     * Remember the blob-core key a file id points at so the file server can open the core.
+     *
+     * @param {string} id
+     * @param {number} [stamp]
+     */
+    _registerBlobCore(id: string, stamp?: number): void;
+    _blobCoreKey(stamp: any): Uint8Array<ArrayBufferLike>;
+    _syncInvites(): Promise<void>;
+    _checkGrant(role: any): Promise<void>;
+    /**
+     * Create a new child handle of `type`. Owner-flow — generates a fresh writer, adds it as a
+     * writer + member, and registers the child on the parent's `handles` collection.
      *
      * @param {string} type
      * @param {CreateChildOpts} [opts]
@@ -273,9 +379,7 @@ export class Handle extends ReadyResource {
      */
     _create(type: string, { name, routes, role, accept }?: CreateChildOpts): Promise<Handle>;
     /**
-     * Join a child handle by invite (joiner-flow). Waits for writer
-     * capability and registers the child on the parent's `handles`
-     * collection.
+     * Join a child handle by invite (joiner-flow).
      *
      * @param {string} invite
      * @param {string} type
@@ -292,9 +396,8 @@ export class Handle extends ReadyResource {
      */
     _pair(invite: string, type: string, { routes, timeout }?: JoinChildOpts, target?: Uint8Array | null): Promise<Handle>;
     /**
-     * Get an open child by id, or re-open it. Concurrent calls for the same id
-     * share one in-flight load, so the child is built — and `handle` emitted —
-     * exactly once.
+     * Get an open child by id, or re-open it. Concurrent calls for the same id share one
+     * in-flight load, so the child is built — and `handle` emitted — exactly once.
      *
      * @param {string} type
      * @param {string} id
@@ -310,19 +413,7 @@ export class Handle extends ReadyResource {
      * @returns {Promise<Handle>}
      */
     _reopen(type: string, id: string, opts: any): Promise<Handle>;
-    /**
-     * Pause networking + storage. Idempotent; no-op on child handles.
-     *
-     * @returns {Promise<void>}
-     */
-    suspend(): Promise<void>;
     _suspend(): Promise<void>;
-    /**
-     * Resume a suspended root handle. Idempotent; no-op on child handles.
-     *
-     * @returns {Promise<void>}
-     */
-    resume(): Promise<void>;
     _resume(): Promise<void>;
     /**
      * @param {Handle} child
@@ -348,140 +439,13 @@ export class Handle extends ReadyResource {
         publicKey: Uint8Array;
         secretKey: Uint8Array;
     } | null>;
-}
-export type Network = import("@cero-base/core/network").Network;
-export type Local = import("../local/index.js").Local;
-export type KeyPair = import("@cero-base/core/identity").KeyPair;
-export type HandleOpts = {
-    /**
-     * Parent handle when this is a child slot.
-     */
-    parent?: Handle;
-    /**
-     * Long-lived user identity. Inherited from `parent` if omitted.
-     */
-    identity?: Identity;
-    /**
-     * Shared swarm. Inherited from `parent` if omitted.
-     */
-    network?: Network;
-    /**
-     * Pre-existing Corestore. Falls back to `parent.store.store`.
-     */
-    store?: any;
-    /**
-     * Built cero spec.
-     */
-    spec?: any;
-    /**
-     * Local store for per-handle keypairs.
-     */
-    local?: Local;
-    /**
-     * Owned HypercoreStorage to close on shutdown.
-     */
-    storage?: any;
-    /**
-     * Owned identity Discovery to destroy on shutdown.
-     */
-    discovery?: any;
-    /**
-     * Data directory (root handles only).
-     */
-    dir?: string;
-    /**
-     * Pass-through cero(...) options.
-     */
-    opts?: any;
-    routes?: Record<string, Function>;
-    /**
-     * Existing database key.
-     */
-    key?: Uint8Array;
-    /**
-     * Existing encryption key.
-     */
-    encryptionKey?: Uint8Array;
-    /**
-     * Rotation epochs delivered at join.
-     */
-    epochs?: Array<{
-        epoch: number;
-        entropy: Uint8Array;
-    }>;
-    /**
-     * Corestore namespace.
-     */
-    namespace?: string;
-    /**
-     * Writer keypair.
-     */
-    keyPair?: KeyPair;
-    /**
-     * Join discovery server-only; flip later with `setActive`.
-     */
-    passive?: boolean;
-    /**
-     * When `false`, skips creating a `Pairing` session.
-     */
-    pair?: boolean;
-};
-export type CreateChildOpts = {
-    name?: string | null;
-    routes?: Record<string, Function>;
-    role?: string;
-    accept?: boolean;
-};
-export type JoinChildOpts = {
-    routes?: Record<string, Function>;
-    timeout?: number;
-};
-export type StaticJoinOpts = {
-    parent?: Handle;
-    network?: Network;
-    identity?: Identity;
-    store?: any;
-    spec?: any;
-    namespace?: string;
-    routes?: Record<string, Function>;
-    timeout?: number;
-};
-export type AcceptOpts = {
     /**
-     * Role to grant the joining peer. Falls back to the invite's role, then `'member'`.
-     */
-    role?: string;
-    name?: string | null;
-};
-export type RecoverOpts = {
-    timeout?: number;
-};
-export type HandleExtra = {
-    /**
-     * Display name; set on child handles by the owner flow.
-     */
-    name?: string | null;
-    /**
-     * `profile` ref, attached dynamically when the schema declares one.
-     */
-    profile?: import("../lib/utils.js").Ref;
-    /**
-     * `members` ref, attached dynamically when the schema declares one.
+     * Pair into an existing handle via an invite, returning a brand-new
+     * `Handle` already configured with the resolved key + encryption key.
+     *
+     * @param {string} invite
+     * @param {StaticJoinOpts} [opts]
+     * @returns {Promise<Handle>}
      */
-    members?: import("../lib/utils.js").Ref;
-};
-/**
- * A child handle plus its dynamically-attached refs.
- */
-export type Child = Handle & HandleExtra;
-/**
- * A handle with every schema ref reachable as a `Ref` property (e.g. `me.profile`, `room.messages`).
- */
-export type CeroHandle = Handle & Record<string, import("../lib/utils.js").Ref>;
-import ReadyResource from 'ready-resource';
-import { FileServer } from '@cero-base/core/blobs/server';
-import { Blobs } from '@cero-base/core/blobs';
-import { Database } from '@cero-base/core/database';
-import { Pairing } from '@cero-base/core/pairing';
-import AbortController from 'bare-abort-controller';
-import { Identity } from '@cero-base/core/identity';
+    static join(invite: string, { parent, network, identity, store, spec, namespace, routes, timeout }?: StaticJoinOpts): Promise<Handle>;
+}