@cero-base/core 0.2.0 → 0.4.1

package/src/database/index.js

@@ -0,0 +1,572 @@
+import Autobee from 'autobee'
+import HyperDB from 'hyperdb'
+import Hypercore from 'hypercore'
+import ReadyResource from 'ready-resource'
+import safetyCatch from 'safety-catch'
+import b4a from 'b4a'
+
+import { NAMESPACE, SINGLE, COLLECTION } from '../lib/constants.js'
+import { genId, subscribe } from '../lib/utils.js'
+import { CeroError } from '../lib/errors.js'
+import { bootstrap } from './bootstrap.js'
+import { makeDispatcher } from './dispatch.js'
+
+/**
+ * @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 = {}) {
+    super()
+
+    if (!opts.store) throw CeroError.REQUIRED('store')
+    if (!opts.identity) throw CeroError.REQUIRED('identity')
+    if (!opts.spec || !opts.spec.database || !opts.spec.dispatch) {
+      throw CeroError.INVALID('spec must have database + dispatch')
+    }
+
+    this.store = opts.store
+    this.identity = opts.identity
+    this.network = opts.network || null
+    this.spec = opts.spec
+    this.meta = opts.spec.meta || { ns: NAMESPACE, refs: {} }
+    this.ns = this.meta.ns || NAMESPACE
+    this.refs = this.meta.refs || {}
+    this.routes = opts.routes || {}
+    this.namespace = opts.namespace || NAMESPACE
+    this.encryptionKey = opts.encryptionKey || opts.identity.encryptionKey || null
+    this.applyOverride = opts.apply || null
+    this.key = opts.key || null
+    this.keyPair = opts.keyPair || {
+      publicKey: opts.identity.publicKey,
+      secretKey: opts.identity.secretKey
+    }
+
+    this.bee = null
+    this.dispatcher = null
+
+    this.beforeHooks = new Map()
+    this.afterHooks = new Map()
+    this.updaters = new Set()
+    this.txQueue = null
+  }
+
+  async _open() {
+    await this.store.ready()
+    if (this.network) await this.network.ready()
+
+    await this.openBee()
+  }
+
+  async _close() {
+    if (this._discovery) {
+      await this._discovery.destroy()
+      this._discovery = null
+    }
+    if (this.bee) {
+      await this.bee.close()
+      this.bee = null
+    }
+  }
+
+  /** Open the underlying autobee, wire dispatcher + apply, attach to network. */
+  async openBee() {
+    this.dispatcher = makeDispatcher(this.spec, this.ns, this.routes)
+
+    const bee = new Autobee(this.store.namespace(this.namespace), this.key, {
+      keyPair: this.keyPair,
+      encryptionKey: this.encryptionKey,
+      optimistic: true,
+      wakeup: this.network?.wakeup || undefined,
+      open: (b) => HyperDB.bee2(b, this.spec.database, { autoUpdate: true }),
+      apply: (nodes, view, host) =>
+        (this.applyOverride || this.dispatcher.apply)(nodes, view, host),
+      update: async (db) => {
+        await db.update()
+        for (const fn of this.updaters) fn()
+        this.emit('update')
+      }
+    })
+
+    await bee.ready()
+    await bee.update()
+
+    this.bee = bee
+    this.key = bee.key
+
+    bee.on('writable', () => this.emit('writable'))
+
+    if (this.network) {
+      this.network.attach(bee)
+      this._discovery = this.network.join(bee.discoveryKey)
+    }
+  }
+
+  get discoveryKey() {
+    return this.bee?.discoveryKey || null
+  }
+
+  get writerKey() {
+    return this.bee?.local?.key || null
+  }
+
+  get writable() {
+    return this.bee?.writable === true
+  }
+
+  get length() {
+    return this.bee?.local?.length || 0
+  }
+
+  get view() {
+    return this.bee?.view || null
+  }
+
+  /**
+   * Register a pre-op hook. Returning `false` from `fn` aborts the op.
+   *
+   * @param {string} op
+   * @param {HookFn} fn
+   * @returns {() => void} disposer
+   */
+  before(op, fn) {
+    return this._addHook(this.beforeHooks, op, fn)
+  }
+
+  /**
+   * Register a post-op hook, fired after the write succeeds.
+   *
+   * @param {string} op
+   * @param {HookFn} fn
+   * @returns {() => void} disposer
+   */
+  after(op, fn) {
+    return this._addHook(this.afterHooks, op, fn)
+  }
+
+  /**
+   * Subscribe to local apply notifications. Fires whenever the view updates.
+   *
+   * @param {() => void} fn
+   * @returns {() => void} disposer
+   */
+  onUpdate(fn) {
+    this.updaters.add(fn)
+    return () => this.updaters.delete(fn)
+  }
+
+  /**
+   * 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
+   */
+  async runBefore(op, ctx) {
+    const hooks = this.beforeHooks.get(op)
+    if (hooks) {
+      for (const fn of hooks) {
+        const out = await fn(ctx)
+        if (out === false) return false
+      }
+    }
+    this.emit(`before:${op}`, ctx)
+    return true
+  }
+
+  /**
+   * Run all registered `after:op` hooks and emit the corresponding event.
+   *
+   * @param {string} op
+   * @param {any} ctx
+   * @returns {Promise<void>}
+   */
+  async runAfter(op, ctx) {
+    const hooks = this.afterHooks.get(op)
+    if (hooks) {
+      for (const fn of hooks) {
+        try {
+          await fn(ctx)
+        } catch (err) {
+          safetyCatch(err)
+        }
+      }
+    }
+    this.emit(`after:${op}`, ctx)
+  }
+
+  /**
+   * Insert (or overwrite by id) a row, stamping `id`/`createdAt`/`updatedAt`.
+   *
+   * @param {string} name
+   * @param {Record<string, any>} row
+   * @returns {Promise<SingleResult | null>}
+   */
+  async put(name, row) {
+    this.guard()
+    const ref = this.ref(name)
+    const id = row.id || genId()
+    const ts = Date.now()
+    const stored = { createdAt: ts, updatedAt: ts, ...row, id }
+
+    const ctx = { op: 'put', name, row: stored }
+    if ((await this.runBefore('put', ctx)) === false) return null
+
+    await this.write([[`add-${ref.verb}`, ctx.row]])
+
+    const result = { data: ctx.row }
+    await this.runAfter('put', { ...ctx, result })
+    return result
+  }
+
+  /**
+   * Upsert by merging with the existing row, preserving `createdAt`.
+   *
+   * @param {string} name
+   * @param {Record<string, any>} row
+   * @returns {Promise<SingleResult | null>}
+   */
+  async set(name, row) {
+    this.guard()
+    const ref = this.ref(name)
+    const col = this.col(ref)
+    const ts = Date.now()
+    const existing =
+      ref.kind === SINGLE
+        ? await this.view.findOne(col, {})
+        : row?.id
+          ? ((await this.view.get(col, { id: row.id })) ?? null)
+          : null
+    const stored = {
+      ...existing,
+      ...row,
+      createdAt: existing?.createdAt ?? ts,
+      updatedAt: ts
+    }
+    if (ref.kind === COLLECTION && !stored.id) stored.id = genId()
+
+    const ctx = { op: 'set', name, row: stored }
+    if ((await this.runBefore('set', ctx)) === false) return null
+
+    await this.write([[`set-${ref.verb}`, ctx.row]])
+
+    const result = { data: ctx.row }
+    await this.runAfter('set', { ...ctx, result })
+    return result
+  }
+
+  /**
+   * Delete by id (collection) or wipe the whole single-row table.
+   *
+   * @param {string} name
+   * @param {string} [id]
+   * @returns {Promise<void | null>}
+   */
+  async del(name, id) {
+    this.guard()
+    const ref = this.ref(name)
+    const ctx = { op: 'del', name, id }
+    if ((await this.runBefore('del', ctx)) === false) return null
+
+    await this.write([[`del-${ref.verb}`, { id }]])
+
+    await this.runAfter('del', ctx)
+  }
+
+  /**
+   * Dispatch a custom action route by name.
+   *
+   * @param {string} op
+   * @param {Record<string, any>} [data]
+   * @returns {Promise<void>}
+   */
+  async call(op, data = {}) {
+    this.guard()
+    await this.write([[op, data]])
+  }
+
+  /**
+   * 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>}
+   */
+  async tx(fn) {
+    if (this.txQueue) return fn()
+    const queue = []
+    this.txQueue = queue
+    let result
+    try {
+      result = await fn()
+    } catch (err) {
+      this.txQueue = null
+      throw err
+    }
+    this.txQueue = null
+    if (queue.length) await this.write(queue)
+    return result
+  }
+
+  /**
+   * Encode and append dispatch ops. Buffers into the active `tx` queue if one
+   * is open.
+   *
+   * @param {Array<[string, any]>} ops
+   * @returns {Promise<void>}
+   */
+  async write(ops) {
+    if (this.txQueue) {
+      for (const op of ops) this.txQueue.push(op)
+      return
+    }
+    if (!this.bee.writable) throw CeroError.NOT_WRITABLE('Database')
+    const encoded = ops.map(([op, payload]) =>
+      this.spec.dispatch.encode(`@${this.ns}/${op}`, payload)
+    )
+    await this.bee.append(encoded.length === 1 ? encoded[0] : encoded)
+  }
+
+  /**
+   * 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>}
+   */
+  async get(name, query) {
+    this.guard()
+    const ref = this.ref(name)
+    const col = this.col(ref)
+
+    if (ref.kind === SINGLE) {
+      return { data: await this.view.findOne(col, {}) }
+    }
+
+    if (typeof query === 'string') {
+      return { data: await this.view.get(col, { id: query }) }
+    }
+
+    const all = await this.view.find(col, {}).toArray()
+    const total = all.length
+    const data = paginate(all, query)
+    return { data, total, size: data.length }
+  }
+
+  /**
+   * Number of rows that match `query` (or total if omitted).
+   *
+   * @param {string} name
+   * @param {Query} [query]
+   * @returns {Promise<{ data: number }>}
+   */
+  async count(name, query) {
+    this.guard()
+    const ref = this.ref(name)
+    const all = await this.view.find(this.col(ref), {}).toArray()
+    return { data: paginate(all, query).length }
+  }
+
+  /**
+   * 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, query) {
+    this.guard()
+    this.ref(name)
+    return subscribe({
+      get: () => this.get(name, query),
+      watch: (fn) => this.onUpdate(fn)
+    })
+  }
+
+  /**
+   * 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) {
+    this.guard()
+    return bootstrap(this, opts)
+  }
+
+  /**
+   * 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>}
+   */
+  async claim({ name = null, isMobile = false } = {}) {
+    this.guard()
+    if (this.bee.writable) return
+
+    const writerKey = this.writerKey
+    const sig = this.identity.sign(writerKey)
+    const encoded = this.spec.dispatch.encode(`@${this.ns}/claim-writer`, {
+      identity: this.identity.publicKey,
+      writer: writerKey,
+      sig,
+      name,
+      isMobile
+    })
+    await this.bee.append(encoded, { optimistic: true })
+    await this.bee.update()
+    if (!this.bee.writable) await this.whenWritable()
+  }
+
+  /**
+   * Resolve once the bee becomes writable, or reject after `timeout` ms.
+   *
+   * @param {{ timeout?: number }} [opts]
+   * @returns {Promise<void>}
+   */
+  async whenWritable({ timeout = 30000 } = {}) {
+    this.guard()
+    if (this.bee.writable) return
+    return new Promise((resolve, reject) => {
+      let timer = null
+      let pollTimer = null
+      let done = false
+
+      const finish = (err) => {
+        if (done) return
+        done = true
+        if (timer) clearTimeout(timer)
+        if (pollTimer) clearInterval(pollTimer)
+        if (this.bee) this.bee.off('writable', onWritable)
+        this.off('close', onClose)
+        if (err) reject(err)
+        else resolve()
+      }
+
+      const onWritable = () => finish()
+      const onClose = () => finish(CeroError.CLOSED('Database'))
+      const poll = async () => {
+        if (done || !this.bee) return
+        try {
+          await this.bee.update()
+          if (!done && this.bee.writable) finish()
+        } catch {}
+      }
+
+      this.bee.on('writable', onWritable)
+      this.on('close', onClose)
+      pollTimer = setInterval(poll, 1000)
+      if (timeout > 0) {
+        timer = setTimeout(() => finish(CeroError.TIMED_OUT('whenWritable')), timeout)
+      }
+    })
+  }
+
+  /**
+   * Add a peer's writer key to the indexer set.
+   *
+   * @param {Uint8Array} publicKey
+   * @returns {Promise<void>}
+   */
+  async addWriter(publicKey) {
+    return this._write('add-writer', 'addWriter', publicKey)
+  }
+
+  /**
+   * Remove a peer's writer key from the indexer set.
+   *
+   * @param {Uint8Array} publicKey
+   * @returns {Promise<void>}
+   */
+  async removeWriter(publicKey) {
+    return this._write('del-writer', 'removeWriter', publicKey)
+  }
+
+  guard() {
+    if (this.closing || this.closed) throw CeroError.CLOSED('Database')
+    if (!this.bee) throw CeroError.NOT_READY('Database', 'db')
+  }
+
+  ref(name) {
+    if (typeof name !== 'string' || !name)
+      throw CeroError.INVALID('name must be a non-empty string')
+    const ref = this.refs[name]
+    if (!ref) throw CeroError.UNKNOWN('ref', name)
+    return { name, kind: ref.kind || COLLECTION, verb: ref.verb || name }
+  }
+
+  col(ref) {
+    return `@${this.ns}/${ref.name}`
+  }
+
+  _addHook(map, op, fn) {
+    if (typeof fn !== 'function') throw CeroError.INVALID('hook fn must be a function')
+    let arr = map.get(op)
+    if (!arr) map.set(op, (arr = []))
+    arr.push(fn)
+    return () => {
+      const i = arr.indexOf(fn)
+      if (i >= 0) arr.splice(i, 1)
+    }
+  }
+
+  async _write(verb, hook, publicKey) {
+    this.guard()
+    if (!b4a.isBuffer(publicKey) && !(publicKey instanceof Uint8Array)) {
+      throw CeroError.INVALID('publicKey must be a buffer')
+    }
+    const ctx = { op: hook, publicKey }
+    if ((await this.runBefore(hook, ctx)) === false) return
+    const writerKey = Hypercore.key({
+      version: this.store.manifestVersion,
+      signers: [{ publicKey }]
+    })
+    const sig = this.identity.sign(writerKey)
+    await this.write([
+      [
+        verb,
+        { master: this.identity.publicKey, writer: writerKey, sig, name: null, isMobile: false }
+      ]
+    ])
+    await this.runAfter(hook, ctx)
+  }
+}
+
+function paginate(rows, query) {
+  if (!query) return rows
+  let out = rows
+  if (query.gt !== undefined) out = out.filter((r) => r.id > query.gt)
+  if (query.gte !== undefined) out = out.filter((r) => r.id >= query.gte)
+  if (query.lt !== undefined) out = out.filter((r) => r.id < query.lt)
+  if (query.lte !== undefined) out = out.filter((r) => r.id <= query.lte)
+  if (query.reverse) out = [...out].reverse()
+  if (query.limit !== undefined) out = out.slice(0, query.limit)
+  return out
+}

package/src/identity/CLAUDE.md

@@ -0,0 +1,3 @@
+<claude-mem-context>
+
+</claude-mem-context>