@cero-base/cero 0.5.2 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cero-base/cero",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "The ideal p2p API — everything is a handle, handles contain refs, refs contain rows.",
   "type": "module",
   "main": "./src/index.js",
@@ -20,8 +20,8 @@
       "default": "./src/index.js"
     },
     "./build": {
-      "types": "./types/builder.d.ts",
-      "default": "./src/builder.js"
+      "types": "./types/build/index.d.ts",
+      "default": "./src/build/index.js"
     },
     "./server": {
       "types": "./types/rpc/server.d.ts",
@@ -67,7 +67,7 @@
     "test": "ls test/*.test.js | xargs -P2 -n1 brittle-node"
   },
   "dependencies": {
-    "@cero-base/core": "^0.5.2",
+    "@cero-base/core": "^0.6.0",
     "b4a": "^1.8.1",
     "bare-crypto": "^1.13.7",
     "bare-fs": "^4.7.1",

package/src/build/builtins.js

@@ -0,0 +1,137 @@
+// Build wiring for the builtin schemas (schemas.js): turns the grouped field
+// maps into the type / collection / dispatch / command descriptors the builder
+// registers. Every cero schema includes these; app refs are added on top.
+import { CeroError } from '@cero-base/core/errors'
+import { COUNTERS, DB_TYPE } from '../lib/constants.js'
+import * as schemas from './schemas.js'
+
+// Builtin collections by scope — ref name → { type, kind? }. kind defaults to
+// 'collection' (id-keyed); 'single' has no key. Dispatches are derived for
+// main; counters is internal (a collection with no add/set/del).
+export const refs = {
+  main: {
+    members: { type: 'member' },
+    devices: { type: 'device' },
+    invites: { type: 'invite' },
+    handles: { type: 'handle' }
+  },
+  local: {
+    master: { type: 'master', kind: 'single' },
+    keypair: { type: 'keypair', kind: 'single' },
+    'handle-keypairs': { type: 'handle-keypair' }
+  }
+}
+
+export const hyperdbType = (prim) => DB_TYPE[prim] || 'string'
+
+const at = (ns, n) => `@${ns}/${n}`
+const keyOf = (def) => (def.kind === 'single' ? [] : ['id'])
+
+const fields = (map) =>
+  Object.entries(map).map(([name, m]) => ({
+    name,
+    type: hyperdbType(m.prim),
+    required: m.required === true
+  }))
+
+// Merge app `t.extend` fields into a builtin's base fields — base can't be redeclared.
+const merge = (type, base, extra) => {
+  if (!extra) return base
+  for (const k in extra)
+    if (k in base)
+      throw CeroError.INVALID(`'${k}' is a base field of '${type}' and cannot be redeclared`)
+  return { ...base, ...extra }
+}
+
+const descriptors = (group, extend = {}) =>
+  Object.entries(group).map(([name, base]) => ({
+    name,
+    compact: false,
+    fields: fields(merge(name, base, extend[name]))
+  }))
+
+// meta.refs entries for a scope's builtins.
+export const builtinRefs = (ns, scope) =>
+  Object.fromEntries(
+    Object.entries(refs[scope]).map(([name, def]) => [
+      name,
+      {
+        kind: def.kind || 'collection',
+        path: [name],
+        builtin: true,
+        ...(scope === 'main' && { verb: def.type }),
+        schema: at(ns, def.type)
+      }
+    ])
+  )
+
+// hyperschema type descriptors. scope is 'main' | 'local' | 'rpc'; `extend`
+// merges app `t.extend` fields into the matching type.
+export const builtinTypes = (scope, extend) => descriptors(schemas[scope], extend)
+export const rpcTypes = () => descriptors(schemas.rpc)
+
+// hyperdb collection descriptors for a scope.
+export const builtinCollections = (ns, scope) => {
+  const out = Object.entries(refs[scope]).map(([name, def]) => ({
+    name,
+    schema: at(ns, def.type),
+    key: keyOf(def)
+  }))
+  if (scope === 'main') out.push({ name: COUNTERS, schema: at(ns, 'counter'), key: ['name'] })
+  return out
+}
+
+// hyperdispatch descriptors (main scope only).
+export const builtinDispatches = (ns) => [
+  { name: 'add-writer', requestType: at(ns, 'writer') },
+  { name: 'del-writer', requestType: at(ns, 'writer') },
+  { name: 'claim-writer', requestType: at(ns, 'claim') },
+  ...Object.values(refs.main).flatMap(({ type }) => [
+    { name: `add-${type}`, requestType: at(ns, type) },
+    { name: `set-${type}`, requestType: at(ns, type) },
+    { name: `del-${type}`, requestType: at(ns, 'del-by-id') }
+  ])
+]
+
+export const rpcCommands = (ns) => {
+  const ref = (n) => at(ns, n)
+  return [
+    { name: 'init', request: { name: ref('req-empty') }, response: { name: ref('res-identity') } },
+    {
+      name: 'restore',
+      request: { name: ref('req-restore') },
+      response: { name: ref('res-identity') }
+    },
+    { name: 'add-row', request: { name: ref('req-row') }, response: { name: ref('res-data') } },
+    {
+      name: 'add-handle',
+      request: { name: ref('req-row') },
+      response: { name: ref('res-handle') }
+    },
+    { name: 'set', request: { name: ref('req-row') }, response: { name: ref('res-data') } },
+    { name: 'get', request: { name: ref('req-query') }, response: { name: ref('res-rows') } },
+    { name: 'get-one', request: { name: ref('req-id') }, response: { name: ref('res-data') } },
+    { name: 'del', request: { name: ref('req-id') }, response: { name: ref('res-ok') } },
+    { name: 'count', request: { name: ref('req-query') }, response: { name: ref('res-count') } },
+    {
+      name: 'watch',
+      request: { name: ref('req-query') },
+      response: { name: ref('res-rows'), stream: true }
+    },
+    { name: 'call', request: { name: ref('req-call') }, response: { name: ref('res-data') } },
+    { name: 'invite', request: { name: ref('req-invite') }, response: { name: ref('res-invite') } },
+    { name: 'revoke', request: { name: ref('req-revoke') }, response: { name: ref('res-ok') } },
+    { name: 'join', request: { name: ref('req-join') }, response: { name: ref('res-handle') } },
+    {
+      name: 'open-handle',
+      request: { name: ref('req-open') },
+      response: { name: ref('res-handle') }
+    },
+    {
+      name: 'close-handle',
+      request: { name: ref('req-handle') },
+      response: { name: ref('res-ok') }
+    },
+    { name: 'leave', request: { name: ref('req-handle') }, response: { name: ref('res-ok') } }
+  ]
+}

package/src/{builder.js → build/index.js}

@@ -8,20 +8,17 @@ import HRPCBuilder from 'hrpc'
 
 import { CeroError } from '@cero-base/core/errors'
 
+import { NS } from '../lib/constants.js'
 import {
-  BUILTINS,
-  LOCAL_BUILTINS,
-  hyperdbType,
+  refs,
+  builtinRefs,
   builtinTypes,
   builtinCollections,
   builtinDispatches,
-  localBuiltinTypes,
-  localBuiltinCollections,
   rpcTypes,
-  rpcCommands
-} from './lib/builtins.js'
-
-const NS = 'cero'
+  rpcCommands,
+  hyperdbType
+} from './builtins.js'
 
 /**
  * @typedef {import('@cero-base/core/schema').Schema} Schema
@@ -45,22 +42,34 @@ const NS = 'cero'
  * @returns {Promise<void>}
  */
 export async function build(specDir, schema, { ns = NS } = {}) {
-  const defs = /** @type {SchemaDefs & { local?: SchemaDefs }} */ (schema?.defs || schema)
-  if (!defs || typeof defs !== 'object') throw CeroError.REQUIRED('schema')
+  const raw = /** @type {SchemaDefs & { local?: SchemaDefs }} */ (schema?.defs || schema)
+  if (!raw || typeof raw !== 'object') throw CeroError.REQUIRED('schema')
+
+  // Pull out `t.extend(...)` entries (keyed by builtin ref name) and map them
+  // to the builtin's type name, to merge into builtin types across every scope.
+  const extend = {}
+  const defs = {}
+  for (const [k, v] of Object.entries(raw)) {
+    if (v && v.kind === 'extend') {
+      const type = refs.main[k]?.type
+      if (!type) throw CeroError.INVALID(`'${k}' is not an extendable builtin`)
+      extend[type] = v.fields
+    } else {
+      defs[k] = v
+    }
+  }
 
-  const main = compile(splitMain(defs), ns, BUILTINS)
-  const local = defs.local
-    ? compile(defs.local, ns, LOCAL_BUILTINS)
-    : compile({}, ns, LOCAL_BUILTINS)
+  const main = compile(splitMain(defs), ns, 'main')
+  const local = compile(defs.local || {}, ns, 'local')
   const handles = {}
   for (const [name, child] of Object.entries(splitHandles(defs))) {
-    handles[name] = compile(child, ns)
+    handles[name] = compile(child, ns, 'main')
   }
 
-  emitMain(join(specDir, 'main'), ns, main, { rpc: true })
+  emitMain(join(specDir, 'main'), ns, main, { rpc: true, extend })
   emitLocal(join(specDir, 'local'), ns, local)
   for (const [name, handle] of Object.entries(handles)) {
-    emitMain(join(specDir, 'handles', name), ns, handle, { rpc: false })
+    emitMain(join(specDir, 'handles', name), ns, handle, { rpc: false, extend })
   }
 
   const meta = {
@@ -105,18 +114,10 @@ function isPlainHandle(v) {
   return v && typeof v === 'object' && !v.kind && !v.prim
 }
 
-function compile(root, ns, builtins = BUILTINS) {
+function compile(root, ns, scope = 'main') {
   const ctx = { types: [], collections: [], dispatches: [], meta: { ns, refs: {} }, ns }
 
-  for (const b of builtins) {
-    ctx.meta.refs[b.name] = {
-      kind: b.kind || 'collection',
-      path: [b.name],
-      builtin: true,
-      verb: b.verb,
-      schema: `@${ns}/${b.type}`
-    }
-  }
+  Object.assign(ctx.meta.refs, builtinRefs(ns, scope))
 
   for (const [name, node] of Object.entries(root)) {
     if (node.kind === 'handle') {
@@ -174,11 +175,11 @@ function fieldsFor(fields) {
   return Object.entries(fields).map(([name, marker]) => ({
     name,
     type: hyperdbType(marker.prim),
-    required: false
+    required: marker.required === true
   }))
 }
 
-function emitMain(dir, ns, { types, collections, dispatches }, { rpc }) {
+function emitMain(dir, ns, { types, collections, dispatches }, { rpc, extend = {} }) {
   const schemaDir = join(dir, 'schema')
   const dbDir = join(dir, 'db')
   const dispatchDir = join(dir, 'dispatch')
@@ -186,14 +187,14 @@ function emitMain(dir, ns, { types, collections, dispatches }, { rpc }) {
 
   const s = Hyperschema.from(schemaDir)
   const sns = s.namespace(ns)
-  for (const desc of builtinTypes()) sns.register(desc)
+  for (const desc of builtinTypes('main', extend)) sns.register(desc)
   for (const desc of types) sns.register(desc)
   if (rpc) for (const desc of rpcTypes()) sns.register(desc)
   Hyperschema.toDisk(s, schemaDir, { esm: true })
 
   const db = HyperdbBuilder.from(schemaDir, dbDir)
   const dns = db.namespace(ns)
-  for (const desc of builtinCollections(ns)) dns.collections.register(desc)
+  for (const desc of builtinCollections(ns, 'main')) dns.collections.register(desc)
   for (const desc of collections) dns.collections.register(desc)
   HyperdbBuilder.toDisk(db, dbDir, { esm: true })
 
@@ -217,13 +218,13 @@ function emitLocal(dir, ns, { types, collections }) {
 
   const s = Hyperschema.from(schemaDir)
   const sns = s.namespace(ns)
-  for (const desc of localBuiltinTypes()) sns.register(desc)
+  for (const desc of builtinTypes('local')) sns.register(desc)
   for (const desc of types) sns.register(desc)
   Hyperschema.toDisk(s, schemaDir, { esm: true })
 
   const db = HyperdbBuilder.from(schemaDir, dbDir)
   const dns = db.namespace(ns)
-  for (const desc of localBuiltinCollections(ns)) dns.collections.register(desc)
+  for (const desc of builtinCollections(ns, 'local')) dns.collections.register(desc)
   for (const desc of collections) dns.collections.register(desc)
   HyperdbBuilder.toDisk(db, dbDir, { esm: true })
 }

package/src/build/schemas.js

@@ -0,0 +1,162 @@
+// Builtin type schemas grouped by scope, in the schema DSL — kept separate from
+// the build wiring (builtins.js) so apps can extend them with `t.extend`.
+// Field order is the wire order; do not reorder.
+import { t } from '../lib/spec.js'
+
+const { string, bytes, int, uint, bool, required } = t
+
+export const main = {
+  'del-by-id': {
+    id: required(string)
+  },
+  writer: {
+    master: required(bytes),
+    writer: required(bytes),
+    sig: required(bytes),
+    isIndexer: bool
+  },
+  counter: {
+    name: required(string),
+    value: required(uint)
+  },
+  member: {
+    id: required(string),
+    key: required(bytes),
+    role: required(string),
+    name: string,
+    createdAt: int,
+    updatedAt: int,
+    sig: bytes,
+    index: uint
+  },
+  device: {
+    id: required(string),
+    memberId: string,
+    name: string,
+    isMobile: bool,
+    createdAt: int,
+    updatedAt: int,
+    index: uint
+  },
+  invite: {
+    id: required(string),
+    invite: required(bytes),
+    publicKey: required(bytes),
+    data: bytes,
+    sig: bytes,
+    role: required(string),
+    expires: int,
+    createdAt: int,
+    index: uint
+  },
+  handle: {
+    id: required(string),
+    type: required(string),
+    key: required(bytes),
+    encryptionKey: bytes,
+    name: string,
+    createdAt: int,
+    updatedAt: int,
+    index: uint
+  },
+  claim: {
+    identity: required(bytes),
+    writer: required(bytes),
+    sig: required(bytes)
+  }
+}
+
+export const local = {
+  master: {
+    seed: required(bytes)
+  },
+  keypair: {
+    publicKey: required(bytes),
+    secretKey: required(bytes)
+  },
+  'handle-keypair': {
+    id: required(string),
+    publicKey: required(bytes),
+    secretKey: required(bytes),
+    encryptionKey: bytes
+  }
+}
+
+export const rpc = {
+  'req-empty': {
+    ok: bool
+  },
+  'req-restore': {
+    phrase: required(string)
+  },
+  'req-row': {
+    handle: required(string),
+    ref: required(string),
+    data: required(bytes),
+    local: bool
+  },
+  'req-id': {
+    handle: required(string),
+    ref: required(string),
+    id: required(string),
+    local: bool
+  },
+  'req-query': {
+    handle: required(string),
+    ref: required(string),
+    query: bytes,
+    local: bool
+  },
+  'req-call': {
+    handle: required(string),
+    op: required(string),
+    data: bytes
+  },
+  'req-invite': {
+    handle: required(string),
+    role: string
+  },
+  'req-revoke': {
+    handle: required(string),
+    invite: required(string)
+  },
+  'req-join': {
+    parent: required(string),
+    ref: required(string),
+    invite: required(string)
+  },
+  'req-open': {
+    parent: required(string),
+    row: required(string)
+  },
+  'req-handle': {
+    handle: required(string)
+  },
+  'res-data': {
+    data: bytes
+  },
+  'res-rows': {
+    data: required(bytes),
+    total: required(int),
+    size: required(int)
+  },
+  'res-count': {
+    count: required(int)
+  },
+  'res-invite': {
+    invite: required(string)
+  },
+  'res-handle': {
+    id: required(string),
+    type: required(string),
+    name: string
+  },
+  'res-identity': {
+    id: required(string),
+    deviceId: string,
+    phrase: string
+  },
+  'res-ok': {
+    ok: bool
+  }
+}

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.
@@ -214,9 +214,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 +281,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 +314,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 +330,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,
@@ -372,7 +368,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 +385,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
       })
@@ -439,7 +435,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)
@@ -503,7 +499,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

package/src/index.js

@@ -11,6 +11,7 @@ import { Local } from './local/index.js'
 import { put, set, get, del, count, watch, call, open } from './lib/operators.js'
 import { peek } from './lib/peek.js'
 import { t, schema } from './lib/spec.js'
+import { FLUSH } from './lib/constants.js'
 
 export { Handle, Ref, Local }
 export { put, set, get, del, count, watch, call, open } from './lib/operators.js'
@@ -65,7 +66,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 +110,7 @@ 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 })
 
   return me
 }

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/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;
+    };
+})[];