From ee80f7d6f441053ffa158676e175602a203e18ee Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C5=ABdolfs=20O=C5=A1i=C5=86=C5=A1?= Date: Wed, 18 Nov 2026 11:01:00 +0100 Subject: [PATCH] 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. --- .github/workflows/shared-core.yml | 39 ++++ AGENTS.md | 8 +- desktop/package.json | 1 + package-lock.json | 31 +++ package.json | 1 + shared/core/.prettierrc | 4 + shared/core/AGENTS.md | 31 +++ shared/core/eslint.config.js | 38 ++++ shared/core/package.json | 22 ++ shared/core/src/keys.ts | 31 +++ shared/core/src/refUpdates.ts | 51 +++++ shared/core/tests/refUpdates.test.ts | 50 +++++ shared/core/tsconfig.json | 16 ++ shared/core/vitest.config.ts | 8 + shared/ui/AGENTS.md | 21 +- shared/ui/lib/query.svelte.ts | 249 +++++++++++++++++++++ shared/ui/package.json | 3 + shared/ui/tests/query.svelte.test.ts | 311 +++++++++++++++++++++++++++ shared/ui/vite.config.ts | 3 + 19 files changed, 915 insertions(+), 3 deletions(-) create mode 100644 .github/workflows/shared-core.yml create mode 100644 shared/core/.prettierrc create mode 100644 shared/core/AGENTS.md create mode 100644 shared/core/eslint.config.js create mode 100644 shared/core/package.json create mode 100644 shared/core/src/keys.ts create mode 100644 shared/core/src/refUpdates.ts create mode 100644 shared/core/tests/refUpdates.test.ts create mode 100644 shared/core/tsconfig.json create mode 100644 shared/core/vitest.config.ts create mode 100644 shared/ui/lib/query.svelte.ts create mode 100644 shared/ui/tests/query.svelte.test.ts diff --git a/.github/workflows/shared-core.yml b/.github/workflows/shared-core.yml new file mode 100644 index 000000000..cd61a8f98 --- /dev/null +++ b/.github/workflows/shared-core.yml @@ -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 diff --git a/AGENTS.md b/AGENTS.md index ea5588e57..e03c64ef8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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` | diff --git a/desktop/package.json b/desktop/package.json index 85be181f8..e3e282e84 100644 --- a/desktop/package.json +++ b/desktop/package.json @@ -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", diff --git a/package-lock.json b/package-lock.json index 3f6105528..17c56c562 100644 --- a/package-lock.json +++ b/package-lock.json @@ -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", diff --git a/package.json b/package.json index 2ff58c6e7..32c26626e 100644 --- a/package.json +++ b/package.json @@ -2,6 +2,7 @@ "name": "radicle-gui", "private": true, "workspaces": [ + "shared/core", "shared/ui", "explorer", "desktop" diff --git a/shared/core/.prettierrc b/shared/core/.prettierrc new file mode 100644 index 000000000..10634c71f --- /dev/null +++ b/shared/core/.prettierrc @@ -0,0 +1,4 @@ +{ + "arrowParens": "avoid", + "proseWrap": "never" +} diff --git a/shared/core/AGENTS.md b/shared/core/AGENTS.md new file mode 100644 index 000000000..507d4f23a --- /dev/null +++ b/shared/core/AGENTS.md @@ -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/` + +## 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. diff --git a/shared/core/eslint.config.js b/shared/core/eslint.config.js new file mode 100644 index 000000000..d7e88cb31 --- /dev/null +++ b/shared/core/eslint.config.js @@ -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.", + }, + ], + }, + ], + }, + }, +]; diff --git a/shared/core/package.json b/shared/core/package.json new file mode 100644 index 000000000..8b0f23251 --- /dev/null +++ b/shared/core/package.json @@ -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" + } +} diff --git a/shared/core/src/keys.ts b/shared/core/src/keys.ts new file mode 100644 index 000000000..b0bca289f --- /dev/null +++ b/shared/core/src/keys.ts @@ -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]) + ); +} diff --git a/shared/core/src/refUpdates.ts b/shared/core/src/refUpdates.ts new file mode 100644 index 000000000..38360e293 --- /dev/null +++ b/shared/core/src/refUpdates.ts @@ -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(); + 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\/[^/]+\//, ""); +} diff --git a/shared/core/tests/refUpdates.test.ts b/shared/core/tests/refUpdates.test.ts new file mode 100644 index 000000000..867819dec --- /dev/null +++ b/shared/core/tests/refUpdates.test.ts @@ -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)]); + }); +}); diff --git a/shared/core/tsconfig.json b/shared/core/tsconfig.json new file mode 100644 index 000000000..f943689c9 --- /dev/null +++ b/shared/core/tsconfig.json @@ -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 + } +} diff --git a/shared/core/vitest.config.ts b/shared/core/vitest.config.ts new file mode 100644 index 000000000..da5177688 --- /dev/null +++ b/shared/core/vitest.config.ts @@ -0,0 +1,8 @@ +import { defineConfig } from "vitest/config"; + +export default defineConfig({ + test: { + include: ["tests/**/*.test.ts"], + reporters: "verbose", + }, +}); diff --git a/shared/ui/AGENTS.md b/shared/ui/AGENTS.md index 719e441c3..0163670f3 100644 --- a/shared/ui/AGENTS.md +++ b/shared/ui/AGENTS.md @@ -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 diff --git a/shared/ui/lib/query.svelte.ts b/shared/ui/lib/query.svelte.ts new file mode 100644 index 000000000..205eaac5f --- /dev/null +++ b/shared/ui/lib/query.svelte.ts @@ -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 { + queryKey: Key; + queryFn: () => Promise; + 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>(); + +function invalidateOnSettle(client: QueryClient, query: CachedQuery): void { + let pending = readBeforeChange.get(client); + if (!pending) { + const set = new WeakSet(); + 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 = {}, +): Promise { + 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 { + readonly current: QueryObserverResult; +} + +// 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( + client: QueryClient, + options: () => QueryOptions, +): Query { + const observer = new QueryObserver(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 Promise>> +>(); + +function listenersOf(client: QueryClient, key: Key): Set<() => Promise> { + 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 { + let running: Promise | undefined; + let again = false; + let destroyed = false; + function refreshInOrder(): Promise { + 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(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 { + 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(latest: () => T): Pinned { + let snapshot = $state.raw(latest()); + + return { + get current() { + return snapshot; + }, + get stale() { + return latest() !== snapshot; + }, + apply() { + snapshot = latest(); + }, + }; +} diff --git a/shared/ui/package.json b/shared/ui/package.json index 8a462943a..9c0780534 100644 --- a/shared/ui/package.json +++ b/shared/ui/package.json @@ -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", diff --git a/shared/ui/tests/query.svelte.test.ts b/shared/ui/tests/query.svelte.test.ts new file mode 100644 index 000000000..9984906be --- /dev/null +++ b/shared/ui/tests/query.svelte.test.ts @@ -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) { + cleanups.push( + $effect.root(() => { + onInvalidate(client, () => key, refresh); + }), + ); + flushSync(); +} + +function deferred() { + let resolve!: (value: T) => void; + const promise = new Promise(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(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>; + 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(); + 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(); + const queryFn = vi + .fn<() => Promise>() + .mockReturnValueOnce(before.promise) + .mockResolvedValue("after"); + let query!: ReturnType>; + 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(key); + const queryFn = vi.fn(async () => current.join("/")); + let query!: ReturnType>; + 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>() + .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(); +}); diff --git a/shared/ui/vite.config.ts b/shared/ui/vite.config.ts index 0c9cccc48..76a49b801 100644 --- a/shared/ui/vite.config.ts +++ b/shared/ui/vite.config.ts @@ -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 }, });