mirror of
https://seed.radicle.dev/rad:z4V1sjrXqjvFdnCUbxPFqd5p4DtH5.git
synced 2026-11-21 06:10:44 +08:00
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:
@@ -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
|
||||
@@ -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` |
|
||||
|
||||
|
||||
@@ -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",
|
||||
|
||||
Generated
+31
@@ -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",
|
||||
|
||||
@@ -2,6 +2,7 @@
|
||||
"name": "radicle-gui",
|
||||
"private": true,
|
||||
"workspaces": [
|
||||
"shared/core",
|
||||
"shared/ui",
|
||||
"explorer",
|
||||
"desktop"
|
||||
|
||||
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"arrowParens": "avoid",
|
||||
"proseWrap": "never"
|
||||
}
|
||||
@@ -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.
|
||||
@@ -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.",
|
||||
},
|
||||
],
|
||||
},
|
||||
],
|
||||
},
|
||||
},
|
||||
];
|
||||
@@ -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"
|
||||
}
|
||||
}
|
||||
@@ -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])
|
||||
);
|
||||
}
|
||||
@@ -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\/[^/]+\//, "");
|
||||
}
|
||||
@@ -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)]);
|
||||
});
|
||||
});
|
||||
@@ -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
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,8 @@
|
||||
import { defineConfig } from "vitest/config";
|
||||
|
||||
export default defineConfig({
|
||||
test: {
|
||||
include: ["tests/**/*.test.ts"],
|
||||
reporters: "verbose",
|
||||
},
|
||||
});
|
||||
+20
-1
@@ -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
|
||||
|
||||
@@ -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();
|
||||
},
|
||||
};
|
||||
}
|
||||
@@ -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",
|
||||
|
||||
@@ -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,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 },
|
||||
});
|
||||
|
||||
Reference in New Issue
Block a user