fetchium 0.1.0 → 0.2.0

package/plugin/docs/core/types.md

@@ -0,0 +1,374 @@
+---
+title: Types
+---
+
+Fetchium includes a DSL for defining the shape of your data - parameters, results, and entity fields. Fetchium uses these shapes to **parse API responses**, **normalize entities** into the cache, and **infer TypeScript types** so your queries are fully typed end-to-end.
+
+This type validation system is focused on validating **JSON**. It is not a general-purpose validator, such as tools like [Zod](https://zod.dev/), which can be used to validate and parse nearly _any_ object that can be described with _TypeScript_. They support input values like _functions_, _custom classes_, objects with _circular references_, and so on.
+
+By contrast, Fetchium's scope is _intentionally narrow_ and focused on _performance and evolution_. The DSL only includes the bare necessities to describe the _majority_ of JSON based APIs, with certain edge-case anti-patterns excluded entirely. It also includes an opinionated set of default behaviors designed to help you build robust APIs that can change over time.
+
+## DSL Reference
+
+The type DSL includes the usual suspects of such systems:
+
+- Base primitives
+- Objects/Arrays/Records
+- Unions
+- Helpers for optional/nullable/nullish union types
+
+| Definition          | TypeScript type          |
+| ------------------- | ------------------------ |
+| `t.string`          | `string`                 |
+| `t.number`          | `number`                 |
+| `t.boolean`         | `boolean`                |
+| `t.null`            | `null`                   |
+| `t.undefined`       | `undefined`              |
+| `t.object({ ... })` | `{ ... }`                |
+| `t.array(type)`     | `T[]`                    |
+| `t.record(type)`    | `Record<string, T>`      |
+| `t.union(...types)` | Union of types           |
+| `t.optional(type)`  | `T \| undefined`         |
+| `t.nullable(type)`  | `T \| null`              |
+| `t.nullish(type)`   | `T \| undefined \| null` |
+
+These can be combined in standard, predictable ways:
+
+```ts
+t.union(t.string, t.number);
+
+t.object({ foo: t.string, bar: t.number });
+
+t.array(t.nullable(t.boolean));
+```
+
+Notably there are no _chaining_ APIs, e.g. `t.string.optional`. While convenient and readable, chaining APIs add a lot of _weight_. Every primitive type becomes an object, and every combination of primitive types becomes a _new_ object. Under the hood, Fetchium represents primitive types as _number masks_, meaning that for a type definition like:
+
+```ts
+t.object({
+  name: t.string,
+  desc: t.optional(t.string),
+  currentState: t.union(t.string, t.number),
+});
+```
+
+Only a single object is created - the object definition. Every other type union is a masking operation, and the result is an object of numbers.
+
+In addition to these basic primitives, there are a number of additional special type validators:
+
+| Definition                          | TypeScript type         | Desc                                                                                                                                                                                              |
+| ----------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `t.const(value)`                    | Literal type of `value` | Constant value                                                                                                                                                                                    |
+| `t.enum(...values)`                 | Union of literals       | One of a set of constant values                                                                                                                                                                   |
+| `t.enum.caseInsensitive(...values)` | Union of literals       | Case-insensitive set of values. All values get coerced to the casing in the _definition_. While not _recommended_, this is helpful for legacy APIs which may have inconsistent casing             |
+| `t.typename(value)`                 | Literal string          | Type identifier for object and [Entity](/core/entities) types                                                                                                                                     |
+| `t.id`                              | `string \| number`      | Identifier for [Entity](/core/entities) types                                                                                                                                                     |
+| `t.result(type)`                    | `ParseResult<T>`        | Parse result for explicit handling of parse errors                                                                                                                                                |
+| `t.format(name)`                    | Registered format type  | Formatted string or number value, such as `date` or `date-time`. Formatted values are serialized and deserialized via a registered format function, and types are registered in a global registry |
+| `t.entity(EntityClass)`             | Entity class instance   | An instance of the given [Entity](/core/entities) class                                                                                                                                           |
+
+## Designed for Evolving APIs
+
+APIs change. New fields are added, new types appear in lists, response shapes grow. There are many small changes like these that generally don't warrant a "v2" of the API, and that may _appear_ additive and safely non-breaking at first, but that cause regressions when shipped in an app.
+
+For instance, consider the following API Response:
+
+```ts
+interface TextItem {
+  type: 'text';
+  content: string;
+}
+
+interface ImageItem {
+  type: 'image';
+  url: string;
+  caption: string;
+}
+
+type FeedItem = TextItem | ImageItem;
+
+interface FeedResponse {
+  items: FeedItem[];
+}
+```
+
+Here we have a feed with two types of items, perhaps the initial MVP implementation of our feed page. We get it out the door and onto devices, and immediately product turns around and asks to add a Video feed item.
+
+Now, if the developer of the client portion was thoughtful during the build out, they would have realized that even though there are only two items available currently, there _may_ be more in the future, and their implementation would have done something like the following:
+
+```tsx
+import { ImageFeedItem, TextFeedItem } from './feed-components';
+
+export function Feed() {
+  const { items, isReady } = useFeedItems();
+
+  if (!isReady) return <div>Loading...</div>;
+
+  return (
+    <div>
+      {items.map((item) => {
+        switch (item.type) {
+          case 'text':
+            return <TextFeedItem item={item} />;
+          case 'image':
+            return <ImageFeedItem item={item} />;
+          default:
+            // Unknown feed item type, render nothing, log to telemetry
+            telemetry.log('unknown feed item type');
+        }
+      })}
+    </div>
+  );
+}
+```
+
+But maybe they didn't think about this, and instead threw an error if an unknown type was added. Or even before that, maybe their _type validators_ didn't account for the possibility of new types, and they throw an error on parse.
+
+Fetchium's philosophy is based on _resilience_ to changes like these, and it achieves this through a core assumption:
+
+> Showing _nothing_ is a better default than throwing an error.
+
+This is not always true, there are times when you do want to show errors and tell users about explicit failures. But additive changes which have no impact on _existing clients_ out in the world should not cause failures by default. In the world of _native app_ development, where users may not upgrade for some time, this becomes exceedingly relevant.
+
+Fetchium achieves this with two main default behaviors:
+
+1. **Optional fields fall back gracefully.** If a field is wrapped in `t.optional(...)` and the incoming value doesn't match, it falls back to `undefined` instead of throwing a failure. This allows you to turn
+   - `t.optional(t.string)` into
+   - `t.optional(t.union(t.string, t.number))`
+     Without it being a breaking change to older clients.
+2. **Arrays filter out unparseable items.** If an element in an array fails to parse, it's silently removed from the result rather than failing the entire response. This lets you add new types to a polymorphic array - clients that don't know about the new type simply don't see those items.
+
+These two default behaviors are _safe_ because in both cases, we know that the code itself must be capable of handling it. In the case of optional fields, developers must already handle the `undefined` branch, and in the case of arrays, we simply skip over the unparsed items as if they didn't exist.
+
+{% callout title="Logging parse failure events" type="note" %}
+While these types of failures are typically expected, you may still want to know about them to understand if many clients are seeing a dramatic uptick in them. If every item in the array fails to parse, and users are seeing nothing in their feed, that is notable and still not ideal.
+
+Failures can be captured by passing in a custom `log` object when creating the QueryClient. These failures are captured via `log.warn`, which has the same type signature as `console.warn`.
+{% /callout %}
+
+### Parse Results
+
+You can also handle these failures more explicitly with `t.result`:
+
+```ts
+// Produces string | undefined
+t.optional(t.string);
+
+// Produces ParseResult<string>
+t.result(t.string);
+```
+
+When you wrap a type in `t.result`, it returns a parse result of the value:
+
+```ts
+interface ParseSuccess<T> {
+  success: true;
+  value: T;
+}
+
+interface ParseError {
+  success: false;
+  error: unknown;
+}
+
+type ParseResult<T> = ParseSuccess<T> | ParseError;
+```
+
+Parse results fail explicitly instead of silently and force the user to handle the error, ensure that it is safe to fail. They only apply to the _immediate_ child, so nested properties will still default to `undefined` if possible before attempting to throw.
+
+## Unions and Performance
+
+Unions are one of the trickiest parts of any parsing system. In particular, there are two main areas where things get difficult:
+
+1. Unions of multiple different types of well-defined objects
+2. Unions of unbounded _collections_ (e.g. arrays and records)
+
+Unions of primitives types are fairly trivial (simply check `typeof`), and unions that include _one_ complex object type are also fairly straightforward, but when we need to distinguish between object shapes, it becomes much more difficult.
+
+### Unions of Multiple Object Types
+
+Imagine if we removed the `type` property from our earlier `FeedItem` example:
+
+```ts
+interface TextItem {
+  content: string;
+}
+
+interface ImageItem {
+  url: string;
+  caption: string;
+}
+
+type FeedItem = TextItem | ImageItem;
+```
+
+The only way for us to tell if a `FeedItem` is a text or image item is through checking for the individual fields of one or the other. For validation libraries, this ends up meaning we parse _each type sequentially_ until we find one that matches the given object, which results in repeated traversals and errors being created and caught.
+
+This is a massive performance penalty on one of the most common patterns in API unions, and libraries like Zod have added their own `discriminatedUnion` type functions to short circuit this by looking up a _discriminator field_, like our original `type` string in the first example. However, this strategy relies on developers _knowing and remembering_ to use a special type of union in these cases, which leaves you one small mistake away from a performance regression.
+
+This brings us to Fetchium's _first_ major restriction on unions:
+
+> **Object/entity unions must be discriminated.** When a union contains multiple object or entity types, each must have a _type_ field, denoted with `t.typename(...)`. This field can be _any_ field (you can call it `type` or `typename` or `__typename` or anything else that is a valid string), but ALL objects in a union must have the _same_ typename field, and each object must have a _unique_ typename _value_.
+
+So for example, to define our `TextItem` and `ImageItem` types, we could do the following:
+
+```ts
+// ✅ Valid, same typename property with distinct values
+const TextItem = t.object({
+  type: t.typename('text'),
+  content: t.string,
+});
+
+const ImageItem = t.object({
+  type: t.typename('image'),
+  url: t.string,
+  caption: t.string,
+});
+
+const FeedItem = t.union(TextItem, ImageItem);
+```
+
+But these would be invalid:
+
+```ts
+// 🛑 Invalid, different typenames
+const TextItem = t.object({
+  type: t.typename('text'),
+  content: t.string,
+});
+
+const ImageItem = t.object({
+  typename: t.typename('image'),
+  url: t.string,
+  caption: t.string,
+});
+
+const FeedItem = t.union(TextItem, ImageItem);
+
+// 🛑 Invalid, overlapping typenames
+const TextItem = t.object({
+  type: t.typename('text'),
+  content: t.string,
+});
+
+const ExpandedTextItem = t.object({
+  typename: t.typename('text'),
+  content: t.string,
+  fullContent: t.string,
+});
+
+const FeedItem = t.union(TextItem, ExpandedTextItem);
+
+// 🛑 Invalid, missing typenames on some objects
+const TextItem = t.object({
+  content: t.string,
+});
+
+const ImageItem = t.object({
+  typename: t.typename('image'),
+  url: t.string,
+  caption: t.string,
+});
+
+const FeedItem = t.union(TextItem, ImageItem);
+```
+
+### Unions of Collections
+
+The other major pain point in parsing is _unions of collections_. To be clear, we are not talking about _collections of unions_. To illustrate:
+
+```ts
+// Union of Collections
+type UoC = string[] | number[] | TextItem[] | ImageItem[];
+
+// Collection of Unions
+type CoU = (string | number | TextItem | ImageItem)[];
+```
+
+Collections of unions are actually completely fine, given they follow the previously established rules around `typename` for objects. But the reverse is difficult because of the potential for overlapping unions. Consider:
+
+```ts
+type Overlapping = (string | number)[] | (string | boolean)[];
+```
+
+This type gives us a few problems:
+
+- If we receive an array of _only_ strings, which type is it? We can't tell based on the value alone.
+- If we receive an array with a number, many strings, and then a boolean, how do we maintain the context that we've already selected into one of the types?
+- For even more complex type unions with more complex overlapping, how do we narrow progressively as we're parsing?
+
+In other words, this is a can of worms for a behavior that is _fairly_ niche, and which can be solved (perhaps less ideally) by using a Collection of Unions instead. This leads to the _second_ major restriction Fetchium places on unions
+
+> **Unions may only contain one type of each collection (records and arrays).** Unions may contain a record type and/or an array type, along with any number of primitive types and discriminated object types. But they cannot contain _more_ than one record or array type.
+
+Some examples of valid and invalid collection unions:
+
+```ts
+// ✅ Valid, array of unions
+t.array(t.union(t.string, t.number));
+
+// ✅ Valid, primitive + 1 array type
+t.union(t.string, t.array(t.string));
+
+// ✅ 1 array type + 1 record type
+t.union(t.array(t.string), t.record(t.string));
+
+// ✅ 1 array type + 1 record type
+t.union(
+  t.array(t.union(t.string, t.number)),
+  t.record(t.union(t.string, t.number)),
+);
+
+// ✅ Valid, primitive + 1 array type + object type
+t.union(t.string, t.array(t.string), t.object({ prop: t.string }));
+
+// 🛑 Invalid, 2 array types
+t.union(t.array(t.string), t.array(t.number));
+
+// 🛑 Invalid, 2 record types
+t.union(t.record(t.string), t.record(t.number));
+```
+
+## Formatted Values
+
+Formats transform raw JSON values into richer types during parsing and serialize them back for caching. Two formats are included by default, matching the OpenAPI spec for formats:
+
+| Format        | Raw type | Parsed type | Description                |
+| ------------- | -------- | ----------- | -------------------------- |
+| `'date'`      | `string` | `Date`      | `YYYY-MM-DD` parsed as UTC |
+| `'date-time'` | `string` | `Date`      | ISO 8601 string to Date    |
+
+```tsx
+startDate = t.format('date');
+createdAt = t.format('date-time');
+```
+
+Register custom formats with `registerFormat()`:
+
+```tsx
+import { registerFormat, Mask } from 'fetchium';
+
+registerFormat(
+  'currency',
+  Mask.STRING,
+  (raw) => parseFloat(raw.replace(/[$,]/g, '')),
+  (value) => `$${value.toFixed(2)}`,
+);
+
+// Then use it:
+price = t.format('currency');
+```
+
+To add TypeScript types for custom formats, use module augmentation:
+
+```ts
+declare global {
+  namespace SignaliumQuery {
+    interface FormatRegistry {
+      'my-format': MyType;
+    }
+  }
+}
+```
+
+By default, formats are parsed eagerly. Pass `{ eager: false }` to defer parsing until the field is first read.

package/plugin/docs/data/caching.md

@@ -0,0 +1,298 @@
+---
+title: Caching & Refetching
+---
+
+Most data-fetching libraries treat caching as an afterthought --- a bag of imperative methods you call to set, invalidate, and evict cached data. You end up with `queryClient.invalidateQueries()` scattered across your codebase, mentally tracking which queries need refreshing after which mutations, and debugging stale UI when you forget one.
+
+Fetchium takes a different approach. Caching in Fetchium is _declarative_. You configure three time-based knobs on your query classes --- `staleTime`, `gcTime`, and `cacheTime` --- and Fetchium handles the mechanics. The combination of entity normalization, automatic background refetching, and mutation effects keeps your data fresh without manual intervention. And when you do need to invalidate queries directly, you declare that on the mutation class too --- not in an imperative callback.
+
+This philosophy is a direct extension of Fetchium's core design principle: _describe what you want, not how to get it_.
+
+---
+
+## The Three Time Knobs
+
+Fetchium's cache behavior is controlled by three settings, each operating at a different layer of the caching system.
+
+| Setting     | Unit         | Default            | Scope                    | Description                                              |
+| ----------- | ------------ | ------------------ | ------------------------ | -------------------------------------------------------- |
+| `staleTime` | milliseconds | `0` (always stale) | Per-query instance       | How long data is considered fresh after fetching         |
+| `gcTime`    | minutes      | `5`                | Per-query instance       | How long an unwatched query stays in the in-memory cache |
+| `cacheTime` | minutes      | `1440` (24 hours)  | Per-query class (static) | How long query results persist in the persistent store   |
+
+The lifecycle of a piece of data flows through these layers:
+
+```
+fetch → in-memory cache (gcTime) → persistent store (cacheTime) → evicted
+```
+
+When a query is actively used by a component, it lives in memory. When all consumers unmount, the `gcTime` clock starts --- if no consumer re-subscribes before it expires, the data is evicted from memory. The persistent store (localStorage, IndexedDB) holds data independently and is governed by `cacheTime`. When a query is re-activated, Fetchium checks the store first --- if the cached data is newer than `cacheTime`, it is served immediately while a background refetch may occur (depending on `staleTime`).
+
+### staleTime
+
+`staleTime` controls how long data is considered _fresh_ after a successful fetch. While data is fresh, Fetchium serves it directly from the in-memory cache without hitting the network. Once the stale time has elapsed, the next read triggers a background refetch.
+
+The default is `0`, meaning data is always considered stale. This is intentionally conservative --- every time a component mounts or re-activates, Fetchium will refetch in the background. For many applications this is exactly right: the network request happens transparently, the component shows cached data instantly, and updates arrive moments later.
+
+Increase `staleTime` when:
+
+- The data changes infrequently (user profiles, configuration, feature flags)
+- The endpoint is expensive or rate-limited
+- You want to reduce unnecessary network traffic on frequent navigation
+
+```ts
+class GetFeatureFlags extends RESTQuery {
+  path = '/feature-flags';
+
+  result = { flags: t.object({ darkMode: t.boolean, betaAccess: t.boolean }) };
+
+  config = {
+    staleTime: 5 * 60_000, // fresh for 5 minutes
+  };
+}
+```
+
+### gcTime
+
+`gcTime` controls how long a query stays in the _in-memory_ cache after all of its consumers have unmounted. This is the window during which a user can navigate away and come back without triggering a new fetch --- the data is still in memory, ready to be served instantly.
+
+The default is `5` minutes. Due to Fetchium's bucket-based garbage collection, the actual eviction time falls between `gcTime` and `2 × gcTime`. This is a deliberate trade-off: bucket-based GC is much cheaper than per-key timers, and the imprecision is irrelevant for most applications.
+
+| `gcTime` value | Behavior                                                       |
+| -------------- | -------------------------------------------------------------- |
+| `0`            | Evicted on the next tick after all consumers unmount           |
+| `5` (default)  | Stays in memory for 5--10 minutes after last consumer unmounts |
+| `Infinity`     | Never evicted from memory (use with caution)                   |
+
+### cacheTime
+
+`cacheTime` controls how long query results persist in the _persistent store_ (localStorage, IndexedDB, or whatever `QueryStore` implementation you provide). When a query is activated and no in-memory data exists, Fetchium checks the store. If the cached entry is newer than `cacheTime`, it is loaded and served to the component immediately. If it is older, the stale entry is discarded and a fresh fetch happens.
+
+The default is `1440` minutes (24 hours). Unlike `gcTime`, which is set per-instance via the `config` object, `cacheTime` is set per-query-class via the _static_ `cache` property. This is because persistent storage is shared across all instances of a query class.
+
+---
+
+## Configuring Cache Behavior
+
+### Per-instance config
+
+`staleTime` and `gcTime` are set on the instance-level `config` field (or `getConfig()` method):
+
+```ts
+class GetUser extends RESTQuery {
+  params = { id: t.number };
+
+  path = `/users/${this.params.id}`;
+
+  result = { name: t.string, email: t.string };
+
+  config = {
+    staleTime: 30_000, // fresh for 30 seconds
+    gcTime: 10, // keep in memory 10 minutes after unmount
+  };
+}
+```
+
+For dynamic configuration based on runtime conditions, use the `getConfig()` method:
+
+```ts
+class GetUser extends RESTQuery {
+  params = { id: t.number };
+
+  path = `/users/${this.params.id}`;
+
+  result = { name: t.string, email: t.string };
+
+  getConfig() {
+    const lastResponseOk = this.response?.ok ?? true;
+
+    return {
+      staleTime: lastResponseOk ? 30_000 : 0,
+      gcTime: 10,
+    };
+  }
+}
+```
+
+### Static cache for persistent store
+
+`cacheTime` and `maxCount` are configured via the static `cache` property on the query class:
+
+```ts
+class GetUser extends RESTQuery {
+  static cache = {
+    cacheTime: 120, // persist in store for 2 hours
+    maxCount: 100, // keep at most 100 cached instances
+  };
+
+  params = { id: t.number };
+
+  path = `/users/${this.params.id}`;
+
+  result = { name: t.string, email: t.string };
+}
+```
+
+`maxCount` limits how many distinct parameter combinations are stored for this query class. When the limit is exceeded, the oldest entries are evicted. The default is `50`.
+
+---
+
+## Manual Refetching with `__refetch()`
+
+The declarative cache covers the vast majority of use cases, but sometimes you need to explicitly trigger a fresh fetch. Every query result exposes a `__refetch()` method:
+
+```tsx {% mode="react" %}
+function UserProfile({ userId }: { userId: number }) {
+  const query = useQuery(GetUser, { id: userId });
+
+  if (!query.isReady) return <div>Loading...</div>;
+
+  return (
+    <div>
+      <h1>{query.value.name}</h1>
+      <button onClick={() => query.value.__refetch()}>Refresh</button>
+    </div>
+  );
+}
+```
+
+```tsx {% mode="signalium" %}
+const UserProfile = component(({ userId }: { userId: number }) => {
+  const query = fetchQuery(GetUser, { id: userId });
+
+  if (!query.isReady) return <div>Loading...</div>;
+
+  return (
+    <div>
+      <h1>{query.value.name}</h1>
+      <button onClick={() => query.value.__refetch()}>Refresh</button>
+    </div>
+  );
+});
+```
+
+`__refetch()` returns the query's `ReactivePromise`, so you can `await` it if you need to know when the fresh data arrives:
+
+```ts
+const freshResult = await result.__refetch();
+```
+
+If a fetch is already in flight, `__refetch()` returns the existing promise without starting a duplicate request.
+
+{% callout title="Why __refetch lives on the result" type="note" %}
+You might wonder why `__refetch()` is on the `QueryResult` rather than on the `ReactivePromise`. The reason is composability: the result object can be passed to child components, stored in variables, or returned from helper functions. Any consumer holding a reference to the result can trigger a refetch without needing access to the original query handle.
+{% /callout %}
+
+---
+
+## Cache Invalidation
+
+If you are coming from TanStack Query, you may be used to `queryClient.invalidateQueries()` --- a single imperative call that marks queries as stale and triggers refetches. Fetchium handles this differently: invalidation is _declarative_ and happens through mutation effects, not imperative calls.
+
+In a traditional query cache, each query is an island. When a mutation changes data, you have to manually figure out _which queries_ are affected and invalidate them in an `onSuccess` callback. Forget one, and you have stale UI. Add a new query that displays the same data, and you have to remember to add it to the invalidation list.
+
+Fetchium's entity normalization eliminates this problem for most cases. When User #42's name changes via a mutation, _every query displaying User #42 updates automatically_, because they all share the same normalized entity proxy. You do not need to know which queries to invalidate --- the entity system handles it.
+
+The mechanisms for keeping data fresh in Fetchium are, in order of preference:
+
+1. **Entity effects from mutations** (`creates`, `updates`, `deletes`). When a mutation succeeds, its effects update entities in the normalized store. Every query referencing those entities sees the change immediately. This is the most common and most powerful freshness mechanism.
+
+2. **Query invalidation via `invalidates`**. For mutations whose effects are too complex or broad to express as entity-level changes, you can declare `invalidates` in the mutation's effects to mark specific query classes as stale. You can target all instances of a query class, or only those matching a param subset. See the [Mutations guide](/data/mutations) for details.
+
+3. **`staleTime` expiration.** Background refetches happen automatically when data becomes stale and a consumer re-reads it. For data that changes unpredictably on the server, this provides eventual consistency without any manual intervention.
+
+4. **`__refetch()` for explicit reloads.** When you need a one-off full query reload from a specific place in your code (not tied to a mutation), `__refetch()` on the query result gives you a direct escape hatch.
+
+5. **`refreshStaleOnReconnect` for network recovery.** When the user's device comes back online, stale queries are automatically refetched.
+
+{% callout type="note" %}
+Entity effects should be your first choice. They are precise, efficient, and work with optimistic updates and live data. Use `invalidates` when the mutation's impact is too broad to express as entity changes. Use `__refetch()` only for one-off imperative needs outside of the mutation system.
+{% /callout %}
+
+---
+
+## Background Refetching
+
+Fetchium automatically refetches data in several scenarios, all governed by the `staleTime` setting.
+
+### On remount
+
+When a component mounts and subscribes to a query that already has cached data, Fetchium serves the cached data immediately. If the data is stale (older than `staleTime`), a background refetch is triggered. The component sees the cached data first, then re-renders with fresh data when the fetch completes.
+
+This is why the default `staleTime` of `0` works well in practice: users see data instantly, and it silently refreshes in the background. The UI never shows a loading spinner for data that has been fetched before.
+
+### On reconnect
+
+The `refreshStaleOnReconnect` option (default: `true`) controls whether stale queries are automatically refetched when the device comes back online. When a user loses connectivity and then reconnects, all active queries whose data has become stale are refetched automatically.
+
+```ts
+class GetUser extends RESTQuery {
+  params = { id: t.number };
+
+  path = `/users/${this.params.id}`;
+
+  result = { name: t.string, email: t.string };
+
+  config = {
+    refreshStaleOnReconnect: false, // opt out of automatic reconnect refetch
+  };
+}
+```
+
+### Stale vs. pending
+
+It is worth understanding the distinction between _stale_ and _pending_:
+
+- **Stale** means the data's age has exceeded `staleTime`. Stale data is still perfectly usable --- it is served to the component and displayed to the user. It simply means a background refetch will be triggered on the next activation.
+- **Pending** means a fetch is currently in flight. A query can be both stale and pending simultaneously (it has old data and is fetching new data).
+
+The `ReactivePromise` exposes both states: `isPending` tells you if a fetch is in progress, while `isReady` tells you if _any_ value (fresh or stale) is available. For most UIs, you should use `isReady` to decide whether to render content, not `isPending`.
+
+---
+
+## Entity-Level GC
+
+Entities have their own garbage collection, configured via the static `cache` property on the `Entity` class:
+
+```ts
+class User extends Entity {
+  static cache = { gcTime: 10 }; // keep in memory 10 minutes after last reference
+
+  __typename = t.typename('User');
+  id = t.id;
+
+  name = t.string;
+}
+```
+
+| `gcTime` value        | Behavior                                                      |
+| --------------------- | ------------------------------------------------------------- |
+| `undefined` (default) | Entity is evicted immediately when no queries reference it    |
+| `0`                   | Entity is evicted on the next tick                            |
+| `10`                  | Entity stays in cache for 10--20 minutes after last reference |
+| `Infinity`            | Entity is never garbage collected                             |
+
+Entity GC and query GC are independent but related. When a query is evicted from memory (its `gcTime` expires), the entities it referenced lose one consumer. If no other active query references a given entity, that entity's own `gcTime` clock starts. This means:
+
+- If both the query and entity have a `gcTime` of 5, an entity could stay in memory for up to 5 + 10 = 15 minutes after the last component unmounts (query GC window + entity GC window, accounting for bucket imprecision).
+- Setting entity `gcTime` to `Infinity` keeps entities in memory permanently --- useful for user profiles or other data that is referenced from many queries and expensive to re-parse.
+
+{% callout %}
+Entity cache configuration is set at the class level, not per-instance. All instances of `User` share the same GC policy regardless of which query loaded them.
+{% /callout %}
+
+---
+
+## Next Steps
+
+{% quick-links %}
+
+{% quick-link title="Mutations" icon="theming" href="/data/mutations" description="Update data with optimistic updates and entity effects" /%}
+
+{% quick-link title="Offline & Persistence" icon="installation" href="/guides/offline" description="Configure persistent stores and offline-first network modes" /%}
+
+{% quick-link title="REST Queries Reference" icon="presets" href="/reference/rest-queries" description="Full reference for query fields, methods, and configuration" /%}
+
+{% quick-link title="Entities" icon="plugins" href="/core/entities" description="Normalized entity caching and identity-stable proxies" /%}
+
+{% /quick-links %}