@timber-js/app 0.2.0-alpha.154 → 0.2.0-alpha.155

package/docs/api/30-api-server.mdx

@@ -0,0 +1,233 @@
+---
+title: 'API: @timber-js/app/server'
+description: 'Server-side exports — deny, redirect, getHeaders, getCookieJar, createActionClient, and context types.'
+slug: 'api-server'
+---
+
+# @timber-js/app/server
+
+Server-side utilities and types. Import from `@timber-js/app/server`.
+
+## Navigation & Status
+
+### `deny(statusOrOptions?, data?)`
+
+Universal denial/error primitive. Produces an HTTP error status and renders the matching status file. Accepts any 4xx or 5xx status code. Default status is 403.
+
+```ts
+import { deny } from '@timber-js/app/server';
+
+deny(); // 403 (default)
+deny(404); // 404 Not Found
+deny(503, { retry: true }); // 503 with data
+deny({ status: 500, data: { title: 'Error' } }); // object form
+```
+
+### `redirect(url, type?)`
+
+Redirect to a URL. Sends HTTP 307 (temporary) by default.
+
+```ts
+import { redirect } from '@timber-js/app/server';
+
+redirect('/login'); // 302 Temporary Redirect
+redirect('/new-page', { permanent: true }); // 308 Permanent Redirect
+redirect('/new-page', { status: 301 }); // 301 (explicit status)
+redirect('/new-page', 301); // 301 (shorthand)
+```
+
+The `permanent` option defaults to status **308** (preserves HTTP method). If you need 301 specifically, pass `status: 301`. When both `permanent` and `status` are provided, `status` wins.
+
+### `redirectExternal(url, allowList, status?)`
+
+Redirect to an external URL. The target origin must be in the provided allow-list. Only `http:` and `https:` schemes are permitted — this prevents open redirect vulnerabilities and blocks `javascript:` scheme injection.
+
+```ts
+import { redirectExternal } from '@timber-js/app/server';
+
+// Redirect to an allowed external domain
+redirectExternal('https://auth.example.com/login', ['https://auth.example.com']);
+
+// With a custom status code
+redirectExternal('https://docs.example.com', ['https://docs.example.com'], 301);
+```
+
+| Parameter   | Type       | Default | Description                                                |
+| ----------- | ---------- | ------- | ---------------------------------------------------------- |
+| `url`       | `string`   | —       | Absolute URL to redirect to                                |
+| `allowList` | `string[]` | —       | Allowed origins (e.g. `['https://example.com']`)           |
+| `status`    | `number`   | `302`   | HTTP redirect status code (3xx)                            |
+
+Throws if the origin is not in the allow-list, the scheme isn't `http:` or `https:`, or the URL is invalid.
+
+## Request Context
+
+### `getHeaders()`
+
+Returns the incoming request headers. ALS-backed — works in server components, middleware, access checks.
+
+```ts
+import { getHeaders } from '@timber-js/app/server';
+
+const h = getHeaders();
+const auth = h.get('authorization');
+```
+
+Returns `ReadonlyHeaders` — a read-only `Headers` interface (sync).
+
+### `getCookieJar()`
+
+Returns the request cookies with mutation methods.
+
+```ts
+import { getCookieJar } from '@timber-js/app/server';
+
+const c = getCookieJar();
+c.get('session'); // Read
+c.set('theme', 'dark'); // Set (before flush only)
+c.delete('session'); // Delete
+c.clear(); // Clear all
+```
+
+Mutations are only allowed before the response flushes. Attempting to set a cookie after flush throws in dev mode.
+
+For typed cookies with validation and a client React hook, see [`defineCookie()`](/docs/typed-params) from `@timber-js/app/cookies`.
+
+## Actions
+
+### `createActionClient(options)`
+
+Create a reusable action client with middleware for auth and validation.
+
+```ts
+import { createActionClient, ActionError } from '@timber-js/app/server';
+import { getUser } from '@/lib/auth';
+
+const action = createActionClient({
+  middleware: async () => {
+    const user = await getUser();
+    if (!user) throw new ActionError('UNAUTHORIZED');
+    return { user };
+  },
+});
+
+// Usage:
+const myAction = action.schema(z.object({ title: z.string() })).action(async ({ input, ctx }) => {
+  // ctx.user is typed from middleware return
+});
+```
+
+### `ActionError`
+
+Throw from action middleware or bodies to produce a typed error result.
+
+```ts
+throw new ActionError('UNAUTHORIZED');
+throw new ActionError('VALIDATION_FAILED', { field: 'email' });
+```
+
+### `revalidatePath(path)`
+
+Re-render a path and return the RSC payload as part of the action response.
+
+### `revalidateTag(tag)`
+
+Invalidate all cache entries with the given tag.
+
+## Segment Params
+
+### `getSegmentParams(segmentPath?)`
+
+Returns route path params for the current request. Pass a `SEGMENT_PATH` string from `$segment` for exact types, or omit for `Partial<AllSegmentParams>`. ALS-backed — works in server components, middleware, access checks, and server actions.
+
+```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>
+```
+
+For typed coercion, define codecs in `app/schema.ts` with `defineSchema()`. See [Typed Params](/docs/typed-params).
+
+## Types
+
+### `RouteContext`
+
+```ts
+interface RouteContext {
+  req: Request;
+  headers: Headers; // Response headers (writable)
+}
+```
+
+Segment params and query params are **not** on `RouteContext`. Read them via the same ALS-backed `.get()` accessors pages use — `segmentParams.get()` from `./params` and `searchParams.get()` from `./search-params`. For the raw query string, use `new URL(ctx.req.url).searchParams`.
+
+### `MiddlewareContext`
+
+```ts
+interface MiddlewareContext {
+  req: Request;
+  segmentParams: Record<string, string | string[]>;
+  headers: Headers;        // Response headers (writable)
+  requestHeaders: Headers; // Request headers (injectable)
+}
+```
+
+### `AccessContext`
+
+Empty interface — `access.ts` takes no arguments. Use ALS-backed imports like `getSegmentParams(SEGMENT_PATH)`.
+
+### `Metadata`
+
+The full metadata type — see [Metadata & SEO](/docs/metadata-and-fonts) for usage.
+
+### `MetadataRoute`
+
+Type for metadata route files (sitemap, robots, etc.).
+
+## Tracing
+
+### `getTraceId()`
+
+Returns the current request's 32-char hex trace ID. Works in middleware, access checks, server components, and server actions.
+
+```ts
+import { getTraceId } from '@timber-js/app/server';
+
+const id = getTraceId();
+```
+
+### `getSpanId()`
+
+Returns the current OTEL span ID, or `undefined` if OTEL is not active.
+
+### `withSpan(name, attributes, fn)`
+
+Run a function within an OTEL span. No-op passthrough if OTEL is not available.
+
+```ts
+import { withSpan } from '@timber-js/app/server';
+
+declare const db: { query(...args: unknown[]): Promise<unknown> };
+
+const result = await withSpan('db.query', { table: 'users' }, () => db.query());
+```
+
+### `addSpanEvent(name, attributes?)`
+
+Add an event to the current active span.
+
+See [Instrumentation & Tracing](/docs/instrumentation) for full documentation.
+
+## Lifecycle
+
+### `waitUntil(promise)`
+
+Register a promise to be kept alive after the response is sent. Platform-dependent — works on Cloudflare Workers and other platforms that support it.
+
+```ts
+import { waitUntil } from '@timber-js/app/server';
+
+waitUntil(analytics.track(event));
+```

package/docs/api/31-api-client.mdx

@@ -0,0 +1,161 @@
+---
+title: 'API: @timber-js/app/client'
+description: 'Client-side exports — Link, useRouter, usePathname, navigation hooks, and form utilities.'
+slug: 'api-client'
+---
+
+# @timber-js/app/client
+
+Client-side components and hooks. Import from `@timber-js/app/client`.
+
+## Components
+
+### `<Link>`
+
+Client-side navigation link. Type-checks `href` against the generated route map.
+
+```tsx
+import { Link } from '@timber-js/app/client';
+
+<Link href="/about">About</Link>
+<Link href="/products/123" replace>Product</Link>
+<Link href="/gallery" onNavigate={(e) => { /* intercept */ }}>Gallery</Link>
+```
+
+#### Props
+
+| Prop         | Type                | Description                                 |
+| ------------ | ------------------- | ------------------------------------------- |
+| `href`       | `string`            | Target URL (type-checked against route map) |
+| `replace`    | `boolean`           | Use `replaceState` instead of `pushState`   |
+| `prefetch`   | `boolean`           | Prefetch on hover/viewport                  |
+| `onNavigate` | `OnNavigateHandler` | Intercept navigation before routing         |
+
+### `<TimberErrorBoundary>`
+
+Error boundary component with reset support.
+
+## Hooks
+
+### `useRouter()`
+
+Programmatic navigation.
+
+```tsx
+const router = useRouter();
+router.push('/dashboard');
+router.replace('/settings');
+router.refresh();
+router.back();
+router.forward();
+```
+
+#### `RouterInstance`
+
+| Method          | Description                        |
+| --------------- | ---------------------------------- |
+| `push(href)`    | Navigate, add history entry        |
+| `replace(href)` | Navigate, replace history entry    |
+| `refresh()`     | Re-fetch current route RSC payload |
+| `back()`        | Go back                            |
+| `forward()`     | Go forward                         |
+
+### `usePathname()`
+
+Returns the current pathname as a string.
+
+```tsx
+const pathname = usePathname(); // "/dashboard/settings"
+```
+
+### `useSelectedLayoutSegment()`
+
+Returns the active child segment within a layout.
+
+```tsx
+const segment = useSelectedLayoutSegment(); // "settings"
+```
+
+### `useSelectedLayoutSegments()`
+
+Returns all active segments below the current layout.
+
+```tsx
+const segments = useSelectedLayoutSegments(); // ["settings", "profile"]
+```
+
+### `usePendingNavigation()`
+
+Returns whether a navigation is in flight. Use instead of wrapping `children` in `<Suspense>`.
+
+```tsx
+const pending = usePendingNavigation();
+```
+
+### `useLinkStatus()`
+
+Per-link pending state. Must be used inside a `<Link>` component's children.
+
+```tsx
+const { pending } = useLinkStatus();
+```
+
+### `useSegmentParams(segmentPath?)`
+
+Returns the current route segment params. Pass `SEGMENT_PATH` from `$segment` for exact types.
+
+```tsx
+import { SEGMENT_PATH } from './$segment';
+import { useSegmentParams } from '@timber-js/app/client';
+
+const { id } = useSegmentParams(SEGMENT_PATH);  // Exact types from schema
+const params = useSegmentParams();        // Partial<AllSegmentParams>
+```
+
+## Form Hooks
+
+### `useActionState(action, initialState)`
+
+Typed wrapper around React 19's `useActionState`. Returns `[result, formAction, isPending, errors]` — the 4th element auto-derives field and form-level errors from the result.
+
+```tsx
+const [result, action, isPending, errors] = useActionState(createTodo, flash);
+
+errors.hasErrors         // boolean
+errors.fieldErrors       // Record<string, string[]>
+errors.formErrors        // string[]
+errors.serverError       // { code, data? } | null
+errors.getFieldError('title') // string | null
+```
+
+### `useFormAction(action)`
+
+Bind a server action to a form with pending state.
+
+## Utilities
+
+### `interpolateParams(pattern, params)`
+
+Fill a route pattern with param values.
+
+```ts
+interpolateParams('/products/[id]', { id: '123' }); // "/products/123"
+```
+
+### `defineSearchParams().useQueryStates()`
+
+Sync typed search params to the URL. Called on a `defineSearchParams()` definition. See [Search Params](/docs/typed-params).
+
+## Cookie Hooks
+
+### `defineCookie().useCookie()`
+
+Reactive cookie access in client components. Define a typed cookie with `defineCookie()` from `@timber-js/app/cookies`, then call `.useCookie()` in client components. Returns `[value, setter, deleter]`.
+
+```tsx
+import { themeCookie } from '../lib/cookies';
+
+const [theme, setTheme, deleteTheme] = themeCookie.useCookie();
+```
+
+See [Cookies](/docs/typed-params) for full documentation.

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

@@ -0,0 +1,193 @@
+---
+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(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(
+  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(...)` 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(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' });
+```
+
+## `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>;
+  expire(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>;
+}
+```
+
+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 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),
+  expire: (k, s) => redis.expire(k, s),
+  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="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 }),
+  expire: (k, s) => redis.expire(k, s),
+  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 }),
+  expire: (k, s) => redis.expire(k, s),
+  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.