@cero-base/cero 0.5.2 → 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.5.2",
+  "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",
@@ -20,8 +20,8 @@
       "default": "./src/index.js"
     },
     "./build": {
-      "types": "./types/builder.d.ts",
-      "default": "./src/builder.js"
+      "types": "./types/build/index.d.ts",
+      "default": "./src/build/index.js"
     },
     "./server": {
       "types": "./types/rpc/server.d.ts",
@@ -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.5.2",
+    "@cero-base/core": "^0.7.0",
     "b4a": "^1.8.1",
     "bare-crypto": "^1.13.7",
     "bare-fs": "^4.7.1",

package/src/build/builtins.js

@@ -0,0 +1,137 @@
+// Build wiring for the builtin schemas (schemas.js): turns the grouped field
+// maps into the type / collection / dispatch / command descriptors the builder
+// registers. Every cero schema includes these; app refs are added on top.
+import { CeroError } from '@cero-base/core/errors'
+import { COUNTERS, DB_TYPE } from '../lib/constants.js'
+import * as schemas from './schemas.js'
+
+// Builtin collections by scope — ref name → { type, kind? }. kind defaults to
+// 'collection' (id-keyed); 'single' has no key. Dispatches are derived for
+// main; counters is internal (a collection with no add/set/del).
+export const refs = {
+  main: {
+    members: { type: 'member' },
+    devices: { type: 'device' },
+    invites: { type: 'invite' },
+    handles: { type: 'handle' }
+  },
+  local: {
+    master: { type: 'master', kind: 'single' },
+    keypair: { type: 'keypair', kind: 'single' },
+    'handle-keypairs': { type: 'handle-keypair' }
+  }
+}
+
+export const hyperdbType = (prim) => DB_TYPE[prim] || 'string'
+
+const at = (ns, n) => `@${ns}/${n}`
+const keyOf = (def) => (def.kind === 'single' ? [] : ['id'])
+
+const fields = (map) =>
+  Object.entries(map).map(([name, m]) => ({
+    name,
+    type: hyperdbType(m.prim),
+    required: m.required === true
+  }))
+
+// Merge app `t.extend` fields into a builtin's base fields — base can't be redeclared.
+const merge = (type, base, extra) => {
+  if (!extra) return base
+  for (const k in extra)
+    if (k in base)
+      throw CeroError.INVALID(`'${k}' is a base field of '${type}' and cannot be redeclared`)
+  return { ...base, ...extra }
+}
+
+const descriptors = (group, extend = {}) =>
+  Object.entries(group).map(([name, base]) => ({
+    name,
+    compact: false,
+    fields: fields(merge(name, base, extend[name]))
+  }))
+
+// meta.refs entries for a scope's builtins.
+export const builtinRefs = (ns, scope) =>
+  Object.fromEntries(
+    Object.entries(refs[scope]).map(([name, def]) => [
+      name,
+      {
+        kind: def.kind || 'collection',
+        path: [name],
+        builtin: true,
+        ...(scope === 'main' && { verb: def.type }),
+        schema: at(ns, def.type)
+      }
+    ])
+  )
+
+// hyperschema type descriptors. scope is 'main' | 'local' | 'rpc'; `extend`
+// merges app `t.extend` fields into the matching type.
+export const builtinTypes = (scope, extend) => descriptors(schemas[scope], extend)
+export const rpcTypes = () => descriptors(schemas.rpc)
+
+// hyperdb collection descriptors for a scope.
+export const builtinCollections = (ns, scope) => {
+  const out = Object.entries(refs[scope]).map(([name, def]) => ({
+    name,
+    schema: at(ns, def.type),
+    key: keyOf(def)
+  }))
+  if (scope === 'main') out.push({ name: COUNTERS, schema: at(ns, 'counter'), key: ['name'] })
+  return out
+}
+
+// hyperdispatch descriptors (main scope only).
+export const builtinDispatches = (ns) => [
+  { name: 'add-writer', requestType: at(ns, 'writer') },
+  { name: 'del-writer', requestType: at(ns, 'writer') },
+  { name: 'claim-writer', requestType: at(ns, 'claim') },
+  ...Object.values(refs.main).flatMap(({ type }) => [
+    { name: `add-${type}`, requestType: at(ns, type) },
+    { name: `set-${type}`, requestType: at(ns, type) },
+    { name: `del-${type}`, requestType: at(ns, 'del-by-id') }
+  ])
+]
+
+export const rpcCommands = (ns) => {
+  const ref = (n) => at(ns, n)
+  return [
+    { name: 'init', request: { name: ref('req-empty') }, response: { name: ref('res-identity') } },
+    {
+      name: 'restore',
+      request: { name: ref('req-restore') },
+      response: { name: ref('res-identity') }
+    },
+    { name: 'add-row', request: { name: ref('req-row') }, response: { name: ref('res-data') } },
+    {
+      name: 'add-handle',
+      request: { name: ref('req-row') },
+      response: { name: ref('res-handle') }
+    },
+    { name: 'set', request: { name: ref('req-row') }, response: { name: ref('res-data') } },
+    { name: 'get', request: { name: ref('req-query') }, response: { name: ref('res-rows') } },
+    { name: 'get-one', request: { name: ref('req-id') }, response: { name: ref('res-data') } },
+    { name: 'del', request: { name: ref('req-id') }, response: { name: ref('res-ok') } },
+    { name: 'count', request: { name: ref('req-query') }, response: { name: ref('res-count') } },
+    {
+      name: 'watch',
+      request: { name: ref('req-query') },
+      response: { name: ref('res-rows'), stream: true }
+    },
+    { name: 'call', request: { name: ref('req-call') }, response: { name: ref('res-data') } },
+    { name: 'invite', request: { name: ref('req-invite') }, response: { name: ref('res-invite') } },
+    { name: 'revoke', request: { name: ref('req-revoke') }, response: { name: ref('res-ok') } },
+    { name: 'join', request: { name: ref('req-join') }, response: { name: ref('res-handle') } },
+    {
+      name: 'open-handle',
+      request: { name: ref('req-open') },
+      response: { name: ref('res-handle') }
+    },
+    {
+      name: 'close-handle',
+      request: { name: ref('req-handle') },
+      response: { name: ref('res-ok') }
+    },
+    { name: 'leave', request: { name: ref('req-handle') }, response: { name: ref('res-ok') } }
+  ]
+}

package/src/{builder.js → build/index.js}

@@ -8,20 +8,18 @@ import HRPCBuilder from 'hrpc'
 
 import { CeroError } from '@cero-base/core/errors'
 
+import { NS } from '../lib/constants.js'
+import { internal } from '../lib/internal.js'
 import {
-  BUILTINS,
-  LOCAL_BUILTINS,
-  hyperdbType,
+  refs,
+  builtinRefs,
   builtinTypes,
   builtinCollections,
   builtinDispatches,
-  localBuiltinTypes,
-  localBuiltinCollections,
   rpcTypes,
-  rpcCommands
-} from './lib/builtins.js'
-
-const NS = 'cero'
+  rpcCommands,
+  hyperdbType
+} from './builtins.js'
 
 /**
  * @typedef {import('@cero-base/core/schema').Schema} Schema
@@ -45,22 +43,38 @@ const NS = 'cero'
  * @returns {Promise<void>}
  */
 export async function build(specDir, schema, { ns = NS } = {}) {
-  const defs = /** @type {SchemaDefs & { local?: SchemaDefs }} */ (schema?.defs || schema)
-  if (!defs || typeof defs !== 'object') throw CeroError.REQUIRED('schema')
+  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) → builtin type
+  // name, merged across scopes. App schema first, then each `cero.use()` extension.
+  const extend = {}
+  const defs = {}
+  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, BUILTINS)
-  const local = defs.local
-    ? compile(defs.local, ns, LOCAL_BUILTINS)
-    : compile({}, ns, LOCAL_BUILTINS)
+  const main = compile(splitMain(defs), ns, 'main')
+  const local = compile(defs.local || {}, ns, 'local')
   const handles = {}
   for (const [name, child] of Object.entries(splitHandles(defs))) {
-    handles[name] = compile(child, ns)
+    handles[name] = compile(child, ns, 'main')
   }
 
-  emitMain(join(specDir, 'main'), ns, main, { rpc: true })
+  emitMain(join(specDir, 'main'), ns, main, { rpc: true, extend })
   emitLocal(join(specDir, 'local'), ns, local)
   for (const [name, handle] of Object.entries(handles)) {
-    emitMain(join(specDir, 'handles', name), ns, handle, { rpc: false })
+    emitMain(join(specDir, 'handles', name), ns, handle, { rpc: false, extend })
   }
 
   const meta = {
@@ -105,18 +119,10 @@ function isPlainHandle(v) {
   return v && typeof v === 'object' && !v.kind && !v.prim
 }
 
-function compile(root, ns, builtins = BUILTINS) {
+function compile(root, ns, scope = 'main') {
   const ctx = { types: [], collections: [], dispatches: [], meta: { ns, refs: {} }, ns }
 
-  for (const b of builtins) {
-    ctx.meta.refs[b.name] = {
-      kind: b.kind || 'collection',
-      path: [b.name],
-      builtin: true,
-      verb: b.verb,
-      schema: `@${ns}/${b.type}`
-    }
-  }
+  Object.assign(ctx.meta.refs, builtinRefs(ns, scope))
 
   for (const [name, node] of Object.entries(root)) {
     if (node.kind === 'handle') {
@@ -174,11 +180,11 @@ function fieldsFor(fields) {
   return Object.entries(fields).map(([name, marker]) => ({
     name,
     type: hyperdbType(marker.prim),
-    required: false
+    required: marker.required === true
   }))
 }
 
-function emitMain(dir, ns, { types, collections, dispatches }, { rpc }) {
+function emitMain(dir, ns, { types, collections, dispatches }, { rpc, extend = {} }) {
   const schemaDir = join(dir, 'schema')
   const dbDir = join(dir, 'db')
   const dispatchDir = join(dir, 'dispatch')
@@ -186,14 +192,14 @@ function emitMain(dir, ns, { types, collections, dispatches }, { rpc }) {
 
   const s = Hyperschema.from(schemaDir)
   const sns = s.namespace(ns)
-  for (const desc of builtinTypes()) sns.register(desc)
+  for (const desc of builtinTypes('main', extend)) sns.register(desc)
   for (const desc of types) sns.register(desc)
   if (rpc) for (const desc of rpcTypes()) sns.register(desc)
   Hyperschema.toDisk(s, schemaDir, { esm: true })
 
   const db = HyperdbBuilder.from(schemaDir, dbDir)
   const dns = db.namespace(ns)
-  for (const desc of builtinCollections(ns)) dns.collections.register(desc)
+  for (const desc of builtinCollections(ns, 'main')) dns.collections.register(desc)
   for (const desc of collections) dns.collections.register(desc)
   HyperdbBuilder.toDisk(db, dbDir, { esm: true })
 
@@ -217,13 +223,13 @@ function emitLocal(dir, ns, { types, collections }) {
 
   const s = Hyperschema.from(schemaDir)
   const sns = s.namespace(ns)
-  for (const desc of localBuiltinTypes()) sns.register(desc)
+  for (const desc of builtinTypes('local')) sns.register(desc)
   for (const desc of types) sns.register(desc)
   Hyperschema.toDisk(s, schemaDir, { esm: true })
 
   const db = HyperdbBuilder.from(schemaDir, dbDir)
   const dns = db.namespace(ns)
-  for (const desc of localBuiltinCollections(ns)) dns.collections.register(desc)
+  for (const desc of builtinCollections(ns, 'local')) dns.collections.register(desc)
   for (const desc of collections) dns.collections.register(desc)
   HyperdbBuilder.toDisk(db, dbDir, { esm: true })
 }

package/src/build/schemas.js

@@ -0,0 +1,162 @@
+// Builtin type schemas grouped by scope, in the schema DSL — kept separate from
+// the build wiring (builtins.js) so apps can extend them with `t.extend`.
+// Field order is the wire order; do not reorder.
+import { t } from '../lib/spec.js'
+
+const { string, bytes, int, uint, bool, required } = t
+
+export const main = {
+  'del-by-id': {
+    id: required(string)
+  },
+  writer: {
+    master: required(bytes),
+    writer: required(bytes),
+    sig: required(bytes),
+    isIndexer: bool
+  },
+  counter: {
+    name: required(string),
+    value: required(uint)
+  },
+  member: {
+    id: required(string),
+    key: required(bytes),
+    role: required(string),
+    name: string,
+    createdAt: int,
+    updatedAt: int,
+    sig: bytes,
+    index: uint
+  },
+  device: {
+    id: required(string),
+    memberId: string,
+    name: string,
+    isMobile: bool,
+    createdAt: int,
+    updatedAt: int,
+    index: uint
+  },
+  invite: {
+    id: required(string),
+    invite: required(bytes),
+    publicKey: required(bytes),
+    data: bytes,
+    sig: bytes,
+    role: required(string),
+    expires: int,
+    createdAt: int,
+    index: uint
+  },
+  handle: {
+    id: required(string),
+    type: required(string),
+    key: required(bytes),
+    encryptionKey: bytes,
+    name: string,
+    createdAt: int,
+    updatedAt: int,
+    index: uint
+  },
+  claim: {
+    identity: required(bytes),
+    writer: required(bytes),
+    sig: required(bytes)
+  }
+}
+
+export const local = {
+  master: {
+    seed: required(bytes)
+  },
+  keypair: {
+    publicKey: required(bytes),
+    secretKey: required(bytes)
+  },
+  'handle-keypair': {
+    id: required(string),
+    publicKey: required(bytes),
+    secretKey: required(bytes),
+    encryptionKey: bytes
+  }
+}
+
+export const rpc = {
+  'req-empty': {
+    ok: bool
+  },
+  'req-restore': {
+    phrase: required(string)
+  },
+  'req-row': {
+    handle: required(string),
+    ref: required(string),
+    data: required(bytes),
+    local: bool
+  },
+  'req-id': {
+    handle: required(string),
+    ref: required(string),
+    id: required(string),
+    local: bool
+  },
+  'req-query': {
+    handle: required(string),
+    ref: required(string),
+    query: bytes,
+    local: bool
+  },
+  'req-call': {
+    handle: required(string),
+    op: required(string),
+    data: bytes
+  },
+  'req-invite': {
+    handle: required(string),
+    role: string
+  },
+  'req-revoke': {
+    handle: required(string),
+    invite: required(string)
+  },
+  'req-join': {
+    parent: required(string),
+    ref: required(string),
+    invite: required(string)
+  },
+  'req-open': {
+    parent: required(string),
+    row: required(string)
+  },
+  'req-handle': {
+    handle: required(string)
+  },
+  'res-data': {
+    data: bytes
+  },
+  'res-rows': {
+    data: required(bytes),
+    total: required(int),
+    size: required(int)
+  },
+  'res-count': {
+    count: required(int)
+  },
+  'res-invite': {
+    invite: required(string)
+  },
+  'res-handle': {
+    id: required(string),
+    type: required(string),
+    name: string
+  },
+  'res-identity': {
+    id: required(string),
+    deviceId: string,
+    phrase: string
+  },
+  'res-ok': {
+    ok: bool
+  }
+}

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))
+    }
+  }
+}