@saptools/cf-hana 0.1.3 → 0.1.5

package/dist/index.d.ts

@@ -96,6 +96,32 @@ interface HanaClientInfo {
     readonly credentialSource: CredentialSource;
 }
 
+type WriteBackupOperation = "update" | "delete";
+interface WriteBackupPlan {
+    readonly operation: WriteBackupOperation;
+    readonly statementSql: string;
+    readonly selectSql: string;
+    readonly selectParams: readonly SqlParam[];
+}
+interface SqlBackupWriteInput {
+    readonly operation: WriteBackupOperation;
+    readonly statementSql: string;
+    readonly result: QueryResult;
+}
+interface SqlBackupWriteOptions {
+    readonly now?: Date;
+    readonly saptoolsRoot?: string;
+}
+interface SqlBackupRecord {
+    readonly directory: string;
+    readonly statementPath: string;
+    readonly backupPath: string;
+    readonly rowCount: number;
+}
+declare function cfHanaBackupRoot(saptoolsRoot?: string): string;
+declare function buildWriteBackupPlan(sql: string, params?: readonly SqlParam[]): WriteBackupPlan | undefined;
+declare function writeSqlBackup(input: SqlBackupWriteInput, options?: SqlBackupWriteOptions): Promise<SqlBackupRecord>;
+
 interface DriverExecResult {
     readonly rows: readonly Record<string, SqlParam>[];
     readonly columns: readonly QueryResultColumn[];
@@ -219,6 +245,8 @@ declare class HanaClient {
     query<TRow = QueryRow>(sql: string, params?: readonly SqlParam[], options?: QueryOptions): Promise<QueryResult<TRow>>;
     /** Run a DML/DDL statement and return its affected-row count. */
     execute(sql: string, params?: readonly SqlParam[], options?: QueryOptions): Promise<QueryResult>;
+    /** Back up rows matched by an UPDATE or DELETE before the caller runs it. */
+    backupWriteStatement(sql: string, params?: readonly SqlParam[], options?: QueryOptions): Promise<SqlBackupRecord | undefined>;
     /** Run a typed `SELECT` built from a spec. */
     selectFrom<TRow = QueryRow>(spec: SelectSpec): Promise<QueryResult<TRow>>;
     /** Count rows in a table, optionally filtered. */
@@ -316,4 +344,4 @@ declare class DestructiveStatementError extends CfHanaError {
 /** Narrow an unknown thrown value to a human-readable message. */
 declare function errorMessage(error: unknown): string;
 
-export { type BuiltStatement, CfHanaError, type CfHanaErrorCode, type ColumnInfo, type ConnectOptions, type CredentialSource, CredentialsNotFoundError, type DbUserRole, DestructiveStatementError, type DriverConnectParams, type DriverConnection, type DriverExecResult, HanaClient, type HanaClientInfo, type HanaDriver, type OutputFormat, type PoolOptions, QueryError, type QueryOptions, type QueryResult, type QueryResultColumn, type QueryRow, ReadOnlyViolationError, type SelectSpec, type SqlParam, type StatementKind, type TableInfo, Transaction, buildCount, buildDelete, buildInsert, buildSelect, buildUpdate, connect, createDriver, errorMessage, formatCsv, formatJson, formatResult, formatTable, query, withConnection };
+export { type BuiltStatement, CfHanaError, type CfHanaErrorCode, type ColumnInfo, type ConnectOptions, type CredentialSource, CredentialsNotFoundError, type DbUserRole, DestructiveStatementError, type DriverConnectParams, type DriverConnection, type DriverExecResult, HanaClient, type HanaClientInfo, type HanaDriver, type OutputFormat, type PoolOptions, QueryError, type QueryOptions, type QueryResult, type QueryResultColumn, type QueryRow, ReadOnlyViolationError, type SelectSpec, type SqlBackupRecord, type SqlBackupWriteInput, type SqlBackupWriteOptions, type SqlParam, type StatementKind, type TableInfo, Transaction, type WriteBackupOperation, type WriteBackupPlan, buildCount, buildDelete, buildInsert, buildSelect, buildUpdate, buildWriteBackupPlan, cfHanaBackupRoot, connect, createDriver, errorMessage, formatCsv, formatJson, formatResult, formatTable, query, withConnection, writeSqlBackup };

package/dist/index.js

@@ -1,5 +1,11 @@
 #!/usr/bin/env node
 
+// src/backup.ts
+import { createHash, randomUUID } from "crypto";
+import { mkdir, writeFile } from "fs/promises";
+import { homedir } from "os";
+import { join } from "path";
+
 // src/errors.ts
 var CfHanaError = class extends Error {
   code;
@@ -43,6 +49,91 @@ function errorMessage(error) {
   return String(error);
 }
 
+// src/format.ts
+function cellText(value, nullText) {
+  if (value === null) {
+    return nullText;
+  }
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+  if (Buffer.isBuffer(value)) {
+    return `0x${value.toString("hex")}`;
+  }
+  if (typeof value === "boolean") {
+    return value ? "true" : "false";
+  }
+  return typeof value === "number" ? value.toString() : value;
+}
+function serializeCell(value) {
+  if (value === null) {
+    return null;
+  }
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+  if (Buffer.isBuffer(value)) {
+    return `0x${value.toString("hex")}`;
+  }
+  return value;
+}
+function csvEscape(text) {
+  if (/[",\r\n]/.test(text)) {
+    return `"${text.replace(/"/g, '""')}"`;
+  }
+  return text;
+}
+function formatTable(result) {
+  if (result.columns.length === 0) {
+    return `(${String(result.rowCount)} row(s) affected)`;
+  }
+  const headers = result.columns.map((column) => column.name);
+  const rows = result.rows.map(
+    (row) => result.columns.map((column) => cellText(row[column.name] ?? null, "NULL"))
+  );
+  const widths = headers.map((header, index) => {
+    const widest = rows.reduce(
+      (max, cells) => Math.max(max, (cells[index] ?? "").length),
+      header.length
+    );
+    return widest;
+  });
+  const renderRow = (cells) => cells.map((cell, index) => cell.padEnd(widths[index] ?? 0)).join(" | ");
+  const separator = widths.map((width) => "-".repeat(width)).join("-+-");
+  const body = rows.map((cells) => renderRow(cells));
+  return [renderRow(headers), separator, ...body].join("\n");
+}
+function formatJson(result) {
+  const rows = result.rows.map((row) => {
+    const serialized = {};
+    for (const [key, value] of Object.entries(row)) {
+      serialized[key] = serializeCell(value);
+    }
+    return serialized;
+  });
+  return JSON.stringify(rows, null, 2);
+}
+function formatCsv(result) {
+  const headers = result.columns.map((column) => column.name);
+  const lines = [headers.map((header) => csvEscape(header)).join(",")];
+  for (const row of result.rows) {
+    lines.push(
+      result.columns.map((column) => csvEscape(cellText(row[column.name] ?? null, ""))).join(",")
+    );
+  }
+  return lines.join("\r\n");
+}
+function formatResult(result, format) {
+  switch (format) {
+    case "table":
+      return formatTable(result);
+    case "json":
+      return formatJson(result);
+    case "csv":
+      return formatCsv(result);
+  }
+}
+
 // src/statements.ts
 var LEADING_NOISE = /^(?:\s|--[^\n]*\n?|\/\*[\s\S]*?\*\/)+/;
 var SELECT_KEYWORDS = /* @__PURE__ */ new Set(["SELECT", "WITH"]);
@@ -131,6 +222,182 @@ function assertParamArity(sql, params) {
   }
 }
 
+// src/backup.ts
+var SAPTOOLS_DIR_NAME = ".saptools";
+var CF_HANA_DIR_NAME = "cf-hana";
+var BACKUPS_DIR_NAME = "backups";
+function defaultSaptoolsRoot() {
+  return join(homedir(), SAPTOOLS_DIR_NAME);
+}
+function trimStatementSql(sql) {
+  return sql.trim().replace(/;+\s*$/, "").trim();
+}
+function isIdentifierChar(char) {
+  return char !== void 0 && /[A-Za-z0-9_$#]/.test(char);
+}
+function skipQuotedText(sql, index) {
+  const quote = sql[index];
+  let cursor = index + 1;
+  while (cursor < sql.length) {
+    if (sql[cursor] === quote) {
+      if (sql[cursor + 1] === quote) {
+        cursor += 2;
+        continue;
+      }
+      return cursor + 1;
+    }
+    cursor += 1;
+  }
+  return cursor;
+}
+function skipLineComment(sql, index) {
+  let cursor = index + 2;
+  while (cursor < sql.length && sql[cursor] !== "\n") {
+    cursor += 1;
+  }
+  return cursor;
+}
+function skipBlockComment(sql, index) {
+  let cursor = index + 2;
+  while (cursor < sql.length && !(sql[cursor] === "*" && sql[cursor + 1] === "/")) {
+    cursor += 1;
+  }
+  return Math.min(cursor + 2, sql.length);
+}
+function skipNonCode(sql, index) {
+  const char = sql[index];
+  if (char === "'" || char === '"') {
+    return skipQuotedText(sql, index);
+  }
+  if (char === "-" && sql[index + 1] === "-") {
+    return skipLineComment(sql, index);
+  }
+  if (char === "/" && sql[index + 1] === "*") {
+    return skipBlockComment(sql, index);
+  }
+  return void 0;
+}
+function keywordMatches(sql, index, keyword) {
+  const end = index + keyword.length;
+  return sql.slice(index, end).toUpperCase() === keyword && !isIdentifierChar(sql[index - 1]) && !isIdentifierChar(sql[end]);
+}
+function findTopLevelKeyword(sql, keyword, startIndex = 0) {
+  let index = startIndex;
+  let depth = 0;
+  while (index < sql.length) {
+    const skipped = skipNonCode(sql, index);
+    if (skipped !== void 0) {
+      index = skipped;
+      continue;
+    }
+    const char = sql[index];
+    if (char === "(") {
+      depth += 1;
+    } else if (char === ")" && depth > 0) {
+      depth -= 1;
+    } else if (depth === 0 && keywordMatches(sql, index, keyword)) {
+      return index;
+    }
+    index += 1;
+  }
+  return void 0;
+}
+function selectParamsAfterWhere(statementSql, whereIndex, params) {
+  return params.slice(countPlaceholders(statementSql.slice(0, whereIndex)));
+}
+function buildSelectPlan(operation, statementSql, targetSql, whereIndex, params) {
+  const target = targetSql.trim();
+  if (target.length === 0) {
+    throw new QueryError(`${operation.toUpperCase()} backup requires a target table`);
+  }
+  if (whereIndex === void 0) {
+    return { operation, statementSql, selectSql: `SELECT * FROM ${target}`, selectParams: [] };
+  }
+  const whereSql = statementSql.slice(whereIndex + "WHERE".length).trim();
+  if (whereSql.length === 0) {
+    throw new QueryError(`${operation.toUpperCase()} backup requires a non-empty WHERE clause`);
+  }
+  return {
+    operation,
+    statementSql,
+    selectSql: `SELECT * FROM ${target} WHERE ${whereSql}`,
+    selectParams: selectParamsAfterWhere(statementSql, whereIndex, params)
+  };
+}
+function buildUpdateBackupPlan(statementSql, params) {
+  const updateIndex = findTopLevelKeyword(statementSql, "UPDATE");
+  const setIndex = updateIndex === void 0 ? void 0 : findTopLevelKeyword(statementSql, "SET", updateIndex + "UPDATE".length);
+  if (updateIndex === void 0 || setIndex === void 0) {
+    throw new QueryError("UPDATE backup requires UPDATE <target> SET syntax");
+  }
+  const whereIndex = findTopLevelKeyword(statementSql, "WHERE", setIndex + "SET".length);
+  return buildSelectPlan(
+    "update",
+    statementSql,
+    statementSql.slice(updateIndex + "UPDATE".length, setIndex),
+    whereIndex,
+    params
+  );
+}
+function buildDeleteBackupPlan(statementSql, params) {
+  const deleteIndex = findTopLevelKeyword(statementSql, "DELETE");
+  const fromIndex = deleteIndex === void 0 ? void 0 : findTopLevelKeyword(statementSql, "FROM", deleteIndex + "DELETE".length);
+  if (deleteIndex === void 0 || fromIndex === void 0) {
+    throw new QueryError("DELETE backup requires DELETE FROM <target> syntax");
+  }
+  const whereIndex = findTopLevelKeyword(statementSql, "WHERE", fromIndex + "FROM".length);
+  const targetEnd = whereIndex ?? statementSql.length;
+  return buildSelectPlan(
+    "delete",
+    statementSql,
+    statementSql.slice(fromIndex + "FROM".length, targetEnd),
+    whereIndex,
+    params
+  );
+}
+function backupTimestamp(now) {
+  return now.toISOString().replace(/:/g, "").replace(".", "");
+}
+function backupHash(statementSql) {
+  return createHash("sha256").update(statementSql).update("\0").update(randomUUID()).digest("hex").slice(0, 12);
+}
+function cfHanaBackupRoot(saptoolsRoot) {
+  return join(saptoolsRoot ?? defaultSaptoolsRoot(), CF_HANA_DIR_NAME, BACKUPS_DIR_NAME);
+}
+function buildWriteBackupPlan(sql, params = []) {
+  const statementSql = trimStatementSql(sql);
+  const keyword = firstKeyword(statementSql);
+  if (keyword !== "UPDATE" && keyword !== "DELETE") {
+    return void 0;
+  }
+  assertParamArity(statementSql, params);
+  if (keyword === "UPDATE") {
+    return buildUpdateBackupPlan(statementSql, params);
+  }
+  return buildDeleteBackupPlan(statementSql, params);
+}
+async function writeSqlBackup(input, options = {}) {
+  const now = options.now ?? /* @__PURE__ */ new Date();
+  const directory = join(
+    cfHanaBackupRoot(options.saptoolsRoot),
+    `${backupTimestamp(now)}-${input.operation}-${backupHash(input.statementSql)}`
+  );
+  const statementPath = join(directory, "statement.sql");
+  const backupPath = join(directory, "backup.csv");
+  await mkdir(directory, { recursive: true, mode: 448 });
+  await Promise.all([
+    writeFile(statementPath, `${input.statementSql}
+`, { encoding: "utf8", mode: 384 }),
+    writeFile(backupPath, formatCsv(input.result), { encoding: "utf8", mode: 384 })
+  ]);
+  return {
+    directory,
+    statementPath,
+    backupPath,
+    rowCount: input.result.rowCount
+  };
+}
+
 // src/builder.ts
 function buildWhere(where) {
   if (where === void 0) {
@@ -243,7 +510,7 @@ async function listColumns(connection, schema, table) {
 }
 
 // src/config.ts
-var CLI_VERSION = "0.1.3";
+var CLI_VERSION = "0.1.5";
 var ENV_PREFIX = "CF_HANA";
 var DEFAULT_QUERY_TIMEOUT_MS = 3e4;
 var DEFAULT_CONNECT_TIMEOUT_MS = 3e4;
@@ -666,16 +933,16 @@ function createDriver(name) {
 }
 
 // src/history.ts
-import { appendFile, mkdir, readdir, rm } from "fs/promises";
-import { homedir } from "os";
-import { join } from "path";
-var SAPTOOLS_DIR_NAME = ".saptools";
-var CF_HANA_DIR_NAME = "cf-hana";
+import { appendFile, mkdir as mkdir2, readdir, rm } from "fs/promises";
+import { homedir as homedir2 } from "os";
+import { join as join2 } from "path";
+var SAPTOOLS_DIR_NAME2 = ".saptools";
+var CF_HANA_DIR_NAME2 = "cf-hana";
 var HISTORIES_DIR_NAME = "histories";
 var HISTORY_RETENTION_DAYS = 5;
 var HISTORY_FILE_PATTERN = /^\d{4}-\d{2}-\d{2}\.jsonl$/;
-function defaultSaptoolsRoot() {
-  return join(homedir(), SAPTOOLS_DIR_NAME);
+function defaultSaptoolsRoot2() {
+  return join2(homedir2(), SAPTOOLS_DIR_NAME2);
 }
 function padDatePart(value) {
   return value.toString().padStart(2, "0");
@@ -694,13 +961,13 @@ function retentionCutoffKey(now) {
   return dateKey(cutoff);
 }
 function resolveSaptoolsRoot(root) {
-  return root ?? defaultSaptoolsRoot();
+  return root ?? defaultSaptoolsRoot2();
 }
 function cfHanaHistoryDirectory(saptoolsRoot) {
-  return join(resolveSaptoolsRoot(saptoolsRoot), CF_HANA_DIR_NAME, HISTORIES_DIR_NAME);
+  return join2(resolveSaptoolsRoot(saptoolsRoot), CF_HANA_DIR_NAME2, HISTORIES_DIR_NAME);
 }
 function sqlHistoryFilePath(now = /* @__PURE__ */ new Date(), saptoolsRoot) {
-  return join(cfHanaHistoryDirectory(saptoolsRoot), `${dateKey(now)}.jsonl`);
+  return join2(cfHanaHistoryDirectory(saptoolsRoot), `${dateKey(now)}.jsonl`);
 }
 async function pruneSqlHistory(now, saptoolsRoot) {
   const historyDir = cfHanaHistoryDirectory(saptoolsRoot);
@@ -716,7 +983,7 @@ async function pruneSqlHistory(now, saptoolsRoot) {
   const cutoffKey = retentionCutoffKey(now);
   await Promise.all(
     files.filter((file) => HISTORY_FILE_PATTERN.test(file)).filter((file) => file.slice(0, 10) < cutoffKey).map(async (file) => {
-      await rm(join(historyDir, file), { force: true });
+      await rm(join2(historyDir, file), { force: true });
     })
   );
 }
@@ -727,7 +994,7 @@ async function appendSqlHistory(input, options = {}) {
     at: now.toISOString(),
     ...input
   };
-  await mkdir(historyDir, { recursive: true, mode: 448 });
+  await mkdir2(historyDir, { recursive: true, mode: 448 });
   await appendFile(sqlHistoryFilePath(now, options.saptoolsRoot), `${JSON.stringify(entry)}
 `, {
     encoding: "utf8",
@@ -743,7 +1010,7 @@ async function appendSqlHistory(input, options = {}) {
 // src/safety.ts
 var DESTRUCTIVE_DDL_KEYWORDS = /* @__PURE__ */ new Set(["DROP", "TRUNCATE", "ALTER"]);
 var UNSCOPED_WRITE_KEYWORDS = /* @__PURE__ */ new Set(["UPDATE", "DELETE"]);
-function skipQuotedText(sql, start) {
+function skipQuotedText2(sql, start) {
   const quote = sql[start];
   let index = start + 1;
   while (index < sql.length) {
@@ -759,14 +1026,14 @@ function skipQuotedText(sql, start) {
   }
   return index;
 }
-function skipLineComment(sql, start) {
+function skipLineComment2(sql, start) {
   let index = start + 2;
   while (index < sql.length && sql[index] !== "\n") {
     index += 1;
   }
   return index;
 }
-function skipBlockComment(sql, start) {
+function skipBlockComment2(sql, start) {
   let index = start + 2;
   while (index < sql.length && !(sql[index] === "*" && sql[index + 1] === "/")) {
     index += 1;
@@ -779,19 +1046,19 @@ function maskIgnoredSqlText(sql) {
   while (index < sql.length) {
     const char = sql[index];
     if (char === "'" || char === '"') {
-      const end = skipQuotedText(sql, index);
+      const end = skipQuotedText2(sql, index);
       masked += " ".repeat(end - index);
       index = end;
       continue;
     }
     if (char === "-" && sql[index + 1] === "-") {
-      const end = skipLineComment(sql, index);
+      const end = skipLineComment2(sql, index);
       masked += " ".repeat(end - index);
       index = end;
       continue;
     }
     if (char === "/" && sql[index + 1] === "*") {
-      const end = skipBlockComment(sql, index);
+      const end = skipBlockComment2(sql, index);
       masked += " ".repeat(end - index);
       index = end;
       continue;
@@ -809,11 +1076,11 @@ function trailingLineCommentIndex(sql) {
   while (index < sql.length) {
     const char = sql[index];
     if (char === "'" || char === '"') {
-      index = skipQuotedText(sql, index);
+      index = skipQuotedText2(sql, index);
       continue;
     }
     if (char === "/" && sql[index + 1] === "*") {
-      index = skipBlockComment(sql, index);
+      index = skipBlockComment2(sql, index);
       continue;
     }
     if (char === "-" && sql[index + 1] === "-") {
@@ -1250,6 +1517,27 @@ var HanaClient = class _HanaClient {
     await this.recordSqlHistory("execute", sql, resolvedParams, result);
     return result;
   }
+  /** Back up rows matched by an UPDATE or DELETE before the caller runs it. */
+  async backupWriteStatement(sql, params, options) {
+    const resolvedParams = params ?? [];
+    const plan = buildWriteBackupPlan(sql, resolvedParams);
+    if (plan === void 0) {
+      return void 0;
+    }
+    return await this.pool.withConnection(async (connection) => {
+      connection.assertAllowed(plan.statementSql, options);
+      const backupQueryOptions = {
+        autoLimit: false,
+        ...options?.timeoutMs === void 0 ? {} : { timeoutMs: options.timeoutMs }
+      };
+      const result = await connection.query(plan.selectSql, plan.selectParams, backupQueryOptions);
+      return await writeSqlBackup({
+        operation: plan.operation,
+        statementSql: plan.statementSql,
+        result
+      });
+    });
+  }
   /** Run a typed `SELECT` built from a spec. */
   async selectFrom(spec) {
     const built = buildSelect(spec);
@@ -1404,91 +1692,6 @@ async function withConnection(selector, work, options) {
     await client.close();
   }
 }
-
-// src/format.ts
-function cellText(value, nullText) {
-  if (value === null) {
-    return nullText;
-  }
-  if (value instanceof Date) {
-    return value.toISOString();
-  }
-  if (Buffer.isBuffer(value)) {
-    return `0x${value.toString("hex")}`;
-  }
-  if (typeof value === "boolean") {
-    return value ? "true" : "false";
-  }
-  return typeof value === "number" ? value.toString() : value;
-}
-function serializeCell(value) {
-  if (value === null) {
-    return null;
-  }
-  if (value instanceof Date) {
-    return value.toISOString();
-  }
-  if (Buffer.isBuffer(value)) {
-    return `0x${value.toString("hex")}`;
-  }
-  return value;
-}
-function csvEscape(text) {
-  if (/[",\r\n]/.test(text)) {
-    return `"${text.replace(/"/g, '""')}"`;
-  }
-  return text;
-}
-function formatTable(result) {
-  if (result.columns.length === 0) {
-    return `(${String(result.rowCount)} row(s) affected)`;
-  }
-  const headers = result.columns.map((column) => column.name);
-  const rows = result.rows.map(
-    (row) => result.columns.map((column) => cellText(row[column.name] ?? null, "NULL"))
-  );
-  const widths = headers.map((header, index) => {
-    const widest = rows.reduce(
-      (max, cells) => Math.max(max, (cells[index] ?? "").length),
-      header.length
-    );
-    return widest;
-  });
-  const renderRow = (cells) => cells.map((cell, index) => cell.padEnd(widths[index] ?? 0)).join(" | ");
-  const separator = widths.map((width) => "-".repeat(width)).join("-+-");
-  const body = rows.map((cells) => renderRow(cells));
-  return [renderRow(headers), separator, ...body].join("\n");
-}
-function formatJson(result) {
-  const rows = result.rows.map((row) => {
-    const serialized = {};
-    for (const [key, value] of Object.entries(row)) {
-      serialized[key] = serializeCell(value);
-    }
-    return serialized;
-  });
-  return JSON.stringify(rows, null, 2);
-}
-function formatCsv(result) {
-  const headers = result.columns.map((column) => column.name);
-  const lines = [headers.map((header) => csvEscape(header)).join(",")];
-  for (const row of result.rows) {
-    lines.push(
-      result.columns.map((column) => csvEscape(cellText(row[column.name] ?? null, ""))).join(",")
-    );
-  }
-  return lines.join("\r\n");
-}
-function formatResult(result, format) {
-  switch (format) {
-    case "table":
-      return formatTable(result);
-    case "json":
-      return formatJson(result);
-    case "csv":
-      return formatCsv(result);
-  }
-}
 export {
   CfHanaError,
   CredentialsNotFoundError,
@@ -1502,6 +1705,8 @@ export {
   buildInsert,
   buildSelect,
   buildUpdate,
+  buildWriteBackupPlan,
+  cfHanaBackupRoot,
   connect,
   createDriver,
   errorMessage,
@@ -1510,6 +1715,7 @@ export {
   formatResult,
   formatTable,
   query,
-  withConnection
+  withConnection,
+  writeSqlBackup
 };
 //# sourceMappingURL=index.js.map