@cero-base/cero 0.8.10 → 1.1.0

package/README.md

@@ -49,6 +49,7 @@ Ships with TypeScript declarations (`.d.ts`) generated from JSDoc.
 | Opt                 | Meaning                                                                                                                                                                                                                                                |
 | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `bootstrap`         | Hyperswarm bootstrap nodes.                                                                                                                                                                                                                            |
+| `channel`           | Optional network-isolation label. Peers connect only to peers on the **same** channel (it salts every swarm topic); omit it for the global network. A storage remembers its channel and refuses to reopen under a different one. Any string works.     |
 | `name` / `isMobile` | Stamped on the device's `add-writer` event.                                                                                                                                                                                                            |
 | `seed` / `phrase`   | Restore from explicit 16-/32-byte entropy or a BIP-39 mnemonic. Without either, a stored identity is loaded if present, else a fresh one is generated.                                                                                                 |
 | `key`               | Open against an existing bee key (multi-device flow).                                                                                                                                                                                                  |
@@ -56,6 +57,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.
 
@@ -104,8 +106,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)`
@@ -166,9 +169,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
@@ -211,6 +214,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.
@@ -360,8 +410,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)
@@ -386,14 +437,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.10",
+  "version": "1.1.0",
   "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.10",
+    "@cero-base/core": "^1.1.0",
     "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,16 +13,18 @@ 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' },
     keypair: { type: 'keypair', kind: 'single' },
-    'handle-keypairs': { type: 'handle-keypair' }
+    'handle-keypairs': { type: 'handle-keypair' },
+    environment: { type: 'environment', kind: 'single' }
   }
 }
 
-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 +32,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 +104,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),
@@ -79,6 +87,9 @@ export const local = {
     publicKey: required(bytes),
     secretKey: required(bytes),
     encryptionKey: bytes
+  },
+  environment: {
+    channel: required(string)
   }
 }
 
@@ -93,7 +104,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 +163,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': {