@cero-base/cero 1.19.0 → 2.1.0

package/src/index.js

@@ -17,21 +17,18 @@ import {
   set,
   get,
   del,
-  count,
   watch,
   changes,
   call,
   open,
   rotate,
   before,
-  after,
-  bind,
-  define
+  after
 } from './lib/operators.js'
 import { peek } from './lib/peek.js'
 import { t, schema } from './lib/spec.js'
 import { FLUSH, TIMEOUT } from './lib/constants.js'
-import { internal } from './lib/internal.js'
+import { bind } from './extensions/index.js'
 
 export { Handle, Ref, Local }
 export {
@@ -39,16 +36,13 @@ export {
   set,
   get,
   del,
-  count,
   watch,
   changes,
   call,
   open,
   rotate,
   before,
-  after,
-  bind,
-  define
+  after
 } from './lib/operators.js'
 export { peek } from './lib/peek.js'
 export { t, schema } from './lib/spec.js'
@@ -69,20 +63,20 @@ export { t, schema } from './lib/spec.js'
  * @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'`.
  */
 
 /**
- * Open (or create) a cero handle at `dir`. Sets up storage, network and
- * identity, then returns a ready root `Handle` with all schema refs
- * attached as properties.
+ * Open (or create) a cero handle at `dir`.
  *
  * @param {string} dir       Data directory.
  * @param {any} spec         Built spec — output of `cero/build`.
@@ -99,9 +93,7 @@ export async function cero(dir, spec, opts = {}) {
   let network = null
   let discovery = null
   let me = null
-  // Any failure during open (bad phrase, network/bootstrap error, recovery
-  // timeout, extension setup) must close whatever opened — else the corestore
-  // lock leaks and a retry in the same process hits locked storage.
+  // any failure during open must close what opened, or the storage lock leaks
   try {
     await storage.ready()
     await fs.promises.chmod(`${dir}/main`, 0o700)
@@ -115,15 +107,11 @@ export async function cero(dir, spec, opts = {}) {
 
     const { identity, fresh } = await resolveIdentity(opts, local)
     const writer = local ? (await local.store.get('keypair')).data : null
-    // a supplied identity on a device with no writer is recovering: it never
-    // authors the identity's pointer core or any core that exists elsewhere.
-    // Only an identity cero generated here creates a database
+    // a supplied identity on a device with no writer recovers; only a cero-minted identity creates
     const recovering = !writer && (!!opts.key || !fresh)
     const timeout = opts.recoveryTimeout || TIMEOUT
 
-    // Channel stamp: a storage remembers its channel; reopening it under a different channel —
-    // including no channel at all, which would silently rejoin the global network — is a
-    // misconfiguration that could leak data across networks, so reject it.
+    // a storage remembers its channel; reopening under another would silently rejoin the global network
     if (local) {
       const stored = (await local.store.get('environment')).data?.channel ?? null
       const wanted = opts.channel ?? null
@@ -137,17 +125,15 @@ export async function cero(dir, spec, opts = {}) {
       backoffs: opts.backoffs,
       channel: opts.channel,
       store,
-      mirrors: opts.mirrors
+      mirrors: opts.mirrors,
+      presence: opts.presence
     })
     await network.ready()
     discovery = network.join(identity.topic)
-    // a freshly minted identity has no peers yet — flushing the announce
-    // before proceeding only delays first onboarding
+    // a fresh identity has no peers yet, flushing the announce would only delay onboarding
     if (!fresh) await Promise.race([discovery.flush(), new Promise((r) => setTimeout(r, FLUSH))])
 
-    // the pointer core: signed by the identity, written once by the device that
-    // created the identity, read by every device that recovers it. It holds the
-    // root database key, so a phrase alone finds the data
+    // the pointer core: identity-signed, written once by the creating device, holds the root key
     const manifest = pointerManifest(store, identity)
     const pointer = store.get(
       !writer && !recovering
@@ -194,39 +180,20 @@ export async function cero(dir, spec, opts = {}) {
           secretKey: result.writer.secretKey
         })
       }
-      if (!recovering) {
-        const ts = Date.now()
-        await me.store.call('add-member', {
-          id: identity.id,
-          key: me.store.writerKey,
-          role: 'owner',
-          name: opts.name || null,
-          createdAt: ts,
-          updatedAt: ts
-        })
-        if (pointer.length === 0) await pointer.append(c.encode(c.fixed32, me.store.key))
+      if (!recovering && pointer.length === 0) {
+        await pointer.append(c.encode(c.fixed32, me.store.key))
       }
     }
 
-    for (const ext of internal.extensions) {
-      if (ext.bundled && opts.extensions === false) continue
+    for (const ext of me.extensions) {
       const off = await ext.setup?.(me)
       if (typeof off === 'function') me.once('close', off)
     }
 
     if (opts.bluetooth) {
-      // `true` → defaults; `{ autoStart, backend }` → options. A bare backend
-      // object (pre-1.3 shape, has Central/Server) is still accepted.
-      const bt =
-        opts.bluetooth === true
-          ? {}
-          : opts.bluetooth.Central
-            ? { backend: opts.bluetooth }
-            : opts.bluetooth
+      const bt = opts.bluetooth === true ? {} : opts.bluetooth
       me.bluetooth = new Bluetooth(me, {
-        // pass the backend through untouched: `|| null` turned an omitted
-        // backend (= lazy-load bare-bluetooth) into an explicit null
-        // (= disabled), leaving BLE 'unsupported' on every platform
+        // an omitted backend lazy-loads bare-bluetooth, null disables it
         backend: bt.backend,
         autoStart: bt.autoStart !== false,
         maxOutbound: bt.maxOutbound,
@@ -237,11 +204,10 @@ export async function cero(dir, spec, opts = {}) {
       await me.bluetooth.ready()
     }
 
-    bind(me, null)
+    bind(me, null, me.operators)
     return me
   } catch (err) {
-    // once the root Handle exists it owns (and closes) everything; before that,
-    // tear the raw resources down in reverse order.
+    // before the root Handle exists, tear the raw resources down in reverse order
     if (me) await me.close().catch(safetyCatch)
     else {
       await discovery?.destroy().catch(safetyCatch)
@@ -255,9 +221,7 @@ export async function cero(dir, spec, opts = {}) {
 }
 
 /**
- * Restore a cero instance from a mnemonic phrase. Closes the running
- * instance, wipes the on-disk `main/` tree and re-opens with the phrase, which
- * recovers so the writer slot is re-claimed.
+ * Restore a cero instance from a mnemonic phrase.
  *
  * @param {Handle} me   Existing root handle to restore.
  * @param {string} phrase   BIP-39 mnemonic phrase.
@@ -267,12 +231,10 @@ export async function restore(me, phrase) {
   if (!me?._dir) throw CeroError.INVALID('me must be a cero instance')
   if (!phrase || typeof phrase !== 'string') throw CeroError.INVALID('phrase must be a string')
 
-  // Already this identity? Nothing to restore — return the running instance.
   const current = await Identity.fromSeed(Identity.toSeed(phrase))
   if (current.id === me.identity.id) return me
 
-  // everything carries over except the old identity — the channel in
-  // particular, or the recovered instance never meets its peers
+  // everything carries over except the identity, the channel above all
   const {
     _dir: dir,
     spec,
@@ -285,15 +247,12 @@ export async function restore(me, phrase) {
   return cero(dir, spec, { ...opts, phrase })
 }
 
-// Facade: expose the operators + helpers as properties on `cero` too, so both
-// `import { define }` and `cero.define(...)` work. Explicit assignments (not
-// `Object.assign`) so tsc reflects them onto the `cero` namespace in the .d.ts.
+// the facade: cero.put and import { put } are the same function
 cero.t = t
 cero.put = put
 cero.set = set
 cero.get = get
 cero.del = del
-cero.count = count
 cero.watch = watch
 cero.changes = changes
 cero.call = call
@@ -304,22 +263,6 @@ cero.after = after
 cero.peek = peek
 cero.restore = restore
 cero.schema = schema
-cero.bind = bind
-cero.define = define
-// test-only escape hatch (cross-package tests reset/seed the registry)
-cero._internal = internal
-// A bare function is shorthand for a behavior-only extension: `{ setup: fn }`.
-// Accepts both `use(a, b)` and `use([a, b])` (and a mix) for easier composition.
-// A named extension replaces any registered one with the same name — so
-// `use(profileSync({ fields }))` reconfigures the bundled default instead of
-// doubling it.
-cero.use = (...exts) => {
-  for (const e of exts.flat().map((e) => (typeof e === 'function' ? { setup: e } : e))) {
-    const i = e.name ? internal.extensions.findIndex((x) => x.name === e.name) : -1
-    if (i >= 0) internal.extensions[i] = e
-    else internal.extensions.push(e)
-  }
-}
 
 function pointerManifest(store, identity) {
   return { version: store.manifestVersion, signers: [{ publicKey: identity.publicKey }] }

package/src/lib/bluetooth.js

@@ -8,19 +8,8 @@ import { Pairing } from '@cero-base/core/pairing'
 import { Invite } from '@cero-base/core/invite'
 
 /**
- * `me.bluetooth` — the app-facing surface for nearby (Bluetooth) sync, a thin
- * facade over ble-swarm. Bluetooth only changes how peers meet and carry
- * bytes; capability-gated replication still decides what syncs. Discovery is
- * one topic-derived service UUID at a time (tag `cero-ble`) — the data service
- * sits on a fixed per-tag UUID, so switching topics only retunes the radio.
- *
- * ```js
- * const me = await cero(dir, spec, { channel, bluetooth: true })
- * me.bluetooth.state          // 'unsupported' | 'unauthorized' | 'off' | 'waiting' | 'starting' | 'on'
- * await me.bluetooth.start()
- * me.bluetooth.peers          // Map of live BLE links
- * me.bluetooth.on('update', () => {})
- * ```
+ * `me.bluetooth` — the app-facing surface for nearby (Bluetooth) sync, a thin facade over
+ * ble-swarm.
  *
  * @extends ReadyResource
  */
@@ -43,14 +32,11 @@ export class Bluetooth extends ReadyResource {
     this._restorePending = false
 
     const identity = handle.identity
-    // the mesh topic: one per channel, or a fixed global topic when
-    // channelless — any nearby cero device links (global nearby; strangers
-    // still sync zero bytes, replication is capability-gated)
+    // one mesh topic per channel, or a global one when channelless; strangers still sync nothing
     this._topic = crypto.hash(b4a.from(handle.network.channel || 'cero-ble'))
     this.swarm = new BluetoothSwarm({
       backend,
-      // injected links authenticate with the same long-lived identity as the
-      // swarm, so one person reached over Wi-Fi and BLE dedupes to one peer
+      // the swarm identity, so one person over Wi-Fi and BLE dedupes to one peer
       keyPair: { publicKey: identity.publicKey, secretKey: identity.secretKey },
       topic: this._topic,
       tag: 'cero-ble',
@@ -59,9 +45,7 @@ export class Bluetooth extends ReadyResource {
       maxInbound
     })
     this.swarm.on('update', () => {
-      // an ended rendezvous retunes back to the mesh only once its links
-      // drain — retuning drops links, and the pairing link still carries
-      // the joiner's initial replication
+      // retune to the mesh only once the pairing link's initial replication drained
       if (this._restorePending && this.swarm.peers.size === 0) {
         this._restorePending = false
         this.swarm.setTopic(this._topic).catch(safetyCatch)
@@ -69,7 +53,6 @@ export class Bluetooth extends ReadyResource {
       this.emit('update')
     })
     this.swarm.on('connection', (conn) => {
-      // the same treatment as any transport: wakeup, replication, pairing
       this._handle.network.inject(conn)
     })
   }
@@ -88,6 +71,11 @@ export class Bluetooth extends ReadyResource {
     if (this._autoStart) await this.start()
   }
 
+  async _close() {
+    this._clearAnnounce()
+    await this.swarm.destroy()
+  }
+
   /**
    * Begin advertising + scanning. Idempotent; no-op when unsupported.
    *
@@ -98,34 +86,20 @@ export class Bluetooth extends ReadyResource {
   }
 
   /**
-   * Stop advertising/scanning and drop links; open invite rendezvous end with
-   * the radio. Idempotent. Local data and the rest of the network (DHT) are
-   * untouched.
+   * Stop advertising/scanning and drop links; open invite rendezvous end with the radio.
    *
    * @returns {Promise<void>}
    */
   async stop() {
     this._clearAnnounce()
     await this.swarm.stop()
-    // while stopped setTopic just sticks — the next start() is back on the
-    // mesh. A start() + announce() that landed during the await wins.
+    // while stopped setTopic sticks; a start() + announce() during the await wins
     if (!this._announce) await this.swarm.setTopic(this._topic)
   }
 
   /**
-   * Offline join rendezvous: retune the radio to the invite-derived topic so
-   * holder and joiner find each other with zero DHT. One topic at a time —
-   * announcing a new invite replaces the previous rendezvous. Returns a stop
-   * function — closing the QR must stop the rendezvous so a photographed
-   * invite doesn't stay an ambient discovery beacon (admission itself is
-   * always gated by blind-pairing verifying the invite). The retune back to
-   * the mesh topic waits for live links to drain: the link a join just
-   * established survives and carries the joiner's initial replication.
-   * Auto-stops at the invite's expiry, on `stop()`, and on close.
-   *
-   * Only active while nearby sync is on: before `start()` (and after `stop()`)
-   * this is a no-op — the user controls the radio, and a join must not touch
-   * Bluetooth (OS permissions, GATT server) they never enabled.
+   * Offline join rendezvous: retune the radio to the invite-derived topic so holder and
+   * joiner find each other with zero DHT.
    *
    * @param {string} invite  Z32 invite string.
    * @returns {() => void}
@@ -161,20 +135,6 @@ export class Bluetooth extends ReadyResource {
     }
   }
 
-  _stopAnnounce() {
-    this._clearAnnounce()
-    if (this.swarm.peers.size > 0) this._restorePending = true
-    else this.swarm.setTopic(this._topic).catch(safetyCatch)
-  }
-
-  _clearAnnounce() {
-    const e = this._announce
-    if (!e) return
-    if (e.timer) clearTimeout(e.timer)
-    this._announce = null
-    this._restorePending = false
-  }
-
   /**
    * Host-lifecycle pause (app backgrounded): radio down, user intent kept.
    *
@@ -193,8 +153,17 @@ export class Bluetooth extends ReadyResource {
     await this.swarm.resume()
   }
 
-  async _close() {
+  _stopAnnounce() {
     this._clearAnnounce()
-    await this.swarm.destroy()
+    if (this.swarm.peers.size > 0) this._restorePending = true
+    else this.swarm.setTopic(this._topic).catch(safetyCatch)
+  }
+
+  _clearAnnounce() {
+    const e = this._announce
+    if (!e) return
+    if (e.timer) clearTimeout(e.timer)
+    this._announce = null
+    this._restorePending = false
   }
 }

package/src/lib/constants.js

@@ -1,5 +1,3 @@
-// Shared cero constants.
-
 export const NS = 'cero'
 export const COUNTERS = 'counters'
 export const EPOCHS = 'epochs'
@@ -7,16 +5,3 @@ export const EPOCHS = 'epochs'
 // 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',
-  file: 'string'
-}