@cero-base/cero 1.19.0 → 2.1.0

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

@@ -5,7 +5,7 @@ import { CeroError } from '@cero-base/core/errors'
 import { encodeId } from '@cero-base/core/blobs/codec'
 
 import { cero, restore } from '../index.js'
-import { put, set, get, del, count, watch, changes, call } from '../lib/operators.js'
+import { put, set, get, del, watch, changes, call } from '../lib/operators.js'
 
 /**
  * @typedef {import('@cero-base/core/rpc').RPCServer} BaseRPCServer
@@ -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 () => {
@@ -113,7 +112,7 @@ export class Server extends RPCServer {
     })
   }
 
-  /** Register the row-level RPC handlers (put/set/get/del/count/watch/call). */
+  /** Register the row-level RPC handlers (put/set/get/del/watch/call). */
   _wireData() {
     this.rpc.onAddFile(async ({ handle, data, name, type }) => {
       const h = this._resolve(handle)
@@ -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 }
     })
 
@@ -162,12 +161,6 @@ export class Server extends RPCServer {
       return {}
     })
 
-    this.rpc.onCount(async ({ handle, ref, query, local }) => {
-      const { ref: r, codec } = this._refOf(handle, ref, local)
-      const { data } = await count(r, codec.decodeQuery(query))
-      return { count: data }
-    })
-
     this.rpc.onWatch((stream) => {
       const { handle, ref, query, local } = stream.data
       let r, codec, live
@@ -175,17 +168,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 +201,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 +225,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 +269,25 @@ 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.onSetActive(({ handle, active }) => {
+      this._resolve(handle).setActive(active)
+      return {}
+    })
+
+    this.rpc.onSuspend(async () => {
+      await this.me.suspend()
+      return {}
+    })
+
+    this.rpc.onResume(async () => {
+      await this.me.resume()
+      return {}
+    })
 
     this.rpc.onJoin(async ({ parent, ref, invite }) => {
       if (this._resolve(parent) !== this.me) throw CeroError.UNSUPPORTED('nested handles')
@@ -306,7 +305,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 +357,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 +367,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

@@ -8,6 +8,14 @@ export type BuildOpts = {
      * Namespace prefix for emitted schema ids. Defaults to `'cero'`.
      */
     ns?: string;
+    /**
+     * The extensions to fold in. A module specifier, relative to `specDir`, is imported here for its `extensions` export and written into the spec, so every process runs the same list. A list is folded in only. The bundled two by default, `[]` for none.
+     */
+    extensions?: string | import('../extensions/index.js').Extension[];
+    /**
+     * A module specifier, relative to `specDir`, written into the spec for its `operators` export, so every process binds the same map.
+     */
+    operators?: string;
 };
 /**
  * @typedef {import('@cero-base/core/schema').Schema} Schema
@@ -16,21 +24,15 @@ export type BuildOpts = {
  *
  * @typedef {object} BuildOpts
  * @property {string} [ns]  Namespace prefix for emitted schema ids. Defaults to `'cero'`.
+ * @property {string | import('../extensions/index.js').Extension[]} [extensions]  The extensions to fold in. A module specifier, relative to `specDir`, is imported here for its `extensions` export and written into the spec, so every process runs the same list. A list is folded in only. The bundled two by default, `[]` for none.
+ * @property {string} [operators]  A module specifier, relative to `specDir`, written into the spec for its `operators` export, so every process binds the same map.
  */
 /**
  * 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, operators }?: 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/build/schemas.d.ts

@@ -151,6 +151,10 @@ export declare const rpc: {
     'req-handle': {
         handle: import("@cero-base/core").Prim;
     };
+    'req-set-active': {
+        handle: import("@cero-base/core").Prim;
+        active: import("@cero-base/core").Prim;
+    };
     'res-data': {
         data: import("@cero-base/core").Prim;
     };
@@ -163,9 +167,6 @@ export declare const rpc: {
         changes: import("@cero-base/core").Prim;
         reset: import("@cero-base/core").Prim;
     };
-    'res-count': {
-        count: import("@cero-base/core").Prim;
-    };
     'res-invite': {
         invite: import("@cero-base/core").Prim;
     };

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]
  */
@@ -13,7 +8,6 @@ export declare function handleSync({ fields }?: {
     fields?: Record<string, any>;
 }): {
     name: string;
-    bundled: boolean;
     schema: {
         handles: {
             kind: 'extend';

package/types/extensions/index.d.ts

@@ -1,2 +1,104 @@
+import { t, schema } from '../lib/spec.js';
+import * as operators from '../lib/operators.js';
 export * from './profile-sync.js';
 export * from './handle-sync.js';
+export { t, schema };
+export declare const put: typeof operators.put, set: typeof operators.set, get: typeof operators.get, del: typeof operators.del, watch: typeof operators.watch, changes: typeof operators.changes, call: typeof operators.call, open: typeof operators.open, rotate: typeof operators.rotate, before: typeof operators.before, after: typeof operators.after;
+export declare const cero: {
+    t: {
+        string: import("@cero-base/core").Prim;
+        uint: import("@cero-base/core").Prim;
+        int: import("@cero-base/core").Prim;
+        bool: import("@cero-base/core").Prim;
+        bytes: import("@cero-base/core").Prim;
+        json: import("@cero-base/core").Prim;
+        fixed32: import("@cero-base/core").Prim;
+        fixed64: import("@cero-base/core").Prim;
+        file: import("@cero-base/core").Prim;
+        required: (marker: import("@cero-base/core").Prim) => import("@cero-base/core").Prim;
+        single(fields: Record<string, import("@cero-base/core").Prim>): import("@cero-base/core").TypeDef;
+        collection(fields: Record<string, import("@cero-base/core").Prim>, opts?: {
+            indexes?: Record<string, string[]>;
+            own?: boolean;
+        }): import("@cero-base/core").TypeDef;
+        action(fields: Record<string, import("@cero-base/core").Prim>): import("@cero-base/core").TypeDef;
+        extend(fields: Record<string, import("@cero-base/core").Prim>): {
+            kind: 'extend';
+            fields: Record<string, import("@cero-base/core").Prim>;
+        };
+    };
+    schema: typeof schema;
+    put: typeof operators.put;
+    set: typeof operators.set;
+    get: typeof operators.get;
+    del: typeof operators.del;
+    watch: typeof operators.watch;
+    changes: typeof operators.changes;
+    call: typeof operators.call;
+    open: typeof operators.open;
+    rotate: typeof operators.rotate;
+    before: typeof operators.before;
+    after: typeof operators.after;
+};
+export type Extension = {
+    /**
+     * Refs to add, or `t.extend` on a builtin, nested by handle type like the app schema.
+     */
+    schema?: Record<string, any>;
+    /**
+     * Runs once the root is ready; a returned function runs on close.
+     */
+    setup?: (me: any) => any;
+};
+/**
+ * @typedef {object} Extension
+ * @property {Record<string, any>} [schema]  Refs to add, or `t.extend` on a builtin, nested by handle type like the app schema.
+ * @property {(me: any) => any} [setup]      Runs once the root is ready; a returned function runs on close.
+ */
+/** The two every app gets unless its build names a list. */
+export declare const bundled: ({
+    name: string;
+    schema: {
+        profile: import("@cero-base/core").TypeDef;
+        members: {
+            kind: 'extend';
+            fields: Record<string, import("@cero-base/core").Prim>;
+        };
+    };
+    setup(me: any): void;
+} | {
+    name: string;
+    schema: {
+        handles: {
+            kind: 'extend';
+            fields: Record<string, import("@cero-base/core").Prim>;
+        };
+    };
+    setup(me: any): void;
+})[];
+/**
+ * The extensions a spec carries, else the bundled two. A bare function is `{ setup }`.
+ *
+ * @param {any} spec
+ * @param {Array<any>} [override]
+ * @returns {Extension[]}
+ */
+export declare function extensionsOf(spec: any, override?: Array<any>): Extension[];
+/**
+ * The operators a spec carries: functions taking the handle first, keyed by namespace, a
+ * key naming a handle type holding that type's namespaces.
+ *
+ * @param {any} spec
+ * @param {Record<string, any>} [override]
+ * @returns {Record<string, any>}
+ */
+export declare function operatorsOf(spec: any, override?: Record<string, any>): Record<string, any>;
+/**
+ * Put the operators for `handle` on it: the root when `type` is null, else a child of `type`.
+ *
+ * @param {any} handle
+ * @param {string | null} type
+ * @param {Record<string, any>} operators
+ * @returns {any} handle
+ */
+export declare function bind(handle: any, type: string | null, operators: Record<string, any>): any;

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]
  */
@@ -11,7 +7,6 @@ export declare function profileSync({ fields }?: {
     fields?: Record<string, any>;
 }): {
     name: string;
-    bundled: boolean;
     schema: {
         profile: import("@cero-base/core").TypeDef;
         members: {