@cero-base/cero 0.4.0

package/src/lib/operators.js

@@ -0,0 +1,128 @@
+import { Readable } from 'streamx'
+
+/**
+ * @typedef {import('./utils.js').Ref} Ref
+ * @typedef {{ data: any }} SingleResult
+ * @typedef {{ data: any[], total: number, size: number }} ListResult
+ * @typedef {{ data: any | null }} GetByIdResult
+ */
+
+/**
+ * Insert (or overwrite by id) a row on `ref`.
+ *
+ * @param {Ref} ref
+ * @param {Record<string, any>} row
+ * @returns {Promise<SingleResult>}
+ */
+export const put = (ref, row) => ref.handle.store.put(ref.name, row)
+
+/**
+ * Upsert a row on `ref` — merges with the existing row and preserves
+ * `createdAt`.
+ *
+ * @param {Ref} ref
+ * @param {Record<string, any>} row
+ * @returns {Promise<SingleResult>}
+ */
+export const set = (ref, row) => ref.handle.store.set(ref.name, row)
+
+/**
+ * Delete a row by id (collection refs), or wipe the row (single refs).
+ *
+ * @param {Ref} ref
+ * @param {string} [id]
+ * @returns {Promise<void>}
+ */
+export const del = (ref, id) => ref.handle.store.del(ref.name, id)
+
+/**
+ * Count rows on `ref`, optionally filtered.
+ *
+ * @param {Ref} ref
+ * @param {Record<string, any>} [q]
+ * @returns {Promise<{ data: number }>}
+ */
+export const count = (ref, q) => ref.handle.store.count(ref.name, q)
+
+/**
+ * Invoke an `action`-kind ref (a custom mutation declared in the schema).
+ *
+ * @param {Ref} ref
+ * @param {Record<string, any>} [d]
+ * @returns {Promise<any>}
+ */
+export const call = (ref, d) => ref.handle.store.call(ref.name, d)
+
+// get/watch on a handle-kind ref list its rows from the `handles` collection
+// filtered by type (handle types are stored there with their { id, key,
+// encryptionKey, name }). Data-kind refs go straight to the store.
+// For handle-kind refs on the facade, the parent store lives on `root`.
+const parentStore = (ref) => (ref.handle.root ? ref.handle.root.store : ref.handle.store)
+
+const normalize = (rows, name) => {
+  const data = (rows || []).filter((r) => r.type === name)
+  return { data, total: data.length, size: data.length }
+}
+
+/**
+ * Read from `ref`. For data refs, dispatches to the underlying store. For
+ * `handle`-kind refs, lists existing child handles of that type from the
+ * parent's `handles` collection.
+ *
+ * @param {Ref} ref
+ * @param {string | Record<string, any>} [q]
+ * @returns {Promise<SingleResult | ListResult | GetByIdResult>}
+ */
+export const get = async (ref, q) => {
+  if (ref.kind !== 'handle') return ref.handle.store.get(ref.name, q)
+  const { data: all } = await parentStore(ref).get('handles', q)
+  return normalize(all, ref.name)
+}
+
+/**
+ * Live snapshot stream on `ref` — re-emits the latest `get()` result on
+ * every underlying mutation. Destroy the stream to stop watching.
+ *
+ * @param {Ref} ref
+ * @param {Record<string, any>} [q]
+ * @returns {import('streamx').Readable}
+ */
+export const watch = (ref, q) => {
+  if (ref.kind !== 'handle') return ref.handle.store.watch(ref.name, q)
+  const source = parentStore(ref).watch('handles', q)
+  const out = new Readable({
+    destroy(cb) {
+      source.destroy()
+      cb(null)
+    }
+  })
+  source.on('data', (snap) => out.push(normalize(snap?.data, ref.name)))
+  source.on('end', () => out.push(null))
+  source.on('error', (err) => out.destroy(err))
+  return out
+}
+
+// Universal signal instantiator. Dispatch on the second arg:
+//   string                  → join via invite
+//   { invite: string }      → join via invite (object form)
+//   { id: string }          → load an existing handle by id
+//   object | undefined      → create (opts)
+/**
+ * Open (or create / join / load) a child handle through a `handle`-kind
+ * ref. Dispatches on the normalize of `arg`:
+ *
+ *   - `string`                → join via an invite string
+ *   - `{ invite: string }`    → join via invite (object form)
+ *   - `{ id: string }`        → load an existing handle by id
+ *   - `object | undefined`    → create a new handle with the given opts
+ *
+ * @param {Ref} ref
+ * @param {string | { invite?: string, id?: string, name?: string, routes?: any, role?: string, accept?: boolean } | undefined} [arg]
+ * @returns {Promise<any>}  The resolved child `Handle`.
+ */
+export const open = (ref, arg) => {
+  if (typeof arg === 'string') return ref.handle._join(arg, ref.name)
+  if (arg && typeof arg.invite === 'string') return ref.handle._join(arg.invite, ref.name)
+  if (arg && typeof arg.id === 'string') return ref.handle._load(ref.name, arg.id)
+  return ref.handle._create(ref.name, arg)
+}

package/src/lib/peek.js

@@ -0,0 +1,36 @@
+import HypercoreStorage from 'hypercore-storage'
+import Corestore from 'corestore'
+
+import { CeroError } from '@cero-base/core/errors'
+
+import { Local } from '../local/index.js'
+
+/**
+ * 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 async function peek(dir, spec) {
+  if (typeof dir !== 'string' || !dir) throw CeroError.INVALID('dir must be a non-empty string')
+  if (!spec) throw CeroError.REQUIRED('spec')
+
+  const root = new HypercoreStorage(`${dir}/main`)
+  await root.ready()
+  const store = new Corestore(root, { manifestVersion: 2 })
+  await store.ready()
+
+  const local = new Local(null, spec, { store })
+  await local.ready()
+  try {
+    const { data } = await local.store.get('master')
+    return !!data?.seed
+  } finally {
+    await local.close()
+    await store.close()
+    await root.close()
+  }
+}

package/src/lib/spec.js

@@ -0,0 +1,6 @@
+/**
+ * Re-exports of the schema DSL (`t`) and `schema()` wrapper from
+ * `@cero-base/core/schema`, so cero apps can describe their tables without
+ * pulling in the core package directly.
+ */
+export { t, schema } from '@cero-base/core/schema'

package/src/lib/utils.js

@@ -0,0 +1,41 @@
+/**
+ * @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, name, kind, schema = null) {
+    this.handle = handle
+    this.name = name
+    this.kind = kind
+    this.schema = schema
+  }
+}
+
+/**
+ * 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, refs) {
+  for (const [name, info] of Object.entries(refs || {})) {
+    target[name] = new Ref(target, name, info.kind, info.schema)
+  }
+}

package/src/local/index.js

@@ -0,0 +1,49 @@
+import ReadyResource from 'ready-resource'
+
+import { Storage } from '@cero-base/core/storage'
+import { CeroError } from '@cero-base/core/errors'
+
+import { attachRefs } from '../lib/utils.js'
+
+/**
+ * @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, spec, { root, store } = {}) {
+    super()
+    if (!root && !store && (typeof dir !== 'string' || !dir))
+      throw CeroError.REQUIRED('dir, root, or store')
+    if (!spec?.local?.database) throw CeroError.REQUIRED('spec.local.database')
+    if (!spec?.meta?.local) throw CeroError.REQUIRED('spec.meta.local')
+
+    this.dir = dir
+    this.spec = spec
+    this.store = Storage.bee(dir, {
+      spec: { database: spec.local.database, meta: spec.meta.local },
+      root,
+      store
+    })
+  }
+
+  async _open() {
+    await this.store.ready()
+    attachRefs(this, this.store.refs)
+  }
+
+  async _close() {
+    await this.store.close()
+  }
+}

package/src/rpc/CLAUDE.md

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

package/src/rpc/client.js

@@ -0,0 +1,337 @@
+import { Readable } from 'streamx'
+import { RPCClient, bindCodec } from '@cero-base/core/rpc'
+
+import { attachRefs } from '../lib/utils.js'
+
+export { put, set, get, del, count, watch, call, open } from '../lib/operators.js'
+
+/**
+ * @typedef {import('@cero-base/core/rpc').RPCClient} BaseRPCClient
+ *
+ * @typedef {object} RefInfo
+ * @property {'single'|'collection'|'action'|'handle'} [kind]
+ * @property {string} [schema]
+ * @property {string} [type]
+ *
+ * @typedef {import('@cero-base/core/rpc').Spec & { meta: { ns?: string, refs: Record<string, RefInfo>, handles?: Record<string, Spec> }, handles: Record<string, Spec> }} Spec  Built cero spec (schema + rpc + per-handle child specs).
+ *
+ * @typedef {{ data: any }} SingleResult
+ * @typedef {{ data: any[], total: number, size: number }} ListResult
+ * @typedef {{ data: any | null }} GetByIdResult
+ *
+ * @typedef {object} ClientIdentity
+ * @property {string} id
+ * @property {() => string|null} toPhrase
+ *
+ * @typedef {object} HandleStub
+ * @property {string} id
+ * @property {string} type
+ * @property {string|null} name
+ */
+
+// Mixin applied to both Client and Handle so they expose the same row-ops
+// surface as a local cero handle but routed over the wire.
+const operators = {
+  /** @param {string} name @returns {string|undefined} */
+  schemaOf(name) {
+    return this.spec.meta.refs[name]?.schema
+  },
+
+  /**
+   * Insert a row over the wire.
+   *
+   * @param {string} name
+   * @param {Record<string, any>} row
+   * @returns {Promise<SingleResult>}
+   */
+  async put(name, row) {
+    const schema = this.schemaOf(name)
+    const codec = this.spec.codec
+    const input = row?.id ? row : { id: '', ...row }
+    const res = await this.rpc.addRow({
+      handle: this.id,
+      ref: name,
+      data: codec.encodeRow(schema, input)
+    })
+    return { data: codec.decodeRow(schema, res.data) }
+  },
+
+  /**
+   * Upsert a row over the wire.
+   *
+   * @param {string} name
+   * @param {Record<string, any>} row
+   * @returns {Promise<SingleResult>}
+   */
+  async set(name, row) {
+    const schema = this.schemaOf(name)
+    const codec = this.spec.codec
+    const res = await this.rpc.set({
+      handle: this.id,
+      ref: name,
+      data: codec.encodeRow(schema, row)
+    })
+    return { data: codec.decodeRow(schema, res.data) }
+  },
+
+  /**
+   * Read a row (by id string) or a list (by query object). Mirrors the
+   * `Storage.get` contract.
+   *
+   * @param {string} name
+   * @param {string | Record<string, any>} [query]
+   * @returns {Promise<SingleResult | ListResult | GetByIdResult>}
+   */
+  async get(name, query) {
+    const schema = this.schemaOf(name)
+    const codec = this.spec.codec
+    if (typeof query === 'string') {
+      const res = await this.rpc.getOne({ handle: this.id, ref: name, id: query })
+      return { data: res.data ? codec.decodeRow(schema, res.data) : null }
+    }
+    const res = await this.rpc.get({
+      handle: this.id,
+      ref: name,
+      query: codec.encodeQuery(query)
+    })
+    const kind = this.spec.meta.refs[name]?.kind
+    const data =
+      kind === 'single' ? codec.decodeRow(schema, res.data) : codec.decodeRows(schema, res.data)
+    return { data, total: res.total, size: res.size }
+  },
+
+  /**
+   * Delete a row by id.
+   *
+   * @param {string} name
+   * @param {string} [id]
+   * @returns {Promise<void>}
+   */
+  async del(name, id) {
+    await this.rpc.del({ handle: this.id, ref: name, id })
+  },
+
+  /**
+   * Count matching rows.
+   *
+   * @param {string} name
+   * @param {Record<string, any>} [query]
+   * @returns {Promise<{ data: number }>}
+   */
+  async count(name, query) {
+    const codec = this.spec.codec
+    const res = await this.rpc.count({
+      handle: this.id,
+      ref: name,
+      query: codec.encodeQuery(query)
+    })
+    return { data: res.count }
+  },
+
+  /**
+   * Live snapshot stream. Re-emits the latest `get()` shape on every
+   * underlying mutation. Destroy the stream to stop watching.
+   *
+   * @param {string} name
+   * @param {Record<string, any>} [query]
+   * @returns {import('streamx').Readable}
+   */
+  watch(name, query) {
+    const refInfo = this.spec.meta.refs[name]
+    const schema = refInfo?.schema
+    const codec = this.spec.codec
+    const wire = this.rpc.watch({
+      handle: this.id,
+      ref: name,
+      query: codec.encodeQuery(query)
+    })
+    const out = new Readable({
+      predestroy() {
+        wire.destroy()
+      }
+    })
+    wire.on('data', (snap) => {
+      const data =
+        refInfo.kind === 'single'
+          ? (codec.decodeRow(schema, snap.data) ?? null)
+          : codec.decodeRows(schema, snap.data)
+      out.push({ data, total: snap.total, size: snap.size })
+    })
+    wire.on('end', () => out.push(null))
+    wire.on('error', (err) => out.destroy(err))
+    return out
+  },
+
+  /**
+   * Invoke a named action ref over the wire.
+   *
+   * @param {string} op
+   * @param {any} [data]
+   * @returns {Promise<void>}
+   */
+  async call(op, data) {
+    const schema = this.schemaOf(op)
+    const codec = this.spec.codec
+    const encoded = data ? codec.encodeAction({ [op]: { schema } }, op, data) : null
+    await this.rpc.call({ handle: this.id, op, data: encoded })
+  },
+
+  /**
+   * Mint a pairing invite for this handle.
+   *
+   * @param {{ role?: string }} [opts]
+   * @returns {Promise<string>}
+   */
+  async invite({ role } = {}) {
+    const { invite } = await this.rpc.invite({ handle: this.id, role: role || '' })
+    return invite
+  },
+
+  /**
+   * Revoke a previously issued invite.
+   *
+   * @param {string} invite
+   * @returns {Promise<boolean>}
+   */
+  async revoke(invite) {
+    const { ok } = await this.rpc.revoke({ handle: this.id, invite })
+    return ok
+  }
+}
+
+/**
+ * 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 async function restore(me, phrase) {
+  const res = await me.rpc.restore({ phrase })
+  me.id = res.id
+  me.deviceId = res.deviceId || null
+  me.identity = { id: res.id, toPhrase: () => res.phrase || null }
+  return me
+}
+
+/**
+ * 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, spec) {
+    super(ipc, spec)
+    Object.assign(this, operators)
+    this.id = null
+    this.deviceId = null
+    this.store = this
+  }
+
+  async _open() {
+    await super._open()
+    const { id, deviceId, phrase } = await this.rpc.init({})
+    this.id = id
+    this.deviceId = deviceId || null
+    this.identity = { id, toPhrase: () => phrase || null }
+    attachRefs(this, /** @type {Spec} */ (this.spec).meta.refs)
+  }
+
+  /**
+   * Create a new child handle of the given type.
+   *
+   * @param {string} type
+   * @param {Record<string, any>} [opts]
+   * @returns {Promise<Handle>}
+   */
+  async _create(type, opts = {}) {
+    const stub = await this.rpc.addHandle({
+      ref: type,
+      handle: this.id,
+      data: this.spec.codec.encodeCreate(opts)
+    })
+    return new Handle(this, stub.id, stub.type, stub.name || null)
+  }
+
+  /**
+   * Load an existing child handle by id.
+   *
+   * @param {string} type
+   * @param {string} id
+   * @returns {Promise<Handle>}
+   */
+  async _load(type, id) {
+    const stub = await this.rpc.openHandle({ parent: this.id, row: id })
+    return new Handle(this, stub.id, stub.type, stub.name || null)
+  }
+
+  /**
+   * Join a child handle via invite.
+   *
+   * @param {string} invite
+   * @param {string} type
+   * @returns {Promise<Handle>}
+   */
+  async _join(invite, type) {
+    const stub = await this.rpc.join({ parent: this.id, ref: type, invite })
+    return new Handle(this, stub.id, stub.type, stub.name || null)
+  }
+}
+
+/**
+ * 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.
+ */
+class Handle {
+  /**
+   * @param {Client} parent
+   * @param {string} id
+   * @param {string} type
+   * @param {string|null} name
+   */
+  constructor(parent, id, type, name) {
+    Object.assign(this, operators)
+    this.parent = parent
+    this.id = id
+    this.type = type
+    this.name = name
+    this.spec = /** @type {Spec} */ (parent.spec).handles[type]
+    if (!this.spec.codec) bindCodec(this.spec)
+    this.store = this
+    attachRefs(this, this.spec.meta.refs)
+  }
+
+  /** Underlying RPC channel borrowed from the parent. */
+  get rpc() {
+    return this.parent.rpc
+  }
+
+  /** Tear down the remote handle without leaving the room. */
+  close() {
+    return this.parent.rpc.closeHandle({ handle: this.id })
+  }
+
+  /** Tear down the remote handle and drop membership. */
+  leave() {
+    return this.parent.rpc.leave({ handle: this.id })
+  }
+}
+
+/**
+ * Construct a `Client`, wait for `init` to complete, and return it.
+ *
+ * @param {any} ipc
+ * @param {object} spec
+ * @returns {Promise<Client>}
+ */
+export async function connect(ipc, spec) {
+  const client = new Client(ipc, spec)
+  await client.ready()
+  return client
+}

package/src/rpc/index.js

@@ -0,0 +1,8 @@
+/**
+ * RPC barrel — re-exports the `Server`/`Client` classes and their
+ * `serve()`/`connect()` helpers so consumers can spin up either side
+ * of the cero IPC bridge from a single import.
+ */
+
+export { Server, serve } from './server.js'
+export { Client, connect } from './client.js'