@timber-js/app 0.2.0-alpha.20 → 0.2.0-alpha.201

package/docs/api/32-api-cache.mdx

@@ -0,0 +1,311 @@
+---
+title: 'API: @timber-js/app/cache'
+description: 'Cache exports — cache, CacheHandler, MemoryCacheHandler, and invalidation.'
+slug: 'api-cache'
+---
+
+# @timber-js/app/cache
+
+Caching primitives and cache handler interface. Import from `@timber-js/app/cache`.
+
+## `cache.data(fn, options)`
+
+Wrap an async function with cross-request caching.
+
+```ts
+import { cache } from '@timber-js/app/cache';
+
+declare const db: { users: { findUnique(opts: { where: { id: string } }): Promise<{ id: string; name: string }> } };
+
+const getUser = cache.data(
+  async (userId: string) => {
+    return db.users.findUnique({ where: { id: userId } });
+  },
+  {
+    ttl: 60,
+    key: (userId) => `user:${userId}`,
+    staleWhileRevalidate: true,
+    tags: (userId) => [`user:${userId}`],
+  }
+);
+```
+
+### `CacheOptions<Fn>`
+
+| Option                 | Type                                | Description                                |
+| ---------------------- | ----------------------------------- | ------------------------------------------ |
+| `ttl`                  | `number`                            | Time-to-live in seconds                    |
+| `key`                  | `(...args) => string`               | Custom cache key function (optional)       |
+| `staleWhileRevalidate` | `boolean`                           | Serve stale while refetching in background |
+| `tags`                 | `string[] \| (...args) => string[]` | Tags for invalidation                      |
+
+Default key: FNV-1a hash of function identity + deterministic JSON serialization of arguments.
+
+The function identity is derived at build time from the source text of the `cache.data(...)` call, so it is stable across restarts, instances, and deploys. With a persistent shared handler (Redis/KV), cached entries survive deploys as long as the call itself is unchanged — reordering calls or editing unrelated code preserves the cache, while editing the wrapped function or its options gives the call a fresh identity (old entries simply expire via TTL). Renaming or moving the file also resets identity for every call in it.
+
+Build-time identity covers calls the bundler can see statically: named imports (including aliases like `import { cache as c }`) and namespace imports (`import * as timber` + `timber.cache.data(fn, opts)`). Calls it can't trace — a local alias like `const c = cache`, or `cache` re-exported through your own wrapper module — fall back to a hash of the function's source text at runtime. The fallback is still deterministic across instances of the same build, but it resets across deploys, and byte-identical closures produced by a factory can collide — pass an explicit `key` in those cases (timber logs a warning when the fallback is used).
+
+### `cache.invalidate(options)`
+
+Invalidate cache entries by tag or key:
+
+```ts
+import { cache } from '@timber-js/app/cache';
+
+cache.invalidate({ tag: 'products' });
+cache.invalidate({ key: 'user:abc' });
+```
+
+## `cache.component(Component, options)`
+
+Wrap an async server component to cache its rendered RSC flight payload. The component renders once and subsequent requests splice the cached output into the live stream.
+
+```ts
+import { cache } from '@timber-js/app/cache';
+
+const PostBody = cache.component(
+  async function PostBody() {
+    const post = await getPost();
+    return <article>{post.content}</article>;
+  },
+  { prerender: true }
+);
+```
+
+`prerender` controls **when** the cache is populated. `ttl`/`tags` control **how it refreshes at runtime**. They are orthogonal — every combination is a meaningful tier:
+
+```tsx
+// Static: rendered at build, changes only on redeploy
+const BlogBody = cache.component(Body, { prerender: true });
+
+// Cached: rendered on first request, refreshed by TTL/tags
+const Pricing = cache.component(PricingTable, { ttl: 300, tags: ['pricing'] });
+
+// ISR: rendered at build, refreshable without a redeploy
+const DocsPage = cache.component(DocsBody, { prerender: true, ttl: 3600, tags: ['docs'] });
+```
+
+### `PrebuiltComponentOptions`
+
+| Option                          | Type                                          | Description                                                                                   |
+| ------------------------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `prerender`                     | `boolean`                                     | Populate at build time via `generateStaticSegmentParams`                                      |
+| `ttl`                           | `number`                                      | Runtime freshness window in seconds                                                           |
+| `tags`                          | `string[] \| (props) => string[]`             | Tags for invalidation via `revalidateTag`                                                     |
+| `staleWhileRevalidate`          | `boolean`                                     | Serve stale while a background re-render refreshes                                            |
+| `slots`                         | `string[]`                                    | Prop names whose values are live React elements composed into the cached shell at request time |
+| `fallbackOnMissingSegmentParams`| `boolean`                                     | When `false`, a cache miss throws instead of rendering live (default: `true`)                  |
+
+Only module-scope declarations are transformed at build time:
+
+```ts
+// ✅ Transformed — eligible for prebuilding
+const Shell = cache.component(MyComponent, { prerender: true });
+
+// ❌ Not transformed — renders dynamically with a warning
+export default function Page() {
+  const Cached = cache.component(Inner, { ttl: 60 }); // nested scope
+}
+```
+
+### Tier Rules
+
+| Declaration                  | Enumerated params       | Unenumerated miss                    |
+| ---------------------------- | ----------------------- | ------------------------------------ |
+| `prerender` only             | Built at deploy         | Live render every time, never stored |
+| `ttl`/`tags` only            | —                       | Rendered + stored on first request   |
+| `prerender` + `ttl`/`tags`   | Built at deploy         | Rendered + stored on first request   |
+
+### Slots
+
+Cache a wrapper component's output as a shell with holes for live children:
+
+```tsx
+const Shell = cache.component(ExpensiveWrapper, {
+  ttl: 3600,
+  tags: ['marketing'],
+  slots: ['children'],
+});
+
+// Request time: the shell is served from cache; children render live.
+<Shell theme="dark"><LiveUserFeed /></Shell>
+```
+
+Slot props are excluded from the cache key — two instances with the same data props share one shell entry. Slots are **runtime tier only**: `prerender` is ignored when `slots` is active because the build cannot enumerate children variants.
+
+### Route-Level Sugar
+
+For "this whole route is static," export `prerender` from a page or layout instead of wrapping manually:
+
+```ts title="Fully static route"
+export const prerender = true;
+```
+
+```ts title="Route-level ISR"
+export const prerender = { ttl: 3600, tags: ['docs'] };
+```
+
+This desugars to wrapping the page's default export in `cache.component(...)`. Layout `prerender` cascades to descendant pages unless overridden (most-specific-wins).
+
+### Nesting
+
+When a cached component renders inside another cached component, the outer entry's lifetime wins. The inner's output is baked into the outer's payload as a flat copy — `revalidateTag` on the inner's tags does **not** refresh the embedded copy. The framework warns at capture time when the inner declares a refresh channel the outer cannot honor.
+
+## `CacheHandler` Interface
+
+Implement this to plug in a custom cache backend.
+
+```ts
+interface CacheHandler {
+  get(key: string): Promise<{ value: unknown; tags: string[] } | null>;
+  set(key: string, value: unknown, options: { ttl: number; tags: string[] }): Promise<void>;
+  invalidate(options: { tag: string }): Promise<void>;
+}
+```
+
+## `MemoryCacheHandler`
+
+In-memory cache with LRU eviction. The default handler.
+
+```ts
+import { MemoryCacheHandler } from '@timber-js/app/cache';
+
+const handler = new MemoryCacheHandler({ maxSize: 1000 });
+handler.size; // Current number of entries
+```
+
+### Options
+
+| Option    | Type     | Default | Description                         |
+| --------- | -------- | ------- | ----------------------------------- |
+| `maxSize` | `number` | `1000`  | Maximum entries before LRU eviction |
+
+## `RedisCacheHandler`
+
+Redis-backed cache handler. Takes a client wrapped to timber's `RedisClient` contract — TTL is a required positional argument, so an adapter can't silently drop the expiry:
+
+```ts
+interface RedisClient {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string, ttlSeconds: number): Promise<unknown>;
+  expireNX(key: string, seconds: number): Promise<unknown>;
+  expireGT(key: string, seconds: number): Promise<unknown>;
+  del(key: string): Promise<unknown>; // single key
+  sadd(key: string, ...members: string[]): Promise<unknown>;
+  srem(key: string, ...members: string[]): Promise<unknown>;
+  smembers(key: string): Promise<string[]>;
+  ttl(key: string): Promise<number>;
+  execMulti?(ops: RedisWriteOp[]): Promise<void>; // optional MULTI/EXEC
+}
+```
+
+`expireNX` and `expireGT` map to Redis 7.0's `EXPIRE key seconds NX|GT` subcommands. `NX` sets the TTL only if none exists, `GT` extends only if greater. Both are used internally for atomic tag set TTL management. Separate methods ensure adapters cannot silently drop the mode. Requires **Redis 7.0+**.
+
+`execMulti` is optional. When provided, `set()` executes tag-index writes and the data write atomically via `MULTI/EXEC`, preventing concurrent `invalidate({tag})` calls from interleaving. When absent, writes are sequential (correct but with a narrow self-healing race window).
+
+This is deliberately not the native shape of any client library — ioredis, node-redis, and @upstash/redis disagree on TTL argument shapes and method casing, and a contract that pattern-matches one client lets another silently write keys with no expiry. Wrap your client with one of these adapters:
+
+```ts title="ioredis"
+import { RedisCacheHandler } from '@timber-js/app/cache';
+import type { RedisWriteOp } from '@timber-js/app/cache';
+import Redis from 'ioredis';
+
+const redis = new Redis(process.env.REDIS_URL!);
+const handler = new RedisCacheHandler({
+  get: (k) => redis.get(k),
+  set: (k, v, ttl) => redis.set(k, v, 'EX', ttl),
+  expireNX: (k, s) => redis.expire(k, s, 'NX'),
+  expireGT: (k, s) => redis.expire(k, s, 'GT'),
+  del: (k) => redis.del(k),
+  sadd: (k, ...m) => redis.sadd(k, ...m),
+  srem: (k, ...m) => redis.srem(k, ...m),
+  smembers: (k) => redis.smembers(k),
+  ttl: (k) => redis.ttl(k),
+  execMulti: async (ops) => {
+    const p = redis.multi();
+    for (const op of ops) {
+      switch (op.op) {
+        case 'set': p.set(op.key, op.value, 'EX', op.ttlSeconds); break;
+        case 'sadd': p.sadd(op.key, ...op.members); break;
+        case 'expireNX': p.expire(op.key, op.seconds, 'NX'); break;
+        case 'expireGT': p.expire(op.key, op.seconds, 'GT'); break;
+        case 'del': p.del(op.key); break;
+      }
+    }
+    await p.exec();
+  },
+});
+```
+
+```ts title="node-redis"
+import { RedisCacheHandler } from '@timber-js/app/cache';
+import { createClient } from 'redis';
+
+const redis = createClient({ url: process.env.REDIS_URL });
+await redis.connect();
+const handler = new RedisCacheHandler({
+  get: (k) => redis.get(k),
+  set: (k, v, ttl) => redis.set(k, v, { EX: ttl }),
+  expireNX: (k, s) => redis.expire(k, s, 'NX'),
+  expireGT: (k, s) => redis.expire(k, s, 'GT'),
+  del: (k) => redis.del(k),
+  sadd: (k, ...m) => redis.sAdd(k, m),
+  srem: (k, ...m) => redis.sRem(k, m),
+  smembers: (k) => redis.sMembers(k),
+  ttl: (k) => redis.ttl(k),
+});
+```
+
+```ts title="@upstash/redis"
+import { RedisCacheHandler } from '@timber-js/app/cache';
+import { Redis } from '@upstash/redis';
+
+// automaticDeserialization must be off: the handler stores JSON strings
+// and parses them itself.
+const redis = new Redis({
+  url: process.env.UPSTASH_REDIS_REST_URL!,
+  token: process.env.UPSTASH_REDIS_REST_TOKEN!,
+  automaticDeserialization: false,
+});
+const handler = new RedisCacheHandler({
+  get: (k) => redis.get(k),
+  set: (k, v, ttl) => redis.set(k, v, { ex: ttl }),
+  expireNX: (k, s) => redis.expire(k, s, 'NX'),
+  expireGT: (k, s) => redis.expire(k, s, 'GT'),
+  del: (k) => redis.del(k),
+  sadd: (k, ...m) => redis.sadd(k, m[0], ...m.slice(1)),
+  srem: (k, ...m) => redis.srem(k, m[0], ...m.slice(1)),
+  smembers: (k) => redis.smembers(k),
+  ttl: (k) => redis.ttl(k),
+});
+```
+
+## `CloudflareKVCacheHandler`
+
+Cloudflare Workers KV–backed cache handler. Resolves the KV binding per-request via `getCloudflareBindings()`. Uses tag index keys for tag-based invalidation. Eventually consistent — TTL is the primary expiry mechanism.
+
+```ts
+import { CloudflareKVCacheHandler } from '@timber-js/app/adapters/cloudflare/cache';
+
+const handler = new CloudflareKVCacheHandler({
+  bindingName: 'TIMBER_CACHE',
+  prefix: 'tc:', // optional, default 'tc:'
+});
+```
+
+## Invalidation
+
+### `revalidateTag(tag)`
+
+Invalidate all cache entries with the given tag. Re-exported from `@timber-js/app/server` for convenience.
+
+```ts
+import { revalidateTag } from '@timber-js/app/server';
+
+revalidateTag('products');
+revalidateTag(`user:${userId}`);
+```
+
+## Singleflight
+
+Request coalescing is built into `cache()` automatically — when multiple concurrent calls miss the cache for the same key, only one executes the underlying function. The singleflight and stable-stringify utilities are internal implementation details and not part of the public API.

package/docs/api/33-api-search-params.mdx

@@ -0,0 +1,176 @@
+---
+title: 'API: @timber-js/app/search-params & Segment Params'
+description: 'Params exports — defineSchema, getSegmentParams, defineSearchParams, codecs, and utilities.'
+slug: 'api-params'
+---
+
+# @timber-js/app/search-params
+
+Typed search parameter definitions.
+
+## `defineSearchParams(codecs)`
+
+Create a typed search params definition for a route.
+
+```ts
+import { defineSearchParams } from '@timber-js/app/search-params';
+import { z } from 'zod/v4';
+
+export const searchParams = defineSearchParams({
+  page: z.coerce.number().default(1),
+  sort: z.enum(['price', 'name', 'date']).default('date'),
+  q: z.string().optional(),
+});
+```
+
+### Implicit optionality
+
+Search params are optional by nature — the URL might not contain them. A schema without `.default()` or `.optional()` (e.g. bare `z.string()`) is treated as implicitly optional: absent or invalid input parses to `undefined`, and the field's inferred type widens to `T | undefined`. Definitions never throw at module-eval time, and schema-backed parsing never throws at request time.
+
+```ts
+const def = defineSearchParams({ name: z.string() });
+def.parse(new URLSearchParams(''));        // { name: undefined }
+def.parse(new URLSearchParams('name=x'));  // { name: 'x' }
+// Inferred type: { name: string | undefined }
+```
+
+Note: `z.coerce.*` schemas declare input `unknown`, so a coerce schema without `.default()` keeps its narrow type even though absent input yields `undefined` at runtime — add `.default()` to coerce schemas for accurate types.
+
+### Returns: `SearchParamsDefinition<T>`
+
+| Method / Property         | Description                                            |
+| ------------------------- | ------------------------------------------------------ |
+| `.get()`                  | Read from ALS and parse (server-only)                  |
+| `.parse(searchParams)`    | Parse and validate from `URLSearchParams` or `Promise` |
+| `.useQueryStates(opts?)`  | Client hook — read and update typed search params      |
+| `.extend(codecs)`         | Add additional params                                  |
+| `.pick(...keys)`          | Create a subset                                        |
+| `.href(base, values)`     | Build a full URL with params                           |
+| `.buildSearchParams(values)` | Serialize to a query string — pass to `<Link searchParams>` |
+| `.codecs`                 | Read-only codec map                                    |
+| `.urlKeys`                | Read-only URL key alias map                            |
+
+---
+
+# Segment Params
+
+Segment params are defined globally in `app/schema.ts` via `defineSchema`. Access them with `getSegmentParams()` from `@timber-js/app/server` or `useSegmentParams()` from `@timber-js/app/client`.
+
+## `defineSchema(config)`
+
+Define segment param codecs in a single file. Exported from `@timber-js/app`.
+
+```ts
+import { defineSchema } from '@timber-js/app/params';
+import { codec } from '@timber-js/app/codec';
+import { z } from 'zod/v4';
+
+export default defineSchema({
+  segmentParams: {
+    '[id]': z.coerce.number().int().positive(),
+    '[artistSlug]': codec.string,
+    '[year]': codec.integer,
+  },
+});
+```
+
+Each key uses the bracket syntax from the filesystem. Parse failure → 404.
+
+## `getSegmentParams(segmentPath?)`
+
+Read segment params on the server. ALS-backed. Exported from `@timber-js/app/server`.
+
+```ts
+import { SEGMENT_PATH } from './$segment';
+import { getSegmentParams } from '@timber-js/app/server';
+
+const { id } = getSegmentParams(SEGMENT_PATH); // Exact types from schema
+const params = getSegmentParams();       // Partial<AllSegmentParams>
+```
+
+## `useSegmentParams(segmentPath?)`
+
+Read segment params on the client. Context-backed. Exported from `@timber-js/app/client`.
+
+```tsx
+import { SEGMENT_PATH } from './$segment';
+import { useSegmentParams } from '@timber-js/app/client';
+
+const { id } = useSegmentParams(SEGMENT_PATH); // Exact types from schema
+```
+
+See [Typed Params](/docs/typed-params) for the full guide.
+
+## `SearchParamCodec<T>`
+
+The codec protocol shared across search params, segment params, and cookies. See [Codecs](/docs/typed-params) for the full guide.
+
+```ts
+interface SearchParamCodec<T> {
+  parse(value: string | string[] | undefined): T;
+  serialize(value: T): string | string[] | null;
+  urlKey?: string;
+  // optional total entry point — preferred over parse when present
+  parseServerSide?(value: string | string[] | undefined): T;
+}
+```
+
+`parse` receives the **raw** URL value — `string | string[] | undefined` — because a param may be absent (`/products`) or repeated (`?q=a&q=b`). A codec must handle all three.
+
+If handling all three in `parse` is awkward — as it is for a nuqs parser, whose `parse` is written for a present scalar — publish `parseServerSide` instead. Timber calls it wherever it invokes the codec, and its return type is the field's type: a codec that answers `null` for an absent param is a `SearchParamCodec<T | null>`.
+
+Compatible codecs:
+
+- **Zod/Valibot/ArkType schemas** — auto-detected via Standard Schema. Total over absent and repeated input, so this is the safe default.
+- **Custom** — any object implementing the interface
+- **nuqs parsers** — total through timber, with one exception. See below.
+
+## Parsers come from nuqs
+
+Timber does not ship or re-export `parseAs*` parsers. Import them from [nuqs](https://nuqs.47ng.com/), which is a peer dependency; timber ships the wrappers (`withDefault`, `withUrlKey`) and the schema bridge.
+
+nuqs checks whether a param is present before calling `parse`, so a parser's `parse` assumes a present scalar. Timber calls the parser's `parseServerSide` instead — nuqs's own adapter for the raw URL value — so every **single**-value parser is total:
+
+| Raw value             | Result                                                        |
+| --------------------- | ------------------------------------------------------------- |
+| absent (`/products`)  | `null`, or the parser's own default if it declares one        |
+| repeated (`?v=a&v=b`) | the **first** value, matching `URLSearchParams.get()`         |
+| present               | whatever the parser returns; if it **throws**, `null`         |
+
+So `?page=1&page=2` gives `1`, `parseAsBoolean` on a missing `?debug=` gives `null` rather than an HTTP 500, and `parseAsString` on `?q=a&q=b` gives `'a'` rather than an array its type forbids.
+
+A present value is not validated for you — each parser decides. `parseAsBoolean` on `?v=maybe` is `false`, and `parseAsInteger` on `?v=12abc` is `12`. Use a schema when you need the value rejected rather than coerced.
+
+`parseAsNativeArrayOf` is nuqs's *multi*-value parser for repeated keys (`?tags=a&tags=b`). It works in `defineSearchParams`: timber accepts it via `TotalSearchParamCodec` (its `parseServerSide` covers the full domain) and its `serialize` returns `string[]`, which `buildSearchParams` emits as repeated keys. The codec round-trips correctly.
+
+Two consequences worth knowing:
+
+- **`parseAsArrayOf` reads one key, not repeated keys.** It is a comma-separated list inside a single value, so `?tags=a,b` gives `['a','b']` but `?tags=a&tags=b` gives `['a']`. For repeated keys use `parseAsNativeArrayOf` or an array schema — `tags: z.array(z.string()).default([])`.
+- **`parseAsJson` requires a validator argument** — `parseAsJson(z.object({ … }).parse)`. Called bare it does not type-check, and at runtime returns `null` for every value.
+
+A field typed by a bare parser is nullable (`parseAsString` → `string | null`). Use `withDefault()` — timber's or the parser's own — to make it non-nullable.
+
+## Codec Wrappers
+
+### `withDefault(codec, value)`
+
+Wrap a codec to supply a value whenever the inner codec produces none — `null` or `undefined`. The field is non-nullable.
+
+```ts
+import { withDefault } from '@timber-js/app/search-params';
+import { parseAsInteger } from 'nuqs';
+const page = withDefault(parseAsInteger, 1); // number (never null)
+```
+
+A **present** value is left alone, including a falsy one: `?page=0` is `0`, and `?q=` is `''`, not the default.
+
+### `withUrlKey(codec, key)`
+
+Attach a URL key alias to a codec.
+
+```ts
+import { withUrlKey } from '@timber-js/app/search-params';
+import { z } from 'zod/v4';
+const query = withUrlKey(z.string().nullable().default(null), 'q');
+// ?q=shoes → { query: 'shoes' }
+```