@cero-base/core 0.8.9 → 1.0.1

package/types/pairing/index.d.ts

@@ -5,11 +5,13 @@
  * @property {Uint8Array} [topic]                                    Optional override topic; defaults to `identity.publicKey`.
  * @property {any} [inviteEncoding]                                  compact-encoding type for the invite payload `data`.
  * @property {any} [joinerEncoding]                                  compact-encoding type for the joiner-supplied `userData`.
+ * @property {(err: Error) => void} [onerror]                        Called when a background candidate fails to process.
  *
  * @typedef {object} CreateInviteOpts
  * @property {string} [role]                                         Role tag bound into the invite.
  * @property {number} [expiresIn]                                    TTL in ms; `0`/omitted = no expiry.
  * @property {any} [data]                                            Arbitrary payload (encoded via `inviteEncoding` when set).
+ * @property {boolean} [multiUse]                                    Reusable until expiry/revoke; default `false` (consumed on first settle).
  *
  * @typedef {object} JoinOpts
  * @property {any} [userData]                                        Payload sent with the candidate request.
@@ -22,7 +24,7 @@
  *
  * @typedef {{ key: Uint8Array, encryptionKey: Uint8Array | null, additional: Uint8Array | null }} JoinResult
  *
- * @typedef {object} CandidateOpts
+ * @typedef {object} RequestOpts
  * @property {Pairing} pairing                                       Owning Pairing instance.
  * @property {any} req                                               blind-pairing candidate request being answered.
  * @property {Invite} invite                                         Invite the candidate paired against.
@@ -54,12 +56,13 @@ export class Pairing extends ReadyResource {
      */
     static isInvite(str: unknown): boolean;
     /** @param {PairingOpts} [opts] */
-    constructor({ network, identity, topic, inviteEncoding, joinerEncoding }?: PairingOpts);
+    constructor({ network, identity, topic, inviteEncoding, joinerEncoding, onerror }?: PairingOpts);
     network: import("../index.js").Network;
     identity: import("../index.js").Identity;
     topic: Uint8Array<ArrayBufferLike>;
     inviteEncoding: any;
     joinerEncoding: any;
+    _onerror: (err: Error) => void;
     _blind: any;
     _member: any;
     _invites: Map<any, any>;
@@ -70,7 +73,7 @@ export class Pairing extends ReadyResource {
      * @param {CreateInviteOpts} [opts]
      * @returns {Promise<string>}
      */
-    createInvite({ role, expiresIn, data }?: CreateInviteOpts): Promise<string>;
+    createInvite({ role, expiresIn, data, multiUse }?: CreateInviteOpts): Promise<string>;
     /**
      * Forget a previously-minted invite. New candidates carrying it will be
      * dropped silently.
@@ -129,6 +132,10 @@ export type PairingOpts = {
      * compact-encoding type for the joiner-supplied `userData`.
      */
     joinerEncoding?: any;
+    /**
+     * Called when a background candidate fails to process.
+     */
+    onerror?: (err: Error) => void;
 };
 export type CreateInviteOpts = {
     /**
@@ -143,6 +150,10 @@ export type CreateInviteOpts = {
      * Arbitrary payload (encoded via `inviteEncoding` when set).
      */
     data?: any;
+    /**
+     * Reusable until expiry/revoke; default `false` (consumed on first settle).
+     */
+    multiUse?: boolean;
 };
 export type JoinOpts = {
     /**
@@ -173,7 +184,7 @@ export type JoinResult = {
     encryptionKey: Uint8Array | null;
     additional: Uint8Array | null;
 };
-export type CandidateOpts = {
+export type RequestOpts = {
     /**
      * Owning Pairing instance.
      */

package/types/pairing/invite.d.ts

@@ -4,7 +4,7 @@
  * @property {string} role                          Optional role tag baked into the signed body.
  * @property {number} expires                       Absolute expiry timestamp; `0` means never.
  * @property {Uint8Array | null} data               Encoded payload (raw or via `encoding`).
- * @property {Uint8Array} blindInvite               Raw blind-pairing invite handed to candidates.
+ * @property {Uint8Array} blind                     Raw blind-pairing invite handed to candidates.
  * @property {Uint8Array} [sig]                     Ed25519 signature over the canonical body.
  * @property {string | null} [_str]                 Cached z32 string form.
  *
@@ -14,7 +14,7 @@
  * @property {string} role                          Optional role tag for the joiner.
  * @property {number} expiresIn                     TTL in ms from now; `0` means never expires.
  * @property {any} data                             Caller payload; encoded via `encoding` when provided.
- * @property {Uint8Array} blindInvite               Raw blind-pairing invite to wrap.
+ * @property {Uint8Array} blind                     Raw blind-pairing invite to wrap.
  * @property {any} [encoding]                       compact-encoding type used to encode `data`.
  *
  * @typedef {object} ParseInviteOpts
@@ -26,7 +26,7 @@
  * authenticated by the joiner before any handshake happens.
  *
  * @property {any} [_rawData]                         Decoded payload kept alongside the encoded `data` for convenience.
- * @property {any} _blind                             Lazily-decoded blind-pairing invite view (cache).
+ * @property {Uint8Array} _discoveryKey               Cached discovery key of the wrapped blind invite.
  */
 export class Invite {
     /**
@@ -35,7 +35,7 @@ export class Invite {
      * @param {CreateInviteOpts} opts
      * @returns {Invite}
      */
-    static create({ secretKey, publicKey, role, expiresIn, data, blindInvite, encoding }: CreateInviteOpts): Invite;
+    static create({ secretKey, publicKey, role, expiresIn, data, blind, encoding }: CreateInviteOpts): Invite;
     /**
      * Parse a z32 invite string, verify its signature and (optionally) decode
      * its payload.
@@ -60,10 +60,10 @@ export class Invite {
     role: string;
     expires: number;
     data: Uint8Array<ArrayBufferLike>;
-    blindInvite: Uint8Array<ArrayBufferLike>;
+    blind: Uint8Array<ArrayBufferLike>;
     sig: Uint8Array<ArrayBufferLike>;
     _str: string;
-    _blind: any;
+    _discoveryKey: any;
     /**
      * Whether the invite is past its TTL (always `false` when `expires === 0`).
      *
@@ -71,11 +71,11 @@ export class Invite {
      */
     get expired(): boolean;
     /**
-     * Lazily-decoded view of the underlying blind-pairing invite.
+     * Discovery key of the wrapped blind-pairing invite — the topic it targets.
      *
-     * @returns {any}
+     * @returns {Uint8Array}
      */
-    get blind(): any;
+    get discoveryKey(): Uint8Array;
     /**
      * Verify the embedded signature against the encoded body.
      *
@@ -109,7 +109,7 @@ export type InviteFields = {
     /**
      * Raw blind-pairing invite handed to candidates.
      */
-    blindInvite: Uint8Array;
+    blind: Uint8Array;
     /**
      * Ed25519 signature over the canonical body.
      */
@@ -143,7 +143,7 @@ export type CreateInviteOpts = {
     /**
      * Raw blind-pairing invite to wrap.
      */
-    blindInvite: Uint8Array;
+    blind: Uint8Array;
     /**
      * compact-encoding type used to encode `data`.
      */

package/types/rpc/client.d.ts

@@ -1,18 +1,7 @@
 /**
- * Client-side RPC adapter. Mirror of `RPCServer` — wraps an IPC duplex
- * in a length-framed stream and constructs the spec's hrpc binding ready
- * to issue requests. Frames are paused until `_open` runs so handlers
- * registered before `ready()` see a clean slate.
+ * Client-side RPC adapter — issues requests over the framed IPC stream.
+ * All wiring lives in {@link RPCPeer}; this is the client-named role.
  */
-export class RPCClient extends ReadyResource {
-    /**
-     * @param {any} ipc                                Duplex IPC stream (e.g. a socket or pipe).
-     * @param {import('./index.js').Spec} spec         Spec object exposing `rpc` and `schema`.
-     */
-    constructor(ipc: any, spec: import("./index.js").Spec);
-    ipc: any;
-    spec: import("./index.js").Spec;
-    framed: any;
-    rpc: any;
+export class RPCClient extends RPCPeer {
 }
-import ReadyResource from 'ready-resource';
+import { RPCPeer } from './peer.js';

package/types/rpc/peer.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Shared RPC peer: wraps an IPC duplex in a length-framed stream and constructs
+ * the spec's hrpc binding. Frames are paused until `_open` runs so handlers
+ * registered before `ready()` see a clean slate. `RPCClient` and `RPCServer`
+ * are thin named subclasses — identical wiring, distinct roles.
+ */
+export class RPCPeer extends ReadyResource {
+    /**
+     * @param {any} ipc                                Duplex IPC stream (e.g. a socket or pipe).
+     * @param {import('./index.js').Spec} spec         Spec object exposing `rpc` and `schema`.
+     */
+    constructor(ipc: any, spec: import("./index.js").Spec);
+    ipc: any;
+    spec: import("./index.js").Spec;
+    framed: any;
+    rpc: any;
+}
+import ReadyResource from 'ready-resource';

package/types/rpc/server.d.ts

@@ -1,18 +1,7 @@
 /**
- * Server-side RPC adapter. Wraps an IPC duplex in a length-framed stream
- * and instantiates the spec's hrpc binding once `bindCodec` has populated
- * envelope encoders. Reads are paused until `_open` runs so the
- * application has a chance to register handlers before frames flow.
+ * Server-side RPC adapter — serves the spec's handlers over the framed IPC
+ * stream. All wiring lives in {@link RPCPeer}; this is the server-named role.
  */
-export class RPCServer extends ReadyResource {
-    /**
-     * @param {any} ipc                                Duplex IPC stream (e.g. a socket or pipe).
-     * @param {import('./index.js').Spec} spec         Spec object exposing `rpc` and `schema`.
-     */
-    constructor(ipc: any, spec: import("./index.js").Spec);
-    ipc: any;
-    spec: import("./index.js").Spec;
-    framed: any;
-    rpc: any;
+export class RPCServer extends RPCPeer {
 }
-import ReadyResource from 'ready-resource';
+import { RPCPeer } from './peer.js';

package/types/storage/index.d.ts

@@ -66,13 +66,18 @@ export class Storage extends ReadyResource {
      */
     put(name: string, row: Record<string, any>): Promise<SingleResult>;
     /**
-     * Upsert by merging with the existing row, preserving `createdAt`.
+     * Upsert by merging with the existing row, preserving `createdAt`. Pass
+     * `{ upsert: false }` to update-only — a missing row is left untouched
+     * (returns `null`) instead of created. Mirrors `Database.set`.
      *
      * @param {string} name
      * @param {Record<string, any>} row
-     * @returns {Promise<SingleResult>}
+     * @param {{ upsert?: boolean }} [opts]
+     * @returns {Promise<SingleResult | null>}
      */
-    set(name: string, row: Record<string, any>): Promise<SingleResult>;
+    set(name: string, row: Record<string, any>, { upsert }?: {
+        upsert?: boolean;
+    }): Promise<SingleResult | null>;
     /**
      * Delete by id (collection) or wipe the whole single-row table.
      *
@@ -108,7 +113,7 @@ export class Storage extends ReadyResource {
      * @param {Record<string, any>} [query]
      * @returns {import('streamx').Readable}
      */
-    watch(name: string, query?: Record<string, any>): any;
+    watch(name: string, query?: Record<string, any>): import("streamx").Readable;
     _guard(): void;
     /** @param {string} name @returns {Ref} */
     _ref(name: string): Ref;