@cero-base/cero 1.18.2 → 2.0.0

package/src/lib/operators.js

@@ -3,10 +3,10 @@ import b4a from 'b4a'
 
 import { encodeId, decodeId } from '@cero-base/core/blobs/codec'
 import { CeroError } from '@cero-base/core/errors'
-import { onAbort } from './utils.js'
+import { onAbort } from '@cero-base/core/utils'
 
 /**
- * @typedef {import('./utils.js').Ref} Ref
+ * @typedef {import('./refs.js').Ref} Ref
  * @typedef {import('../handle/index.js').CeroHandle} CeroHandle
  * @typedef {{ data: any }} SingleResult
  * @typedef {{ data: any[], total: number, size: number }} ListResult
@@ -30,9 +30,7 @@ export function resolveFile(handle, id, name) {
 }
 
 /**
- * Insert (or overwrite by id) a row on `ref`. The `files` builtin is special:
- * `put(handle.files, { data, type, name? })` uploads the bytes to this handle's
- * blob store, records `{ id, name }`, and resolves the file.
+ * Insert (or overwrite by id) a row on `ref`.
  *
  * @param {Ref} ref
  * @param {Record<string, any>} row
@@ -55,9 +53,7 @@ async function putFile(ref, row) {
 }
 
 /**
- * Upsert a row on `ref` — merges with the existing row and preserves
- * `createdAt`. Pass `{ upsert: false }` to update-only: a missing row is left
- * untouched instead of created (atomic — never resurrects a deleted row).
+ * Upsert a row on `ref` — merges with the existing row and preserves `createdAt`.
  *
  * @param {Ref} ref
  * @param {Record<string, any>} row
@@ -101,13 +97,10 @@ export function call(ref, d) {
   return ref.handle.store.call(ref.name, d)
 }
 
-// Write ops per ref kind, for `before`/`after` subscriptions.
 const WRITES = { single: ['set'], collection: ['put', 'set', 'del'] }
 
 /**
- * Intercept writes to `ref` before they commit — `fn(ctx)` runs in-path
- * (awaited). Return `false` to cancel the write, or mutate `ctx.row`.
- * Returns an unsubscribe fn; pass `{ signal }` to unsubscribe on abort.
+ * Intercept writes to `ref` before they commit — `fn(ctx)` runs in-path (awaited).
  *
  * @param {Ref} ref
  * @param {(ctx: { op: string, name: string, row: any }) => any} fn
@@ -130,9 +123,8 @@ export function before(ref, fn, opts) {
 }
 
 /**
- * Subscribe to writes on `ref` — fires after each committed write,
- * non-blocking (observe only). Returns an unsubscribe fn; pass `{ signal }`
- * to unsubscribe on abort.
+ * Subscribe to writes on `ref` — fires after each committed write, non-blocking (observe
+ * only).
  *
  * @param {Ref} ref
  * @param {(ctx: { op: string, name: string, row: any }) => void} fn
@@ -153,10 +145,7 @@ export function after(ref, fn, opts) {
   return off
 }
 
-// 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`.
+// handle refs read their rows from the parent's `handles` collection, filtered by type
 const parentStore = (ref) => (ref.handle.root ? ref.handle.root.store : ref.handle.store)
 
 const normalize = (rows, name) => {
@@ -195,9 +184,7 @@ function resolveRow(ref, row) {
 }
 
 /**
- * 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.
+ * Read from `ref`. For data refs, dispatches to the underlying store.
  *
  * @param {Ref} ref
  * @param {string | Record<string, any>} [q]
@@ -212,22 +199,17 @@ export async function get(ref, q) {
   return resolveResult(ref, res)
 }
 
-// Tie a fresh watch stream to its handle's lifecycle (destroyed on close) and
-// to an optional `{ signal }` (destroyed on abort). Local refs have no
-// close-cascade, so they keep managing their own streams.
+// a watch stream dies with its handle, or with the signal
 const bindStream = (owner, stream, opts) => {
   const stopAbort = onAbort(opts?.signal, () => stream.destroy())
-  // drop the abort listener once the stream ends, so it doesn't linger on a
-  // long-lived signal after the stream is gone
+  // drop the abort listener once the stream ends
   if (stopAbort) stream.once('close', stopAbort)
   return owner.own ? owner.own(stream) : stream
 }
 
 /**
- * Live snapshot stream on `ref` — re-emits the latest `get()` result on
- * every underlying mutation. Tied to `ref.handle`'s lifecycle: closing the
- * handle destroys it. Pass `{ signal }` to bind it to a finer scope, or
- * destroy the stream directly to stop watching sooner.
+ * Live snapshot stream on `ref` — re-emits the latest `get()` result on every underlying
+ * mutation.
  *
  * @param {Ref} ref
  * @param {Record<string, any>} [q]
@@ -247,10 +229,9 @@ export function watch(ref, q, opts) {
 }
 
 /**
- * Delta subscription: batches of `{ prev, next }` row pairs instead of
- * full snapshots — lossless under backpressure, self-contained (the first
- * batch, and any batch after a view swap, replays current state as inserts
- * with `reset: true`). File-typed fields resolve on both sides.
+ * Delta subscription: batches of `{ prev, next }` row pairs instead of full snapshots —
+ * lossless under backpressure, self-contained (the first batch, and any batch after a view
+ * swap, replays current.
  */
 export function changes(ref, q, opts) {
   const owner = ref.handle
@@ -297,9 +278,7 @@ export function changes(ref, q, opts) {
   return bindStream(owner, out, opts)
 }
 
-// Snapshots are idempotent — under a slow consumer hold only the NEWEST one
-// instead of queueing every intermediate (a busy room + un-drained reader
-// used to buffer full result sets without bound).
+// snapshots are idempotent: a slow consumer gets only the newest
 function snapshotStream(src, map) {
   let pending
   let wanted = false
@@ -329,19 +308,8 @@ function snapshotStream(src, map) {
   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
+ * Open (or create / join / load) a child handle through a `handle`-kind ref.
  *
  * @param {Ref} ref
  * @param {string | { invite?: string, id?: string, name?: string, routes?: any, role?: string, accept?: boolean } | undefined} [arg]
@@ -355,13 +323,9 @@ export function open(ref, arg) {
 }
 
 /**
- * Rotate a handle's encryption epoch. A fresh secret is sealed to every
- * current member and announced through the log — members removed before the
- * rotation cannot decrypt anything written after it. Requires the remove
- * permission (admin or owner). Compose with removal:
- *
- *   await cero.del(room.members, memberId)
- *   await cero.rotate(room)
+ * Rotate a handle's encryption epoch. A fresh secret is sealed to every current member and
+ * announced through the log — members removed before the rotation cannot decrypt anything
+ * written after it.
  *
  * @param {any} handle
  * @returns {Promise<{ epoch: number }>}
@@ -370,16 +334,8 @@ export function rotate(handle) {
   return handle.store.rotate()
 }
 
-// ─── custom operators ──────────────────────────────────────────────────────
-// App business logic lives as custom operators: pure functions whose first arg
-// is the handle they act on, composed from the operators above. `define`
-// registers them by scope; `bind` puts them on a handle — either an explicit
-// `{ ns: module }` map, or (given a scope) the registered operators for that
-// scope, which is how cero auto-binds the root and each child as it opens.
-
 const registry = {}
 
-// Curry `handle` as arg 0 of every function in `fns`, under `handle[ns]`.
 function attach(handle, ns, fns) {
   const bound = {}
   for (const key of Object.keys(fns)) {
@@ -390,12 +346,7 @@ function attach(handle, ns, fns) {
 
 /**
  * Put custom operators on `handle`, currying it as their first argument so
- * `handle.ns.fn(args)` calls `fn(handle, args)`. `arg` is either:
- *   - a `{ ns: module }` map  → bind exactly those, or
- *   - `null`                  → the registered root operators, or
- *   - a child-handle type     → the registered operators for that type.
- * The scope forms are how cero binds handles automatically; pass a map yourself
- * for manual binding.
+ * `handle.ns.fn(args)` calls `fn(handle, args)`.
  *
  * @param {any} handle
  * @param {Record<string, any> | string | null} arg
@@ -418,9 +369,8 @@ export function bind(handle, arg) {
 }
 
 /**
- * Register custom operators by scope. A bare key binds on the root handle; a key
- * that names a child-handle type binds on every handle of that type. Call once
- * at startup, before `cero()` / `connect()`, in both processes.
+ * Register custom operators by scope. A bare key binds on the root handle; a key that
+ * names a child-handle type binds on every handle of that type.
  *
  * @param {Record<string, any>} map
  */

package/src/lib/peek.js

@@ -6,14 +6,11 @@ import { CeroError } from '@cero-base/core/errors'
 
 import { Local } from '../local/index.js'
 
-// Lives outside operators.js so the storage deps stay off the RPC client's
-// module graph — bundlers follow even dynamic imports, and a browser build
-// must never reach hypercore/sodium.
+// outside operators.js so storage deps stay off the client's module graph
 
 /**
- * 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.
+ * Quickly check whether the on-disk directory at `dir` already holds an initialised cero
+ * identity (i.e. a stored master seed).
  *
  * @param {string} dir   Cero data directory.
  * @param {any} spec     Built spec — same value passed to `cero(dir, spec)`.
@@ -23,8 +20,7 @@ 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')
 
-  // Construct first (cheap), ready inside the try — a corrupt dir that throws in
-  // any ready() must still close root + store + local, not leak the storage lock.
+  // construct first, ready inside the try: a corrupt dir must still close everything
   const root = new HypercoreStorage(`${dir}/main`)
   const store = new Corestore(root, { manifestVersion: 2 })
   const local = new Local(null, spec, { store })

package/src/lib/refs.js

@@ -0,0 +1,46 @@
+import { CeroError } from '@cero-base/core/errors'
+
+/**
+ * @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`.
+ */
+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`, so callers
+   * write `handle.someRef` instead of looking refs up by name.
+   *
+   * @param {any} target
+   * @param {Record<string, RefInfo>} refs
+   */
+  static attach(target, refs) {
+    for (const [name, info] of Object.entries(refs || {})) {
+      // a ref named like a reserved member must fail loud, not overwrite it
+      if (name in target) {
+        throw CeroError.INVALID(
+          `schema ref '${name}' collides with a reserved ${target.constructor?.name || 'handle'} member — rename it`
+        )
+      }
+      target[name] = new Ref(target, name, info.kind, info.schema)
+    }
+  }
+}

package/src/lib/spec.js

@@ -1,6 +1,5 @@
 /**
- * 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.
+ * 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/local/index.js

@@ -3,7 +3,7 @@ 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'
+import { Ref } from '../lib/refs.js'
 
 /**
  * @typedef {object} LocalOpts
@@ -13,9 +13,8 @@ import { attachRefs } from '../lib/utils.js'
  */
 
 /**
- * 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.
+ * Per-device, single-writer storage for cero — holds the master seed, device keypair and
+ * any per-handle keypairs.
  */
 export class Local extends ReadyResource {
   /**
@@ -43,7 +42,7 @@ export class Local extends ReadyResource {
 
   async _open() {
     await this.store.ready()
-    attachRefs(this, this.store.refs)
+    Ref.attach(this, this.store.refs)
   }
 
   async _close() {

package/src/rpc/client.js

@@ -4,7 +4,7 @@ import c from 'compact-encoding'
 import z32 from 'z32'
 import { decodeId } from '@cero-base/core/blobs/codec'
 
-import { attachRefs } from '../lib/utils.js'
+import { Ref } from '../lib/refs.js'
 import {
   put,
   set,
@@ -12,6 +12,7 @@ import {
   del,
   count,
   watch,
+  changes,
   call,
   open,
   rotate,
@@ -20,7 +21,7 @@ import {
 } from '../lib/operators.js'
 import { t, schema } from '../lib/spec.js'
 
-export { put, set, get, del, count, watch, call, open, rotate, bind, define, t, schema }
+export { put, set, get, del, count, watch, changes, call, open, rotate, bind, define, t, schema }
 
 /**
  * @typedef {import('@cero-base/core/rpc').RPCClient} BaseRPCClient
@@ -29,7 +30,7 @@ export { put, set, get, del, count, watch, call, open, rotate, bind, define, t,
  * @property {'single'|'collection'|'action'|'handle'} [kind]
  * @property {string} [schema]
  * @property {string} [type]
- * @property {boolean} [builtin]
+ * @property {boolean} [internal]
  *
  * @typedef {import('@cero-base/core/rpc').Spec & { meta: { ns?: string, refs: Record<string, RefInfo>, local?: { refs: Record<string, RefInfo> }, handles?: Record<string, Spec> }, handles: Record<string, Spec> }} Spec  Built cero spec (schema + rpc + per-handle child specs).
  *
@@ -47,7 +48,6 @@ export { put, set, get, del, count, watch, call, open, rotate, bind, define, t,
  * @property {string|null} name
  */
 
-// Compact-encoding blobId struct matching hypercore-blob-server's wire format.
 const blobIdEnc = {
   preencode(state, b) {
     c.uint.preencode(state, b.blockOffset)
@@ -71,9 +71,7 @@ const blobIdEnc = {
   }
 }
 
-// Mixin applied to Client, Handle and LocalRefs so they expose the same
-// row-ops surface as a local cero handle but routed over the wire. `_local`
-// selects the per-device store + JSON codec; main refs use the schema codec.
+// the same row-ops surface as a local handle, routed over the wire
 const operators = {
   _local: false,
 
@@ -112,9 +110,8 @@ const operators = {
   },
 
   /**
-   * Augment a decoded row (or array of rows) to resolve file-typed fields to
-   * `{ id, type, size, url }` objects. The `files` builtin's own `id` is the
-   * file id; other refs declare file fields in `meta.refs[name].files`.
+   * Augment a decoded row (or array of rows) to resolve file-typed fields to `{ id, type,
+   * size, url }` objects.
    *
    * @param {string} name
    * @param {any} data
@@ -129,7 +126,7 @@ const operators = {
 
   _resolveRow(name, info, row) {
     if (!row || typeof row !== 'object') return row
-    if (info?.builtin && info?.verb === 'file') {
+    if (info?.internal && info?.verb === 'file') {
       if (!row.id) return row
       try {
         const { type, blobId } = decodeId(row.id)
@@ -317,15 +314,14 @@ const operators = {
     wire.on('end', end)
     wire.on('close', end)
     // the channel tears the stream down on client close — that is an end,
-    // not a failure (bare-rpc ≥1.3.2 errors every in-flight op on teardown)
+    // not a failure
     wire.on('error', (err) => (err.code === 'CHANNEL_CLOSED' ? end() : out.destroy(err)))
     return out
   },
 
   /**
-   * Delta subscription over the wire — same contract as the local operator:
-   * batches of `{ prev, next }` with file fields resolved, `reset` marks
-   * a full replay. Lossless: server-side the cursor folds under backpressure.
+   * Delta subscription over the wire — same contract as the local operator: batches of `{
+   * prev, next }` with file fields resolved, `reset` marks a full replay.
    */
   changes(name, query) {
     const refInfo = this._refInfo(name)
@@ -357,8 +353,7 @@ const operators = {
     }
     pump().catch((err) => {
       if (out.destroyed) return
-      // the server tears the stream down on handle close, and the channel on
-      // client close — both are ends, not failures (same contract as watch)
+      // both are ends, not failures
       if (err.code === 'PREMATURE_CLOSE' || err.code === 'CHANNEL_CLOSED') out.push(null)
       else out.destroy(err)
     })
@@ -434,10 +429,7 @@ export async function restore(me, phrase) {
 }
 
 /**
- * Per-device `local`-namespace surface on a Client. Exposes each app-defined
- * local ref (e.g. `client.local.settings`) and routes ops over RPC with
- * `local: true`, so they hit the server's per-device store and never
- * replicate. Built-in local refs (identity master/keypair) are not exposed.
+ * Per-device `local`-namespace surface on a Client.
  */
 class LocalRefs {
   /** @param {Client} client */
@@ -448,8 +440,8 @@ class LocalRefs {
     this.store = this
     this._local = true
     const refs = client.spec.meta.local?.refs || {}
-    const exposed = Object.fromEntries(Object.entries(refs).filter(([, info]) => !info.builtin))
-    attachRefs(this, exposed)
+    const exposed = Object.fromEntries(Object.entries(refs).filter(([, info]) => !info.internal))
+    Ref.attach(this, exposed)
   }
 
   /** Underlying RPC channel borrowed from the parent. */
@@ -464,9 +456,9 @@ class LocalRefs {
 }
 
 /**
- * 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.
+ * 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 {
   /**
@@ -491,7 +483,7 @@ export class Client extends RPCClient {
     this._fileBase = fileBase || ''
     this._fileToken = fileToken || ''
     this.identity = { id, toPhrase: async () => (await this.rpc.seed({})).phrase || null }
-    attachRefs(this, /** @type {Spec} */ (this.spec).meta.refs)
+    Ref.attach(this, /** @type {Spec} */ (this.spec).meta.refs)
     bind(this, null)
     if (/** @type {Spec} */ (this.spec).meta.local?.refs) this.local = new LocalRefs(this)
   }
@@ -504,7 +496,7 @@ export class Client extends RPCClient {
    * @returns {Promise<Handle>}
    */
   async _create(type, opts = {}) {
-    // `routes` are functions and can't cross the wire; role/accept now do.
+    // routes are functions and cannot cross the wire
     const wire = { ...opts, noAccept: opts.accept === false || undefined }
     const stub = await this.rpc.addHandle({
       ref: type,
@@ -540,9 +532,9 @@ export class Client extends RPCClient {
 }
 
 /**
- * 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.
+ * 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 {
   /**
@@ -560,7 +552,7 @@ class Handle {
     this.spec = /** @type {Spec} */ (parent.spec).handles[type]
     if (!this.spec.codec) bindCodec(this.spec)
     this.store = this
-    attachRefs(this, this.spec.meta.refs)
+    Ref.attach(this, this.spec.meta.refs)
     bind(this, this.type)
   }
 
@@ -594,13 +586,8 @@ export async function connect(ipc, spec) {
 }
 
 /**
- * Symmetric client entry. Mirrors the main `cero`, but `cero(ipc, spec)` connects
- * to a server (via `connect`) instead of opening a local store. The same operator
- * surface is attached, so `import { cero } from '@cero-base/cero/client'` works
- * just like `import { cero } from '@cero-base/cero'`.
- *
- * Note: `before`/`after`/`peek` are intentionally not exposed here — they hook the
- * local write path / probe a local store, which a client proxy has no notion of.
+ * Symmetric client entry. Mirrors the main `cero`, but `cero(ipc, spec)` connects to a
+ * server (via `connect`) instead of opening a local store.
  *
  * @param {any} ipc    Framed IPC duplex stream.
  * @param {any} spec   Built cero spec.
@@ -618,6 +605,7 @@ cero.get = get
 cero.del = del
 cero.count = count
 cero.watch = watch
+cero.changes = changes
 cero.call = call
 cero.open = open
 cero.rotate = rotate

package/src/rpc/index.js

@@ -1,7 +1,7 @@
 /**
- * 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.
+ * 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'