@bzync/nextsql 0.0.1 → 0.0.2

package/nextsql.d.ts

@@ -1,10 +1,9 @@
-// Public TypeScript surface for the official NextSQL Node.js driver.
+// Shared TypeScript surface for the official Node.js and Bun NextSQL drivers.
+// Keys and passwords are never accepted in a URL.
 //
-// Self-contained COPY of drivers/js/types.d.ts. It must NOT import from ../js:
-// the package tarball contains only the files in package.json "files", so a
-// parent-directory import resolves to nothing for an installed consumer. The
-// parity test in the driver test suite fails if this drifts from the canonical
-// shared file.
+// drivers/node/nextsql.d.ts and drivers/bun/nextsql.d.ts are published copies
+// of this file (npm packs only in-package files); their parity tests fail if
+// they drift from this canonical source.
 
 export interface TLSOptions {
   /** PEM or DER trust material. */
@@ -52,6 +51,8 @@ export interface Config {
   readConsistency?: ReadConsistencyMode;
   /** Bounded-read staleness window in milliseconds. 0 selects the server default. */
   maxStalenessMs?: number;
+  /** Maximum number of prepared statements to cache per connection LRU. Default: 0 (disabled on raw connect; 50 in pool). */
+  statementCacheSize?: number;
 }
 
 export interface FieldKey {
@@ -330,6 +331,35 @@ export declare const Type: {
 
 export declare function connect(cfg: Config): Promise<Conn>;
 export declare function connectCluster(cfg: Config): Promise<Cluster>;
+
+export interface PoolOptions {
+  /** Minimum number of idle connections to maintain. Default: 1 */
+  min?: number;
+  /** Maximum number of connections in the pool. Default: 10 */
+  max?: number;
+  /** Maximum milliseconds to wait for a connection before timing out. Default: 30000 (30s) */
+  timeoutMs?: number;
+  /** Maximum idle milliseconds before an unused connection is retired. Default: 300000 (5m) */
+  idleTimeoutMs?: number;
+  /** Maximum number of prepared statements to cache per connection LRU. Default: 50. 0 disables. */
+  statementCacheSize?: number;
+}
+
+export declare class Pool {
+  constructor(config: Config, options?: PoolOptions);
+  readonly size: number;
+  readonly idleCount: number;
+  readonly inUseCount: number;
+  readonly isClosed: boolean;
+  acquire(): Promise<Conn>;
+  release(conn: Conn): Promise<void>;
+  withConnection<T>(fn: (conn: Conn) => Promise<T>): Promise<T>;
+  exec(sql: string, params?: unknown[]): Promise<Result>;
+  query(sql: string, params?: unknown[]): Promise<Result>;
+  close(): Promise<void>;
+}
+
+export declare function createPool(config: Config, options?: PoolOptions): Pool;
 export declare function generateFieldKey(id: string): FieldKey;
 export declare function inspectField(ciphertext: string): { keyID: string; type: FieldTypeDescriptor };
 export declare function encryptField(provider: FieldKeyProvider, database: string, table: string, column: string, type: FieldTypeDescriptor, value: unknown): Promise<string | null>;

package/nextsql.js

@@ -1759,6 +1759,8 @@ class Conn {
     this.secret = 0n;
     this.busy = false;
     this.publicErrorCodes = false;
+    this.statementCacheSize = cfg?.statementCacheSize ?? 0;
+    this._stmtCache = this.statementCacheSize > 0 ? new Map() : null;
   }
 
   async handshake() {
@@ -1904,6 +1906,30 @@ class Conn {
     if (this.busy) {
       throw new NextSQLError('conflict', 'connection is busy');
     }
+    if (this._stmtCache && params && params.length > 0) {
+      let stmt = this._stmtCache.get(sql);
+      if (stmt) {
+        this._stmtCache.delete(sql);
+        this._stmtCache.set(sql, stmt);
+      } else {
+        stmt = await this.prepare(sql);
+        if (this._stmtCache.size >= this.statementCacheSize) {
+          const oldestKey = this._stmtCache.keys().next().value;
+          const oldestStmt = this._stmtCache.get(oldestKey);
+          this._stmtCache.delete(oldestKey);
+          oldestStmt.close().catch(() => {});
+        }
+        this._stmtCache.set(sql, stmt);
+      }
+      try {
+        return await this._execute(stmt.id, params);
+      } catch (err) {
+        this._stmtCache.delete(sql);
+        stmt.close().catch(() => {});
+        throw err;
+      }
+    }
+
     this.busy = true;
     try {
       await this.wire.writeFrame(Type.Query, encodeQuery(sql, params || []));
@@ -1996,6 +2022,11 @@ class Conn {
   }
 
   async close() {
+    if (this._stmtCache) {
+      const stmts = [...this._stmtCache.values()];
+      this._stmtCache.clear();
+      await Promise.allSettled(stmts.map(s => s.close()));
+    }
     if (!this.wire) {
       return;
     }
@@ -2197,8 +2228,188 @@ async function connectCluster(cfg) {
   return new Cluster(cfg, conns);
 }
 
+class Pool {
+  constructor(cfg, options = {}) {
+    validateConfig(cfg);
+    const min = options.min ?? 1;
+    const max = options.max ?? 10;
+    const timeoutMs = options.timeoutMs ?? 30000;
+    const idleTimeoutMs = options.idleTimeoutMs ?? 300000;
+    const statementCacheSize = options.statementCacheSize ?? 50;
+
+    if (min < 0) throw new NextSQLError('invalid_argument', 'min must be >= 0');
+    if (max < 1) throw new NextSQLError('invalid_argument', 'max must be >= 1');
+    if (max < min) throw new NextSQLError('invalid_argument', 'max must be >= min');
+    if (statementCacheSize < 0) throw new NextSQLError('invalid_argument', 'statementCacheSize must be >= 0');
+
+    this._cfg = { ...cfg, statementCacheSize };
+    this._min = min;
+    this._max = max;
+    this._timeoutMs = timeoutMs;
+    this._idleTimeoutMs = idleTimeoutMs;
+    this._statementCacheSize = statementCacheSize;
+
+    this._idle = []; // [{ conn, lastUsed }]
+    this._inUse = new Set();
+    this._waiters = []; // [{ resolve, reject, timer }]
+    this._closed = false;
+  }
+
+  get size() {
+    return this._idle.length + this._inUse.size;
+  }
+
+  get idleCount() {
+    return this._idle.length;
+  }
+
+  get inUseCount() {
+    return this._inUse.size;
+  }
+
+  get isClosed() {
+    return this._closed;
+  }
+
+  async acquire() {
+    if (this._closed) {
+      throw new NextSQLError('unavailable', 'connection pool is closed');
+    }
+
+    const now = Date.now();
+    while (this._idle.length > 0) {
+      const item = this._idle.pop();
+      if (this._idleTimeoutMs > 0 && (now - item.lastUsed) > this._idleTimeoutMs) {
+        item.conn.close().catch(() => {});
+        continue;
+      }
+      if (item.conn.wire && item.conn.wire.closed) {
+        continue;
+      }
+      this._inUse.add(item.conn);
+      return item.conn;
+    }
+
+    if (this.size < this._max) {
+      const conn = await connect(this._cfg);
+      this._inUse.add(conn);
+      return conn;
+    }
+
+    return new Promise((resolve, reject) => {
+      let timer = null;
+      if (this._timeoutMs > 0) {
+        timer = setTimeout(() => {
+          const idx = this._waiters.findIndex(w => w.resolve === resolve);
+          if (idx >= 0) {
+            this._waiters.splice(idx, 1);
+            reject(new NextSQLError('resource_exhausted', 'connection pool exhausted, wait timeout exceeded'));
+          }
+        }, this._timeoutMs);
+      }
+      this._waiters.push({ resolve, reject, timer });
+    });
+  }
+
+  async release(conn) {
+    if (!this._inUse.has(conn)) {
+      return;
+    }
+    this._inUse.delete(conn);
+
+    if (this._closed || (conn.wire && conn.wire.closed)) {
+      conn.close().catch(() => {});
+      this._drainWaiters();
+      return;
+    }
+
+    // Clean connection state: roll back uncommitted transaction
+    try {
+      await conn.exec('ROLLBACK');
+    } catch {
+      conn.close().catch(() => {});
+      this._drainWaiters();
+      return;
+    }
+
+    while (this._waiters.length > 0) {
+      const waiter = this._waiters.shift();
+      if (waiter.timer) clearTimeout(waiter.timer);
+      this._inUse.add(conn);
+      waiter.resolve(conn);
+      return;
+    }
+
+    this._idle.push({ conn, lastUsed: Date.now() });
+  }
+
+  _drainWaiters() {
+    if (this._closed) {
+      while (this._waiters.length > 0) {
+        const w = this._waiters.shift();
+        if (w.timer) clearTimeout(w.timer);
+        w.reject(new NextSQLError('unavailable', 'connection pool is closed'));
+      }
+      return;
+    }
+    if (this.size < this._max && this._waiters.length > 0) {
+      const waiter = this._waiters.shift();
+      if (waiter.timer) clearTimeout(waiter.timer);
+      connect(this._cfg).then(conn => {
+        this._inUse.add(conn);
+        waiter.resolve(conn);
+      }).catch(err => {
+        waiter.reject(err);
+      });
+    }
+  }
+
+  async withConnection(fn) {
+    const conn = await this.acquire();
+    try {
+      return await fn(conn);
+    } finally {
+      await this.release(conn);
+    }
+  }
+
+  async exec(sql, params) {
+    return this.withConnection(conn => conn.exec(sql, params));
+  }
+
+  async query(sql, params) {
+    return this.withConnection(async (conn) => {
+      const rows = await conn.query(sql, params);
+      return rows.collect();
+    });
+  }
+
+  async close() {
+    if (this._closed) return;
+    this._closed = true;
+
+    while (this._waiters.length > 0) {
+      const w = this._waiters.shift();
+      if (w.timer) clearTimeout(w.timer);
+      w.reject(new NextSQLError('unavailable', 'connection pool is closed'));
+    }
+
+    const conns = [...this._idle.map(item => item.conn), ...this._inUse];
+    this._idle = [];
+    this._inUse.clear();
+
+    await Promise.allSettled(conns.map(c => c.close()));
+  }
+}
+
+function createPool(cfg, options) {
+  return new Pool(cfg, options);
+}
+
 module.exports = {
   connect,
+  createPool,
+  Pool,
   FlagCancel,
   FlagPublicErrorCodes,
   connectCluster,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bzync/nextsql",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Official NextSQL Node.js driver. Keys never go in URLs.",
   "license": "MIT",
   "main": "nextsql.js",