@yydb/yydb-client 0.0.0 → 0.0.2

package/README.md

@@ -1,4 +1,79 @@
-# @yydb/yydb-client
+# `@yydb/yydb-client`
 
-Placeholder 0.0.0 for npm Trusted Publisher bootstrap.
-Real releases replace this from CI (`release-npm.yml`).
+**Lightweight TypeScript client for the YY wire protocol (WebSocket or TCP).**
+
+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.
+
+[![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)
+
+## Install
+
+```bash
+npm install @yydb/yydb-client
+```
+
+## Browser or WebSocket
+
+Start a local host first:
+
+```text
+yydb serve app.yydb --bind 127.0.0.1:7700
+```
+
+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

@@ -0,0 +1,39 @@
+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;
+}
+/**
+ * TypeScript client for YY wire (browser = WebSocket `/wire`).
+ * Accepts product magic `YYDB` or `YYDS` as equivalent self-claims (same wire);
+ * does not require the magic to match a preferred product. Version gate: `0000`.
+ */
+export declare class Client {
+    readonly endpoint: string;
+    private transport;
+    private nextId;
+    private constructor();
+    /** Construct from an already-open transport (used by Node TCP entry). */
+    static fromTransport(endpoint: string, transport: Transport): Client;
+    /** Open WebSocket to `yydb serve` `/wire` and Hello-handshake. */
+    static connect(options: ConnectOptions | string): Promise<Client>;
+    close(): void;
+    hello(): Promise<string>;
+    serverVersion(): Promise<string>;
+    info(): Promise<string>;
+    getSchema(): Promise<SchemaVersion | null>;
+    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

@@ -0,0 +1,104 @@
+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);
+ * does not require the magic to match a preferred product. Version gate: `0000`.
+ */
+export class Client {
+    endpoint;
+    transport;
+    nextId = 1;
+    constructor(endpoint, transport) {
+        this.endpoint = endpoint;
+        this.transport = transport;
+    }
+    /** Construct from an already-open transport (used by Node TCP entry). */
+    static fromTransport(endpoint, transport) {
+        return new Client(endpoint, transport);
+    }
+    /** Open WebSocket to `yydb serve` `/wire` and Hello-handshake. */
+    static async connect(options) {
+        const endpoint = typeof options === 'string' ? options : options.endpoint;
+        if (!endpoint.trim()) {
+            throw new Error('empty serve endpoint');
+        }
+        const transport = await openWebSocketTransport(endpoint);
+        const client = new Client(endpoint, transport);
+        await client.hello();
+        return client;
+    }
+    close() {
+        this.transport.close();
+    }
+    async hello() {
+        const response = await this.roundtrip(MsgType.Hello, new Uint8Array());
+        return new TextDecoder().decode(response.body);
+    }
+    async serverVersion() {
+        return this.hello();
+    }
+    async info() {
+        const response = await this.roundtrip(MsgType.Info, new Uint8Array());
+        return new TextDecoder().decode(response.body);
+    }
+    async getSchema() {
+        const response = await this.roundtrip(MsgType.SchemaGet, new Uint8Array());
+        return decodeSchemaGetOk(response.body);
+    }
+    async ensureSchema(version, document) {
+        await this.roundtrip(MsgType.SchemaEnsure, encodeSchemaEnsure(version, document));
+    }
+    async get(key) {
+        const response = await this.roundtrip(MsgType.KvGet, encodeKvGet(key));
+        return decodeKvGetOk(response.body);
+    }
+    async put(key, 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({
+            msgType,
+            flags: 0,
+            requestId,
+            body,
+        });
+        if (response.requestId !== requestId) {
+            throw new Error('wire response request_id mismatch');
+        }
+        if (response.msgType === MsgType.Error) {
+            throw new Error(new TextDecoder().decode(response.body));
+        }
+        const expectedOk = {
+            [MsgType.Hello]: MsgType.HelloOk,
+            [MsgType.Info]: MsgType.InfoOk,
+            [MsgType.SchemaGet]: MsgType.SchemaGetOk,
+            [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) {
+            throw new Error(`unexpected wire response type ${response.msgType}`);
+        }
+        return response;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +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';

package/dist/index.js

@@ -0,0 +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';

package/dist/node.d.ts

@@ -0,0 +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';
+/** Node entry: TCP by default; `ws://` uses WebSocket. */
+export declare function connect(options: ConnectOptions | string): Promise<Client>;

package/dist/node.js

@@ -0,0 +1,21 @@
+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://');
+}
+/** Node entry: TCP by default; `ws://` uses WebSocket. */
+export async function connect(options) {
+    const endpoint = typeof options === 'string' ? options : options.endpoint;
+    if (!endpoint.trim()) {
+        throw new Error('empty serve 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

@@ -0,0 +1,3 @@
+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

@@ -0,0 +1,101 @@
+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 hostport = normalizeTcpHostPort(endpoint);
+    const [host, portText] = hostport.includes(']:')
+        ? (() => {
+            const rest = hostport.slice(1);
+            const idx = rest.indexOf(']:');
+            return [rest.slice(0, idx), rest.slice(idx + 2)];
+        })()
+        : 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);
+    });
+    let buffer = new Uint8Array(0);
+    const waiters = [];
+    let microHostHandler;
+    socket.on('data', (chunk) => {
+        const next = new Uint8Array(buffer.byteLength + chunk.byteLength);
+        next.set(buffer, 0);
+        next.set(chunk, buffer.byteLength);
+        buffer = next;
+        for (const wake of waiters.splice(0)) {
+            wake();
+        }
+    });
+    async function readExactBytes(n) {
+        while (buffer.byteLength < n) {
+            await new Promise((resolve) => waiters.push(resolve));
+        }
+        const out = buffer.slice(0, n);
+        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) {
+            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

@@ -0,0 +1,9 @@
+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

@@ -0,0 +1,23 @@
+export function normalizeWsUrl(endpoint) {
+    const trimmed = endpoint.trim();
+    if (trimmed.startsWith('ws://') || trimmed.startsWith('wss://')) {
+        if (trimmed.includes('/wire')) {
+            return trimmed;
+        }
+        return trimmed.replace(/\/$/, '') + '/wire';
+    }
+    const hostport = trimmed
+        .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];
+}

package/dist/wire.d.ts

@@ -0,0 +1,89 @@
+/**
+ * YY wire protocol — VOS-native serve frames.
+ * Prefix: product magic `YYDB` | `YYDS` (backend self-claim only; same effect),
+ * then four ASCII version digits (`0000` current, `0001` next).
+ * Frontends accept either magic and do not require product consistency.
+ */
+export declare const MAGIC_YYDB: Uint8Array;
+export declare const MAGIC_YYDS: Uint8Array;
+/** @deprecated Use MAGIC_YYDB — encode default product. */
+export declare const MAGIC: Uint8Array;
+/** Current wire version digits. */
+export declare const WIRE_VERSION: Uint8Array;
+/** Next planned wire version (not spoken yet). */
+export declare const WIRE_VERSION_NEXT: Uint8Array;
+export declare const HEADER_LEN = 20;
+export declare const MAX_BODY_LEN: number;
+export declare const MsgType: {
+    readonly Hello: 1;
+    readonly HelloOk: 2;
+    readonly Info: 3;
+    readonly InfoOk: 4;
+    readonly SchemaGet: 5;
+    readonly SchemaGetOk: 6;
+    readonly SchemaEnsure: 7;
+    readonly SchemaEnsureOk: 8;
+    readonly KvGet: 9;
+    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 interface Frame {
+    msgType: number;
+    flags: number;
+    requestId: number;
+    body: Uint8Array;
+    /** Product magic observed on decode (backend self-claim; optional to ignore). */
+    product?: ProductMagic;
+}
+export declare function encodeFrame(frame: Frame, product?: ProductMagic): Uint8Array;
+export declare function decodeFrame(bytes: Uint8Array): Frame;
+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;
+    document: string;
+}
+export declare function decodeSchemaGetOk(body: Uint8Array): SchemaVersion | null;
+export declare function decodeKvGetOk(body: Uint8Array): Uint8Array | null;

package/dist/wire.js

@@ -0,0 +1,331 @@
+/**
+ * YY wire protocol — VOS-native serve frames.
+ * Prefix: product magic `YYDB` | `YYDS` (backend self-claim only; same effect),
+ * 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');
+/** @deprecated Use MAGIC_YYDB — encode default product. */
+export const MAGIC = MAGIC_YYDB;
+/** Current wire version digits. */
+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 HEADER_LEN = 20;
+export const MAX_BODY_LEN = 16 * 1024 * 1024;
+export const MsgType = {
+    Hello: 1,
+    HelloOk: 2,
+    Info: 3,
+    InfoOk: 4,
+    SchemaGet: 5,
+    SchemaGetOk: 6,
+    SchemaEnsure: 7,
+    SchemaEnsureOk: 8,
+    KvGet: 9,
+    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) {
+    view.setUint16(offset, value, true);
+}
+function writeU32(view, offset, value) {
+    view.setUint32(offset, value, true);
+}
+function readU16(view, offset) {
+    return view.getUint16(offset, true);
+}
+function readU32(view, offset) {
+    return view.getUint32(offset, true);
+}
+function productBytes(product) {
+    return product === 'YYDS' ? MAGIC_YYDS : MAGIC_YYDB;
+}
+function parseProduct(bytes) {
+    const text = new TextDecoder().decode(bytes.subarray(0, 4));
+    if (text === 'YYDB' || text === 'YYDS') {
+        return text;
+    }
+    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') {
+        throw new Error(`wire version not supported (got ${version}, want 0000)`);
+    }
+}
+export function encodeFrame(frame, product = 'YYDB') {
+    if (frame.body.byteLength > MAX_BODY_LEN) {
+        throw new Error('wire body too large');
+    }
+    const out = new Uint8Array(HEADER_LEN + frame.body.byteLength);
+    out.set(productBytes(product), 0);
+    out.set(WIRE_VERSION, 4);
+    const view = new DataView(out.buffer);
+    writeU16(view, 8, frame.msgType);
+    writeU16(view, 10, frame.flags);
+    writeU32(view, 12, frame.requestId);
+    writeU32(view, 16, frame.body.byteLength);
+    out.set(frame.body, HEADER_LEN);
+    return out;
+}
+export function decodeFrame(bytes) {
+    if (bytes.byteLength < HEADER_LEN) {
+        throw new Error('wire frame truncated header');
+    }
+    const product = parseProduct(bytes);
+    checkVersion(bytes);
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const msgType = readU16(view, 8);
+    const flags = readU16(view, 10);
+    const requestId = readU32(view, 12);
+    const bodyLen = readU32(view, 16);
+    if (bodyLen > MAX_BODY_LEN) {
+        throw new Error('wire body too large');
+    }
+    const need = HEADER_LEN + bodyLen;
+    if (bytes.byteLength < need) {
+        throw new Error('wire frame truncated body');
+    }
+    return {
+        msgType,
+        flags,
+        requestId,
+        body: bytes.slice(HEADER_LEN, need),
+        product,
+    };
+}
+export function pushU32(out, value) {
+    out.push(value & 0xff, (value >> 8) & 0xff, (value >> 16) & 0xff, (value >> 24) & 0xff);
+}
+export function pushBytes(out, bytes) {
+    pushU32(out, bytes.byteLength);
+    for (let i = 0; i < bytes.byteLength; i++) {
+        out.push(bytes[i]);
+    }
+}
+export function encodeSchemaEnsure(version, document) {
+    const out = [];
+    pushU32(out, version >>> 0);
+    pushBytes(out, new TextEncoder().encode(document));
+    return Uint8Array.from(out);
+}
+export function encodeKvGet(key) {
+    const out = [];
+    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));
+    pushBytes(out, value);
+    return Uint8Array.from(out);
+}
+function readU32At(body, offset) {
+    if (offset.n + 4 > body.byteLength) {
+        throw new Error('wire body truncated u32');
+    }
+    const view = new DataView(body.buffer, body.byteOffset, body.byteLength);
+    const value = readU32(view, offset.n);
+    offset.n += 4;
+    return value;
+}
+function readBytesAt(body, offset, len) {
+    if (offset.n + len > body.byteLength) {
+        throw new Error('wire body truncated bytes');
+    }
+    const slice = body.slice(offset.n, offset.n + len);
+    offset.n += len;
+    return slice;
+}
+export function decodeSchemaGetOk(body) {
+    if (body.byteLength === 0) {
+        throw new Error('schema get ok empty');
+    }
+    if (body[0] === 0) {
+        return null;
+    }
+    const offset = { n: 1 };
+    const version = readU32At(body, offset);
+    const docLen = readU32At(body, offset);
+    const doc = readBytesAt(body, offset, docLen);
+    return { version, document: new TextDecoder().decode(doc) };
+}
+export function decodeKvGetOk(body) {
+    if (body.byteLength === 0) {
+        throw new Error('kv get ok empty');
+    }
+    if (body[0] === 0) {
+        return null;
+    }
+    const offset = { n: 1 };
+    const valLen = readU32At(body, offset);
+    return readBytesAt(body, offset, valLen);
+}

package/dist/ws.d.ts

@@ -0,0 +1,3 @@
+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

@@ -0,0 +1,68 @@
+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';
+    await new Promise((resolve, reject) => {
+        ws.addEventListener('open', () => resolve(), { once: true });
+        ws.addEventListener('error', () => reject(new Error(`websocket failed: ${url}`)), {
+            once: true,
+        });
+    });
+    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 {
+        setMicroHostHandler(handler) {
+            microHostHandler = handler;
+        },
+        async send(frame) {
+            await writeFrame(frame);
+            while (true) {
+                const response = await readFrame();
+                if (await handleServerPush(response)) {
+                    continue;
+                }
+                return response;
+            }
+        },
+        close() {
+            ws.close();
+        },
+    };
+}

package/package.json

@@ -1,14 +1,53 @@
 {
   "name": "@yydb/yydb-client",
-  "version": "0.0.0",
-  "description": "Placeholder — YY wire TypeScript client",
-  "license": "MIT",
-  "private": false,
-  "publishConfig": {
-    "access": "public"
+  "version": "0.0.2",
+  "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",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "import": "./dist/node.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --experimental-strip-types --test src/wire.test.ts"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/yy-database/yydb.git"
+    "url": "git+https://github.com/yy-database/yydb.git",
+    "directory": "projects/packages/yydb-client"
+  },
+  "homepage": "https://github.com/yy-database/yydb/tree/dev/projects/packages/yydb-client#readme",
+  "bugs": {
+    "url": "https://github.com/yy-database/yydb/issues"
+  },
+  "keywords": [
+    "yydb",
+    "yyds",
+    "vos",
+    "wire-protocol",
+    "typescript"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "typescript": "~5.3.0"
+  },
+  "engines": {
+    "node": ">=18"
   }
 }