@cero-base/cero 0.5.2 → 0.7.0

package/src/handle/index.js

@@ -11,6 +11,8 @@ import { Pairing } from '@cero-base/core/pairing'
 import { toId } from '@cero-base/core/utils'
 import { CeroError } from '@cero-base/core/errors'
 
+import { NS, TIMEOUT } from '../lib/constants.js'
+
 import { attachRefs } from '../lib/utils.js'
 
 export { Ref } from '../lib/utils.js'
@@ -64,8 +66,6 @@ export { Ref } from '../lib/utils.js'
  *
  * @typedef {object} RecoverOpts
  * @property {number} [timeout]
- * @property {string | null} [name]
- * @property {boolean} [isMobile]
  *
  * @typedef {object} HandleExtra
  * @property {string | null} [name]                       Display name; set on child handles by the owner flow.
@@ -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()
@@ -214,9 +207,9 @@ export class Handle extends ReadyResource {
    * @param {RecoverOpts} [opts]
    * @returns {Promise<void>}
    */
-  async recover({ timeout = 30000, name = null, isMobile = false } = {}) {
+  async recover({ timeout = TIMEOUT } = {}) {
     if (this.store.writable) return
-    await this.store.claim({ name, isMobile })
+    await this.store.claim()
     await this.store.whenWritable({ timeout })
     await this.store.bee.update()
   }
@@ -281,9 +274,7 @@ export class Handle extends ReadyResource {
       await this.store.call('add-writer', {
         sig,
         master: this.identity.publicKey,
-        writer: writerKey,
-        name: name || null,
-        isMobile: false
+        writer: writerKey
       })
       await this.store.call('add-member', member)
     })
@@ -316,7 +307,7 @@ export class Handle extends ReadyResource {
       new Handle({
         parent: this,
         spec: pickHandle(this.spec, type),
-        namespace: `cero/handle/${type}/${writer.id}`,
+        namespace: `${NS}/handle/${type}/${writer.id}`,
         routes,
         keyPair: writer
       })
@@ -332,9 +323,7 @@ export class Handle extends ReadyResource {
     await child.store.call('add-writer', {
       master: this.identity.publicKey,
       writer: writerKey,
-      sig: this.identity.sign(writerKey),
-      name,
-      isMobile: false
+      sig: this.identity.sign(writerKey)
     })
     await child.store.call('add-member', {
       id: this.identity.id,
@@ -344,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,
@@ -357,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
   }
 
@@ -372,7 +360,7 @@ export class Handle extends ReadyResource {
    * @returns {Promise<Handle>}
    */
   async _join(invite, type, { routes, timeout } = {}) {
-    const deadline = timeout || 30000
+    const deadline = timeout || TIMEOUT
 
     // Idempotent: if the invite targets a handle we already have, return it —
     // without pairing, so there's no waiting on a peer to confirm.
@@ -389,7 +377,7 @@ export class Handle extends ReadyResource {
       await Handle.join(invite, {
         parent: this,
         spec: pickHandle(this.spec, type),
-        namespace: `cero/handle/${type}/${randomNs()}`,
+        namespace: `${NS}/handle/${type}/${randomNs()}`,
         routes,
         timeout
       })
@@ -400,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
   }
 
@@ -439,7 +426,7 @@ export class Handle extends ReadyResource {
     const child = new Handle({
       parent: this,
       spec: pickHandle(this.spec, type),
-      namespace: `cero/handle/${type}/${id}`,
+      namespace: `${NS}/handle/${type}/${id}`,
       key: data.key,
       encryptionKey: data.encryptionKey,
       keyPair: /** @type {KeyPair} */ (writer)
@@ -456,6 +443,7 @@ export class Handle extends ReadyResource {
     }
     this._wireAccept(child)
     this.children.add(child)
+    this.emit('handle', child, {})
     return child
   }
 
@@ -503,7 +491,7 @@ export class Handle extends ReadyResource {
    */
   static async join(
     invite,
-    { parent, network, identity, store, spec, namespace, routes, timeout = 30000 } = {}
+    { parent, network, identity, store, spec, namespace, routes, timeout = TIMEOUT } = {}
   ) {
     const net = network || parent?.network
     const id = identity || parent?.identity
@@ -538,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]
@@ -601,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,12 +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'
 
@@ -65,7 +67,7 @@ export async function cero(dir, spec, opts = {}) {
   const network = new Network({ bootstrap: opts.bootstrap })
   await network.ready()
   const discovery = network.join(identity.topic)
-  await Promise.race([discovery.flush(), new Promise((r) => setTimeout(r, 500))])
+  await Promise.race([discovery.flush(), new Promise((r) => setTimeout(r, FLUSH))])
 
   const me = new Handle({
     storage,
@@ -109,12 +111,12 @@ export async function cero(dir, spec, opts = {}) {
       })
     }
   }
-  if (opts.recovery)
-    await me.recover({
-      timeout: opts.recoveryTimeout,
-      name: opts.name || null,
-      isMobile: opts.isMobile === true
-    })
+  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
 }
@@ -154,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/constants.js

@@ -0,0 +1,20 @@
+// Shared cero constants.
+
+export const NS = 'cero'
+export const COUNTERS = 'counters'
+
+// Writer-admission / pairing timeout (ms), and the initial discovery-flush wait (ms).
+export const TIMEOUT = 30000
+export const FLUSH = 500
+
+// schema-DSL primitive → HyperDB type (used by the builder).
+export const DB_TYPE = {
+  string: 'string',
+  uint: 'uint',
+  int: 'int',
+  bool: 'bool',
+  bytes: 'buffer',
+  json: 'json',
+  fixed32: 'fixed32',
+  fixed64: 'fixed64'
+}

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/build/builtins.d.ts

@@ -0,0 +1,88 @@
+export namespace refs {
+    namespace main {
+        namespace members {
+            let type: string;
+        }
+        namespace devices {
+            let type_1: string;
+            export { type_1 as type };
+        }
+        namespace invites {
+            let type_2: string;
+            export { type_2 as type };
+        }
+        namespace handles {
+            let type_3: string;
+            export { type_3 as type };
+        }
+    }
+    let local: {
+        master: {
+            type: string;
+            kind: string;
+        };
+        keypair: {
+            type: string;
+            kind: string;
+        };
+        'handle-keypairs': {
+            type: string;
+        };
+    };
+}
+export function hyperdbType(prim: any): any;
+export function builtinRefs(ns: any, scope: any): {
+    [k: string]: {
+        schema: string;
+        verb: any;
+        kind: any;
+        path: string[];
+        builtin: boolean;
+    };
+};
+export function builtinTypes(scope: any, extend: any): {
+    name: string;
+    compact: boolean;
+    fields: {
+        name: string;
+        type: any;
+        required: boolean;
+    }[];
+}[];
+export function rpcTypes(): {
+    name: string;
+    compact: boolean;
+    fields: {
+        name: string;
+        type: any;
+        required: boolean;
+    }[];
+}[];
+export function builtinCollections(ns: any, scope: any): {
+    name: string;
+    schema: string;
+    key: string[];
+}[];
+export function builtinDispatches(ns: any): {
+    name: string;
+    requestType: string;
+}[];
+export function rpcCommands(ns: any): ({
+    name: string;
+    request: {
+        name: string;
+    };
+    response: {
+        name: string;
+        stream?: undefined;
+    };
+} | {
+    name: string;
+    request: {
+        name: string;
+    };
+    response: {
+        name: string;
+        stream: boolean;
+    };
+})[];

package/types/build/schemas.d.ts

@@ -0,0 +1,153 @@
+export const main: {
+    'del-by-id': {
+        id: import("@cero-base/core/schema").Prim;
+    };
+    writer: {
+        master: import("@cero-base/core/schema").Prim;
+        writer: import("@cero-base/core/schema").Prim;
+        sig: import("@cero-base/core/schema").Prim;
+        isIndexer: import("@cero-base/core/schema").Prim;
+    };
+    counter: {
+        name: import("@cero-base/core/schema").Prim;
+        value: import("@cero-base/core/schema").Prim;
+    };
+    member: {
+        id: import("@cero-base/core/schema").Prim;
+        key: import("@cero-base/core/schema").Prim;
+        role: import("@cero-base/core/schema").Prim;
+        name: import("@cero-base/core/schema").Prim;
+        createdAt: import("@cero-base/core/schema").Prim;
+        updatedAt: import("@cero-base/core/schema").Prim;
+        sig: import("@cero-base/core/schema").Prim;
+        index: import("@cero-base/core/schema").Prim;
+    };
+    device: {
+        id: import("@cero-base/core/schema").Prim;
+        memberId: import("@cero-base/core/schema").Prim;
+        name: import("@cero-base/core/schema").Prim;
+        isMobile: import("@cero-base/core/schema").Prim;
+        createdAt: import("@cero-base/core/schema").Prim;
+        updatedAt: import("@cero-base/core/schema").Prim;
+        index: import("@cero-base/core/schema").Prim;
+    };
+    invite: {
+        id: import("@cero-base/core/schema").Prim;
+        invite: import("@cero-base/core/schema").Prim;
+        publicKey: import("@cero-base/core/schema").Prim;
+        data: import("@cero-base/core/schema").Prim;
+        sig: import("@cero-base/core/schema").Prim;
+        role: import("@cero-base/core/schema").Prim;
+        expires: import("@cero-base/core/schema").Prim;
+        createdAt: import("@cero-base/core/schema").Prim;
+        index: import("@cero-base/core/schema").Prim;
+    };
+    handle: {
+        id: import("@cero-base/core/schema").Prim;
+        type: import("@cero-base/core/schema").Prim;
+        key: import("@cero-base/core/schema").Prim;
+        encryptionKey: import("@cero-base/core/schema").Prim;
+        name: import("@cero-base/core/schema").Prim;
+        createdAt: import("@cero-base/core/schema").Prim;
+        updatedAt: import("@cero-base/core/schema").Prim;
+        index: import("@cero-base/core/schema").Prim;
+    };
+    claim: {
+        identity: import("@cero-base/core/schema").Prim;
+        writer: import("@cero-base/core/schema").Prim;
+        sig: import("@cero-base/core/schema").Prim;
+    };
+};
+export const local: {
+    master: {
+        seed: import("@cero-base/core/schema").Prim;
+    };
+    keypair: {
+        publicKey: import("@cero-base/core/schema").Prim;
+        secretKey: import("@cero-base/core/schema").Prim;
+    };
+    'handle-keypair': {
+        id: import("@cero-base/core/schema").Prim;
+        publicKey: import("@cero-base/core/schema").Prim;
+        secretKey: import("@cero-base/core/schema").Prim;
+        encryptionKey: import("@cero-base/core/schema").Prim;
+    };
+};
+export const rpc: {
+    'req-empty': {
+        ok: import("@cero-base/core/schema").Prim;
+    };
+    'req-restore': {
+        phrase: import("@cero-base/core/schema").Prim;
+    };
+    'req-row': {
+        handle: import("@cero-base/core/schema").Prim;
+        ref: import("@cero-base/core/schema").Prim;
+        data: import("@cero-base/core/schema").Prim;
+        local: import("@cero-base/core/schema").Prim;
+    };
+    'req-id': {
+        handle: import("@cero-base/core/schema").Prim;
+        ref: import("@cero-base/core/schema").Prim;
+        id: import("@cero-base/core/schema").Prim;
+        local: import("@cero-base/core/schema").Prim;
+    };
+    'req-query': {
+        handle: import("@cero-base/core/schema").Prim;
+        ref: import("@cero-base/core/schema").Prim;
+        query: import("@cero-base/core/schema").Prim;
+        local: import("@cero-base/core/schema").Prim;
+    };
+    'req-call': {
+        handle: import("@cero-base/core/schema").Prim;
+        op: import("@cero-base/core/schema").Prim;
+        data: import("@cero-base/core/schema").Prim;
+    };
+    'req-invite': {
+        handle: import("@cero-base/core/schema").Prim;
+        role: import("@cero-base/core/schema").Prim;
+    };
+    'req-revoke': {
+        handle: import("@cero-base/core/schema").Prim;
+        invite: import("@cero-base/core/schema").Prim;
+    };
+    'req-join': {
+        parent: import("@cero-base/core/schema").Prim;
+        ref: import("@cero-base/core/schema").Prim;
+        invite: import("@cero-base/core/schema").Prim;
+    };
+    'req-open': {
+        parent: import("@cero-base/core/schema").Prim;
+        row: import("@cero-base/core/schema").Prim;
+    };
+    'req-handle': {
+        handle: import("@cero-base/core/schema").Prim;
+    };
+    'res-data': {
+        data: import("@cero-base/core/schema").Prim;
+    };
+    'res-rows': {
+        data: import("@cero-base/core/schema").Prim;
+        total: import("@cero-base/core/schema").Prim;
+        size: import("@cero-base/core/schema").Prim;
+    };
+    'res-count': {
+        count: import("@cero-base/core/schema").Prim;
+    };
+    'res-invite': {
+        invite: import("@cero-base/core/schema").Prim;
+    };
+    'res-handle': {
+        id: import("@cero-base/core/schema").Prim;
+        type: import("@cero-base/core/schema").Prim;
+        name: import("@cero-base/core/schema").Prim;
+    };
+    'res-identity': {
+        id: import("@cero-base/core/schema").Prim;
+        deviceId: import("@cero-base/core/schema").Prim;
+        phrase: import("@cero-base/core/schema").Prim;
+    };
+    'res-ok': {
+        ok: import("@cero-base/core/schema").Prim;
+    };
+};

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

@@ -48,8 +48,6 @@ export { Ref } from "../lib/utils.js";
  *
  * @typedef {object} RecoverOpts
  * @property {number} [timeout]
- * @property {string | null} [name]
- * @property {boolean} [isMobile]
  *
  * @typedef {object} HandleExtra
  * @property {string | null} [name]                       Display name; set on child handles by the owner flow.
@@ -91,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. */
@@ -126,7 +123,7 @@ export class Handle extends ReadyResource {
      * @param {RecoverOpts} [opts]
      * @returns {Promise<void>}
      */
-    recover({ timeout, name, isMobile }?: RecoverOpts): Promise<void>;
+    recover({ timeout }?: RecoverOpts): Promise<void>;
     /**
      * Mint a pairing invite for this handle.
      *
@@ -205,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]
@@ -326,8 +322,6 @@ export type AcceptOpts = {
 };
 export type RecoverOpts = {
     timeout?: number;
-    name?: string | null;
-    isMobile?: boolean;
 };
 export type HandleExtra = {
     /**