@cero-base/cero 0.4.1 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cero-base/cero",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "The ideal p2p API — everything is a handle, handles contain refs, refs contain rows.",
   "type": "module",
   "main": "./src/index.js",

package/src/builder.js

@@ -257,6 +257,7 @@ import * as dispatch from './main/dispatch/index.js'
 import * as schema from './main/schema/index.js'
 import rpc from './main/rpc/index.js'
 import localDatabase from './local/db/index.js'
+import * as localSchema from './local/schema/index.js'
 ${handleImports(names, kinds)}
 
 export const meta = ${JSON.stringify(meta, null, 2)}
@@ -266,7 +267,7 @@ export const spec = {
   dispatch,
   schema,
   rpc,
-  local: { database: localDatabase },
+  local: { database: localDatabase, schema: localSchema, meta: meta.local },
   meta,
   handles: {
 ${handleEntries(names, kinds)}

package/src/lib/builtins.js

@@ -254,7 +254,8 @@ export function rpcTypes() {
       fields: [
         { name: 'handle', type: 'string', required: true },
         { name: 'ref', type: 'string', required: true },
-        { name: 'data', type: 'buffer', required: true }
+        { name: 'data', type: 'buffer', required: true },
+        { name: 'local', type: 'bool', required: false }
       ]
     },
     {
@@ -263,7 +264,8 @@ export function rpcTypes() {
       fields: [
         { name: 'handle', type: 'string', required: true },
         { name: 'ref', type: 'string', required: true },
-        { name: 'id', type: 'string', required: true }
+        { name: 'id', type: 'string', required: true },
+        { name: 'local', type: 'bool', required: false }
       ]
     },
     {
@@ -272,7 +274,8 @@ export function rpcTypes() {
       fields: [
         { name: 'handle', type: 'string', required: true },
         { name: 'ref', type: 'string', required: true },
-        { name: 'query', type: 'buffer', required: false }
+        { name: 'query', type: 'buffer', required: false },
+        { name: 'local', type: 'bool', required: false }
       ]
     },
     {

package/src/rpc/client.js

@@ -12,8 +12,9 @@ export { put, set, get, del, count, watch, call, open } from '../lib/operators.j
  * @property {'single'|'collection'|'action'|'handle'} [kind]
  * @property {string} [schema]
  * @property {string} [type]
+ * @property {boolean} [builtin]
  *
- * @typedef {import('@cero-base/core/rpc').Spec & { meta: { ns?: string, refs: Record<string, RefInfo>, handles?: Record<string, Spec> }, handles: Record<string, Spec> }} Spec  Built cero spec (schema + rpc + per-handle child specs).
+ * @typedef {import('@cero-base/core/rpc').Spec & { meta: { ns?: string, refs: Record<string, RefInfo>, local?: { refs: Record<string, RefInfo> }, handles?: Record<string, Spec> }, handles: Record<string, Spec> }} Spec  Built cero spec (schema + rpc + per-handle child specs).
  *
  * @typedef {{ data: any }} SingleResult
  * @typedef {{ data: any[], total: number, size: number }} ListResult
@@ -29,12 +30,26 @@ export { put, set, get, del, count, watch, call, open } from '../lib/operators.j
  * @property {string|null} name
  */
 
-// Mixin applied to both Client and Handle so they expose the same row-ops
-// surface as a local cero handle but routed over the wire.
+// 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.
 const operators = {
+  _local: false,
+
+  /** @param {string} name @returns {RefInfo|undefined} */
+  _refInfo(name) {
+    const refs = this._local ? this.spec.meta.local?.refs : this.spec.meta.refs
+    return refs?.[name]
+  },
+
+  /** @returns {any} */
+  _codec() {
+    return this._local ? this.spec.local.codec : this.spec.codec
+  },
+
   /** @param {string} name @returns {string|undefined} */
   schemaOf(name) {
-    return this.spec.meta.refs[name]?.schema
+    return this._refInfo(name)?.schema
   },
 
   /**
@@ -45,13 +60,14 @@ const operators = {
    * @returns {Promise<SingleResult>}
    */
   async put(name, row) {
+    const codec = this._codec()
     const schema = this.schemaOf(name)
-    const codec = this.spec.codec
     const input = row?.id ? row : { id: '', ...row }
     const res = await this.rpc.addRow({
       handle: this.id,
       ref: name,
-      data: codec.encodeRow(schema, input)
+      data: codec.encodeRow(schema, input),
+      local: this._local
     })
     return { data: codec.decodeRow(schema, res.data) }
   },
@@ -64,12 +80,13 @@ const operators = {
    * @returns {Promise<SingleResult>}
    */
   async set(name, row) {
+    const codec = this._codec()
     const schema = this.schemaOf(name)
-    const codec = this.spec.codec
     const res = await this.rpc.set({
       handle: this.id,
       ref: name,
-      data: codec.encodeRow(schema, row)
+      data: codec.encodeRow(schema, row),
+      local: this._local
     })
     return { data: codec.decodeRow(schema, res.data) }
   },
@@ -83,20 +100,27 @@ const operators = {
    * @returns {Promise<SingleResult | ListResult | GetByIdResult>}
    */
   async get(name, query) {
+    const codec = this._codec()
     const schema = this.schemaOf(name)
-    const codec = this.spec.codec
     if (typeof query === 'string') {
-      const res = await this.rpc.getOne({ handle: this.id, ref: name, id: query })
+      const res = await this.rpc.getOne({
+        handle: this.id,
+        ref: name,
+        id: query,
+        local: this._local
+      })
       return { data: res.data ? codec.decodeRow(schema, res.data) : null }
     }
     const res = await this.rpc.get({
       handle: this.id,
       ref: name,
-      query: codec.encodeQuery(query)
+      query: codec.encodeQuery(query),
+      local: this._local
     })
-    const kind = this.spec.meta.refs[name]?.kind
     const data =
-      kind === 'single' ? codec.decodeRow(schema, res.data) : codec.decodeRows(schema, res.data)
+      this._refInfo(name)?.kind === 'single'
+        ? codec.decodeRow(schema, res.data)
+        : codec.decodeRows(schema, res.data)
     return { data, total: res.total, size: res.size }
   },
 
@@ -108,7 +132,7 @@ const operators = {
    * @returns {Promise<void>}
    */
   async del(name, id) {
-    await this.rpc.del({ handle: this.id, ref: name, id })
+    await this.rpc.del({ handle: this.id, ref: name, id, local: this._local })
   },
 
   /**
@@ -119,11 +143,12 @@ const operators = {
    * @returns {Promise<{ data: number }>}
    */
   async count(name, query) {
-    const codec = this.spec.codec
+    const codec = this._codec()
     const res = await this.rpc.count({
       handle: this.id,
       ref: name,
-      query: codec.encodeQuery(query)
+      query: codec.encodeQuery(query),
+      local: this._local
     })
     return { data: res.count }
   },
@@ -137,13 +162,14 @@ const operators = {
    * @returns {import('streamx').Readable}
    */
   watch(name, query) {
-    const refInfo = this.spec.meta.refs[name]
+    const refInfo = this._refInfo(name)
+    const codec = this._codec()
     const schema = refInfo?.schema
-    const codec = this.spec.codec
     const wire = this.rpc.watch({
       handle: this.id,
       ref: name,
-      query: codec.encodeQuery(query)
+      query: codec.encodeQuery(query),
+      local: this._local
     })
     const out = new Readable({
       predestroy() {
@@ -171,7 +197,7 @@ const operators = {
    */
   async call(op, data) {
     const schema = this.schemaOf(op)
-    const codec = this.spec.codec
+    const codec = this._codec()
     const encoded = data ? codec.encodeAction({ [op]: { schema } }, op, data) : null
     await this.rpc.call({ handle: this.id, op, data: encoded })
   },
@@ -215,6 +241,36 @@ export async function restore(me, phrase) {
   return me
 }
 
+/**
+ * Per-device `local`-namespace surface on a Client. Exposes each app-defined
+ * local ref (e.g. `client.local.settings`) and routes ops over RPC with
+ * `local: true`, so they hit the server's per-device store and never
+ * replicate. Built-in local refs (identity master/keypair) are not exposed.
+ */
+class LocalRefs {
+  /** @param {Client} client */
+  constructor(client) {
+    Object.assign(this, operators)
+    this.parent = client
+    this.spec = client.spec
+    this.store = this
+    this._local = true
+    const refs = client.spec.meta.local?.refs || {}
+    const exposed = Object.fromEntries(Object.entries(refs).filter(([, info]) => !info.builtin))
+    attachRefs(this, exposed)
+  }
+
+  /** Underlying RPC channel borrowed from the parent. */
+  get rpc() {
+    return this.parent.rpc
+  }
+
+  /** Root handle id (local ops are resolved against the root's local store). */
+  get id() {
+    return this.parent.id
+  }
+}
+
 /**
  * IPC-side RPC client for cero. Wraps an `hrpc` channel and exposes the
  * same handle/ref/row API as a local cero instance, transparently
@@ -227,10 +283,12 @@ export class Client extends RPCClient {
    */
   constructor(ipc, spec) {
     super(ipc, spec)
+    if (spec.local?.schema && !spec.local.codec) bindCodec(spec.local)
     Object.assign(this, operators)
     this.id = null
     this.deviceId = null
     this.store = this
+    this.local = null
   }
 
   async _open() {
@@ -240,6 +298,7 @@ export class Client extends RPCClient {
     this.deviceId = deviceId || null
     this.identity = { id, toPhrase: () => phrase || null }
     attachRefs(this, /** @type {Spec} */ (this.spec).meta.refs)
+    if (/** @type {Spec} */ (this.spec).meta.local?.refs) this.local = new LocalRefs(this)
   }
 
   /**

package/src/rpc/server.js

@@ -40,6 +40,7 @@ export class Server extends RPCServer {
     if (!storage) throw CeroError.REQUIRED('storage')
     if (!spec) throw CeroError.REQUIRED('spec')
     super(ipc, spec)
+    if (spec.local?.schema && !spec.local.codec) bindCodec(spec.local)
     this.storage = storage
     this.opts = opts
     this.me = null
@@ -100,20 +101,20 @@ export class Server extends RPCServer {
 
   /** Register the row-level RPC handlers (put/set/get/del/count/watch/call). */
   _wireData() {
-    this.rpc.onAddRow(async ({ handle, ref, data }) => {
-      const { ref: r, codec } = this._refOf(handle, ref)
+    this.rpc.onAddRow(async ({ handle, ref, data, local }) => {
+      const { ref: r, codec } = this._refOf(handle, ref, local)
       const { data: row } = await put(r, codec.decodeRow(r.schema, data))
       return { data: codec.encodeRow(r.schema, row) }
     })
 
-    this.rpc.onSet(async ({ handle, ref, data }) => {
-      const { ref: r, codec } = this._refOf(handle, ref)
+    this.rpc.onSet(async ({ handle, ref, data, local }) => {
+      const { ref: r, codec } = this._refOf(handle, ref, local)
       const { data: row } = await set(r, codec.decodeRow(r.schema, data))
       return { data: codec.encodeRow(r.schema, row) }
     })
 
-    this.rpc.onGet(async ({ handle, ref, query }) => {
-      const { ref: r, codec } = this._refOf(handle, ref)
+    this.rpc.onGet(async ({ handle, ref, query, local }) => {
+      const { ref: r, codec } = this._refOf(handle, ref, local)
       const result = /** @type {GetResult} */ (await get(r, codec.decodeQuery(query)))
       const data =
         r.kind === 'single'
@@ -122,28 +123,28 @@ export class Server extends RPCServer {
       return { data, total: result.total ?? 0, size: result.size ?? 0 }
     })
 
-    this.rpc.onGetOne(async ({ handle, ref, id }) => {
-      const { ref: r, codec } = this._refOf(handle, ref)
+    this.rpc.onGetOne(async ({ handle, ref, id, local }) => {
+      const { ref: r, codec } = this._refOf(handle, ref, local)
       const { data } = await get(r, id)
       return { data: data ? codec.encodeRow(r.schema, data) : null }
     })
 
-    this.rpc.onDel(async ({ handle, ref, id }) => {
-      await del(this._refOf(handle, ref).ref, id)
+    this.rpc.onDel(async ({ handle, ref, id, local }) => {
+      await del(this._refOf(handle, ref, local).ref, id)
       return {}
     })
 
-    this.rpc.onCount(async ({ handle, ref, query }) => {
-      const { ref: r, codec } = this._refOf(handle, ref)
+    this.rpc.onCount(async ({ handle, ref, query, local }) => {
+      const { ref: r, codec } = this._refOf(handle, ref, local)
       const { data } = await count(r, codec.decodeQuery(query))
       return { count: data }
     })
 
     this.rpc.onWatch((stream) => {
-      const { handle, ref, query } = stream.data
+      const { handle, ref, query, local } = stream.data
       let r, codec, live
       try {
-        ;({ ref: r, codec } = this._refOf(handle, ref))
+        ;({ ref: r, codec } = this._refOf(handle, ref, local))
         live = watch(r, codec.decodeQuery(query))
       } catch (err) {
         stream.destroy(err)
@@ -249,13 +250,23 @@ export class Server extends RPCServer {
   }
 
   /**
-   * Resolve a `{ handle, ref }` pair to its `Ref` and the handle's codec.
+   * Resolve a `{ handle, ref }` pair to its `Ref` and codec. When `local` is
+   * set, the ref is resolved against the root's per-device `local` store and
+   * paired with the codec bound from the local schema.
    *
    * @param {string} id
    * @param {string} name
+   * @param {boolean} [local]
    * @returns {RefAndCodec}
    */
-  _refOf(id, name) {
+  _refOf(id, name, local) {
+    if (local) {
+      const info = this.spec.meta.local?.refs?.[name]
+      if (!info || info.builtin) throw CeroError.UNKNOWN('local ref', name)
+      const r = this.me.local?.[name]
+      if (!r) throw CeroError.UNKNOWN('local ref', name)
+      return { ref: r, codec: this.spec.local.codec }
+    }
     const h = this._resolve(id)
     const r = h[name]
     if (!r) throw CeroError.UNKNOWN('ref', name)

package/types/rpc/client.d.ts

@@ -29,6 +29,7 @@ export class Client extends RPCClient {
     id: any;
     deviceId: any;
     store: this;
+    local: LocalRefs;
     identity: {
         id: any;
         toPhrase: () => any;
@@ -63,6 +64,7 @@ export type RefInfo = {
     kind?: "single" | "collection" | "action" | "handle";
     schema?: string;
     type?: string;
+    builtin?: boolean;
 };
 /**
  * Built cero spec (schema + rpc + per-handle child specs).
@@ -71,6 +73,9 @@ export type Spec = import("@cero-base/core/rpc").Spec & {
     meta: {
         ns?: string;
         refs: Record<string, RefInfo>;
+        local?: {
+            refs: Record<string, RefInfo>;
+        };
         handles?: Record<string, Spec>;
     };
     handles: Record<string, Spec>;
@@ -96,6 +101,24 @@ export type HandleStub = {
     name: string | null;
 };
 import { RPCClient } from '@cero-base/core/rpc';
+/**
+ * Per-device `local`-namespace surface on a Client. Exposes each app-defined
+ * local ref (e.g. `client.local.settings`) and routes ops over RPC with
+ * `local: true`, so they hit the server's per-device store and never
+ * replicate. Built-in local refs (identity master/keypair) are not exposed.
+ */
+declare class LocalRefs {
+    /** @param {Client} client */
+    constructor(client: Client);
+    parent: Client;
+    spec: import("@cero-base/core/rpc").Spec;
+    store: this;
+    _local: boolean;
+    /** Underlying RPC channel borrowed from the parent. */
+    get rpc(): any;
+    /** Root handle id (local ops are resolved against the root's local store). */
+    get id(): any;
+}
 /**
  * Client-side proxy for a remote handle. Exposes the same row-ops surface
  * as `Client` but scoped to a single child handle id, and routes every

package/types/rpc/server.d.ts

@@ -87,13 +87,16 @@ export class Server extends RPCServer {
      */
     _resolve(id: string): any;
     /**
-     * Resolve a `{ handle, ref }` pair to its `Ref` and the handle's codec.
+     * Resolve a `{ handle, ref }` pair to its `Ref` and codec. When `local` is
+     * set, the ref is resolved against the root's per-device `local` store and
+     * paired with the codec bound from the local schema.
      *
      * @param {string} id
      * @param {string} name
+     * @param {boolean} [local]
      * @returns {RefAndCodec}
      */
-    _refOf(id: string, name: string): RefAndCodec;
+    _refOf(id: string, name: string, local?: boolean): RefAndCodec;
     /**
      * Snapshot the current identity for return to the client.
      *