@cero-base/cero 0.6.0 → 0.7.0

package/README.md

@@ -173,6 +173,97 @@ await cero.open(me.room, { id: existingRoomId }) // load an existing room by id
 
 Returns the child handle, ready to operate on (`cero.put(joined.messages, …)` etc.).
 
+### `cero.before(ref, fn)` / `cero.after(ref, fn)`
+
+Hook into writes to a ref. `before` runs **in-path** before the write commits — return `false` to cancel, or mutate `ctx.row`. `after` is a non-blocking **event** that fires once the write has committed. Both return an unsubscribe fn — call it to stop early, or ignore it for a subscription that should live as long as the handle (it's dropped when the handle closes).
+
+```js
+const off = cero.before(room.messages, (ctx) => {
+  if (!ctx.row.text?.trim()) return false // reject empty messages
+})
+
+cero.after(me.profile, ({ row }) => {
+  /* react to your profile changing */
+})
+```
+
+`ctx` is `{ op, name, row }` (plus `result` in `after`).
+
+## 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.
+
+```js
+import { profileSync } from '@cero-base/cero/extensions'
+
+cero.use(profileSync()) // before build() (for the schema) and before cero() (for the behavior)
+await build('./spec', schema)
+```
+
+An extension is two optional parts:
+
+```js
+function myExtension() {
+  return {
+    schema: { members: cero.t.extend({ status: cero.t.string }) }, // merged into your schema
+    setup(me) {
+      me.on('handle', (room, opts) => {
+        /* opts carries the open args (e.g. opts.name on create); me.children is the set of open rooms */
+      })
+    }
+  }
+}
+```
+
+For a behavior-only extension (no schema), pass a function directly — it's shorthand for `{ setup }`:
+
+```js
+cero.use((me) => {
+  me.on('handle', (room) => {
+    /* … */
+  })
+})
+```
+
+Build and the running app are separate processes, so `cero.use()` runs in both — your build script (for the schema) and once at app startup before `cero()` (for the behavior).
+
+### Cleanup
+
+`setup(me)` may return a disposer; cero calls it on `me.close()`. You rarely need it — `before`/`after` and `me.on(...)` registered on `me` or its rooms are torn down automatically when the handle closes. Return a disposer **only** for things the handle's close won't clean up, like a timer or an external connection:
+
+```js
+setup(me) {
+  const timer = setInterval(() => ping(me), 30_000)
+  return () => clearInterval(timer)
+}
+```
+
+### `profileSync` (bundled)
+
+Mirrors your `profile` onto your `member` row in every room, so others see your name and avatar. It **declares its own `profile` single** (`name` + the synced fields) and extends `member` with them — no app schema required. Defaults to syncing `avatar`:
+
+```js
+cero.use(profileSync())
+cero.use(profileSync({ fields: { status: cero.t.string } })) // sync extra fields
+```
+
+Want a richer profile (e.g. a `bio` that doesn't sync)? Declare your own `profile` single — the app schema wins, and `profileSync` still adds the member side.
+
+### `handleSync` (bundled)
+
+Mirrors a child handle's `profile` (name + avatar) onto its row in the parent's `handles` list — so a handle/room list renders names and photos without opening each handle. Adds `avatar` (or your `fields`) to the `handle` builtin and reflects the handle's own `profile` (which your app owns) onto the row.
+
+```js
+cero.use(handleSync())
+
+// your handle type declares a `profile`; your app sets it:
+const room = await cero.open(me.room)
+await cero.set(room.profile, { name: 'general', avatar: 'pic.png' })
+// → the me.handles row now carries name + avatar — render the room list, no opens
+```
+
+Requires your handle types to declare a `profile` single; handles without one are left untouched.
+
 ## RPC
 
 cero runs in one process; your UI runs in another. Connect them with any duplex stream (Bare IPC, Electron `contextBridge`, a worker port, even a TCP socket).
@@ -263,12 +354,13 @@ const remote = await connect(c, spec)
 
 ## Exports
 
-| Path                     | What you get                                                             |
-| ------------------------ | ------------------------------------------------------------------------ |
-| `@cero-base/cero`        | factory + operators + schema DSL                                         |
-| `@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                     |
+| Path                         | What you get                                                             |
+| ---------------------------- | ------------------------------------------------------------------------ |
+| `@cero-base/cero`            | factory + operators + schema DSL                                         |
+| `@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                     |
+| `@cero-base/cero/extensions` | bundled extensions (`profileSync`, …)                                    |
 
 ## Tests
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cero-base/cero",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "The ideal p2p API — everything is a handle, handles contain refs, refs contain rows.",
   "type": "module",
   "main": "./src/index.js",
@@ -30,6 +30,10 @@
     "./client": {
       "types": "./types/rpc/client.d.ts",
       "default": "./src/rpc/client.js"
+    },
+    "./extensions": {
+      "types": "./types/extensions/index.d.ts",
+      "default": "./src/extensions/index.js"
     }
   },
   "typesVersions": {
@@ -42,6 +46,9 @@
       ],
       "client": [
         "types/rpc/client.d.ts"
+      ],
+      "extensions": [
+        "types/extensions/index.d.ts"
       ]
     }
   },
@@ -67,7 +74,7 @@
     "test": "ls test/*.test.js | xargs -P2 -n1 brittle-node"
   },
   "dependencies": {
-    "@cero-base/core": "^0.6.0",
+    "@cero-base/core": "^0.7.0",
     "b4a": "^1.8.1",
     "bare-crypto": "^1.13.7",
     "bare-fs": "^4.7.1",

package/src/build/index.js

@@ -9,6 +9,7 @@ import HRPCBuilder from 'hrpc'
 import { CeroError } from '@cero-base/core/errors'
 
 import { NS } from '../lib/constants.js'
+import { internal } from '../lib/internal.js'
 import {
   refs,
   builtinRefs,
@@ -45,19 +46,23 @@ export async function build(specDir, schema, { ns = NS } = {}) {
   const raw = /** @type {SchemaDefs & { local?: SchemaDefs }} */ (schema?.defs || schema)
   if (!raw || typeof raw !== 'object') throw CeroError.REQUIRED('schema')
 
-  // Pull out `t.extend(...)` entries (keyed by builtin ref name) and map them
-  // to the builtin's type name, to merge into builtin types across every scope.
+  // Pull out `t.extend(...)` entries (keyed by builtin ref name) → builtin type
+  // name, merged across scopes. App schema first, then each `cero.use()` extension.
   const extend = {}
   const defs = {}
-  for (const [k, v] of Object.entries(raw)) {
-    if (v && v.kind === 'extend') {
-      const type = refs.main[k]?.type
-      if (!type) throw CeroError.INVALID(`'${k}' is not an extendable builtin`)
-      extend[type] = v.fields
-    } else {
-      defs[k] = v
+  const collect = (entries, fromExt = false) => {
+    for (const [k, v] of Object.entries(entries)) {
+      if (v && v.kind === 'extend') {
+        const type = refs.main[k]?.type
+        if (!type) throw CeroError.INVALID(`'${k}' is not an extendable builtin`)
+        extend[type] = { ...extend[type], ...v.fields }
+      } else if (!fromExt || !(k in defs)) {
+        defs[k] = v // app schema wins over an extension's default
+      }
     }
   }
+  collect(raw)
+  for (const ext of internal.extensions) if (ext.schema) collect(ext.schema, true)
 
   const main = compile(splitMain(defs), ns, 'main')
   const local = compile(defs.local || {}, ns, 'local')

package/src/extensions/handle-sync.js

@@ -0,0 +1,32 @@
+import { t } from '../lib/spec.js'
+import { set, watch } from '../lib/operators.js'
+
+/**
+ * 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.
+ *
+ * @param {{ fields?: Record<string, any> }} [opts]
+ */
+export function handleSync({ fields = { avatar: t.string } } = {}) {
+  return {
+    schema: { handles: t.extend(fields) },
+    setup(me) {
+      me.on('handle', (child, opts) => {
+        if (!child.profile) return
+        if (opts.name) set(child.profile, { name: opts.name })
+        const sub = watch(child.profile)
+        sub.on('data', ({ data }) => {
+          if (!data?.name) return
+          child.name = data.name
+          set(me.handles, { id: child.id, ...data }, { upsert: false })
+        })
+        child.once('close', () => sub.destroy())
+      })
+    }
+  }
+}

package/src/extensions/index.js

@@ -0,0 +1,2 @@
+export { profileSync } from './profile-sync.js'
+export { handleSync } from './handle-sync.js'

package/src/extensions/profile-sync.js

@@ -0,0 +1,30 @@
+import { t } from '../lib/spec.js'
+import { get, set, after } from '../lib/operators.js'
+
+/**
+ * Mirror your `profile` onto your `member` row in every room. Declares a
+ * `profile` single (`name`, `avatar`, plus any extra `fields`) and mirrors them
+ * onto the `member` builtin, then publishes when you open/join a room 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 = { avatar: t.string } } = {}) {
+  return {
+    schema: {
+      profile: t.single({ name: t.string, ...fields }),
+      members: t.extend(fields)
+    },
+    setup(me) {
+      const publish = async (room) => {
+        const { data: member } = await get(room.members, me.identity.id)
+        if (!member) return
+        const { data: profile } = await get(me.profile)
+        if (profile) await set(room.members, { id: me.identity.id, ...profile })
+      }
+      me.on('handle', publish)
+      after(me.profile, () => me.children.forEach(publish))
+    }
+  }
+}

package/src/handle/index.js

@@ -137,16 +137,9 @@ export class Handle extends ReadyResource {
       await this.pair.ready()
     }
     attachRefs(this, this.store.refs)
-    if (!this.children) return
-
-    this._offUpdate = this.store.onUpdate(() => {
-      if (this.closing || this.closed) return
-      for (const c of this.children) this._syncMember(c).catch(this._onerror)
-    })
   }
 
   async _close() {
-    this._offUpdate?.()
     if (this.children) {
       for (const c of [...this.children]) await c.close()
       this.children.clear()
@@ -340,7 +333,6 @@ export class Handle extends ReadyResource {
       createdAt: ts,
       updatedAt: ts
     })
-    if (name && child.profile) await child.store.set('profile', { name })
     await this.store.call('add-handle', {
       id,
       type,
@@ -353,7 +345,7 @@ export class Handle extends ReadyResource {
 
     if (accept !== false) this._wireAccept(child, { role })
     this.children.add(child)
-    await this._syncMember(child)
+    this.emit('handle', child, { name, role })
     return child
   }
 
@@ -396,20 +388,19 @@ export class Handle extends ReadyResource {
     const id = toId(child.store.key)
     await this._saveKeyPair(id, child.store.keyPair)
 
-    const name = child.profile ? await waitForProfileName(child, deadline) : null
     const ts = Date.now()
     await this.store.call('add-handle', {
       id,
       type,
       key: child.store.key,
       encryptionKey: child.store.encryptionKey,
-      name,
+      name: null,
       createdAt: ts,
       updatedAt: ts
     })
     this._wireAccept(child)
     this.children.add(child)
-    await this._syncMember(child)
+    this.emit('handle', child, {})
     return child
   }
 
@@ -452,6 +443,7 @@ export class Handle extends ReadyResource {
     }
     this._wireAccept(child)
     this.children.add(child)
+    this.emit('handle', child, {})
     return child
   }
 
@@ -534,20 +526,6 @@ export class Handle extends ReadyResource {
     })
   }
 
-  async _syncMember(child) {
-    if (!child.store.writable) return
-    const { data: profile } = await this.store.get('profile')
-    if (!profile) return
-    const { data: existing } = await child.store.get('members', this.identity.id)
-    if (!existing) return
-    await child.store.call('set-member', {
-      ...existing,
-      ...profile,
-      id: existing.id,
-      updatedAt: Date.now()
-    })
-  }
-
   /**
    * @param {Handle} child
    * @param {{ role?: string }} [opts]
@@ -597,13 +575,3 @@ function pickHandle(spec, type) {
 function randomNs() {
   return z32.encode(Identity.randomBytes(8))
 }
-
-async function waitForProfileName(child, timeout) {
-  const deadline = Date.now() + timeout
-  while (Date.now() < deadline) {
-    const { data } = await child.store.get('profile')
-    if (data?.name) return data.name
-    await new Promise((r) => setTimeout(r, 100))
-  }
-  return null
-}

package/src/index.js

@@ -8,13 +8,14 @@ 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 } from './lib/operators.js'
+import { put, set, get, del, count, watch, call, open, before, after } from './lib/operators.js'
 import { peek } from './lib/peek.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 } from './lib/operators.js'
+export { put, set, get, del, count, watch, call, open, before, after } from './lib/operators.js'
 export { peek } from './lib/peek.js'
 export { t, schema } from './lib/spec.js'
 
@@ -112,6 +113,11 @@ export async function cero(dir, spec, opts = {}) {
   }
   if (opts.recovery) await me.recover({ timeout: opts.recoveryTimeout })
 
+  for (const ext of internal.extensions) {
+    const off = await ext.setup?.(me)
+    if (typeof off === 'function') me.once('close', off)
+  }
+
   return me
 }
 
@@ -150,7 +156,26 @@ export async function restore(me, phrase) {
   })
 }
 
-Object.assign(cero, { put, set, get, del, count, watch, call, open, peek, restore, t, schema })
+Object.assign(cero, {
+  t,
+  put,
+  set,
+  get,
+  del,
+  count,
+  watch,
+  call,
+  open,
+  before,
+  after,
+  peek,
+  restore,
+  schema
+})
+cero._internal = internal
+// A bare function is shorthand for a behavior-only extension: `{ setup: fn }`.
+cero.use = (...exts) =>
+  internal.extensions.push(...exts.map((e) => (typeof e === 'function' ? { setup: e } : e)))
 
 async function resolveIdentity(opts, local) {
   if (opts.identity) return opts.identity

package/src/lib/internal.js

@@ -0,0 +1,3 @@
+// Process-wide registry for extensions registered via `cero.use()`.
+// `build()` folds in each extension's schema; `cero()` runs each setup.
+export const internal = { extensions: [] }

package/src/lib/operators.js

@@ -18,13 +18,15 @@ export const put = (ref, row) => ref.handle.store.put(ref.name, row)
 
 /**
  * Upsert a row on `ref` — merges with the existing row and preserves
- * `createdAt`.
+ * `createdAt`. Pass `{ upsert: false }` to update-only: a missing row is left
+ * untouched instead of created (atomic — never resurrects a deleted row).
  *
  * @param {Ref} ref
  * @param {Record<string, any>} row
+ * @param {{ upsert?: boolean }} [opts]
  * @returns {Promise<SingleResult>}
  */
-export const set = (ref, row) => ref.handle.store.set(ref.name, row)
+export const set = (ref, row, opts) => ref.handle.store.set(ref.name, row, opts)
 
 /**
  * Delete a row by id (collection refs), or wipe the row (single refs).
@@ -53,6 +55,43 @@ export const count = (ref, q) => ref.handle.store.count(ref.name, q)
  */
 export const call = (ref, d) => ref.handle.store.call(ref.name, d)
 
+// Write ops per ref kind, for `before`/`after` subscriptions.
+const WRITES = { single: ['set'], collection: ['put', 'set', 'del'] }
+
+/**
+ * Intercept writes to `ref` before they commit — `fn(ctx)` runs in-path
+ * (awaited). Return `false` to cancel the write, or mutate `ctx.row`.
+ * Returns an unsubscribe fn.
+ *
+ * @param {Ref} ref
+ * @param {(ctx: { op: string, name: string, row: any }) => any} fn
+ * @returns {() => void}
+ */
+export const before = (ref, fn) => {
+  const db = ref.handle.store
+  const ops = WRITES[ref.kind] || ['set']
+  const offs = ops.map((op) =>
+    db.before(op, (ctx) => (ctx.name === ref.name ? fn(ctx) : undefined))
+  )
+  return () => offs.forEach((off) => off())
+}
+
+/**
+ * Subscribe to writes on `ref` — fires after each committed write,
+ * non-blocking (observe only). Returns an unsubscribe fn.
+ *
+ * @param {Ref} ref
+ * @param {(ctx: { op: string, name: string, row: any }) => void} fn
+ * @returns {() => void}
+ */
+export const after = (ref, fn) => {
+  const db = ref.handle.store
+  const ops = WRITES[ref.kind] || ['set']
+  const handler = (ctx) => ctx.name === ref.name && fn(ctx)
+  for (const op of ops) db.on(`after:${op}`, handler)
+  return () => ops.forEach((op) => db.off(`after:${op}`, handler))
+}
+
 // get/watch on a handle-kind ref list its rows from the `handles` collection
 // filtered by type (handle types are stored there with their { id, key,
 // encryptionKey, name }). Data-kind refs go straight to the store.

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

@@ -0,0 +1,22 @@
+/**
+ * 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.
+ *
+ * @param {{ fields?: Record<string, any> }} [opts]
+ */
+export function handleSync({ fields }?: {
+    fields?: Record<string, any>;
+}): {
+    schema: {
+        handles: {
+            kind: "extend";
+            fields: Record<string, import("@cero-base/core/schema").Prim>;
+        };
+    };
+    setup(me: any): void;
+};

package/types/extensions/index.d.ts

@@ -0,0 +1,2 @@
+export { profileSync } from "./profile-sync.js";
+export { handleSync } from "./handle-sync.js";

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

@@ -0,0 +1,21 @@
+/**
+ * Mirror your `profile` onto your `member` row in every room. Declares a
+ * `profile` single (`name`, `avatar`, plus any extra `fields`) and mirrors them
+ * onto the `member` builtin, then publishes when you open/join a room 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 }?: {
+    fields?: Record<string, any>;
+}): {
+    schema: {
+        profile: import("@cero-base/core/schema").TypeDef;
+        members: {
+            kind: "extend";
+            fields: Record<string, import("@cero-base/core/schema").Prim>;
+        };
+    };
+    setup(me: any): void;
+};

package/types/handle/index.d.ts

@@ -89,7 +89,6 @@ export class Handle extends ReadyResource {
     store: Database;
     pair: Pairing;
     _wantsPair: boolean;
-    _offUpdate: () => void;
     /** Canonical id — identity id for the root handle, store key for children. */
     get id(): any;
     /** This device's id + name. `null` on child handles. */
@@ -203,7 +202,6 @@ export class Handle extends ReadyResource {
      * @returns {Promise<void>}
      */
     resume(): Promise<void>;
-    _syncMember(child: any): Promise<void>;
     /**
      * @param {Handle} child
      * @param {{ role?: string }} [opts]

package/types/index.d.ts

@@ -25,6 +25,10 @@
  * @returns {Promise<Handle>}
  */
 export function cero(dir: string, spec: any, opts?: CeroOpts): Promise<Handle>;
+export namespace cero {
+    export { internal as _internal };
+    export function use(...exts: any[]): number;
+}
 /**
  * Restore a cero instance from a mnemonic phrase. Closes the running
  * instance, wipes the on-disk `main/` tree and re-opens with `recovery: true`
@@ -94,9 +98,10 @@ export type CeroOpts = {
     recoveryTimeout?: number;
 };
 import { Handle } from './handle/index.js';
+import { internal } from './lib/internal.js';
 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 } from "./lib/operators.js";
+export { put, set, get, del, count, watch, call, open, before, after } from "./lib/operators.js";
 export { t, schema } from "./lib/spec.js";

package/types/lib/internal.d.ts

@@ -0,0 +1,3 @@
+export namespace internal {
+    let extensions: any[];
+}

package/types/lib/operators.d.ts

@@ -1,10 +1,22 @@
 export function put(ref: Ref, row: Record<string, any>): Promise<SingleResult>;
-export function set(ref: Ref, row: Record<string, any>): Promise<SingleResult>;
+export function set(ref: Ref, row: Record<string, any>, opts?: {
+    upsert?: boolean;
+}): Promise<SingleResult>;
 export function del(ref: Ref, id?: string): Promise<void>;
 export function count(ref: Ref, q?: Record<string, any>): Promise<{
     data: number;
 }>;
 export function call(ref: Ref, d?: Record<string, any>): Promise<any>;
+export function before(ref: Ref, fn: (ctx: {
+    op: string;
+    name: string;
+    row: any;
+}) => any): () => void;
+export function after(ref: Ref, fn: (ctx: {
+    op: string;
+    name: string;
+    row: any;
+}) => void): () => void;
 export function get(ref: Ref, q?: string | Record<string, any>): Promise<SingleResult | ListResult | GetByIdResult>;
 export function watch(ref: Ref, q?: Record<string, any>): any;
 export function open(ref: Ref, arg?: string | {

package/src/CLAUDE.md

@@ -1,3 +0,0 @@
-<claude-mem-context>
-
-</claude-mem-context>

package/src/handle/CLAUDE.md

@@ -1,3 +0,0 @@
-<claude-mem-context>
-
-</claude-mem-context>

package/src/lib/CLAUDE.md

@@ -1,3 +0,0 @@
-<claude-mem-context>
-
-</claude-mem-context>