@cero-base/cero 1.19.0 → 2.0.0

package/src/rpc/client.js

@@ -30,7 +30,7 @@ export { put, set, get, del, count, watch, changes, call, open, rotate, bind, de
  * @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).
  *
@@ -48,7 +48,6 @@ export { put, set, get, del, count, watch, changes, call, open, rotate, bind, de
  * @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)
@@ -72,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,
 
@@ -113,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
@@ -130,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)
@@ -318,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)
@@ -358,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)
     })
@@ -435,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 */
@@ -449,7 +440,7 @@ 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))
+    const exposed = Object.fromEntries(Object.entries(refs).filter(([, info]) => !info.internal))
     Ref.attach(this, exposed)
   }
 
@@ -465,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 {
   /**
@@ -505,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,
@@ -541,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 {
   /**
@@ -595,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.

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'

package/src/rpc/server.js

@@ -27,10 +27,9 @@ import { put, set, get, del, count, watch, changes, call } from '../lib/operator
  */
 
 /**
- * IPC-side RPC server for cero. Bridges an `hrpc` channel to a live
- * `Handle` tree: lazy-initializes the root via `cero()` on the first
- * `init` call, then exposes data ops, pairing, and handle lifecycle
- * over the wire using the spec-bound codec.
+ * IPC-side RPC server for cero. Bridges an `hrpc` channel to a live `Handle` tree:
+ * lazy-initializes the root via `cero()` on the first `init` call, then exposes data ops,
+ * pairing, and handle lifecycle.
  */
 export class Server extends RPCServer {
   /**
@@ -52,14 +51,6 @@ export class Server extends RPCServer {
     this._wireInit()
   }
 
-  /** End every watch stream bound to a handle (e.g. when it closes or leaves). */
-  _endWatches(handle) {
-    const set = this._watchStreams.get(handle)
-    if (!set) return
-    for (const s of set) s.destroy()
-    this._watchStreams.delete(handle)
-  }
-
   /**
    * Root cero id (null until `init` has run).
    *
@@ -87,6 +78,14 @@ export class Server extends RPCServer {
     await super._close()
   }
 
+  /** End every watch stream bound to a handle (e.g. when it closes or leaves). */
+  _endWatches(handle) {
+    const set = this._watchStreams.get(handle)
+    if (!set) return
+    for (const s of set) s.destroy()
+    this._watchStreams.delete(handle)
+  }
+
   /** Wire the `init` handler that lazily constructs the root cero handle. */
   _wireInit() {
     this.rpc.onInit(async () => {
@@ -147,7 +146,7 @@ export class Server extends RPCServer {
         r.kind === 'single'
           ? codec.encodeRow(r.schema, result.data)
           : codec.encodeRows(r.schema, result.data)
-      // total is int on the wire: -1 encodes "skipped" (null), see T2.1 lazy total
+      // total is int on the wire: -1 encodes null
       return { data, total: result.total ?? -1, size: result.size ?? 0 }
     })
 
@@ -175,17 +174,13 @@ export class Server extends RPCServer {
         ;({ ref: r, codec } = this._refOf(handle, ref, local))
         live = watch(r, codec.decodeQuery(query))
       } catch (err) {
-        // Forward the error to the client over the wire by destroying the
-        // underlying response stream with it (emits a CLOSE|ERROR frame). The
-        // local RPCStream's 'error' is swallowed so it doesn't crash the server.
+        // forward the error over the wire by destroying the response stream with it
         stream.once('error', () => {})
         stream.writeStream.destroy(err)
         stream.destroy()
         return
       }
-      // keep-latest under IPC backpressure: snapshots are idempotent, so an
-      // un-drained wire holds one pending snapshot (newest wins) instead of
-      // queueing every intermediate result set — encode only what ships
+      // keep-latest under backpressure: snapshots are idempotent
       let pending = null
       let blocked = false
       const onData = (snap) => {
@@ -212,8 +207,7 @@ export class Server extends RPCServer {
       if (!set) this._watchStreams.set(handle, (set = new Set()))
       set.add(stream)
       live.on('data', onData)
-      // channel teardown destroys the stream with CHANNEL_CLOSED — 'close'
-      // below does the cleanup; the error itself must not crash the server
+      // channel teardown destroys the stream with CHANNEL_CLOSED; 'close' cleans up
       stream.on('error', safetyCatch)
       stream.on('close', () => {
         live.off('data', onData)
@@ -237,8 +231,7 @@ export class Server extends RPCServer {
       let set = this._watchStreams.get(handle)
       if (!set) this._watchStreams.set(handle, (set = new Set()))
       set.add(stream)
-      // no keep-latest: delta batches are not idempotent — hold the iteration
-      // on wire backpressure instead; the cursor folds everything missed
+      // deltas are not idempotent: hold the iteration on backpressure instead
       const pump = async () => {
         for await (const batch of live) {
           const ok = stream.write({
@@ -282,13 +275,10 @@ export class Server extends RPCServer {
       return { ok }
     })
 
-    // specs built before rotation have no rotate command
-    if (typeof this.rpc.onRotate === 'function') {
-      this.rpc.onRotate(async ({ handle }) => {
-        const { epoch } = await this._resolve(handle).store.rotate()
-        return { epoch }
-      })
-    }
+    this.rpc.onRotate(async ({ handle }) => {
+      const { epoch } = await this._resolve(handle).store.rotate()
+      return { epoch }
+    })
 
     this.rpc.onJoin(async ({ parent, ref, invite }) => {
       if (this._resolve(parent) !== this.me) throw CeroError.UNSUPPORTED('nested handles')
@@ -306,7 +296,7 @@ export class Server extends RPCServer {
       const info = parent.spec.meta.refs?.[ref] || parent.spec.handles?.[ref]
       if (!info) throw CeroError.UNKNOWN('handle type', ref)
       const wire = parent.spec.codec.decodeCreate(data) || {}
-      // routes can't cross the wire (functions) — both sides register them via define()
+      // routes are functions and cannot cross the wire
       const opts = { name: wire.name, role: wire.role, accept: wire.noAccept ? false : undefined }
       const child = await this.me._create(ref, opts)
       const id = child.id
@@ -358,9 +348,7 @@ export class Server extends RPCServer {
   }
 
   /**
-   * Resolve a `{ handle, ref }` pair to its `Ref` and codec. When `local` is
-   * set, the ref is resolved against the root's per-device `local` store and
-   * paired with the codec bound from the local schema.
+   * Resolve a `{ handle, ref }` pair to its `Ref` and codec.
    *
    * @param {string} id
    * @param {string} name
@@ -370,7 +358,7 @@ export class Server extends RPCServer {
   _refOf(id, name, local) {
     if (local) {
       const info = this.spec.meta.local?.refs?.[name]
-      if (!info || info.builtin) throw CeroError.UNKNOWN('local ref', name)
+      if (!info || info.internal) throw CeroError.UNKNOWN('local ref', name)
       const r = this.me.local?.[name]
       if (!r) throw CeroError.UNKNOWN('local ref', name)
       return { ref: r, codec: this.spec.local.codec }

package/types/build/index.d.ts

@@ -20,17 +20,9 @@ export type BuildOpts = {
 /**
  * Compile a cero schema into wire-level artifacts and write them to disk.
  *
- * Emits a `main/` tree (schema + hyperdb + dispatch + rpc), a `local/` tree
- * for per-device data, one `handles/<name>/` tree per child handle type, and
- * an `index.js` that re-exports a ready-to-use `spec` object.
- *
  * @param {string} specDir          Output directory.
  * @param {SchemaInput} schema      Either a `schema(...)` wrapper or its raw defs object.
  * @param {BuildOpts} [opts]
  * @returns {Promise<void>}
  */
-export { getHyperdbType } from './builtins.js';
-export declare function build(specDir: any, schema: any, { ns, extensions }?: {
-    extensions?: boolean;
-    ns?: string;
-}): Promise<void>;
+export declare function build(specDir: string, schema: SchemaInput, { ns, extensions }?: BuildOpts): Promise<void>;

package/types/build/{builtins.d.ts → internal.d.ts}

@@ -1,4 +1,4 @@
-export declare const refs: {
+export declare const defs: {
     main: {
         members: {
             type: string;
@@ -34,26 +34,12 @@ export declare const refs: {
         };
     };
 };
-export declare function getHyperdbType(prim: any): any;
-export declare function builtinRefs(ns: any, scope: any): {
-    [k: string]: {
-        kind: any;
-        path: string[];
-        builtin: boolean;
-        verb: any;
-        schema: string;
-    };
-};
-export declare function builtinTypes(scope: any, extend: any): {
+export declare function fields(map: any): {
     name: string;
-    compact: boolean;
-    fields: {
-        name: string;
-        type: any;
-        required: boolean;
-    }[];
+    type: any;
+    required: boolean;
 }[];
-export declare function rpcTypes(): {
+export declare function types(scope: any, extend?: {}): {
     name: string;
     compact: boolean;
     fields: {
@@ -62,35 +48,31 @@ export declare function rpcTypes(): {
         required: boolean;
     }[];
 }[];
-export declare function builtinCollections(ns: any, scope: any): {
+export declare function refs(ns: any, scope: any): {
+    [k: string]: {
+        kind: any;
+        path: string[];
+        internal: boolean;
+        verb: any;
+        schema: string;
+    };
+};
+export declare function collections(ns: any, scope: any): {
     name: string;
     schema: string;
     key: string[];
 }[];
-export declare function builtinDispatches(ns: any): {
+export declare function dispatches(ns: any): {
     name: string;
     requestType: string;
 }[];
-export declare function rotateDispatch(ns: any): {
-    name: string;
-    requestType: string;
-};
-export declare function rpcCommands(ns: any): ({
-    name: string;
+export declare function commands(ns: any): {
+    name: string | boolean;
     request: {
         name: string;
     };
     response: {
         name: string;
-        stream?: undefined;
+        stream: string | true;
     };
-} | {
-    name: string;
-    request: {
-        name: string;
-    };
-    response: {
-        name: string;
-        stream: boolean;
-    };
-})[];
+}[];

package/types/extensions/handle-sync.d.ts

@@ -1,11 +1,6 @@
 /**
- * Mirror a child handle's `profile` (name + avatar) onto its row in the parent's
- * `handles` list — so a handle list shows names + avatars without opening each
- * one. Adds the synced `fields` to the `handle` builtin.
- *
- * On create it seeds the handle's `profile.name` from the open `{ name }`, then
- * reflects the (app-owned) `profile` onto the row. Requires your handle types to
- * declare a `profile` single — handles without one are left untouched.
+ * Mirror a child handle's `profile` (name + avatar) onto its row in the parent's `handles`
+ * list — so a handle list shows names + avatars without opening each one.
  *
  * @param {{ fields?: Record<string, any> }} [opts]
  */

package/types/extensions/index.d.ts

@@ -1,2 +1,24 @@
 export * from './profile-sync.js';
 export * from './handle-sync.js';
+export declare const registry: ({
+    name: string;
+    bundled: boolean;
+    schema: {
+        profile: import("@cero-base/core").TypeDef;
+        members: {
+            kind: 'extend';
+            fields: Record<string, import("@cero-base/core").Prim>;
+        };
+    };
+    setup(me: any): void;
+} | {
+    name: string;
+    bundled: boolean;
+    schema: {
+        handles: {
+            kind: 'extend';
+            fields: Record<string, import("@cero-base/core").Prim>;
+        };
+    };
+    setup(me: any): void;
+})[];

package/types/extensions/profile-sync.d.ts

@@ -1,9 +1,5 @@
 /**
  * Mirror your `profile` onto your `member` row in every handle you're in.
- * Declares a `profile` single (`name`, `avatar`, plus any extra `fields`) and
- * mirrors them onto the `member` builtin, then publishes when you open/join a
- * handle and whenever your profile changes. An app may declare its own richer
- * `profile` instead — the app schema wins.
  *
  * @param {{ fields?: Record<string, any> }} [opts]
  */