@cero-base/core 0.2.0 → 0.4.1

package/types/rpc/index.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @typedef {object} Spec
+ * @property {{ encode: (type: string, value: any) => Uint8Array, decode: (type: string, buf: Uint8Array) => any, getEncoding?: (name: string) => any }} schema   hyperschema-shaped module.
+ * @property {{ ns?: string }} [meta]                                                                                                                              Optional metadata; `ns` controls envelope type fqns.
+ * @property {any} [rpc]                                                                                                                                          hrpc constructor used by RPCServer/RPCClient.
+ * @property {Codec} [codec]                                                                                                                                      Filled in by `bindCodec`.
+ *
+ * @typedef {object} Codec
+ * @property {(type: string, row: any) => Uint8Array} encodeRow
+ * @property {(type: string, buf: Uint8Array) => any} decodeRow
+ * @property {(type: string, rows: any[]) => Uint8Array} encodeRows
+ * @property {(type: string, buf: Uint8Array) => any[]} decodeRows
+ * @property {(q: any) => Uint8Array} encodeQuery
+ * @property {(buf: Uint8Array) => any} decodeQuery
+ * @property {(row: any) => Uint8Array} encodeCreate
+ * @property {(buf: Uint8Array) => any} decodeCreate
+ * @property {(handle: any, op: string, data: any) => Uint8Array} encodeAction
+ * @property {(handle: any, op: string, buf: Uint8Array) => any} decodeAction
+ */
+/**
+ * Attach a `codec` namespace to a hyperschema-shaped `spec`. Looks up
+ * envelope types using the spec's namespace (`@<ns>/rows` etc.) and falls
+ * back to the bundled `@cero/*` envelopes when the spec has not declared
+ * its own. Returns the spec for chaining.
+ *
+ * @param {Spec} spec
+ * @returns {Spec}
+ */
+export function bindCodec(spec: Spec): Spec;
+export { RPCServer } from "./server.js";
+export { RPCClient } from "./client.js";
+export type Spec = {
+    /**
+     * hyperschema-shaped module.
+     */
+    schema: {
+        encode: (type: string, value: any) => Uint8Array;
+        decode: (type: string, buf: Uint8Array) => any;
+        getEncoding?: (name: string) => any;
+    };
+    /**
+     * Optional metadata; `ns` controls envelope type fqns.
+     */
+    meta?: {
+        ns?: string;
+    };
+    /**
+     * hrpc constructor used by RPCServer/RPCClient.
+     */
+    rpc?: any;
+    /**
+     * Filled in by `bindCodec`.
+     */
+    codec?: Codec;
+};
+export type Codec = {
+    encodeRow: (type: string, row: any) => Uint8Array;
+    decodeRow: (type: string, buf: Uint8Array) => any;
+    encodeRows: (type: string, rows: any[]) => Uint8Array;
+    decodeRows: (type: string, buf: Uint8Array) => any[];
+    encodeQuery: (q: any) => Uint8Array;
+    decodeQuery: (buf: Uint8Array) => any;
+    encodeCreate: (row: any) => Uint8Array;
+    decodeCreate: (buf: Uint8Array) => any;
+    encodeAction: (handle: any, op: string, data: any) => Uint8Array;
+    decodeAction: (handle: any, op: string, buf: Uint8Array) => any;
+};

package/types/rpc/server.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Server-side RPC adapter. Wraps an IPC duplex in a length-framed stream
+ * and instantiates the spec's hrpc binding once `bindCodec` has populated
+ * envelope encoders. Reads are paused until `_open` runs so the
+ * application has a chance to register handlers before frames flow.
+ */
+export class RPCServer extends ReadyResource {
+    /**
+     * @param {any} ipc                                Duplex IPC stream (e.g. a socket or pipe).
+     * @param {import('./index.js').Spec} spec         Spec object exposing `rpc` and `schema`.
+     */
+    constructor(ipc: any, spec: import("./index.js").Spec);
+    ipc: any;
+    spec: import("./index.js").Spec;
+    framed: any;
+    rpc: any;
+}
+import ReadyResource from 'ready-resource';

package/types/storage/index.d.ts

@@ -0,0 +1,163 @@
+/**
+ * @typedef {object} StorageOpts
+ * @property {{ database: any, meta?: { ns?: string, refs?: Record<string, { kind?: string }> } }} spec
+ * @property {'rocks' | 'bee'} backend
+ * @property {any} [root]   Pre-existing HypercoreStorage to reuse.
+ * @property {any} [store]  Pre-existing Corestore to reuse.
+ *
+ * @typedef {{ name: string, kind: string }} Ref
+ * @typedef {{ id?: string, createdAt: number, updatedAt: number, [k: string]: any }} StoredRow
+ * @typedef {{ data: any }} SingleResult
+ * @typedef {{ data: any[], total: number, size: number }} ListResult
+ * @typedef {{ data: any | null }} GetByIdResult
+ */
+/**
+ * Local, single-writer storage. Backed by either RocksDB (`rocks`) or a
+ * Hyperbee on top of corestore (`bee`). Exposes the same `put/get/...`
+ * surface as `Database` but without networking or multi-writer apply.
+ */
+export class Storage extends ReadyResource {
+    /**
+     * Construct a RocksDB-backed Storage.
+     *
+     * @param {string} dir
+     * @param {Omit<StorageOpts, 'backend'>} opts
+     */
+    static rocks(dir: string, opts: Omit<StorageOpts, "backend">): Storage;
+    /**
+     * Construct a Hyperbee-backed Storage.
+     *
+     * @param {string} dir
+     * @param {Omit<StorageOpts, 'backend'>} opts
+     */
+    static bee(dir: string, opts: Omit<StorageOpts, "backend">): Storage;
+    /**
+     * @param {string} dir
+     * @param {StorageOpts} [opts]
+     */
+    constructor(dir: string, { spec, backend, root, store }?: StorageOpts);
+    dir: string;
+    spec: {
+        database: any;
+        meta?: {
+            ns?: string;
+            refs?: Record<string, {
+                kind?: string;
+            }>;
+        };
+    };
+    backend: "rocks" | "bee";
+    ns: string;
+    refs: Record<string, {
+        kind?: string;
+    }>;
+    _cf: string;
+    _ownsRoot: boolean;
+    _ownsStore: boolean;
+    root: any;
+    store: any;
+    db: any;
+    /**
+     * Insert (or overwrite by id) a row, stamping `id`/`createdAt`/`updatedAt`.
+     *
+     * @param {string} name
+     * @param {Record<string, any>} row
+     * @returns {Promise<SingleResult>}
+     */
+    put(name: string, row: Record<string, any>): Promise<SingleResult>;
+    /**
+     * Upsert by merging with the existing row, preserving `createdAt`.
+     *
+     * @param {string} name
+     * @param {Record<string, any>} row
+     * @returns {Promise<SingleResult>}
+     */
+    set(name: string, row: Record<string, any>): Promise<SingleResult>;
+    /**
+     * Delete by id (collection) or wipe the whole single-row table.
+     *
+     * @param {string} name
+     * @param {string} [id]
+     * @returns {Promise<void>}
+     */
+    del(name: string, id?: string): 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 | Record<string, any>} [query]
+     * @returns {Promise<SingleResult | ListResult | GetByIdResult>}
+     */
+    get(name: string, query?: string | Record<string, any>): Promise<SingleResult | ListResult | GetByIdResult>;
+    /**
+     * Number of rows that match `query` (or total if omitted).
+     *
+     * @param {string} name
+     * @param {Record<string, any>} [query]
+     * @returns {Promise<{ data: number }>}
+     */
+    count(name: string, query?: Record<string, any>): 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 {Record<string, any>} [query]
+     * @returns {import('streamx').Readable}
+     */
+    watch(name: string, query?: Record<string, any>): any;
+    _guard(): void;
+    /** @param {string} name @returns {Ref} */
+    _ref(name: string): Ref;
+    /** @param {Ref} ref @returns {string} */
+    _col(ref: Ref): string;
+    /** @param {Ref} ref @param {string} [id] @returns {Promise<any | null>} */
+    _read(ref: Ref, id?: string): Promise<any | null>;
+    /** @param {Ref} ref @param {Record<string, any>} row @returns {Promise<void>} */
+    _write(ref: Ref, row: Record<string, any>): Promise<void>;
+}
+export type StorageOpts = {
+    spec: {
+        database: any;
+        meta?: {
+            ns?: string;
+            refs?: Record<string, {
+                kind?: string;
+            }>;
+        };
+    };
+    backend: "rocks" | "bee";
+    /**
+     * Pre-existing HypercoreStorage to reuse.
+     */
+    root?: any;
+    /**
+     * Pre-existing Corestore to reuse.
+     */
+    store?: any;
+};
+export type Ref = {
+    name: string;
+    kind: string;
+};
+export type StoredRow = {
+    id?: string;
+    createdAt: number;
+    updatedAt: number;
+    [k: string]: any;
+};
+export type SingleResult = {
+    data: any;
+};
+export type ListResult = {
+    data: any[];
+    total: number;
+    size: number;
+};
+export type GetByIdResult = {
+    data: any | null;
+};
+import ReadyResource from 'ready-resource';

package/src/lib/base.js

@@ -1,84 +0,0 @@
-import { Cero } from '@lekinox/cero'
-import { SCOPE_PRIVATE, SCOPE_SHARED } from '../lib/constants.js'
-import { Collection } from '../lib/collection.js'
-import { Batch } from '../lib/batch.js'
-
-const SEED_WORD_COUNT = 12
-
-export class CeroBase extends Cero {
-  constructor(dir, schema, spec, opts = {}) {
-    super(
-      dir,
-      {
-        ...spec,
-        identity: {
-          ...spec.identity,
-          routes: schema.routes(SCOPE_PRIVATE),
-          counters: schema.counterNames(SCOPE_PRIVATE)
-        },
-        room: {
-          ...spec.room,
-          ns: schema.namespace || undefined,
-          routes: schema.routes(SCOPE_SHARED),
-          counters: schema.counterNames(SCOPE_SHARED)
-        }
-      },
-      opts
-    )
-
-    this.schema = schema
-    this._baseUpdateHandler = null
-
-    // Expose cero's local-scope tables (rooms cache, files, settings, …) and
-    // user-declared `scope: 'local'` collections via the unified Collection API.
-    // db.local already has cero's find/insert/delete; we just add .collection.
-    if (this.local) {
-      this.local.collection = (name) => new Collection(this, name, { local: true })
-    }
-
-    this.once('ready', () => {
-      this._bindIdentityBase()
-    })
-  }
-
-  _bindIdentityBase() {
-    if (this._baseUpdateHandler && this._prevBase) {
-      this._prevBase.removeListener('update', this._baseUpdateHandler)
-    }
-    this._baseUpdateHandler = () => this.emit('update')
-    this._prevBase = this.identity?.base
-    if (this._prevBase) this._prevBase.on('update', this._baseUpdateHandler)
-  }
-
-  async _swapIdentity(handler, opts) {
-    const result = await super._swapIdentity(handler, opts)
-    this._bindIdentityBase()
-    return result
-  }
-
-  seed() {
-    return this.identity?.seed?.get() || null
-  }
-
-  async join(input, opts = {}) {
-    const isSeed = typeof input === 'string' && input.trim().split(/\s+/).length >= SEED_WORD_COUNT
-    if (isSeed) return this.recover(input, opts)
-    return this.pair(input, opts)
-  }
-
-  /** Create a device-pairing invite string for this identity. */
-  async invite(opts = {}) {
-    if (!this.opened) await this.ready()
-    const { invite } = await this.invites.create(opts)
-    return invite
-  }
-
-  collection(name) {
-    this.schema.require(name, 'db')
-    return new Collection(this, name)
-  }
-
-  batch() {
-    return new Batch(this)
-  }
-}

package/src/lib/batch.js

@@ -1,98 +0,0 @@
-import { randomId } from './crypto.js'
-import { isLocal, isPrivate, isShared } from './utils.js'
-
-/**
- * Batch — buffer multiple put/del operations and flush as single dispatch
- *
- * @example
- * const batch = db.batch()
- * batch.put('settings', { key: 'a', value: '1' })
- * await batch.flush()
- */
-export class Batch {
-  constructor(owner) {
-    this.owner = owner
-    this.schema = owner.schema
-    this.operations = []
-  }
-
-  put(name, doc) {
-    const scope = this._validate(name)
-
-    const data = doc.id ? doc : { ...doc, id: randomId() }
-    if (this.schema.hasTimestamps(name)) {
-      data.createdAt = data.createdAt ?? Date.now()
-    }
-
-    // If cero doesn't have add-${type}, fall back to set-${type} which is
-    // itself an upsert.
-    const action = this.schema.hasAdd(name) ? 'add' : 'set'
-    this.operations.push({ action, name, data, scope })
-    return data
-  }
-
-  async del(name, query) {
-    const scope = this._validate(name)
-
-    const col = this.owner.collection(name)
-    const [existing] = await col.get(query)
-    if (!existing) return false
-
-    const keys = this.schema.keysOf(name)
-    const keyData = keys.reduce((acc, k) => ((acc[k] = existing[k]), acc), {})
-
-    this.operations.push({ action: 'del', name, data: keyData, scope })
-    return true
-  }
-
-  async flush() {
-    if (this.operations.length === 0) return
-
-    const localOps = this.operations.filter((op) => isLocal(op.scope))
-    const privateOps = this.operations.filter((op) => isPrivate(op.scope))
-    const sharedOps = this.operations.filter((op) => isShared(op.scope))
-
-    for (const op of localOps) {
-      const path = this.schema.getPath(op.name)
-      if (op.action === 'del') {
-        await this.owner.local.delete(path, op.data)
-      } else {
-        await this.owner.local.insert(path, op.data)
-      }
-    }
-
-    if (privateOps.length > 0) {
-      const identity = this.owner.identity
-      const ns = identity.ns
-      await identity.dispatch(`@${ns}/batch`, {
-        operations: privateOps.map((op) => {
-          const route = `@${ns}/${op.action}-${this.schema.types.get(op.name)}`
-          return identity.spec.dispatch.encode(route, op.data)
-        })
-      })
-    }
-
-    if (sharedOps.length > 0) {
-      const room = this.owner.room
-      const ns = room.ns
-      await room.dispatch(`@${ns}/batch`, {
-        operations: sharedOps.map((op) => {
-          const route = `@${ns}/${op.action}-${this.schema.types.get(op.name)}`
-          return room.spec.dispatch.encode(route, op.data)
-        })
-      })
-    }
-
-    this.operations = []
-
-    if (localOps.length > 0) {
-      this.owner.emit('update')
-    }
-  }
-
-  _validate(name) {
-    const scope = this.schema.getScope(name)
-    if (!scope) throw new Error(`Unknown collection: '${name}'`)
-    return scope
-  }
-}

package/src/lib/builder.js

@@ -1,24 +0,0 @@
-import { build as ceroBuild } from '@lekinox/cero'
-
-/**
- * Build all specs in one output directory.
- *
- * @param {string} dir - Output directory
- * @param {object} [schema] - Schema from t.schema()
- * @param {object} [opts] - Options
- * @param {function} [opts.rpc] - RPC builder function ({ register, ns }) => void
- */
-export async function build(dir, schema, opts = {}) {
-  const ns = schema?.namespace || null
-  const builders = {
-    local: ({ register, ns }) => schema?.build('local', register, ns),
-    identity: ({ register, ns }) => schema?.build('private', register, ns),
-    room: ({ register, ns }) => schema?.build('shared', register, ns),
-    ...(opts.rpc ? { rpc: opts.rpc } : {})
-  }
-  if (ns) {
-    await ceroBuild(dir, ns, builders)
-  } else {
-    await ceroBuild(dir, builders)
-  }
-}