@cavulsqa/reactive-db 0.2.0 → 1.0.0

package/README.md

@@ -2,17 +2,34 @@
 
 Framework-agnostic primitives for keeping a UI in step with a local SQLite database.
 
-- `createChangeBus` — publish and subscribe to per-table change events (`TableChangeEvent`).
+- `createChangeBus<DB>` — publish and subscribe to per-table change events (`TableChangeEvent`).
+  Pass the schema and table names are checked against it (`TableName<DB>`); subscribe to
+  `ALL_TABLES` for everything.
+- `hashQueryKey` — a stable string for a `QueryKey` (an array). Identity comes from the arguments,
+  not from a name the caller invents, so two call sites only share a request when they are asking
+  the same question. A function or symbol in a key throws rather than hashing alike.
 - `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.
+- `createReactiveDb<DB>` — wraps a Kysely instance so writes announce the tables they touched;
+  `executeWithEvent` does the same for a single query. A transaction reports **what it actually
+  did** per table, not a blanket `"bulk"` — otherwise a query filtering on `refetchOn` ignores
+  precisely the batched writes that matter.
 - `createQueryMetrics` — query duration, error, and cache-hit counters.
 - `ReactiveQueryOptions`, `calcRetryDelay`, `noopMetrics` — the option contract and retry policy a
   framework binding builds on.
 
+## Table names are the one argument that fails silently
+
+Misspell one in `tables` and the query subscribes to a table nobody writes to: no error, no warning,
+a screen that is stale forever. So pass the schema:
+
+```ts
+const bus = createChangeBus<Database>();
+bus.emit("sale_ordr", "insert"); // ← a type error, with a "did you mean" suggestion
+```
+
 `kysely` is an **optional** peer: it is imported for types only. Marking it optional keeps npm
 from auto-installing a kysely major that `@cavulsqa/mobile-db` cannot use - which otherwise
 resolves the whole tree onto an older mobile-db.

package/dist/index.d.mts

@@ -1,5 +1,15 @@
 import { Kysely } from "kysely";
 //#region src/events.d.ts
+/**
+ * A table in the schema, when one is known.
+ *
+ * Defaults to `string` so a caller can skip the parameter, but passing the schema is the point: a
+ * table name is the one argument in this library that fails silently. Misspell it in `tables` and
+ * the query simply never refetches - no error, no warning, a screen that is stale forever.
+ */
+type TableName<DB = Record<string, unknown>> = keyof DB & string;
+/** Every table, for a listener that wants the whole bus rather than named tables. */
+declare const ALL_TABLES = "*";
 type ChangeType = "insert" | "update" | "delete" | "bulk";
 interface TableChangeMeta {
   affectedRows?: number;
@@ -11,11 +21,22 @@ 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;
+interface ChangeBus<DB = Record<string, unknown>> {
+  emit: (table: TableName<DB>, type: ChangeType, meta?: TableChangeMeta) => void;
+  on: (tables: (TableName<DB> | typeof ALL_TABLES)[], listener: (event: TableChangeEvent) => void) => () => void;
 }
-declare function createChangeBus(): ChangeBus;
+declare function createChangeBus<DB = Record<string, unknown>>(): ChangeBus<DB>;
+//#endregion
+//#region src/queryKey.d.ts
+type QueryKey = readonly unknown[];
+/**
+ * A stable string for a key array.
+ *
+ * The identity has to come from the arguments, not from a name the caller invents: two mounted
+ * queries sharing an identity await one request and share its result, so `"order-detail"` used by
+ * two detail pages showed one page the other page's order. `["order-detail", id]` cannot.
+ */
+declare function hashQueryKey(key: QueryKey): string;
 //#endregion
 //#region src/resultCache.d.ts
 interface ResultCache {
@@ -36,15 +57,22 @@ interface VisibilityGate {
 declare function createVisibilityGate(): VisibilityGate;
 //#endregion
 //#region src/mutationProxy.d.ts
+type EmitChangeFn<DB> = (table: TableName<DB>, changeType: ChangeType, meta?: {
+  affectedRows?: number;
+}) => void;
 interface ReactiveDbDeps<DB> {
   getDb: () => Kysely<DB>;
-  emitChange: (table: string, changeType: ChangeType, meta?: {
-    affectedRows?: number;
-  }) => void;
+  emitChange: EmitChangeFn<DB>;
 }
 declare function affectedRowsOf(result: unknown): number | null;
+/**
+ * A Kysely that announces the tables it wrote to.
+ *
+ * The database is resolved per access rather than captured, so this can be created at module scope
+ * before anything has opened it.
+ */
 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>;
+declare function executeWithEvent<T, DB>(emitChange: EmitChangeFn<DB>, table: TableName<DB>, changeType: ChangeType, executor: () => Promise<T>): Promise<T>;
 //#endregion
 //#region src/queryMetrics.d.ts
 interface QueryMetric {
@@ -81,9 +109,11 @@ interface CreateQueryMetricsOptions {
 declare function createQueryMetrics(options?: CreateQueryMetricsOptions): QueryMetricsRecorder;
 //#endregion
 //#region src/useReactiveQuery.d.ts
-interface ReactiveQueryOptions<T = unknown> {
-  tables: string[];
-  queryKey: string;
+interface ReactiveQueryOptions<T = unknown, DB = Record<string, unknown>> {
+  /** Every table the query function reads. Under-list one and the screen goes stale in silence. */
+  tables: TableName<DB>[];
+  /** Identity, taken from the arguments the query reads. See `hashQueryKey`. */
+  queryKey: QueryKey;
   debounce?: number;
   debug?: boolean;
   refetchOn?: TableChangeEvent["type"][];
@@ -114,8 +144,8 @@ interface QueryMetrics {
   incrementListeners(): void;
   decrementListeners(): void;
 }
-type OnTableChangeFn = (tables: string[], callback: (event: TableChangeEvent) => void) => () => void;
+type OnTableChangeFn<DB = Record<string, unknown>> = (tables: (TableName<DB> | typeof ALL_TABLES)[], 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 };
+export { ALL_TABLES, ChangeBus, ChangeDecision, ChangeType, CreateQueryMetricsOptions, EmitChangeFn, type OnTableChangeFn, QueryKey, QueryMetric, type QueryMetrics, QueryMetricsRecorder, QueryMetricsState, ReactiveDbDeps, type ReactiveQueryOptions, ResultCache, ShowDecision, TableChangeEvent, TableChangeMeta, TableName, VisibilityGate, affectedRowsOf, calcRetryDelay, createChangeBus, createQueryMetrics, createReactiveDb, createResultCache, createVisibilityGate, executeWithEvent, hashQueryKey, noopMetrics };

package/dist/index.mjs

@@ -1,4 +1,6 @@
 //#region src/events.ts
+/** Every table, for a listener that wants the whole bus rather than named tables. */
+const ALL_TABLES = "*";
 function createChangeBus() {
 	const listeners = /* @__PURE__ */ new Set();
 	return {
@@ -23,6 +25,31 @@ function createChangeBus() {
 	};
 }
 //#endregion
+//#region src/queryKey.ts
+/**
+* A stable string for a key array.
+*
+* The identity has to come from the arguments, not from a name the caller invents: two mounted
+* queries sharing an identity await one request and share its result, so `"order-detail"` used by
+* two detail pages showed one page the other page's order. `["order-detail", id]` cannot.
+*/
+function hashQueryKey(key) {
+	return JSON.stringify(key, (_field, value) => {
+		if (typeof value === "function" || typeof value === "symbol") throw new Error(`[reactive-db] a query key cannot contain a ${typeof value}: it has no stable serialisation, so two different queries would hash alike and share each other's results. Key on the values the query reads instead.`);
+		return isPlainObject(value) ? sortFields(value) : value;
+	});
+}
+function isPlainObject(value) {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === Object.prototype || prototype === null;
+}
+function sortFields(value) {
+	const sorted = {};
+	for (const field of Object.keys(value).sort()) sorted[field] = value[field];
+	return sorted;
+}
+//#endregion
 //#region src/resultCache.ts
 function createResultCache(maxEntries) {
 	const entries = /* @__PURE__ */ new Map();
@@ -77,12 +104,30 @@ const MUTATION_CHANGE_TYPE = {
 	updateTable: "update",
 	deleteFrom: "delete"
 };
+const EXECUTORS = /* @__PURE__ */ new Set([
+	"execute",
+	"executeTakeFirst",
+	"executeTakeFirstOrThrow"
+]);
 const ROW_COUNT_KEYS = [
 	"numUpdatedRows",
 	"numDeletedRows",
 	"numInsertedOrUpdatedRows",
 	"numAffectedRows"
 ];
+function isMutationMethod(prop) {
+	return typeof prop === "string" && prop in MUTATION_CHANGE_TYPE;
+}
+/** Kysely's builders are structurally huge and reached dynamically, so reads are narrowed by hand. */
+function read(target, prop) {
+	return Reflect.get(target, prop);
+}
+function isFunction(value) {
+	return typeof value === "function";
+}
+function hasExecute(value) {
+	return typeof value === "object" && value !== null && isFunction(read(value, "execute"));
+}
 function affectedRowsOf(result) {
 	const rows = Array.isArray(result) ? result : result == null ? [] : [result];
 	let counted = null;
@@ -97,78 +142,80 @@ function affectedRowsOf(result) {
 	}
 	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) {
+function wrapBuilder(builder, table, changeType, notify) {
 	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);
+		const value = read(target, prop);
+		if (!isFunction(value)) return value;
+		if (typeof prop === "string" && EXECUTORS.has(prop)) return async (...args) => {
+			const result = await value.apply(target, args);
+			notify(table, changeType, result);
+			return result;
+		};
 		return (...args) => {
 			const result = value.apply(target, args);
-			if (result && typeof result.execute === "function" && result !== target) return wrapBuilder(result, table, changeType, onExecuted);
-			return result;
+			return hasExecute(result) && result !== target ? wrapBuilder(result, table, changeType, notify) : result;
 		};
 	} });
 }
-function createMutationProxy(db, onExecuted) {
+function interceptMutations(db, notify) {
 	return new Proxy(db, { get(target, prop) {
-		const value = target[prop];
-		if (prop === "insertInto" || prop === "updateTable" || prop === "deleteFrom") return (...args) => {
+		const value = read(target, prop);
+		if (isMutationMethod(prop) && isFunction(value)) return (...args) => {
 			const table = args[0];
-			const builder = value.apply(target, args);
-			const changeType = MUTATION_CHANGE_TYPE[prop];
-			return wrapBuilder(builder, table, changeType, onExecuted);
+			return wrapBuilder(value.apply(target, args), table, MUTATION_CHANGE_TYPE[prop], notify);
 		};
-		if (typeof value === "function") return value.bind(target);
-		return value;
+		return isFunction(value) ? value.bind(target) : value;
 	} });
 }
+/**
+* A transaction reports what it actually did, per table.
+*
+* It used to report `"bulk"` for everything, which any query filtering on `refetchOn` then dropped
+* on the floor - and since batched writes are the ones that run in transactions, a screen watching
+* for inserts missed precisely the writes that mattered.
+*/
 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);
+		const value = read(target, prop);
+		if (!isFunction(value)) return value;
+		if (prop === "execute") return async (callback) => {
+			const touched = /* @__PURE__ */ new Map();
+			const result = await value.call(target, (trx) => callback(interceptMutations(trx, (table, changeType) => {
+				const seen = touched.get(table) ?? /* @__PURE__ */ new Set();
+				seen.add(changeType);
+				touched.set(table, seen);
 			})));
-			for (const table of touchedTables) emitChange(table, "bulk");
+			for (const [table, changeTypes] of touched) for (const changeType of changeTypes) emitChange(table, changeType);
 			return result;
 		};
-		if (typeof value === "function") return (...args) => {
+		return (...args) => {
 			const result = value.apply(target, args);
-			if (result && typeof result.execute === "function") return wrapTransactionBuilder(result, emitChange);
-			return result;
+			return hasExecute(result) ? wrapTransactionBuilder(result, emitChange) : result;
 		};
-		return value;
 	} });
 }
+/**
+* A Kysely that announces the tables it wrote to.
+*
+* The database is resolved per access rather than captured, so this can be created at module scope
+* before anything has opened it.
+*/
 function createReactiveDb(deps) {
 	const { getDb, emitChange } = deps;
-	function emitMutationEvent(table, changeType, result) {
+	const notify = (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 value = read(db, prop);
+		if (isMutationMethod(prop) && isFunction(value)) 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);
+			return wrapBuilder(value.apply(db, args), table, MUTATION_CHANGE_TYPE[prop], notify);
 		};
-		if (typeof value === "function") return value.bind(db);
-		return value;
+		if (prop === "transaction" && isFunction(value)) return () => wrapTransactionBuilder(value.apply(db, []), emitChange);
+		return isFunction(value) ? value.bind(db) : value;
 	} });
 }
 async function executeWithEvent(emitChange, table, changeType, executor) {
@@ -271,4 +318,4 @@ const noopMetrics = {
 	decrementListeners() {}
 };
 //#endregion
-export { affectedRowsOf, calcRetryDelay, createChangeBus, createQueryMetrics, createReactiveDb, createResultCache, createVisibilityGate, executeWithEvent, noopMetrics };
+export { ALL_TABLES, affectedRowsOf, calcRetryDelay, createChangeBus, createQueryMetrics, createReactiveDb, createResultCache, createVisibilityGate, executeWithEvent, hashQueryKey, noopMetrics };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cavulsqa/reactive-db",
-  "version": "0.2.0",
+  "version": "1.0.0",
   "description": "Framework-agnostic reactive query primitives: table-change bus, result cache, visibility gate, mutation proxy, query metrics.",
   "keywords": [
     "cache",
@@ -31,10 +31,10 @@
     "access": "public"
   },
   "devDependencies": {
-    "@types/node": "^26.1.1",
+    "@types/node": "^24.12.2",
     "bumpp": "^11.1.0",
     "kysely": "^0.29.5",
-    "typescript": "^7.0.2",
+    "typescript": "^5.9.3",
     "vite": "npm:@voidzero-dev/vite-plus-core@0.3.0",
     "vite-plus": "0.3.0"
   },