@zvndev/powdb-client 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.17.0 - 2026-07-19
+
+- **Typed wire error codes.** Servers >= 0.17.0 append a stable one-byte error
+  class to error frames; the client maps it onto `PowDBErrorCode` (`timeout`,
+  `size_exceeded`, `auth_failed`, ...) instead of collapsing every server
+  error to `query_failed`, and exposes the raw class as
+  `PowDBError.wireErrorClass`. Fully backward compatible: classless frames
+  from older servers behave exactly as before, and unknown future classes
+  fall back to `query_failed`. See the repo's `docs/errors.md` for the code
+  table.
+
 ## 0.16.0 - 2026-07-18
 
 - Version-alignment release in lockstep with workspace v0.16.0 (NUL-safe

package/dist/cjs/errors.d.ts

@@ -26,6 +26,39 @@ export type PowDBErrorCode =
  | "timeout"
 /** Type coercion on a row failed (queryTyped). */
  | "type_coercion_failed";
+/**
+ * Stable wire error classes appended by 0.17+ servers to Error frames
+ * (see docs/errors.md in the PowDB repo). These numeric values never change;
+ * new classes are only appended. Treat unknown values as `internal`.
+ */
+export declare const WIRE_ERROR_CLASS: {
+    /** Unclassified or internal server error. */
+    readonly internal: 0;
+    /** The query text failed to lex or parse. */
+    readonly parse: 1;
+    /** Planning or execution failed (unknown table/column, type mismatch, ...). */
+    readonly execution: 2;
+    /** A time budget elapsed (query timeout, gate wait, idle timeout). */
+    readonly timeout: 3;
+    /** A memory or size limit was exceeded. */
+    readonly limit_exceeded: 4;
+    /** The server is read-only and the statement requires a writer. */
+    readonly readonly_refused: 5;
+    /** Authentication or database selection failed at CONNECT time. */
+    readonly auth_failed: 6;
+    /** Too many failed authentication attempts. */
+    readonly rate_limited: 7;
+    /** A constraint (e.g. unique index) rejected the write. */
+    readonly constraint_violation: 8;
+    /** Execution was cancelled cooperatively (client disconnect). */
+    readonly cancelled: 9;
+};
+/**
+ * Map a server wire error class to the client's `PowDBErrorCode` taxonomy.
+ * `undefined` (legacy server, no class byte) and unknown future bytes fall
+ * back to `"query_failed"`, preserving pre-class behavior.
+ */
+export declare function errorCodeForWireClass(errorClass: number | undefined): PowDBErrorCode;
 /**
  * All errors thrown by `@zvndev/powdb-client` are instances of this class.
  * Use `err.code` to branch; `err.cause` optionally carries the underlying
@@ -33,8 +66,16 @@ export type PowDBErrorCode =
  */
 export declare class PowDBError extends Error {
     readonly code: PowDBErrorCode;
+    /**
+     * The raw server wire error class (see `WIRE_ERROR_CLASS`), when the error
+     * came from a server Error frame that carried one. Finer-grained than
+     * `code` (e.g. it distinguishes readonly refusals and constraint
+     * violations); `undefined` for client-side errors and legacy servers.
+     */
+    readonly wireErrorClass?: number;
     constructor(message: string, code: PowDBErrorCode, options?: {
         cause?: unknown;
+        wireErrorClass?: number;
     });
 }
 /**

package/dist/cjs/errors.js

@@ -8,9 +8,55 @@
  * legitimate reason to handle them differently.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PowDBScriptError = exports.PowDBError = void 0;
+exports.PowDBScriptError = exports.PowDBError = exports.WIRE_ERROR_CLASS = void 0;
+exports.errorCodeForWireClass = errorCodeForWireClass;
 exports.isPowDBError = isPowDBError;
 exports.isPowDBScriptError = isPowDBScriptError;
+/**
+ * Stable wire error classes appended by 0.17+ servers to Error frames
+ * (see docs/errors.md in the PowDB repo). These numeric values never change;
+ * new classes are only appended. Treat unknown values as `internal`.
+ */
+exports.WIRE_ERROR_CLASS = {
+    /** Unclassified or internal server error. */
+    internal: 0,
+    /** The query text failed to lex or parse. */
+    parse: 1,
+    /** Planning or execution failed (unknown table/column, type mismatch, ...). */
+    execution: 2,
+    /** A time budget elapsed (query timeout, gate wait, idle timeout). */
+    timeout: 3,
+    /** A memory or size limit was exceeded. */
+    limit_exceeded: 4,
+    /** The server is read-only and the statement requires a writer. */
+    readonly_refused: 5,
+    /** Authentication or database selection failed at CONNECT time. */
+    auth_failed: 6,
+    /** Too many failed authentication attempts. */
+    rate_limited: 7,
+    /** A constraint (e.g. unique index) rejected the write. */
+    constraint_violation: 8,
+    /** Execution was cancelled cooperatively (client disconnect). */
+    cancelled: 9,
+};
+/**
+ * Map a server wire error class to the client's `PowDBErrorCode` taxonomy.
+ * `undefined` (legacy server, no class byte) and unknown future bytes fall
+ * back to `"query_failed"`, preserving pre-class behavior.
+ */
+function errorCodeForWireClass(errorClass) {
+    switch (errorClass) {
+        case exports.WIRE_ERROR_CLASS.timeout:
+            return "timeout";
+        case exports.WIRE_ERROR_CLASS.limit_exceeded:
+            return "size_exceeded";
+        case exports.WIRE_ERROR_CLASS.auth_failed:
+        case exports.WIRE_ERROR_CLASS.rate_limited:
+            return "auth_failed";
+        default:
+            return "query_failed";
+    }
+}
 /**
  * All errors thrown by `@zvndev/powdb-client` are instances of this class.
  * Use `err.code` to branch; `err.cause` optionally carries the underlying
@@ -18,11 +64,23 @@ exports.isPowDBScriptError = isPowDBScriptError;
  */
 class PowDBError extends Error {
     code;
+    /**
+     * The raw server wire error class (see `WIRE_ERROR_CLASS`), when the error
+     * came from a server Error frame that carried one. Finer-grained than
+     * `code` (e.g. it distinguishes readonly refusals and constraint
+     * violations); `undefined` for client-side errors and legacy servers.
+     */
+    wireErrorClass;
     constructor(message, code, options) {
         // ErrorOptions.cause is supported in Node 16.9+; we require Node 18+.
-        super(message, options);
+        // Only forward `cause` when the caller supplied one, so a bare options
+        // object never materializes an own `cause: undefined` property.
+        super(message, options && "cause" in options
+            ? { cause: options.cause }
+            : undefined);
         this.name = "PowDBError";
         this.code = code;
+        this.wireErrorClass = options?.wireErrorClass;
         // Preserve the prototype chain across `target: es2020` and friends.
         Object.setPrototypeOf(this, PowDBError.prototype);
     }

package/dist/cjs/index.d.ts

@@ -19,7 +19,7 @@ import { EventEmitter } from "node:events";
 import { type NativeJson, type SyncRepairAction, type WireRetainedUnit, type WireSyncStatus, type WireValue } from "./protocol.js";
 import { type TypedRow, type TypedSchema } from "./typed.js";
 /** Client library version. Compared to the server's reported version. */
-export declare const CLIENT_VERSION = "0.16.0";
+export declare const CLIENT_VERSION = "0.17.0";
 /**
  * The maximum catalog format version this client can read. State this as the
  * `catalogVersion` in sync pull requests: the server accepts any replica whose
@@ -471,7 +471,7 @@ export { escapeLiteral, escapeIdent, ident, powql, PowqlIdent, } from "./escape.
 export { Pool } from "./pool.js";
 export type { PoolOptions } from "./pool.js";
 export { splitStatements } from "./script.js";
-export { PowDBError, isPowDBError, PowDBScriptError, isPowDBScriptError, } from "./errors.js";
+export { errorCodeForWireClass, PowDBError, isPowDBError, PowDBScriptError, isPowDBScriptError, WIRE_ERROR_CLASS, } from "./errors.js";
 export type { PowDBErrorCode } from "./errors.js";
 export { coerceValue, coerceRow, coerceRows, } from "./typed.js";
 export type { ColumnType, TypedSchema, TypedRow, Coerced, JsonValue, } from "./typed.js";

package/dist/cjs/index.js

@@ -49,7 +49,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.coerceRows = exports.coerceRow = exports.coerceValue = exports.isPowDBScriptError = exports.PowDBScriptError = exports.isPowDBError = exports.PowDBError = exports.splitStatements = exports.Pool = exports.PowqlIdent = exports.powql = exports.ident = exports.escapeIdent = exports.escapeLiteral = exports.MAX_SYNC_PULL_BYTES = exports.MAX_SYNC_PULL_UNITS = exports.MAX_SYNC_UNITS = exports.MAX_PARAMS = exports.MAX_COLUMNS = exports.MAX_ROWS = exports.MAX_PAYLOAD_SIZE = exports.tryDecode = exports.encode = exports.Client = exports.SUPPORTED_CATALOG_VERSION = exports.CLIENT_VERSION = void 0;
+exports.coerceRows = exports.coerceRow = exports.coerceValue = exports.WIRE_ERROR_CLASS = exports.isPowDBScriptError = exports.PowDBScriptError = exports.isPowDBError = exports.PowDBError = exports.errorCodeForWireClass = exports.splitStatements = exports.Pool = exports.PowqlIdent = exports.powql = exports.ident = exports.escapeIdent = exports.escapeLiteral = exports.MAX_SYNC_PULL_BYTES = exports.MAX_SYNC_PULL_UNITS = exports.MAX_SYNC_UNITS = exports.MAX_PARAMS = exports.MAX_COLUMNS = exports.MAX_ROWS = exports.MAX_PAYLOAD_SIZE = exports.tryDecode = exports.encode = exports.Client = exports.SUPPORTED_CATALOG_VERSION = exports.CLIENT_VERSION = void 0;
 exports.assertServerCatalogVersionSupported = assertServerCatalogVersionSupported;
 const net = __importStar(require("node:net"));
 const tls = __importStar(require("node:tls"));
@@ -59,7 +59,7 @@ const errors_js_1 = require("./errors.js");
 const script_js_1 = require("./script.js");
 const typed_js_1 = require("./typed.js");
 /** Client library version. Compared to the server's reported version. */
-exports.CLIENT_VERSION = "0.16.0";
+exports.CLIENT_VERSION = "0.17.0";
 /**
  * The maximum catalog format version this client can read. State this as the
  * `catalogVersion` in sync pull requests: the server accepts any replica whose
@@ -152,7 +152,7 @@ function nativeQueryResult(reply) {
         case "ResultMessage":
             return { kind: "message", message: reply.message };
         case "Error":
-            throw new errors_js_1.PowDBError(`query failed: ${reply.message}`, "query_failed");
+            throw new errors_js_1.PowDBError(`query failed: ${reply.message}`, (0, errors_js_1.errorCodeForWireClass)(reply.errorClass), { wireErrorClass: reply.errorClass });
         default:
             throw new errors_js_1.PowDBError(`unexpected reply to native query: ${reply.type}`, "protocol_error");
     }
@@ -168,7 +168,7 @@ function rawNativeQueryResult(reply) {
         case "ResultMessage":
             return { kind: "message", message: reply.message };
         case "Error":
-            throw new errors_js_1.PowDBError(`query failed: ${reply.message}`, "query_failed");
+            throw new errors_js_1.PowDBError(`query failed: ${reply.message}`, (0, errors_js_1.errorCodeForWireClass)(reply.errorClass), { wireErrorClass: reply.errorClass });
         default:
             throw new errors_js_1.PowDBError(`unexpected reply to native query: ${reply.type}`, "protocol_error");
     }
@@ -386,7 +386,7 @@ class Client extends node_events_1.EventEmitter {
                     result = { kind: "message", message: reply.message };
                     break;
                 case "Error":
-                    throw new errors_js_1.PowDBError(`query failed: ${reply.message}`, "query_failed");
+                    throw new errors_js_1.PowDBError(`query failed: ${reply.message}`, (0, errors_js_1.errorCodeForWireClass)(reply.errorClass), { wireErrorClass: reply.errorClass });
                 default:
                     throw new errors_js_1.PowDBError(`unexpected reply: ${reply.type}`, "protocol_error");
             }
@@ -515,7 +515,7 @@ class Client extends node_events_1.EventEmitter {
                     result = { kind: "message", message: reply.message };
                     break;
                 case "Error":
-                    throw new errors_js_1.PowDBError(`query failed: ${reply.message}`, "query_failed");
+                    throw new errors_js_1.PowDBError(`query failed: ${reply.message}`, (0, errors_js_1.errorCodeForWireClass)(reply.errorClass), { wireErrorClass: reply.errorClass });
                 default:
                     throw new errors_js_1.PowDBError(`unexpected reply: ${reply.type}`, "protocol_error");
             }
@@ -572,7 +572,7 @@ class Client extends node_events_1.EventEmitter {
         try {
             const reply = await this.send({ type: "SyncStatus", replicaId }, opts);
             if (reply.type === "Error") {
-                throw new errors_js_1.PowDBError(`sync status failed: ${reply.message}`, "query_failed");
+                throw new errors_js_1.PowDBError(`sync status failed: ${reply.message}`, (0, errors_js_1.errorCodeForWireClass)(reply.errorClass), { wireErrorClass: reply.errorClass });
             }
             if (reply.type !== "SyncStatusResult") {
                 throw new errors_js_1.PowDBError(`unexpected reply: ${reply.type}`, "protocol_error");
@@ -622,7 +622,7 @@ class Client extends node_events_1.EventEmitter {
                 segmentFormatVersion: toU16(request.segmentFormatVersion, "segmentFormatVersion"),
             }, opts);
             if (reply.type === "Error") {
-                throw new errors_js_1.PowDBError(`sync pull failed: ${reply.message}`, "query_failed");
+                throw new errors_js_1.PowDBError(`sync pull failed: ${reply.message}`, (0, errors_js_1.errorCodeForWireClass)(reply.errorClass), { wireErrorClass: reply.errorClass });
             }
             if (reply.type !== "SyncPullResult") {
                 throw new errors_js_1.PowDBError(`unexpected reply: ${reply.type}`, "protocol_error");
@@ -665,7 +665,7 @@ class Client extends node_events_1.EventEmitter {
                 remoteLsn: toU64(request.remoteLsn, "remoteLsn"),
             }, opts);
             if (reply.type === "Error") {
-                throw new errors_js_1.PowDBError(`sync ack failed: ${reply.message}`, "query_failed");
+                throw new errors_js_1.PowDBError(`sync ack failed: ${reply.message}`, (0, errors_js_1.errorCodeForWireClass)(reply.errorClass), { wireErrorClass: reply.errorClass });
             }
             if (reply.type !== "SyncAckResult") {
                 throw new errors_js_1.PowDBError(`unexpected reply: ${reply.type}`, "protocol_error");
@@ -1226,10 +1226,12 @@ Object.defineProperty(exports, "Pool", { enumerable: true, get: function () { re
 var script_js_2 = require("./script.js");
 Object.defineProperty(exports, "splitStatements", { enumerable: true, get: function () { return script_js_2.splitStatements; } });
 var errors_js_2 = require("./errors.js");
+Object.defineProperty(exports, "errorCodeForWireClass", { enumerable: true, get: function () { return errors_js_2.errorCodeForWireClass; } });
 Object.defineProperty(exports, "PowDBError", { enumerable: true, get: function () { return errors_js_2.PowDBError; } });
 Object.defineProperty(exports, "isPowDBError", { enumerable: true, get: function () { return errors_js_2.isPowDBError; } });
 Object.defineProperty(exports, "PowDBScriptError", { enumerable: true, get: function () { return errors_js_2.PowDBScriptError; } });
 Object.defineProperty(exports, "isPowDBScriptError", { enumerable: true, get: function () { return errors_js_2.isPowDBScriptError; } });
+Object.defineProperty(exports, "WIRE_ERROR_CLASS", { enumerable: true, get: function () { return errors_js_2.WIRE_ERROR_CLASS; } });
 var typed_js_2 = require("./typed.js");
 Object.defineProperty(exports, "coerceValue", { enumerable: true, get: function () { return typed_js_2.coerceValue; } });
 Object.defineProperty(exports, "coerceRow", { enumerable: true, get: function () { return typed_js_2.coerceRow; } });

package/dist/cjs/protocol.d.ts

@@ -221,6 +221,7 @@ export type Message = {
 } | {
     type: "Error";
     message: string;
+    errorClass?: number;
 } | {
     type: "Disconnect";
 } | {

package/dist/cjs/protocol.js

@@ -544,8 +544,16 @@ function decodePayload(msgType, payload) {
         }
         case exports.MSG_RESULT_MSG:
             return { type: "ResultMessage", message: decodeString(payload, cursor) };
-        case exports.MSG_ERROR:
-            return { type: "Error", message: decodeString(payload, cursor) };
+        case exports.MSG_ERROR: {
+            const message = decodeString(payload, cursor);
+            // 0.17+ servers append one stable error-class byte after the
+            // length-prefixed message (see docs/errors.md). Old servers send only
+            // the string, so absence means "no class".
+            if (cursor.pos < payload.length) {
+                return { type: "Error", message, errorClass: payload[cursor.pos] };
+            }
+            return { type: "Error", message };
+        }
         case exports.MSG_DISCONNECT:
             return { type: "Disconnect" };
         case exports.MSG_PING:

package/dist/errors.d.ts

@@ -26,6 +26,39 @@ export type PowDBErrorCode =
  | "timeout"
 /** Type coercion on a row failed (queryTyped). */
  | "type_coercion_failed";
+/**
+ * Stable wire error classes appended by 0.17+ servers to Error frames
+ * (see docs/errors.md in the PowDB repo). These numeric values never change;
+ * new classes are only appended. Treat unknown values as `internal`.
+ */
+export declare const WIRE_ERROR_CLASS: {
+    /** Unclassified or internal server error. */
+    readonly internal: 0;
+    /** The query text failed to lex or parse. */
+    readonly parse: 1;
+    /** Planning or execution failed (unknown table/column, type mismatch, ...). */
+    readonly execution: 2;
+    /** A time budget elapsed (query timeout, gate wait, idle timeout). */
+    readonly timeout: 3;
+    /** A memory or size limit was exceeded. */
+    readonly limit_exceeded: 4;
+    /** The server is read-only and the statement requires a writer. */
+    readonly readonly_refused: 5;
+    /** Authentication or database selection failed at CONNECT time. */
+    readonly auth_failed: 6;
+    /** Too many failed authentication attempts. */
+    readonly rate_limited: 7;
+    /** A constraint (e.g. unique index) rejected the write. */
+    readonly constraint_violation: 8;
+    /** Execution was cancelled cooperatively (client disconnect). */
+    readonly cancelled: 9;
+};
+/**
+ * Map a server wire error class to the client's `PowDBErrorCode` taxonomy.
+ * `undefined` (legacy server, no class byte) and unknown future bytes fall
+ * back to `"query_failed"`, preserving pre-class behavior.
+ */
+export declare function errorCodeForWireClass(errorClass: number | undefined): PowDBErrorCode;
 /**
  * All errors thrown by `@zvndev/powdb-client` are instances of this class.
  * Use `err.code` to branch; `err.cause` optionally carries the underlying
@@ -33,8 +66,16 @@ export type PowDBErrorCode =
  */
 export declare class PowDBError extends Error {
     readonly code: PowDBErrorCode;
+    /**
+     * The raw server wire error class (see `WIRE_ERROR_CLASS`), when the error
+     * came from a server Error frame that carried one. Finer-grained than
+     * `code` (e.g. it distinguishes readonly refusals and constraint
+     * violations); `undefined` for client-side errors and legacy servers.
+     */
+    readonly wireErrorClass?: number;
     constructor(message: string, code: PowDBErrorCode, options?: {
         cause?: unknown;
+        wireErrorClass?: number;
     });
 }
 /**

package/dist/errors.js

@@ -6,6 +6,51 @@
  * is intentionally small — new codes are added only when a caller has a
  * legitimate reason to handle them differently.
  */
+/**
+ * Stable wire error classes appended by 0.17+ servers to Error frames
+ * (see docs/errors.md in the PowDB repo). These numeric values never change;
+ * new classes are only appended. Treat unknown values as `internal`.
+ */
+export const WIRE_ERROR_CLASS = {
+    /** Unclassified or internal server error. */
+    internal: 0,
+    /** The query text failed to lex or parse. */
+    parse: 1,
+    /** Planning or execution failed (unknown table/column, type mismatch, ...). */
+    execution: 2,
+    /** A time budget elapsed (query timeout, gate wait, idle timeout). */
+    timeout: 3,
+    /** A memory or size limit was exceeded. */
+    limit_exceeded: 4,
+    /** The server is read-only and the statement requires a writer. */
+    readonly_refused: 5,
+    /** Authentication or database selection failed at CONNECT time. */
+    auth_failed: 6,
+    /** Too many failed authentication attempts. */
+    rate_limited: 7,
+    /** A constraint (e.g. unique index) rejected the write. */
+    constraint_violation: 8,
+    /** Execution was cancelled cooperatively (client disconnect). */
+    cancelled: 9,
+};
+/**
+ * Map a server wire error class to the client's `PowDBErrorCode` taxonomy.
+ * `undefined` (legacy server, no class byte) and unknown future bytes fall
+ * back to `"query_failed"`, preserving pre-class behavior.
+ */
+export function errorCodeForWireClass(errorClass) {
+    switch (errorClass) {
+        case WIRE_ERROR_CLASS.timeout:
+            return "timeout";
+        case WIRE_ERROR_CLASS.limit_exceeded:
+            return "size_exceeded";
+        case WIRE_ERROR_CLASS.auth_failed:
+        case WIRE_ERROR_CLASS.rate_limited:
+            return "auth_failed";
+        default:
+            return "query_failed";
+    }
+}
 /**
  * All errors thrown by `@zvndev/powdb-client` are instances of this class.
  * Use `err.code` to branch; `err.cause` optionally carries the underlying
@@ -13,11 +58,23 @@
  */
 export class PowDBError extends Error {
     code;
+    /**
+     * The raw server wire error class (see `WIRE_ERROR_CLASS`), when the error
+     * came from a server Error frame that carried one. Finer-grained than
+     * `code` (e.g. it distinguishes readonly refusals and constraint
+     * violations); `undefined` for client-side errors and legacy servers.
+     */
+    wireErrorClass;
     constructor(message, code, options) {
         // ErrorOptions.cause is supported in Node 16.9+; we require Node 18+.
-        super(message, options);
+        // Only forward `cause` when the caller supplied one, so a bare options
+        // object never materializes an own `cause: undefined` property.
+        super(message, options && "cause" in options
+            ? { cause: options.cause }
+            : undefined);
         this.name = "PowDBError";
         this.code = code;
+        this.wireErrorClass = options?.wireErrorClass;
         // Preserve the prototype chain across `target: es2020` and friends.
         Object.setPrototypeOf(this, PowDBError.prototype);
     }

package/dist/index.d.ts

@@ -19,7 +19,7 @@ import { EventEmitter } from "node:events";
 import { type NativeJson, type SyncRepairAction, type WireRetainedUnit, type WireSyncStatus, type WireValue } from "./protocol.js";
 import { type TypedRow, type TypedSchema } from "./typed.js";
 /** Client library version. Compared to the server's reported version. */
-export declare const CLIENT_VERSION = "0.16.0";
+export declare const CLIENT_VERSION = "0.17.0";
 /**
  * The maximum catalog format version this client can read. State this as the
  * `catalogVersion` in sync pull requests: the server accepts any replica whose
@@ -471,7 +471,7 @@ export { escapeLiteral, escapeIdent, ident, powql, PowqlIdent, } from "./escape.
 export { Pool } from "./pool.js";
 export type { PoolOptions } from "./pool.js";
 export { splitStatements } from "./script.js";
-export { PowDBError, isPowDBError, PowDBScriptError, isPowDBScriptError, } from "./errors.js";
+export { errorCodeForWireClass, PowDBError, isPowDBError, PowDBScriptError, isPowDBScriptError, WIRE_ERROR_CLASS, } from "./errors.js";
 export type { PowDBErrorCode } from "./errors.js";
 export { coerceValue, coerceRow, coerceRows, } from "./typed.js";
 export type { ColumnType, TypedSchema, TypedRow, Coerced, JsonValue, } from "./typed.js";

package/dist/index.js

@@ -18,11 +18,11 @@ import * as net from "node:net";
 import * as tls from "node:tls";
 import { EventEmitter } from "node:events";
 import { encode, tryDecode, MAX_SYNC_PULL_BYTES, MAX_SYNC_PULL_UNITS, } from "./protocol.js";
-import { PowDBError, PowDBScriptError, isPowDBError } from "./errors.js";
+import { errorCodeForWireClass, isPowDBError, PowDBError, PowDBScriptError, } from "./errors.js";
 import { splitStatements } from "./script.js";
 import { coerceRows, } from "./typed.js";
 /** Client library version. Compared to the server's reported version. */
-export const CLIENT_VERSION = "0.16.0";
+export const CLIENT_VERSION = "0.17.0";
 /**
  * The maximum catalog format version this client can read. State this as the
  * `catalogVersion` in sync pull requests: the server accepts any replica whose
@@ -115,7 +115,7 @@ function nativeQueryResult(reply) {
         case "ResultMessage":
             return { kind: "message", message: reply.message };
         case "Error":
-            throw new PowDBError(`query failed: ${reply.message}`, "query_failed");
+            throw new PowDBError(`query failed: ${reply.message}`, errorCodeForWireClass(reply.errorClass), { wireErrorClass: reply.errorClass });
         default:
             throw new PowDBError(`unexpected reply to native query: ${reply.type}`, "protocol_error");
     }
@@ -131,7 +131,7 @@ function rawNativeQueryResult(reply) {
         case "ResultMessage":
             return { kind: "message", message: reply.message };
         case "Error":
-            throw new PowDBError(`query failed: ${reply.message}`, "query_failed");
+            throw new PowDBError(`query failed: ${reply.message}`, errorCodeForWireClass(reply.errorClass), { wireErrorClass: reply.errorClass });
         default:
             throw new PowDBError(`unexpected reply to native query: ${reply.type}`, "protocol_error");
     }
@@ -349,7 +349,7 @@ export class Client extends EventEmitter {
                     result = { kind: "message", message: reply.message };
                     break;
                 case "Error":
-                    throw new PowDBError(`query failed: ${reply.message}`, "query_failed");
+                    throw new PowDBError(`query failed: ${reply.message}`, errorCodeForWireClass(reply.errorClass), { wireErrorClass: reply.errorClass });
                 default:
                     throw new PowDBError(`unexpected reply: ${reply.type}`, "protocol_error");
             }
@@ -478,7 +478,7 @@ export class Client extends EventEmitter {
                     result = { kind: "message", message: reply.message };
                     break;
                 case "Error":
-                    throw new PowDBError(`query failed: ${reply.message}`, "query_failed");
+                    throw new PowDBError(`query failed: ${reply.message}`, errorCodeForWireClass(reply.errorClass), { wireErrorClass: reply.errorClass });
                 default:
                     throw new PowDBError(`unexpected reply: ${reply.type}`, "protocol_error");
             }
@@ -535,7 +535,7 @@ export class Client extends EventEmitter {
         try {
             const reply = await this.send({ type: "SyncStatus", replicaId }, opts);
             if (reply.type === "Error") {
-                throw new PowDBError(`sync status failed: ${reply.message}`, "query_failed");
+                throw new PowDBError(`sync status failed: ${reply.message}`, errorCodeForWireClass(reply.errorClass), { wireErrorClass: reply.errorClass });
             }
             if (reply.type !== "SyncStatusResult") {
                 throw new PowDBError(`unexpected reply: ${reply.type}`, "protocol_error");
@@ -585,7 +585,7 @@ export class Client extends EventEmitter {
                 segmentFormatVersion: toU16(request.segmentFormatVersion, "segmentFormatVersion"),
             }, opts);
             if (reply.type === "Error") {
-                throw new PowDBError(`sync pull failed: ${reply.message}`, "query_failed");
+                throw new PowDBError(`sync pull failed: ${reply.message}`, errorCodeForWireClass(reply.errorClass), { wireErrorClass: reply.errorClass });
             }
             if (reply.type !== "SyncPullResult") {
                 throw new PowDBError(`unexpected reply: ${reply.type}`, "protocol_error");
@@ -628,7 +628,7 @@ export class Client extends EventEmitter {
                 remoteLsn: toU64(request.remoteLsn, "remoteLsn"),
             }, opts);
             if (reply.type === "Error") {
-                throw new PowDBError(`sync ack failed: ${reply.message}`, "query_failed");
+                throw new PowDBError(`sync ack failed: ${reply.message}`, errorCodeForWireClass(reply.errorClass), { wireErrorClass: reply.errorClass });
             }
             if (reply.type !== "SyncAckResult") {
                 throw new PowDBError(`unexpected reply: ${reply.type}`, "protocol_error");
@@ -1171,5 +1171,5 @@ export { MAX_PAYLOAD_SIZE, MAX_ROWS, MAX_COLUMNS, MAX_PARAMS, MAX_SYNC_UNITS, MA
 export { escapeLiteral, escapeIdent, ident, powql, PowqlIdent, } from "./escape.js";
 export { Pool } from "./pool.js";
 export { splitStatements } from "./script.js";
-export { PowDBError, isPowDBError, PowDBScriptError, isPowDBScriptError, } from "./errors.js";
+export { errorCodeForWireClass, PowDBError, isPowDBError, PowDBScriptError, isPowDBScriptError, WIRE_ERROR_CLASS, } from "./errors.js";
 export { coerceValue, coerceRow, coerceRows, } from "./typed.js";

package/dist/protocol.d.ts

@@ -221,6 +221,7 @@ export type Message = {
 } | {
     type: "Error";
     message: string;
+    errorClass?: number;
 } | {
     type: "Disconnect";
 } | {

package/dist/protocol.js

@@ -539,8 +539,16 @@ function decodePayload(msgType, payload) {
         }
         case MSG_RESULT_MSG:
             return { type: "ResultMessage", message: decodeString(payload, cursor) };
-        case MSG_ERROR:
-            return { type: "Error", message: decodeString(payload, cursor) };
+        case MSG_ERROR: {
+            const message = decodeString(payload, cursor);
+            // 0.17+ servers append one stable error-class byte after the
+            // length-prefixed message (see docs/errors.md). Old servers send only
+            // the string, so absence means "no class".
+            if (cursor.pos < payload.length) {
+                return { type: "Error", message, errorClass: payload[cursor.pos] };
+            }
+            return { type: "Error", message };
+        }
         case MSG_DISCONNECT:
             return { type: "Disconnect" };
         case MSG_PING:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zvndev/powdb-client",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "TypeScript client for PowDB (PowQL wire protocol)",
   "type": "module",
   "packageManager": "pnpm@10.29.3",