@cero-base/core 0.2.0 → 0.4.1

package/types/database/index.d.ts

@@ -0,0 +1,329 @@
+/**
+ * @typedef {object} DatabaseOpts
+ * @property {any} store                                              Corestore (or compatible) used to materialize the autobee.
+ * @property {import('../identity/index.js').Identity} identity       Long-lived member identity used to sign writer changes.
+ * @property {import('../network/index.js').Network} [network]        Optional swarm; required for multi-writer replication.
+ * @property {{ database: any, dispatch: any, meta?: { ns?: string, refs?: Record<string, { kind?: string, verb?: string }> } }} spec  Generated hyperdb + hyperdispatch spec.
+ * @property {Record<string, Function>} [routes]                      Custom action handlers keyed by route name.
+ * @property {string} [namespace]                                     Corestore namespace; defaults to `cero`.
+ * @property {Uint8Array | null} [encryptionKey]                      Optional encryption key; falls back to identity's key.
+ * @property {(nodes: any, view: any, host: any) => Promise<void>} [apply]  Override the default apply function.
+ * @property {Uint8Array | null} [key]                                Existing autobee key to reopen.
+ * @property {import('../identity/index.js').KeyPair} [keyPair]       Device writer keypair; defaults to identity's keypair.
+ *
+ * @typedef {{ data: any | null }} SingleResult
+ * @typedef {{ data: any[], total: number, size: number }} ListResult
+ * @typedef {{ gt?: string, gte?: string, lt?: string, lte?: string, reverse?: boolean, limit?: number }} Query
+ * @typedef {{ kind: string, verb: string, name: string }} Ref
+ * @typedef {(ctx: any) => any | Promise<any>} HookFn
+ */
+/**
+ * Multi-writer database built on Autobee + HyperDB. Persists rows via a
+ * hyperdispatch-encoded log and exposes a `put/get/...` surface mirroring
+ * `Storage`, plus membership ops (claim/addWriter/removeWriter) for the
+ * shared writer set.
+ */
+export class Database extends ReadyResource {
+    /** @param {Partial<DatabaseOpts>} [opts] */
+    constructor(opts?: Partial<DatabaseOpts>);
+    store: any;
+    identity: import("../index.js").Identity;
+    network: import("../index.js").Network;
+    spec: {
+        database: any;
+        dispatch: any;
+        meta?: {
+            ns?: string;
+            refs?: Record<string, {
+                kind?: string;
+                verb?: string;
+            }>;
+        };
+    };
+    meta: {
+        ns?: string;
+        refs?: Record<string, {
+            kind?: string;
+            verb?: string;
+        }>;
+    };
+    ns: string;
+    refs: Record<string, {
+        kind?: string;
+        verb?: string;
+    }>;
+    routes: Record<string, Function>;
+    namespace: string;
+    encryptionKey: Uint8Array<ArrayBufferLike>;
+    applyOverride: (nodes: any, view: any, host: any) => Promise<void>;
+    key: Uint8Array<ArrayBufferLike>;
+    keyPair: import("../identity/index.js").KeyPair | {
+        publicKey: Uint8Array<ArrayBufferLike>;
+        secretKey: Uint8Array<ArrayBufferLike>;
+    };
+    bee: any;
+    dispatcher: {
+        dispatcher: any;
+        apply(nodes: any, view: any, host: any): Promise<void>;
+    };
+    beforeHooks: Map<any, any>;
+    afterHooks: Map<any, any>;
+    updaters: Set<any>;
+    txQueue: any[];
+    _discovery: import("../network/discovery.js").Discovery;
+    /** Open the underlying autobee, wire dispatcher + apply, attach to network. */
+    openBee(): Promise<void>;
+    get discoveryKey(): any;
+    get writerKey(): any;
+    get writable(): boolean;
+    get length(): any;
+    get view(): any;
+    /**
+     * Register a pre-op hook. Returning `false` from `fn` aborts the op.
+     *
+     * @param {string} op
+     * @param {HookFn} fn
+     * @returns {() => void} disposer
+     */
+    before(op: string, fn: HookFn): () => void;
+    /**
+     * Register a post-op hook, fired after the write succeeds.
+     *
+     * @param {string} op
+     * @param {HookFn} fn
+     * @returns {() => void} disposer
+     */
+    after(op: string, fn: HookFn): () => void;
+    /**
+     * Subscribe to local apply notifications. Fires whenever the view updates.
+     *
+     * @param {() => void} fn
+     * @returns {() => void} disposer
+     */
+    onUpdate(fn: () => void): () => void;
+    /**
+     * Run all registered `before:op` hooks and emit the corresponding event.
+     *
+     * @param {string} op
+     * @param {any} ctx
+     * @returns {Promise<boolean>} `false` if any hook vetoed the op
+     */
+    runBefore(op: string, ctx: any): Promise<boolean>;
+    /**
+     * Run all registered `after:op` hooks and emit the corresponding event.
+     *
+     * @param {string} op
+     * @param {any} ctx
+     * @returns {Promise<void>}
+     */
+    runAfter(op: string, ctx: any): Promise<void>;
+    /**
+     * Insert (or overwrite by id) a row, stamping `id`/`createdAt`/`updatedAt`.
+     *
+     * @param {string} name
+     * @param {Record<string, any>} row
+     * @returns {Promise<SingleResult | null>}
+     */
+    put(name: string, row: Record<string, any>): Promise<SingleResult | null>;
+    /**
+     * Upsert by merging with the existing row, preserving `createdAt`.
+     *
+     * @param {string} name
+     * @param {Record<string, any>} row
+     * @returns {Promise<SingleResult | null>}
+     */
+    set(name: string, row: Record<string, any>): Promise<SingleResult | null>;
+    /**
+     * Delete by id (collection) or wipe the whole single-row table.
+     *
+     * @param {string} name
+     * @param {string} [id]
+     * @returns {Promise<void | null>}
+     */
+    del(name: string, id?: string): Promise<void | null>;
+    /**
+     * Dispatch a custom action route by name.
+     *
+     * @param {string} op
+     * @param {Record<string, any>} [data]
+     * @returns {Promise<void>}
+     */
+    call(op: string, data?: Record<string, any>): Promise<void>;
+    /**
+     * Batch every write performed inside `fn` into a single autobee append.
+     * Nested calls reuse the outer queue.
+     *
+     * @template T
+     * @param {() => Promise<T> | T} fn
+     * @returns {Promise<T>}
+     */
+    tx<T>(fn: () => Promise<T> | T): Promise<T>;
+    /**
+     * Encode and append dispatch ops. Buffers into the active `tx` queue if one
+     * is open.
+     *
+     * @param {Array<[string, any]>} ops
+     * @returns {Promise<void>}
+     */
+    write(ops: Array<[string, any]>): Promise<void>;
+    /**
+     * Read a row. With no `query`: list all (collection) or fetch the one
+     * record (single). With a string id: fetch that specific row.
+     *
+     * @param {string} name
+     * @param {string | Query} [query]
+     * @returns {Promise<SingleResult | ListResult>}
+     */
+    get(name: string, query?: string | Query): Promise<SingleResult | ListResult>;
+    /**
+     * Number of rows that match `query` (or total if omitted).
+     *
+     * @param {string} name
+     * @param {Query} [query]
+     * @returns {Promise<{ data: number }>}
+     */
+    count(name: string, query?: Query): Promise<{
+        data: number;
+    }>;
+    /**
+     * Live snapshot stream — re-emits the latest `get()` result on every
+     * underlying mutation. Destroy the stream to stop watching.
+     *
+     * @param {string} name
+     * @param {Query} [query]
+     * @returns {import('streamx').Readable}
+     */
+    watch(name: string, query?: Query): any;
+    /**
+     * First-run bootstrap: create the device writer, save it, and swap into it.
+     *
+     * @param {{ name?: string | null, isMobile?: boolean, recovering?: boolean }} [opts]
+     * @returns {Promise<{ id: Uint8Array, writer: import('../identity/index.js').KeyPair }>}
+     */
+    bootstrap(opts?: {
+        name?: string | null;
+        isMobile?: boolean;
+        recovering?: boolean;
+    }): Promise<{
+        id: Uint8Array;
+        writer: import("../identity/index.js").KeyPair;
+    }>;
+    /**
+     * Claim writership on an existing room by signing our writer key with the
+     * member identity and appending optimistically.
+     *
+     * @param {{ name?: string | null, isMobile?: boolean }} [opts]
+     * @returns {Promise<void>}
+     */
+    claim({ name, isMobile }?: {
+        name?: string | null;
+        isMobile?: boolean;
+    }): Promise<void>;
+    /**
+     * Resolve once the bee becomes writable, or reject after `timeout` ms.
+     *
+     * @param {{ timeout?: number }} [opts]
+     * @returns {Promise<void>}
+     */
+    whenWritable({ timeout }?: {
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Add a peer's writer key to the indexer set.
+     *
+     * @param {Uint8Array} publicKey
+     * @returns {Promise<void>}
+     */
+    addWriter(publicKey: Uint8Array): Promise<void>;
+    /**
+     * Remove a peer's writer key from the indexer set.
+     *
+     * @param {Uint8Array} publicKey
+     * @returns {Promise<void>}
+     */
+    removeWriter(publicKey: Uint8Array): Promise<void>;
+    guard(): void;
+    ref(name: any): {
+        name: string;
+        kind: string;
+        verb: string;
+    };
+    col(ref: any): string;
+    _addHook(map: any, op: any, fn: any): () => void;
+    _write(verb: any, hook: any, publicKey: any): Promise<void>;
+}
+export type DatabaseOpts = {
+    /**
+     * Corestore (or compatible) used to materialize the autobee.
+     */
+    store: any;
+    /**
+     * Long-lived member identity used to sign writer changes.
+     */
+    identity: import("../identity/index.js").Identity;
+    /**
+     * Optional swarm; required for multi-writer replication.
+     */
+    network?: import("../network/index.js").Network;
+    /**
+     * Generated hyperdb + hyperdispatch spec.
+     */
+    spec: {
+        database: any;
+        dispatch: any;
+        meta?: {
+            ns?: string;
+            refs?: Record<string, {
+                kind?: string;
+                verb?: string;
+            }>;
+        };
+    };
+    /**
+     * Custom action handlers keyed by route name.
+     */
+    routes?: Record<string, Function>;
+    /**
+     * Corestore namespace; defaults to `cero`.
+     */
+    namespace?: string;
+    /**
+     * Optional encryption key; falls back to identity's key.
+     */
+    encryptionKey?: Uint8Array | null;
+    /**
+     * Override the default apply function.
+     */
+    apply?: (nodes: any, view: any, host: any) => Promise<void>;
+    /**
+     * Existing autobee key to reopen.
+     */
+    key?: Uint8Array | null;
+    /**
+     * Device writer keypair; defaults to identity's keypair.
+     */
+    keyPair?: import("../identity/index.js").KeyPair;
+};
+export type SingleResult = {
+    data: any | null;
+};
+export type ListResult = {
+    data: any[];
+    total: number;
+    size: number;
+};
+export type Query = {
+    gt?: string;
+    gte?: string;
+    lt?: string;
+    lte?: string;
+    reverse?: boolean;
+    limit?: number;
+};
+export type Ref = {
+    kind: string;
+    verb: string;
+    name: string;
+};
+export type HookFn = (ctx: any) => any | Promise<any>;
+import ReadyResource from 'ready-resource';

package/types/identity/index.d.ts

@@ -0,0 +1,160 @@
+/**
+ * @typedef {{ publicKey: Uint8Array, secretKey: Uint8Array, id: string }} KeyPair
+ * @typedef {{ publicKey: Uint8Array, secretKey: Uint8Array, encryptionKey: Uint8Array, seed: Uint8Array }} IdentityFields
+ */
+/**
+ * Long-lived user identity derived from a BIP-39 seed phrase. Holds the
+ * sign keypair, a symmetric encryption key and the canonical id/topic used
+ * by every other resource to identify this user.
+ */
+export class Identity {
+    /**
+     * Build an identity from 16- or 32-byte entropy.
+     *
+     * @param {Uint8Array} seed
+     * @returns {Promise<Identity>}
+     */
+    static fromSeed(seed: Uint8Array): Promise<Identity>;
+    /**
+     * Build an identity from a BIP-39 mnemonic.
+     *
+     * @param {string} phrase
+     * @returns {Promise<Identity>}
+     */
+    static fromPhrase(phrase: string): Promise<Identity>;
+    /**
+     * Generate a fresh identity from CSPRNG entropy.
+     *
+     * @param {{ words?: 12 | 24 }} [opts]
+     * @returns {Promise<Identity>}
+     */
+    static generate({ words }?: {
+        words?: 12 | 24;
+    }): Promise<Identity>;
+    /**
+     * Generate a random BIP-39 mnemonic.
+     *
+     * @param {12 | 24} [words]
+     * @returns {string}
+     */
+    static genPhrase(words?: 12 | 24): string;
+    /**
+     * Phrase → seed entropy.
+     *
+     * @param {string} phrase
+     * @returns {Uint8Array}
+     */
+    static toSeed(phrase: string): Uint8Array;
+    /**
+     * Seed entropy → phrase.
+     *
+     * @param {Uint8Array} seed
+     * @returns {string}
+     */
+    static toPhrase(seed: Uint8Array): string;
+    /**
+     * Validate that a value is a 16- or 32-byte buffer.
+     *
+     * @param {any} x
+     * @returns {x is Uint8Array}
+     */
+    static isSeed(x: any): x is Uint8Array;
+    /**
+     * Validate that a string is a BIP-39 mnemonic.
+     *
+     * @param {unknown} x
+     * @returns {x is string}
+     */
+    static isPhrase(x: unknown): x is string;
+    /**
+     * Verify a signature against an arbitrary public key.
+     *
+     * @param {Uint8Array} publicKey
+     * @param {Uint8Array} message
+     * @param {Uint8Array} signature
+     * @returns {boolean}
+     */
+    static verify(publicKey: Uint8Array, message: Uint8Array, signature: Uint8Array): boolean;
+    /**
+     * Generate a fresh Ed25519 keypair (for devices, blind invites, etc.).
+     *
+     * @returns {KeyPair}
+     */
+    static randomKeyPair(): KeyPair;
+    /**
+     * N bytes from a CSPRNG.
+     *
+     * @param {number} [n]
+     * @returns {Uint8Array}
+     */
+    static randomBytes(n?: number): Uint8Array;
+    /**
+     * Fresh seed entropy sized for the chosen mnemonic length.
+     *
+     * @param {12 | 24} [words]
+     * @returns {Uint8Array}
+     */
+    static randomSeed(words?: 12 | 24): Uint8Array;
+    /** @param {IdentityFields} keys */
+    constructor(keys: IdentityFields);
+    /**
+     * Canonical z32-encoded public key.
+     *
+     * @type {string}
+     */
+    id: string;
+    /** @type {Uint8Array} */
+    publicKey: Uint8Array;
+    /** @type {Uint8Array} */
+    secretKey: Uint8Array;
+    /**
+     * Symmetric key for encrypting per-identity payloads.
+     *
+     * @type {Uint8Array}
+     */
+    encryptionKey: Uint8Array;
+    /**
+     * Hash of the public key — used as the swarm topic.
+     *
+     * @type {Uint8Array}
+     */
+    topic: Uint8Array;
+    /**
+     * Original 16- or 32-byte entropy.
+     *
+     * @type {Uint8Array}
+     */
+    seed: Uint8Array;
+    /**
+     * Detached Ed25519 signature over `message`.
+     *
+     * @param {Uint8Array} message
+     * @returns {Uint8Array}
+     */
+    sign(message: Uint8Array): Uint8Array;
+    /**
+     * Verify a signature against this identity's public key.
+     *
+     * @param {Uint8Array} message
+     * @param {Uint8Array} signature
+     * @returns {boolean}
+     */
+    verify(message: Uint8Array, signature: Uint8Array): boolean;
+    /**
+     * Render the underlying seed as a BIP-39 mnemonic phrase.
+     *
+     * @returns {string}
+     */
+    toPhrase(): string;
+}
+export type KeyPair = {
+    publicKey: Uint8Array;
+    secretKey: Uint8Array;
+    id: string;
+};
+export type IdentityFields = {
+    publicKey: Uint8Array;
+    secretKey: Uint8Array;
+    encryptionKey: Uint8Array;
+    seed: Uint8Array;
+};

package/types/index.d.ts

@@ -0,0 +1,11 @@
+export { Identity } from "./identity/index.js";
+export { Storage } from "./storage/index.js";
+export { Network } from "./network/index.js";
+export { Database } from "./database/index.js";
+export { Blobs } from "./blobs/index.js";
+export { Pairing } from "./pairing/index.js";
+export { Invite } from "./pairing/invite.js";
+export { CeroError } from "./lib/errors.js";
+export { RPCServer, RPCClient, bindCodec } from "./rpc/index.js";
+export { t, schema } from "./lib/schema.js";
+export { genId, toId, toKey, isKeyId, subscribe } from "./lib/utils.js";

package/types/lib/constants.d.ts

@@ -0,0 +1,13 @@
+export const SINGLE: "single";
+export const COLLECTION: "collection";
+export const HANDLE: "handle";
+export const ACTION: "action";
+export const ACTIVE: "active";
+export const PASSIVE: "passive";
+export const ROCKS: "rocks";
+export const BEE: "bee";
+export const OWNER: "owner";
+export const WRITE: "write";
+export const READ: "read";
+export const NAMESPACE: "cero";
+export const COUNTERS: "counters";

package/types/lib/errors.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Canonical error class. Every instance carries a stable `code` field which
+ * is also prefixed to the message, so logs stay self-identifying. Static
+ * factories produce errors with the right code + a sensible message.
+ */
+export class CeroError extends Error {
+    /**
+     * Type-guard for `err instanceof CeroError` that survives realm boundaries.
+     *
+     * @param {any} err
+     * @returns {err is CeroError}
+     */
+    static isCeroError(err: any): err is CeroError;
+    /**
+     * Missing required argument.
+     *
+     * @param {string} name
+     */
+    static REQUIRED(name: string): CeroError;
+    /**
+     * Argument failed validation.
+     *
+     * @param {string} msg
+     */
+    static INVALID(msg: string): CeroError;
+    /**
+     * Operation on a closed resource.
+     *
+     * @param {string} resource
+     */
+    static CLOSED(resource: string): CeroError;
+    /**
+     * Operation before `ready()` resolved.
+     *
+     * @param {string} resource
+     * @param {string} name
+     */
+    static NOT_READY(resource: string, name: string): CeroError;
+    /**
+     * Resource has been destroyed.
+     *
+     * @param {string} resource
+     */
+    static DESTROYED(resource: string): CeroError;
+    /**
+     * Lookup failed for a typed id.
+     *
+     * @param {string} kind
+     * @param {string} id
+     */
+    static UNKNOWN(kind: string, id: string): CeroError;
+    /**
+     * Write attempted on a read-only handle.
+     *
+     * @param {string} resource
+     */
+    static NOT_WRITABLE(resource: string): CeroError;
+    /**
+     * Async operation exceeded its deadline.
+     *
+     * @param {string} what
+     */
+    static TIMED_OUT(what: string): CeroError;
+    /**
+     * Feature is not yet implemented.
+     *
+     * @param {string} what
+     */
+    static UNSUPPORTED(what: string): CeroError;
+    /**
+     * Invite payload failed to parse or verify.
+     *
+     * @param {string} [msg]
+     */
+    static INVALID_INVITE(msg?: string): CeroError;
+    /**
+     * Invite is past its TTL.
+     *
+     * @param {string} [msg]
+     */
+    static EXPIRED(msg?: string): CeroError;
+    /**
+     * Host refused the join — `reason` is exposed on the instance.
+     *
+     * @param {string | null} [reason]
+     * @param {string} [msg]
+     */
+    static DENIED(reason?: string | null, msg?: string): CeroError;
+    /**
+     * Pairing handshake did not complete in time.
+     *
+     * @param {string} [msg]
+     */
+    static TIMEOUT(msg?: string): CeroError;
+    /**
+     * Underlying swarm/transport failure.
+     *
+     * @param {string} [msg]
+     */
+    static NETWORK_ERROR(msg?: string): CeroError;
+    /**
+     * @param {string} code            Stable identifier (e.g. `REQUIRED`, `EXPIRED`).
+     * @param {string} [message]       Human-readable detail; appended after the code.
+     * @param {Record<string, unknown> | null} [extras]  Extra fields copied onto the instance.
+     */
+    constructor(code: string, message?: string, extras?: Record<string, unknown> | null);
+    isCeroError: boolean;
+    code: string;
+    get name(): string;
+}

package/types/lib/schema.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Wrap a definitions object so the builder can recognise it as a schema.
+ *
+ * @param {SchemaDefs} defs
+ * @returns {Schema}
+ */
+export function schema(defs: SchemaDefs): Schema;
+export namespace t {
+    let string: Prim;
+    let uint: Prim;
+    let int: Prim;
+    let bool: Prim;
+    let bytes: Prim;
+    let json: Prim;
+    let fixed32: Prim;
+    let fixed64: Prim;
+    /**
+     * Single-row table (one record, set/get by name).
+     *
+     * @param {Record<string, Prim>} fields
+     * @returns {TypeDef}
+     */
+    function single(fields: Record<string, Prim>): TypeDef;
+    /**
+     * Multi-row table keyed by `id`.
+     *
+     * @param {Record<string, Prim>} fields
+     * @returns {TypeDef}
+     */
+    function collection(fields: Record<string, Prim>): TypeDef;
+    /**
+     * RPC-style mutation that doesn't persist a row.
+     *
+     * @param {Record<string, Prim>} fields
+     * @returns {TypeDef}
+     */
+    function action(fields: Record<string, Prim>): TypeDef;
+}
+export type Prim = {
+    prim: string;
+};
+export type TypeDef = {
+    kind: "single" | "collection" | "action";
+    fields: Record<string, Prim>;
+};
+export type SchemaDefs = {
+    [name: string]: TypeDef | Record<string, TypeDef>;
+} & {
+    local?: Record<string, TypeDef>;
+};
+export type Schema = {
+    defs: SchemaDefs;
+};