Add shared core package and query cache

Core holds the keys of the data both apps read and maps a node's ref
updates to the keys they affect. The query cache wraps TanStack Query for
runes, as decided in ADRs 4 and 5.
This commit is contained in:
Rūdolfs Ošiņš
2026-11-20 19:32:16 +01:00
parent 5937288817
commit ee80f7d6f4
19 changed files with 915 additions and 3 deletions
+20 -1
View File
@@ -64,10 +64,29 @@ the components:
heartwood
- Define them in `lib/types.ts`, named after domain concepts such as `Author`
or `Reaction`. The first extraction that needs a domain type creates the
file. ADR 4 moves them to `@radicle-gui/core` once that package exists
file. ADR 4 moves them to `@radicle-gui/core`
- Apps pass their own objects when the shapes match, and map them in one place
where they don't. Never import an app's types here
## Query cache
`lib/query.svelte.ts` wraps TanStack Query for the apps' views, as decided in
`docs/adr/0005-reactivity.md`. Only the apps use it; shared components keep
taking props.
- `createQuery` observes one key in the cache. `onInvalidate` runs a
component's own refresh when its key is invalidated, for data the cache
doesn't hold, and several components may listen on one key
- A route loader calls `markLoading` on a key before reading what a component
then refreshes with `onInvalidate`, so that an invalidation during the load
refreshes it at mount. `invalidatedSinceLoading` tells whether one came
- Invalidate with `invalidate` rather than the client's
`invalidateQueries`, so that a fetch in flight doesn't leave data from
before the change looking fresh. Use the client's only to join a refetch
already in flight
- `pinned` holds a value the user is reading until they ask for the latest
- Keys come from `@radicle-gui/core/keys`, never ad-hoc arrays
## Stylesheets and fonts
The `sharedPublic()` Vite plugin in `vite.ts` serves `public/` at each app's
+249
View File
@@ -0,0 +1,249 @@
import type { Key } from "@radicle-gui/core/keys";
import type {
InvalidateQueryFilters,
Query as CachedQuery,
QueryObserverResult,
} from "@tanstack/query-core";
import { hashKey, QueryClient, QueryObserver } from "@tanstack/query-core";
import { createSubscriber } from "svelte/reactivity";
// Data is only refetched when a change event invalidates it, never because
// time passed or the window regained focus.
export function createQueryClient(): QueryClient {
return new QueryClient({
defaultOptions: {
queries: {
staleTime: Infinity,
refetchOnWindowFocus: false,
refetchOnReconnect: false,
// The data comes from a local backend or a seed the user chose, so
// fetches never wait for the browser to say it is online.
networkMode: "always",
// A retry pauses while the window is hidden, and nothing resumes it
// because the client doesn't track focus.
retry: false,
},
},
});
}
export interface QueryOptions<T> {
queryKey: Key;
queryFn: () => Promise<T>;
enabled?: boolean;
}
// Queries whose fetch in flight read data from before an invalidation, by
// client. Each is invalidated once that fetch settles.
const readBeforeChange = new WeakMap<QueryClient, WeakSet<CachedQuery>>();
function invalidateOnSettle(client: QueryClient, query: CachedQuery): void {
let pending = readBeforeChange.get(client);
if (!pending) {
const set = new WeakSet<CachedQuery>();
pending = set;
readBeforeChange.set(client, set);
client.getQueryCache().subscribe(event => {
if (event.type !== "updated" || !set.has(event.query)) return;
if (event.action.type !== "success" && event.action.type !== "error") {
return;
}
set.delete(event.query);
queueMicrotask(
() =>
void client.invalidateQueries({
queryKey: event.query.queryKey,
exact: true,
}),
);
});
}
pending.add(query);
}
// Invalidates like `client.invalidateQueries`, and also handles the fetches in
// flight that it wouldn't restart: those nothing observes yet, such as a route
// loader's, and first fetches. Their result, read before the change, would
// otherwise count as fresh, so they are invalidated once they settle. They
// aren't restarted, so that a stream of updates can't keep a slow fetch from
// ever finishing.
export async function invalidate(
client: QueryClient,
filters: InvalidateQueryFilters<Key> = {},
): Promise<void> {
for (const query of client
.getQueryCache()
.findAll({ ...filters, fetchStatus: "fetching" })) {
if (!query.isActive() || query.state.data === undefined) {
invalidateOnSettle(client, query);
}
}
await client.invalidateQueries(filters);
}
export interface Query<T> {
readonly current: QueryObserverResult<T>;
}
// Observes one key in the cache while something reads `current`. Create it
// during component initialisation, so that it follows changes to `options`.
export function createQuery<T>(
client: QueryClient,
options: () => QueryOptions<T>,
): Query<T> {
const observer = new QueryObserver<T, Error, T, T, Key>(client, options());
$effect.pre(() => {
observer.setOptions(options());
});
const subscribe = createSubscriber(update => observer.subscribe(update));
return {
get current() {
subscribe();
return observer.getCurrentResult();
},
};
}
// When data a component keeps with `onInvalidate` last refreshed. It sits under
// its data's key, so invalidating that key or a prefix of it reaches it, but in
// a slot of its own, so the cache never mistakes it for the data.
function refreshedKey(key: Key): Key {
return [...key, "\0refreshed"];
}
// Marks `key` as refreshed now, for a route loader to call before it reads the
// data a component then keeps with `onInvalidate`. An invalidation from then
// on, even one that arrives before the component mounts, refreshes it.
export function markLoading(client: QueryClient, key: Key): void {
client.setQueryData(refreshedKey(key), Date.now());
}
export function invalidatedSinceLoading(
client: QueryClient,
key: Key,
): boolean {
return client.getQueryState(refreshedKey(key))?.isInvalidated ?? false;
}
// Components listening on each key. A key has one query, which runs only one
// query function, so that function runs every listener's refresh.
const listeners = new WeakMap<
QueryClient,
Map<string, Set<() => Promise<void>>>
>();
function listenersOf(client: QueryClient, key: Key): Set<() => Promise<void>> {
let byKey = listeners.get(client);
if (!byKey) {
// eslint-disable-next-line svelte/prefer-svelte-reactivity -- never rendered
byKey = new Map();
listeners.set(client, byKey);
}
const hash = hashKey(key);
let set = byKey.get(hash);
if (!set) {
set = new Set();
byKey.set(hash, set);
}
return set;
}
// Runs `refresh` whenever `key` is invalidated, for data a component keeps
// itself rather than in the cache. The cache only holds when it last
// refreshed. Create it during component initialisation. Whatever loaded the
// data counts as the first refresh: a route loader marks that with
// `markLoading`, and data loaded otherwise is taken as current.
//
// Refreshes never overlap: an invalidation during one runs another after it,
// so results land in order. A failed refresh is logged, and the next
// invalidation tries again.
export function onInvalidate(
client: QueryClient,
key: () => Key,
refresh: () => Promise<void>,
): void {
let running: Promise<void> | undefined;
let again = false;
let destroyed = false;
function refreshInOrder(): Promise<void> {
if (running) {
again = true;
return running;
}
running = (async () => {
do {
again = false;
if (destroyed) break;
try {
await refresh();
} catch (error) {
console.error("Refreshing after an update failed", error);
}
} while (again);
running = undefined;
})();
return running;
}
$effect.pre(() => {
destroyed = false;
const queryKey = refreshedKey(key());
const set = listenersOf(client, queryKey);
set.add(refreshInOrder);
return () => {
destroyed = true;
set.delete(refreshInOrder);
if (set.size === 0) listeners.get(client)?.delete(hashKey(queryKey));
};
});
$effect.pre(() => {
const queryKey = refreshedKey(key());
if (client.getQueryState(queryKey)?.data === undefined) {
client.setQueryData(queryKey, Date.now());
}
});
const refreshed = createQuery<number>(client, () => {
const queryKey = refreshedKey(key());
return {
queryKey,
queryFn: async () => {
await Promise.all(
[...listenersOf(client, queryKey)].map(listener => listener()),
);
return Date.now();
},
};
});
$effect(() => {
void refreshed.current;
});
}
export interface Pinned<T> {
readonly current: T;
// Whether newer data than `current` is available.
readonly stale: boolean;
apply(): void;
}
// Holds on to a value until `apply()` is called. The cache keeps the identity
// of unchanged data, so a different object means the data changed.
export function pinned<T>(latest: () => T): Pinned<T> {
let snapshot = $state.raw(latest());
return {
get current() {
return snapshot;
},
get stale() {
return latest() !== snapshot;
},
apply() {
snapshot = latest();
},
};
}
+3
View File
@@ -18,6 +18,8 @@
"svelte": "^5.56.6"
},
"dependencies": {
"@radicle-gui/core": "0.0.0",
"@tanstack/query-core": "^5.104.5",
"lru-cache": "^11.5.2"
},
"devDependencies": {
@@ -30,6 +32,7 @@
"eslint-plugin-simple-import-sort": "^14.0.0",
"eslint-plugin-svelte": "^3.22.0",
"globals": "^17.7.0",
"happy-dom": "^21.0.4",
"prettier": "^3.9.5",
"prettier-plugin-svelte": "^4.1.1",
"svelte": "^5.56.6",
+311
View File
@@ -0,0 +1,311 @@
import type { QueryClient } from "@tanstack/query-core";
import { flushSync } from "svelte";
import { afterEach, beforeEach, expect, test, vi } from "vitest";
import {
createQuery,
createQueryClient,
invalidate,
invalidatedSinceLoading,
markLoading,
onInvalidate,
pinned,
} from "../lib/query.svelte";
const key = ["repo", "rad:z1", "issues"] as const;
let client: QueryClient;
const cleanups: (() => void)[] = [];
function listen(refresh: () => Promise<void>) {
cleanups.push(
$effect.root(() => {
onInvalidate(client, () => key, refresh);
}),
);
flushSync();
}
function deferred<T = void>() {
let resolve!: (value: T) => void;
const promise = new Promise<T>(res => {
resolve = res;
});
return { promise, resolve };
}
beforeEach(() => {
client = createQueryClient();
});
afterEach(() => {
for (const cleanup of cleanups.splice(0)) cleanup();
client.clear();
});
test("takes the loaded data as current", async () => {
const refresh = vi.fn(() => Promise.resolve());
listen(refresh);
await Promise.resolve();
expect(refresh).not.toHaveBeenCalled();
});
test("refreshes when the key is invalidated", async () => {
const refresh = vi.fn(() => Promise.resolve());
listen(refresh);
await client.invalidateQueries({ queryKey: key });
expect(refresh).toHaveBeenCalledTimes(1);
});
test("refreshes every listener on the same key", async () => {
const first = vi.fn(() => Promise.resolve());
const second = vi.fn(() => Promise.resolve());
listen(first);
listen(second);
await client.invalidateQueries({ queryKey: key });
expect(first).toHaveBeenCalledTimes(1);
expect(second).toHaveBeenCalledTimes(1);
});
test("refreshes at mount after an invalidation during the load", async () => {
markLoading(client, key);
await client.invalidateQueries({ queryKey: key });
const refresh = vi.fn(() => Promise.resolve());
listen(refresh);
await vi.waitFor(() => expect(refresh).toHaveBeenCalledTimes(1));
});
test("ignores an invalidation from before the load", async () => {
markLoading(client, key);
await client.invalidateQueries({ queryKey: key });
markLoading(client, key);
const refresh = vi.fn(() => Promise.resolve());
listen(refresh);
await Promise.resolve();
expect(refresh).not.toHaveBeenCalled();
});
test("runs an invalidation during a refresh after it", async () => {
const first = deferred();
let running = 0;
let overlapped = false;
const refresh = vi.fn(async () => {
running++;
if (running > 1) overlapped = true;
if (refresh.mock.calls.length === 1) await first.promise;
running--;
});
listen(refresh);
const firstRefresh = client.invalidateQueries({ queryKey: key });
await vi.waitFor(() => expect(refresh).toHaveBeenCalledTimes(1));
// As events do, cancelling the refetch in flight.
const secondRefresh = client.invalidateQueries({ queryKey: key });
first.resolve();
await Promise.all([firstRefresh, secondRefresh]);
await vi.waitFor(() => expect(refresh).toHaveBeenCalledTimes(2));
expect(overlapped).toBe(false);
});
test("follows a key change, refreshing for an update during its load", async () => {
const other = ["repo", "rad:z1", "patches"] as const;
let current = $state<readonly string[]>(key);
const refresh = vi.fn(() => Promise.resolve());
cleanups.push(
$effect.root(() => {
onInvalidate(client, () => current, refresh);
}),
);
flushSync();
markLoading(client, other);
await client.invalidateQueries({ queryKey: other });
current = other;
flushSync();
await vi.waitFor(() => expect(refresh).toHaveBeenCalledTimes(1));
// The old key no longer refreshes this component, only those still on it.
const stayed = vi.fn(() => Promise.resolve());
listen(stayed);
await client.invalidateQueries({ queryKey: key });
expect(stayed).toHaveBeenCalledTimes(1);
expect(refresh).toHaveBeenCalledTimes(1);
});
test("a pinned value changes only when applied", () => {
let latest = $state({ body: "first" });
let value!: ReturnType<typeof pinned<{ body: string }>>;
cleanups.push(
$effect.root(() => {
value = pinned(() => latest);
}),
);
latest = { body: "second" };
expect(value.current.body).toBe("first");
expect(value.stale).toBe(true);
value.apply();
expect(value.current.body).toBe("second");
expect(value.stale).toBe(false);
});
test("a loader's fetch is stale once it settles if invalidated meanwhile", async () => {
const before = deferred<string>();
const queryFn = vi.fn(() => before.promise);
const loaded = client.fetchQuery({ queryKey: key, queryFn });
await invalidate(client, { queryKey: key });
before.resolve("before");
expect(await loaded).toBe("before");
expect(queryFn).toHaveBeenCalledTimes(1);
await vi.waitFor(() =>
expect(client.getQueryState(key)?.isInvalidated).toBe(true),
);
});
test("an observed first fetch refetches once it settles if invalidated meanwhile", async () => {
const before = deferred<string>();
const queryFn = vi
.fn<() => Promise<string>>()
.mockReturnValueOnce(before.promise)
.mockResolvedValue("after");
let query!: ReturnType<typeof createQuery<string>>;
cleanups.push(
$effect.root(() => {
query = createQuery(client, () => ({ queryKey: key, queryFn }));
$effect(() => {
void query.current;
});
}),
);
flushSync();
const invalidated = [
invalidate(client, { queryKey: key }),
invalidate(client, { queryKey: key }),
];
before.resolve("before");
await Promise.all(invalidated);
await vi.waitFor(() => expect(query.current.data).toBe("after"));
expect(queryFn).toHaveBeenCalledTimes(2);
});
test("an idle query is only marked stale", async () => {
const queryFn = vi.fn(() => Promise.resolve("data"));
await client.fetchQuery({ queryKey: key, queryFn });
await invalidate(client, { queryKey: key });
expect(queryFn).toHaveBeenCalledTimes(1);
expect(client.getQueryState(key)?.isInvalidated).toBe(true);
});
test("an observed query refetches on invalidation and follows key changes", async () => {
const other = ["repo", "rad:z1", "patches"] as const;
let current = $state<readonly string[]>(key);
const queryFn = vi.fn(async () => current.join("/"));
let query!: ReturnType<typeof createQuery<string>>;
cleanups.push(
$effect.root(() => {
query = createQuery(client, () => ({ queryKey: current, queryFn }));
$effect(() => {
void query.current;
});
}),
);
flushSync();
await vi.waitFor(() => expect(query.current.data).toBe(key.join("/")));
await invalidate(client, { queryKey: key });
expect(queryFn).toHaveBeenCalledTimes(2);
current = other;
flushSync();
await vi.waitFor(() => expect(query.current.data).toBe(other.join("/")));
});
test("a disabled query doesn't fetch", async () => {
const queryFn = vi.fn(() => Promise.resolve("data"));
cleanups.push(
$effect.root(() => {
const query = createQuery(client, () => ({
queryKey: key,
queryFn,
enabled: false,
}));
$effect(() => {
void query.current;
});
}),
);
flushSync();
await Promise.resolve();
expect(queryFn).not.toHaveBeenCalled();
});
test("keeps refresh times apart from the data under the same key", async () => {
client.setQueryData(key, "data");
markLoading(client, key);
listen(() => Promise.resolve());
expect(client.getQueryData(key)).toBe("data");
expect(invalidatedSinceLoading(client, key)).toBe(false);
await client.invalidateQueries({ queryKey: key });
markLoading(client, key);
expect(invalidatedSinceLoading(client, key)).toBe(false);
});
test("tells whether a key was invalidated since loading", async () => {
markLoading(client, key);
await client.invalidateQueries({ queryKey: ["repo"] });
expect(invalidatedSinceLoading(client, key)).toBe(true);
});
test("stops refreshing once destroyed", async () => {
const first = deferred();
const refresh = vi.fn(async () => {
if (refresh.mock.calls.length === 1) await first.promise;
});
listen(refresh);
const firstRefresh = client.invalidateQueries({ queryKey: key });
await vi.waitFor(() => expect(refresh).toHaveBeenCalledTimes(1));
const secondRefresh = client.invalidateQueries({ queryKey: key });
for (const cleanup of cleanups.splice(0)) cleanup();
first.resolve();
await Promise.all([firstRefresh, secondRefresh]);
expect(refresh).toHaveBeenCalledTimes(1);
});
test("a failed refresh is retried on the next invalidation", async () => {
const refresh = vi
.fn<() => Promise<void>>()
.mockRejectedValueOnce(new Error("down"))
.mockResolvedValueOnce();
const error = vi.spyOn(console, "error").mockImplementation(() => undefined);
listen(refresh);
await client.invalidateQueries({ queryKey: key });
await client.invalidateQueries({ queryKey: key });
expect(refresh).toHaveBeenCalledTimes(2);
expect(error).toHaveBeenCalledTimes(1);
error.mockRestore();
});
+3
View File
@@ -3,8 +3,11 @@ import { defineConfig } from "vitest/config";
export default defineConfig({
test: {
environment: "happy-dom",
include: ["tests/**/*.test.ts"],
reporters: "verbose",
},
plugins: [svelte()],
// Svelte's server build never runs effects, which rune tests need.
resolve: { conditions: process.env.VITEST ? ["browser"] : undefined },
});