@cero-base/cero 2.0.0 → 2.1.0

package/types/index.d.ts

@@ -1,12 +1,11 @@
 import { Identity } from '@cero-base/core/identity';
 import { Handle, Ref } from './handle/index.js';
 import { Local } from './local/index.js';
-import { put, set, get, del, count, watch, changes, call, open, rotate, before, after, bind, define } from './lib/operators.js';
+import { put, set, get, del, watch, changes, call, open, rotate, before, after } from './lib/operators.js';
 import { peek } from './lib/peek.js';
 import { t, schema } from './lib/spec.js';
-import { registry } from './extensions/index.js';
 export { Handle, Ref, Local };
-export { put, set, get, del, count, watch, changes, call, open, rotate, before, after, bind, define } from './lib/operators.js';
+export { put, set, get, del, watch, changes, call, open, rotate, before, after } from './lib/operators.js';
 export { peek } from './lib/peek.js';
 export { t, schema } from './lib/spec.js';
 export type CeroHandle = import('./handle/index.js').CeroHandle;
@@ -54,6 +53,14 @@ export type CeroOpts = {
      * Blind-peer public keys. Rooms and files are mirrored through them so peers sync even when never online at the same time. Mirrors hold only encrypted blocks — they never read your data.
      */
     mirrors?: Array<string | Uint8Array>;
+    /**
+     * How many rooms search, how many only announce, and the idle ms before the rest leave the swarm.
+     */
+    presence?: {
+        active?: number;
+        announced?: number;
+        idle?: number;
+    };
     /**
      * Existing database key to recover into, skipping the pointer lookup.
      */
@@ -79,9 +86,13 @@ export type CeroOpts = {
      */
     storageKey?: Uint8Array;
     /**
-     * `false` disables the bundled extensions (profileSync, handleSync) for this instance. Build with `{ extensions: false }` too so the spec matches.
+     * The extensions this instance runs, instead of the ones the spec carries. Build with the same list.
+     */
+    extensions?: import('./extensions/index.js').Extension[];
+    /**
+     * The operators to bind, instead of the ones the spec carries.
      */
-    extensions?: boolean;
+    operators?: Record<string, any>;
     /**
      * `true` enables nearby (Bluetooth) sync via `me.bluetooth` (auto-started). `{ autoStart: false }` creates the facade without starting the radio — the app calls `me.bluetooth.start()`/`stop()` (user toggle). `backend` injects a bare-bluetooth-shaped backend (tests). `maxOutbound`/`maxInbound` cap concurrent outbound links and inbound sessions. `pipe` picks the data pipe — `'l2cap'` (default, faster) or `'gatt'`; both peers must match. Absent backend on an unsupported host → `me.bluetooth.state === 'unsupported'`.
      */
@@ -108,13 +119,15 @@ export type CeroOpts = {
  * @property {number[]} [backoffs]                     Swarm reconnect backoff tiers in ms (testing/tuning).
  * @property {string} [channel]                        Optional network-isolation label; only same-channel peers connect.
  * @property {Array<string | Uint8Array>} [mirrors]    Blind-peer public keys. Rooms and files are mirrored through them so peers sync even when never online at the same time. Mirrors hold only encrypted blocks — they never read your data.
+ * @property {{ active?: number, announced?: number, idle?: number }} [presence]  How many rooms search, how many only announce, and the idle ms before the rest leave the swarm.
  * @property {Uint8Array} [key]                        Existing database key to recover into, skipping the pointer lookup.
  * @property {Uint8Array} [encryptionKey]              Pre-existing encryption key.
  * @property {Record<string, Function>} [routes]       Custom RPC routes for the database dispatcher.
  * @property {(err: any) => void} [onerror]            Background-task error handler.
  * @property {number} [recoveryTimeout]                Max wait to find another device and be admitted, in ms. Defaults to 30000.
  * @property {Uint8Array} [storageKey]                 32-byte key encrypting local key material (master seed, device keypairs) at rest. Source it from the OS keychain — cero never stores it.
- * @property {boolean} [extensions]                    `false` disables the bundled extensions (profileSync, handleSync) for this instance. Build with `{ extensions: false }` too so the spec matches.
+ * @property {import('./extensions/index.js').Extension[]} [extensions]  The extensions this instance runs, instead of the ones the spec carries. Build with the same list.
+ * @property {Record<string, any>} [operators]  The operators to bind, instead of the ones the spec carries.
  * @property {boolean | { autoStart?: boolean, backend?: any, maxOutbound?: number, maxInbound?: number, pipe?: 'l2cap' | 'gatt' }} [bluetooth]  `true` enables nearby (Bluetooth) sync via `me.bluetooth` (auto-started). `{ autoStart: false }` creates the facade without starting the radio — the app calls `me.bluetooth.start()`/`stop()` (user toggle). `backend` injects a bare-bluetooth-shaped backend (tests). `maxOutbound`/`maxInbound` cap concurrent outbound links and inbound sessions. `pipe` picks the data pipe — `'l2cap'` (default, faster) or `'gatt'`; both peers must match. Absent backend on an unsupported host → `me.bluetooth.state === 'unsupported'`.
  */
 /**
@@ -132,7 +145,6 @@ export declare namespace cero {
     export { set };
     export { get };
     export { del };
-    export { count };
     export { watch };
     export { changes };
     export { call };
@@ -143,10 +155,6 @@ export declare namespace cero {
     export { peek };
     export { restore };
     export { schema };
-    export { bind };
-    export { define };
-    export { registry as _registry };
-    export var use: (...exts: any[]) => void;
 }
 /**
  * Restore a cero instance from a mnemonic phrase.

package/types/lib/operators.d.ts

@@ -1,4 +1,5 @@
 export type Ref = import('./refs.js').Ref;
+export type HookContext = import('@cero-base/core/database').HookContext;
 export type CeroHandle = import('../handle/index.js').CeroHandle;
 export type SingleResult = {
     data: any;
@@ -13,6 +14,7 @@ export type GetByIdResult = {
 };
 /**
  * @typedef {import('./refs.js').Ref} Ref
+ * @typedef {import('@cero-base/core/database').HookContext} HookContext
  * @typedef {import('../handle/index.js').CeroHandle} CeroHandle
  * @typedef {{ data: any }} SingleResult
  * @typedef {{ data: any[], total: number, size: number }} ListResult
@@ -61,16 +63,6 @@ export declare function set(ref: Ref, row: Record<string, any>, opts?: {
  * @returns {Promise<void>}
  */
 export declare function del(ref: Ref, id?: string): Promise<void>;
-/**
- * Count rows on `ref`, optionally filtered.
- *
- * @param {Ref} ref
- * @param {Record<string, any>} [q]
- * @returns {Promise<{ data: number }>}
- */
-export declare function count(ref: Ref, q?: Record<string, any>): Promise<{
-    data: number;
-}>;
 /**
  * Invoke an `action`-kind ref (a custom mutation declared in the schema).
  *
@@ -80,34 +72,35 @@ export declare function count(ref: Ref, q?: Record<string, any>): Promise<{
  */
 export declare function call(ref: Ref, d?: Record<string, any>): Promise<any>;
 /**
- * Intercept writes to `ref` before they commit — `fn(ctx)` runs in-path (awaited).
+ * Rule that runs before a write to `ref` lands — at apply, on every peer, inside the op's
+ * transaction. Return `false` to refuse it: the writer's own call rejects with `REFUSED`.
+ * `ctx` is `{ op, name, row, existing, id, memberId, role, get, put, set, del }`; mutate
+ * `ctx.row` to rewrite what is stored. `op` is the op as it applies, so an upsert on a
+ * collection is a `put`. The four operators on `ctx` read and write the room as it stands at
+ * this op, inside the transaction. Must be deterministic — read only `ctx`, never a clock or
+ * local state — and registered before any op applies, in the process that owns the data. The
+ * imported operators throw inside a hook; use the ones on `ctx`. Not available over RPC.
  *
  * @param {Ref} ref
- * @param {(ctx: { op: string, name: string, row: any }) => any} fn
+ * @param {(ctx: HookContext) => unknown} fn
  * @param {{ signal?: AbortSignal }} [opts]
  * @returns {() => void}
  */
-export declare function before(ref: Ref, fn: (ctx: {
-    op: string;
-    name: string;
-    row: any;
-}) => any, opts?: {
+export declare function before(ref: Ref, fn: (ctx: HookContext) => unknown, opts?: {
     signal?: AbortSignal;
 }): () => void;
 /**
- * Subscribe to writes on `ref` — fires after each committed write, non-blocking (observe
- * only).
+ * Rule that runs after a write to `ref` lands — at apply, on every peer, inside the op's
+ * transaction. Write derived rows through `ctx.put` / `ctx.set` / `ctx.del`; a throw refuses
+ * the whole op. Same `ctx` and the same determinism and registration rules as `before`. Use
+ * `changes(ref)` instead to observe writes locally.
  *
  * @param {Ref} ref
- * @param {(ctx: { op: string, name: string, row: any }) => void} fn
+ * @param {(ctx: HookContext) => unknown} fn
  * @param {{ signal?: AbortSignal }} [opts]
  * @returns {() => void}
  */
-export declare function after(ref: Ref, fn: (ctx: {
-    op: string;
-    name: string;
-    row: any;
-}) => void, opts?: {
+export declare function after(ref: Ref, fn: (ctx: HookContext) => unknown, opts?: {
     signal?: AbortSignal;
 }): () => void;
 /**
@@ -162,21 +155,3 @@ export declare function open(ref: Ref, arg?: string | {
 export declare function rotate(handle: any): Promise<{
     epoch: number;
 }>;
-/**
- * Put custom operators on `handle`, currying it as their first argument so
- * `handle.ns.fn(args)` calls `fn(handle, args)`.
- *
- * @param {any} handle
- * @param {Record<string, any> | string | null} arg
- * @returns {any} handle
- */
-export declare function bind(handle: any, arg: Record<string, any> | string | null): any;
-/**
- * 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
- */
-export declare function define(map: Record<string, any>): void;
-/** Test seam: clear all registered operators. */
-export declare function _clearDefined(): void;

package/types/lib/refs.d.ts

@@ -18,19 +18,21 @@ export declare class Ref {
     name: string;
     kind: string;
     schema: string;
+    type: any;
     /**
      * @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: any, name: string, kind: string, schema?: string | null);
+    constructor(handle: any, name: string, kind: string, schema?: string | null, type?: any);
     /**
      * 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
+     * @param {Record<string, any>} [handles]  The handle types, so `target.room.notes` names every room's notes.
      */
-    static attach(target: any, refs: Record<string, RefInfo>): void;
+    static attach(target: any, refs: Record<string, RefInfo>, handles?: Record<string, any>): void;
 }

package/types/rpc/client.d.ts

@@ -1,7 +1,7 @@
 import { RPCClient } from '@cero-base/core/rpc';
-import { put, set, get, del, count, watch, changes, call, open, rotate, bind, define } from '../lib/operators.js';
+import { put, set, get, del, watch, changes, call, open, rotate } from '../lib/operators.js';
 import { t, schema } from '../lib/spec.js';
-export { put, set, get, del, count, watch, changes, call, open, rotate, bind, define, t, schema };
+export { put, set, get, del, watch, changes, call, open, rotate, t, schema };
 export type BaseRPCClient = import('@cero-base/core/rpc').RPCClient;
 export type RefInfo = {
     kind?: 'single' | 'collection' | 'action' | 'handle';
@@ -70,6 +70,7 @@ declare class LocalRefs {
  * across the wire.
  */
 export declare class Client extends RPCClient {
+    operators: Record<string, any>;
     id: any;
     deviceId: any;
     store: this;
@@ -83,9 +84,16 @@ export declare class Client extends RPCClient {
     /**
      * @param {any} ipc   Framed IPC stream (must be writable).
      * @param {Spec} spec  Compiled cero spec (schema + rpc + handles).
+     * @param {{ operators?: Record<string, any> }} [opts]  The operators to bind, instead of the ones the spec carries.
      */
-    constructor(ipc: any, spec: Spec);
+    constructor(ipc: any, spec: Spec, opts?: {
+        operators?: Record<string, any>;
+    });
     _open(): Promise<void>;
+    /** Pause networking and storage on the server. Idempotent. */
+    suspend(): Promise<void>;
+    /** Resume a suspended server. Idempotent. */
+    resume(): Promise<void>;
     /**
      * Create a new child handle of the given type.
      *
@@ -142,18 +150,24 @@ declare class Handle {
  *
  * @param {any} ipc
  * @param {object} spec
+ * @param {{ operators?: Record<string, any> }} [opts]
  * @returns {Promise<Client>}
  */
-export declare function connect(ipc: any, spec: object): Promise<Client>;
+export declare function connect(ipc: any, spec: object, opts?: {
+    operators?: Record<string, any>;
+}): Promise<Client>;
 /**
  * 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.
+ * @param {{ operators?: Record<string, any> }} [opts]
  * @returns {Promise<Client>}
  */
-export declare function cero(ipc: any, spec: any): Promise<Client>;
+export declare function cero(ipc: any, spec: any, opts?: {
+    operators?: Record<string, any>;
+}): Promise<Client>;
 export declare namespace cero {
     export { connect };
     export { restore };
@@ -162,13 +176,10 @@ export declare namespace cero {
     export { set };
     export { get };
     export { del };
-    export { count };
     export { watch };
     export { changes };
     export { call };
     export { open };
     export { rotate };
-    export { bind };
-    export { define };
     export { schema };
 }

package/types/rpc/server.d.ts

@@ -101,7 +101,7 @@ export declare class Server extends RPCServer {
     _wireInit(): void;
     /** Wire the `restore` handler that rebuilds the local store from a phrase. */
     _wireRestore(): void;
-    /** 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(): void;
     /** Register invite/revoke/join RPC handlers. */
     _wirePairing(): void;