@yydb/yydb-client 0.0.1 → 0.0.3

package/README.md

@@ -1,26 +1,79 @@
 # `@yydb/yydb-client`
 
-TypeScript client for the **YY wire protocol**. Used by `yydb-webui` and
-`homepage`.
+**Lightweight TypeScript client for the YY wire protocol (WebSocket or TCP).**
 
-Frame prefix:
+Use this when you already run `yydb serve` (from [`@yydb/yydb`](../yydb) CLI or another host) and only need the client
+surface — browser, WebUI, Electron renderer, or a thin Node process.
 
-- product magic: **`YYDB`** or **`YYDS`** — backend self-claim; **same wire
-  effect**; client accepts either and does not require consistency
-- version digits: **`0000`** now; later **`0001`**, … (this is what matters)
+[![npm](https://img.shields.io/npm/v/@yydb/yydb-client)](https://www.npmjs.com/package/@yydb/yydb-client)
+[![Node.js](https://img.shields.io/node/v/@yydb/yydb-client)](https://www.npmjs.com/package/@yydb/yydb-client)
+[![Check Rust](https://github.com/yy-database/yydb/actions/workflows/check-rust.yml/badge.svg?branch=dev)](https://github.com/yy-database/yydb/actions/workflows/check-rust.yml)
+[![Check TypeScript](https://github.com/yy-database/yydb/actions/workflows/check-typescript.yml/badge.svg?branch=dev)](https://github.com/yy-database/yydb/actions/workflows/check-typescript.yml)
 
-| Entry | Transport |
-| --- | --- |
-| `@yydb/yydb-client` | WebSocket (`/wire`) — browsers / WebUI |
-| `@yydb/yydb-client/node` | Node TCP (or `ws://` WebSocket) |
+## Install
 
-Rust crates in this repo:
+```bash
+npm install @yydb/yydb-client
+```
 
-- `backends/yydb` — YYDB **embedded** facade
-- `backends/yydb-client` — YYDB **remote** TCP client for `yydb serve`
+## Browser or WebSocket
 
-## Security
+Start a local host first:
 
-Reference serve has **no ACL**. Only connect to loopback endpoints you control.
+```text
+yydb serve app.yydb --bind 127.0.0.1:7700
+```
 
-See [`../../documentation/serve-protocol.md`](../../documentation/serve-protocol.md).
+Then connect from browser-compatible code:
+
+```ts
+import {Client} from "@yydb/yydb-client";
+
+const db = await Client.connect("ws://127.0.0.1:7700/wire");
+await db.ensureSchema(1, "table Setting { @@id: uuid, key: utf8, value: utf8 }");
+await db.put("theme", "dark");
+console.log(await db.get("theme"));
+db.close();
+```
+
+## Node TCP
+
+The `/node` entry point supports a TCP endpoint and `ws://` URLs:
+
+```ts
+import {connect} from "@yydb/yydb-client/node";
+
+const db = await connect("127.0.0.1:7700");
+console.log(await db.info());
+db.close();
+```
+
+If a Node application only needs to open a local `.yydb` file, use
+[`@yydb/yydb`](https://www.npmjs.com/package/@yydb/yydb). It manages the local engine for you; this package is for an
+existing host or a custom transport integration.
+
+## Exports
+
+| Import                   | Transport         | Typical use        |
+|--------------------------|-------------------|--------------------|
+| `@yydb/yydb-client`      | WebSocket `/wire` | Browsers and WebUI |
+| `@yydb/yydb-client/node` | TCP or WebSocket  | Node and Electron  |
+
+The high-level client includes `info`, schema ensure/get, key/value get/put, server version, and close operations. Frame
+helpers such as `encodeFrame` and
+`MsgType` are exported for tools and tests.
+
+## Compatibility and security
+
+The client accepts hosts that announce either `YYDB` or `YYDS` on the shared wire. The reference `yydb serve` endpoint
+has no authentication, so connect only to a host you control, normally `127.0.0.1` or `localhost`.
+
+Protocol details for implementers are in the
+[`yydb-serve-protocol` skill](../yydb-skills/skills/yydb-serve-protocol/SKILL.md) (`@yydb/yydb-skills`).
+
+## Links
+
+- [Node file API](https://www.npmjs.com/package/@yydb/yydb)
+- [Local WebUI](https://github.com/yy-database/yydb.rs/tree/dev/projects/packages/yydb-webui)
+- [YYDB user guides](https://github.com/yy-database/yydb.rs/tree/dev/projects/packages/homepage/documentation/zh-hans)
+- [License](https://github.com/yy-database/yydb.rs/blob/dev/License.md)

package/dist/client.d.ts

@@ -1,7 +1,8 @@
-import { SchemaVersion } from "./wire.js";
-import type { Transport } from "./transport.js";
-export type { Frame, MsgTypeCode, SchemaVersion, } from "./wire.js";
-export { MsgType, encodeFrame, decodeFrame } from "./wire.js";
+import { MicroRegisterPayload, SchemaVersion, WireUdfScalarValue } from './wire.js';
+import type { MicroHostHandler, Transport } from './transport.js';
+export type { Frame, MicroHostInvokePayload, MicroRegisterPayload, MsgTypeCode, SchemaVersion, WireUdfScalarKind, WireUdfScalarValue, } from './wire.js';
+export type { MicroHostHandler } from './transport.js';
+export { MsgType, encodeFrame, decodeFrame } from './wire.js';
 export interface ConnectOptions {
     /** `ws://127.0.0.1:7700/wire` or `127.0.0.1:7700` (upgraded to `/wire`). */
     endpoint: string;
@@ -28,5 +29,11 @@ export declare class Client {
     ensureSchema(version: number, document: string): Promise<void>;
     get(key: string): Promise<Uint8Array | null>;
     put(key: string, value: Uint8Array | string): Promise<void>;
+    /** Register a session-local host micro contract on the remote engine. */
+    registerMicro(payload: MicroRegisterPayload): Promise<void>;
+    /** Install the host handler used to answer `MicroHostInvoke` server pushes. */
+    setMicroHostHandler(handler: MicroHostHandler | undefined): void;
+    /** Invoke a registered scalar UDF on the remote engine. */
+    callScalar(name: string, version: number, args: readonly WireUdfScalarValue[]): Promise<WireUdfScalarValue>;
     private roundtrip;
 }

package/dist/client.js

@@ -1,6 +1,6 @@
-import { decodeKvGetOk, decodeSchemaGetOk, encodeKvGet, encodeKvPut, encodeSchemaEnsure, MsgType, } from "./wire.js";
-import { openWebSocketTransport } from "./ws.js";
-export { MsgType, encodeFrame, decodeFrame } from "./wire.js";
+import { decodeKvGetOk, decodeScalarCallOk, decodeSchemaGetOk, encodeKvGet, encodeKvPut, encodeMicroRegister, encodeScalarCall, encodeSchemaEnsure, MsgType, } from './wire.js';
+import { openWebSocketTransport } from './ws.js';
+export { MsgType, encodeFrame, decodeFrame } from './wire.js';
 /**
  * TypeScript client for YY wire (browser = WebSocket `/wire`).
  * Accepts product magic `YYDB` or `YYDS` as equivalent self-claims (same wire);
@@ -20,9 +20,9 @@ export class Client {
     }
     /** Open WebSocket to `yydb serve` `/wire` and Hello-handshake. */
     static async connect(options) {
-        const endpoint = typeof options === "string" ? options : options.endpoint;
+        const endpoint = typeof options === 'string' ? options : options.endpoint;
         if (!endpoint.trim()) {
-            throw new Error("empty serve endpoint");
+            throw new Error('empty serve endpoint');
         }
         const transport = await openWebSocketTransport(endpoint);
         const client = new Client(endpoint, transport);
@@ -55,9 +55,22 @@ export class Client {
         return decodeKvGetOk(response.body);
     }
     async put(key, value) {
-        const bytes = typeof value === "string" ? new TextEncoder().encode(value) : value;
+        const bytes = typeof value === 'string' ? new TextEncoder().encode(value) : value;
         await this.roundtrip(MsgType.KvPut, encodeKvPut(key, bytes));
     }
+    /** Register a session-local host micro contract on the remote engine. */
+    async registerMicro(payload) {
+        await this.roundtrip(MsgType.MicroRegister, encodeMicroRegister(payload));
+    }
+    /** Install the host handler used to answer `MicroHostInvoke` server pushes. */
+    setMicroHostHandler(handler) {
+        this.transport.setMicroHostHandler?.(handler);
+    }
+    /** Invoke a registered scalar UDF on the remote engine. */
+    async callScalar(name, version, args) {
+        const response = await this.roundtrip(MsgType.ScalarCall, encodeScalarCall(name, version, args));
+        return decodeScalarCallOk(response.body);
+    }
     async roundtrip(msgType, body) {
         const requestId = this.nextId++;
         const response = await this.transport.send({
@@ -67,7 +80,7 @@ export class Client {
             body,
         });
         if (response.requestId !== requestId) {
-            throw new Error("wire response request_id mismatch");
+            throw new Error('wire response request_id mismatch');
         }
         if (response.msgType === MsgType.Error) {
             throw new Error(new TextDecoder().decode(response.body));
@@ -79,6 +92,8 @@ export class Client {
             [MsgType.SchemaEnsure]: MsgType.SchemaEnsureOk,
             [MsgType.KvGet]: MsgType.KvGetOk,
             [MsgType.KvPut]: MsgType.KvPutOk,
+            [MsgType.MicroRegister]: MsgType.MicroRegisterOk,
+            [MsgType.ScalarCall]: MsgType.ScalarCallOk,
         };
         const want = expectedOk[msgType];
         if (want !== undefined && response.msgType !== want) {

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /** Browser-safe entry (WebSocket). For Node TCP use `@yydb/yydb-client/node`. */
-export { Client } from "./client.js";
-export type { ConnectOptions } from "./client.js";
-export { MAGIC, MAGIC_YYDB, MAGIC_YYDS, WIRE_VERSION, WIRE_VERSION_NEXT, HEADER_LEN, MsgType, encodeFrame, decodeFrame, encodeSchemaEnsure, encodeKvGet, encodeKvPut, decodeSchemaGetOk, decodeKvGetOk, } from "./wire.js";
-export type { Frame, MsgTypeCode, ProductMagic, SchemaVersion } from "./wire.js";
+export { Client } from './client.js';
+export type { ConnectOptions } from './client.js';
+export { MAGIC, MAGIC_YYDB, MAGIC_YYDS, WIRE_VERSION, WIRE_VERSION_NEXT, HEADER_LEN, MsgType, encodeFrame, decodeFrame, encodeSchemaEnsure, encodeKvGet, encodeKvPut, decodeSchemaGetOk, decodeKvGetOk, } from './wire.js';
+export type { Frame, MsgTypeCode, ProductMagic, SchemaVersion } from './wire.js';

package/dist/index.js

@@ -1,3 +1,3 @@
 /** Browser-safe entry (WebSocket). For Node TCP use `@yydb/yydb-client/node`. */
-export { Client } from "./client.js";
-export { MAGIC, MAGIC_YYDB, MAGIC_YYDS, WIRE_VERSION, WIRE_VERSION_NEXT, HEADER_LEN, MsgType, encodeFrame, decodeFrame, encodeSchemaEnsure, encodeKvGet, encodeKvPut, decodeSchemaGetOk, decodeKvGetOk, } from "./wire.js";
+export { Client } from './client.js';
+export { MAGIC, MAGIC_YYDB, MAGIC_YYDS, WIRE_VERSION, WIRE_VERSION_NEXT, HEADER_LEN, MsgType, encodeFrame, decodeFrame, encodeSchemaEnsure, encodeKvGet, encodeKvPut, decodeSchemaGetOk, decodeKvGetOk, } from './wire.js';

package/dist/node.d.ts

@@ -1,7 +1,7 @@
-import { Client, type ConnectOptions } from "./client.js";
-export { Client } from "./client.js";
-export type { ConnectOptions } from "./client.js";
-export { MsgType, encodeFrame, decodeFrame, encodeSchemaEnsure, encodeKvGet, encodeKvPut, decodeSchemaGetOk, decodeKvGetOk, } from "./wire.js";
-export type { Frame, MsgTypeCode, SchemaVersion } from "./wire.js";
+import { Client, type ConnectOptions } from './client.js';
+export { Client } from './client.js';
+export type { ConnectOptions } from './client.js';
+export { MsgType, encodeFrame, decodeFrame, encodeSchemaEnsure, encodeKvGet, encodeKvPut, decodeSchemaGetOk, decodeKvGetOk } from './wire.js';
+export type { Frame, MsgTypeCode, SchemaVersion } from './wire.js';
 /** Node entry: TCP by default; `ws://` uses WebSocket. */
 export declare function connect(options: ConnectOptions | string): Promise<Client>;

package/dist/node.js

@@ -1,22 +1,20 @@
-import { Client } from "./client.js";
-import { openTcpTransport } from "./tcp.js";
-import { openWebSocketTransport } from "./ws.js";
-import { normalizeWsUrl } from "./transport.js";
-export { Client } from "./client.js";
-export { MsgType, encodeFrame, decodeFrame, encodeSchemaEnsure, encodeKvGet, encodeKvPut, decodeSchemaGetOk, decodeKvGetOk, } from "./wire.js";
+import { Client } from './client.js';
+import { openTcpTransport } from './tcp.js';
+import { openWebSocketTransport } from './ws.js';
+import { normalizeWsUrl } from './transport.js';
+export { Client } from './client.js';
+export { MsgType, encodeFrame, decodeFrame, encodeSchemaEnsure, encodeKvGet, encodeKvPut, decodeSchemaGetOk, decodeKvGetOk } from './wire.js';
 function wantsWebSocket(endpoint) {
     const trimmed = endpoint.trim();
-    return trimmed.startsWith("ws://") || trimmed.startsWith("wss://");
+    return trimmed.startsWith('ws://') || trimmed.startsWith('wss://');
 }
 /** Node entry: TCP by default; `ws://` uses WebSocket. */
 export async function connect(options) {
-    const endpoint = typeof options === "string" ? options : options.endpoint;
+    const endpoint = typeof options === 'string' ? options : options.endpoint;
     if (!endpoint.trim()) {
-        throw new Error("empty serve endpoint");
+        throw new Error('empty serve endpoint');
     }
-    const transport = wantsWebSocket(endpoint)
-        ? await openWebSocketTransport(endpoint)
-        : await openTcpTransport(endpoint);
+    const transport = wantsWebSocket(endpoint) ? await openWebSocketTransport(endpoint) : await openTcpTransport(endpoint);
     const client = Client.fromTransport(wantsWebSocket(endpoint) ? normalizeWsUrl(endpoint) : endpoint, transport);
     await client.hello();
     return client;

package/dist/tcp.d.ts

@@ -1,3 +1,3 @@
-import { type Transport } from "./transport.js";
+import { type Transport } from './transport.js';
 /** Node.js TCP transport for `yydb serve` binary frames. */
 export declare function openTcpTransport(endpoint: string): Promise<Transport>;

package/dist/tcp.js

@@ -1,28 +1,41 @@
-import { decodeFrame, encodeFrame } from "./wire.js";
-import { normalizeTcpHostPort } from "./transport.js";
+import { decodeFrame, decodeMicroHostInvoke, encodeFrame, encodeMicroHostInvokeOk, MsgType } from './wire.js';
+import { normalizeTcpHostPort } from './transport.js';
+async function readExact(readExactBytes, n) {
+    return readExactBytes(n);
+}
+async function readFrame(readExactBytes) {
+    const header = await readExact(readExactBytes, 20);
+    const bodyLen = new DataView(header.buffer, header.byteOffset, header.byteLength).getUint32(16, true);
+    const body = bodyLen > 0 ? await readExact(readExactBytes, bodyLen) : new Uint8Array();
+    const full = new Uint8Array(20 + body.byteLength);
+    full.set(header, 0);
+    full.set(body, 20);
+    return decodeFrame(full);
+}
 /** Node.js TCP transport for `yydb serve` binary frames. */
 export async function openTcpTransport(endpoint) {
-    const net = await import("node:net");
+    const net = await import('node:net');
     const hostport = normalizeTcpHostPort(endpoint);
-    const [host, portText] = hostport.includes("]:")
+    const [host, portText] = hostport.includes(']:')
         ? (() => {
             const rest = hostport.slice(1);
-            const idx = rest.indexOf("]:");
+            const idx = rest.indexOf(']:');
             return [rest.slice(0, idx), rest.slice(idx + 2)];
         })()
-        : hostport.split(":");
+        : hostport.split(':');
     const port = Number(portText);
     if (!host || !Number.isFinite(port)) {
         throw new Error(`invalid TCP endpoint: ${endpoint}`);
     }
     const socket = net.createConnection({ host, port });
     await new Promise((resolve, reject) => {
-        socket.once("connect", () => resolve());
-        socket.once("error", reject);
+        socket.once('connect', () => resolve());
+        socket.once('error', reject);
     });
     let buffer = new Uint8Array(0);
     const waiters = [];
-    socket.on("data", (chunk) => {
+    let microHostHandler;
+    socket.on('data', (chunk) => {
         const next = new Uint8Array(buffer.byteLength + chunk.byteLength);
         next.set(buffer, 0);
         next.set(chunk, buffer.byteLength);
@@ -31,7 +44,7 @@ export async function openTcpTransport(endpoint) {
             wake();
         }
     });
-    async function readExact(n) {
+    async function readExactBytes(n) {
         while (buffer.byteLength < n) {
             await new Promise((resolve) => waiters.push(resolve));
         }
@@ -39,24 +52,47 @@ export async function openTcpTransport(endpoint) {
         buffer = buffer.slice(n);
         return out;
     }
+    async function writeFrame(frame) {
+        const encoded = encodeFrame(frame);
+        await new Promise((resolve, reject) => {
+            socket.write(Buffer.from(encoded), (error) => {
+                if (error)
+                    reject(error);
+                else
+                    resolve();
+            });
+        });
+    }
+    async function handleServerPush(frame) {
+        if (frame.msgType !== MsgType.MicroHostInvoke) {
+            return false;
+        }
+        if (!microHostHandler) {
+            throw new Error('received MicroHostInvoke without a micro host handler');
+        }
+        const payload = decodeMicroHostInvoke(frame.body);
+        const result = await microHostHandler(payload);
+        await writeFrame({
+            msgType: MsgType.MicroHostInvokeOk,
+            flags: 0,
+            requestId: frame.requestId,
+            body: encodeMicroHostInvokeOk(result),
+        });
+        return true;
+    }
     return {
+        setMicroHostHandler(handler) {
+            microHostHandler = handler;
+        },
         async send(frame) {
-            const encoded = encodeFrame(frame);
-            await new Promise((resolve, reject) => {
-                socket.write(Buffer.from(encoded), (error) => {
-                    if (error)
-                        reject(error);
-                    else
-                        resolve();
-                });
-            });
-            const header = await readExact(20);
-            const bodyLen = new DataView(header.buffer, header.byteOffset, header.byteLength).getUint32(16, true);
-            const body = bodyLen > 0 ? await readExact(bodyLen) : new Uint8Array();
-            const full = new Uint8Array(20 + body.byteLength);
-            full.set(header, 0);
-            full.set(body, 20);
-            return decodeFrame(full);
+            await writeFrame(frame);
+            while (true) {
+                const response = await readFrame(readExactBytes);
+                if (await handleServerPush(response)) {
+                    continue;
+                }
+                return response;
+            }
         },
         close() {
             socket.end();

package/dist/transport.d.ts

@@ -1,7 +1,9 @@
-import type { Frame } from "./wire.js";
+import type { Frame, MicroHostInvokePayload, WireUdfScalarValue } from './wire.js';
+export type MicroHostHandler = (payload: MicroHostInvokePayload) => WireUdfScalarValue | Promise<WireUdfScalarValue>;
 export type Transport = {
     send(frame: Frame): Promise<Frame>;
     close(): void;
+    setMicroHostHandler?(handler: MicroHostHandler | undefined): void;
 };
 export declare function normalizeWsUrl(endpoint: string): string;
 export declare function normalizeTcpHostPort(endpoint: string): string;

package/dist/transport.js

@@ -1,23 +1,23 @@
 export function normalizeWsUrl(endpoint) {
     const trimmed = endpoint.trim();
-    if (trimmed.startsWith("ws://") || trimmed.startsWith("wss://")) {
-        if (trimmed.includes("/wire")) {
+    if (trimmed.startsWith('ws://') || trimmed.startsWith('wss://')) {
+        if (trimmed.includes('/wire')) {
             return trimmed;
         }
-        return trimmed.replace(/\/$/, "") + "/wire";
+        return trimmed.replace(/\/$/, '') + '/wire';
     }
     const hostport = trimmed
-        .replace(/^tcp:\/\//, "")
-        .replace(/^http:\/\//, "")
-        .split("/")[0];
+        .replace(/^tcp:\/\//, '')
+        .replace(/^http:\/\//, '')
+        .split('/')[0];
     return `ws://${hostport}/wire`;
 }
 export function normalizeTcpHostPort(endpoint) {
     const trimmed = endpoint
         .trim()
-        .replace(/^tcp:\/\//, "")
-        .replace(/^http:\/\//, "")
-        .replace(/^ws:\/\//, "")
-        .replace(/^wss:\/\//, "");
-    return trimmed.split("/")[0];
+        .replace(/^tcp:\/\//, '')
+        .replace(/^http:\/\//, '')
+        .replace(/^ws:\/\//, '')
+        .replace(/^wss:\/\//, '');
+    return trimmed.split('/')[0];
 }

package/dist/wire.d.ts

@@ -27,10 +27,26 @@ export declare const MsgType: {
     readonly KvGetOk: 10;
     readonly KvPut: 11;
     readonly KvPutOk: 12;
+    readonly MicroRegister: 13;
+    readonly MicroRegisterOk: 14;
+    readonly MicroHostInvoke: 15;
+    readonly MicroHostInvokeOk: 16;
+    readonly ScalarCall: 17;
+    readonly ScalarCallOk: 18;
     readonly Error: 255;
 };
+/** Phase-1 scalar kinds on the YY wire micro register path. */
+export type WireUdfScalarKind = 'null' | 'bool' | 'i64' | 'text';
+/** Phase-1 scalar value on the YY wire host invoke path. */
+export type WireUdfScalarValue = null | boolean | number | string;
+export interface MicroHostInvokePayload {
+    hostId: number;
+    handleVersion: number;
+    functionId: string;
+    args: readonly WireUdfScalarValue[];
+}
 export type MsgTypeCode = (typeof MsgType)[keyof typeof MsgType];
-export type ProductMagic = "YYDB" | "YYDS";
+export type ProductMagic = 'YYDB' | 'YYDS';
 export interface Frame {
     msgType: number;
     flags: number;
@@ -45,6 +61,25 @@ export declare function pushU32(out: number[], value: number): void;
 export declare function pushBytes(out: number[], bytes: Uint8Array): void;
 export declare function encodeSchemaEnsure(version: number, document: string): Uint8Array;
 export declare function encodeKvGet(key: string): Uint8Array;
+export interface MicroRegisterPayload {
+    hostId: number;
+    handleVersion: number;
+    udfVersion: number;
+    name: string;
+    functionId: string;
+    args: readonly WireUdfScalarKind[];
+    returns: WireUdfScalarKind;
+    fingerprint: Uint8Array;
+}
+/** Decode a `MicroHostInvoke` body. */
+export declare function decodeMicroHostInvoke(body: Uint8Array): MicroHostInvokePayload;
+/** Encode a `MicroHostInvokeOk` body. */
+export declare function encodeMicroHostInvokeOk(value: WireUdfScalarValue): Uint8Array;
+/** Encode a `ScalarCall` body. */
+export declare function encodeScalarCall(name: string, version: number, args: readonly WireUdfScalarValue[]): Uint8Array;
+/** Decode a `ScalarCallOk` body. */
+export declare function decodeScalarCallOk(body: Uint8Array): WireUdfScalarValue;
+export declare function encodeMicroRegister(payload: MicroRegisterPayload): Uint8Array;
 export declare function encodeKvPut(key: string, value: Uint8Array): Uint8Array;
 export interface SchemaVersion {
     version: number;

package/dist/wire.js

@@ -4,14 +4,14 @@
  * then four ASCII version digits (`0000` current, `0001` next).
  * Frontends accept either magic and do not require product consistency.
  */
-export const MAGIC_YYDB = new TextEncoder().encode("YYDB");
-export const MAGIC_YYDS = new TextEncoder().encode("YYDS");
+export const MAGIC_YYDB = new TextEncoder().encode('YYDB');
+export const MAGIC_YYDS = new TextEncoder().encode('YYDS');
 /** @deprecated Use MAGIC_YYDB — encode default product. */
 export const MAGIC = MAGIC_YYDB;
 /** Current wire version digits. */
-export const WIRE_VERSION = new TextEncoder().encode("0000");
+export const WIRE_VERSION = new TextEncoder().encode('0000');
 /** Next planned wire version (not spoken yet). */
-export const WIRE_VERSION_NEXT = new TextEncoder().encode("0001");
+export const WIRE_VERSION_NEXT = new TextEncoder().encode('0001');
 export const HEADER_LEN = 20;
 export const MAX_BODY_LEN = 16 * 1024 * 1024;
 export const MsgType = {
@@ -27,6 +27,12 @@ export const MsgType = {
     KvGetOk: 10,
     KvPut: 11,
     KvPutOk: 12,
+    MicroRegister: 13,
+    MicroRegisterOk: 14,
+    MicroHostInvoke: 15,
+    MicroHostInvokeOk: 16,
+    ScalarCall: 17,
+    ScalarCallOk: 18,
     Error: 255,
 };
 function writeU16(view, offset, value) {
@@ -42,24 +48,24 @@ function readU32(view, offset) {
     return view.getUint32(offset, true);
 }
 function productBytes(product) {
-    return product === "YYDS" ? MAGIC_YYDS : MAGIC_YYDB;
+    return product === 'YYDS' ? MAGIC_YYDS : MAGIC_YYDB;
 }
 function parseProduct(bytes) {
     const text = new TextDecoder().decode(bytes.subarray(0, 4));
-    if (text === "YYDB" || text === "YYDS") {
+    if (text === 'YYDB' || text === 'YYDS') {
         return text;
     }
-    throw new Error("wire frame bad product magic (want YYDB|YYDS)");
+    throw new Error('wire frame bad product magic (want YYDB|YYDS)');
 }
 function checkVersion(bytes) {
     const version = new TextDecoder().decode(bytes.subarray(4, 8));
-    if (version !== "0000") {
+    if (version !== '0000') {
         throw new Error(`wire version not supported (got ${version}, want 0000)`);
     }
 }
-export function encodeFrame(frame, product = "YYDB") {
+export function encodeFrame(frame, product = 'YYDB') {
     if (frame.body.byteLength > MAX_BODY_LEN) {
-        throw new Error("wire body too large");
+        throw new Error('wire body too large');
     }
     const out = new Uint8Array(HEADER_LEN + frame.body.byteLength);
     out.set(productBytes(product), 0);
@@ -74,7 +80,7 @@ export function encodeFrame(frame, product = "YYDB") {
 }
 export function decodeFrame(bytes) {
     if (bytes.byteLength < HEADER_LEN) {
-        throw new Error("wire frame truncated header");
+        throw new Error('wire frame truncated header');
     }
     const product = parseProduct(bytes);
     checkVersion(bytes);
@@ -84,11 +90,11 @@ export function decodeFrame(bytes) {
     const requestId = readU32(view, 12);
     const bodyLen = readU32(view, 16);
     if (bodyLen > MAX_BODY_LEN) {
-        throw new Error("wire body too large");
+        throw new Error('wire body too large');
     }
     const need = HEADER_LEN + bodyLen;
     if (bytes.byteLength < need) {
-        throw new Error("wire frame truncated body");
+        throw new Error('wire frame truncated body');
     }
     return {
         msgType,
@@ -118,6 +124,164 @@ export function encodeKvGet(key) {
     pushBytes(out, new TextEncoder().encode(key));
     return Uint8Array.from(out);
 }
+function encodeUdfTypeTag(kind) {
+    switch (kind) {
+        case 'null':
+            return 0;
+        case 'bool':
+            return 1;
+        case 'i64':
+            return 2;
+        case 'text':
+            return 3;
+        default:
+            throw new Error(`unsupported wire udf type: ${kind}`);
+    }
+}
+function pushU64(out, value) {
+    const view = new DataView(new ArrayBuffer(8));
+    view.setBigUint64(0, BigInt(value), true);
+    out.push(...new Uint8Array(view.buffer));
+}
+/** Encode a `MicroRegister` body. */
+function encodeUdfValue(out, value) {
+    if (value === null) {
+        out.push(0);
+        return;
+    }
+    if (typeof value === 'boolean') {
+        out.push(1, value ? 1 : 0);
+        return;
+    }
+    if (typeof value === 'number') {
+        out.push(2);
+        const view = new DataView(new ArrayBuffer(8));
+        view.setBigInt64(0, BigInt(value), true);
+        out.push(...new Uint8Array(view.buffer));
+        return;
+    }
+    if (typeof value === 'string') {
+        out.push(3);
+        pushBytes(out, new TextEncoder().encode(value));
+        return;
+    }
+    throw new Error('unsupported wire udf value');
+}
+function decodeUdfValue(body, offset) {
+    if (offset.n >= body.byteLength) {
+        throw new Error('wire scalar value missing tag');
+    }
+    const tag = body[offset.n];
+    offset.n += 1;
+    switch (tag) {
+        case 0:
+            return null;
+        case 1: {
+            if (offset.n >= body.byteLength) {
+                throw new Error('wire bool value truncated');
+            }
+            const value = body[offset.n] !== 0;
+            offset.n += 1;
+            return value;
+        }
+        case 2: {
+            if (offset.n + 8 > body.byteLength) {
+                throw new Error('wire i64 value truncated');
+            }
+            const view = new DataView(body.buffer, body.byteOffset, body.byteLength);
+            const value = Number(view.getBigInt64(offset.n, true));
+            offset.n += 8;
+            return value;
+        }
+        case 3: {
+            const len = readU32At(body, offset);
+            const bytes = readBytesAt(body, offset, len);
+            return new TextDecoder().decode(bytes);
+        }
+        default:
+            throw new Error('wire scalar value has invalid type tag');
+    }
+}
+function encodeUdfValues(values) {
+    if (values.length > 255) {
+        throw new Error('wire scalar arg count exceeds u8');
+    }
+    const out = [values.length];
+    for (const value of values) {
+        encodeUdfValue(out, value);
+    }
+    return out;
+}
+function decodeUdfValues(body, offset) {
+    if (offset.n >= body.byteLength) {
+        throw new Error('wire scalar args missing count');
+    }
+    const count = body[offset.n];
+    offset.n += 1;
+    const values = [];
+    for (let index = 0; index < count; index += 1) {
+        values.push(decodeUdfValue(body, offset));
+    }
+    return values;
+}
+/** Decode a `MicroHostInvoke` body. */
+export function decodeMicroHostInvoke(body) {
+    const offset = { n: 0 };
+    const hostId = Number(readU64At(body, offset));
+    const handleVersion = readU32At(body, offset);
+    const functionIdLen = readU32At(body, offset);
+    const functionId = new TextDecoder().decode(readBytesAt(body, offset, functionIdLen));
+    const args = decodeUdfValues(body, offset);
+    return { hostId, handleVersion, functionId, args };
+}
+/** Encode a `MicroHostInvokeOk` body. */
+export function encodeMicroHostInvokeOk(value) {
+    const out = [];
+    encodeUdfValue(out, value);
+    return Uint8Array.from(out);
+}
+/** Encode a `ScalarCall` body. */
+export function encodeScalarCall(name, version, args) {
+    const out = [];
+    pushU32(out, version >>> 0);
+    pushBytes(out, new TextEncoder().encode(name));
+    out.push(...encodeUdfValues(args));
+    return Uint8Array.from(out);
+}
+/** Decode a `ScalarCallOk` body. */
+export function decodeScalarCallOk(body) {
+    return decodeUdfValue(body, { n: 0 });
+}
+function readU64At(body, offset) {
+    if (offset.n + 8 > body.byteLength) {
+        throw new Error('wire body truncated u64');
+    }
+    const view = new DataView(body.buffer, body.byteOffset, body.byteLength);
+    const value = view.getBigUint64(offset.n, true);
+    offset.n += 8;
+    return value;
+}
+export function encodeMicroRegister(payload) {
+    if (payload.fingerprint.byteLength !== 32) {
+        throw new Error('micro register fingerprint must be 32 bytes');
+    }
+    const out = [];
+    pushU64(out, payload.hostId);
+    pushU32(out, payload.handleVersion);
+    pushU32(out, payload.udfVersion);
+    pushBytes(out, new TextEncoder().encode(payload.name));
+    pushBytes(out, new TextEncoder().encode(payload.functionId));
+    if (payload.args.length > 255) {
+        throw new Error('micro register supports at most 255 args');
+    }
+    out.push(payload.args.length);
+    for (const arg of payload.args) {
+        out.push(encodeUdfTypeTag(arg));
+    }
+    out.push(encodeUdfTypeTag(payload.returns));
+    out.push(...payload.fingerprint);
+    return Uint8Array.from(out);
+}
 export function encodeKvPut(key, value) {
     const out = [];
     pushBytes(out, new TextEncoder().encode(key));
@@ -126,7 +290,7 @@ export function encodeKvPut(key, value) {
 }
 function readU32At(body, offset) {
     if (offset.n + 4 > body.byteLength) {
-        throw new Error("wire body truncated u32");
+        throw new Error('wire body truncated u32');
     }
     const view = new DataView(body.buffer, body.byteOffset, body.byteLength);
     const value = readU32(view, offset.n);
@@ -135,7 +299,7 @@ function readU32At(body, offset) {
 }
 function readBytesAt(body, offset, len) {
     if (offset.n + len > body.byteLength) {
-        throw new Error("wire body truncated bytes");
+        throw new Error('wire body truncated bytes');
     }
     const slice = body.slice(offset.n, offset.n + len);
     offset.n += len;
@@ -143,7 +307,7 @@ function readBytesAt(body, offset, len) {
 }
 export function decodeSchemaGetOk(body) {
     if (body.byteLength === 0) {
-        throw new Error("schema get ok empty");
+        throw new Error('schema get ok empty');
     }
     if (body[0] === 0) {
         return null;
@@ -156,7 +320,7 @@ export function decodeSchemaGetOk(body) {
 }
 export function decodeKvGetOk(body) {
     if (body.byteLength === 0) {
-        throw new Error("kv get ok empty");
+        throw new Error('kv get ok empty');
     }
     if (body[0] === 0) {
         return null;

package/dist/ws.d.ts

@@ -1,3 +1,3 @@
-import { type Transport } from "./transport.js";
+import { type Transport } from './transport.js';
 /** Browser / any host with WebSocket — path `/wire`, binary frames. */
 export declare function openWebSocketTransport(endpoint: string): Promise<Transport>;

package/dist/ws.js

@@ -1,45 +1,65 @@
-import { decodeFrame, encodeFrame } from "./wire.js";
-import { normalizeWsUrl } from "./transport.js";
+import { decodeFrame, decodeMicroHostInvoke, encodeFrame, encodeMicroHostInvokeOk, MsgType } from './wire.js';
+import { normalizeWsUrl } from './transport.js';
 /** Browser / any host with WebSocket — path `/wire`, binary frames. */
 export async function openWebSocketTransport(endpoint) {
     const url = normalizeWsUrl(endpoint);
     const ws = new WebSocket(url);
-    ws.binaryType = "arraybuffer";
+    ws.binaryType = 'arraybuffer';
     await new Promise((resolve, reject) => {
-        ws.addEventListener("open", () => resolve(), { once: true });
-        ws.addEventListener("error", () => reject(new Error(`websocket failed: ${url}`)), { once: true });
+        ws.addEventListener('open', () => resolve(), { once: true });
+        ws.addEventListener('error', () => reject(new Error(`websocket failed: ${url}`)), {
+            once: true,
+        });
     });
-    let pending = null;
-    ws.addEventListener("message", (event) => {
-        try {
-            const data = event.data instanceof ArrayBuffer
-                ? new Uint8Array(event.data)
-                : new Uint8Array(event.data);
-            const frame = decodeFrame(data);
-            if (pending) {
-                const slot = pending;
-                pending = null;
-                slot.resolve(frame);
-            }
-        }
-        catch (error) {
-            if (pending) {
-                const slot = pending;
-                pending = null;
-                slot.reject(error);
-            }
+    let microHostHandler;
+    const buffer = [];
+    const waiters = [];
+    ws.addEventListener('message', (event) => {
+        const data = event.data instanceof ArrayBuffer ? new Uint8Array(event.data) : new Uint8Array(event.data);
+        buffer.push(decodeFrame(data));
+        for (const wake of waiters.splice(0)) {
+            wake();
         }
     });
+    async function readFrame() {
+        while (buffer.length === 0) {
+            await new Promise((resolve) => waiters.push(resolve));
+        }
+        return buffer.shift();
+    }
+    async function writeFrame(frame) {
+        ws.send(encodeFrame(frame));
+    }
+    async function handleServerPush(frame) {
+        if (frame.msgType !== MsgType.MicroHostInvoke) {
+            return false;
+        }
+        if (!microHostHandler) {
+            throw new Error('received MicroHostInvoke without a micro host handler');
+        }
+        const payload = decodeMicroHostInvoke(frame.body);
+        const result = await microHostHandler(payload);
+        await writeFrame({
+            msgType: MsgType.MicroHostInvokeOk,
+            flags: 0,
+            requestId: frame.requestId,
+            body: encodeMicroHostInvokeOk(result),
+        });
+        return true;
+    }
     return {
-        send(frame) {
-            return new Promise((resolve, reject) => {
-                if (pending) {
-                    reject(new Error("overlapping websocket requests"));
-                    return;
+        setMicroHostHandler(handler) {
+            microHostHandler = handler;
+        },
+        async send(frame) {
+            await writeFrame(frame);
+            while (true) {
+                const response = await readFrame();
+                if (await handleServerPush(response)) {
+                    continue;
                 }
-                pending = { resolve, reject };
-                ws.send(encodeFrame(frame));
-            });
+                return response;
+            }
         },
         close() {
             ws.close();

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@yydb/yydb-client",
-  "version": "0.0.1",
-  "description": "TypeScript client for YY wire protocol v1 (VOS-native; YYDB/YYDS/compatible hosts)",
-  "license": "MIT",
+  "version": "0.0.3",
+  "description": "TypeScript client for the YYDB WebSocket and TCP wire protocol",
+  "license": "MPL-2.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -26,12 +26,12 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/yy-database/yydb.rs.git",
-    "directory": "frontends/yydb-client"
+    "url": "git+https://github.com/yy-database/yydb.git",
+    "directory": "projects/packages/yydb-client"
   },
-  "homepage": "https://github.com/yy-database/yydb.rs/tree/dev/frontends/yydb-client#readme",
+  "homepage": "https://github.com/yy-database/yydb/tree/dev/projects/packages/yydb-client#readme",
   "bugs": {
-    "url": "https://github.com/yy-database/yydb.rs/issues"
+    "url": "https://github.com/yy-database/yydb/issues"
   },
   "keywords": [
     "yydb",