@yydb/yydb-client 0.0.5 → 0.0.7

package/README.md

@@ -14,7 +14,7 @@ browser, WebUI, Electron renderer, or a thin Node process.
 | `@yydb/yydb-client`      | WebSocket `/wire` | Browsers and WebUI |
 | `@yydb/yydb-client/node` | TCP or WebSocket  | Node and Electron  |
 
-Frame helpers (`encodeFrame`, `MsgType`, …) are exported for tools and tests.
+Frame helpers (`encodeFrame`, `MessageType`, …) are exported for tools and tests.
 
 ## Example
 

package/dist/client.d.ts

@@ -1,8 +1,10 @@
 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 { Frame, MicroHostInvokePayload, MicroRegisterPayload, MsgTypeCode, SchemaVersion, WireErrorBody, WireUdfScalarKind, WireUdfScalarValue, } from './wire.js';
 export type { MicroHostHandler } from './transport.js';
-export { MsgType, encodeFrame, decodeFrame } from './wire.js';
+export { MsgType, encodeFrame, decodeFrame, encodeErrorBody, decodeErrorBody } from './wire.js';
+export { YydbError, YydbErrorCodes, isRetryableYydbCode, isYydbError } from './errors.js';
+export type { YydbErrorCode, YydbErrorOptions } from './errors.js';
 export interface ConnectOptions {
     /** `ws://127.0.0.1:7700/wire` or `127.0.0.1:7700` (upgraded to `/wire`). */
     endpoint: string;
@@ -16,12 +18,16 @@ export declare class Client {
     readonly endpoint: string;
     private transport;
     private nextId;
+    private closed;
     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 the transport. Idempotent — further calls fail with `yydb.session.closed`. */
     close(): void;
+    /** Whether {@link close} already ran. */
+    isClosed(): boolean;
     hello(): Promise<string>;
     serverVersion(): Promise<string>;
     info(): Promise<string>;

package/dist/client.js

@@ -1,6 +1,19 @@
-import { decodeKvGetOk, decodeScalarCallOk, decodeSchemaGetOk, encodeKvGet, encodeKvPut, encodeMicroRegister, encodeScalarCall, encodeSchemaEnsure, MsgType, } from './wire.js';
+import { decodeErrorBody, decodeKvGetOk, decodeScalarCallOk, decodeSchemaGetOk, encodeKvGet, encodeKvPut, encodeMicroRegister, encodeScalarCall, encodeSchemaEnsure, MsgType, } from './wire.js';
 import { openWebSocketTransport } from './ws.js';
-export { MsgType, encodeFrame, decodeFrame } from './wire.js';
+import { YydbError, YydbErrorCodes } from './errors.js';
+export { MsgType, encodeFrame, decodeFrame, encodeErrorBody, decodeErrorBody } from './wire.js';
+export { YydbError, YydbErrorCodes, isRetryableYydbCode, isYydbError } from './errors.js';
+/** Expected reply type and operation label per request type. */
+const REQUESTS = {
+    [MsgType.Hello]: { operation: 'hello', ok: MsgType.HelloOk },
+    [MsgType.Info]: { operation: 'info', ok: MsgType.InfoOk },
+    [MsgType.SchemaGet]: { operation: 'schemaGet', ok: MsgType.SchemaGetOk },
+    [MsgType.SchemaEnsure]: { operation: 'schemaEnsure', ok: MsgType.SchemaEnsureOk },
+    [MsgType.KvGet]: { operation: 'kvGet', ok: MsgType.KvGetOk },
+    [MsgType.KvPut]: { operation: 'kvPut', ok: MsgType.KvPutOk },
+    [MsgType.MicroRegister]: { operation: 'microRegister', ok: MsgType.MicroRegisterOk },
+    [MsgType.ScalarCall]: { operation: 'scalarCall', ok: MsgType.ScalarCallOk },
+};
 /**
  * TypeScript client for YY wire (browser = WebSocket `/wire`).
  * Accepts product magic `YYDB` or `YYDS` as equivalent self-claims (same wire);
@@ -10,6 +23,7 @@ export class Client {
     endpoint;
     transport;
     nextId = 1;
+    closed = false;
     constructor(endpoint, transport) {
         this.endpoint = endpoint;
         this.transport = transport;
@@ -22,16 +36,36 @@ export class Client {
     static async connect(options) {
         const endpoint = typeof options === 'string' ? options : options.endpoint;
         if (!endpoint.trim()) {
-            throw new Error('empty serve endpoint');
+            throw new YydbError(YydbErrorCodes.clientInvalidEndpoint, 'empty serve endpoint', {
+                operation: 'connect',
+            });
+        }
+        let transport;
+        try {
+            transport = await openWebSocketTransport(endpoint);
+        }
+        catch (cause) {
+            throw new YydbError(YydbErrorCodes.clientTransportFailure, `connect ${endpoint}: transport failed`, {
+                operation: 'connect',
+                cause,
+            });
         }
-        const transport = await openWebSocketTransport(endpoint);
         const client = new Client(endpoint, transport);
         await client.hello();
         return client;
     }
+    /** Close the transport. Idempotent — further calls fail with `yydb.session.closed`. */
     close() {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
         this.transport.close();
     }
+    /** Whether {@link close} already ran. */
+    isClosed() {
+        return this.closed;
+    }
     async hello() {
         const response = await this.roundtrip(MsgType.Hello, new Uint8Array());
         return new TextDecoder().decode(response.body);
@@ -72,33 +106,46 @@ export class Client {
         return decodeScalarCallOk(response.body);
     }
     async roundtrip(msgType, body) {
+        const request = REQUESTS[msgType];
+        const operation = request?.operation ?? `msgType(${msgType})`;
+        if (this.closed) {
+            throw new YydbError(YydbErrorCodes.sessionClosed, `${operation}: YYDB session is closed`, { operation });
+        }
         const requestId = this.nextId++;
-        const response = await this.transport.send({
-            msgType,
-            flags: 0,
-            requestId,
-            body,
-        });
+        let response;
+        try {
+            response = await this.transport.send({
+                msgType,
+                flags: 0,
+                requestId,
+                body,
+            });
+        }
+        catch (cause) {
+            throw new YydbError(YydbErrorCodes.clientTransportFailure, `${operation}: transport failed`, { operation, cause });
+        }
         if (response.requestId !== requestId) {
-            throw new Error('wire response request_id mismatch');
+            throw new YydbError(YydbErrorCodes.clientRequestIdMismatch, `${operation}: wire response request_id mismatch (got ${response.requestId}, want ${requestId})`, { operation });
         }
         if (response.msgType === MsgType.Error) {
-            throw new Error(new TextDecoder().decode(response.body));
+            throw remoteError(response.body, operation);
         }
-        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}`);
+        if (request && response.msgType !== request.ok) {
+            throw new YydbError(YydbErrorCodes.clientUnexpectedResponse, `${operation}: unexpected wire response type ${response.msgType}`, {
+                operation,
+            });
         }
         return response;
     }
 }
+/** Turn an `Error` frame into a {@link YydbError}, keeping the engine code. */
+function remoteError(body, operation) {
+    let decoded;
+    try {
+        decoded = decodeErrorBody(body);
+    }
+    catch (cause) {
+        return new YydbError(YydbErrorCodes.clientDecodeFailure, `${operation}: malformed wire error frame`, { operation, cause });
+    }
+    return new YydbError(decoded.code, decoded.message, { operation });
+}

package/dist/errors.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Host-facing YYDB error surface.
+ *
+ * Every public failure carries a stable `code`: engine codes come from the
+ * Rust core (`yydb.schema.invalid`, …) over the wire, client codes are minted
+ * locally with the `yydb.client.` prefix. Branch on `code` — `message` is
+ * display text only.
+ */
+/** Stable codes known to the TypeScript hosts. */
+export declare const YydbErrorCodes: {
+    readonly io: "yydb.io";
+    readonly corrupt: "yydb.corrupt";
+    readonly schemaConflict: "yydb.schema.conflict";
+    readonly schemaInvalid: "yydb.schema.invalid";
+    readonly udfNotFound: "yydb.udf.not_found";
+    readonly udfArity: "yydb.udf.arity";
+    readonly udfFailed: "yydb.udf.failed";
+    readonly udfVersionMismatch: "yydb.udf.version_mismatch";
+    readonly objectNotFound: "yydb.object.not_found";
+    readonly objectCorrupt: "yydb.object.corrupt";
+    readonly unsupported: "yydb.unsupported";
+    readonly protocol: "yydb.protocol";
+    readonly casConflict: "yydb.cas.conflict";
+    readonly leaseUnavailable: "yydb.lease.unavailable";
+    readonly fencingMismatch: "yydb.fencing.mismatch";
+    readonly leaseExpired: "yydb.lease.expired";
+    readonly quotaExceeded: "yydb.quota.exceeded";
+    readonly sessionClosed: "yydb.session.closed";
+    readonly clientInvalidEndpoint: "yydb.client.invalid_endpoint";
+    readonly clientTransportFailure: "yydb.client.transport_failure";
+    readonly clientRequestIdMismatch: "yydb.client.request_id_mismatch";
+    readonly clientUnexpectedResponse: "yydb.client.unexpected_response";
+    readonly clientDecodeFailure: "yydb.client.decode_failure";
+};
+/** A known code, or any future code the engine introduces. */
+export type YydbErrorCode = (typeof YydbErrorCodes)[keyof typeof YydbErrorCodes] | (string & {});
+/** Whether `code` may be retried with the same arguments. */
+export declare function isRetryableYydbCode(code: string): boolean;
+/** Options carried by a {@link YydbError}. */
+export interface YydbErrorOptions {
+    /** Operation that failed (`schemaGet`, `kvPut`, `query`, …). */
+    operation?: string;
+    /** Underlying failure when this error wraps one. */
+    cause?: unknown;
+}
+/** YYDB failure with a stable machine-readable {@link YydbError.code}. */
+export declare class YydbError extends Error {
+    /** Stable code — engine code or `yydb.client.*`. */
+    readonly code: string;
+    /** Operation that failed. */
+    readonly operation: string;
+    /** Whether the same call may be retried. */
+    readonly retryable: boolean;
+    constructor(code: YydbErrorCode, message: string, options?: YydbErrorOptions);
+}
+/** Narrowing helper so callers can branch without `instanceof` imports. */
+export declare function isYydbError(value: unknown): value is YydbError;

package/dist/errors.js

@@ -0,0 +1,68 @@
+/**
+ * Host-facing YYDB error surface.
+ *
+ * Every public failure carries a stable `code`: engine codes come from the
+ * Rust core (`yydb.schema.invalid`, …) over the wire, client codes are minted
+ * locally with the `yydb.client.` prefix. Branch on `code` — `message` is
+ * display text only.
+ */
+/** Stable codes known to the TypeScript hosts. */
+export const YydbErrorCodes = {
+    io: 'yydb.io',
+    corrupt: 'yydb.corrupt',
+    schemaConflict: 'yydb.schema.conflict',
+    schemaInvalid: 'yydb.schema.invalid',
+    udfNotFound: 'yydb.udf.not_found',
+    udfArity: 'yydb.udf.arity',
+    udfFailed: 'yydb.udf.failed',
+    udfVersionMismatch: 'yydb.udf.version_mismatch',
+    objectNotFound: 'yydb.object.not_found',
+    objectCorrupt: 'yydb.object.corrupt',
+    unsupported: 'yydb.unsupported',
+    protocol: 'yydb.protocol',
+    casConflict: 'yydb.cas.conflict',
+    leaseUnavailable: 'yydb.lease.unavailable',
+    fencingMismatch: 'yydb.fencing.mismatch',
+    leaseExpired: 'yydb.lease.expired',
+    quotaExceeded: 'yydb.quota.exceeded',
+    sessionClosed: 'yydb.session.closed',
+    clientInvalidEndpoint: 'yydb.client.invalid_endpoint',
+    clientTransportFailure: 'yydb.client.transport_failure',
+    clientRequestIdMismatch: 'yydb.client.request_id_mismatch',
+    clientUnexpectedResponse: 'yydb.client.unexpected_response',
+    clientDecodeFailure: 'yydb.client.decode_failure',
+};
+/**
+ * Codes where retrying the same operation can legitimately succeed: a socket or
+ * lease hiccup, or a compare-and-set that lost a benign race. Every other code
+ * needs the caller to change input, schema, or wiring first.
+ */
+const RETRYABLE_CODES = new Set([
+    YydbErrorCodes.clientTransportFailure,
+    YydbErrorCodes.casConflict,
+    YydbErrorCodes.leaseUnavailable,
+]);
+/** Whether `code` may be retried with the same arguments. */
+export function isRetryableYydbCode(code) {
+    return RETRYABLE_CODES.has(code);
+}
+/** YYDB failure with a stable machine-readable {@link YydbError.code}. */
+export class YydbError extends Error {
+    /** Stable code — engine code or `yydb.client.*`. */
+    code;
+    /** Operation that failed. */
+    operation;
+    /** Whether the same call may be retried. */
+    retryable;
+    constructor(code, message, options = {}) {
+        super(message, { cause: options.cause });
+        this.name = 'YydbError';
+        this.code = code;
+        this.operation = options.operation ?? 'unknown';
+        this.retryable = isRetryableYydbCode(code);
+    }
+}
+/** Narrowing helper so callers can branch without `instanceof` imports. */
+export function isYydbError(value) {
+    return value instanceof YydbError;
+}

package/dist/index.d.ts

@@ -1,5 +1,8 @@
 /** 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, encodeMicroRegister, encodeScalarCall, decodeScalarCallOk, decodeSchemaGetOk, decodeKvGetOk, } from './wire.js';
-export type { Frame, MicroRegisterPayload, MsgTypeCode, ProductMagic, SchemaVersion, WireUdfScalarKind, WireUdfScalarValue } from './wire.js';
+export { MAGIC, MAGIC_YYDB, MAGIC_YYDS, WIRE_VERSION, WIRE_VERSION_NEXT, HEADER_LEN, MsgType, encodeFrame, decodeFrame, encodeSchemaEnsure, encodeKvGet, encodeKvPut, encodeMicroRegister, encodeScalarCall, encodeErrorBody, decodeErrorBody, decodeScalarCallOk, decodeSchemaGetOk, decodeKvGetOk, } from './wire.js';
+export type { Frame, MicroRegisterPayload, MsgTypeCode, ProductMagic, SchemaVersion, WireErrorBody, WireUdfScalarKind, WireUdfScalarValue, } from './wire.js';
+export { YydbError, YydbErrorCodes, isRetryableYydbCode, isYydbError } from './errors.js';
+export type { YydbErrorCode, YydbErrorOptions } from './errors.js';
+export type { MicroHostHandler, Transport } from './transport.js';

package/dist/index.js

@@ -1,3 +1,4 @@
 /** 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, encodeMicroRegister, encodeScalarCall, decodeScalarCallOk, decodeSchemaGetOk, decodeKvGetOk, } from './wire.js';
+export { MAGIC, MAGIC_YYDB, MAGIC_YYDS, WIRE_VERSION, WIRE_VERSION_NEXT, HEADER_LEN, MsgType, encodeFrame, decodeFrame, encodeSchemaEnsure, encodeKvGet, encodeKvPut, encodeMicroRegister, encodeScalarCall, encodeErrorBody, decodeErrorBody, decodeScalarCallOk, decodeSchemaGetOk, decodeKvGetOk, } from './wire.js';
+export { YydbError, YydbErrorCodes, isRetryableYydbCode, isYydbError } from './errors.js';

package/dist/node.d.ts

@@ -1,7 +1,10 @@
 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';
+export { MsgType, encodeFrame, decodeFrame, encodeSchemaEnsure, encodeKvGet, encodeKvPut, decodeSchemaGetOk, decodeKvGetOk, encodeErrorBody, decodeErrorBody, } from './wire.js';
+export type { Frame, MsgTypeCode, SchemaVersion, WireErrorBody } from './wire.js';
+export { YydbError, YydbErrorCodes, isRetryableYydbCode, isYydbError } from './errors.js';
+export type { YydbErrorCode, YydbErrorOptions } from './errors.js';
+export type { MicroHostHandler, Transport } from './transport.js';
 /** Node entry: TCP by default; `ws://` uses WebSocket. */
 export declare function connect(options: ConnectOptions | string): Promise<Client>;

package/dist/node.js

@@ -2,8 +2,10 @@ import { Client } from './client.js';
 import { openTcpTransport } from './tcp.js';
 import { openWebSocketTransport } from './ws.js';
 import { normalizeWsUrl } from './transport.js';
+import { YydbError, YydbErrorCodes } from './errors.js';
 export { Client } from './client.js';
-export { MsgType, encodeFrame, decodeFrame, encodeSchemaEnsure, encodeKvGet, encodeKvPut, decodeSchemaGetOk, decodeKvGetOk } from './wire.js';
+export { MsgType, encodeFrame, decodeFrame, encodeSchemaEnsure, encodeKvGet, encodeKvPut, decodeSchemaGetOk, decodeKvGetOk, encodeErrorBody, decodeErrorBody, } from './wire.js';
+export { YydbError, YydbErrorCodes, isRetryableYydbCode, isYydbError } from './errors.js';
 function wantsWebSocket(endpoint) {
     const trimmed = endpoint.trim();
     return trimmed.startsWith('ws://') || trimmed.startsWith('wss://');
@@ -12,9 +14,17 @@ function wantsWebSocket(endpoint) {
 export async function connect(options) {
     const endpoint = typeof options === 'string' ? options : options.endpoint;
     if (!endpoint.trim()) {
-        throw new Error('empty serve endpoint');
+        throw new YydbError(YydbErrorCodes.clientInvalidEndpoint, 'empty serve endpoint', {
+            operation: 'connect',
+        });
+    }
+    let transport;
+    try {
+        transport = wantsWebSocket(endpoint) ? await openWebSocketTransport(endpoint) : await openTcpTransport(endpoint);
+    }
+    catch (cause) {
+        throw new YydbError(YydbErrorCodes.clientTransportFailure, `connect ${endpoint}: transport failed`, { operation: 'connect', cause });
     }
-    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/wire.d.ts

@@ -87,3 +87,14 @@ export interface SchemaVersion {
 }
 export declare function decodeSchemaGetOk(body: Uint8Array): SchemaVersion | null;
 export declare function decodeKvGetOk(body: Uint8Array): Uint8Array | null;
+/** Structured `Error` frame body: stable code plus display message. */
+export interface WireErrorBody {
+    /** Stable error code (`yydb.schema.invalid`, …). */
+    code: string;
+    /** Display message; hosts must not branch on this text. */
+    message: string;
+}
+/** Encode an `Error` frame body. */
+export declare function encodeErrorBody(error: WireErrorBody): Uint8Array;
+/** Decode an `Error` frame body. */
+export declare function decodeErrorBody(body: Uint8Array): WireErrorBody;

package/dist/wire.js

@@ -329,3 +329,19 @@ export function decodeKvGetOk(body) {
     const valLen = readU32At(body, offset);
     return readBytesAt(body, offset, valLen);
 }
+/** Encode an `Error` frame body. */
+export function encodeErrorBody(error) {
+    const out = [];
+    pushBytes(out, new TextEncoder().encode(error.code));
+    pushBytes(out, new TextEncoder().encode(error.message));
+    return Uint8Array.from(out);
+}
+/** Decode an `Error` frame body. */
+export function decodeErrorBody(body) {
+    const offset = { n: 0 };
+    const codeLen = readU32At(body, offset);
+    const code = new TextDecoder().decode(readBytesAt(body, offset, codeLen));
+    const messageLen = readU32At(body, offset);
+    const message = new TextDecoder().decode(readBytesAt(body, offset, messageLen));
+    return { code, message };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yydb/yydb-client",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "description": "TypeScript client for the YYDB WebSocket and TCP wire protocol",
   "license": "MPL-2.0",
   "type": "module",
@@ -22,7 +22,7 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "node --experimental-strip-types --test src/wire.test.ts"
+    "test": "pnpm run build && node --experimental-strip-types --test src/**/*.test.ts"
   },
   "repository": {
     "type": "git",