@cero-base/cero 1.18.2 → 2.0.0

package/src/rpc/server.js

@@ -12,7 +12,6 @@ import { put, set, get, del, count, watch, changes, call } from '../lib/operator
  *
  * @typedef {object} ServerOpts
  * @property {string} storage   Directory passed to `cero()` for the local store.
- * @property {object} spec      Compiled cero spec (schema + rpc + handles).
  * @property {string} [name]    Optional display name forwarded to `cero()`.
  * @property {Array<{ host: string, port: number }>} [bootstrap]  Custom DHT bootstrap.
  * @property {boolean} [isMobile]
@@ -28,19 +27,19 @@ 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 {
   /**
    * @param {any} ipc                Framed IPC stream (must be writable).
+   * @param {object} spec
    * @param {Partial<ServerOpts>} [opts]
    */
-  constructor(ipc, { storage, spec, ...opts } = {}) {
-    if (!storage) throw CeroError.REQUIRED('storage')
+  constructor(ipc, spec, { storage, ...opts } = {}) {
     if (!spec) throw CeroError.REQUIRED('spec')
+    if (!storage) throw CeroError.REQUIRED('storage')
     super(ipc, spec)
     if (spec.local?.schema && !spec.local.codec) bindCodec(spec.local)
     this.storage = storage
@@ -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 }
@@ -409,11 +397,12 @@ export class Server extends RPCServer {
  * Construct a `Server`, wait for it to be ready, and return it.
  *
  * @param {any} ipc
+ * @param {object} spec
  * @param {ServerOpts} opts
  * @returns {Promise<Server>}
  */
-export async function serve(ipc, opts) {
-  const server = new Server(ipc, opts)
+export async function serve(ipc, spec, opts) {
+  const server = new Server(ipc, spec, opts)
   await server.ready()
   return server
 }

package/types/build/index.d.ts

@@ -1,10 +1,5 @@
-export function build(specDir: any, schema: any, { ns, extensions }?: {
-    ns?: string;
-    extensions?: boolean;
-}): Promise<void>;
-export { getHyperdbType } from "./builtins.js";
-export type Schema = import("@cero-base/core/schema").Schema;
-export type SchemaDefs = import("@cero-base/core/schema").SchemaDefs;
+export type Schema = import('@cero-base/core/schema').Schema;
+export type SchemaDefs = import('@cero-base/core/schema').SchemaDefs;
 export type SchemaInput = Schema | (SchemaDefs & {
     local?: SchemaDefs;
 });
@@ -14,3 +9,20 @@ export type BuildOpts = {
      */
     ns?: string;
 };
+/**
+ * @typedef {import('@cero-base/core/schema').Schema} Schema
+ * @typedef {import('@cero-base/core/schema').SchemaDefs} SchemaDefs
+ * @typedef {Schema | (SchemaDefs & { local?: SchemaDefs })} SchemaInput
+ *
+ * @typedef {object} BuildOpts
+ * @property {string} [ns]  Namespace prefix for emitted schema ids. Defaults to `'cero'`.
+ */
+/**
+ * Compile a cero schema into wire-level artifacts and write them to disk.
+ *
+ * @param {string} specDir          Output directory.
+ * @param {SchemaInput} schema      Either a `schema(...)` wrapper or its raw defs object.
+ * @param {BuildOpts} [opts]
+ * @returns {Promise<void>}
+ */
+export declare function build(specDir: string, schema: SchemaInput, { ns, extensions }?: BuildOpts): Promise<void>;

package/types/build/internal.d.ts

@@ -0,0 +1,78 @@
+export declare const defs: {
+    main: {
+        members: {
+            type: string;
+        };
+        devices: {
+            type: string;
+        };
+        invites: {
+            type: string;
+        };
+        handles: {
+            type: string;
+        };
+        files: {
+            type: string;
+        };
+    };
+    local: {
+        master: {
+            type: string;
+            kind: string;
+        };
+        keypair: {
+            type: string;
+            kind: string;
+        };
+        'handle-keypairs': {
+            type: string;
+        };
+        environment: {
+            type: string;
+            kind: string;
+        };
+    };
+};
+export declare function fields(map: any): {
+    name: string;
+    type: any;
+    required: boolean;
+}[];
+export declare function types(scope: any, extend?: {}): {
+    name: string;
+    compact: boolean;
+    fields: {
+        name: string;
+        type: any;
+        required: boolean;
+    }[];
+}[];
+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 dispatches(ns: any): {
+    name: string;
+    requestType: string;
+}[];
+export declare function commands(ns: any): {
+    name: string | boolean;
+    request: {
+        name: string;
+    };
+    response: {
+        name: string;
+        stream: string | true;
+    };
+}[];

package/types/build/schemas.d.ts

@@ -1,4 +1,4 @@
-export const main: {
+export declare const main: {
     'del-by-id': {
         id: import("@cero-base/core").Prim;
     };
@@ -80,7 +80,7 @@ export const main: {
         stamp: import("@cero-base/core").Prim;
     };
 };
-export const local: {
+export declare const local: {
     master: {
         seed: import("@cero-base/core").Prim;
     };
@@ -98,7 +98,7 @@ export const local: {
         channel: import("@cero-base/core").Prim;
     };
 };
-export const rpc: {
+export declare const rpc: {
     'req-empty': {
         ok: import("@cero-base/core").Prim;
     };

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

@@ -1,22 +1,17 @@
 /**
- * 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]
  */
-export function handleSync({ fields }?: {
+export declare function handleSync({ fields }?: {
     fields?: Record<string, any>;
 }): {
     name: string;
     bundled: boolean;
     schema: {
         handles: {
-            kind: "extend";
+            kind: 'extend';
             fields: Record<string, import("@cero-base/core").Prim>;
         };
     };

package/types/extensions/index.d.ts

@@ -1,2 +1,24 @@
-export * from "./profile-sync.js";
-export * from "./handle-sync.js";
+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,13 +1,9 @@
 /**
  * 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]
  */
-export function profileSync({ fields }?: {
+export declare function profileSync({ fields }?: {
     fields?: Record<string, any>;
 }): {
     name: string;
@@ -15,7 +11,7 @@ export function profileSync({ fields }?: {
     schema: {
         profile: import("@cero-base/core").TypeDef;
         members: {
-            kind: "extend";
+            kind: 'extend';
             fields: Record<string, import("@cero-base/core").Prim>;
         };
     };