@yorozu/db-sqlite 0.5.6 → 1.0.31

package/README.md

@@ -12,6 +12,7 @@ let driver = createSqliteDriver({
     filename: "app.sqlite",
     // native, // inject better-sqlite3 ctor (tests). Default: better-sqlite3
     log, // optional Logger; silent default
+    autoFlush: true, // opt-in; or { pendingPuts: 32, idleMs: 1000 }
 })
 
 let db = await driver.open(schema)
@@ -27,9 +28,12 @@ Logger is optional. Internally: `makeLog(opts.log ?? makeSilentLog(), "yorozu-db
 - One table per collection: `pk TEXT PRIMARY KEY`, `payload TEXT` (JSON minus blob fields), plus `"<index>__<i>"` columns (TEXT/REAL). Sidecar `"<collection>__blobs"` `(pk, field, data BLOB)`.
 - `get` rehydrates `Blob` when `Blob` exists, otherwise `Uint8Array`.
 - Reserved index `"__pk"`: primary-key walk, even if not in `CollectionDef.indexes`.
+- `scan(..., { direction: "rev" })` returns the highest keys first; omit = fwd.
 - `scan(..., { keysOnly: true })` is `SELECT pk, index columns` only. Never `payload`, never join `__blobs`. Omit `ScanHit.value`.
 - Prefix TTL: `scan("by-evict", { lt: [cutoff], keysOnly: true })` matches `[storedAt, bytes]` with `storedAt < cutoff` (`[cutoff] < [cutoff, 0]`).
 - Default `put` flush is `"now"`. `"batch"` buffers until `db.flush()` or the next `"rw"` transact commit, not `"r"`. `flush()` coalesces by `(collection, pk)`. Sync put batches use better-sqlite3 `db.transaction`.
+- `flush({ reason, signal })`: already-aborted `signal` rejects with `AbortError` (or `signal.reason`) before taking the lock; in-flight writes finish. Read transact `flush` stays a no-op.
+- Opt-in `autoFlush`: omitted = off. `true` → `{ pendingPuts: 32, idleMs: 1000 }`. After batch puts, idle-flush via `requestIdle` with `{ reason: "idle" }`; at `pendingPuts` distinct pks, re-arm with timeout 0. Successful flush / close cancels the idle handle.
 - Async `transact`: mutex + `BEGIN IMMEDIATE` / `COMMIT` / `ROLLBACK`. Not `db.transaction(fn)` (that API is sync-only). Nested `transact` throws via a facade. Concurrent `transact` serializes. Prefer the callback's `db.collection()`. A collection obtained before `transact` is reentrant while the SQL tx is open and joins that tx (rolls back with it). Concurrent ops from another task still queue on the mutex.
 - Scan `limit` is applied after `inRange` + `compareIndexKey` sort (no SQL `LIMIT`). String / mixed index keys are not filtered by SQL `WHERE` (SQLite TEXT is UTF-8; `IndexKey` strings compare as UTF-16). Select covering columns, then `inRange` / `compareIndexKey`.
 - Call `await db.flush()` before `close()`. Do not leave `{ flush: "batch" }` puts outstanding if another process may take the file.

package/driver.d.ts

@@ -5,4 +5,8 @@ export declare function createSqliteDriver(opts: {
     filename: string;
     native?: typeof Database;
     log?: Logger;
+    autoFlush?: boolean | {
+        pendingPuts?: number;
+        idleMs?: number;
+    };
 }): DbDriver;

package/index.js

@@ -773,6 +773,9 @@ var require_lib = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 	module.exports.SqliteError = require_sqlite_error();
 }));
 //#endregion
+//#region ../db/src/types.ts
+var DEFAULT_AUTO_FLUSH_IDLE_MS = 1e3;
+//#endregion
 //#region ../db/src/bounds.ts
 function rankOf(value) {
 	if (typeof value === "number") {
@@ -829,6 +832,33 @@ function inRange(indexKey, bound = {}) {
 	return true;
 }
 //#endregion
+//#region ../utils/src/async/idle.ts
+function requestIdle(fn, opts) {
+	let g = globalThis;
+	let timeout = opts?.timeout;
+	if (typeof g.requestIdleCallback === "function") {
+		let ricOpts;
+		if (timeout !== void 0) ricOpts = { timeout: timeout > 0 ? timeout : 1 };
+		let id = g.requestIdleCallback(fn, ricOpts);
+		return { cancel() {
+			g.cancelIdleCallback?.(id);
+		} };
+	}
+	let delay = 0;
+	if (typeof timeout === "number" && Number.isFinite(timeout) && timeout > 0) delay = timeout;
+	let timer = setTimeout(() => {
+		fn({
+			didTimeout: true,
+			timeRemaining() {
+				return 0;
+			}
+		});
+	}, delay);
+	return { cancel() {
+		clearTimeout(timer);
+	} };
+}
+//#endregion
 //#region ../../node_modules/.pnpm/halua@5.0.0/node_modules/halua/lib/index.js
 function toarray(value) {
 	return Array.isArray(value) ? value : typeof value === "undefined" ? [] : [value];
@@ -1599,6 +1629,22 @@ function makeLog(src, issueKey) {
 //#region src/driver.ts
 var import___vite_browser_external = require___vite_browser_external();
 var import_lib = /* @__PURE__ */ __toESM(require_lib(), 1);
+function abortedReason(signal) {
+	if (!signal?.aborted) return void 0;
+	return signal.reason ?? new DOMException("The operation was aborted.", "AbortError");
+}
+function resolveAutoFlush(autoFlush) {
+	if (autoFlush !== true && (typeof autoFlush !== "object" || autoFlush === null)) return null;
+	let src = autoFlush === true ? {} : autoFlush;
+	let pendingPuts = src.pendingPuts;
+	let idleMs = src.idleMs;
+	if (pendingPuts === void 0 || !Number.isFinite(pendingPuts) || pendingPuts < 1) pendingPuts = 32;
+	if (idleMs === void 0 || !Number.isFinite(idleMs) || idleMs < 0) idleMs = DEFAULT_AUTO_FLUSH_IDLE_MS;
+	return {
+		pendingPuts,
+		idleMs
+	};
+}
 var IDENT_RE = /^[A-Za-z0-9_-]+$/;
 var ISSUE_KEY = "yorozu-db-sqlite";
 function reportError(log, err) {
@@ -1664,6 +1710,11 @@ function indexKeyPath(def, name) {
 	if (!idx) throw new Error(`unknown index: ${name}`);
 	return idx.keyPath;
 }
+function compareHits(a, b, rev) {
+	let c = compareIndexKey(a.indexKey, b.indexKey);
+	if (c === 0) c = compareIndexKey(a.primaryKey, b.primaryKey);
+	return rev ? -c : c;
+}
 function isBlobish(value) {
 	if (typeof Blob !== "undefined" && value instanceof Blob) return true;
 	if (typeof ArrayBuffer !== "undefined" && value instanceof ArrayBuffer) return true;
@@ -1836,6 +1887,10 @@ var SerialQueue = class {
 		this._tail = run.then(() => void 0, () => void 0);
 		return run;
 	}
+	/** Run fn without the reentrant store so timers/idle do not inherit the lock. */
+	detached(fn) {
+		return this._held.exit(fn);
+	}
 };
 var WriteGuardCollection = class {
 	name;
@@ -1895,8 +1950,10 @@ var NestedTxDb = class {
 	transact(_names, _mode, _fn) {
 		return Promise.reject(/* @__PURE__ */ new Error("nested transact is not supported"));
 	}
-	flush() {
+	flush(opts) {
 		if (this._mode.value === "r") return Promise.resolve();
+		let aborted = abortedReason(opts?.signal);
+		if (aborted !== void 0) return Promise.reject(aborted);
 		this._flushUnlocked();
 		return Promise.resolve();
 	}
@@ -1950,7 +2007,8 @@ var SqliteCollection = class {
 	_table;
 	_blobTable;
 	_indexColIds;
-	constructor(def, handle, pending, inSqlTx) {
+	_onBatchQueued;
+	constructor(def, handle, pending, inSqlTx, onBatchQueued) {
 		this.name = def.name;
 		this._def = def;
 		this._keyPath = def.keyPath;
@@ -1962,6 +2020,7 @@ var SqliteCollection = class {
 		this._table = quoteIdent(def.name);
 		this._blobTable = quoteIdent(`${def.name}__blobs`);
 		this._indexColIds = allIndexColIds(def);
+		this._onBatchQueued = onBatchQueued;
 	}
 	_colPending() {
 		return this._pending.get(this.name);
@@ -2063,6 +2122,7 @@ var SqliteCollection = class {
 		let write = await this._prepareWrite(row);
 		if ((opts?.flush ?? "now") === "batch") {
 			this._ensurePending().set(write.pk, write);
+			this._onBatchQueued();
 			return;
 		}
 		this._colPending()?.delete(write.pk);
@@ -2075,6 +2135,7 @@ var SqliteCollection = class {
 		if ((opts?.flush ?? "now") === "batch") {
 			let pending = this._ensurePending();
 			for (let write of writes) pending.set(write.pk, write);
+			this._onBatchQueued();
 			return;
 		}
 		let live = this._colPending();
@@ -2181,11 +2242,7 @@ var SqliteCollection = class {
 			if (!keysOnly && valueByPk.size > 0) this._attachBlobs(valueByPk, [...valueByPk.keys()]);
 		}
 		if (pending && pending.size > 0) hits = this._mergePending(index, bound, hits, pending);
-		hits.sort((a, b) => {
-			let c = compareIndexKey(a.indexKey, b.indexKey);
-			if (c !== 0) return c;
-			return compareIndexKey(a.primaryKey, b.primaryKey);
-		});
+		hits.sort((a, b) => compareHits(a, b, bound.direction === "rev"));
 		if (bound.limit !== void 0) hits = hits.slice(0, Math.max(0, bound.limit));
 		return hits;
 	}
@@ -2207,16 +2264,12 @@ var SqliteCollection = class {
 				value: write.row
 			});
 		}
-		out.sort((a, b) => {
-			let c = compareIndexKey(a.indexKey, b.indexKey);
-			if (c !== 0) return c;
-			return compareIndexKey(a.primaryKey, b.primaryKey);
-		});
 		return out;
 	}
 };
 var SqliteDb = class {
 	schema;
+	log;
 	_handle;
 	_collections;
 	_gated;
@@ -2228,10 +2281,14 @@ var SqliteDb = class {
 	_txView;
 	_onClose;
 	_closed = false;
-	constructor(schema, handle, onClose) {
+	_autoFlush;
+	_idleHandle = null;
+	constructor(schema, handle, onClose, autoFlush, log) {
 		this.schema = schema;
 		this._handle = handle;
 		this._onClose = onClose;
+		this._autoFlush = autoFlush;
+		this.log = log;
 		this._collections = /* @__PURE__ */ new Map();
 		this._gated = /* @__PURE__ */ new Map();
 		this._txView = new NestedTxDb(this, (name) => {
@@ -2240,7 +2297,7 @@ var SqliteDb = class {
 			return col;
 		}, () => this._flushPending(), this._txMode);
 		for (let def of schema.collections) {
-			let col = new SqliteCollection(def, handle, this._pending, this._inSqlTx);
+			let col = new SqliteCollection(def, handle, this._pending, this._inSqlTx, () => this._onBatchQueued());
 			this._collections.set(def.name, col);
 			this._gated.set(def.name, new GatedCollection(col, this._lock));
 		}
@@ -2273,12 +2330,18 @@ var SqliteDb = class {
 			}
 		}));
 	}
-	flush() {
+	flush(opts) {
+		let aborted = abortedReason(opts?.signal);
+		if (aborted !== void 0) return Promise.reject(aborted);
 		return this._lock.with(async () => {
+			if (this._closed) return;
+			let aborted2 = abortedReason(opts?.signal);
+			if (aborted2 !== void 0) throw aborted2;
 			this._flushPending();
 		});
 	}
 	async close() {
+		this._cancelIdle();
 		if (this._closed) return;
 		this._closed = true;
 		try {
@@ -2288,13 +2351,41 @@ var SqliteDb = class {
 			this._onClose();
 		}
 	}
+	_pendingDistinct() {
+		let n = 0;
+		for (let rows of this._pending.values()) n += rows.size;
+		return n;
+	}
+	_cancelIdle() {
+		this._idleHandle?.cancel();
+		this._idleHandle = null;
+	}
+	_armIdle(timeout) {
+		this._cancelIdle();
+		this._idleHandle = this._lock.detached(() => requestIdle(() => {
+			this._idleHandle = null;
+			if (this._closed) return;
+			this.flush({ reason: "idle" }).catch((err) => reportError(this.log, err));
+		}, { timeout }));
+	}
+	_onBatchQueued() {
+		if (!this._autoFlush) return;
+		if (this._pendingDistinct() >= this._autoFlush.pendingPuts) {
+			this._armIdle(0);
+			return;
+		}
+		if (!this._idleHandle) this._armIdle(this._autoFlush.idleMs);
+	}
 	_flushPending() {
 		let snapshot = [];
 		for (let [name, rows] of this._pending) {
 			if (rows.size === 0) continue;
 			snapshot.push([name, [...rows.values()]]);
 		}
-		if (snapshot.length === 0) return;
+		if (snapshot.length === 0) {
+			this._cancelIdle();
+			return;
+		}
 		let run = () => {
 			for (let [name, writes] of snapshot) {
 				let col = this._collections.get(name);
@@ -2309,17 +2400,20 @@ var SqliteDb = class {
 			if (!live) continue;
 			for (let write of writes) if (live.get(write.pk) === write) live.delete(write.pk);
 		}
+		if (this._pendingDistinct() === 0) this._cancelIdle();
 	}
 };
 var SqliteDriver = class {
 	log;
 	_filename;
 	_native;
+	_autoFlush;
 	_conns = /* @__PURE__ */ new Set();
 	constructor(opts) {
 		this.log = makeLog(opts.log ?? makeSilentLog(), ISSUE_KEY);
 		this._filename = opts.filename;
 		this._native = opts.native ?? import_lib.default;
+		this._autoFlush = resolveAutoFlush(opts.autoFlush);
 	}
 	async open(schema) {
 		let raw;
@@ -2334,7 +2428,7 @@ var SqliteDriver = class {
 			applySchema(handle, schema);
 			let db = new SqliteDb(schema, handle, () => {
 				this._conns.delete(db);
-			});
+			}, this._autoFlush, this.log);
 			this._conns.add(db);
 			return db;
 		} catch (err) {

package/package.json

@@ -1,12 +1,13 @@
 {
     "name": "@yorozu/db-sqlite",
     "type": "module",
-    "version": "0.5.6",
+    "version": "1.0.31",
     "description": "better-sqlite3 thin wrapper + driver for @yorozu/db",
     "license": "MIT",
     "dependencies": {
-        "@yorozu/db": "^0.5.6",
-        "@yorozu/log": "^0.5.6",
+        "@yorozu/db": "^1.0.31",
+        "@yorozu/log": "^1.0.31",
+        "@yorozu/utils": "^1.0.31",
         "better-sqlite3": "12.11.1"
     },
     "exports": {