local-replica 0.0.0 → 0.0.3

package/dist/zustand/index.js

@@ -0,0 +1,641 @@
+import { S as stableQueryKey, t as createReplicaEngine, v as isReplicaSyncKey, y as replicaKeys } from "../createReplicaEngine-CdR-URHo.js";
+import { useEffect, useLayoutEffect, useRef } from "react";
+// src/zustand/errors.ts
+/** `slice.fetch` was asked to fetch for a scope that is no longer active. */
+var ReplicaScopeChangedError = class extends Error {
+	constructor(name, scope) {
+		super(`[replica] ${name}: scope ${scope} is no longer active`);
+		this.name = "ReplicaScopeChangedError";
+	}
+};
+// src/zustand/lens.ts
+/**
+* Apply every view write as ONE host update, so subscribers never observe a
+* view out of step with its bookkeeping. Consecutive key writes go through
+* the lens' `setMany` when it has one, so seeding N rows clones the backing
+* field once instead of N times.
+*/
+const applyLensWrites = (view, state, writes) => {
+	let patch = {};
+	let current = state;
+	let pending = [];
+	const flush = () => {
+		if (pending.length === 0) return;
+		const entries = pending;
+		pending = [];
+		if (view.setMany && entries.length > 1) {
+			const next = view.setMany(current, entries);
+			patch = {
+				...patch,
+				...next
+			};
+			current = {
+				...current,
+				...next
+			};
+			return;
+		}
+		for (const entry of entries) {
+			const next = view.set(current, entry.key, entry.data);
+			patch = {
+				...patch,
+				...next
+			};
+			current = {
+				...current,
+				...next
+			};
+		}
+	};
+	for (const write of writes) if ("type" in write) {
+		flush();
+		const next = view.clear(current);
+		patch = {
+			...patch,
+			...next
+		};
+		current = {
+			...current,
+			...next
+		};
+	} else pending.push({
+		data: write.data,
+		key: write.key
+	});
+	flush();
+	return patch;
+};
+/** Lens for the common case: a `Record<key, TData>` field on the store. */
+const recordLens = (field) => ({
+	clear: () => ({ [field]: {} }),
+	get: (state, key) => state[field]?.[key],
+	keys: (state) => Object.keys(state[field] ?? {}),
+	set: (state, key, data) => {
+		const next = { ...state[field] };
+		if (data === void 0) delete next[key];
+		else next[key] = data;
+		return { [field]: next };
+	},
+	setMany: (state, entries) => {
+		const next = { ...state[field] };
+		for (const { key, data } of entries) if (data === void 0) delete next[key];
+		else next[key] = data;
+		return { [field]: next };
+	}
+});
+/**
+* Lens for a paged view split across store fields: the rows stay where
+* existing readers expect them (`itemsField[key]`, a plain array), the paging
+* bookkeeping lives in `metaField[key]`, and `derive` recomputes fields built
+* from the rows (e.g. a parsed display list) in the same commit — so a derived
+* field is never one frame behind its rows.
+*
+* Rows seeded without bookkeeping (by code outside the replica) read as a
+* single head page.
+*/
+const splitPagedLens = ({ clearDerived, derive, itemsField, metaField }) => {
+	const NO_META = {};
+	const views = /* @__PURE__ */ new WeakMap();
+	const remember = (items, meta, view) => {
+		let byMeta = views.get(items);
+		if (!byMeta) views.set(items, byMeta = /* @__PURE__ */ new WeakMap());
+		byMeta.set(meta, view);
+		return view;
+	};
+	const rowsOf = (state) => state[itemsField] ?? {};
+	const metaOf = (state) => state[metaField] ?? {};
+	return {
+		clear: () => ({
+			[itemsField]: {},
+			[metaField]: {},
+			...clearDerived?.()
+		}),
+		get: (state, key) => {
+			const items = rowsOf(state)[key];
+			if (!items) return void 0;
+			const meta = metaOf(state)[key] ?? NO_META;
+			const cached = views.get(items)?.get(meta);
+			if (cached) return cached;
+			const view = meta === NO_META ? {
+				currentPage: 0,
+				hasMore: true,
+				items,
+				pageSize: items.length
+			} : {
+				...meta,
+				items
+			};
+			return remember(items, meta, view);
+		},
+		keys: (state) => Object.keys(rowsOf(state)),
+		set: (state, key, data) => {
+			const rows = { ...rowsOf(state) };
+			const metas = { ...metaOf(state) };
+			if (data === void 0) {
+				delete rows[key];
+				delete metas[key];
+			} else {
+				const { items, ...meta } = data;
+				rows[key] = items;
+				metas[key] = meta;
+				remember(items, meta, data);
+			}
+			const next = {
+				...state,
+				[itemsField]: rows,
+				[metaField]: metas
+			};
+			return {
+				[itemsField]: rows,
+				[metaField]: metas,
+				...derive?.(next, key, data?.items)
+			};
+		}
+	};
+};
+// src/zustand/requests.ts
+/** Request id of a sync key in a scope: requests of the same id dedupe and supersede. */
+const replicaRequestId = (scope, syncKey) => `${scope}\u0000${stableQueryKey(syncKey)}`;
+/**
+* Lifecycle bookkeeping of head requests: capture (`begin`), send and track in
+* flight, retire older requests once a newer response applied, and settle each
+* request exactly once. What settling *does* is the slice's `fold`; this only
+* guarantees every path — a mounted `useSync`, or `fetch` with no view mounted
+* — goes through it the same way.
+*/
+const createRequests = ({ clearGeneration, fetcher, fold, removalGeneration, resource }) => {
+	let requestSeq = 0;
+	/**
+	* Requests whose start order is at or below this number are retired, per
+	* request id: a newer response already applied, or a `fresh` fetch started
+	* after them. Their late response would repaint an older value.
+	*
+	* An entry only matters while a request it retires is still unsettled:
+	* every request started later has a higher sequence, so a missing entry
+	* (read as 0) admits exactly the same responses. Entries are pruned as soon
+	* as no sent request at or below them is pending, so the map holds only the
+	* ids with an older request in flight.
+	*/
+	const retiredThrough = /* @__PURE__ */ new Map();
+	/** Sequences of the sent requests that have not settled yet, per request id. */
+	const unsettled = /* @__PURE__ */ new Map();
+	/** Drop the retirement of `requestId` once no request it retires is pending. */
+	const pruneRetired = (requestId) => {
+		const through = retiredThrough.get(requestId);
+		if (through === void 0) return;
+		for (const seq of unsettled.get(requestId) ?? []) if (seq <= through) return;
+		retiredThrough.delete(requestId);
+	};
+	const retire = (requestId, seq) => {
+		if ((retiredThrough.get(requestId) ?? 0) < seq) retiredThrough.set(requestId, seq);
+		pruneRetired(requestId);
+	};
+	/** A newer response already applied, or a `fresh` fetch started after it. */
+	const isRetired = ({ requestId, seq }) => seq <= (retiredThrough.get(requestId) ?? 0);
+	const trackUnsettled = ({ requestId, seq }) => {
+		const pending = unsettled.get(requestId) ?? /* @__PURE__ */ new Set();
+		unsettled.set(requestId, pending);
+		pending.add(seq);
+	};
+	const untrackUnsettled = ({ requestId, seq }) => {
+		const pending = unsettled.get(requestId);
+		if (!pending?.delete(seq)) return;
+		if (pending.size === 0) unsettled.delete(requestId);
+		pruneRetired(requestId);
+	};
+	/** The latest request in flight per id, which a non-`fresh` `fetch` joins. */
+	const inflight = /* @__PURE__ */ new Map();
+	/** `useSync` requests in flight per id (`fetch` seeds the driver only while none is). */
+	const syncInflight = /* @__PURE__ */ new Map();
+	/**
+	* `useSync` request each sync id last started, settled by the driver's
+	* callback. The driver settles one request per key at a time (a newer
+	* request supersedes the older one), so the latest start is the one that
+	* settles.
+	*/
+	const syncRequests = /* @__PURE__ */ new Map();
+	const syncKeyOf = (params, scope, key) => resource.syncKey?.(params) ?? replicaKeys.sync(resource.name, resource.version, scope, key, params);
+	/** Capture what a head request for `params` started under. */
+	const begin = (params, scope, source) => {
+		const key = resource.key(params);
+		const syncKey = syncKeyOf(params, scope, key);
+		return {
+			clearGeneration: clearGeneration(scope),
+			key,
+			params,
+			queryKey: resource.storageKey(params),
+			removalGeneration: removalGeneration(scope, key),
+			requestId: replicaRequestId(scope, syncKey),
+			scope,
+			seq: ++requestSeq,
+			source,
+			syncKey
+		};
+	};
+	/** Send the request and track it in flight until it settles. */
+	const send = (request) => {
+		const { requestId } = request;
+		const sent = fetcher(request.params, void 0);
+		const promise = Promise.resolve(sent);
+		request.promise = promise;
+		trackUnsettled(request);
+		inflight.set(requestId, request);
+		if (request.source === "sync") syncInflight.set(requestId, (syncInflight.get(requestId) ?? 0) + 1);
+		const done = () => {
+			if (inflight.get(requestId) === request) inflight.delete(requestId);
+			if (request.source !== "sync") return;
+			const count = syncInflight.get(requestId) - 1;
+			if (count > 0) syncInflight.set(requestId, count);
+			else syncInflight.delete(requestId);
+		};
+		promise.then(done, done);
+		if (request.source === "sync") promise.then((data) => settle(request, { data }), (error) => settle(request, { error }));
+		return sent;
+	};
+	/**
+	* Fold a settled head request into the replica (see the slice's `fold`). A
+	* request is settled once: a `fetch` that joined a `useSync` request shares
+	* its result.
+	*/
+	const settle = (request, outcome) => {
+		if (request.settled) return request.settled;
+		request.settledWith = "error" in outcome ? outcome.error : outcome.data;
+		request.settled = fold(request, outcome);
+		untrackUnsettled(request);
+		if (request.source === "sync") releaseSyncRequest(request);
+		return request.settled;
+	};
+	/**
+	* Drop a settled `useSync` request's record once its driver callback had its
+	* chance to read it. The record is normally taken by that callback, but the
+	* driver skips it when the hook changed key, unmounted or was superseded —
+	* the request still settles on its own promise, and its record (holding the
+	* response) must not stay behind. A driver runs the callback in the same
+	* turn the response resolves (SWR does, in microtasks), so a macrotask later
+	* the record is only a leak.
+	*/
+	const releaseSyncRequest = (request) => {
+		setTimeout(() => {
+			if (syncRequests.get(request.requestId) === request) syncRequests.delete(request.requestId);
+		}, 0);
+	};
+	/** Start a `useSync` request and record it for the driver's callback. */
+	const startSync = (params, scope) => {
+		const request = begin(params, scope, "sync");
+		syncRequests.set(request.requestId, request);
+		return send(request);
+	};
+	/**
+	* The `useSync` request settling now: the one `requestId` last started. A
+	* response the driver settles without having run our fetcher (a
+	* cache-shared key), or one the recorded request did not produce, is
+	* captured now: nothing it started under is known.
+	*/
+	const takeSyncRequest = (requestId, response, params, scope) => {
+		const request = syncRequests.get(requestId);
+		syncRequests.delete(requestId);
+		if (request && (!request.settled || request.settledWith === response)) return request;
+		return begin(params, scope, "sync");
+	};
+	return {
+		begin,
+		/** Records of `useSync` requests not yet released (leak checks in tests). */
+		debugPendingSyncRequests: () => syncRequests.size,
+		/** Retirement records still held (leak checks in tests). */
+		debugRetiredRequests: () => retiredThrough.size,
+		/** The request in flight for `requestId`, which a non-`fresh` `fetch` joins. */
+		inflight: (requestId) => inflight.get(requestId),
+		isRetired,
+		/** Whether a `useSync` request of `requestId` is in flight. */
+		isSyncInflight: (requestId) => syncInflight.has(requestId),
+		retire,
+		send,
+		settle,
+		startSync,
+		syncKeyOf,
+		takeSyncRequest
+	};
+};
+// src/zustand/useSync.ts
+/**
+* Hydrates the persisted row once per scope/key/query, then lets the driver
+* fetch and revalidate the head. Read the data from the store.
+*/
+const createUseSync = ({ driver, engine: { ensureScope, fetcher, hydrate, retain }, get, headQuery, requests, resource, view }) => {
+	/**
+	* Entries (`scope` + key) whose one-shot hydration actually painted a
+	* persisted row. The hydration query settles `true` on a cache miss too, so
+	* a reactivated key may only replay `onHydrated` when its row really came from
+	* storage — not off a provisional seed or another source that happens to sit
+	* in the view.
+	*/
+	const hydratedEntries = /* @__PURE__ */ new Set();
+	const hydratedEntryId = (scope, key) => `${scope}\u0000${key}`;
+	const useSync = (params, { enabled = true, onError, onHydrated, onSuccess, ...schedule } = {}) => {
+		const scope = resource.scope.use();
+		const key = params ? resource.key(params) : void 0;
+		const active = enabled && !!params && key !== void 0;
+		const queryKey = params ? resource.storageKey(params) : void 0;
+		useLayoutEffect(() => {
+			if (active) ensureScope(scope);
+		}, [active, scope]);
+		useLayoutEffect(() => {
+			if (active && key !== void 0 && queryKey !== void 0) headQuery.set(key, queryKey);
+		}, [
+			active,
+			key,
+			queryKey
+		]);
+		useLayoutEffect(() => {
+			if (active && key !== void 0 && queryKey !== void 0) return retain(key, queryKey);
+		}, [
+			active,
+			key,
+			queryKey
+		]);
+		const activeKey = useRef(void 0);
+		const hydratedKey = useRef(void 0);
+		useLayoutEffect(() => {
+			activeKey.current = active ? key : void 0;
+			hydratedKey.current = void 0;
+		}, [
+			active,
+			key,
+			scope
+		]);
+		const hydration = driver.useQuery(active && resource.persisted && resource.persistKey(key) ? replicaKeys.hydrate(resource.name, resource.version, scope, resource.storageKey(params)) : null, async () => {
+			const didHydrate = await hydrate(params, scope);
+			if (didHydrate) hydratedEntries.add(hydratedEntryId(scope, key));
+			if (activeKey.current !== key) return true;
+			hydratedKey.current = hydratedEntryId(scope, key);
+			if (didHydrate) {
+				const hydrated = view.get(get(), key);
+				if (hydrated !== void 0) onHydrated?.(hydrated);
+			}
+			return true;
+		}, { once: true });
+		useEffect(() => {
+			if (!active || key === void 0 || hydration.data !== true) return;
+			const entry = hydratedEntryId(scope, key);
+			if (hydratedKey.current === entry) return;
+			hydratedKey.current = entry;
+			const current = view.get(get(), key);
+			if (current !== void 0) {
+				if (hydratedEntries.has(entry)) onHydrated?.(current);
+				return;
+			}
+			hydrate(params, scope).then((didHydrate) => {
+				if (!didHydrate) return;
+				hydratedEntries.add(entry);
+				if (activeKey.current !== key || resource.scope.get() !== scope) return;
+				const hydrated = view.get(get(), key);
+				if (hydrated !== void 0) onHydrated?.(hydrated);
+			});
+		}, [
+			active,
+			key,
+			scope,
+			hydration.data
+		]);
+		const syncKey = active && fetcher ? requests.syncKeyOf(params, scope, key) : null;
+		/** The request settling now: the one this sync id last started. */
+		const takeRequest = (response) => requests.takeSyncRequest(replicaRequestId(scope, syncKey), response, params, scope);
+		const sync = driver.useQuery(syncKey, () => requests.startSync(params, scope), {
+			...schedule,
+			onError: (error) => {
+				const settled = requests.settle(takeRequest(error), { error });
+				if (settled.current) onError?.(error, {
+					isActive: settled.isActive,
+					key,
+					scope
+				});
+			},
+			onSuccess: (data) => {
+				const settled = requests.settle(takeRequest(data), { data });
+				if (!settled.current || !settled.isActive) return;
+				if (activeKey.current !== key) return;
+				onSuccess?.(data);
+			}
+		});
+		return {
+			error: sync.error,
+			isHydrated: key === void 0 || !resource.persisted || !resource.persistKey(key) || hydration.data === true,
+			isValidating: sync.isValidating,
+			revalidate: () => sync.mutate()
+		};
+	};
+	return useSync;
+};
+// src/zustand/createReplicaSlice.ts
+/**
+* Bind a replica to a domain Zustand store.
+*
+* The domain store stays the only UI source of truth: components read the
+* `view` location through their usual selectors. The engine owns every
+* transition of that location; this slice adds the Zustand port and a
+* `useSync` hook that only orchestrates fetching — data never flows through
+* its return value.
+*/
+const createReplicaSlice = (resource, { driver, effects, get, set, stateKey, view, ...options }) => {
+	const revalidate = (key) => driver.revalidate((queryKey) => isReplicaSyncKey(queryKey, resource.name, {
+		key,
+		scope: resource.scope.get()
+	}));
+	const engine = createReplicaEngine(resource, {
+		...options,
+		port: {
+			commit: (writes, state, label) => set({
+				...applyLensWrites(view, get(), writes),
+				[stateKey]: state
+			}, false, label),
+			getState: () => get()[stateKey],
+			keys: view.keys && (() => view.keys(get())),
+			read: (key) => view.get(get(), key)
+		},
+		revalidate
+	});
+	const { applyHead, clearGeneration, fetcher, isMissingHead, removalGeneration } = engine;
+	/**
+	* Row key of the head query each entry last asked for. One entry backs a
+	* single view, so a response that belongs to a query the entry has already
+	* moved past must not repaint it — it would show a superseded query, and a
+	* view gated on the current query would then wait forever. Making this an
+	* invariant of the slice (not of one driver) keeps it true for drivers that
+	* leave a request's own callback live after the query changed.
+	*/
+	const headQuery = /* @__PURE__ */ new Map();
+	const requests = createRequests({
+		clearGeneration,
+		fetcher,
+		fold: (request, outcome) => fold(request, outcome),
+		removalGeneration,
+		resource
+	});
+	/**
+	* Whether the request still answers the query its entry shows. A `useSync`
+	* request must match the query the entry last asked for (see `headQuery`). A
+	* `fetch` may also land with no view mounted, but never over a view that
+	* shows another query of the key.
+	*/
+	const isActiveQuery = ({ key, queryKey, source }) => {
+		const head = headQuery.get(key);
+		return source === "sync" ? head === queryKey : head === void 0 || head === queryKey;
+	};
+	/**
+	* Fold a settled head request into the replica: apply every guard, then
+	* `replace` / remove a terminal absence (in the captured scope) / purge one
+	* captured off-scope, then run the resource effects.
+	*/
+	const fold = (request, outcome) => {
+		const { key, params, scope } = request;
+		/**
+		* Whether the entry is still on the scope the request was captured under.
+		*
+		* A response can settle after an identity/workspace switch. `replace` drops
+		* it — the engine refuses off-scope actions — but no side effect may run
+		* either: it carries the previous identity's state (onboarding redirect,
+		* display snapshot, analytics identify, settings writes). The captured
+		* key/scope is not enough on its own, because a switch to a scope that
+		* reads the same key/query satisfies the other guards.
+		*/
+		const isActive = resource.scope.get() === scope;
+		const dropped = {
+			applied: false,
+			current: false,
+			isActive,
+			missing: false
+		};
+		if (request.clearGeneration !== clearGeneration(scope) || request.removalGeneration !== removalGeneration(scope, key) || requests.isRetired(request) || !isActiveQuery(request)) return dropped;
+		if ("error" in outcome) {
+			effects?.onError?.(outcome.error, params, {
+				isActive,
+				key,
+				scope
+			});
+			return {
+				...dropped,
+				current: true
+			};
+		}
+		if (!isActive) {
+			const missing = isMissingHead(outcome.data);
+			if (missing) {
+				remove(key, scope);
+				effects?.onPurge?.(params, {
+					key,
+					scope,
+					source: request.source
+				});
+			}
+			return {
+				...dropped,
+				current: true,
+				missing
+			};
+		}
+		requests.retire(request.requestId, request.seq - 1);
+		const { outcome: folded } = applyHead(params, outcome.data, scope);
+		const context = {
+			key,
+			scope,
+			source: request.source
+		};
+		if (folded === "replaced") effects?.onApplied?.(outcome.data, params, context);
+		else if (folded === "missing") effects?.onMissing?.(params, context);
+		return {
+			applied: folded !== "dropped",
+			current: true,
+			isActive,
+			missing: folded === "missing"
+		};
+	};
+	/**
+	* Fetch the head of an entry now and settle it like a `useSync` response —
+	* for stores that need the data while no view is mounted (a hover prefetch,
+	* a refresh after a mutation on a route without the list). `revalidate` only
+	* re-runs mounted queries.
+	*
+	* Joins a request in flight for the same entry unless `fresh`. Resolves with
+	* what was fetched and whether it was applied; rejects when the request
+	* fails, after routing the failure through `effects.onError`.
+	*/
+	const fetch = async (params, { fresh = false, scope = resource.scope.get() } = {}) => {
+		if (!fetcher) throw new Error(`[replica] ${resource.name} has no fetcher`);
+		if (scope !== resource.scope.get()) throw new ReplicaScopeChangedError(resource.name, scope);
+		let request = requests.begin(params, scope, "fetch");
+		const joined = fresh ? void 0 : requests.inflight(request.requestId);
+		if (joined) request = joined;
+		else {
+			if (fresh) requests.retire(request.requestId, request.seq - 1);
+			requests.send(request);
+		}
+		let data;
+		try {
+			data = await request.promise;
+		} catch (error) {
+			requests.settle(request, { error });
+			throw error;
+		}
+		const settled = requests.settle(request, { data });
+		if (settled.applied && request.source === "fetch" && !requests.isSyncInflight(request.requestId)) driver.seed?.(request.syncKey, data);
+		return {
+			applied: settled.applied,
+			data,
+			missing: settled.missing
+		};
+	};
+	/**
+	* Forget the key's head query as well as the entry. A `useSync` request
+	* already in flight for it would otherwise pass the settle guards (the
+	* marker still matches), `replace` the entry and persist pre-mutation rows
+	* back over an invalidation that has already completed. (The engine's
+	* removal generation drops a `fetch` captured before the removal.)
+	*/
+	const remove = (key, scope) => {
+		if (scope === void 0 || scope === resource.scope.get()) headQuery.delete(key);
+		return engine.remove(key, scope);
+	};
+	const useSync = createUseSync({
+		driver,
+		engine,
+		get,
+		headQuery,
+		requests,
+		resource,
+		view
+	});
+	return {
+		...engine,
+		/** @internal Records of `useSync` requests not yet released (leak checks in tests). */
+		debugPendingSyncRequests: requests.debugPendingSyncRequests,
+		/** @internal Retirement records still held (leak checks in tests). */
+		debugRetiredRequests: requests.debugRetiredRequests,
+		fetch,
+		remove,
+		useSync
+	};
+};
+// src/zustand/driver.ts
+/**
+* Driver over SWR. Pass the app's own hook and scoped `mutate` when it wraps
+* SWR (custom cache provider, key augmentation, retry policy).
+*/
+const createSWRDriver = ({ mutate, useSWR }) => ({
+	revalidate: (match) => mutate(match),
+	seed: (key, data) => {
+		mutate(key, data, { revalidate: false }).catch(() => void 0);
+	},
+	useQuery: (key, fetcher, { once, onError, onSuccess, ...schedule }) => useSWR(key, fetcher, {
+		...Object.fromEntries(Object.entries(schedule).filter(([, value]) => value !== void 0)),
+		...once && {
+			revalidateIfStale: false,
+			revalidateOnFocus: false,
+			revalidateOnReconnect: false
+		},
+		...onError && { onError: (error) => onError(error) },
+		...onSuccess && { onSuccess: (data) => onSuccess(data) }
+	})
+});
+export { ReplicaScopeChangedError, createReplicaSlice, createSWRDriver, recordLens, splitPagedLens };
+
+//# sourceMappingURL=index.js.map