@cero-base/cero 0.8.9 → 1.0.1

package/README.md

@@ -56,6 +56,7 @@ Ships with TypeScript declarations (`.d.ts`) generated from JSDoc.
 | `recoveryTimeout`   | Bound on the recovery wait.                                                                                                                                                                                                                            |
 | `routes`            | Custom action handlers keyed by route name.                                                                                                                                                                                                            |
 | `encryptionKey`     | Override the per-identity encryption key.                                                                                                                                                                                                              |
+| `onerror`           | Called with background/async failures that would otherwise be swallowed (failed after-hooks, `onApply` callbacks, pairing candidate errors); the app decides how to log or report them.                                                                |
 
 Reads `me.id`, `me.device`, `me.identity` for canonical metadata. `me.identity.toPhrase()` renders the seed phrase.
 
@@ -85,6 +86,15 @@ const recovered = await cero.restore(me, 'twelve words …')
 | `{ … }` (plain object)     | a child handle — its own scope, share by invite |
 | `local: { … }`             | device-only — never leaves this device          |
 
+A collection can declare **secondary indexes** for fast exact-field lookups:
+
+```js
+cero.t.collection(
+  { text: cero.t.string },
+  { indexes: { 'by-text': ['text'] } } // name → field(s); query via `cero.get(ref, { text: '…' })`
+)
+```
+
 ## Operators
 
 Every operator takes a `ref` (e.g. `me.profile`, `room.messages`) as the first arg.
@@ -95,8 +105,9 @@ Append a row to a collection. Generates an `id`, `createdAt`, and `updatedAt` if
 
 ```js
 const { data } = await cero.put(room.messages, { text: 'hi' })
-data.id // → 'abc…'
-data.memberId // ← stamped automatically by the writer→member backlink
+data.id // → 'abc…'  (plus createdAt / updatedAt)
+// `memberId` (the writer→member backlink) is stamped in the apply layer, so it
+// surfaces on a later `cero.get`, not on the row this call returns.
 ```
 
 ### `cero.set(ref, row)`
@@ -110,19 +121,30 @@ await cero.set(room.messages, { id: 'abc', text: 'edited' }) // upsert by id
 
 ### `cero.get(ref, q?)`
 
-Read. Three shapes depending on `q`:
+Read. The shape of `q` decides what comes back:
 
 ```js
 const { data } = await cero.get(me.profile) // single → the row (or null)
 const { data } = await cero.get(room.messages, 'abc') // by id  → the row (or null)
+
+// collection → paginated, with range filters
 const { data, total, size } = await cero.get(room.messages, {
-  gt: 'm-2025', // filters: gt / gte / lt / lte
+  gt: 'm-2025', // range: gt / gte / lt / lte
   limit: 20,
   reverse: true
-}) // collection → paginated
+})
+
+// search → case-insensitive substring across string fields
+const { data } = await cero.get(room.messages, { search: 'jo sm' })
+// every space-separated term must match (AND); folds case + diacritics ('jose' ⇢ 'José').
+// `fields` restricts which fields are searched (default: all string fields):
+const { data } = await cero.get(room.guests, { search: 'jose', fields: ['name'] })
+
+// exact field match → routed through a declared secondary index when the field has one
+const { data } = await cero.get(room.messages, { text: 'alpha' })
 ```
 
-`total` is the unfiltered row count; `size` is what came back after `limit`.
+`total` is the unfiltered row count; `size` is what came back after `limit`. `search` and exact-field filters compose with `limit` / `reverse`, and `cero.count(ref, q)` honors them too.
 
 ### `cero.del(ref, id)`
 
@@ -146,9 +168,9 @@ A Readable stream that re-emits the latest snapshot on every change. Always emit
 
 ```js
 const stream = cero.watch(room.messages, { limit: 50, reverse: true })
-stream.on('data', ({ data, total, size }) => {
+for await (const { data, total, size } of stream) {
   /* render */
-})
+}
 // stops on room.close(), on stream.destroy(), or on `signal` abort:
 const ac = new AbortController()
 cero.watch(room.messages, null, { signal: ac.signal }) // ac.abort() ⇒ destroyed
@@ -191,6 +213,53 @@ cero.after(me.profile, ({ row }) => {
 
 `ctx` is `{ op, name, row }` (plus `result` in `after`).
 
+## Files
+
+Store a file (avatar, image, attachment) and get a ready-to-render URL. Bytes live in a per-handle blob core — replicated to members on demand, never inlined into the log — so rows carry only a small self-describing id.
+
+Every handle has a builtin `files` collection. `cero.put(handle.files, …)` uploads bytes (a `Buffer` or a `Readable`) and returns a file with a `.url`:
+
+```js
+const { data: file } = await cero.put(me.files, {
+  data: bytes, // Buffer | Readable
+  name: 'cat.jpg',
+  type: 'image/jpeg'
+})
+
+img.src = file.url
+```
+
+Read them back — every row carries a fresh `.url`:
+
+```js
+const { data: files } = await cero.get(me.files) // list all
+const { data: one } = await cero.get(me.files, file.id) // one, by id
+cero.watch(me.files).on('data', ({ data }) => render(data)) // live
+```
+
+### The `file()` column type
+
+For a file referenced from a row — an avatar, a room icon, a message attachment — declare the field `cero.t.file()`. Store the file's `id`; read it back already resolved to `{ id, name, type, size, url }`, with **no extra lookup**:
+
+```js
+// schema.js
+profile: cero.t.single({ name: cero.t.string, avatar: cero.t.file() })
+
+// save: upload, then store the id on the row
+const { data: pic } = await cero.put(me.files, { data: bytes, type: 'image/png' })
+await cero.set(me.profile, { avatar: pic.id })
+
+// read: the avatar comes back url-ready
+const { data: profile } = await cero.get(me.profile)
+img.src = profile.avatar.url
+```
+
+`cero.t.file({ embed: true })` also stores the file's `name` inline — handy for a list of named attachments, so rendering needs no per-item lookup.
+
+### URLs are local and ephemeral
+
+A `.url` points at a localhost server this device runs, with a per-session token — it changes across restarts and is **not** shareable to other peers. Never persist a `.url`: store the **id** (cero does), and re-read to get a current one. Each member derives their own url from the same id, and the bytes download on demand when the url is first fetched.
+
 ## Custom operators
 
 Your app's business logic lives as **custom operators** — plain functions whose first arg is the handle they act on, composing the built-ins. Because the built-ins resolve through the handle (a real DB on the core, an RPC proxy on the client), custom operators are symmetric over RPC for free.
@@ -340,8 +409,9 @@ The client side gets the **same operator API** as a local cero — `cero.put`, `
 import { serve } from '@cero-base/cero/server'
 import { spec } from './spec/index.js'
 
-// serve builds and owns the root cero — pass storage + the built spec, not a handle
-await serve(Bare.IPC, { storage: './data', spec, seed: '…' })
+// serve builds and owns the root cero — pass storage + the built spec, not a handle.
+// Returns a Server instance (call server.close() to shut down).
+const server = await serve(Bare.IPC, { storage: './data', spec, seed: '…' })
 ```
 
 ### Client (the UI process)
@@ -366,14 +436,14 @@ The same `spec/index.js` is imported on both sides. `@cero-base/cero/build` emit
 
 Everything the local API offers, plus lifecycle methods on returned handles:
 
-| Operator / method                                                              | Works over RPC |
-| ------------------------------------------------------------------------------ | -------------- |
-| `cero.put` / `set` / `get` / `del` / `count` / `watch` / `call`                | ✓              |
-| `cero.open(ref, …)` — create, join, load by id                                 | ✓              |
-| `room.invite({ role })` — mint an invite                                       | ✓              |
-| `room.revoke(invite)` — invalidate an outstanding invite; `true` if it existed | ✓              |
-| `room.close()` — release the handle on the server                              | ✓              |
-| `room.leave()` — remove yourself from the room and from your handles list      | ✓              |
+| Operator / method                                                                                                    | Works over RPC |
+| -------------------------------------------------------------------------------------------------------------------- | -------------- |
+| `cero.put` / `set` / `get` / `del` / `count` / `watch` / `call`                                                      | ✓              |
+| `cero.open(ref, …)` — create, join, load by id                                                                       | ✓              |
+| `room.invite({ role, expiresIn, multiUse })` — mint an invite (`multiUse: true` keeps it alive after the first join) | ✓              |
+| `room.revoke(invite)` — invalidate an outstanding invite; `true` if it existed                                       | ✓              |
+| `room.close()` — release the handle on the server                                                                    | ✓              |
+| `room.leave()` — remove yourself from the room and from your handles list                                            | ✓              |
 
 `cero.watch(ref)` returns a Readable on both sides; snapshots flow as a server-streamed RPC.
 

package/package.json

@@ -1,8 +1,17 @@
 {
   "name": "@cero-base/cero",
-  "version": "0.8.9",
+  "version": "1.0.1",
   "description": "The ideal p2p API — everything is a handle, handles contain refs, refs contain rows.",
   "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lekinox/cero-base.git",
+    "directory": "packages/cero"
+  },
   "main": "./src/index.js",
   "types": "./types/index.d.ts",
   "files": [
@@ -39,7 +48,7 @@
   "typesVersions": {
     "*": {
       "build": [
-        "types/builder.d.ts"
+        "types/build/index.d.ts"
       ],
       "server": [
         "types/rpc/server.d.ts"
@@ -64,10 +73,6 @@
     "crypto": {
       "bare": "bare-crypto",
       "default": "crypto"
-    },
-    "abort-controller": {
-      "bare": "bare-abort-controller",
-      "default": "bare-abort-controller"
     }
   },
   "scripts": {
@@ -78,25 +83,30 @@
     "test": "ls test/*.test.js | xargs -P1 -n1 brittle-node"
   },
   "dependencies": {
-    "@cero-base/core": "^0.8.9",
+    "@cero-base/core": "^1.0.1",
     "b4a": "^1.8.1",
     "bare-abort-controller": "^1.1.2",
-    "bare-crypto": "^1.14.1",
+    "bare-crypto": "^1.15.3",
     "bare-fs": "^4.7.2",
     "bare-path": "^3.0.1",
     "blind-pairing": "^2.3.1",
-    "compact-encoding": "^3.1.0",
+    "compact-encoding": "^3.2.0",
+    "corestore": "^7.10.1",
     "hrpc": "^4.3.0",
+    "hypercore": "^11.33.1",
+    "hypercore-crypto": "^3.7.0",
+    "hypercore-storage": "^3.1.1",
     "hyperdb": "^6.7.0",
     "hyperdispatch": "^1.6.0",
     "hyperschema": "^1.21.0",
     "ready-resource": "^1.2.0",
     "safety-catch": "^1.0.3",
+    "streamx": "^2.28.0",
     "z32": "^1.1.0"
   },
   "devDependencies": {
     "@hyperswarm/testnet": "^3.1.4",
-    "brittle": "^4.0.0",
+    "brittle": "^4.0.2",
     "typescript": "^6.0.3"
   },
   "license": "Apache-2.0"

package/src/build/builtins.js

@@ -13,7 +13,8 @@ export const refs = {
     members: { type: 'member' },
     devices: { type: 'device' },
     invites: { type: 'invite' },
-    handles: { type: 'handle' }
+    handles: { type: 'handle' },
+    files: { type: 'file' }
   },
   local: {
     master: { type: 'master', kind: 'single' },
@@ -22,7 +23,7 @@ export const refs = {
   }
 }
 
-export const hyperdbType = (prim) => DB_TYPE[prim] || 'string'
+export const getHyperdbType = (prim) => DB_TYPE[prim] || 'string'
 
 const at = (ns, n) => `@${ns}/${n}`
 const keyOf = (def) => (def.kind === 'single' ? [] : ['id'])
@@ -30,7 +31,7 @@ const keyOf = (def) => (def.kind === 'single' ? [] : ['id'])
 const fields = (map) =>
   Object.entries(map).map(([name, m]) => ({
     name,
-    type: hyperdbType(m.prim),
+    type: getHyperdbType(m.prim),
     required: m.required === true
   }))
 
@@ -102,7 +103,13 @@ export const rpcCommands = (ns) => {
       request: { name: ref('req-restore') },
       response: { name: ref('res-identity') }
     },
+    { name: 'seed', request: { name: ref('req-empty') }, response: { name: ref('res-seed') } },
     { name: 'add-row', request: { name: ref('req-row') }, response: { name: ref('res-data') } },
+    {
+      name: 'add-file',
+      request: { name: ref('req-add-file') },
+      response: { name: ref('res-data') }
+    },
     {
       name: 'add-handle',
       request: { name: ref('req-row') },

package/src/build/index.js

@@ -18,7 +18,7 @@ import {
   builtinDispatches,
   rpcTypes,
   rpcCommands,
-  hyperdbType
+  getHyperdbType
 } from './builtins.js'
 
 /**
@@ -42,6 +42,8 @@ import {
  * @param {BuildOpts} [opts]
  * @returns {Promise<void>}
  */
+export { getHyperdbType } from './builtins.js'
+
 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')
@@ -148,6 +150,12 @@ function compile(root, ns, scope = 'main') {
   }
 }
 
+function fileFieldNames(fields) {
+  return Object.entries(fields)
+    .filter(([, m]) => m.prim === 'file')
+    .map(([name]) => name)
+}
+
 function register(name, node, ctx) {
   const fqn = `@${ctx.ns}/${name}`
   if (node.kind === 'action') {
@@ -160,7 +168,11 @@ function register(name, node, ctx) {
     ctx.types.push({ name, compact: false, fields: fieldsFor(node.fields) })
     ctx.collections.push({ name, schema: fqn, key: [] })
     ctx.dispatches.push({ name: `set-${name}`, requestType: fqn })
-    ctx.meta.refs[name] = { kind: 'single', path: [name], schema: fqn }
+    ctx.dispatches.push({ name: `del-${name}`, requestType: `@${ctx.ns}/del-by-id` })
+    const refEntry = { kind: 'single', path: [name], schema: fqn, fields: Object.keys(node.fields) }
+    const fileFields = fileFieldNames(node.fields)
+    if (fileFields.length) refEntry.files = fileFields
+    ctx.meta.refs[name] = refEntry
     return
   }
   if (node.kind === 'collection') {
@@ -180,7 +192,15 @@ function register(name, node, ctx) {
     ctx.dispatches.push({ name: `add-${name}`, requestType: fqn })
     ctx.dispatches.push({ name: `set-${name}`, requestType: fqn })
     ctx.dispatches.push({ name: `del-${name}`, requestType: `@${ctx.ns}/del-by-id` })
-    ctx.meta.refs[name] = { kind: 'collection', path: [name], schema: fqn }
+    const refEntry = {
+      kind: 'collection',
+      path: [name],
+      schema: fqn,
+      fields: Object.keys(node.fields)
+    }
+    const fileFields = fileFieldNames(node.fields)
+    if (fileFields.length) refEntry.files = fileFields
+    ctx.meta.refs[name] = refEntry
     if (node.indexes) {
       for (const [idx, fields] of Object.entries(node.indexes)) {
         ctx.indexes.push({ name: `${name}-${idx}`, collection: fqn, key: fields })
@@ -193,7 +213,7 @@ function register(name, node, ctx) {
 function fieldsFor(fields) {
   return Object.entries(fields).map(([name, marker]) => ({
     name,
-    type: hyperdbType(marker.prim),
+    type: getHyperdbType(marker.prim),
     required: marker.required === true
   }))
 }

package/src/build/schemas.js

@@ -59,6 +59,14 @@ export const main = {
     updatedAt: int,
     index: uint
   },
+  file: {
+    id: required(string),
+    memberId: string,
+    name: string,
+    createdAt: int,
+    updatedAt: int,
+    index: uint
+  },
   claim: {
     identity: required(bytes),
     writer: required(bytes),
@@ -93,7 +101,8 @@ export const rpc = {
     handle: required(string),
     ref: required(string),
     data: required(bytes),
-    local: bool
+    local: bool,
+    noUpsert: bool
   },
   'req-id': {
     handle: required(string),
@@ -151,9 +160,19 @@ export const rpc = {
     type: required(string),
     name: string
   },
+  'req-add-file': {
+    handle: required(string),
+    data: required(bytes),
+    name: string,
+    type: string
+  },
   'res-identity': {
     id: required(string),
     deviceId: string,
+    fileBase: string,
+    fileToken: string
+  },
+  'res-seed': {
     phrase: string
   },
   'res-ok': {