neon 3.0.0 → 3.1.0

package/dist/psql/io/history.js

@@ -1,299 +1,260 @@
-/**
- * psql history file I/O.
- *
- * TypeScript port of the history-handling portion of PostgreSQL's
- * `src/bin/psql/input.c`. Implements the read/append/truncate operations the
- * REPL drives plus the small env-resolution helpers (`PSQL_HISTORY`,
- * `HISTSIZE`).
- *
- * On-disk format follows GNU readline's history file:
- *
- *   - One entry per line, UTF-8.
- *   - Multi-line entries are encoded with the literal escape sequences
- *     `\n` (backslash + n), `\r`, and `\\`. We decode them back to real
- *     newlines / carriage returns / backslashes on load and re-encode on
- *     write. Upstream psql uses an in-memory NL_IN_HISTORY (0x01) marker
- *     that libreadline then translates to the same on-disk form; we skip
- *     the intermediate marker and operate on real strings throughout.
- *   - Lines whose first character is `#` are treated as timestamp / comment
- *     markers (libreadline writes them when `history_write_timestamps` is
- *     set) and silently skipped on load. psql itself never writes them.
- *
- * Intentional deviations from upstream:
- *
- *   - Append-only writes use `fs.promises.appendFile`, which opens the file
- *     with `O_APPEND` on POSIX so concurrent appends from multiple psql
- *     instances do not interleave within a single write call. On Windows
- *     there is a small race window we accept; the alternative (an external
- *     lock file) is not worth the dependency churn.
- *   - `truncateHistory` writes the trimmed history to a sibling temp file
- *     and `rename`s it into place. POSIX `rename(2)` is atomic w.r.t. other
- *     processes observing the path; Windows is best-effort.
- *   - HISTCONTROL comparisons run on the raw (decoded) entry — this matches
- *     bash/readline behaviour where the user's literal input is what gets
- *     deduped, not the escaped on-disk form.
- */
-import { randomUUID } from "node:crypto";
-import { promises as fs } from "node:fs";
-import * as os from "node:os";
+import { promises } from "node:fs";
 import * as path from "node:path";
+import * as os from "node:os";
+import { randomUUID } from "node:crypto";
+//#region src/psql/io/history.ts
+/**
+* psql history file I/O.
+*
+* TypeScript port of the history-handling portion of PostgreSQL's
+* `src/bin/psql/input.c`. Implements the read/append/truncate operations the
+* REPL drives plus the small env-resolution helpers (`PSQL_HISTORY`,
+* `HISTSIZE`).
+*
+* On-disk format follows GNU readline's history file:
+*
+*   - One entry per line, UTF-8.
+*   - Multi-line entries are encoded with the literal escape sequences
+*     `\n` (backslash + n), `\r`, and `\\`. We decode them back to real
+*     newlines / carriage returns / backslashes on load and re-encode on
+*     write. Upstream psql uses an in-memory NL_IN_HISTORY (0x01) marker
+*     that libreadline then translates to the same on-disk form; we skip
+*     the intermediate marker and operate on real strings throughout.
+*   - Lines whose first character is `#` are treated as timestamp / comment
+*     markers (libreadline writes them when `history_write_timestamps` is
+*     set) and silently skipped on load. psql itself never writes them.
+*
+* Intentional deviations from upstream:
+*
+*   - Append-only writes use `fs.promises.appendFile`, which opens the file
+*     with `O_APPEND` on POSIX so concurrent appends from multiple psql
+*     instances do not interleave within a single write call. On Windows
+*     there is a small race window we accept; the alternative (an external
+*     lock file) is not worth the dependency churn.
+*   - `truncateHistory` writes the trimmed history to a sibling temp file
+*     and `rename`s it into place. POSIX `rename(2)` is atomic w.r.t. other
+*     processes observing the path; Windows is best-effort.
+*   - HISTCONTROL comparisons run on the raw (decoded) entry — this matches
+*     bash/readline behaviour where the user's literal input is what gets
+*     deduped, not the escaped on-disk form.
+*/
 /** psql's compiled-in default for HISTSIZE (see `src/bin/psql/settings.h`). */
 const DEFAULT_HISTSIZE = 500;
 /**
- * In-memory command-line history for the current session, oldest first.
- *
- * Upstream psql delegates history to GNU readline, whose `history_list()`
- * backs the `\s` meta-command (`exec_command_s` in `command.c` prints the
- * live in-memory history, NOT the on-disk file). We keep our own
- * process-local mirror here, populated by {@link recordHistory} from the
- * same funnel the REPL uses to persist a submitted line ({@link
- * appendHistory}). `\s` reads it via {@link getHistory}.
- *
- * Module-level state matches the single-session lifetime of a psql process;
- * tests reset it with {@link clearHistory}.
- */
+* In-memory command-line history for the current session, oldest first.
+*
+* Upstream psql delegates history to GNU readline, whose `history_list()`
+* backs the `\s` meta-command (`exec_command_s` in `command.c` prints the
+* live in-memory history, NOT the on-disk file). We keep our own
+* process-local mirror here, populated by {@link recordHistory} from the
+* same funnel the REPL uses to persist a submitted line ({@link
+* appendHistory}). `\s` reads it via {@link getHistory}.
+*
+* Module-level state matches the single-session lifetime of a psql process;
+* tests reset it with {@link clearHistory}.
+*/
 let inMemoryHistory = [];
 /**
- * Record one submitted line in the session's in-memory history.
- *
- * Empty lines and an exact duplicate of the immediately preceding entry are
- * dropped, mirroring readline's default behaviour (and {@link
- * LineEditor.pushHistory}); HISTCONTROL filtering is applied by the caller
- * ({@link appendHistory}) before this is reached.
- */
-export const recordHistory = (entry) => {
-    if (entry.length === 0)
-        return;
-    if (inMemoryHistory[inMemoryHistory.length - 1] === entry)
-        return;
-    inMemoryHistory.push(entry);
+* Record one submitted line in the session's in-memory history.
+*
+* Empty lines and an exact duplicate of the immediately preceding entry are
+* dropped, mirroring readline's default behaviour (and {@link
+* LineEditor.pushHistory}); HISTCONTROL filtering is applied by the caller
+* ({@link appendHistory}) before this is reached.
+*/
+const recordHistory = (entry) => {
+	if (entry.length === 0) return;
+	if (inMemoryHistory[inMemoryHistory.length - 1] === entry) return;
+	inMemoryHistory.push(entry);
 };
 /**
- * Return the session's in-memory history (oldest first). Returns a copy so
- * callers can't mutate the backing store.
- */
-export const getHistory = () => inMemoryHistory.slice();
+* Return the session's in-memory history (oldest first). Returns a copy so
+* callers can't mutate the backing store.
+*/
+const getHistory = () => inMemoryHistory.slice();
 /** Reset the in-memory history. Primarily for tests and `\s`-less restarts. */
-export const clearHistory = () => {
-    inMemoryHistory = [];
+const clearHistory = () => {
+	inMemoryHistory = [];
 };
 /** Encode a single in-memory entry to the on-disk libreadline form. */
 const encodeEntry = (entry) => entry.replace(/\\/g, "\\\\").replace(/\n/g, "\\n").replace(/\r/g, "\\r");
 /**
- * Decode a single on-disk libreadline line back to its in-memory form.
- *
- * Recognised escapes: `\\` → `\`, `\n` → newline, `\r` → CR. Any other
- * `\<x>` sequence is left as-is (matching readline's lenient decoder), so
- * a stray backslash at the end of the file does not eat the next entry.
- */
+* Decode a single on-disk libreadline line back to its in-memory form.
+*
+* Recognised escapes: `\\` → `\`, `\n` → newline, `\r` → CR. Any other
+* `\<x>` sequence is left as-is (matching readline's lenient decoder), so
+* a stray backslash at the end of the file does not eat the next entry.
+*/
 const decodeEntry = (line) => {
-    let out = "";
-    for (let i = 0; i < line.length; i++) {
-        const c = line.charCodeAt(i);
-        if (c === 0x5c /* '\\' */ && i + 1 < line.length) {
-            const next = line[i + 1];
-            if (next === "n") {
-                out += "\n";
-                i++;
-                continue;
-            }
-            if (next === "r") {
-                out += "\r";
-                i++;
-                continue;
-            }
-            if (next === "\\") {
-                out += "\\";
-                i++;
-                continue;
-            }
-        }
-        out += line[i];
-    }
-    return out;
+	let out = "";
+	for (let i = 0; i < line.length; i++) {
+		if (line.charCodeAt(i) === 92 && i + 1 < line.length) {
+			const next = line[i + 1];
+			if (next === "n") {
+				out += "\n";
+				i++;
+				continue;
+			}
+			if (next === "r") {
+				out += "\r";
+				i++;
+				continue;
+			}
+			if (next === "\\") {
+				out += "\\";
+				i++;
+				continue;
+			}
+		}
+		out += line[i];
+	}
+	return out;
 };
 /**
- * Return `true` if `entry` should be filtered out under `histcontrol`
- * relative to the most recent entry already in history (`prev`).
- *
- * Mirrors `pg_send_history()`'s filter in `input.c`.
- */
+* Return `true` if `entry` should be filtered out under `histcontrol`
+* relative to the most recent entry already in history (`prev`).
+*
+* Mirrors `pg_send_history()`'s filter in `input.c`.
+*/
 const shouldIgnore = (entry, prev, histcontrol) => {
-    const ignoreSpace = histcontrol === "ignorespace" || histcontrol === "ignoreboth";
-    const ignoreDups = histcontrol === "ignoredups" || histcontrol === "ignoreboth";
-    if (ignoreSpace && entry.length > 0 && /^\s/.test(entry))
-        return true;
-    if (ignoreDups && prev !== undefined && prev === entry)
-        return true;
-    return false;
+	const ignoreSpace = histcontrol === "ignorespace" || histcontrol === "ignoreboth";
+	const ignoreDups = histcontrol === "ignoredups" || histcontrol === "ignoreboth";
+	if (ignoreSpace && entry.length > 0 && /^\s/.test(entry)) return true;
+	if (ignoreDups && prev !== void 0 && prev === entry) return true;
+	return false;
 };
 /**
- * Read a libreadline history file and return entries in chronological
- * order (oldest first). A missing file resolves to `[]` so callers can
- * unconditionally `loadHistory` at startup.
- *
- * Lines beginning with `#` are silently skipped (libreadline timestamp
- * markers; psql itself never writes them but we tolerate them).
- *
- * Other I/O errors (EACCES, EISDIR, …) propagate to the caller.
- */
-export const loadHistory = async (filePath) => {
-    let raw;
-    try {
-        raw = await fs.readFile(filePath, "utf8");
-    }
-    catch (err) {
-        if (err &&
-            typeof err === "object" &&
-            "code" in err &&
-            err.code === "ENOENT") {
-            return [];
-        }
-        throw err;
-    }
-    // Strip a single trailing newline so a well-formed file ending in `\n`
-    // doesn't produce a phantom empty entry. Don't strip more than one — a
-    // blank line in the middle of the file represents an entry that was
-    // literally the empty string (rare but possible), and we round-trip it.
-    if (raw.endsWith("\n"))
-        raw = raw.slice(0, -1);
-    if (raw.length === 0)
-        return [];
-    const entries = [];
-    for (const line of raw.split("\n")) {
-        if (line.startsWith("#"))
-            continue;
-        entries.push(decodeEntry(line));
-    }
-    return entries;
+* Read a libreadline history file and return entries in chronological
+* order (oldest first). A missing file resolves to `[]` so callers can
+* unconditionally `loadHistory` at startup.
+*
+* Lines beginning with `#` are silently skipped (libreadline timestamp
+* markers; psql itself never writes them but we tolerate them).
+*
+* Other I/O errors (EACCES, EISDIR, …) propagate to the caller.
+*/
+const loadHistory = async (filePath) => {
+	let raw;
+	try {
+		raw = await promises.readFile(filePath, "utf8");
+	} catch (err) {
+		if (err && typeof err === "object" && "code" in err && err.code === "ENOENT") return [];
+		throw err;
+	}
+	if (raw.endsWith("\n")) raw = raw.slice(0, -1);
+	if (raw.length === 0) return [];
+	const entries = [];
+	for (const line of raw.split("\n")) {
+		if (line.startsWith("#")) continue;
+		entries.push(decodeEntry(line));
+	}
+	return entries;
 };
 /**
- * Append a single entry to the history file, subject to HISTCONTROL.
- *
- * Implementation notes:
- *
- *   - On POSIX, `fs.appendFile` opens with `O_APPEND`, which guarantees
- *     each `write(2)` lands at the current end-of-file. A single
- *     encoded entry plus its trailing `\n` is one write, so concurrent
- *     psql instances writing to the same history file never interleave
- *     within an entry. We accept a small race on Windows.
- *   - `ignoredups` consults the *last* entry currently on disk. We read
- *     the tail of the file rather than the whole history to keep this
- *     O(1)-ish for large histories; for simplicity we read everything
- *     when ignoredups is in effect — typical history files are well
- *     under 1 MiB.
- */
-export const appendHistory = async (filePath, entry, histcontrol = "none") => {
-    if (histcontrol === "ignoredups" ||
-        histcontrol === "ignoreboth" ||
-        histcontrol === "ignorespace") {
-        let prev;
-        if (histcontrol === "ignoredups" || histcontrol === "ignoreboth") {
-            const existing = await loadHistory(filePath);
-            prev = existing[existing.length - 1];
-        }
-        if (shouldIgnore(entry, prev, histcontrol))
-            return;
-    }
-    // Mirror the line into the session's in-memory history (what `\s` prints)
-    // using the same funnel that persists it to disk, so the two stay in
-    // lock-step under HISTCONTROL. Recording happens AFTER the ignore check
-    // so an ignored line is absent from both.
-    recordHistory(entry);
-    await fs.appendFile(filePath, encodeEntry(entry) + "\n", "utf8");
+* Append a single entry to the history file, subject to HISTCONTROL.
+*
+* Implementation notes:
+*
+*   - On POSIX, `fs.appendFile` opens with `O_APPEND`, which guarantees
+*     each `write(2)` lands at the current end-of-file. A single
+*     encoded entry plus its trailing `\n` is one write, so concurrent
+*     psql instances writing to the same history file never interleave
+*     within an entry. We accept a small race on Windows.
+*   - `ignoredups` consults the *last* entry currently on disk. We read
+*     the tail of the file rather than the whole history to keep this
+*     O(1)-ish for large histories; for simplicity we read everything
+*     when ignoredups is in effect — typical history files are well
+*     under 1 MiB.
+*/
+const appendHistory = async (filePath, entry, histcontrol = "none") => {
+	if (histcontrol === "ignoredups" || histcontrol === "ignoreboth" || histcontrol === "ignorespace") {
+		let prev;
+		if (histcontrol === "ignoredups" || histcontrol === "ignoreboth") {
+			const existing = await loadHistory(filePath);
+			prev = existing[existing.length - 1];
+		}
+		if (shouldIgnore(entry, prev, histcontrol)) return;
+	}
+	recordHistory(entry);
+	await promises.appendFile(filePath, encodeEntry(entry) + "\n", "utf8");
 };
 /**
- * Trim the history file to its last `maxLines` entries.
- *
- * If `maxLines <= 0` the file is removed entirely (matching psql's
- * behaviour when HISTSIZE is set to 0). If the file already fits the
- * cap, it's left untouched. Otherwise we write the kept tail to a
- * sibling temp file and `rename` it into place.
- *
- * `rename(2)` on POSIX is atomic w.r.t. observers of the destination
- * path; on Windows the platform call may briefly fail if another
- * process has the destination open, in which case the error propagates.
- */
-export const truncateHistory = async (filePath, maxLines) => {
-    if (maxLines <= 0) {
-        try {
-            await fs.unlink(filePath);
-        }
-        catch (err) {
-            if (err &&
-                typeof err === "object" &&
-                "code" in err &&
-                err.code === "ENOENT") {
-                return;
-            }
-            throw err;
-        }
-        return;
-    }
-    const entries = await loadHistory(filePath);
-    if (entries.length <= maxLines)
-        return;
-    const kept = entries.slice(entries.length - maxLines);
-    const body = kept.map(encodeEntry).join("\n") + "\n";
-    const dir = path.dirname(filePath);
-    const base = path.basename(filePath);
-    const tmpPath = path.join(dir, `.${base}.${randomUUID()}.tmp`);
-    await fs.writeFile(tmpPath, body, { encoding: "utf8", mode: 0o600 });
-    try {
-        await fs.rename(tmpPath, filePath);
-    }
-    catch (err) {
-        // Best-effort cleanup; the temp file is harmless but noisy.
-        try {
-            await fs.unlink(tmpPath);
-        }
-        catch {
-            /* ignore */
-        }
-        throw err;
-    }
+* Trim the history file to its last `maxLines` entries.
+*
+* If `maxLines <= 0` the file is removed entirely (matching psql's
+* behaviour when HISTSIZE is set to 0). If the file already fits the
+* cap, it's left untouched. Otherwise we write the kept tail to a
+* sibling temp file and `rename` it into place.
+*
+* `rename(2)` on POSIX is atomic w.r.t. observers of the destination
+* path; on Windows the platform call may briefly fail if another
+* process has the destination open, in which case the error propagates.
+*/
+const truncateHistory = async (filePath, maxLines) => {
+	if (maxLines <= 0) {
+		try {
+			await promises.unlink(filePath);
+		} catch (err) {
+			if (err && typeof err === "object" && "code" in err && err.code === "ENOENT") return;
+			throw err;
+		}
+		return;
+	}
+	const entries = await loadHistory(filePath);
+	if (entries.length <= maxLines) return;
+	const body = entries.slice(entries.length - maxLines).map(encodeEntry).join("\n") + "\n";
+	const dir = path.dirname(filePath);
+	const base = path.basename(filePath);
+	const tmpPath = path.join(dir, `.${base}.${randomUUID()}.tmp`);
+	await promises.writeFile(tmpPath, body, {
+		encoding: "utf8",
+		mode: 384
+	});
+	try {
+		await promises.rename(tmpPath, filePath);
+	} catch (err) {
+		try {
+			await promises.unlink(tmpPath);
+		} catch {}
+		throw err;
+	}
 };
 /**
- * Resolve the on-disk history file path psql would use, in order of
- * precedence:
- *
- *   1. `$PSQL_HISTORY` if set and non-empty.
- *   2. On Windows: `%APPDATA%\postgresql\psql_history`.
- *   3. Otherwise: `$HOME/.psql_history` (falling back to `os.homedir()`
- *      if `$HOME` is unset, e.g. in some sandboxes).
- *
- * Pure function — `env` defaults to `process.env` but can be injected
- * for tests.
- */
-export const defaultHistoryPath = (env = process.env) => {
-    const explicit = env.PSQL_HISTORY;
-    if (explicit !== undefined && explicit.length > 0)
-        return explicit;
-    if (process.platform === "win32") {
-        const appdata = env.APPDATA;
-        if (appdata !== undefined && appdata.length > 0) {
-            return path.join(appdata, "postgresql", "psql_history");
-        }
-        // Fall through to homedir() if APPDATA isn't set; matches psql's
-        // graceful degradation on a minimally-configured Windows session.
-    }
-    const home = env.HOME ?? os.homedir();
-    return path.join(home, ".psql_history");
+* Resolve the on-disk history file path psql would use, in order of
+* precedence:
+*
+*   1. `$PSQL_HISTORY` if set and non-empty.
+*   2. On Windows: `%APPDATA%\postgresql\psql_history`.
+*   3. Otherwise: `$HOME/.psql_history` (falling back to `os.homedir()`
+*      if `$HOME` is unset, e.g. in some sandboxes).
+*
+* Pure function — `env` defaults to `process.env` but can be injected
+* for tests.
+*/
+const defaultHistoryPath = (env = process.env) => {
+	const explicit = env.PSQL_HISTORY;
+	if (explicit !== void 0 && explicit.length > 0) return explicit;
+	if (process.platform === "win32") {
+		const appdata = env.APPDATA;
+		if (appdata !== void 0 && appdata.length > 0) return path.join(appdata, "postgresql", "psql_history");
+	}
+	const home = env.HOME ?? os.homedir();
+	return path.join(home, ".psql_history");
 };
 /**
- * Resolve the effective HISTSIZE: the `HISTSIZE` env var (if a
- * non-negative integer) or psql's compiled-in default of 500.
- *
- * Values that fail to parse as a non-negative integer fall back to the
- * default — psql itself ignores malformed HISTSIZE and warns, but at
- * this layer we don't have a logger.
- */
-export const resolveHistSize = (env = process.env) => {
-    const raw = env.HISTSIZE;
-    if (raw === undefined || raw === "")
-        return DEFAULT_HISTSIZE;
-    const n = Number(raw);
-    if (!Number.isInteger(n) || n < 0)
-        return DEFAULT_HISTSIZE;
-    return n;
+* Resolve the effective HISTSIZE: the `HISTSIZE` env var (if a
+* non-negative integer) or psql's compiled-in default of 500.
+*
+* Values that fail to parse as a non-negative integer fall back to the
+* default — psql itself ignores malformed HISTSIZE and warns, but at
+* this layer we don't have a logger.
+*/
+const resolveHistSize = (env = process.env) => {
+	const raw = env.HISTSIZE;
+	if (raw === void 0 || raw === "") return DEFAULT_HISTSIZE;
+	const n = Number(raw);
+	if (!Number.isInteger(n) || n < 0) return DEFAULT_HISTSIZE;
+	return n;
 };
+//#endregion
+export { appendHistory, clearHistory, defaultHistoryPath, getHistory, loadHistory, recordHistory, resolveHistSize, truncateHistory };