@spooky-sync/client-solid2 0.0.1-canary.238 → 0.0.1-canary.240

package/AGENTS.md

@@ -45,6 +45,7 @@ Provider props are identical to client-solid: `config`, `fallback`, `preload` (a
   - `isSettled()` — authoritative AND idle; gate windowed-list end detection on it. Not monotonic; latch it (a `createMemo(prev => prev || q.isSettled())`) for a verdict that must stick.
   - Options: `enabled?: () => boolean`, `deregisterOnCleanup?: boolean`.
 - **`createSubmission(fn)`** — button pending/error state around a mutation: `submit()`, `pending()`, `error()`, `result()`, `clearError()`. There is deliberately no `action()` / `createOptimisticStore` layer (see `src/lib/create-submission.ts`).
+- **`useSyncActivity(options?)`** — `{ fetchingQueries, pendingMutations, isDownloading, isUploading }`. One subscription on the engine's aggregate fetch count plus the outbox depth; `isDownloading()` is debounced ON by `downloadDelayMs` (200) and off at once, `isUploading()` is `pendingMutations() > uploadThreshold` (1). Drive a logo/traffic indicator off it; pair with `useSyncStatus().isOffline()` to show the unsaved count while disconnected.
 - **`createPreload`**, **`usePendingMutations`**, **`useSyncStatus`**, **`useStorageStatus`**, **`useFeatureFlag`**, **`useAppRelease`**, **`useCrdtField`**, **`useFileUpload`**, **`useDownloadFile`** — same shapes as client-solid.
 - **`conflate`**, **`fromSubscription`** — the async-iterable helpers the hooks are built on; useful for wrapping other engine subscriptions.
 

package/QUICK_START.md

@@ -116,7 +116,7 @@ Track a backend job's progress by querying its outbox row: `createQuery(() => db
 
 ## Status hooks
 
-Same shapes as client-solid, rebuilt on async-iterable-backed memos: `useSyncStatus`, `useStorageStatus`, `usePendingMutations`, `useFeatureFlag`, `useAppRelease`, `useCrdtField`, `useFileUpload`, `useDownloadFile`, `createPreload`.
+Same shapes as client-solid, rebuilt on async-iterable-backed memos: `useSyncStatus`, `useStorageStatus`, `usePendingMutations`, `useSyncActivity` (new: `isDownloading()` after 200 ms of fetching, `isUploading()` above one queued write, for a traffic indicator), `useFeatureFlag`, `useAppRelease`, `useCrdtField`, `useFileUpload`, `useDownloadFile`, `createPreload`.
 
 ## Migrating from client-solid
 

package/README.md

@@ -8,7 +8,7 @@ What "native" means here:
 
 - Query results are a plain store written from the engine's live subscription and merged keyed by `id`: row identity preserved, coarse `<For>` readers notified, only changed fields written. Not an async-generator projection - see `create-query.ts` for why a never-returning generator breaks navigation transitions.
 - `createQuery` exposes both worlds: non-suspending accessors (`data`, `isLoading`, `isFetching`, `isAuthoritative`, `hasData`, `isEmpty`, `isSettled`, `error`) and a suspending `ready()` for `<Loading>` boundaries. Born committed, so local-first cache paints never suspend. `isLoading()` is true only on a cold first load (nothing cached, server not heard yet); `isEmpty()` is the server saying "no rows".
-- Status hooks (`useSyncStatus`, `useStorageStatus`, `usePendingMutations`, feature flags, app release) are async-iterable-backed memos with `loadingValue`.
+- Status hooks (`useSyncStatus`, `useSyncActivity`, `useStorageStatus`, `usePendingMutations`, feature flags, app release) are async-iterable-backed memos with `loadingValue`. `useSyncActivity` is the traffic indicator pair: `isDownloading()` (queries fetching for longer than 200 ms) and `isUploading()` (more than one write queued), plus the raw `fetchingQueries()` / `pendingMutations()` counts.
 - Mutations stay plain async calls — the engine is already optimistic local-first end to end (local commit → live re-emit → outbox sync). `createSubmission` adds button pending/error state.
 
 See `QUICK_START.md` for usage and the migration table from client-solid, and `src/lib/__tests__/rc-semantics.test.ts` for the probed Solid 2 rc contracts this package depends on (run them after every Solid version bump).

package/dist/index.cjs

@@ -387,6 +387,57 @@ function useSyncStatus() {
 	};
 }
 
+//#endregion
+//#region src/lib/use-sync-activity.ts
+/**
+* The two directions of sync traffic, for an indicator in the app chrome.
+*
+* `fetchingQueries` is one subscription on the engine's aggregate fetch count,
+* not one per query; `pendingMutations` is the outbox depth. `isDownloading`
+* is the fetch count debounced ON by `downloadDelayMs` (and off at once), so a
+* local-first page that answers from cache and confirms with the server in a
+* few milliseconds never flickers. Must be used within a `<Sp00kyProvider>`, or
+* pass the `SyncedDb` explicitly.
+*/
+function useSyncActivity(dbOrOptions, maybeOptions) {
+	const explicitDb = dbOrOptions && typeof dbOrOptions.subscribeToFetchActivity === "function" ? dbOrOptions : void 0;
+	const options = (explicitDb ? maybeOptions : dbOrOptions) ?? {};
+	const db = explicitDb ?? useDb();
+	const downloadDelayMs = options.downloadDelayMs ?? 200;
+	const uploadThreshold = options.uploadThreshold ?? 1;
+	const fetchingQueries = fromSubscription((cb) => db.subscribeToFetchActivity(cb), db.fetchingQueryCount);
+	const pendingMutations = fromSubscription((cb) => db.subscribeToPendingMutations(cb), db.pendingMutationCount);
+	const [isDownloading, setIsDownloading] = (0, solid_js.createSignal)(false, { ownedWrite: true });
+	let timer;
+	(0, solid_js.createEffect)(() => fetchingQueries() > 0, (busy) => {
+		if (timer !== void 0) {
+			clearTimeout(timer);
+			timer = void 0;
+		}
+		if (!busy) {
+			setIsDownloading(false);
+			return;
+		}
+		if (downloadDelayMs <= 0) {
+			setIsDownloading(true);
+			return;
+		}
+		timer = setTimeout(() => {
+			timer = void 0;
+			setIsDownloading(true);
+		}, downloadDelayMs);
+	});
+	(0, solid_js.onCleanup)(() => {
+		if (timer !== void 0) clearTimeout(timer);
+	});
+	return {
+		fetchingQueries,
+		pendingMutations,
+		isDownloading,
+		isUploading: () => pendingMutations() > uploadThreshold
+	};
+}
+
 //#endregion
 //#region src/lib/use-storage-status.ts
 /**
@@ -1163,6 +1214,19 @@ var SyncedDb = class {
 		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
 		return this.sp00ky.subscribeToPendingMutations(cb);
 	}
+	/** Queries mid-fetch right now. See {@link useSyncActivity}. */
+	get fetchingQueryCount() {
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		return this.sp00ky.fetchingQueryCount;
+	}
+	/**
+	* Observe how many queries are fetching from the server. Fires immediately
+	* and on every change. Prefer the `useSyncActivity` hook in components.
+	*/
+	subscribeToFetchActivity(cb) {
+		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
+		return this.sp00ky.subscribeToFetchActivity(cb);
+	}
 	/** Current sync-health snapshot. See {@link useSyncStatus}. */
 	get syncHealth() {
 		if (!this.sp00ky) throw new Error("SyncedDb not initialized");
@@ -1223,5 +1287,6 @@ exports.useFileUpload = useFileUpload;
 exports.usePendingMutations = usePendingMutations;
 exports.useQuery = useQuery;
 exports.useStorageStatus = useStorageStatus;
+exports.useSyncActivity = useSyncActivity;
 exports.useSyncStatus = useSyncStatus;
 //# sourceMappingURL=index.cjs.map