@linxiraos/pi-utils 1.3.0 → 1.3.1

package/CHANGELOG.md

@@ -1,21 +1,27 @@
 ## [Unreleased]
 
+## [1.3.1] - 2026-10-19
+
+### Added
+
+- Added `readSalvageableRows()` to read the rows of a damaged SQLite table that are still readable, skipping only the damaged pages ([#15751](https://github.com/can1357/oh-my-pi/pull/15751) by [@Shadorain](https://github.com/Shadorain))
+
 ## [1.3.0] - 2026-10-18
 
 ### Added
 
-- Added `getMnemopiEmbedRuntimeDir()` for the shared mnemopi embedding server endpoints and logs.
+- Added `sanitizeTextDeep()`, which applies `sanitizeText()` to every string in a JSON-shaped value without mutating it ([#15963](https://github.com/can1357/oh-my-pi/issues/15963))
 - Exported `sqliteFileIdentity()`, so a caller holding a long-lived SQLite connection can tell when its path now names a different file (e.g. after a corrupt store was quarantined and replaced) ([#14361](https://github.com/can1357/oh-my-pi/pull/14361) by [@F0Rextasy](https://github.com/F0Rextasy))
 - Added `slugify()`, the shared lowercase ASCII kebab-case helper with an optional `maxLength` ([#14283](https://github.com/can1357/oh-my-pi/pull/14283) by [@jaredlyon](https://github.com/jaredlyon))
-- Added `sanitizeTextDeep()`, which applies `sanitizeText()` to every string in a JSON-shaped value without mutating it ([#15963](https://github.com/can1357/oh-my-pi/issues/15963))
+- Added `getMnemopiEmbedRuntimeDir()` for the shared mnemopi embedding server endpoints and logs.
 
 ### Fixed
 
-- Fixed `ChildProcess.kill()` silently leaving the child running when the native process handle could not be resolved or used; it now signals the child directly and escalates to SIGKILL after the grace period.
-- Fixed an unhandled rejection when a subprocess is spawned with an already-aborted signal ([#15750](https://github.com/can1357/oh-my-pi/pull/15750) by [@harshaygadekar](https://github.com/harshaygadekar))
+- Fixed Windows archive extraction overwriting existing files or following existing symlinks when copying a symlink entry without symlink privileges ([#15931](https://github.com/can1357/oh-my-pi/pull/15931) by [@jchanghong023](https://github.com/jchanghong023)).
 - Fixed Markdown fence info-string parsing to keep backtick-containing backtick openers as paragraph text while accepting backticks in tilde info strings and Unicode line separators in either fence's info string ([#15928](https://github.com/can1357/oh-my-pi/pull/15928) by [@jchanghong023](https://github.com/jchanghong023)).
 - Fixed `parseHTML` treating `<link>` in RSS/Atom documents as an HTML void element, which dropped the URL text of RSS `<link>…</link>` ([#15954](https://github.com/can1357/oh-my-pi/issues/15954))
-- Fixed Windows archive extraction overwriting existing files or following existing symlinks when copying a symlink entry without symlink privileges ([#15931](https://github.com/can1357/oh-my-pi/pull/15931) by [@jchanghong023](https://github.com/jchanghong023)).
+- Fixed an unhandled rejection when a subprocess is spawned with an already-aborted signal ([#15750](https://github.com/can1357/oh-my-pi/pull/15750) by [@harshaygadekar](https://github.com/harshaygadekar))
+- Fixed `ChildProcess.kill()` silently leaving the child running when the native process handle could not be resolved or used; it now signals the child directly and escalates to SIGKILL after the grace period.
 
 ## [1.2.0] - 2026-10-12
 

package/dist/types/sqlite.d.ts

@@ -42,6 +42,17 @@ export declare function openSqliteDatabaseSync<T>(dbPath: string, initialize: (d
 export declare function annotateSqliteError(error: unknown, dbPath: string): Error;
 /** Checkpoints committed WAL frames without waiting for concurrent readers. */
 export declare function checkpointWal(db: Database): void;
+/**
+ * Reads every row of a rowid table that SQLite can still decode, to salvage a
+ * damaged store. A full scan aborts at the first unreadable page, so this walks
+ * rowids with indexed seeks instead: when a seek hits damage it doubles its
+ * stride past it, then bisects back to the first rowid from which seeking
+ * works again, losing only rows on the damaged pages. Cross-linked pages can
+ * still decode rows with foreign column types, so callers validate types;
+ * rows returned out of rowid order count as damage. Only corruption errors are
+ * treated as damage; anything else is thrown.
+ */
+export declare function readSalvageableRows<T extends object>(db: Database, table: string, columns: string): T[];
 /**
  * SQLite's busy result-code family — base `SQLITE_BUSY` plus the extended
  * variants `SQLITE_BUSY_RECOVERY` (concurrent WAL recovery), `SQLITE_BUSY_SNAPSHOT`,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@linxiraos/pi-utils",
-	"version": "1.3.0",
+	"version": "1.3.1",
 	"description": "Shared utilities for pi packages",
 	"keywords": [
 		"utilities",
@@ -54,7 +54,7 @@
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@linxiraos/pi-natives": "1.3.0"
+		"@linxiraos/pi-natives": "1.3.1"
 	},
 	"devDependencies": {
 		"@types/bun": "1.4.3"

package/src/sqlite.ts

@@ -343,6 +343,75 @@ export function checkpointWal(db: Database): void {
 	db.run("PRAGMA wal_checkpoint(PASSIVE)");
 }
 
+/** Damaged regions one {@link readSalvageableRows} scan skips before abandoning the rest of the table. */
+const SALVAGE_MAX_DAMAGED_REGIONS = 1000;
+
+/**
+ * Reads every row of a rowid table that SQLite can still decode, to salvage a
+ * damaged store. A full scan aborts at the first unreadable page, so this walks
+ * rowids with indexed seeks instead: when a seek hits damage it doubles its
+ * stride past it, then bisects back to the first rowid from which seeking
+ * works again, losing only rows on the damaged pages. Cross-linked pages can
+ * still decode rows with foreign column types, so callers validate types;
+ * rows returned out of rowid order count as damage. Only corruption errors are
+ * treated as damage; anything else is thrown.
+ */
+export function readSalvageableRows<T extends object>(db: Database, table: string, columns: string): T[] {
+	type Row = T & { salvage_rowid: number };
+	using seek = db.prepare<Row, [number]>(
+		`SELECT rowid AS salvage_rowid, ${columns} FROM ${table} WHERE rowid > ? ORDER BY rowid LIMIT 1`,
+	);
+	using exact = db.prepare<Row, [number]>(`SELECT rowid AS salvage_rowid, ${columns} FROM ${table} WHERE rowid = ?`);
+	// The row found, null when there is none, or undefined when the read hit damage.
+	const probe = (after: number, at?: number): Row | null | undefined => {
+		try {
+			const row = at === undefined ? seek.get(after) : exact.get(at);
+			if (!row) return null;
+			const valid = Number.isSafeInteger(row.salvage_rowid) && row.salvage_rowid === (at ?? row.salvage_rowid);
+			return valid && row.salvage_rowid > after ? row : undefined;
+		} catch (error) {
+			if (isSqliteCorruptionError(error)) return undefined;
+			throw error;
+		}
+	};
+
+	const rows: T[] = [];
+	const keep = (row: Row): void => {
+		const { salvage_rowid: _, ...values } = row;
+		rows.push(values as unknown as T);
+	};
+	let after = Number.MIN_SAFE_INTEGER;
+	let damaged = 0;
+	while (after < Number.MAX_SAFE_INTEGER) {
+		const row = probe(after);
+		if (row === null) break;
+		if (row) {
+			keep(row);
+			after = row.salvage_rowid;
+			continue;
+		}
+		if (++damaged > SALVAGE_MAX_DAMAGED_REGIONS) break;
+		// An end-of-table result counts as clear: the gap below it may still hold readable rows.
+		let bad = after;
+		let clear = Number.MAX_SAFE_INTEGER;
+		for (let step = 1; after + step < clear; step *= 2) {
+			if (probe(after + step) !== undefined) clear = after + step;
+			else bad = after + step;
+		}
+		while (clear - bad > 1) {
+			const mid = bad + Math.floor((clear - bad) / 2);
+			if (probe(mid) === undefined) bad = mid;
+			else clear = mid;
+		}
+		// An interior key bounds its left subtree inclusively, so seeking past the last
+		// damaged rowid descends into the damage again and `clear` itself is skipped.
+		const boundary = probe(bad, clear);
+		if (boundary) keep(boundary);
+		after = clear;
+	}
+	return rows;
+}
+
 /**
  * SQLite's busy result-code family — base `SQLITE_BUSY` plus the extended
  * variants `SQLITE_BUSY_RECOVERY` (concurrent WAL recovery), `SQLITE_BUSY_SNAPSHOT`,