@cero-base/cero 0.8.5 → 0.8.6

package/README.md

@@ -191,6 +191,52 @@ cero.after(me.profile, ({ row }) => {
 
 `ctx` is `{ op, name, row }` (plus `result` in `after`).
 
+## Custom operators
+
+Your app's business logic lives as **custom operators** — plain functions whose first arg is the handle they act on, composing the built-ins. Because the built-ins resolve through the handle (a real DB on the core, an RPC proxy on the client), custom operators are symmetric over RPC for free.
+
+```js
+// guest.js — pure functions, one per export
+import { put, del } from '@cero-base/cero'
+import { ensureGuestId } from './ids.js'
+
+export const create = (room, data) => put(room.guests, { ...data, id: ensureGuestId(data.id) })
+export const remove = (room, id) => del(room.guests, id)
+```
+
+### `cero.define(map)`
+
+Register custom operators by **scope**, once, and cero puts them on every matching handle — the root and each child as it opens, on both the core and the client. A **bare key** binds on the root handle; a key that names a **child-handle type** binds on each handle of that type:
+
+```js
+import * as user from './user.js'
+import * as guest from './guest.js'
+import * as station from './station.js'
+
+cero.define({
+  user, // bound on the root  → me.user.rename(…)
+  room: { guest, station } // bound on each room → room.guest.create(…)
+})
+
+const room = await cero.open(me.room, { id })
+await room.guest.create({ name: 'Bob' }) // no binding at the call site
+```
+
+cero reads the spec to tell root namespaces from child-handle types, so there is no `root` wrapper. Call `cero.define(...)` once at startup — in the build/server process **and** the client — the same as extensions.
+
+### `cero.bind(handle, map)`
+
+The primitive `define` uses. Curry a handle onto a `{ ns: module }` map yourself — for a handle you opened manually, or to bind operators you don't want globally registered:
+
+```js
+import * as guest from './guest.js'
+
+cero.bind(room, { guest })
+await room.guest.create({ name: 'Bob' }) // → guest.create(room, …)
+```
+
+Non-functions in the map are skipped; the handle is returned.
+
 ## Extensions
 
 An extension bundles **schema** (build-time) with **behavior** (runtime). Register it with `cero.use()` — `build()` folds in its schema and `cero()` runs its `setup` once the handle is ready. cero core stays schema-agnostic; apps opt into the behaviors they want.
@@ -373,7 +419,7 @@ const remote = await connect(c, spec)
 
 | Path                         | What you get                                                             |
 | ---------------------------- | ------------------------------------------------------------------------ |
-| `@cero-base/cero`            | factory + operators + schema DSL                                         |
+| `@cero-base/cero`            | factory + operators + schema DSL + `define`/`bind`                       |
 | `@cero-base/cero/client`     | `connect(ipc, spec)` — talk to a cero running in another process         |
 | `@cero-base/cero/server`     | `serve(ipc, { storage, spec })` — run + expose a cero over an IPC stream |
 | `@cero-base/cero/build`      | `build(specDir, schema)` — generate the on-disk spec                     |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cero-base/cero",
-  "version": "0.8.5",
+  "version": "0.8.6",
   "description": "The ideal p2p API — everything is a handle, handles contain refs, refs contain rows.",
   "type": "module",
   "main": "./src/index.js",
@@ -78,12 +78,12 @@
     "test": "ls test/*.test.js | xargs -P1 -n1 brittle-node"
   },
   "dependencies": {
-    "@cero-base/core": "^0.8.5",
+    "@cero-base/core": "^0.8.6",
     "b4a": "^1.8.1",
     "bare-abort-controller": "^1.1.2",
-    "bare-crypto": "^1.13.7",
-    "bare-fs": "^4.7.1",
-    "bare-path": "^3.0.0",
+    "bare-crypto": "^1.14.1",
+    "bare-fs": "^4.7.2",
+    "bare-path": "^3.0.1",
     "blind-pairing": "^2.3.1",
     "compact-encoding": "^3.1.0",
     "hrpc": "^4.3.0",
@@ -97,7 +97,7 @@
   "devDependencies": {
     "@hyperswarm/testnet": "^3.1.4",
     "brittle": "^4.0.0",
-    "typescript": "^5.7.0"
+    "typescript": "^6.0.3"
   },
   "license": "Apache-2.0"
 }

package/src/handle/index.js

@@ -15,6 +15,7 @@ import { CeroError } from '@cero-base/core/errors'
 import { NS, TIMEOUT } from '../lib/constants.js'
 
 import { attachRefs, onAbort } from '../lib/utils.js'
+import { bind } from '../lib/operators.js'
 
 export { Ref } from '../lib/utils.js'
 
@@ -399,6 +400,7 @@ export class Handle extends ReadyResource {
     })
 
     if (accept !== false) this._wireAccept(child, { role })
+    bind(child, type)
     this.children.add(child)
     this.emit('handle', child, { name, role })
     return child
@@ -454,6 +456,7 @@ export class Handle extends ReadyResource {
       updatedAt: ts
     })
     this._wireAccept(child)
+    bind(child, type)
     this.children.add(child)
     this.emit('handle', child, {})
     return child
@@ -517,6 +520,7 @@ export class Handle extends ReadyResource {
       await this._saveKeyPair(id, writer)
     }
     this._wireAccept(child)
+    bind(child, type)
     this.children.add(child)
     this.emit('handle', child, {})
     return child

package/src/index.js

@@ -8,15 +8,41 @@ import { CeroError } from '@cero-base/core/errors'
 
 import { Handle, Ref } from './handle/index.js'
 import { Local } from './local/index.js'
-import { put, set, get, del, count, watch, call, open, before, after } from './lib/operators.js'
-import { peek } from './lib/peek.js'
+import {
+  put,
+  set,
+  get,
+  del,
+  count,
+  watch,
+  call,
+  open,
+  before,
+  after,
+  bind,
+  define,
+  peek
+} from './lib/operators.js'
 import { t, schema } from './lib/spec.js'
 import { FLUSH } from './lib/constants.js'
 import { internal } from './lib/internal.js'
 
 export { Handle, Ref, Local }
-export { put, set, get, del, count, watch, call, open, before, after } from './lib/operators.js'
-export { peek } from './lib/peek.js'
+export {
+  put,
+  set,
+  get,
+  del,
+  count,
+  watch,
+  call,
+  open,
+  before,
+  after,
+  bind,
+  define,
+  peek
+} from './lib/operators.js'
 export { t, schema } from './lib/spec.js'
 
 /**
@@ -123,6 +149,7 @@ export async function cero(dir, spec, opts = {}) {
     throw err
   }
 
+  bind(me, null)
   return me
 }
 
@@ -175,7 +202,9 @@ Object.assign(cero, {
   after,
   peek,
   restore,
-  schema
+  schema,
+  bind,
+  define
 })
 cero._internal = internal
 // A bare function is shorthand for a behavior-only extension: `{ setup: fn }`.

package/src/lib/operators.js

@@ -1,6 +1,11 @@
 import { Readable } from 'streamx'
+import HypercoreStorage from 'hypercore-storage'
+import Corestore from 'corestore'
+
+import { CeroError } from '@cero-base/core/errors'
 
 import { onAbort } from './utils.js'
+import { Local } from '../local/index.js'
 
 /**
  * @typedef {import('./utils.js').Ref} Ref
@@ -186,3 +191,96 @@ export const open = (ref, arg) => {
   if (arg && typeof arg.id === 'string') return ref.handle._load(ref.name, arg.id)
   return ref.handle._create(ref.name, arg)
 }
+
+/**
+ * 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.
+ *
+ * @param {string} dir   Cero data directory.
+ * @param {any} spec     Built spec — same value passed to `cero(dir, spec)`.
+ * @returns {Promise<boolean>}  `true` if a master seed exists on disk.
+ */
+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')
+
+  const root = new HypercoreStorage(`${dir}/main`)
+  await root.ready()
+  const store = new Corestore(root, { manifestVersion: 2 })
+  await store.ready()
+
+  const local = new Local(null, spec, { store })
+  await local.ready()
+  try {
+    const { data } = await local.store.get('master')
+    return !!data?.seed
+  } finally {
+    await local.close()
+    await store.close()
+    await root.close()
+  }
+}
+
+// ─── 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)) {
+    if (typeof fns[key] === 'function') bound[key] = (...args) => fns[key](handle, ...args)
+  }
+  handle[ns] = bound
+}
+
+/**
+ * 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.
+ *
+ * @param {any} handle
+ * @param {Record<string, any> | string | null} arg
+ * @returns {any} handle
+ */
+export function bind(handle, arg) {
+  if (arg !== null && typeof arg !== 'string') {
+    for (const ns of Object.keys(arg)) attach(handle, ns, arg[ns])
+    return handle
+  }
+  const handles = handle.spec?.meta?.handles || {}
+  for (const ns of Object.keys(registry)) {
+    if (arg === null) {
+      if (!(ns in handles)) attach(handle, ns, registry[ns]) // bare root namespace
+    } else if (ns === arg) {
+      for (const k of Object.keys(registry[ns])) attach(handle, k, registry[ns][k]) // child group
+    }
+  }
+  return handle
+}
+
+/**
+ * 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.
+ *
+ * @param {Record<string, any>} map
+ */
+export function define(map) {
+  Object.assign(registry, map)
+}
+
+/** Test seam: clear all registered operators. */
+export function _clearDefined() {
+  for (const k of Object.keys(registry)) delete registry[k]
+}

package/src/rpc/client.js

@@ -2,6 +2,7 @@ import { Readable } from 'streamx'
 import { RPCClient, bindCodec } from '@cero-base/core/rpc'
 
 import { attachRefs } from '../lib/utils.js'
+import { bind } from '../lib/operators.js'
 
 export { put, set, get, del, count, watch, call, open } from '../lib/operators.js'
 
@@ -298,6 +299,7 @@ export class Client extends RPCClient {
     this.deviceId = deviceId || null
     this.identity = { id, toPhrase: () => phrase || null }
     attachRefs(this, /** @type {Spec} */ (this.spec).meta.refs)
+    bind(this, null)
     if (/** @type {Spec} */ (this.spec).meta.local?.refs) this.local = new LocalRefs(this)
   }
 
@@ -364,6 +366,7 @@ class Handle {
     if (!this.spec.codec) bindCodec(this.spec)
     this.store = this
     attachRefs(this, this.spec.meta.refs)
+    bind(this, this.type)
   }
 
   /** Underlying RPC channel borrowed from the parent. */

package/types/index.d.ts

@@ -39,7 +39,6 @@ export namespace cero {
  * @returns {Promise<Handle>}  Freshly restored root handle.
  */
 export function restore(me: Handle, phrase: string): Promise<Handle>;
-export { peek } from "./lib/peek.js";
 export type CeroOpts = {
     /**
      * Pre-resolved identity. If absent, derived from `seed`/`phrase` or generated.
@@ -103,5 +102,5 @@ import { Ref } from './handle/index.js';
 import { Local } from './local/index.js';
 import { Identity } from '@cero-base/core/identity';
 export { Handle, Ref, Local };
-export { put, set, get, del, count, watch, call, open, before, after } from "./lib/operators.js";
+export { put, set, get, del, count, watch, call, open, before, after, bind, define, peek } from "./lib/operators.js";
 export { t, schema } from "./lib/spec.js";

package/types/lib/operators.d.ts

@@ -1,3 +1,37 @@
+/**
+ * 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.
+ *
+ * @param {string} dir   Cero data directory.
+ * @param {any} spec     Built spec — same value passed to `cero(dir, spec)`.
+ * @returns {Promise<boolean>}  `true` if a master seed exists on disk.
+ */
+export function peek(dir: string, spec: any): Promise<boolean>;
+/**
+ * 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.
+ *
+ * @param {any} handle
+ * @param {Record<string, any> | string | null} arg
+ * @returns {any} handle
+ */
+export 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. Call once
+ * at startup, before `cero()` / `connect()`, in both processes.
+ *
+ * @param {Record<string, any>} map
+ */
+export function define(map: Record<string, any>): void;
+/** Test seam: clear all registered operators. */
+export function _clearDefined(): void;
 export function put(ref: Ref, row: Record<string, any>): Promise<SingleResult>;
 export function set(ref: Ref, row: Record<string, any>, opts?: {
     upsert?: boolean;

package/src/lib/peek.js

@@ -1,36 +0,0 @@
-import HypercoreStorage from 'hypercore-storage'
-import Corestore from 'corestore'
-
-import { CeroError } from '@cero-base/core/errors'
-
-import { Local } from '../local/index.js'
-
-/**
- * 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.
- *
- * @param {string} dir   Cero data directory.
- * @param {any} spec     Built spec — same value passed to `cero(dir, spec)`.
- * @returns {Promise<boolean>}  `true` if a master seed exists on disk.
- */
-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')
-
-  const root = new HypercoreStorage(`${dir}/main`)
-  await root.ready()
-  const store = new Corestore(root, { manifestVersion: 2 })
-  await store.ready()
-
-  const local = new Local(null, spec, { store })
-  await local.ready()
-  try {
-    const { data } = await local.store.get('master')
-    return !!data?.seed
-  } finally {
-    await local.close()
-    await store.close()
-    await root.close()
-  }
-}

package/types/lib/peek.d.ts

@@ -1,10 +0,0 @@
-/**
- * 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.
- *
- * @param {string} dir   Cero data directory.
- * @param {any} spec     Built spec — same value passed to `cero(dir, spec)`.
- * @returns {Promise<boolean>}  `true` if a master seed exists on disk.
- */
-export function peek(dir: string, spec: any): Promise<boolean>;