fetchium 0.1.0 → 0.1.1

package/plugin/docs/guides/offline.md

@@ -0,0 +1,270 @@
+---
+title: Offline & Persistence
+---
+
+Fetchium has built-in support for offline operation and query persistence. It can detect network status, pause queries when the device goes offline, and persist query results across sessions so your application works even without a connection.
+
+This guide covers the offline and persistence-specific pieces of Fetchium's infrastructure. For the caching time knobs (`staleTime`, `gcTime`, `cacheTime`) and cache invalidation patterns, see [Caching & Refetching](/data/caching).
+
+---
+
+## Network Manager
+
+The `NetworkManager` tracks whether the device is online or offline. It automatically listens to browser `online` and `offline` events, and exposes the current status as a reactive signal so that queries can pause and resume automatically.
+
+### Basic usage
+
+```tsx
+import { NetworkManager } from 'fetchium';
+
+const networkManager = new NetworkManager();
+```
+
+The network manager is passed to the `QueryClient` constructor:
+
+```tsx
+import { QueryClient } from 'fetchium';
+import { SyncQueryStore, MemoryPersistentStore } from 'fetchium/stores/sync';
+
+const store = new SyncQueryStore(new MemoryPersistentStore());
+const networkManager = new NetworkManager();
+
+const client = new QueryClient(store, { fetch }, networkManager);
+```
+
+If you do not provide a `NetworkManager`, the `QueryClient` creates one automatically.
+
+### Manual override
+
+For testing or custom scenarios, you can manually override the network status:
+
+```tsx
+networkManager.setNetworkStatus(false);
+networkManager.setNetworkStatus(true);
+networkManager.clearManualOverride();
+```
+
+When a manual override is active, the browser's actual connectivity events are ignored.
+
+### Reactive signal
+
+The network manager exposes its status as a reactive signal. You can read it directly in reactive functions:
+
+```tsx
+const onlineSignal = networkManager.getOnlineSignal();
+```
+
+---
+
+## Network Modes
+
+Each query can configure how it behaves when the device is offline. Set `networkMode` in the query's `config` property:
+
+```tsx
+import { t, NetworkMode } from 'fetchium';
+import { RESTQuery } from 'fetchium/rest';
+
+class GetUser extends RESTQuery {
+  params = { id: t.id };
+
+  path = `/users/${this.params.id}`;
+
+  result = { id: t.id, name: t.string };
+
+  config = {
+    networkMode: NetworkMode.OfflineFirst,
+  };
+}
+```
+
+There are three network modes:
+
+### `NetworkMode.Online` (default)
+
+The query only fetches when the device is online. If the device goes offline while a query is active, the query pauses and resumes automatically when connectivity is restored.
+
+This is the safest default --- it prevents failed requests and unnecessary retries while offline.
+
+### `NetworkMode.Always`
+
+The query fetches regardless of network status. Use this when you have a local server, service worker, or other mechanism that can handle requests even without internet access.
+
+### `NetworkMode.OfflineFirst`
+
+If cached data exists, the query returns it immediately even when offline. When the device comes back online, the query refetches to get fresh data (assuming the data is stale).
+
+This mode is ideal for applications that need to show something to the user even when there is no connection.
+
+{% callout %}
+When using `NetworkMode.OfflineFirst`, pair it with a `QueryStore` that persists data across sessions. Otherwise, the cache will be empty on a fresh app launch and there will be nothing to show while offline.
+{% /callout %}
+
+### Refetch on reconnect
+
+By default, queries with `NetworkMode.Online` or `NetworkMode.OfflineFirst` refetch stale data when the device reconnects. You can disable this behavior:
+
+```tsx
+config = {
+  networkMode: NetworkMode.Online,
+  refreshStaleOnReconnect: false,
+};
+```
+
+---
+
+## Query Stores
+
+A query store is responsible for persisting query results and entity data to a durable backend. Fetchium provides two implementations: a synchronous store for in-memory or localStorage-style backends, and an asynchronous store for IndexedDB, AsyncStorage, or cross-worker architectures.
+
+### SyncQueryStore
+
+The `SyncQueryStore` wraps a synchronous key-value store. It is the simplest option and works well for most applications.
+
+```tsx
+import { SyncQueryStore, MemoryPersistentStore } from 'fetchium/stores/sync';
+
+const store = new SyncQueryStore(new MemoryPersistentStore());
+const client = new QueryClient(store, { fetch });
+```
+
+The `MemoryPersistentStore` keeps everything in memory --- data is lost when the page is refreshed. For persistence across sessions, implement the `SyncPersistentStore` interface with a durable backend like `localStorage`.
+
+### AsyncQueryStore
+
+The `AsyncQueryStore` is designed for asynchronous storage backends such as IndexedDB or React Native's AsyncStorage. It uses a writer-reader architecture where one instance (the writer) owns the backing store, and other instances (readers) communicate with it via messages.
+
+```tsx
+import { AsyncQueryStore } from 'fetchium/stores/async';
+
+const store = new AsyncQueryStore({
+  isWriter: true,
+  connect: (handleMessage) => ({
+    sendMessage: (msg) => handleMessage(msg),
+  }),
+  delegate: myAsyncPersistentStore,
+});
+```
+
+**Writer vs reader:**
+
+- The **writer** (`isWriter: true`) is the only instance that writes to the backing store. It must be provided a `delegate` (an `AsyncPersistentStore` implementation).
+- **Readers** (`isWriter: false`) send write operations to the writer via messages and can load data directly from their own delegate (if provided).
+
+This architecture ensures serialized writes even when multiple tabs or workers are involved.
+
+---
+
+## Custom Persistent Stores
+
+To build a custom persistence backend, implement either the `SyncPersistentStore` or `AsyncPersistentStore` interface. Both share the same shape --- the async version wraps each method in a `Promise`.
+
+The store needs to handle three data types: strings (for serialized JSON values), numbers (for timestamps and reference counts), and `Uint32Array` buffers (for entity ID sets and LRU queues).
+
+### Example: localStorage adapter
+
+```tsx
+class LocalStoragePersistentStore implements SyncPersistentStore {
+  has(key: string): boolean {
+    return localStorage.getItem(key) !== null;
+  }
+
+  getString(key: string): string | undefined {
+    return localStorage.getItem(key) ?? undefined;
+  }
+
+  setString(key: string, value: string): void {
+    localStorage.setItem(key, value);
+  }
+
+  getNumber(key: string): number | undefined {
+    const v = localStorage.getItem(key);
+    return v !== null ? Number(v) : undefined;
+  }
+
+  setNumber(key: string, value: number): void {
+    localStorage.setItem(key, String(value));
+  }
+
+  getBuffer(key: string): Uint32Array | undefined {
+    const v = localStorage.getItem(key);
+    if (v === null) return undefined;
+    return new Uint32Array(JSON.parse(v));
+  }
+
+  setBuffer(key: string, value: Uint32Array): void {
+    localStorage.setItem(key, JSON.stringify(Array.from(value)));
+  }
+
+  delete(key: string): void {
+    localStorage.removeItem(key);
+  }
+
+  getAllKeys(): string[] {
+    return Object.keys(localStorage);
+  }
+}
+```
+
+{% callout type="warning" %}
+`localStorage` has a 5 MB limit in most browsers. For larger datasets, consider using IndexedDB via the `AsyncQueryStore` instead.
+{% /callout %}
+
+For complete API details on both store types, see the [stores/sync](/api/stores-sync) and [stores/async](/api/stores-async) API reference pages.
+
+---
+
+## Putting It All Together
+
+Here is a complete example that sets up a `QueryClient` with persistence and network awareness for an offline-capable application:
+
+```tsx
+import { QueryClient, NetworkManager } from 'fetchium';
+import { SyncQueryStore } from 'fetchium/stores/sync';
+
+const store = new SyncQueryStore(new LocalStoragePersistentStore());
+const networkManager = new NetworkManager();
+
+const client = new QueryClient(
+  store,
+  {
+    fetch: globalThis.fetch,
+    baseUrl: 'https://api.example.com',
+  },
+  networkManager,
+);
+```
+
+With this setup:
+
+- Query results are persisted to `localStorage` and survive page refreshes
+- Queries automatically pause when the device goes offline and resume when it reconnects
+- Unused queries are evicted from memory after their `gcTime` expires, but their persisted data remains in `localStorage` for the next session
+
+Configure individual queries for offline behavior:
+
+```tsx
+class GetDashboard extends RESTQuery {
+  path = '/dashboard';
+
+  result = { stats: t.object({ visits: t.number }) };
+
+  config = {
+    networkMode: NetworkMode.OfflineFirst,
+    staleTime: 60_000,
+  };
+}
+```
+
+---
+
+## Next Steps
+
+{% quick-links %}
+
+{% quick-link title="Caching & Refetching" icon="presets" href="/data/caching" description="Understand staleTime, gcTime, cacheTime, and cache invalidation patterns" /%}
+
+{% quick-link title="stores/sync API" icon="plugins" href="/api/stores-sync" description="Full API reference for the synchronous query store" /%}
+
+{% quick-link title="stores/async API" icon="theming" href="/api/stores-async" description="Full API reference for the asynchronous query store" /%}
+
+{% /quick-links %}

package/plugin/docs/guides/testing.md

@@ -0,0 +1,301 @@
+---
+title: Testing
+---
+
+Fetchium ships a dedicated `fetchium/testing` package that gives you type-safe query mocking, automatic data generation from your type definitions, entity factories, and test variation knobs for exploring structural edge cases. You never need to understand Signalium internals, mock global state, or patch module imports. Just set up your mocks, write your tests, and let Fetchium handle the wiring.
+
+---
+
+## Quick Start
+
+Every test starts with a `MockClient`. It wraps a `QueryClient` with an in-memory store and a mock fetch router so your queries resolve against canned data instead of a real server.
+
+```ts
+import { MockClient } from 'fetchium/testing';
+
+const mock = new MockClient();
+afterEach(() => mock.reset());
+afterAll(() => mock.destroy());
+```
+
+`mock.reset()` clears all mocked routes and request history between tests. `mock.destroy()` tears down the underlying client and timers.
+
+{% callout title="Always destroy the client" type="warning" %}
+`QueryClient` manages background timers. Call `mock.destroy()` in your test teardown to avoid timer leaks.
+{% /callout %}
+
+---
+
+## Setting Up Your Test Harness
+
+`MockClient` provides a `QueryClient` via `mock.client`. You plug this into your own render utility alongside your app's providers --- auth, theme, i18n, routing, or whatever your app needs:
+
+```tsx
+// test-utils.tsx
+import { render } from '@testing-library/react';
+import { ContextProvider } from 'signalium/react';
+import { QueryClientContext } from 'fetchium';
+
+export function renderApp(
+  ui: React.ReactElement,
+  { client }: { client: QueryClient },
+) {
+  return render(
+    <ContextProvider value={client} context={QueryClientContext}>
+      {ui}
+    </ContextProvider>,
+  );
+}
+```
+
+If your app has additional providers, add them here. Fetchium has no opinions about your provider stack --- it only needs `QueryClientContext` to be present.
+
+---
+
+## Mocking Queries
+
+Register mock responses with `mock.when()`. The response shape is type-checked against the query's `result` definition:
+
+```ts
+import { Entity, t } from 'fetchium';
+import { RESTQuery } from 'fetchium/rest';
+
+class User extends Entity {
+  __typename = t.typename('User');
+  id = t.id;
+  name = t.string;
+  email = t.string;
+  avatar = t.optional(t.string);
+}
+
+class GetUser extends RESTQuery {
+  params = { id: t.number };
+  path = `/users/${this.params.id}`;
+  result = { user: t.entity(User) };
+}
+
+// In your test:
+mock.when(GetUser, { id: 1 }).respond({
+  user: mock.entity(User, { name: 'Alice', email: 'alice@example.com' }),
+});
+```
+
+### Auto-generated responses
+
+If you do not care about the exact field values, `.auto()` generates a complete valid response from the query's type definitions:
+
+```ts
+mock.when(GetUser, { id: 1 }).auto();
+```
+
+You can pass partial overrides that are deep-merged into the generated data:
+
+```ts
+mock.when(GetUser, { id: 1 }).auto({
+  user: { name: 'Alice' },
+});
+```
+
+### Catch-all routes
+
+Omit params to match any request for that query class:
+
+```ts
+mock.when(GetUser).auto();
+```
+
+### Sequential responses
+
+Chain `.thenRespond()` to queue multiple responses:
+
+```ts
+mock
+  .when(GetUser, { id: 1 })
+  .respond({ user: mock.entity(User, { name: 'V1' }) })
+  .thenRespond({ user: mock.entity(User, { name: 'V2' }) });
+```
+
+The first fetch returns V1, the second returns V2. Subsequent fetches reuse the last response.
+
+### Error states
+
+```ts
+mock.when(GetUser, { id: 999 }).error(404);
+mock.when(GetUser, { id: 1 }).networkError('connection refused');
+```
+
+### Simulated latency
+
+```ts
+mock.when(GetUser, { id: 1 }).delay(500).auto();
+```
+
+### Raw escape hatch
+
+`.raw()` bypasses type checking entirely, for testing how your app handles unexpected data:
+
+```ts
+mock.when(GetUser, { id: 1 }).raw({ incomplete: true });
+```
+
+---
+
+## Generating Test Data
+
+### `mock.entity()`
+
+Generates a plain JSON object matching an entity's type definition. Fields are auto-filled with debuggable sequential values (`"name_1"`, `"email_2"`, etc.), and you override whatever matters for your test:
+
+```ts
+const alice = mock.entity(User, { name: 'Alice' });
+// => { __typename: 'User', id: '1', name: 'Alice', email: 'email_1' }
+
+const bob = mock.entity(User, { name: 'Bob', email: 'bob@test.com' });
+// => { __typename: 'User', id: '2', name: 'Bob', email: 'bob@test.com' }
+```
+
+IDs auto-increment per typename, so each entity gets a unique identity.
+
+### Entity Factories
+
+For richer test data, register a factory with custom generators:
+
+```ts
+mock.define(User, {
+  name: (seq) => `User ${seq}`,
+  email: (seq, fields) =>
+    `${fields.name.toLowerCase().replace(' ', '.')}@test.com`,
+});
+
+const alice = mock.entity(User, { name: 'Alice' });
+// => { __typename: 'User', id: '1', name: 'Alice', email: 'alice@test.com' }
+```
+
+Generator functions receive a `seq` counter (auto-incrementing per typename) and a `fields` object containing previously generated field values, for derived data.
+
+Factories are also used by `.auto()` when it generates entities for query responses.
+
+### Standalone usage
+
+For Storybook or other contexts outside `MockClient`:
+
+```ts
+import { entity, defineFactory } from 'fetchium/testing';
+
+const user = entity(User, { name: 'Alice' });
+
+const UserFactory = defineFactory(User, {
+  name: (seq) => `User ${seq}`,
+});
+UserFactory.build({ name: 'Alice' });
+UserFactory.buildMany(5);
+```
+
+---
+
+## Testing Components
+
+A complete component test:
+
+```tsx
+import { MockClient } from 'fetchium/testing';
+import { renderApp } from '../test-utils';
+
+const mock = new MockClient();
+afterEach(() => mock.reset());
+afterAll(() => mock.destroy());
+
+it('renders the user name after loading', async () => {
+  mock.when(GetUser, { id: 1 }).respond({
+    user: mock.entity(User, { name: 'Alice', email: 'alice@example.com' }),
+  });
+
+  const { getByTestId } = renderApp(<UserProfile userId={1} />, {
+    client: mock.client,
+  });
+
+  await waitFor(() => {
+    expect(getByTestId('name')).toHaveTextContent('Alice');
+  });
+});
+```
+
+---
+
+## Testing Mutations
+
+Mutations are mocked the same way. You can inspect what was sent using `mock.calls`:
+
+```ts
+import { getMutation, t } from 'fetchium';
+import { RESTMutation } from 'fetchium/rest';
+
+class CreateUser extends RESTMutation {
+  readonly params = { name: t.string, email: t.string };
+  readonly path = '/users';
+  readonly method = 'POST' as const;
+  readonly body = { name: this.params.name, email: this.params.email };
+  readonly result = { user: t.entity(User) };
+}
+
+it('sends the correct request body', async () => {
+  mock.when(CreateUser).respond({
+    user: mock.entity(User, { name: 'Bob', email: 'bob@example.com' }),
+  });
+
+  // ... trigger the mutation in your component or reactive code ...
+
+  expect(mock.wasCalled(CreateUser)).toBe(true);
+  expect(mock.lastCall(CreateUser)?.body).toEqual({
+    name: 'Bob',
+    email: 'bob@example.com',
+  });
+});
+```
+
+### Entity effects
+
+Because Fetchium normalizes entities, a mutation that returns updated entity data automatically updates any query that references the same entity:
+
+```ts
+it('mutation updates the entity visible in queries', async () => {
+  mock.when(GetUser, { id: 1 }).respond({
+    user: mock.entity(User, { id: '1', name: 'Alice' }),
+  });
+  mock.when(UpdateUser).respond({
+    user: mock.entity(User, { id: '1', name: 'Alice Updated' }),
+  });
+
+  // Fetch the user, then mutate.
+  // The query's data reflects the update automatically.
+});
+```
+
+---
+
+## Summary
+
+| What you are testing             | Tools needed                    | Pattern                                             |
+| -------------------------------- | ------------------------------- | --------------------------------------------------- |
+| React components with `useQuery` | `MockClient` + your `renderApp` | `mock.when().respond()`, render, assert             |
+| Mutations                        | `MockClient`                    | `mock.when(Mutation).respond()`, check `mock.calls` |
+| Entity effects after mutation    | `MockClient` + entity query     | Mock both, verify query data reflects mutation      |
+| Error states                     | `MockClient`                    | `.error()` or `.networkError()`                     |
+
+The core idea is always the same: create a `MockClient`, set up your mocks, plug `mock.client` into your providers, and assert.
+
+---
+
+## Next Steps
+
+{% quick-links %}
+
+{% quick-link title="Queries" icon="plugins" href="/core/queries" description="Learn how to define queries and use them in components" /%}
+
+{% quick-link title="Entities" icon="theming" href="/core/entities" description="Understand normalized entities and identity-stable proxies" /%}
+
+{% quick-link title="Mutations" icon="presets" href="/data/mutations" description="Define mutations with entity effects and optimistic updates" /%}
+
+{% quick-link title="Error Handling" icon="warning" href="/guides/error-handling" description="Handle network failures, retries, and error boundaries" /%}
+
+{% /quick-links %}