@saptools/cf-hana 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.1.2 - 2026-06-23
+
+- Harden connection pooling so queued callers continue after transient reconnect failures.
+- Preserve query results when HANA statement cleanup fails and close partially opened clients on schema setup errors.
+- Strengthen read-only and destructive-statement checks around comments, quoted identifiers, and unknown statements.
+- Improve `explain()` statement isolation, cleanup, and read-only behavior.
+- Validate CLI numeric options strictly and align E2E diagnostics with project defaults.
+
+## 0.1.1 - 2026-05-22
+
+- Patch release to publish via npm trusted publishing after the manual `0.1.0` bootstrap.
+
 ## 0.1.0 - 2026-05-22
 
 - Initial release: run SQL directly against SAP HANA Cloud databases bound to a Cloud Foundry app, addressed by a `region/org/space/app` selector (or a bare app name).

package/README.md

@@ -44,7 +44,7 @@ driver is bundled as a dependency — there is no native build step.
 import { connect, query } from "@saptools/cf-hana";
 
 // Open a reusable, pooled client for one CF app's HANA database.
-const db = await connect("eu10/acme/dev/orders-srv");
+const db = await connect("eu10/acme/dev/orders-api");
 
 const open = await db.query("SELECT ID, STATUS FROM ORDERS WHERE STATUS = ?", ["OPEN"]);
 console.log(open.rows);
@@ -58,16 +58,16 @@ await db.transaction(async (tx) => {
 await db.close();
 
 // One-shot: connect, run one query, close.
-const rows = await query("orders-srv", "SELECT COUNT(*) AS N FROM ORDERS");
+const rows = await query("orders-api", "SELECT COUNT(*) AS N FROM ORDERS");
 ```
 
 ## The selector
 
 Every entry point takes a selector as its first argument:
 
-- **Explicit** — `region/org/space/app` (e.g. `eu10/acme/dev/orders-srv`). Works
+- **Explicit** — `region/org/space/app` (e.g. `eu10/acme/dev/orders-api`). Works
   without any cached topology.
-- **Bare app name** — `orders-srv`. Resolved against the topology cached by
+- **Bare app name** — `orders-api`. Resolved against the topology cached by
   `cf-sync sync`; throws if the name is ambiguous across spaces.
 
 ## CLI
@@ -87,11 +87,11 @@ Common options: `--format <table|json|csv>`, `--refresh`, `--role <runtime|hdi>`
 accepts `--param <value>` (repeatable) to bind `?` placeholders.
 
 ```bash
-cf-hana query eu10/acme/dev/orders-srv "SELECT ID, STATUS FROM ORDERS WHERE STATUS = ?" \
+cf-hana query eu10/acme/dev/orders-api "SELECT ID, STATUS FROM ORDERS WHERE STATUS = ?" \
   --param OPEN --format json
-cf-hana tables orders-srv
-cf-hana columns orders-srv ORDERS_APP.ORDERS
-cf-hana ping eu10/acme/dev/orders-srv
+cf-hana tables orders-api
+cf-hana columns orders-api ORDERS_APP.ORDERS
+cf-hana ping eu10/acme/dev/orders-api
 ```
 
 ## Programmatic API

package/dist/cli.js

@@ -247,7 +247,7 @@ async function listColumns(connection, schema, table) {
 
 // src/config.ts
 var CLI_NAME = "cf-hana";
-var CLI_VERSION = "0.1.0";
+var CLI_VERSION = "0.1.2";
 var ENV_PREFIX = "CF_HANA";
 var DEFAULT_QUERY_TIMEOUT_MS = 3e4;
 var DEFAULT_CONNECT_TIMEOUT_MS = 3e4;
@@ -498,7 +498,7 @@ var HdbConnection = class {
       const raw = await this.executeStatement(statement, params);
       return toExecResult(statement, raw);
     } finally {
-      statement.drop();
+      dropStatementQuietly(statement);
     }
   }
   setAutoCommit(enabled) {
@@ -565,6 +565,12 @@ var HdbConnection = class {
     });
   }
 };
+function dropStatementQuietly(statement) {
+  try {
+    statement.drop();
+  } catch {
+  }
+}
 function openClient(client, timeoutMs) {
   return new Promise((resolve, reject) => {
     let settled = false;
@@ -600,6 +606,20 @@ function openClient(client, timeoutMs) {
     });
   });
 }
+async function closeClientQuietly(client) {
+  try {
+    await new Promise((resolve) => {
+      client.disconnect(() => {
+        resolve();
+      });
+    });
+  } catch {
+  }
+  try {
+    client.close();
+  } catch {
+  }
+}
 function setCurrentSchema(client, schema) {
   return new Promise((resolve, reject) => {
     client.exec(`SET SCHEMA ${quoteIdentifier(schema)}`, (error) => {
@@ -621,7 +641,12 @@ async function connectHdb(params) {
     useTLS: true
   });
   await openClient(client, params.connectTimeoutMs);
-  await setCurrentSchema(client, params.schema);
+  try {
+    await setCurrentSchema(client, params.schema);
+  } catch (error) {
+    await closeClientQuietly(client);
+    throw error;
+  }
   return new HdbConnection(client);
 }
 function createHdbDriver() {
@@ -647,11 +672,100 @@ function createDriver(name) {
 // src/safety.ts
 var DESTRUCTIVE_DDL_KEYWORDS = /* @__PURE__ */ new Set(["DROP", "TRUNCATE", "ALTER"]);
 var UNSCOPED_WRITE_KEYWORDS = /* @__PURE__ */ new Set(["UPDATE", "DELETE"]);
-function stripStringLiterals(sql) {
-  return sql.replace(/'(?:[^']|'')*'/g, "''");
+function skipQuotedText(sql, start) {
+  const quote = sql[start];
+  let index = start + 1;
+  while (index < sql.length) {
+    if (sql[index] === quote) {
+      if (sql[index + 1] === quote) {
+        index += 2;
+        continue;
+      }
+      index += 1;
+      break;
+    }
+    index += 1;
+  }
+  return index;
+}
+function skipLineComment(sql, start) {
+  let index = start + 2;
+  while (index < sql.length && sql[index] !== "\n") {
+    index += 1;
+  }
+  return index;
+}
+function skipBlockComment(sql, start) {
+  let index = start + 2;
+  while (index < sql.length && !(sql[index] === "*" && sql[index + 1] === "/")) {
+    index += 1;
+  }
+  return Math.min(index + 2, sql.length);
+}
+function maskIgnoredSqlText(sql) {
+  let masked = "";
+  let index = 0;
+  while (index < sql.length) {
+    const char = sql[index];
+    if (char === "'" || char === '"') {
+      const end = skipQuotedText(sql, index);
+      masked += " ".repeat(end - index);
+      index = end;
+      continue;
+    }
+    if (char === "-" && sql[index + 1] === "-") {
+      const end = skipLineComment(sql, index);
+      masked += " ".repeat(end - index);
+      index = end;
+      continue;
+    }
+    if (char === "/" && sql[index + 1] === "*") {
+      const end = skipBlockComment(sql, index);
+      masked += " ".repeat(end - index);
+      index = end;
+      continue;
+    }
+    masked += char ?? "";
+    index += 1;
+  }
+  return masked;
 }
 function hasWhereClause(sql) {
-  return /\bwhere\b/i.test(stripStringLiterals(sql));
+  return /\bwhere\b/i.test(maskIgnoredSqlText(sql));
+}
+function trailingLineCommentIndex(sql) {
+  let index = 0;
+  while (index < sql.length) {
+    const char = sql[index];
+    if (char === "'" || char === '"') {
+      index = skipQuotedText(sql, index);
+      continue;
+    }
+    if (char === "/" && sql[index + 1] === "*") {
+      index = skipBlockComment(sql, index);
+      continue;
+    }
+    if (char === "-" && sql[index + 1] === "-") {
+      const lineEnd = sql.indexOf("\n", index + 2);
+      if (lineEnd === -1 || sql.slice(lineEnd + 1).trim().length === 0) {
+        return index;
+      }
+      index = lineEnd + 1;
+      continue;
+    }
+    index += 1;
+  }
+  return void 0;
+}
+function appendLimit(sql, limit) {
+  const trimmed = sql.replace(/[\s;]+$/, "");
+  const commentIndex = trailingLineCommentIndex(trimmed);
+  if (commentIndex === void 0) {
+    return `${trimmed} LIMIT ${String(limit)}`;
+  }
+  const beforeComment = trimmed.slice(0, commentIndex).replace(/[\s;]+$/, "");
+  const comment = trimmed.slice(commentIndex);
+  return `${beforeComment} LIMIT ${String(limit)} ${comment}`;
 }
 function inspectStatement(sql) {
   const kind = classifyStatement(sql);
@@ -669,12 +783,12 @@ function inspectStatement(sql) {
 }
 function evaluateGuard(sql, config) {
   const inspection = inspectStatement(sql);
-  if (config.readOnly && (inspection.kind === "dml" || inspection.kind === "ddl")) {
+  if (config.readOnly && inspection.kind !== "select") {
     return {
       allowed: false,
       destructive: inspection.destructive,
       violation: "read-only",
-      reason: `read-only mode blocks ${inspection.kind.toUpperCase()} statements`
+      reason: inspection.kind === "unknown" ? "read-only mode only permits SELECT/WITH statements" : `read-only mode blocks ${inspection.kind.toUpperCase()} statements`
     };
   }
   if (inspection.destructive && !config.allowDestructive) {
@@ -696,12 +810,11 @@ function applyAutoLimit(sql, limit) {
   if (limit === false || classifyStatement(sql) !== "select") {
     return { sql, applied: false };
   }
-  const stripped = stripStringLiterals(sql);
+  const stripped = maskIgnoredSqlText(sql);
   if (/\blimit\b/i.test(stripped) || /\btop\s+\d/i.test(stripped)) {
     return { sql, applied: false };
   }
-  const trimmed = sql.replace(/[\s;]+$/, "");
-  return { sql: `${trimmed} LIMIT ${String(limit)}`, applied: true };
+  return { sql: appendLimit(sql, limit), applied: true };
 }
 
 // src/connection.ts
@@ -750,6 +863,12 @@ var Connection = class _Connection {
   async execute(sql, params, options) {
     return await this.run(sql, params ?? [], options ?? {});
   }
+  assertAllowed(sql, options) {
+    this.evaluateSafety(sql, options ?? {});
+  }
+  async executeInternal(sql, params, options) {
+    return await this.run(sql, params ?? [], options ?? {}, { bypassSafety: true });
+  }
   async setAutoCommit(enabled) {
     await this.driverConnection.setAutoCommit(enabled);
   }
@@ -765,21 +884,10 @@ var Connection = class _Connection {
   get isClosed() {
     return this.driverConnection.isClosed();
   }
-  async run(sql, params, options) {
+  async run(sql, params, options, runOptions = {}) {
     assertParamArity(sql, params);
-    const decision = evaluateGuard(sql, {
-      readOnly: this.config.readOnly,
-      allowDestructive: options.allowDestructive ?? this.config.allowDestructive
-    });
-    if (!decision.allowed) {
-      if (decision.violation === "read-only") {
-        throw new ReadOnlyViolationError(
-          decision.reason ?? "read-only mode blocks this statement"
-        );
-      }
-      throw new DestructiveStatementError(
-        decision.reason ?? "destructive statement blocked"
-      );
+    if (runOptions.bypassSafety !== true) {
+      this.evaluateSafety(sql, options);
     }
     const kind = classifyStatement(sql);
     const autoLimit = options.autoLimit ?? this.config.autoLimit;
@@ -809,6 +917,23 @@ var Connection = class _Connection {
     } catch {
     }
   }
+  evaluateSafety(sql, options) {
+    const decision = evaluateGuard(sql, {
+      readOnly: this.config.readOnly,
+      allowDestructive: options.allowDestructive ?? this.config.allowDestructive
+    });
+    if (decision.allowed) {
+      return;
+    }
+    if (decision.violation === "read-only") {
+      throw new ReadOnlyViolationError(
+        decision.reason ?? "read-only mode blocks this statement"
+      );
+    }
+    throw new DestructiveStatementError(
+      decision.reason ?? "destructive statement blocked"
+    );
+  }
 };
 
 // src/pool.ts
@@ -949,6 +1074,7 @@ var ConnectionPool = class {
         (error) => {
           this.created -= 1;
           waiter.reject(error);
+          this.servePendingWaiters();
         }
       );
     }
@@ -995,6 +1121,11 @@ var Transaction = class {
 };
 
 // src/client.ts
+var explainStatementCounter = 0;
+function nextExplainStatementName() {
+  explainStatementCounter = (explainStatementCounter + 1) % Number.MAX_SAFE_INTEGER;
+  return `cf_hana_${String(process.pid)}_${String(Date.now())}_${String(explainStatementCounter)}`;
+}
 var HanaClient = class _HanaClient {
   constructor(pool, info) {
     this.pool = pool;
@@ -1113,21 +1244,35 @@ var HanaClient = class _HanaClient {
   /** Return the HANA execution plan for a statement. */
   async explain(sql, params) {
     return await this.pool.withConnection(async (connection) => {
-      const statementName = `cf_hana_${String(Date.now())}`;
-      await connection.execute(
+      connection.assertAllowed(sql);
+      const statementName = nextExplainStatementName();
+      await connection.executeInternal(
         `EXPLAIN PLAN SET STATEMENT_NAME = '${statementName}' FOR ${sql}`,
         params
       );
-      try {
-        return await connection.query(
-          "SELECT OPERATOR_NAME, TABLE_NAME, TABLE_TYPE, EXECUTION_ENGINE FROM EXPLAIN_PLAN_TABLE WHERE STATEMENT_NAME = ? ORDER BY OPERATOR_ID",
+      const cleanup = async () => {
+        await connection.executeInternal(
+          "DELETE FROM EXPLAIN_PLAN_TABLE WHERE STATEMENT_NAME = ?",
           [statementName]
         );
-      } finally {
-        await connection.execute(
-          "DELETE FROM EXPLAIN_PLAN_TABLE WHERE STATEMENT_NAME = ?",
+      };
+      let queryCompleted = false;
+      try {
+        const result = await connection.query(
+          "SELECT OPERATOR_NAME, TABLE_NAME, TABLE_TYPE, EXECUTION_ENGINE FROM EXPLAIN_PLAN_TABLE WHERE STATEMENT_NAME = ? ORDER BY OPERATOR_ID",
           [statementName]
         );
+        queryCompleted = true;
+        await cleanup();
+        return result;
+      } catch (error) {
+        if (!queryCompleted) {
+          try {
+            await cleanup();
+          } catch {
+          }
+        }
+        throw error;
       }
     });
   }
@@ -1238,12 +1383,26 @@ function fail(message) {
   process.exit(1);
 }
 function parseIntOption(value) {
-  const parsed = Number.parseInt(value, 10);
-  if (!Number.isInteger(parsed)) {
+  const trimmed = value.trim();
+  if (!/^-?\d+$/.test(trimmed)) {
     throw new CfHanaError("CONFIG", `Expected an integer but received "${value}"`);
   }
+  const parsed = Number(trimmed);
+  if (!Number.isSafeInteger(parsed)) {
+    throw new CfHanaError("CONFIG", `Expected a safe integer but received "${value}"`);
+  }
   return parsed;
 }
+function assertPositiveOption(name, value) {
+  if (value !== void 0 && value <= 0) {
+    throw new CfHanaError("CONFIG", `${name} must be a positive integer`);
+  }
+}
+function assertNonNegativeOption(name, value) {
+  if (value !== void 0 && value < 0) {
+    throw new CfHanaError("CONFIG", `${name} must be a non-negative integer`);
+  }
+}
 function collectParam(value, previous) {
   return [...previous, value];
 }
@@ -1267,6 +1426,9 @@ function parseQualifiedName(value) {
   return { schema: value.slice(0, dot), table: value.slice(dot + 1) };
 }
 function toConnectOptions(opts) {
+  assertPositiveOption("--limit", opts.limit);
+  assertPositiveOption("--timeout", opts.timeout);
+  assertNonNegativeOption("--binding-index", opts.bindingIndex);
   return {
     refresh: opts.refresh,
     role: parseRole(opts.role),