@cavulsqa/reactive-db 0.1.0

package/README.md

@@ -0,0 +1,24 @@
+# @cavulsqa/reactive-db
+
+Framework-agnostic primitives for keeping a UI in step with a local SQLite database.
+
+- `createChangeBus` — publish and subscribe to per-table change events (`TableChangeEvent`).
+- `createResultCache` — bounded, keyed result cache with staleness handling. A standalone
+  primitive: `@cavulsqa/reactive-vue` does not use it, so nothing shares results between call
+  sites unless you build that on top.
+- `createVisibilityGate` — suppresses refetches while a view is hidden.
+- `createReactiveDb` — wraps a Kysely instance so writes announce the tables they touched;
+  `executeWithEvent` does the same for a single query.
+- `createQueryMetrics` — query duration, error, and cache-hit counters.
+- `ReactiveQueryOptions`, `calcRetryDelay`, `noopMetrics` — the option contract and retry policy a
+  framework binding builds on.
+
+**No framework dependency.** There is no `vue` import; `isVisible?: { value: boolean }` is a
+structural stand-in for a ref, so any framework (or none) can drive it. Vue bindings live in
+[`@cavulsqa/reactive-vue`](../reactive-vue).
+
+## Install
+
+```bash
+vp install @cavulsqa/reactive-db
+```

package/dist/index.d.mts

@@ -0,0 +1,121 @@
+import { Kysely } from "kysely";
+//#region src/events.d.ts
+type ChangeType = "insert" | "update" | "delete" | "bulk";
+interface TableChangeMeta {
+  affectedRows?: number;
+  affectedIds?: (string | number)[];
+  transactionId?: string;
+  timestamp?: number;
+}
+interface TableChangeEvent extends TableChangeMeta {
+  table: string;
+  type: ChangeType;
+}
+interface ChangeBus {
+  emit: (table: string, type: ChangeType, meta?: TableChangeMeta) => void;
+  on: (tables: string[], listener: (event: TableChangeEvent) => void) => () => void;
+}
+declare function createChangeBus(): ChangeBus;
+//#endregion
+//#region src/resultCache.d.ts
+interface ResultCache {
+  get(key: string): unknown;
+  set(key: string, value: unknown, tables: string[]): void;
+  invalidateTable(table: string): void;
+  clear(): void;
+}
+declare function createResultCache(maxEntries: number): ResultCache;
+//#endregion
+//#region src/visibilityGate.d.ts
+type ChangeDecision = "refetch" | "defer";
+type ShowDecision = "refetch" | "idle";
+interface VisibilityGate {
+  recordChange(isVisible: boolean): ChangeDecision;
+  recordVisible(): ShowDecision;
+}
+declare function createVisibilityGate(): VisibilityGate;
+//#endregion
+//#region src/mutationProxy.d.ts
+interface ReactiveDbDeps<DB> {
+  getDb: () => Kysely<DB>;
+  emitChange: (table: string, changeType: ChangeType, meta?: {
+    affectedRows?: number;
+  }) => void;
+}
+declare function affectedRowsOf(result: unknown): number | null;
+declare function createReactiveDb<DB>(deps: ReactiveDbDeps<DB>): Kysely<DB>;
+declare function executeWithEvent<T>(emitChange: ReactiveDbDeps<unknown>["emitChange"], table: string, changeType: ChangeType, executor: () => Promise<T>): Promise<T>;
+//#endregion
+//#region src/queryMetrics.d.ts
+interface QueryMetric {
+  count: number;
+  totalTime: number;
+  avgTime: number;
+  lastTime: number;
+  lastSeen: number;
+}
+interface QueryMetricsState {
+  queries: Record<string, QueryMetric>;
+  errors: Record<string, number>;
+  cacheHits: number;
+  refetchesByTable: Record<string, number>;
+  activeListeners: number;
+  startTime: number;
+  isDevToolsOpen: boolean;
+}
+interface QueryMetricsRecorder {
+  recordQuery(queryKey: string, durationMs: number): void;
+  recordError(queryKey: string): void;
+  recordCacheHit(): void;
+  recordRefetch(table: string): void;
+  incrementListeners(): void;
+  decrementListeners(): void;
+  reset(): void;
+  getState(): QueryMetricsState;
+  toggleDevTools(isOpen?: boolean): void;
+}
+interface CreateQueryMetricsOptions {
+  maxEntries?: number;
+  wrapState?: (state: QueryMetricsState) => QueryMetricsState;
+}
+declare function createQueryMetrics(options?: CreateQueryMetricsOptions): QueryMetricsRecorder;
+//#endregion
+//#region src/useReactiveQuery.d.ts
+interface ReactiveQueryOptions<T = unknown> {
+  tables: string[];
+  queryKey: string;
+  debounce?: number;
+  debug?: boolean;
+  refetchOn?: TableChangeEvent["type"][];
+  shouldRefetch?: (event: TableChangeEvent) => boolean;
+  cacheTime?: number;
+  staleWhileRevalidate?: boolean;
+  enabled?: boolean;
+  /**
+   * Run the query once on mount. Defaults to true. Set false when a caller-owned
+   * watcher already drives the initial load, so the mount fetch would only add a
+   * redundant run. Unlike `enabled: false`, the table-change subscription stays.
+   */
+  fetchOnMount?: boolean;
+  onSuccess?: (data: T) => void;
+  onError?: (error: Error) => void;
+  cancelOnUnmount?: boolean;
+  retry?: number | false;
+  retryDelay?: number | ((attempt: number) => number);
+  isVisible?: {
+    value: boolean;
+  };
+}
+interface QueryMetrics {
+  recordQuery(queryKey: string, durationMs: number): void;
+  recordError(queryKey: string): void;
+  recordCacheHit(): void;
+  recordRefetch(table: string): void;
+  incrementListeners(): void;
+  decrementListeners(): void;
+}
+type OnTableChangeFn = (tables: string[], callback: (event: TableChangeEvent) => void) => () => void;
+declare function calcRetryDelay(attempt: number, retryDelay?: number | ((attempt: number) => number)): number;
+declare const noopMetrics: QueryMetrics;
+//#endregion
+export { ChangeBus, ChangeDecision, ChangeType, CreateQueryMetricsOptions, type OnTableChangeFn, QueryMetric, type QueryMetrics, QueryMetricsRecorder, QueryMetricsState, ReactiveDbDeps, type ReactiveQueryOptions, ResultCache, ShowDecision, TableChangeEvent, TableChangeMeta, VisibilityGate, affectedRowsOf, calcRetryDelay, createChangeBus, createQueryMetrics, createReactiveDb, createResultCache, createVisibilityGate, executeWithEvent, noopMetrics };

package/dist/index.mjs

@@ -0,0 +1,274 @@
+//#region src/events.ts
+function createChangeBus() {
+	const listeners = /* @__PURE__ */ new Set();
+	return {
+		emit(table, type, meta) {
+			const event = {
+				table,
+				type,
+				...meta
+			};
+			for (const listener of listeners) if (listener.tables.has("*") || listener.tables.has(table)) listener.fn(event);
+		},
+		on(tables, listener) {
+			const entry = {
+				tables: new Set(tables),
+				fn: listener
+			};
+			listeners.add(entry);
+			return () => {
+				listeners.delete(entry);
+			};
+		}
+	};
+}
+//#endregion
+//#region src/resultCache.ts
+function createResultCache(maxEntries) {
+	const entries = /* @__PURE__ */ new Map();
+	return {
+		get(key) {
+			const entry = entries.get(key);
+			if (entry === void 0) return void 0;
+			entries.delete(key);
+			entries.set(key, entry);
+			return entry.value;
+		},
+		set(key, value, tables) {
+			if (entries.has(key)) entries.delete(key);
+			entries.set(key, {
+				value,
+				tables
+			});
+			while (entries.size > maxEntries) {
+				const oldest = entries.keys().next().value;
+				entries.delete(oldest);
+			}
+		},
+		invalidateTable(table) {
+			for (const [key, entry] of entries) if (entry.tables.includes(table)) entries.delete(key);
+		},
+		clear() {
+			entries.clear();
+		}
+	};
+}
+//#endregion
+//#region src/visibilityGate.ts
+function createVisibilityGate() {
+	let deferred = false;
+	return {
+		recordChange(isVisible) {
+			if (isVisible) return "refetch";
+			deferred = true;
+			return "defer";
+		},
+		recordVisible() {
+			if (!deferred) return "idle";
+			deferred = false;
+			return "refetch";
+		}
+	};
+}
+//#endregion
+//#region src/mutationProxy.ts
+const MUTATION_CHANGE_TYPE = {
+	insertInto: "insert",
+	updateTable: "update",
+	deleteFrom: "delete"
+};
+const ROW_COUNT_KEYS = [
+	"numUpdatedRows",
+	"numDeletedRows",
+	"numInsertedOrUpdatedRows",
+	"numAffectedRows"
+];
+function affectedRowsOf(result) {
+	const rows = Array.isArray(result) ? result : result == null ? [] : [result];
+	let counted = null;
+	for (const row of rows) {
+		if (!row || typeof row !== "object") continue;
+		for (const key of ROW_COUNT_KEYS) {
+			const value = row[key];
+			if (value === void 0 || value === null) continue;
+			counted = (counted ?? 0) + Number(value);
+			break;
+		}
+	}
+	return counted ?? (rows.length > 0 ? rows.length : null);
+}
+function wrapExecutor(executor, table, changeType, onExecuted) {
+	return async () => {
+		const result = await executor();
+		onExecuted(table, changeType, result);
+		return result;
+	};
+}
+function wrapBuilder(builder, table, changeType, onExecuted) {
+	return new Proxy(builder, { get(target, prop) {
+		const value = target[prop];
+		if (typeof value !== "function") return value;
+		if (prop === "execute" || prop === "executeTakeFirst" || prop === "executeTakeFirstOrThrow") return wrapExecutor(value.bind(target), table, changeType, onExecuted);
+		return (...args) => {
+			const result = value.apply(target, args);
+			if (result && typeof result.execute === "function" && result !== target) return wrapBuilder(result, table, changeType, onExecuted);
+			return result;
+		};
+	} });
+}
+function createMutationProxy(db, onExecuted) {
+	return new Proxy(db, { get(target, prop) {
+		const value = target[prop];
+		if (prop === "insertInto" || prop === "updateTable" || prop === "deleteFrom") return (...args) => {
+			const table = args[0];
+			const builder = value.apply(target, args);
+			const changeType = MUTATION_CHANGE_TYPE[prop];
+			return wrapBuilder(builder, table, changeType, onExecuted);
+		};
+		if (typeof value === "function") return value.bind(target);
+		return value;
+	} });
+}
+function wrapTransactionBuilder(txBuilder, emitChange) {
+	return new Proxy(txBuilder, { get(target, prop) {
+		const value = target[prop];
+		if (prop === "execute" && typeof value === "function") return async (callback) => {
+			const touchedTables = /* @__PURE__ */ new Set();
+			const result = await value.call(target, (trx) => callback(createMutationProxy(trx, (table) => {
+				touchedTables.add(table);
+			})));
+			for (const table of touchedTables) emitChange(table, "bulk");
+			return result;
+		};
+		if (typeof value === "function") return (...args) => {
+			const result = value.apply(target, args);
+			if (result && typeof result.execute === "function") return wrapTransactionBuilder(result, emitChange);
+			return result;
+		};
+		return value;
+	} });
+}
+function createReactiveDb(deps) {
+	const { getDb, emitChange } = deps;
+	function emitMutationEvent(table, changeType, result) {
+		const affectedRows = affectedRowsOf(result);
+		if (affectedRows === 0) return;
+		emitChange(table, changeType, affectedRows === null ? void 0 : { affectedRows });
+	}
+	return new Proxy({}, { get(_target, prop) {
+		const db = getDb();
+		const value = db[prop];
+		if (prop === "insertInto" || prop === "updateTable" || prop === "deleteFrom") return (...args) => {
+			const table = args[0];
+			const builder = value.apply(db, args);
+			const changeType = MUTATION_CHANGE_TYPE[prop];
+			return wrapBuilder(builder, table, changeType, emitMutationEvent);
+		};
+		if (prop === "transaction") return () => {
+			return wrapTransactionBuilder(value.apply(db, []), emitChange);
+		};
+		if (typeof value === "function") return value.bind(db);
+		return value;
+	} });
+}
+async function executeWithEvent(emitChange, table, changeType, executor) {
+	const result = await executor();
+	emitChange(table, changeType);
+	return result;
+}
+//#endregion
+//#region src/queryMetrics.ts
+const DEFAULT_MAX_ENTRIES = 200;
+function createQueryMetrics(options = {}) {
+	const maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES;
+	const state = (options.wrapState ?? ((s) => s))({
+		queries: {},
+		errors: {},
+		cacheHits: 0,
+		refetchesByTable: {},
+		activeListeners: 0,
+		startTime: Date.now(),
+		isDevToolsOpen: false
+	});
+	function pruneQueries() {
+		const entries = Object.entries(state.queries);
+		if (entries.length <= maxEntries) return;
+		const expired = entries.sort(([, a], [, b]) => a.lastSeen - b.lastSeen).slice(0, entries.length - maxEntries);
+		for (const [key] of expired) {
+			delete state.queries[key];
+			delete state.errors[key];
+		}
+	}
+	function pruneRecord(record) {
+		const keys = Object.keys(record);
+		if (keys.length <= maxEntries) return;
+		for (const key of keys.slice(0, keys.length - maxEntries)) delete record[key];
+	}
+	return {
+		recordQuery(queryKey, durationMs) {
+			const now = Date.now();
+			if (!state.queries[queryKey]) state.queries[queryKey] = {
+				count: 0,
+				totalTime: 0,
+				avgTime: 0,
+				lastTime: 0,
+				lastSeen: now
+			};
+			const metric = state.queries[queryKey];
+			metric.count++;
+			metric.totalTime += durationMs;
+			metric.avgTime = metric.totalTime / metric.count;
+			metric.lastTime = durationMs;
+			metric.lastSeen = now;
+			pruneQueries();
+		},
+		recordError(queryKey) {
+			state.errors[queryKey] = (state.errors[queryKey] ?? 0) + 1;
+			pruneRecord(state.errors);
+		},
+		recordCacheHit() {
+			state.cacheHits++;
+		},
+		recordRefetch(table) {
+			state.refetchesByTable[table] = (state.refetchesByTable[table] ?? 0) + 1;
+			pruneRecord(state.refetchesByTable);
+		},
+		incrementListeners() {
+			state.activeListeners++;
+		},
+		decrementListeners() {
+			if (state.activeListeners > 0) state.activeListeners--;
+		},
+		reset() {
+			state.queries = {};
+			state.errors = {};
+			state.cacheHits = 0;
+			state.refetchesByTable = {};
+			state.startTime = Date.now();
+		},
+		getState() {
+			return state;
+		},
+		toggleDevTools(isOpen) {
+			state.isDevToolsOpen = isOpen ?? !state.isDevToolsOpen;
+		}
+	};
+}
+//#endregion
+//#region src/useReactiveQuery.ts
+const DEFAULT_RETRY_BASE = 1e3;
+function calcRetryDelay(attempt, retryDelay) {
+	if (typeof retryDelay === "function") return retryDelay(attempt);
+	if (typeof retryDelay === "number") return retryDelay;
+	return DEFAULT_RETRY_BASE * Math.pow(2, attempt);
+}
+const noopMetrics = {
+	recordQuery() {},
+	recordError() {},
+	recordCacheHit() {},
+	recordRefetch() {},
+	incrementListeners() {},
+	decrementListeners() {}
+};
+//#endregion
+export { affectedRowsOf, calcRetryDelay, createChangeBus, createQueryMetrics, createReactiveDb, createResultCache, createVisibilityGate, executeWithEvent, noopMetrics };

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@cavulsqa/reactive-db",
+  "version": "0.1.0",
+  "description": "Framework-agnostic reactive query primitives: table-change bus, result cache, visibility gate, mutation proxy, query metrics.",
+  "keywords": [
+    "cache",
+    "offline-first",
+    "query",
+    "reactive",
+    "sqlite"
+  ],
+  "homepage": "https://github.com/aybinv7/cavulsqa/tree/main/packages/reactive-db#readme",
+  "bugs": {
+    "url": "https://github.com/aybinv7/cavulsqa/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aybinv7/cavulsqa.git",
+    "directory": "packages/reactive-db"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "test": "vp test",
+    "check": "vp check",
+    "prepublishOnly": "vp run build"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.1",
+    "bumpp": "^11.1.0",
+    "kysely": "^0.28.9",
+    "typescript": "^7.0.2",
+    "vite": "catalog:",
+    "vite-plus": "catalog:"
+  },
+  "peerDependencies": {
+    "kysely": ">=0.28"
+  },
+  "peerDependenciesMeta": {
+    "kysely": {
+      "optional": true
+    }
+  }
+}