@cavulsqa/reactive-vue 0.1.0

package/README.md

@@ -0,0 +1,108 @@
+# @cavulsqa/reactive-vue
+
+Vue bindings for [`@cavulsqa/reactive-db`](../reactive-db). This is the layer you would otherwise
+copy between apps.
+
+- `createReactiveQuery(deps)` — returns `useReactiveQuery`, `useStructuralQuery`, and
+  `useStaticQuery`, bound to Vue's lifecycle: fetch on mount, refetch on table change (debounced),
+  in-flight deduplication by query key, retry with backoff, stale-while-revalidate, a per-instance
+  cache window, cancel on unmount, and a deferred first read via a reactive `enabled`.
+- `uniqueQueryKey(prefix)` — a key that is never shared, so a query is never deduplicated against
+  another.
+- An injectable `logger`, so failures reach your error service rather than only the console.
+- `createVueQueryMetrics()` — the recorder with its state in `reactive()`, plus a `useQueryMetrics`
+  composable of derived counters for a dev-tools panel.
+- `@cavulsqa/reactive-vue/framework7` — `providePageVisibility()` / `usePageVisibility()`, which
+  track whether the surrounding page is on screen so a background tab stops refetching. Framework7
+  page events and `.page` by default; both are options, so another router can reuse it.
+
+Nothing in the base entry knows about Framework7. The visibility adapter is a separate subpath you
+opt into.
+
+## Why a factory
+
+The change bus and the metrics recorder are app-owned singletons — writes have to emit on the same
+bus the queries listen to. Rather than have the package own a global, you pass them in once:
+
+```ts
+import { createChangeBus, createReactiveDb } from "@cavulsqa/reactive-db";
+import { createReactiveQuery, createVueQueryMetrics } from "@cavulsqa/reactive-vue";
+import { usePageVisibility } from "@cavulsqa/reactive-vue/framework7";
+
+const bus = createChangeBus();
+const metrics = createVueQueryMetrics();
+
+export const rdb = createReactiveDb<Database>({
+  getDb: () => dbService.getDb(),
+  emitChange: bus.emit,
+});
+
+export const { useReactiveQuery, useStructuralQuery, useStaticQuery } = createReactiveQuery({
+  onTableChange: bus.on,
+  metrics: metrics.recorder,
+  useVisibility: usePageVisibility,
+});
+
+export const { useQueryMetrics } = metrics;
+```
+
+Then, at a call site:
+
+```ts
+const { data, loading, error, refetch } = useReactiveQuery(
+  () => rdb.selectFrom("sale_order").selectAll().execute(),
+  { tables: ["sale_order"], queryKey: uniqueQueryKey("sale_order:list") },
+);
+```
+
+`metrics` defaults to a no-op recorder. `useVisibility` defaults to always-visible — without an
+adapter, a screen the user cannot see still refetches. `logger` defaults to the console; pass your
+app's error service and a failed query lands where every other failure does:
+
+```ts
+createReactiveQuery({
+  onTableChange: bus.on,
+  logger: { debug: noop, warn: reportWarning, error: reportError },
+});
+```
+
+## queryKey is an identity, not a label
+
+Two mounted queries sharing a `queryKey` await a single request and share its result. That is
+correct for the same list rendered twice, and wrong for two different queries that happen to be
+named alike — the second is handed the first's rows.
+
+So: `uniqueQueryKey("sale_order:list")` unless sharing is the point, in which case use a stable
+literal. As a backstop, mounting the same key against different `tables` logs a warning; pass
+`warnOnKeyConflict: false` to silence it.
+
+## What this does not do
+
+`cacheTime` is a **per-instance** revalidation window: it suppresses a refetch that a table change
+would otherwise trigger, on that one query. It is not a shared cache — two screens running the same
+query each hold their own result, and neither reads the other's.
+
+`@cavulsqa/reactive-db` exports `createResultCache`, which is a real bounded keyed cache, but this
+composable does not use it. Wiring it in means invalidating cached entries by table on every change
+event, which is most of what a query-cache library does; if you need that, reach for
+[TanStack Query](https://tanstack.com/query) and drive `invalidateQueries` from `bus.on` instead of
+growing this one.
+
+## Deferring a tab's first read
+
+Framework7 mounts every tab at startup. Without `enabled`, a tab the user has not opened still
+competes for the one native database thread while the first screen loads:
+
+```ts
+useReactiveQuery(load, {
+  tables: ["partner"],
+  queryKey: uniqueQueryKey("partner:list"),
+  enabled: isTabActive, // a ref - activation starts the read and the subscription together
+});
+```
+
+## Install
+
+```bash
+vp install @cavulsqa/reactive-vue @cavulsqa/reactive-db vue
+```

package/dist/framework7.d.mts

@@ -0,0 +1,24 @@
+import { Ref } from "vue";
+//#region src/framework7.d.ts
+/**
+ * Framework7 emits these on the `.page` element. An app on another router passes its own.
+ */
+interface PageVisibilityEvents {
+  show: readonly string[];
+  hide: readonly string[];
+}
+declare const FRAMEWORK7_PAGE_EVENTS: PageVisibilityEvents;
+interface ProvidePageVisibilityOptions {
+  events?: PageVisibilityEvents;
+  pageSelector?: string;
+}
+declare function providePageVisibility(options?: ProvidePageVisibilityOptions): Ref<boolean>;
+/**
+ * The provider's own component reads its ref directly: `provide` is not visible to the component
+ * that called it.
+ */
+declare function usePageVisibility(): {
+  value: boolean;
+};
+//#endregion
+export { FRAMEWORK7_PAGE_EVENTS, PageVisibilityEvents, ProvidePageVisibilityOptions, providePageVisibility, usePageVisibility };

package/dist/framework7.mjs

@@ -0,0 +1,62 @@
+import { getCurrentInstance, inject, onBeforeUnmount, onMounted, provide, ref } from "vue";
+//#region src/framework7.ts
+const FRAMEWORK7_PAGE_EVENTS = {
+	show: ["page:beforein", "page:tabshow"],
+	hide: ["page:beforeout", "page:tabhide"]
+};
+const PAGE_VISIBILITY_KEY = Symbol("pageVisibility");
+const ALWAYS_VISIBLE = { value: true };
+const ownVisibility = /* @__PURE__ */ new WeakMap();
+function resolvePageEl(node, pageSelector) {
+	let current = node;
+	while (current) {
+		if (current instanceof HTMLElement) return current.matches(pageSelector) ? current : current.closest(pageSelector);
+		current = current.nextSibling;
+	}
+	return null;
+}
+/**
+* A page inside an inactive tab starts hidden. Everything else starts visible, including a page
+* whose surrounding view is not a tab at all.
+*/
+function initialVisibility(pageEl) {
+	const view = pageEl.closest(".view");
+	if (!view?.classList.contains("tab")) return true;
+	return view.classList.contains("tab-active");
+}
+function providePageVisibility(options = {}) {
+	const events = options.events ?? FRAMEWORK7_PAGE_EVENTS;
+	const pageSelector = options.pageSelector ?? ".page";
+	const isVisible = ref(true);
+	const instance = getCurrentInstance();
+	let pageEl = null;
+	const show = () => isVisible.value = true;
+	const hide = () => isVisible.value = false;
+	provide(PAGE_VISIBILITY_KEY, isVisible);
+	if (instance) ownVisibility.set(instance, isVisible);
+	onMounted(() => {
+		pageEl = resolvePageEl(instance?.vnode.el ?? instance?.proxy?.$el, pageSelector);
+		if (!pageEl) return;
+		isVisible.value = initialVisibility(pageEl);
+		for (const event of events.show) pageEl.addEventListener(event, show);
+		for (const event of events.hide) pageEl.addEventListener(event, hide);
+	});
+	onBeforeUnmount(() => {
+		if (!pageEl) return;
+		for (const event of events.show) pageEl.removeEventListener(event, show);
+		for (const event of events.hide) pageEl.removeEventListener(event, hide);
+		pageEl = null;
+	});
+	return isVisible;
+}
+/**
+* The provider's own component reads its ref directly: `provide` is not visible to the component
+* that called it.
+*/
+function usePageVisibility() {
+	const instance = getCurrentInstance();
+	if (!instance) return ALWAYS_VISIBLE;
+	return ownVisibility.get(instance) ?? inject(PAGE_VISIBILITY_KEY, ALWAYS_VISIBLE);
+}
+//#endregion
+export { FRAMEWORK7_PAGE_EVENTS, providePageVisibility, usePageVisibility };

package/dist/index.d.mts

@@ -0,0 +1,117 @@
+import { ComputedRef, Ref } from "vue";
+import { OnTableChangeFn, QueryMetric, QueryMetrics, QueryMetricsRecorder, ReactiveQueryOptions } from "@cavulsqa/reactive-db";
+//#region src/reactiveQuery.d.ts
+interface ReactiveQueryLogger {
+  debug: (message: string, ...details: unknown[]) => void;
+  warn: (message: string, ...details: unknown[]) => void;
+  error: (message: string, ...details: unknown[]) => void;
+}
+/**
+ * `enabled` may be a ref, so a screen can defer its first read until it is actually shown.
+ * Framework7 mounts every tab at startup; without this, a tab the user has not opened still
+ * competes for the one native database thread while the first screen is loading.
+ */
+type VueReactiveQueryOptions<T> = Omit<ReactiveQueryOptions<T>, "enabled"> & {
+  enabled?: boolean | Ref<boolean> | ComputedRef<boolean>;
+};
+interface ReactiveQuery<T> {
+  data: Ref<T | null>;
+  loading: Ref<boolean>;
+  error: Ref<Error | null>;
+  isStale: Ref<boolean>;
+  isCacheValid: ComputedRef<boolean>;
+  cacheAge: ComputedRef<number>;
+  retryCount: Ref<number>;
+  refetch: (options?: {
+    force?: boolean;
+  }) => Promise<void>;
+  invalidate: () => Promise<void>;
+  cancel: () => void;
+}
+interface CreateReactiveQueryDeps {
+  /** Subscribe to table changes. Wire this to the same change bus the writes emit on. */
+  onTableChange: OnTableChangeFn;
+  /** Defaults to a no-op recorder. Pass `createVueQueryMetrics().recorder` to collect timings. */
+  metrics?: QueryMetrics;
+  /**
+   * Resolves the visibility of the surrounding page when a call site does not pass `isVisible`.
+   * Defaults to always-visible, which means a screen the user cannot see still refetches. On a
+   * router that mounts every tab up front, pass an adapter - `usePageVisibility` from
+   * `@cavulsqa/reactive-vue/framework7` is one.
+   */
+  useVisibility?: () => {
+    value: boolean;
+  };
+  /**
+   * Warn when two mounted queries share a `queryKey` but watch different tables - they are
+   * different queries, so the second is handed the first's rows. Defaults to on outside
+   * production.
+   */
+  warnOnKeyConflict?: boolean;
+  /**
+   * Where a failed query and the `debug` traces go. Defaults to the console; pass the app's error
+   * service so a failure reaches the same place as every other one.
+   */
+  logger?: ReactiveQueryLogger;
+}
+interface ReactiveQueryComposables {
+  useReactiveQuery: <T>(queryFn: () => Promise<T>, options: VueReactiveQueryOptions<T>) => ReactiveQuery<T>;
+  useStructuralQuery: <T>(queryFn: () => Promise<T>, tables: string[], options: Omit<VueReactiveQueryOptions<T>, "tables" | "refetchOn">) => ReactiveQuery<T>;
+  useStaticQuery: <T>(queryFn: () => Promise<T>, tables: string[], options: Omit<VueReactiveQueryOptions<T>, "tables" | "enabled">) => ReactiveQuery<T>;
+}
+/**
+ * Binds the reactive-db primitives to Vue's lifecycle once, and returns the composables an app
+ * calls everywhere. The change bus and the metrics recorder are app-owned singletons, so they are
+ * injected here rather than created per query.
+ */
+declare function createReactiveQuery(deps: CreateReactiveQueryDeps): ReactiveQueryComposables;
+//#endregion
+//#region src/queryKeys.d.ts
+/**
+ * A key unique to this call, so the query is never deduplicated against another and its
+ * `cacheTime` window is its own.
+ *
+ * A `queryKey` is an *identity*: two mounted queries sharing one await a single request and share
+ * the result. That is what you want for the same list rendered twice, and wrong for two different
+ * queries that happen to be named alike - the second would be handed the first's rows. Reach for a
+ * stable literal only when sharing is the intent; otherwise call this.
+ */
+declare function uniqueQueryKey(prefix: string): string;
+//#endregion
+//#region src/queryMetrics.d.ts
+interface VueQueryMetricsOptions {
+  maxEntries?: number;
+  /**
+   * Name of a `window` property to expose `snapshot()` and `reset()` on, for a driven session
+   * (a device debugger) to read timings without opening dev tools. Omit outside development.
+   */
+  exposeOnWindowAs?: string;
+}
+interface QueryMetricsView {
+  totalQueries: ComputedRef<number>;
+  avgQueryTime: ComputedRef<number>;
+  cacheHitRate: ComputedRef<number>;
+  refetchesByTable: ComputedRef<Record<string, number>>;
+  queriesByKey: ComputedRef<Record<string, QueryMetric>>;
+  slowestQueries: ComputedRef<Array<QueryMetric & {
+    key: string;
+  }>>;
+  errors: ComputedRef<Record<string, number>>;
+  activeListeners: ComputedRef<number>;
+  uptime: ComputedRef<number>;
+  isDevToolsOpen: ComputedRef<boolean>;
+  reset: () => void;
+  toggleDevTools: (isOpen?: boolean) => void;
+}
+interface VueQueryMetrics {
+  recorder: QueryMetricsRecorder;
+  useQueryMetrics: () => QueryMetricsView;
+}
+/**
+ * Wraps the recorder's state in `reactive()` so a dev-tools panel re-renders as queries run, and
+ * derives the aggregate views from it. One recorder per app: pass `recorder` to
+ * `createReactiveQuery` so both sides count the same queries.
+ */
+declare function createVueQueryMetrics(options?: VueQueryMetricsOptions): VueQueryMetrics;
+//#endregion
+export { CreateReactiveQueryDeps, QueryMetricsView, ReactiveQuery, ReactiveQueryComposables, ReactiveQueryLogger, VueQueryMetrics, VueQueryMetricsOptions, VueReactiveQueryOptions, createReactiveQuery, createVueQueryMetrics, uniqueQueryKey };

package/dist/index.mjs

@@ -0,0 +1,324 @@
+import { computed, isRef, onMounted, onUnmounted, reactive, ref, watch } from "vue";
+import { calcRetryDelay, createQueryMetrics, createVisibilityGate, noopMetrics } from "@cavulsqa/reactive-db";
+//#region src/reactiveQuery.ts
+const DEFAULT_DEBOUNCE = 100;
+const ALWAYS_VISIBLE = { value: true };
+const consoleLogger = {
+	debug: (message, ...details) => console.log(message, ...details),
+	warn: (message, ...details) => console.warn(message, ...details),
+	error: (message, ...details) => console.error(message, ...details)
+};
+/**
+* Binds the reactive-db primitives to Vue's lifecycle once, and returns the composables an app
+* calls everywhere. The change bus and the metrics recorder are app-owned singletons, so they are
+* injected here rather than created per query.
+*/
+function createReactiveQuery(deps) {
+	const metrics = deps.metrics ?? noopMetrics;
+	const resolveVisibility = deps.useVisibility ?? (() => ALWAYS_VISIBLE);
+	const warnOnKeyConflict = deps.warnOnKeyConflict ?? true;
+	const logger = deps.logger ?? consoleLogger;
+	const inFlightQueries = /* @__PURE__ */ new Map();
+	const watchedTablesByKey = /* @__PURE__ */ new Map();
+	function claimKey(queryKey, tables) {
+		const signature = [...tables].sort().join(",");
+		const existing = watchedTablesByKey.get(queryKey);
+		if (!existing) {
+			watchedTablesByKey.set(queryKey, {
+				tables: signature,
+				holders: 1
+			});
+			return;
+		}
+		if (warnOnKeyConflict && existing.tables !== signature) logger.warn(`[useReactiveQuery] queryKey "${queryKey}" is mounted twice watching different tables ("${existing.tables}" and "${signature}"). These are different queries sharing an identity, so one will receive the other's result. Use uniqueQueryKey() for a key that is never shared.`);
+		existing.holders += 1;
+	}
+	function releaseKey(queryKey) {
+		const existing = watchedTablesByKey.get(queryKey);
+		if (!existing) return;
+		existing.holders -= 1;
+		if (existing.holders <= 0) watchedTablesByKey.delete(queryKey);
+	}
+	function useReactiveQuery(queryFn, options) {
+		const data = ref(null);
+		const loading = ref(false);
+		const error = ref(null);
+		const isStale = ref(false);
+		const lastFetchTime = ref(0);
+		const cacheClock = ref(Date.now());
+		const retryCount = ref(0);
+		let debounceTimer = null;
+		let retryTimer = null;
+		let abandonRetry = null;
+		let disposed = false;
+		let activeRequestId = 0;
+		const debounceMs = options.debounce ?? DEFAULT_DEBOUNCE;
+		const enabledRef = isRef(options.enabled) ? options.enabled : ref(options.enabled !== false);
+		const fetchOnMount = options.fetchOnMount !== false;
+		const queryKey = options.queryKey;
+		const cancelOnUnmount = options.cancelOnUnmount !== false;
+		const maxRetries = options.retry === false ? 0 : options.retry ?? 0;
+		const cacheAge = computed(() => cacheClock.value - lastFetchTime.value);
+		const isCacheValid = computed(() => {
+			if (!options.cacheTime || !lastFetchTime.value) return false;
+			return cacheClock.value - lastFetchTime.value < options.cacheTime;
+		});
+		function cancel() {
+			activeRequestId++;
+		}
+		function syncCacheClock() {
+			cacheClock.value = Date.now();
+		}
+		function isCacheValidNow() {
+			syncCacheClock();
+			return isCacheValid.value;
+		}
+		/**
+		* Resolves when the backoff elapses, or immediately when the query is torn down. Waiting on a
+		* bare `setTimeout` meant an unmount mid-backoff still woke up and ran `queryFn` again -
+		* against the one native database thread this composable exists to protect.
+		*/
+		function waitForRetry(delay) {
+			return new Promise((resolve) => {
+				abandonRetry = () => {
+					if (retryTimer) clearTimeout(retryTimer);
+					retryTimer = null;
+					abandonRetry = null;
+					resolve();
+				};
+				retryTimer = setTimeout(() => {
+					retryTimer = null;
+					abandonRetry = null;
+					resolve();
+				}, delay);
+			});
+		}
+		async function executeQueryWithRetry(showLoading = true, attempt = 0, force = false) {
+			if (!force && inFlightQueries.has(queryKey)) {
+				if (options.debug) logger.debug(`[useReactiveQuery] Deduping query: ${queryKey}`);
+				try {
+					data.value = await inFlightQueries.get(queryKey);
+					metrics.recordCacheHit();
+				} catch {}
+				return;
+			}
+			cancel();
+			const requestId = activeRequestId;
+			if (options.staleWhileRevalidate && data.value !== null) isStale.value = true;
+			else loading.value = showLoading;
+			error.value = null;
+			retryCount.value = attempt;
+			const startTime = performance.now();
+			const queryPromise = queryFn();
+			inFlightQueries.set(queryKey, queryPromise);
+			try {
+				const result = await queryPromise;
+				if (requestId !== activeRequestId) return;
+				data.value = result;
+				lastFetchTime.value = Date.now();
+				isStale.value = false;
+				retryCount.value = 0;
+				const duration = performance.now() - startTime;
+				metrics.recordQuery(queryKey, duration);
+				if (options.debug) logger.debug(`[useReactiveQuery] Query executed (${duration.toFixed(1)}ms):`, result);
+				options.onSuccess?.(result);
+			} catch (err) {
+				if (requestId !== activeRequestId) return;
+				const errorObj = err instanceof Error ? err : new Error(String(err));
+				if (attempt < maxRetries) {
+					const delay = calcRetryDelay(attempt, options.retryDelay);
+					inFlightQueries.delete(queryKey);
+					if (options.debug) logger.debug(`[useReactiveQuery] Retry ${attempt + 1}/${maxRetries} in ${delay}ms`);
+					await waitForRetry(delay);
+					if (disposed || requestId !== activeRequestId) return;
+					return executeQueryWithRetry(showLoading, attempt + 1, force);
+				}
+				error.value = errorObj;
+				isStale.value = false;
+				logger.error("[useReactiveQuery] Query failed:", err);
+				metrics.recordError(queryKey);
+				options.onError?.(errorObj);
+			} finally {
+				loading.value = false;
+				if (inFlightQueries.get(queryKey) === queryPromise) inFlightQueries.delete(queryKey);
+			}
+		}
+		function scheduledRefetch() {
+			if (isCacheValidNow()) {
+				if (options.debug) logger.debug("[useReactiveQuery] Cache valid, skipping refetch");
+				metrics.recordCacheHit();
+				return;
+			}
+			if (debounceTimer) clearTimeout(debounceTimer);
+			debounceTimer = setTimeout(() => {
+				metrics.recordRefetch(options.tables[0] ?? "unknown");
+				executeQueryWithRetry();
+				debounceTimer = null;
+			}, debounceMs);
+		}
+		async function refetch(refetchOptions) {
+			if (debounceTimer) {
+				clearTimeout(debounceTimer);
+				debounceTimer = null;
+			}
+			await executeQueryWithRetry(true, 0, refetchOptions?.force);
+		}
+		function invalidate() {
+			lastFetchTime.value = 0;
+			syncCacheClock();
+			return refetch();
+		}
+		function shouldTriggerRefetch(event) {
+			if (options.refetchOn && !options.refetchOn.includes(event.type)) {
+				if (options.debug) logger.debug(`[useReactiveQuery] Skipping ${event.type} (not in refetchOn)`);
+				return false;
+			}
+			if (options.shouldRefetch && !options.shouldRefetch(event)) {
+				if (options.debug) logger.debug("[useReactiveQuery] Skipping (shouldRefetch returned false)");
+				return false;
+			}
+			return true;
+		}
+		const gate = createVisibilityGate();
+		const visibility = options.isVisible ?? resolveVisibility();
+		let unsubscribe = null;
+		let stopVisibilityWatch = null;
+		let active = false;
+		function activate() {
+			if (active) return;
+			active = true;
+			claimKey(queryKey, options.tables);
+			if (fetchOnMount) executeQueryWithRetry();
+			unsubscribe = deps.onTableChange(options.tables, (event) => {
+				if (options.debug) logger.debug("[useReactiveQuery] Table changed:", event);
+				if (!shouldTriggerRefetch(event)) return;
+				if (gate.recordChange(visibility.value) === "refetch") scheduledRefetch();
+			});
+			if (isRef(visibility)) stopVisibilityWatch = watch(visibility, (visible) => {
+				if (visible && gate.recordVisible() === "refetch") scheduledRefetch();
+			});
+			metrics.incrementListeners();
+		}
+		function deactivate() {
+			if (!active) return;
+			active = false;
+			releaseKey(queryKey);
+			unsubscribe?.();
+			unsubscribe = null;
+			stopVisibilityWatch?.();
+			stopVisibilityWatch = null;
+			metrics.decrementListeners();
+		}
+		let stopEnabledWatch = null;
+		onMounted(() => {
+			if (enabledRef.value) activate();
+			stopEnabledWatch = watch(enabledRef, (isEnabled) => {
+				if (isEnabled) activate();
+				else deactivate();
+			});
+		});
+		onUnmounted(() => {
+			disposed = true;
+			stopEnabledWatch?.();
+			deactivate();
+			if (debounceTimer) clearTimeout(debounceTimer);
+			abandonRetry?.();
+			if (cancelOnUnmount) cancel();
+		});
+		return {
+			data,
+			loading,
+			error,
+			isStale,
+			isCacheValid,
+			cacheAge,
+			retryCount,
+			refetch,
+			invalidate,
+			cancel
+		};
+	}
+	return {
+		useReactiveQuery,
+		useStructuralQuery: (queryFn, tables, options) => useReactiveQuery(queryFn, {
+			tables,
+			refetchOn: ["insert", "delete"],
+			...options
+		}),
+		useStaticQuery: (queryFn, tables, options) => useReactiveQuery(queryFn, {
+			tables,
+			enabled: false,
+			...options
+		})
+	};
+}
+//#endregion
+//#region src/queryKeys.ts
+let instanceCounter = 0;
+/**
+* A key unique to this call, so the query is never deduplicated against another and its
+* `cacheTime` window is its own.
+*
+* A `queryKey` is an *identity*: two mounted queries sharing one await a single request and share
+* the result. That is what you want for the same list rendered twice, and wrong for two different
+* queries that happen to be named alike - the second would be handed the first's rows. Reach for a
+* stable literal only when sharing is the intent; otherwise call this.
+*/
+function uniqueQueryKey(prefix) {
+	instanceCounter += 1;
+	return `${prefix}#${instanceCounter}`;
+}
+//#endregion
+//#region src/queryMetrics.ts
+const SLOWEST_QUERY_COUNT = 5;
+/**
+* Wraps the recorder's state in `reactive()` so a dev-tools panel re-renders as queries run, and
+* derives the aggregate views from it. One recorder per app: pass `recorder` to
+* `createReactiveQuery` so both sides count the same queries.
+*/
+function createVueQueryMetrics(options = {}) {
+	const recorder = createQueryMetrics({
+		maxEntries: options.maxEntries,
+		wrapState: reactive
+	});
+	const state = recorder.getState();
+	if (options.exposeOnWindowAs && typeof window !== "undefined") window[options.exposeOnWindowAs] = {
+		snapshot: () => JSON.parse(JSON.stringify(recorder.getState())),
+		reset: () => recorder.reset()
+	};
+	function useQueryMetrics() {
+		const totalQueries = computed(() => Object.values(state.queries).reduce((sum, metric) => sum + metric.count, 0));
+		return {
+			totalQueries,
+			avgQueryTime: computed(() => {
+				const metrics = Object.values(state.queries);
+				if (metrics.length === 0) return 0;
+				const totalTime = metrics.reduce((sum, metric) => sum + metric.totalTime, 0);
+				const totalCount = metrics.reduce((sum, metric) => sum + metric.count, 0);
+				return totalCount > 0 ? totalTime / totalCount : 0;
+			}),
+			cacheHitRate: computed(() => {
+				const total = totalQueries.value + state.cacheHits;
+				return total > 0 ? state.cacheHits / total * 100 : 0;
+			}),
+			refetchesByTable: computed(() => ({ ...state.refetchesByTable })),
+			queriesByKey: computed(() => ({ ...state.queries })),
+			slowestQueries: computed(() => Object.entries(state.queries).map(([key, metric]) => ({
+				key,
+				...metric
+			})).sort((a, b) => b.avgTime - a.avgTime).slice(0, SLOWEST_QUERY_COUNT)),
+			errors: computed(() => ({ ...state.errors })),
+			activeListeners: computed(() => state.activeListeners),
+			uptime: computed(() => Date.now() - state.startTime),
+			isDevToolsOpen: computed(() => state.isDevToolsOpen),
+			reset: () => recorder.reset(),
+			toggleDevTools: (isOpen) => recorder.toggleDevTools(isOpen)
+		};
+	}
+	return {
+		recorder,
+		useQueryMetrics
+	};
+}
+//#endregion
+export { createReactiveQuery, createVueQueryMetrics, uniqueQueryKey };

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@cavulsqa/reactive-vue",
+  "version": "0.1.0",
+  "description": "Vue bindings for @cavulsqa/reactive-db: a reactive query composable, Framework7 page visibility, and a reactive metrics view.",
+  "keywords": [
+    "framework7",
+    "offline-first",
+    "query",
+    "reactive",
+    "sqlite",
+    "vue"
+  ],
+  "homepage": "https://github.com/aybinv7/cavulsqa/tree/main/packages/reactive-vue#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-vue"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./framework7": "./dist/framework7.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": {
+    "@cavulsqa/reactive-db": "workspace:*",
+    "@types/node": "^26.1.1",
+    "bumpp": "^11.1.0",
+    "happy-dom": "catalog:",
+    "typescript": "^7.0.2",
+    "vite": "catalog:",
+    "vite-plus": "catalog:",
+    "vue": "catalog:"
+  },
+  "peerDependencies": {
+    "@cavulsqa/reactive-db": "^0.1.0",
+    "vue": ">=3.5"
+  }
+}