@cero-base/cero 0.8.10 → 1.0.1

package/src/lib/operators.js

@@ -1,28 +1,54 @@
 import { Readable } from 'streamx'
 
-import { CeroError } from '@cero-base/core/errors'
-
+import { encodeId, decodeId } from '@cero-base/core/blobs/codec'
 import { onAbort } from './utils.js'
 
-// `peek` (below) lazy-imports hypercore-storage / corestore / local so this
-// module — which the lightweight RPC client re-exports — stays free of native
-// deps. A client never calls `peek`, so the heavy imports load only on the core.
-
 /**
  * @typedef {import('./utils.js').Ref} Ref
+ * @typedef {import('../handle/index.js').CeroHandle} CeroHandle
  * @typedef {{ data: any }} SingleResult
  * @typedef {{ data: any[], total: number, size: number }} ListResult
  * @typedef {{ data: any | null }} GetByIdResult
  */
 
 /**
- * Insert (or overwrite by id) a row on `ref`.
+ * Resolve a durable file id (+ optional name) to the read shape returned
+ * everywhere: `{ id, name?, type, size, url }`.
+ *
+ * @param {object} handle
+ * @param {string} id
+ * @param {string} [name]
+ * @returns {{ id: string, type: string, size: number, url: string, name?: string }}
+ */
+export function resolveFile(handle, id, name) {
+  const { type, blobId } = decodeId(id)
+  const file = { id, type, size: blobId.byteLength, url: handle.getLink(id) }
+  if (name != null) file.name = name
+  return file
+}
+
+/**
+ * Insert (or overwrite by id) a row on `ref`. The `files` builtin is special:
+ * `put(handle.files, { data, type, name? })` uploads the bytes to this handle's
+ * blob store, records `{ id, name }`, and returns the resolved file.
  *
  * @param {Ref} ref
  * @param {Record<string, any>} row
- * @returns {Promise<SingleResult>}
+ * @returns {Promise<SingleResult | { id: string, name?: string, type: string, size: number, url: string }>}
  */
-export const put = (ref, row) => ref.handle.store.put(ref.name, row)
+export const put = (ref, row) =>
+  ref.name === 'files' ? putFile(ref, row) : ref.handle.store.put(ref.name, row)
+
+async function putFile(ref, row) {
+  const handle = ref.handle
+  if (handle.rpc) return handle.put('files', row)
+  const { data, type, name = null } = row
+  await handle.blobs.ready()
+  const blobId = await handle.blobs.put(data)
+  const id = encodeId(handle.blobs.key, blobId, type)
+  await handle.store.call('add-file', { id, name })
+  return resolveFile(handle, id, name)
+}
 
 /**
  * Upsert a row on `ref` — merges with the existing row and preserves
@@ -82,8 +108,12 @@ export const before = (ref, fn, opts) => {
   const offs = ops.map((op) =>
     db.before(op, (ctx) => (ctx.name === ref.name ? fn(ctx) : undefined))
   )
-  const off = () => offs.forEach((unsub) => unsub())
-  onAbort(opts?.signal, off)
+  let stopAbort
+  const off = () => {
+    offs.forEach((unsub) => unsub())
+    stopAbort?.()
+  }
+  stopAbort = onAbort(opts?.signal, off)
   return off
 }
 
@@ -102,8 +132,12 @@ export const after = (ref, fn, opts) => {
   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)
-  const off = () => ops.forEach((op) => db.off(`after:${op}`, handler))
-  onAbort(opts?.signal, off)
+  let stopAbort
+  const off = () => {
+    ops.forEach((op) => db.off(`after:${op}`, handler))
+    stopAbort?.()
+  }
+  stopAbort = onAbort(opts?.signal, off)
   return off
 }
 
@@ -118,6 +152,49 @@ const normalize = (rows, name) => {
   return { data, total: data.length, size: data.length }
 }
 
+function resolveResult(ref, res) {
+  if (res == null || res.data == null) return res
+  const data = Array.isArray(res.data)
+    ? res.data.map((row) => resolveRow(ref, row))
+    : resolveRow(ref, res.data)
+  return { ...res, data }
+}
+
+function resolveRow(ref, row) {
+  if (!row || typeof row !== 'object') return row
+  if (ref.handle.rpc) return ref.handle._resolveRow(ref.name, ref.handle._refInfo(ref.name), row)
+  const handle = ref.handle
+  const resolve = (id, name) => {
+    registerBlobCore(handle, id)
+    return resolveFile(handle, id, name)
+  }
+  if (ref.name === 'files') {
+    return { ...row, ...resolve(row.id, row.name) }
+  }
+  const fields = handle.store.refs?.[ref.name]?.files
+  if (!fields || !fields.length) return row
+  const out = { ...row }
+  for (const f of fields) {
+    const v = out[f]
+    if (v == null) continue
+    out[f] = resolve(v)
+  }
+  return out
+}
+
+function registerBlobCore(handle, id) {
+  if (!id || !handle.root?._coreKeys) return
+  try {
+    const { coreKey } = decodeId(id)
+    const hex = Buffer.from(coreKey).toString('hex')
+    if (!handle.root._coreKeys.has(hex)) {
+      handle.root._coreKeys.set(hex, handle.root.store.encryptionKey)
+    }
+  } catch {
+    // ignore invalid ids
+  }
+}
+
 /**
  * Read from `ref`. For data refs, dispatches to the underlying store. For
  * `handle`-kind refs, lists existing child handles of that type from the
@@ -128,16 +205,22 @@ const normalize = (rows, name) => {
  * @returns {Promise<SingleResult | ListResult | GetByIdResult>}
  */
 export const get = async (ref, q) => {
-  if (ref.kind !== 'handle') return ref.handle.store.get(ref.name, q)
-  const { data: all } = await parentStore(ref).get('handles', q)
-  return normalize(all, ref.name)
+  if (ref.kind === 'handle') {
+    const { data } = await parentStore(ref).get('handles', q)
+    return normalize(data, ref.name)
+  }
+  const res = await ref.handle.store.get(ref.name, q)
+  return resolveResult(ref, res)
 }
 
 // Tie a fresh watch stream to its handle's lifecycle (destroyed on close) and
 // to an optional `{ signal }` (destroyed on abort). Local refs have no
 // close-cascade, so they keep managing their own streams.
 const bindStream = (owner, stream, opts) => {
-  onAbort(opts?.signal, () => stream.destroy())
+  const stopAbort = onAbort(opts?.signal, () => stream.destroy())
+  // drop the abort listener once the stream ends, so it doesn't linger on a
+  // long-lived signal after the stream is gone
+  if (stopAbort) stream.once('close', stopAbort)
   return owner.own ? owner.own(stream) : stream
 }
 
@@ -154,7 +237,19 @@ const bindStream = (owner, stream, opts) => {
  */
 export const watch = (ref, q, opts) => {
   const owner = ref.handle
-  if (ref.kind !== 'handle') return bindStream(owner, owner.store.watch(ref.name, q), opts)
+  if (ref.kind !== 'handle') {
+    const src = owner.store.watch(ref.name, q)
+    const out = new Readable({
+      destroy(cb) {
+        src.destroy()
+        cb(null)
+      }
+    })
+    src.on('data', (res) => out.push(resolveResult(ref, res)))
+    src.on('end', () => out.push(null))
+    src.on('error', (err) => out.destroy(err))
+    return bindStream(owner, out, opts)
+  }
   const source = parentStore(ref).watch('handles', q)
   const out = new Readable({
     destroy(cb) {
@@ -184,7 +279,7 @@ export const watch = (ref, q, opts) => {
  *
  * @param {Ref} ref
  * @param {string | { invite?: string, id?: string, name?: string, routes?: any, role?: string, accept?: boolean } | undefined} [arg]
- * @returns {Promise<any>}  The resolved child `Handle`.
+ * @returns {Promise<CeroHandle>}  The resolved child handle.
  */
 export const open = (ref, arg) => {
   if (typeof arg === 'string') return ref.handle._join(arg, ref.name)
@@ -193,40 +288,6 @@ export const open = (ref, arg) => {
   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 { default: HypercoreStorage } = await import('hypercore-storage')
-  const { default: Corestore } = await import('corestore')
-  const { Local } = await import('../local/index.js')
-
-  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`

package/src/lib/peek.js

@@ -0,0 +1,42 @@
+import HypercoreStorage from 'hypercore-storage'
+import Corestore from 'corestore'
+import safetyCatch from 'safety-catch'
+
+import { CeroError } from '@cero-base/core/errors'
+
+import { Local } from '../local/index.js'
+
+// Lives outside operators.js so the storage deps stay off the RPC client's
+// module graph — bundlers follow even dynamic imports, and a browser build
+// must never reach hypercore/sodium.
+
+/**
+ * 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')
+
+  // Construct first (cheap), ready inside the try — a corrupt dir that throws in
+  // any ready() must still close root + store + local, not leak the storage lock.
+  const root = new HypercoreStorage(`${dir}/main`)
+  const store = new Corestore(root, { manifestVersion: 2 })
+  const local = new Local(null, spec, { store })
+  try {
+    await root.ready()
+    await store.ready()
+    await local.ready()
+    const { data } = await local.store.get('master')
+    return !!data?.seed
+  } finally {
+    await local.close().catch(safetyCatch)
+    await store.close().catch(safetyCatch)
+    await root.close().catch(safetyCatch)
+  }
+}

package/src/lib/utils.js

@@ -1,3 +1,5 @@
+import { CeroError } from '@cero-base/core/errors'
+
 /**
  * @typedef {'collection' | 'single' | 'action' | 'handle'} RefKind
  * @typedef {{ kind?: string, schema?: string }} RefInfo
@@ -36,19 +38,30 @@ export class Ref {
  */
 export function attachRefs(target, refs) {
   for (const [name, info] of Object.entries(refs || {})) {
+    // Fail loud rather than silently overwrite a method/property (close, on,
+    // store, …) when a schema declares a ref named like a reserved member.
+    if (name in target) {
+      throw CeroError.INVALID(
+        `schema ref '${name}' collides with a reserved ${target.constructor?.name || 'handle'} member — rename it`
+      )
+    }
     target[name] = new Ref(target, name, info.kind, info.schema)
   }
 }
 
 /**
  * Run `cb` when `signal` aborts — or immediately if it already has. No-op
- * without a signal. The listener removes itself on fire.
+ * without a signal. The listener removes itself on fire. Returns a disposer that
+ * detaches the listener early, so a manual unsubscribe doesn't leave it lingering
+ * on a long-lived signal.
  *
- * @param {AbortSignal} [signal]
+ * @param {AbortSignal | undefined} signal
  * @param {() => void} cb
+ * @returns {(() => void) | undefined}
  */
 export function onAbort(signal, cb) {
   if (!signal) return
-  if (signal.aborted) return cb()
+  if (signal.aborted) return void cb()
   signal.addEventListener('abort', cb, { once: true })
+  return () => signal.removeEventListener('abort', cb)
 }

package/src/rpc/client.js

@@ -1,5 +1,8 @@
 import { Readable } from 'streamx'
 import { RPCClient, bindCodec } from '@cero-base/core/rpc'
+import c from 'compact-encoding'
+import z32 from 'z32'
+import { decodeId } from '@cero-base/core/blobs/codec'
 
 import { attachRefs } from '../lib/utils.js'
 import { put, set, get, del, count, watch, call, open, bind, define } from '../lib/operators.js'
@@ -32,6 +35,30 @@ export { put, set, get, del, count, watch, call, open, bind, define, t, schema }
  * @property {string|null} name
  */
 
+// Compact-encoding blobId struct matching hypercore-blob-server's wire format.
+const blobIdEnc = {
+  preencode(state, b) {
+    c.uint.preencode(state, b.blockOffset)
+    c.uint.preencode(state, b.blockLength)
+    c.uint.preencode(state, b.byteOffset)
+    c.uint.preencode(state, b.byteLength)
+  },
+  encode(state, b) {
+    c.uint.encode(state, b.blockOffset)
+    c.uint.encode(state, b.blockLength)
+    c.uint.encode(state, b.byteOffset)
+    c.uint.encode(state, b.byteLength)
+  },
+  decode(state) {
+    return {
+      blockOffset: c.uint.decode(state),
+      blockLength: c.uint.decode(state),
+      byteOffset: c.uint.decode(state),
+      byteLength: c.uint.decode(state)
+    }
+  }
+}
+
 // Mixin applied to Client, Handle and LocalRefs so they expose the same
 // row-ops surface as a local cero handle but routed over the wire. `_local`
 // selects the per-device store + JSON codec; main refs use the schema codec.
@@ -54,6 +81,67 @@ const operators = {
     return this._refInfo(name)?.schema
   },
 
+  /**
+   * Build a renderable URL for a file id using the base + token learned at init.
+   *
+   * @param {string} id
+   * @returns {string}
+   */
+  url(id) {
+    const root = this.parent || this
+    const base = root._fileBase || ''
+    const token = root._fileToken || ''
+    const { coreKey, blobId, type } = decodeId(id)
+    const key = z32.encode(coreKey)
+    const blob = z32.encode(c.encode(blobIdEnc, blobId))
+    const tp = type ? `&type=${encodeURIComponent(type)}` : ''
+    const tok = token ? `&token=${token}` : ''
+    return `${base}/?key=${key}&blob=${blob}${tp}${tok}`
+  },
+
+  /**
+   * Augment a decoded row (or array of rows) to resolve file-typed fields to
+   * `{ id, type, size, url }` objects. The `files` builtin's own `id` is the
+   * file id; other refs declare file fields in `meta.refs[name].files`.
+   *
+   * @param {string} name
+   * @param {any} data
+   * @returns {any}
+   */
+  _resolveFiles(name, data) {
+    if (data == null) return data
+    const info = this._refInfo(name)
+    if (Array.isArray(data)) return data.map((row) => this._resolveRow(name, info, row))
+    return this._resolveRow(name, info, data)
+  },
+
+  _resolveRow(name, info, row) {
+    if (!row || typeof row !== 'object') return row
+    if (info?.builtin && info?.verb === 'file') {
+      if (!row.id) return row
+      try {
+        const { type, blobId } = decodeId(row.id)
+        return { ...row, type, size: blobId.byteLength, url: this.url(row.id) }
+      } catch {
+        return row
+      }
+    }
+    const fileFields = info?.files
+    if (!fileFields || !fileFields.length) return row
+    const out = { ...row }
+    for (const f of fileFields) {
+      const v = out[f]
+      if (v == null) continue
+      try {
+        const { type, blobId } = decodeId(v)
+        out[f] = { id: v, type, size: blobId.byteLength, url: this.url(v) }
+      } catch {
+        // leave as-is if not a valid file id
+      }
+    }
+    return out
+  },
+
   /**
    * Insert a row over the wire.
    *
@@ -64,6 +152,16 @@ const operators = {
   async put(name, row) {
     const codec = this._codec()
     const schema = this.schemaOf(name)
+    if (row && row.data != null) {
+      const res = await this.rpc.addFile({
+        handle: this.id,
+        data: row.data,
+        name: row.name || '',
+        type: row.type || ''
+      })
+      const decoded = codec.decodeRow(schema, res.data)
+      return { data: this._resolveRow(name, this._refInfo(name), decoded) }
+    }
     const input = row?.id ? row : { id: '', ...row }
     const res = await this.rpc.addRow({
       handle: this.id,
@@ -75,20 +173,22 @@ const operators = {
   },
 
   /**
-   * Upsert a row over the wire.
+   * Upsert a row over the wire. Pass `{ upsert: false }` to update-only.
    *
    * @param {string} name
    * @param {Record<string, any>} row
+   * @param {{ upsert?: boolean }} [opts]
    * @returns {Promise<SingleResult>}
    */
-  async set(name, row) {
+  async set(name, row, opts) {
     const codec = this._codec()
     const schema = this.schemaOf(name)
     const res = await this.rpc.set({
       handle: this.id,
       ref: name,
       data: codec.encodeRow(schema, row),
-      local: this._local
+      local: this._local,
+      noUpsert: opts?.upsert === false || undefined
     })
     return { data: codec.decodeRow(schema, res.data) }
   },
@@ -111,7 +211,8 @@ const operators = {
         id: query,
         local: this._local
       })
-      return { data: res.data ? codec.decodeRow(schema, res.data) : null }
+      const decoded = res.data ? codec.decodeRow(schema, res.data) : null
+      return { data: this._resolveFiles(name, decoded) }
     }
     const res = await this.rpc.get({
       handle: this.id,
@@ -119,11 +220,12 @@ const operators = {
       query: codec.encodeQuery(query),
       local: this._local
     })
-    const data =
-      this._refInfo(name)?.kind === 'single'
+    const info = this._refInfo(name)
+    const raw =
+      info?.kind === 'single'
         ? codec.decodeRow(schema, res.data)
         : codec.decodeRows(schema, res.data)
-    return { data, total: res.total, size: res.size }
+    return { data: this._resolveFiles(name, raw), total: res.total, size: res.size }
   },
 
   /**
@@ -179,13 +281,21 @@ const operators = {
       }
     })
     wire.on('data', (snap) => {
-      const data =
+      const raw =
         refInfo.kind === 'single'
           ? (codec.decodeRow(schema, snap.data) ?? null)
           : codec.decodeRows(schema, snap.data)
-      out.push({ data, total: snap.total, size: snap.size })
+      out.push({ data: this._resolveFiles(name, raw), total: snap.total, size: snap.size })
     })
-    wire.on('end', () => out.push(null))
+    // end exactly once whether the wire ends or the server destroys it (handle close)
+    let ended = false
+    const end = () => {
+      if (ended || out.destroyed) return
+      ended = true
+      out.push(null)
+    }
+    wire.on('end', end)
+    wire.on('close', end)
     wire.on('error', (err) => out.destroy(err))
     return out
   },
@@ -239,7 +349,7 @@ export async function restore(me, phrase) {
   const res = await me.rpc.restore({ phrase })
   me.id = res.id
   me.deviceId = res.deviceId || null
-  me.identity = { id: res.id, toPhrase: () => res.phrase || null }
+  me.identity = { id: res.id, toPhrase: async () => (await me.rpc.seed({})).phrase || null }
   return me
 }
 
@@ -295,10 +405,12 @@ export class Client extends RPCClient {
 
   async _open() {
     await super._open()
-    const { id, deviceId, phrase } = await this.rpc.init({})
+    const { id, deviceId, fileBase, fileToken } = await this.rpc.init({})
     this.id = id
     this.deviceId = deviceId || null
-    this.identity = { id, toPhrase: () => phrase || null }
+    this._fileBase = fileBase || ''
+    this._fileToken = fileToken || ''
+    this.identity = { id, toPhrase: async () => (await this.rpc.seed({})).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)
@@ -312,10 +424,12 @@ export class Client extends RPCClient {
    * @returns {Promise<Handle>}
    */
   async _create(type, opts = {}) {
+    // `routes` are functions and can't cross the wire; role/accept now do.
+    const wire = { ...opts, noAccept: opts.accept === false || undefined }
     const stub = await this.rpc.addHandle({
       ref: type,
       handle: this.id,
-      data: this.spec.codec.encodeCreate(opts)
+      data: this.spec.codec.encodeCreate(wire)
     })
     return new Handle(this, stub.id, stub.type, stub.name || null)
   }