@yydb/yydb-client 0.1.1 → 0.1.2

package/README.md

@@ -1,7 +1,7 @@
 # `@yydb/yydb-client`
 
-TypeScript client for the YY wire protocol over WebSocket or TCP. Use when `yydb serve` already runs (from [
-`@yydb/yydb`](https://www.npmjs.com/package/@yydb/yydb) CLI or another host) and you only need the client surface —
+TypeScript client for the YY wire protocol over WebSocket or TCP. Use it when `yydb serve` already runs (from
+[`@yydb/yydb`](https://www.npmjs.com/package/@yydb/yydb) CLI or another host) and you 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)
@@ -52,8 +52,7 @@ instead.
 The client accepts hosts that announce `YYDB` or `YYDS` on the shared wire. Connect only to hosts you control — normally
 `127.0.0.1` or `localhost`.
 
-Protocol details: [
-`yydb-serve-protocol`](https://github.com/yy-database/yydb.rs/tree/dev/projects/packages/yydb-skills/skills/yydb-serve-protocol/SKILL.md)
+Protocol details: [`yydb-serve-protocol`](https://github.com/yy-database/yydb/tree/dev/projects/packages/yydb-skills/skills/yydb-serve-protocol/SKILL.md)
 in [`@yydb/yydb-skills`](https://www.npmjs.com/package/@yydb/yydb-skills).
 
-[YYDB overview](https://github.com/yy-database/yydb.rs) · [User guides](https://github.com/yy-database/yydb.rs/tree/dev/projects/packages/homepage/documentation/zh-hans)
+[YYDB overview](https://github.com/yy-database/yydb) · [User guides](https://github.com/yy-database/yydb/tree/dev/projects/packages/homepage/documentation/zh-hans)

package/dist/client.d.ts

@@ -3,7 +3,7 @@ import type { MicroHostHandler, Transport } from './transport.js';
 export type { Frame, MicroHostInvokePayload, MicroRegisterPayload, MsgTypeCode, SchemaVersion, WireErrorBody, WireUdfScalarKind, WireUdfScalarValue, } from './wire.js';
 export type { MicroHostHandler } from './transport.js';
 export { MsgType, encodeFrame, decodeFrame, encodeErrorBody, decodeErrorBody } from './wire.js';
-export { YydbError, YydbErrorCodes, isRetryableYydbCode, isYydbError } from './errors.js';
+export { YydbError, YydbErrorCodes, YydbClientErrorCodes, 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`). */

package/dist/client.js

@@ -2,7 +2,7 @@ import { decodeErrorBody, decodeKvGetOk, decodeScalarCallOk, decodeSchemaGetOk,
 import { openWebSocketTransport } from './ws.js';
 import { YydbError, YydbErrorCodes } from './errors.js';
 export { MsgType, encodeFrame, decodeFrame, encodeErrorBody, decodeErrorBody } from './wire.js';
-export { YydbError, YydbErrorCodes, isRetryableYydbCode, isYydbError } from './errors.js';
+export { YydbError, YydbErrorCodes, YydbClientErrorCodes, isYydbError } from './errors.js';
 /** Expected reply type and operation label per request type. */
 const REQUESTS = {
     [MsgType.Hello]: { operation: 'hello', ok: MsgType.HelloOk },
@@ -47,6 +47,7 @@ export class Client {
         catch (cause) {
             throw new YydbError(YydbErrorCodes.clientTransportFailure, `connect ${endpoint}: transport failed`, {
                 operation: 'connect',
+                retryable: true,
                 cause,
             });
         }
@@ -122,7 +123,7 @@ export class Client {
             });
         }
         catch (cause) {
-            throw new YydbError(YydbErrorCodes.clientTransportFailure, `${operation}: transport failed`, { operation, cause });
+            throw new YydbError(YydbErrorCodes.clientTransportFailure, `${operation}: transport failed`, { operation, retryable: true, cause });
         }
         if (response.requestId !== requestId) {
             throw new YydbError(YydbErrorCodes.clientRequestIdMismatch, `${operation}: wire response request_id mismatch (got ${response.requestId}, want ${requestId})`, { operation });

package/dist/errors.d.ts

@@ -1,57 +1,87 @@
 /**
- * Host-facing YYDB error surface.
+ * @yydb/yydb-client 公共错误面。
  *
- * 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.
+ * 与 Node 嵌入式库 `@yydb/yydb` 共享同一错误合同：稳定 `code` 字符串、
+ * `operation`、`retryable`、`params`。**分支依据是 `code` 不是 `message`。**
+ *
+ * 引擎侧错误 code 字符串来自 Rust 内核（经 wire 协议传入），这里不维护
+ * 引擎 code 常量表——Rust 新增变体时 host 直接拿到字符串即可。
+ *
+ * Client 本地错误（`yydb.client.*`）只在本包 mint，不流入 Rust。
+ *
+ * 本包与 `@yydb/yydb` **互不依赖**——错误合同在各自边界独立持有。
  */
-/** 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";
+/**
+ * Client 侧专属错误 code（永远不来自 Rust）。
+ */
+export declare const YydbClientErrorCodes: {
+    /** serve() endpoint 为空或无效。 */
+    readonly clientInvalidEndpoint: "yydb.client.invalid_endpoint";
+    /** connect() socket / transport 层失败。 */
+    readonly clientTransportFailure: "yydb.client.transport_failure";
+    /** Server 返回的 request id 与请求不匹配。 */
+    readonly clientRequestIdMismatch: "yydb.client.request_id_mismatch";
+    /** Server 返回了未请求的 msg_type。 */
+    readonly clientUnexpectedResponse: "yydb.client.unexpected_response";
+    /** 无法解析 wire Error frame body。 */
+    readonly clientDecodeFailure: "yydb.client.decode_failure";
+    /** YYDB session 已关闭。 */
     readonly sessionClosed: "yydb.session.closed";
+};
+/**
+ * 所有已知 client error code 的联合（引擎 code 作为字符串直接使用）。
+ */
+export declare const YydbErrorCodes: {
+    /** serve() endpoint 为空或无效。 */
     readonly clientInvalidEndpoint: "yydb.client.invalid_endpoint";
+    /** connect() socket / transport 层失败。 */
     readonly clientTransportFailure: "yydb.client.transport_failure";
+    /** Server 返回的 request id 与请求不匹配。 */
     readonly clientRequestIdMismatch: "yydb.client.request_id_mismatch";
+    /** Server 返回了未请求的 msg_type。 */
     readonly clientUnexpectedResponse: "yydb.client.unexpected_response";
+    /** 无法解析 wire Error frame body。 */
     readonly clientDecodeFailure: "yydb.client.decode_failure";
+    /** YYDB session 已关闭。 */
+    readonly sessionClosed: "yydb.session.closed";
 };
-/** 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}. */
+/** 稳定错误 code 字符串。引擎 code 来自 Rust，client code 来自本包常量。 */
+export type YydbErrorCode = string;
+/** {@link YydbError} 构造参数。 */
 export interface YydbErrorOptions {
-    /** Operation that failed (`schemaGet`, `kvPut`, `query`, …). */
+    /** 失败操作（`schemaGet`、`kvPut`、`query` …）。 */
     operation?: string;
-    /** Underlying failure when this error wraps one. */
+    /**
+     * 相同参数是否可重试。
+     *
+     * 缺省为 `false`（保守）。client 侧 mint 的可重试错误（如
+     * `yydb.client.transport_failure`）**必须**显式设置。引擎侧经 wire 传入
+     * 的错误携带 Rust 权威 retryable 值，解析时覆盖默认。
+     */
+    retryable?: boolean;
+    /** 结构化参数，供 catalog 模板化渲染使用。 */
+    params?: Readonly<Record<string, string>>;
+    /** 被本错误包装的底层失败。 */
     cause?: unknown;
 }
-/** YYDB failure with a stable machine-readable {@link YydbError.code}. */
+/** 带稳定机器可读 `code` 的 YYDB 错误。 */
 export declare class YydbError extends Error {
-    /** Stable code — engine code or `yydb.client.*`. */
+    /** 稳定 code —— 引擎侧来自 Rust，或 `yydb.client.*`。 */
     readonly code: string;
-    /** Operation that failed. */
+    /** 失败操作。 */
     readonly operation: string;
-    /** Whether the same call may be retried. */
+    /** 是否可重试。 */
     readonly retryable: boolean;
+    /** 结构化参数（存在时）。 */
+    readonly params?: Readonly<Record<string, string>>;
     constructor(code: YydbErrorCode, message: string, options?: YydbErrorOptions);
+    /**
+     * 从 wire error body（JSON）解析出 {@link YydbError}。格式：
+     * `{ code, operation?, retryable?, message, params? }`。
+     *
+     * 返回解析后的 {@link YydbError}；纯文本输入返回 `null`。
+     */
+    static fromDiagnosticJson(value: unknown): YydbError | null;
 }
-/** Narrowing helper so callers can branch without `instanceof` imports. */
+/** 让调用方无需 `instanceof` import 即可收窄。 */
 export declare function isYydbError(value: unknown): value is YydbError;

package/dist/errors.js

@@ -1,68 +1,109 @@
 /**
- * Host-facing YYDB error surface.
+ * @yydb/yydb-client 公共错误面。
  *
- * 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.
+ * 与 Node 嵌入式库 `@yydb/yydb` 共享同一错误合同：稳定 `code` 字符串、
+ * `operation`、`retryable`、`params`。**分支依据是 `code` 不是 `message`。**
+ *
+ * 引擎侧错误 code 字符串来自 Rust 内核（经 wire 协议传入），这里不维护
+ * 引擎 code 常量表——Rust 新增变体时 host 直接拿到字符串即可。
+ *
+ * Client 本地错误（`yydb.client.*`）只在本包 mint，不流入 Rust。
+ *
+ * 本包与 `@yydb/yydb` **互不依赖**——错误合同在各自边界独立持有。
  */
-/** 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',
+/**
+ * Client 侧专属错误 code（永远不来自 Rust）。
+ */
+export const YydbClientErrorCodes = {
+    /** serve() endpoint 为空或无效。 */
     clientInvalidEndpoint: 'yydb.client.invalid_endpoint',
+    /** connect() socket / transport 层失败。 */
     clientTransportFailure: 'yydb.client.transport_failure',
+    /** Server 返回的 request id 与请求不匹配。 */
     clientRequestIdMismatch: 'yydb.client.request_id_mismatch',
+    /** Server 返回了未请求的 msg_type。 */
     clientUnexpectedResponse: 'yydb.client.unexpected_response',
+    /** 无法解析 wire Error frame body。 */
     clientDecodeFailure: 'yydb.client.decode_failure',
+    /** YYDB session 已关闭。 */
+    sessionClosed: 'yydb.session.closed',
 };
 /**
- * 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.
+ * 所有已知 client error code 的联合（引擎 code 作为字符串直接使用）。
  */
-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 const YydbErrorCodes = {
+    ...YydbClientErrorCodes,
+};
+/** 带稳定机器可读 `code` 的 YYDB 错误。 */
 export class YydbError extends Error {
-    /** Stable code — engine code or `yydb.client.*`. */
+    /** 稳定 code —— 引擎侧来自 Rust，或 `yydb.client.*`。 */
     code;
-    /** Operation that failed. */
+    /** 失败操作。 */
     operation;
-    /** Whether the same call may be retried. */
+    /** 是否可重试。 */
     retryable;
+    /** 结构化参数（存在时）。 */
+    params;
     constructor(code, message, options = {}) {
         super(message, { cause: options.cause });
         this.name = 'YydbError';
         this.code = code;
         this.operation = options.operation ?? 'unknown';
-        this.retryable = isRetryableYydbCode(code);
+        this.retryable = options.retryable ?? false;
+        if (options.params !== undefined) {
+            this.params = options.params;
+        }
+    }
+    /**
+     * 从 wire error body（JSON）解析出 {@link YydbError}。格式：
+     * `{ code, operation?, retryable?, message, params? }`。
+     *
+     * 返回解析后的 {@link YydbError}；纯文本输入返回 `null`。
+     */
+    static fromDiagnosticJson(value) {
+        let obj;
+        if (typeof value === 'string') {
+            try {
+                const parsed = JSON.parse(value);
+                if (!parsed || typeof parsed !== 'object')
+                    return null;
+                obj = parsed;
+            }
+            catch {
+                return null;
+            }
+        }
+        else if (value && typeof value === 'object') {
+            obj = value;
+        }
+        else {
+            return null;
+        }
+        // WASM envelopes nest the diagnostic under `{ ok, error: {...} }`.
+        let diag = obj;
+        if (typeof obj['ok'] === 'boolean' && !obj['ok'] && obj['error'] && typeof obj['error'] === 'object') {
+            diag = obj['error'];
+        }
+        const code = typeof diag['code'] === 'string' ? diag['code'] : null;
+        const message = typeof diag['message'] === 'string' ? diag['message'] : '';
+        if (!code)
+            return null;
+        const operation = typeof diag['operation'] === 'string' ? diag['operation'] : undefined;
+        const retryable = typeof diag['retryable'] === 'boolean' ? diag['retryable'] : undefined;
+        const params = diag['params'] && typeof diag['params'] === 'object'
+            ? diag['params']
+            : undefined;
+        const opts = {};
+        if (operation !== undefined)
+            opts.operation = operation;
+        if (retryable !== undefined)
+            opts.retryable = retryable;
+        if (params !== undefined)
+            opts.params = params;
+        return new YydbError(code, message, opts);
     }
 }
-/** Narrowing helper so callers can branch without `instanceof` imports. */
+/** 让调用方无需 `instanceof` import 即可收窄。 */
 export function isYydbError(value) {
     return value instanceof YydbError;
 }

package/dist/index.d.ts

@@ -3,6 +3,6 @@ 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, 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 { YydbError, YydbErrorCodes, YydbClientErrorCodes, isYydbError } from './errors.js';
 export type { YydbErrorCode, YydbErrorOptions } from './errors.js';
 export type { MicroHostHandler, Transport } from './transport.js';

package/dist/index.js

@@ -1,4 +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, encodeErrorBody, decodeErrorBody, decodeScalarCallOk, decodeSchemaGetOk, decodeKvGetOk, } from './wire.js';
-export { YydbError, YydbErrorCodes, isRetryableYydbCode, isYydbError } from './errors.js';
+export { YydbError, YydbErrorCodes, YydbClientErrorCodes, isYydbError } from './errors.js';

package/dist/node.d.ts

@@ -3,7 +3,7 @@ export { Client } from './client.js';
 export type { ConnectOptions } from './client.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 { YydbError, YydbErrorCodes, YydbClientErrorCodes, 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. */

package/dist/node.js

@@ -5,7 +5,7 @@ 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, encodeErrorBody, decodeErrorBody, } from './wire.js';
-export { YydbError, YydbErrorCodes, isRetryableYydbCode, isYydbError } from './errors.js';
+export { YydbError, YydbErrorCodes, YydbClientErrorCodes, isYydbError } from './errors.js';
 function wantsWebSocket(endpoint) {
     const trimmed = endpoint.trim();
     return trimmed.startsWith('ws://') || trimmed.startsWith('wss://');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yydb/yydb-client",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "TypeScript client for the YYDB WebSocket and TCP wire protocol",
   "license": "MPL-2.0",
   "type": "module",