@cero-base/cero 0.4.0

package/types/index.d.ts

@@ -0,0 +1,102 @@
+/**
+ * @typedef {object} CeroOpts
+ * @property {Identity} [identity]                     Pre-resolved identity. If absent, derived from `seed`/`phrase` or generated.
+ * @property {Uint8Array} [seed]                       16- or 32-byte seed entropy.
+ * @property {string} [phrase]                         BIP-39 mnemonic — alternative to `seed`.
+ * @property {12 | 24} [words]                         Mnemonic length when generating a fresh identity.
+ * @property {string | null} [name]                    Friendly device name persisted on the identity claim.
+ * @property {boolean} [isMobile]                      Marks this device as mobile.
+ * @property {Array<{ host: string, port: number }>} [bootstrap]  Custom DHT bootstrap nodes.
+ * @property {Uint8Array} [key]                        Pre-existing database key (skip bootstrap).
+ * @property {Uint8Array} [encryptionKey]              Pre-existing encryption key.
+ * @property {Record<string, Function>} [routes]       Custom RPC routes for the database dispatcher.
+ * @property {(err: any) => void} [onerror]            Background-task error handler.
+ * @property {boolean} [recovery]                      Recovery flow — wipe local state and re-claim a writer slot.
+ * @property {number} [recoveryTimeout]                Max wait for writer capability during recovery.
+ */
+/**
+ * Open (or create) a cero handle at `dir`. Sets up storage, network and
+ * identity, then returns a ready root `Handle` with all schema refs
+ * attached as properties.
+ *
+ * @param {string} dir       Data directory.
+ * @param {any} spec         Built spec — output of `cero/build`.
+ * @param {CeroOpts} [opts]
+ * @returns {Promise<Handle>}
+ */
+export function cero(dir: string, spec: any, opts?: CeroOpts): Promise<Handle>;
+/**
+ * Restore a cero instance from a mnemonic phrase. Closes the running
+ * instance, wipes the on-disk `main/` tree and re-opens with `recovery: true`
+ * so the writer slot is re-claimed.
+ *
+ * @param {Handle} me   Existing root handle to restore.
+ * @param {string} phrase   BIP-39 mnemonic phrase.
+ * @returns {Promise<Handle>}  Freshly restored root handle.
+ */
+export function restore(me: Handle, phrase: string): Promise<Handle>;
+export { peek } from "./lib/peek.js";
+export type CeroOpts = {
+    /**
+     * Pre-resolved identity. If absent, derived from `seed`/`phrase` or generated.
+     */
+    identity?: Identity;
+    /**
+     * 16- or 32-byte seed entropy.
+     */
+    seed?: Uint8Array;
+    /**
+     * BIP-39 mnemonic — alternative to `seed`.
+     */
+    phrase?: string;
+    /**
+     * Mnemonic length when generating a fresh identity.
+     */
+    words?: 12 | 24;
+    /**
+     * Friendly device name persisted on the identity claim.
+     */
+    name?: string | null;
+    /**
+     * Marks this device as mobile.
+     */
+    isMobile?: boolean;
+    /**
+     * Custom DHT bootstrap nodes.
+     */
+    bootstrap?: Array<{
+        host: string;
+        port: number;
+    }>;
+    /**
+     * Pre-existing database key (skip bootstrap).
+     */
+    key?: Uint8Array;
+    /**
+     * Pre-existing encryption key.
+     */
+    encryptionKey?: Uint8Array;
+    /**
+     * Custom RPC routes for the database dispatcher.
+     */
+    routes?: Record<string, Function>;
+    /**
+     * Background-task error handler.
+     */
+    onerror?: (err: any) => void;
+    /**
+     * Recovery flow — wipe local state and re-claim a writer slot.
+     */
+    recovery?: boolean;
+    /**
+     * Max wait for writer capability during recovery.
+     */
+    recoveryTimeout?: number;
+};
+import { Handle } from './handle/index.js';
+import { Ref } from './handle/index.js';
+import { Local } from './local/index.js';
+import { Identity } from '@cero-base/core/identity';
+export { Handle, Ref, Local };
+export { put, set, get, del, count, watch, call, open } from "./lib/operators.js";
+export { t, schema } from "./lib/spec.js";

package/types/lib/builtins.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Map a schema-DSL primitive name to its HyperDB type name.
+ *
+ * @param {string} prim
+ * @returns {string}
+ */
+export function hyperdbType(prim: string): string;
+/**
+ * Type descriptors registered into every main schema.
+ *
+ * @returns {TypeDesc[]}
+ */
+export function builtinTypes(): TypeDesc[];
+/**
+ * Collection descriptors for every main schema, namespaced under `ns`.
+ *
+ * @param {string} ns
+ * @returns {CollectionDesc[]}
+ */
+export function builtinCollections(ns: string): CollectionDesc[];
+/**
+ * Dispatch (mutation) descriptors for every main schema, namespaced under `ns`.
+ *
+ * @param {string} ns
+ * @returns {DispatchDesc[]}
+ */
+export function builtinDispatches(ns: string): DispatchDesc[];
+/**
+ * Type descriptors registered into every local schema.
+ *
+ * @returns {TypeDesc[]}
+ */
+export function localBuiltinTypes(): TypeDesc[];
+/**
+ * Collection descriptors for every local schema, namespaced under `ns`.
+ *
+ * @param {string} ns
+ * @returns {CollectionDesc[]}
+ */
+export function localBuiltinCollections(ns: string): CollectionDesc[];
+/**
+ * Request/response type descriptors for the RPC facade.
+ *
+ * @returns {TypeDesc[]}
+ */
+export function rpcTypes(): TypeDesc[];
+/**
+ * RPC command (verb) descriptors for the cero server, namespaced under `ns`.
+ *
+ * @param {string} ns
+ * @returns {CommandDesc[]}
+ */
+export function rpcCommands(ns: string): CommandDesc[];
+/**
+ * Builtin type/collection/dispatch/rpc definitions used by the builder.
+ * Every cero schema includes these; user-defined refs are added on top.
+ *
+ * @typedef {{ name: string, type: string, verb?: string, kind?: string }} BuiltinRef
+ * @typedef {{ name: string, type: string, required: boolean }} FieldDesc
+ * @typedef {{ name: string, compact: boolean, fields: FieldDesc[] }} TypeDesc
+ * @typedef {{ name: string, schema: string, key: string[] }} CollectionDesc
+ * @typedef {{ name: string, requestType: string }} DispatchDesc
+ * @typedef {{
+ *   name: string,
+ *   request: { name: string },
+ *   response: { name: string, stream?: boolean }
+ * }} CommandDesc
+ */
+/**
+ * Refs that exist on every main (Handle) schema.
+ *
+ * @type {BuiltinRef[]}
+ */
+export const BUILTINS: BuiltinRef[];
+/**
+ * Refs that exist on every local schema.
+ *
+ * @type {BuiltinRef[]}
+ */
+export const LOCAL_BUILTINS: BuiltinRef[];
+/** Collection name for the internal counters table. */
+export const COUNTERS: "counters";
+/**
+ * Builtin type/collection/dispatch/rpc definitions used by the builder.
+ * Every cero schema includes these; user-defined refs are added on top.
+ */
+export type BuiltinRef = {
+    name: string;
+    type: string;
+    verb?: string;
+    kind?: string;
+};
+/**
+ * Builtin type/collection/dispatch/rpc definitions used by the builder.
+ * Every cero schema includes these; user-defined refs are added on top.
+ */
+export type FieldDesc = {
+    name: string;
+    type: string;
+    required: boolean;
+};
+/**
+ * Builtin type/collection/dispatch/rpc definitions used by the builder.
+ * Every cero schema includes these; user-defined refs are added on top.
+ */
+export type TypeDesc = {
+    name: string;
+    compact: boolean;
+    fields: FieldDesc[];
+};
+/**
+ * Builtin type/collection/dispatch/rpc definitions used by the builder.
+ * Every cero schema includes these; user-defined refs are added on top.
+ */
+export type CollectionDesc = {
+    name: string;
+    schema: string;
+    key: string[];
+};
+/**
+ * Builtin type/collection/dispatch/rpc definitions used by the builder.
+ * Every cero schema includes these; user-defined refs are added on top.
+ */
+export type DispatchDesc = {
+    name: string;
+    requestType: string;
+};
+/**
+ * Builtin type/collection/dispatch/rpc definitions used by the builder.
+ * Every cero schema includes these; user-defined refs are added on top.
+ */
+export type CommandDesc = {
+    name: string;
+    request: {
+        name: string;
+    };
+    response: {
+        name: string;
+        stream?: boolean;
+    };
+};

package/types/lib/operators.d.ts

@@ -0,0 +1,29 @@
+export function put(ref: Ref, row: Record<string, any>): Promise<SingleResult>;
+export function set(ref: Ref, row: Record<string, any>): Promise<SingleResult>;
+export function del(ref: Ref, id?: string): Promise<void>;
+export function count(ref: Ref, q?: Record<string, any>): Promise<{
+    data: number;
+}>;
+export function call(ref: Ref, d?: Record<string, any>): Promise<any>;
+export function get(ref: Ref, q?: string | Record<string, any>): Promise<SingleResult | ListResult | GetByIdResult>;
+export function watch(ref: Ref, q?: Record<string, any>): any;
+export function open(ref: Ref, arg?: string | {
+    invite?: string;
+    id?: string;
+    name?: string;
+    routes?: any;
+    role?: string;
+    accept?: boolean;
+} | undefined): Promise<any>;
+export type Ref = import("./utils.js").Ref;
+export type SingleResult = {
+    data: any;
+};
+export type ListResult = {
+    data: any[];
+    total: number;
+    size: number;
+};
+export type GetByIdResult = {
+    data: any | null;
+};

package/types/lib/peek.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Quickly check whether the on-disk directory at `dir` already holds an
+ * initialised cero identity (i.e. a stored master seed). Opens the local
+ * store read-only and closes everything before returning.
+ *
+ * @param {string} dir   Cero data directory.
+ * @param {any} spec     Built spec — same value passed to `cero(dir, spec)`.
+ * @returns {Promise<boolean>}  `true` if a master seed exists on disk.
+ */
+export function peek(dir: string, spec: any): Promise<boolean>;

package/types/lib/spec.d.ts

@@ -0,0 +1 @@
+export { t, schema } from "@cero-base/core/schema";

package/types/lib/utils.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Attach a `Ref` property to `target` for every entry in `refs`. Used by
+ * `Handle` and `Local` during `_open()` so callers can write
+ * `handle.someRef` instead of looking refs up by name.
+ *
+ * @param {any} target
+ * @param {Record<string, RefInfo>} refs
+ */
+export function attachRefs(target: any, refs: Record<string, RefInfo>): void;
+/**
+ * @typedef {'collection' | 'single' | 'action' | 'handle'} RefKind
+ * @typedef {{ kind?: string, schema?: string }} RefInfo
+ *   Shape of the entries in `meta.refs` — describes a single ref name.
+ *   `kind` is one of {@link RefKind}, kept as `string` since it originates
+ *   from a generated spec.
+ */
+/**
+ * Typed pointer to a single ref (table or handle slot) on a `Handle` or
+ * `Local`. Operators (`put`/`get`/`open`/...) take a `Ref` as their first
+ * argument and dispatch through the owning handle's store.
+ */
+export class Ref {
+    /**
+     * @param {any} handle  Owner — a `Handle` (or `Local`) the ref lives on.
+     * @param {string} name  Ref name as declared in the schema.
+     * @param {string} kind  Ref kind: `'collection'`, `'single'`, `'action'`, or `'handle'`.
+     * @param {string | null} [schema]  Fully-qualified schema id, if any.
+     */
+    constructor(handle: any, name: string, kind: string, schema?: string | null);
+    handle: any;
+    name: string;
+    kind: string;
+    schema: string;
+}
+export type RefKind = "collection" | "single" | "action" | "handle";
+/**
+ * Shape of the entries in `meta.refs` — describes a single ref name.
+ * `kind` is one of {@link RefKind}, kept as `string` since it originates
+ * from a generated spec.
+ */
+export type RefInfo = {
+    kind?: string;
+    schema?: string;
+};

package/types/local/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @typedef {object} LocalOpts
+ * @property {any} [root]   Pre-existing HypercoreStorage to reuse.
+ * @property {any} [store]  Pre-existing Corestore to reuse.
+ */
+/**
+ * Per-device, single-writer storage for cero — holds the master seed,
+ * device keypair and any per-handle keypairs. Wraps a hyperbee-backed
+ * `Storage` and exposes each local ref as a property of the instance.
+ */
+export class Local extends ReadyResource {
+    /**
+     * @param {string | null} dir   Directory for the local store, or `null` when reusing an external `store`.
+     * @param {any} spec            Built cero spec — must include `spec.local.database` and `spec.meta.local`.
+     * @param {LocalOpts} [opts]
+     */
+    constructor(dir: string | null, spec: any, { root, store }?: LocalOpts);
+    dir: string;
+    spec: any;
+    store: Storage;
+}
+export type LocalOpts = {
+    /**
+     * Pre-existing HypercoreStorage to reuse.
+     */
+    root?: any;
+    /**
+     * Pre-existing Corestore to reuse.
+     */
+    store?: any;
+};
+import ReadyResource from 'ready-resource';
+import { Storage } from '@cero-base/core/storage';

package/types/rpc/client.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Re-initialize a `Client` from a recovery phrase. Closes the existing
+ * local state and reseeds identity from the phrase.
+ *
+ * @param {Client} me
+ * @param {string} phrase
+ * @returns {Promise<Client>}
+ */
+export function restore(me: Client, phrase: string): Promise<Client>;
+/**
+ * Construct a `Client`, wait for `init` to complete, and return it.
+ *
+ * @param {any} ipc
+ * @param {object} spec
+ * @returns {Promise<Client>}
+ */
+export function connect(ipc: any, spec: object): Promise<Client>;
+/**
+ * IPC-side RPC client for cero. Wraps an `hrpc` channel and exposes the
+ * same handle/ref/row API as a local cero instance, transparently
+ * routing every operation across the wire.
+ */
+export class Client extends RPCClient {
+    /**
+     * @param {any} ipc   Framed IPC stream (must be writable).
+     * @param {Spec} spec  Compiled cero spec (schema + rpc + handles).
+     */
+    constructor(ipc: any, spec: Spec);
+    id: any;
+    deviceId: any;
+    store: this;
+    identity: {
+        id: any;
+        toPhrase: () => any;
+    };
+    /**
+     * Create a new child handle of the given type.
+     *
+     * @param {string} type
+     * @param {Record<string, any>} [opts]
+     * @returns {Promise<Handle>}
+     */
+    _create(type: string, opts?: Record<string, any>): Promise<Handle>;
+    /**
+     * Load an existing child handle by id.
+     *
+     * @param {string} type
+     * @param {string} id
+     * @returns {Promise<Handle>}
+     */
+    _load(type: string, id: string): Promise<Handle>;
+    /**
+     * Join a child handle via invite.
+     *
+     * @param {string} invite
+     * @param {string} type
+     * @returns {Promise<Handle>}
+     */
+    _join(invite: string, type: string): Promise<Handle>;
+}
+export type BaseRPCClient = import("@cero-base/core/rpc").RPCClient;
+export type RefInfo = {
+    kind?: "single" | "collection" | "action" | "handle";
+    schema?: string;
+    type?: string;
+};
+/**
+ * Built cero spec (schema + rpc + per-handle child specs).
+ */
+export type Spec = import("@cero-base/core/rpc").Spec & {
+    meta: {
+        ns?: string;
+        refs: Record<string, RefInfo>;
+        handles?: Record<string, Spec>;
+    };
+    handles: Record<string, Spec>;
+};
+export type SingleResult = {
+    data: any;
+};
+export type ListResult = {
+    data: any[];
+    total: number;
+    size: number;
+};
+export type GetByIdResult = {
+    data: any | null;
+};
+export type ClientIdentity = {
+    id: string;
+    toPhrase: () => string | null;
+};
+export type HandleStub = {
+    id: string;
+    type: string;
+    name: string | null;
+};
+import { RPCClient } from '@cero-base/core/rpc';
+/**
+ * Client-side proxy for a remote handle. Exposes the same row-ops surface
+ * as `Client` but scoped to a single child handle id, and routes every
+ * call through the parent's RPC channel.
+ */
+declare class Handle {
+    /**
+     * @param {Client} parent
+     * @param {string} id
+     * @param {string} type
+     * @param {string|null} name
+     */
+    constructor(parent: Client, id: string, type: string, name: string | null);
+    parent: Client;
+    id: string;
+    type: string;
+    name: string;
+    spec: Spec;
+    store: this;
+    /** Underlying RPC channel borrowed from the parent. */
+    get rpc(): any;
+    /** Tear down the remote handle without leaving the room. */
+    close(): any;
+    /** Tear down the remote handle and drop membership. */
+    leave(): any;
+}
+export { put, set, get, del, count, watch, call, open } from "../lib/operators.js";

package/types/rpc/index.d.ts

@@ -0,0 +1,2 @@
+export { Server, serve } from "./server.js";
+export { Client, connect } from "./client.js";

package/types/rpc/server.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Construct a `Server`, wait for it to be ready, and return it.
+ *
+ * @param {any} ipc
+ * @param {ServerOpts} opts
+ * @returns {Promise<Server>}
+ */
+export function serve(ipc: any, opts: ServerOpts): Promise<Server>;
+/**
+ * @typedef {import('@cero-base/core/rpc').RPCServer} BaseRPCServer
+ *
+ * @typedef {object} ServerOpts
+ * @property {string} storage   Directory passed to `cero()` for the local store.
+ * @property {object} spec      Compiled cero spec (schema + rpc + handles).
+ * @property {string} [name]    Optional display name forwarded to `cero()`.
+ * @property {Array<{ host: string, port: number }>} [bootstrap]  Custom DHT bootstrap.
+ * @property {boolean} [isMobile]
+ * @property {(err: Error) => void} [onerror]
+ *
+ * @typedef {object} Identity
+ * @property {string} id        Long-lived cero identity id.
+ * @property {string} deviceId  Per-device id (empty when no `local` spec).
+ * @property {string|null} phrase  BIP39 recovery phrase for the identity.
+ *
+ * @typedef {{ ref: any, codec: any }} RefAndCodec
+ *
+ * @typedef {{ data: any, total?: number, size?: number }} GetResult  Single-ref get omits `total`/`size`; list/handle refs include them.
+ */
+/**
+ * IPC-side RPC server for cero. Bridges an `hrpc` channel to a live
+ * `Handle` tree: lazy-initializes the root via `cero()` on the first
+ * `init` call, then exposes data ops, pairing, and handle lifecycle
+ * over the wire using the spec-bound codec.
+ */
+export class Server extends RPCServer {
+    /**
+     * @param {any} ipc                Framed IPC stream (must be writable).
+     * @param {Partial<ServerOpts>} [opts]
+     */
+    constructor(ipc: any, { storage, spec, ...opts }?: Partial<ServerOpts>);
+    storage: string;
+    opts: {
+        /**
+         * Optional display name forwarded to `cero()`.
+         */
+        name?: string;
+        /**
+         * Custom DHT bootstrap.
+         */
+        bootstrap?: Array<{
+            host: string;
+            port: number;
+        }>;
+        isMobile?: boolean;
+        onerror?: (err: Error) => void;
+    };
+    me: any;
+    handles: Map<any, any>;
+    /**
+     * Root cero id (null until `init` has run).
+     *
+     * @returns {string|undefined}
+     */
+    get id(): string | undefined;
+    /**
+     * Root identity object (null until `init` has run).
+     *
+     * @returns {any}
+     */
+    get identity(): any;
+    /** Wire the `init` handler that lazily constructs the root cero handle. */
+    _wireInit(): void;
+    /** Wire the `restore` handler that rebuilds the local store from a phrase. */
+    _wireRestore(): void;
+    /** Register the row-level RPC handlers (put/set/get/del/count/watch/call). */
+    _wireData(): void;
+    /** Register invite/revoke/join RPC handlers. */
+    _wirePairing(): void;
+    /** Register add/open/close/leave RPC handlers for child handles. */
+    _wireHandles(): void;
+    /**
+     * Look up a live handle by id, throwing if unknown. Binds the handle's
+     * codec on first use.
+     *
+     * @param {string} id
+     * @returns {any}
+     */
+    _resolve(id: string): any;
+    /**
+     * Resolve a `{ handle, ref }` pair to its `Ref` and the handle's codec.
+     *
+     * @param {string} id
+     * @param {string} name
+     * @returns {RefAndCodec}
+     */
+    _refOf(id: string, name: string): RefAndCodec;
+    /**
+     * Snapshot the current identity for return to the client.
+     *
+     * @returns {Identity}
+     */
+    _identity(): Identity;
+}
+export type BaseRPCServer = import("@cero-base/core/rpc").RPCServer;
+export type ServerOpts = {
+    /**
+     * Directory passed to `cero()` for the local store.
+     */
+    storage: string;
+    /**
+     * Compiled cero spec (schema + rpc + handles).
+     */
+    spec: object;
+    /**
+     * Optional display name forwarded to `cero()`.
+     */
+    name?: string;
+    /**
+     * Custom DHT bootstrap.
+     */
+    bootstrap?: Array<{
+        host: string;
+        port: number;
+    }>;
+    isMobile?: boolean;
+    onerror?: (err: Error) => void;
+};
+export type Identity = {
+    /**
+     * Long-lived cero identity id.
+     */
+    id: string;
+    /**
+     * Per-device id (empty when no `local` spec).
+     */
+    deviceId: string;
+    /**
+     * BIP39 recovery phrase for the identity.
+     */
+    phrase: string | null;
+};
+export type RefAndCodec = {
+    ref: any;
+    codec: any;
+};
+/**
+ * Single-ref get omits `total`/`size`; list/handle refs include them.
+ */
+export type GetResult = {
+    data: any;
+    total?: number;
+    size?: number;
+};
+import { RPCServer } from '@cero-base/core/rpc';