@zvndev/powdb-client 0.6.1 → 0.7.1

package/dist/index.d.ts

@@ -18,7 +18,7 @@ import * as tls from "node:tls";
 import { EventEmitter } from "node:events";
 import { type TypedRow, type TypedSchema } from "./typed.js";
 /** Client library version. Compared to the server's reported version. */
-export declare const CLIENT_VERSION = "0.6.1";
+export declare const CLIENT_VERSION = "0.7.1";
 export type QueryResult = {
     kind: "rows";
     columns: string[];
@@ -43,8 +43,17 @@ export type QueryResult = {
  */
 export type QueryParam = string | number | bigint | boolean | null;
 export interface ClientOptions {
-    host: string;
-    port: number;
+    /** TCP host. Required unless `path` (a Unix domain socket) is given. */
+    host?: string;
+    /** TCP port. Required unless `path` (a Unix domain socket) is given. */
+    port?: number;
+    /**
+     * Path to a Unix domain socket. When set, the client connects over the
+     * socket instead of TCP (same-host, ~2× lower round-trip latency) and
+     * `host`/`port`/`tls` are ignored. Requires a server started with
+     * `--socket <path>`.
+     */
+    path?: string;
     dbName?: string;
     password?: string | null;
     /**

package/dist/index.js

@@ -21,7 +21,7 @@ import { encode, tryDecode, } from "./protocol.js";
 import { PowDBError } from "./errors.js";
 import { coerceRows, } from "./typed.js";
 /** Client library version. Compared to the server's reported version. */
-export const CLIENT_VERSION = "0.6.1";
+export const CLIENT_VERSION = "0.7.1";
 function socketChunkToBuffer(chunk) {
     return typeof chunk === "string" ? Buffer.from(chunk) : chunk;
 }
@@ -85,8 +85,11 @@ export class Client extends EventEmitter {
     }
     /** Open a connection, send Connect, wait for ConnectOk. */
     static async connect(opts) {
-        const { host, port, dbName = "default", password = null, user, connectTimeoutMs = 5000, tls: tlsOpt = false, } = opts;
-        const socket = await openSocket(host, port, connectTimeoutMs, tlsOpt);
+        const { host, port, path, dbName = "default", password = null, user, connectTimeoutMs = 5000, tls: tlsOpt = false, } = opts;
+        if (path === undefined && (host === undefined || port === undefined)) {
+            throw new PowDBError("connect requires either { path } (Unix socket) or { host, port } (TCP)", "connect_failed");
+        }
+        const socket = await openSocket({ host, port, path }, connectTimeoutMs, tlsOpt);
         // We need to read the initial ConnectOk before wiring up the normal
         // pending-queue machinery, so we do a one-shot handshake here.
         const handshake = new Promise((resolve, reject) => {
@@ -147,7 +150,7 @@ export class Client extends EventEmitter {
         const serverMajor = majorOf(reply.version);
         const clientMajor = majorOf(CLIENT_VERSION);
         if (serverMajor !== clientMajor) {
-            const key = `${host}:${port}`;
+            const key = path ?? `${host}:${port}`;
             if (!versionWarnings.has(key)) {
                 versionWarnings.add(key);
                 console.warn(`[powdb] server version ${reply.version} major (${serverMajor}) ` +
@@ -555,7 +558,7 @@ export class Client extends EventEmitter {
         }
     }
 }
-function openSocket(host, port, timeoutMs, tlsOpt) {
+function openSocket(target, timeoutMs, tlsOpt) {
     return new Promise((resolve, reject) => {
         let socket;
         const timer = setTimeout(() => {
@@ -565,8 +568,8 @@ function openSocket(host, port, timeoutMs, tlsOpt) {
         const onConnect = () => {
             clearTimeout(timer);
             socket.setNoDelay(true);
-            // Enable TCP keepalive on the underlying OS socket so dead peers are
-            // detected even when the app is otherwise idle.
+            // Enable keepalive on the underlying OS socket so dead peers are detected
+            // even when the app is otherwise idle. (No-op for Unix sockets.)
             socket.setKeepAlive(true, 30_000);
             resolve(socket);
         };
@@ -576,12 +579,19 @@ function openSocket(host, port, timeoutMs, tlsOpt) {
             // branch on `.code === "connect_failed"` rather than string-matching.
             reject(new PowDBError(`connect failed: ${err.message}`, "connect_failed", { cause: err }));
         };
-        if (tlsOpt) {
+        if (target.path !== undefined) {
+            // Unix domain socket: no TLS (local, same-host), no host/port.
+            socket = new net.Socket();
+            socket.once("connect", onConnect);
+            socket.once("error", onError);
+            socket.connect(target.path);
+        }
+        else if (tlsOpt) {
             // TLS path: `tls.connect` wraps an underlying net.Socket. `secureConnect`
             // fires once the TLS handshake is complete — that is the right hook for
             // "ready to send application data".
             const tlsOptions = tlsOpt === true ? {} : tlsOpt;
-            const tlsSock = tls.connect(port, host, tlsOptions);
+            const tlsSock = tls.connect(target.port, target.host, tlsOptions);
             socket = tlsSock;
             tlsSock.once("secureConnect", onConnect);
             tlsSock.once("error", onError);
@@ -590,7 +600,7 @@ function openSocket(host, port, timeoutMs, tlsOpt) {
             socket = new net.Socket();
             socket.once("connect", onConnect);
             socket.once("error", onError);
-            socket.connect(port, host);
+            socket.connect(target.port, target.host);
         }
     });
 }

package/package.json

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