@cero-base/core 0.0.5 → 0.4.0

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,98 +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
-    this.once('ready', () => {
-      this._bindIdentityBase()
-      this._initFacades()
-    })
-  }
-
-  _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)
-  }
-
-  _initFacades() {
-    const p = this.identity?.profile
-    if (p) {
-      this._profile = {
-        get: () => p.get(),
-        set: (data) => p.set(data),
-        sub: () => p.subscribe()
-      }
-    }
-
-    const d = this.identity?.devices
-    if (d) {
-      this._devices = {
-        get: (query) => d.list(query),
-        sub: (id) => d.subscribe(id),
-        invite: () => this.invites.create().then(({ invite }) => invite)
-      }
-    }
-  }
-
-  get profile() {
-    return this._profile || null
-  }
-
-  get devices() {
-    return this._devices || null
-  }
-
-  collection(name) {
-    this.schema.require(name, 'db')
-    return new Collection(this, name)
-  }
-
-  batch() {
-    return new Batch(this)
-  }
-}

package/src/lib/batch.js

@@ -1,95 +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()
-    }
-
-    this.operations.push({ action: 'add', 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.collections[name]?.key || ['id']
-    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)
-  }
-}

package/src/lib/collection.js

@@ -1,208 +0,0 @@
-import { Readable } from 'streamx'
-import { randomId } from './crypto.js'
-import { debounce, isLocal, isPrivate } from './utils.js'
-
-/** Route a write operation based on scope */
-function writeOp(owner, scope, path, ns, op, data, isDel) {
-  if (isLocal(scope)) {
-    const method = isDel ? 'delete' : 'insert'
-    return owner.local[method](path, data).then(() => owner.emit('update'))
-  }
-  const target = isPrivate(scope) ? owner.identity : owner.room
-  return target.dispatch(`${ns}/${op}`, data)
-}
-
-/**
- * Collection — 4 verbs: put, get, del, sub
- *
- * @example
- * const tasks = room.collection('tasks')
- *
- * await tasks.put({ text: 'Buy milk', done: false })
- * await tasks.get()                       // all docs
- * await tasks.get({ done: false })        // filtered
- * await tasks.del({ id: 'abc' })
- * tasks.sub().on('data', cb)
- */
-export class Collection {
-  constructor(owner, name) {
-    this.owner = owner
-    this.schema = owner.schema
-
-    const def = this.schema.collections[name]
-    this.scope = this.schema.getScope(name)
-    this.name = name
-    this.type = this.schema.types.get(name)
-    this.path = this.schema.getPath(name)
-    this.ns = this.path.split('/')[0]
-    this.keys = def.key || ['id']
-    this.timestamps = this.schema.hasTimestamps(name)
-    this.counter = !isLocal(this.scope) // all non-local collections have counter
-    this.indexes = def.indexes || null
-    this.db = isLocal(this.scope) ? null : isPrivate(this.scope) ? owner.identity.db : owner.room.db
-  }
-
-  /** Upsert — insert if new, update if exists */
-  async put(doc) {
-    const data = doc.id ? doc : { ...doc, id: randomId() }
-    const keyQuery = this.keys.reduce((acc, k) => ((acc[k] = data[k]), acc), {})
-    const existing = data.id ? await this._getOne(keyQuery) : null
-
-    if (existing) {
-      const updated = { ...existing, ...data }
-      if (this.timestamps) updated.updatedAt = Date.now()
-      return this._write(`set-${this.type}`, updated)
-    }
-
-    if (this.timestamps) data.createdAt = data.createdAt ?? Date.now()
-    return this._write(`add-${this.type}`, data)
-  }
-
-  /** Get docs — no query returns all, query filters, supports range queries on index */
-  async get(query = {}, opts = {}) {
-    if (isLocal(this.scope)) {
-      const all = await this.owner.local.find(this.path, opts)
-      return filter(all, query)
-    }
-
-    if (
-      this.counter &&
-      (typeof query.gte === 'number' ||
-        typeof query.lte === 'number' ||
-        typeof query.gt === 'number' ||
-        typeof query.lt === 'number')
-    ) {
-      return this._rangeByIndex(query, opts)
-    }
-
-    return findDocs(this.db, this.path, this.indexes, this.name, query, opts)
-  }
-
-  /** Get count */
-  async count() {
-    if (!this.counter) return (await this.get()).length
-
-    const counterPath = `${this.ns}/counters`
-    const snapshot = this.db.snapshot()
-    try {
-      const counter = await snapshot.get(counterPath, { name: this.name })
-      return counter?.value || 0
-    } finally {
-      await snapshot.close()
-    }
-  }
-
-  /** @private Range query on index field via the by-index index */
-  async _rangeByIndex(query, opts = {}) {
-    const indexPath = `${this.path}-by-index`
-    const snapshot = this.db.snapshot()
-    try {
-      const rangeQuery = {}
-      if (query.gte !== undefined) rangeQuery.gte = { index: query.gte }
-      if (query.lte !== undefined) rangeQuery.lte = { index: query.lte }
-      if (query.gt !== undefined) rangeQuery.gt = { index: query.gt }
-      if (query.lt !== undefined) rangeQuery.lt = { index: query.lt }
-      return snapshot.find(indexPath, { ...rangeQuery, ...opts }).toArray()
-    } finally {
-      await snapshot.close()
-    }
-  }
-
-  /** Delete a document by query */
-  async del(query) {
-    const [existing] = await this.get(query)
-    if (!existing) return false
-
-    const keyData = this.keys.reduce((acc, k) => ((acc[k] = existing[k]), acc), {})
-    await this._write(`del-${this.type}`, keyData, true)
-    return true
-  }
-
-  /** Subscribe — returns Readable stream of query results */
-  sub(query = {}, opts = {}) {
-    const stream = new Readable()
-    const emitter = this.owner
-
-    const refresh = debounce(async () => {
-      try {
-        const results = await this.get(query, opts)
-        stream.push(results)
-      } catch (err) {
-        stream.destroy(err)
-      }
-    })
-
-    refresh()
-    emitter.on('update', refresh)
-
-    const destroy = stream.destroy.bind(stream)
-    stream.destroy = (err) => {
-      emitter.off('update', refresh)
-      return destroy(err)
-    }
-
-    return stream
-  }
-
-  /** @private Single-doc lookup by key (used internally by put/del) */
-  async _getOne(query) {
-    if (isLocal(this.scope)) {
-      return this.owner.local.get(this.path, query)
-    }
-    const snapshot = this.db.snapshot()
-    try {
-      return await snapshot.get(this.path, query)
-    } finally {
-      await snapshot.close()
-    }
-  }
-
-  /** @private Route write to local/identity/room */
-  async _write(op, data, isDel = false) {
-    await writeOp(this.owner, this.scope, this.path, this.ns, op, data, isDel)
-    return isDel ? true : data
-  }
-}
-
-// ==================== Private Helpers ====================
-
-function filter(all, query) {
-  const entries = Object.entries(query)
-  if (entries.length === 0) return all
-  return all.filter((doc) => entries.every(([k, v]) => doc[k] === v))
-}
-
-async function findDocs(db, path, indexes, name, query, opts) {
-  const snapshot = db.snapshot()
-
-  try {
-    const rangeKey = query.gte || query.gt || query.lte || query.lt
-    if (rangeKey) {
-      const index = matchIndex(path, indexes, rangeKey)
-      if (!index) throw new Error(`No index found for range query on ${name}`)
-      return snapshot.find(index, { ...query, ...opts }).toArray()
-    }
-
-    const index = matchIndex(path, indexes, query)
-    if (index) {
-      return snapshot.find(index, { gte: query, lte: query, ...opts }).toArray()
-    }
-
-    const all = await snapshot.find(path, opts).toArray()
-    return filter(all, query)
-  } finally {
-    await snapshot.close()
-  }
-}
-
-function matchIndex(path, indexes, query) {
-  if (!indexes) return null
-
-  const firstField = Object.keys(query)[0]
-  if (!firstField) return null
-
-  for (const [name, fields] of Object.entries(indexes)) {
-    if (fields[0] === firstField) return `${path}-${name}`
-  }
-  return null
-}

package/src/lib/crypto.js

@@ -1,6 +0,0 @@
-import crypto from 'hypercore-crypto'
-import z32 from 'z32'
-
-export function randomId() {
-  return z32.encode(crypto.randomBytes(16))
-}

package/src/lib/index.js

@@ -1,6 +0,0 @@
-export * from './base.js'
-export * from './room.js'
-export * from './batch.js'
-export * from './collection.js'
-export * from './schema.js'
-export * from './constants.js'