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
+39
View File
@@ -0,0 +1,39 @@
name: shared-core
# Only shared/core changes, root npm changes, or changes to this workflow, run it.
on:
pull_request:
paths:
- "shared/core/**"
- "package.json"
- "package-lock.json"
- ".npmrc"
- ".nvmrc"
- ".github/workflows/shared-core.yml"
push:
paths:
- "shared/core/**"
- "package.json"
- "package-lock.json"
- ".npmrc"
- ".nvmrc"
- ".github/workflows/shared-core.yml"
workflow_dispatch:
env:
FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
defaults:
run:
working-directory: shared/core
jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: actions/setup-node@v6
with:
node-version-file: ".nvmrc"
- run: npm ci
- run: npm run check
- run: npm run test:unit
+6 -2
View File
@@ -2,7 +2,7 @@
Monorepo for Radicle's graphical interfaces. It holds two projects, each with
its own Cargo workspace, toolchain files, checks and conventions, and the UI
code they share. One npm workspace at the root holds all three packages:
code they share. One npm workspace at the root holds all four packages:
- **Explorer** (`explorer/`): the Svelte web app for browsing Radicle
repositories, its TypeScript HTTP client, and the `radicle-httpd` and
@@ -11,6 +11,9 @@ code they share. One npm workspace at the root holds all three packages:
- **Shared UI** (`shared/ui/`): the `@radicle-gui/ui` package with Svelte
components, helpers, design tokens and fonts used by both apps. See
`shared/ui/AGENTS.md`.
- **Shared core** (`shared/core/`): the `@radicle-gui/core` package with
domain logic as plain TypeScript, such as query keys and the data that ref
updates affect. See `shared/core/AGENTS.md`.
This file covers what applies to both. Each project's `AGENTS.md` is the
source of truth for anything inside it.
@@ -22,9 +25,10 @@ source of truth for anything inside it.
| `explorer/` | Web app, HTTP client, `radicle-httpd` and `radicle-search` |
| `desktop/` | Tauri app: Svelte frontend in `src/`, Rust in `crates/` |
| `shared/ui/` | UI code shared by both apps |
| `shared/core/` | Domain logic shared by both apps and `shared/ui`, without Svelte or the DOM |
| `package.json`, `package-lock.json`, `.npmrc`, `.nvmrc` | The npm workspace, its lockfile and npm and Node settings |
| `docs/adr/` | Decisions that affect the whole repository |
| `.github/workflows/` | GitHub CI: `explorer-*.yml` for explorer, `desktop-*.yml` for desktop, `shared-ui.yml` for the shared UI |
| `.github/workflows/` | GitHub CI: `explorer-*.yml` for explorer, `desktop-*.yml` for desktop, `shared-ui.yml` and `shared-core.yml` for the shared packages |
| `.buildkite/` | Radicle CI pipelines (explorer only) |
| `.ryph/` | Dev machine image and setup for agents, see `.ryph/environment.md` |
+1
View File
@@ -32,6 +32,7 @@
"@floating-ui/dom": "^1.8.0",
"@pierre/diffs": "1.3.0-beta.9",
"@pierre/trees": "1.0.0-beta.5",
"@radicle-gui/core": "0.0.0",
"@radicle-gui/ui": "0.0.0",
"@tauri-apps/api": "^2.11.1",
"@tauri-apps/plugin-clipboard-manager": "^2.3.2",
+31
View File
@@ -6,6 +6,7 @@
"": {
"name": "radicle-gui",
"workspaces": [
"shared/core",
"shared/ui",
"explorer",
"desktop"
@@ -25,6 +26,7 @@
"@floating-ui/dom": "^1.8.0",
"@pierre/diffs": "1.3.0-beta.9",
"@pierre/trees": "1.0.0-beta.5",
"@radicle-gui/core": "0.0.0",
"@radicle-gui/ui": "0.0.0",
"@tauri-apps/api": "^2.11.1",
"@tauri-apps/plugin-clipboard-manager": "^2.3.2",
@@ -2170,6 +2172,10 @@
"dev": true,
"license": "MIT"
},
"node_modules/@radicle-gui/core": {
"resolved": "shared/core",
"link": true
},
"node_modules/@radicle-gui/ui": {
"resolved": "shared/ui",
"link": true
@@ -2715,6 +2721,16 @@
"@jridgewell/sourcemap-codec": "^1.6.0"
}
},
"node_modules/@tanstack/query-core": {
"version": "5.107.1",
"resolved": "https://registry.npmjs.org/@tanstack/query-core/-/query-core-5.107.1.tgz",
"integrity": "sha512-PSyAik11oQBEVOiVy5hjZWHmoUqOXqK1WYy4v55mcxozEfKaQgpUMsgnXhWjuESzSht8JfzqMS1m6M/9CpNgvg==",
"license": "MIT",
"funding": {
"type": "github",
"url": "https://github.com/sponsors/tannerlinsley"
}
},
"node_modules/@tauri-apps/api": {
"version": "2.11.1",
"resolved": "https://registry.npmjs.org/@tauri-apps/api/-/api-2.11.1.tgz",
@@ -9261,10 +9277,24 @@
"url": "https://github.com/sponsors/wooorm"
}
},
"shared/core": {
"name": "@radicle-gui/core",
"version": "0.0.0",
"devDependencies": {
"@eslint/js": "^10.0.1",
"eslint": "^10.7.0",
"prettier": "^3.9.5",
"typescript": "^6.0.3",
"typescript-eslint": "^8.64.0",
"vitest": "^4.1.12"
}
},
"shared/ui": {
"name": "@radicle-gui/ui",
"version": "0.0.0",
"dependencies": {
"@radicle-gui/core": "0.0.0",
"@tanstack/query-core": "^5.104.5",
"lru-cache": "^11.5.2"
},
"devDependencies": {
@@ -9277,6 +9307,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",
+1
View File
@@ -2,6 +2,7 @@
"name": "radicle-gui",
"private": true,
"workspaces": [
"shared/core",
"shared/ui",
"explorer",
"desktop"
+4
View File
@@ -0,0 +1,4 @@
{
"arrowParens": "avoid",
"proseWrap": "never"
}
+31
View File
@@ -0,0 +1,31 @@
# @radicle-gui/core
Domain logic shared by explorer, desktop and `@radicle-gui/ui`, as plain
TypeScript: types and pure functions, such as the query keys in
`src/keys.ts` and the keys a ref update affects in `src/refUpdates.ts`. See
`docs/adr/0004-shared-core.md` and `docs/adr/0005-reactivity.md` at the
repository root.
The package lives in `shared/core/` of the radicle-gui monorepo, in the root
npm workspace: install dependencies at the repository root with `npm ci`, and
run every other command here from `shared/core/`. Conventions shared with
both apps are in the root `AGENTS.md`.
## Rules
- No Svelte, DOM, Tauri or network dependencies, and no imports from either
app or from `@radicle-gui/ui`. The tsconfig leaves out DOM and Node types,
and eslint rejects the imports
- `@radicle-gui/ui` and the apps depend on core, never the other way round
- The apps import it as `@radicle-gui/core/<module>`
## Checks and tests
```sh
npm run check # tsc, eslint, prettier
npm run format # auto-fix prettier and eslint issues
npm run test:unit
```
CI runs these in `.github/workflows/shared-core.yml`. A change here affects
`shared/ui` and both apps, so also run their checks.
+38
View File
@@ -0,0 +1,38 @@
import js from "@eslint/js";
import ts from "typescript-eslint";
// Core is plain domain logic that both apps and shared/ui build on. Its
// tsconfig leaves out DOM and Node types; this keeps out the packages that
// would tie it to a framework, an app or a transport.
export default [
js.configs.recommended,
...ts.configs.recommended,
{
rules: {
"no-restricted-imports": [
"error",
{
patterns: [
{
group: ["svelte", "svelte/*"],
message: "Core has no Svelte dependencies.",
},
{
group: [
"@tauri-apps/*",
"@bindings/*",
"@app/*",
"@http-client/*",
],
message: "Core doesn't depend on either app.",
},
{
group: ["@radicle-gui/ui", "@radicle-gui/ui/*"],
message: "shared/ui depends on core, never the other way round.",
},
],
},
],
},
},
];
+22
View File
@@ -0,0 +1,22 @@
{
"name": "@radicle-gui/core",
"private": true,
"version": "0.0.0",
"type": "module",
"exports": {
"./*": "./src/*.ts"
},
"scripts": {
"check": "tsc --noEmit && eslint --max-warnings 0 . && prettier '**/*.@(ts|js|json)' --check",
"format": "prettier '**/*.@(ts|js|json)' --write && eslint --fix .",
"test:unit": "TZ='UTC' vitest run"
},
"devDependencies": {
"@eslint/js": "^10.0.1",
"eslint": "^10.7.0",
"prettier": "^3.9.5",
"typescript": "^6.0.3",
"typescript-eslint": "^8.64.0",
"vitest": "^4.1.12"
}
}
+31
View File
@@ -0,0 +1,31 @@
// Keys of the data that shared code reads, by domain identity. Every key of a
// repository starts with `["repo", rid]`, so that prefix covers all of it.
export type Key = readonly string[];
export const keys = {
repo: (rid: string) => ["repo", rid] as const,
repoInfo: (rid: string) => ["repo", rid, "info"] as const,
code: (rid: string) => ["repo", rid, "code"] as const,
issues: (rid: string) => ["repo", rid, "issues"] as const,
issue: (rid: string, id: string) => ["repo", rid, "issue", id] as const,
patches: (rid: string) => ["repo", rid, "patches"] as const,
patch: (rid: string, id: string) => ["repo", rid, "patch", id] as const,
};
// Lists of CI jobs, which scanning every job COB of a repository builds.
export function isJobsKey(key: Key): boolean {
return key[0] === "repo" && key[2] === "jobs";
}
export function isRepoInfoKey(key: Key): boolean {
return key[0] === "repo" && key[2] === "info";
}
// Data the node's COB cache holds: issues, patches and the counts in the
// repository info.
export function isCobCacheKey(key: Key): boolean {
return (
key[0] === "repo" &&
["info", "issues", "issue", "patches", "patch"].includes(key[2])
);
}
+51
View File
@@ -0,0 +1,51 @@
import type { Key } from "./keys";
import { keys } from "./keys";
// Refs that changed in a repository. Without `refs`, the backend doesn't know
// which refs changed, such as when the local user pushed.
export interface RefUpdate {
rid: string;
refs?: string[];
}
const ISSUE = "xyz.radicle.issue";
const PATCH = "xyz.radicle.patch";
export function affectedKeys({ rid, refs }: RefUpdate): Key[] {
if (refs === undefined) {
return [keys.repo(rid)];
}
const affected = new Map<string, Key>();
const add = (key: Key) => affected.set(key.join("\0"), key);
for (const ref of refs) {
const name = withoutNamespace(ref);
const cob = name.match(/^refs\/cobs\/([^/]+)\/([^/]+)$/);
if (cob && cob[1] === ISSUE) {
add(keys.issue(rid, cob[2]));
add(keys.issues(rid));
add(keys.repoInfo(rid));
} else if (cob && cob[1] === PATCH) {
add(keys.patch(rid, cob[2]));
add(keys.patches(rid));
add(keys.repoInfo(rid));
} else if (/^refs\/(heads|tags)\//.test(name)) {
add(keys.code(rid));
add(keys.repoInfo(rid));
} else if (name === "refs/rad/sigrefs") {
// Signed refs change along with the refs they sign.
} else {
// Identity documents and other COB types can affect anything shown.
return [keys.repo(rid)];
}
}
return [...affected.values()];
}
function withoutNamespace(ref: string): string {
return ref.replace(/^refs\/namespaces\/[^/]+\//, "");
}
+50
View File
@@ -0,0 +1,50 @@
import { describe, expect, test } from "vitest";
import { keys } from "../src/keys";
import { affectedKeys } from "../src/refUpdates";
const rid = "rad:z3gqcJUoA1n9HaHKufZs5FCSGazv5";
const nid = "z6MkkfM3tPXNPrPevKr3uSiQtHPuwnNhu2yUVjgd2jXVsVz5";
const issue = "d87dcfe8c2b3200e78b128d9b959cfdf7063fefe";
describe("affectedKeys", () => {
test("an update without refs affects the whole repository", () => {
expect(affectedKeys({ rid })).toEqual([keys.repo(rid)]);
});
test("an issue affects itself, the issue list and the repository info", () => {
expect(
affectedKeys({
rid,
refs: [
`refs/namespaces/${nid}/refs/cobs/xyz.radicle.issue/${issue}`,
`refs/namespaces/${nid}/refs/rad/sigrefs`,
],
}),
).toEqual([keys.issue(rid, issue), keys.issues(rid), keys.repoInfo(rid)]);
});
test("branches affect the code and the repository info once", () => {
expect(
affectedKeys({
rid,
refs: [
`refs/namespaces/${nid}/refs/heads/main`,
`refs/namespaces/${nid}/refs/tags/v1.0.0`,
],
}),
).toEqual([keys.code(rid), keys.repoInfo(rid)]);
});
test("an identity update affects the whole repository", () => {
expect(
affectedKeys({
rid,
refs: [
`refs/namespaces/${nid}/refs/cobs/xyz.radicle.patch/${issue}`,
`refs/namespaces/${nid}/refs/rad/id`,
],
}),
).toEqual([keys.repo(rid)]);
});
});
+16
View File
@@ -0,0 +1,16 @@
{
"include": ["src", "tests"],
"compilerOptions": {
"noEmit": true,
"target": "es2024",
"lib": ["es2024"],
"types": [],
"module": "es2022",
"moduleResolution": "bundler",
"strict": true,
"noUnusedLocals": true,
"noUnusedParameters": true,
"verbatimModuleSyntax": true,
"skipLibCheck": true
}
}
+8
View File
@@ -0,0 +1,8 @@
import { defineConfig } from "vitest/config";
export default defineConfig({
test: {
include: ["tests/**/*.test.ts"],
reporters: "verbose",
},
});
+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 },
});