@timber-js/app 0.2.0-alpha.16 → 0.2.0-alpha.161

package/docs/learn/06-forms-and-actions.mdx

@@ -0,0 +1,146 @@
+---
+title: 'Forms and Actions'
+description: 'Server actions with validation, progressive enhancement, and forms that work without JavaScript.'
+slug: 'forms-and-actions'
+---
+
+# Forms and Actions
+
+Forms in timber.js work without JavaScript. They submit to the server, validate, and return a result. When JavaScript is available, they enhance with client-side state and pending UI.
+
+## Action Clients
+
+Define reusable action middleware with `createActionClient`:
+
+```ts title="lib/action.ts"
+import { createActionClient, ActionError } from '@timber-js/app/server';
+import { getUser } from '@/lib/auth';
+
+export const action = createActionClient({
+  middleware: async () => {
+    const user = await getUser();
+    if (!user) throw new ActionError('UNAUTHORIZED');
+    return { user };
+  },
+});
+```
+
+## Defining Actions
+
+```ts title="app/todos/actions.ts"
+'use server';
+
+import { z } from 'zod/v4';
+import { action } from '@/lib/action';
+import { revalidatePath } from '@timber-js/app/server';
+
+declare const db: { todos: { create(data: { title: string; userId: string }): Promise<void> } };
+
+export const createTodo = action
+  .schema(z.object({ title: z.string().min(1) }))
+  .action(async ({ input, ctx }) => {
+    await db.todos.create({ ...input, userId: ctx.user.id });
+    return revalidatePath('/todos');
+  });
+```
+
+The `.schema()` method accepts any Standard Schema-compatible validator — Zod, Valibot, or ArkType. Validation errors are returned to the client automatically.
+
+## Using Actions in Forms
+
+```tsx title="app/todos/todo-form.tsx"
+'use client';
+
+import { useActionState } from '@timber-js/app/client';
+import { createTodo } from './actions';
+
+export default function TodoForm() {
+  const [state, action, pending, errors] = useActionState(createTodo, null);
+
+  return (
+    <form action={action}>
+      <div>
+        <input name="title" required />
+        {errors.getFieldError('title') && (
+          <p className="text-red-600">{errors.getFieldError('title')}</p>
+        )}
+      </div>
+      {errors.serverError && (
+        <p className="text-red-600">Something went wrong. Please try again.</p>
+      )}
+      <button type="submit" disabled={pending}>
+        {pending ? 'Adding...' : 'Add Todo'}
+      </button>
+    </form>
+  );
+}
+```
+
+Without JS, this submits as a standard form POST. With JS, `useActionState` handles pending state and error display.
+
+### Form Errors
+
+`useActionState` from `@timber-js/app/client` returns a 4-tuple where the 4th element is auto-derived form errors:
+
+```tsx
+const [state, action, pending, errors] = useActionState(myAction, null);
+
+errors.fieldErrors;              // Record<string, string[]>
+errors.formErrors;               // string[] (form-level errors)
+errors.serverError;              // { code: string; data?: Record<string, unknown> } | null
+errors.hasErrors;                // boolean
+errors.getFieldError('title');   // string | null (first error for field)
+```
+
+## After Mutation
+
+| Pattern                   | When to use                                      |
+| ------------------------- | ------------------------------------------------ |
+| `redirect('/path')`       | User should land somewhere new                   |
+| `revalidatePath('/path')` | Current page needs fresh data                    |
+| `useOptimistic`           | Instant UI update, action confirms in background |
+
+## Forms Without JavaScript
+
+When JavaScript is disabled and a server action returns validation errors, timber re-renders the page instead of redirecting. The errors and submitted values are available via `getFormFlash()`:
+
+```tsx title="app/todos/page.tsx"
+import { getFormFlash } from '@timber-js/app/server';
+import { TodoForm } from './todo-form';
+
+export default async function TodosPage() {
+  const flash = getFormFlash();
+  return <TodoForm flash={flash} />;
+}
+```
+
+```tsx title="app/todos/todo-form.tsx"
+'use client';
+
+import { useActionState } from '@timber-js/app/client';
+import { createTodo } from './actions';
+import type { FormFlashData } from '@timber-js/app/server';
+
+export function TodoForm({ flash }: { flash?: FormFlashData | null }) {
+  const [state, action, pending, errors] = useActionState(createTodo, null);
+
+  const fieldError = (field: string) =>
+    errors.getFieldError(field) ?? flash?.validationErrors?.[field]?.[0];
+  const defaultValue = (field: string) =>
+    (flash?.submittedValues?.[field] as string) ?? '';
+
+  return (
+    <form action={action}>
+      <input name="title" defaultValue={defaultValue('title')} />
+      {fieldError('title') && <p className="text-red-600">{fieldError('title')}</p>}
+      <button type="submit" disabled={pending}>
+        {pending ? 'Adding...' : 'Add Todo'}
+      </button>
+    </form>
+  );
+}
+```
+
+Flash data is server-side only — stored in AsyncLocalStorage for the duration of the re-render. Sensitive fields (password, apiKey, cvv, etc.) are automatically stripped from `submittedValues`.
+
+For advanced topics — coercion helpers, `parseFormData`, sensitive field stripping configuration, and the full end-to-end example — see [Advanced Forms](/docs/advanced-forms).

package/docs/learn/07-typed-routes.mdx

@@ -0,0 +1,127 @@
+---
+title: 'Typed Routes'
+description: 'Build-time route types — <Link> validates href, params are inferred from the file tree.'
+slug: 'typed-routes'
+---
+
+# Typed Routes
+
+timber.js generates route types at build time. `<Link>` type-checks `href` against your actual route tree. Segment params are inferred from directory names. Search params are typed when you define them.
+
+## How It Works
+
+When you run `timber dev` or `timber build`, the framework scans your `app/` directory and generates a route map in `.timber/routes.d.ts`:
+
+```ts
+// .timber/routes.d.ts (generated, gitignored)
+export interface TimberSegmentParams {
+  '/': {};
+  '/products/[id]': { id: number };
+  '/blog/[...slug]': { slug: string[] };
+}
+```
+
+Types reference your `app/schema.ts` codecs directly, so they stay in sync automatically.
+
+## Typed `<Link>`
+
+`<Link>` validates `href` against the route map. Invalid routes are caught at build time:
+
+```tsx
+import { Link } from '@timber-js/app/client';
+
+<Link href="/about">About</Link>           // ✓ known route
+<Link href="/nonexistent">Bad</Link>        // ✗ TypeScript error
+```
+
+For dynamic routes, pass `segmentParams`:
+
+```tsx
+import { Link } from '@timber-js/app/client';
+
+<Link href="/products/[id]" segmentParams={{ id: 42 }}>
+  Product
+</Link>
+// → <a href="/products/42">Product</a>
+```
+
+Or use an interpolated href directly:
+
+```tsx
+<Link href={`/products/${id}`}>Product</Link>
+```
+
+Both forms are type-safe. With the pattern form (`/products/[id]`), `segmentParams` is required and typed. With the interpolated form, `segmentParams` is forbidden.
+
+## Typed Segment Params
+
+Each route directory gets a generated `$segment` module. Import `SEGMENT_PATH` for type-safe param access:
+
+```tsx
+// app/products/[id]/page.tsx
+import { SEGMENT_PATH } from './$segment';
+import { getSegmentParams } from '@timber-js/app/server';
+
+export default async function ProductPage() {
+  const { id } = getSegmentParams(SEGMENT_PATH);
+  // id is typed from your schema codec (e.g., number for codec.integer)
+}
+```
+
+Without `SEGMENT_PATH`, params are untyped — all optional strings.
+
+### tsconfig.json
+
+Add `rootDirs` so TypeScript can resolve `$segment` imports:
+
+```jsonc
+{
+  "compilerOptions": {
+    "rootDirs": [".", ".timber/types"]
+  }
+}
+```
+
+## Typed Search Params
+
+When a `params.ts` file exports `searchParams`, search params are fully typed throughout the stack:
+
+```ts title="app/products/params.ts"
+import { defineSearchParams, withDefault, withUrlKey } from '@timber-js/app/search-params';
+import { parseAsInteger, parseAsString, parseAsStringEnum } from 'nuqs';
+import { z } from 'zod/v4';
+
+export const searchParams = defineSearchParams({
+  page: withDefault(parseAsInteger, 1),
+  q: withUrlKey(parseAsString, 'search'),
+  category: z.string().nullable().default(null),
+  sort: withDefault(parseAsStringEnum(['price-asc', 'price-desc', 'newest']), 'newest'),
+});
+```
+
+```tsx title="app/products/page.tsx"
+import { searchParams } from './params';
+
+export default async function ProductsPage() {
+  const { page, q, category, sort } = await searchParams.get();
+  // page: number, q: string | null, category: string | null, sort: 'price-asc' | ...
+}
+```
+
+`<Link>` validates `searchParams` against the route's definition too:
+
+```tsx
+<Link
+  href="/products/[id]"
+  segmentParams={{ id }}
+  searchParams={{ sort: 'newest', q: 'boots' }}
+/>
+```
+
+See [Typed Params](/docs/typed-params) for the full search params API.
+
+## Codegen
+
+Types are generated during `timber dev` (on startup and when routes change) and `timber build`. The generated `.timber/routes.d.ts` is gitignored — it's a build artifact. Run `timber dev` once to get types for your editor.
+
+For the full type definitions and context types (`RouteContext`, `MiddlewareContext`, `AccessContext`), see the [TypeScript API Reference](/docs/api-typescript).

package/docs/learn/08-streaming.mdx

@@ -0,0 +1,146 @@
+---
+title: 'Streaming'
+description: 'Suspense placement, deferSuspenseFor, and the layout footgun.'
+slug: 'streaming'
+---
+
+# Streaming
+
+```ts title="app/schema.ts" id="schema" hidden
+import { defineSchema } from '@timber-js/app/params';
+import { codec } from '@timber-js/app/codec';
+
+export default defineSchema({
+  segmentParams: {
+    '[id]': codec.string,
+  },
+});
+```
+
+Streaming lets the server send HTML to the browser in chunks as it becomes ready. timber uses streaming selectively — the shell is sent as a complete block, and only `<Suspense>` boundaries stream in afterward.
+
+## The Shell vs. Suspense Boundaries
+
+timber divides your page into two phases:
+
+**The shell** (before the [flush point](/docs/the-flush-point)):
+- Layouts, navigation, page structure
+- Primary content that defines the page
+- Determines the HTTP status code
+
+**Suspense boundaries** (after the flush):
+- Secondary content wrapped in `<Suspense>`
+- Streams in progressively as data resolves
+- Cannot affect the status code
+
+```tsx title="app/products/[id]/page.tsx" use="schema"
+import { Suspense } from 'react';
+import { SEGMENT_PATH } from './$segment';
+import { deny, getSegmentParams } from '@timber-js/app/server';
+
+declare function getProduct(id: string): Promise<{ id: string; name: string } | null>;
+declare function ReviewsSkeleton(): React.ReactElement;
+declare function ProductReviews(props: { productId: string }): React.ReactElement;
+
+export default async function ProductPage() {
+  const { id } = getSegmentParams(SEGMENT_PATH);
+  const product = await getProduct(id);
+  if (!product) deny(404); // Real HTTP 404
+
+  return (
+    <div>
+      <h1>{product.name}</h1>
+      <Suspense fallback={<ReviewsSkeleton />}>
+        <ProductReviews productId={product.id} />
+      </Suspense>
+    </div>
+  );
+}
+```
+
+The product loads before the flush — if it doesn't exist, the server sends a real 404. Reviews stream in later.
+
+## Choosing What to Stream
+
+**Don't stream** (keep in the shell):
+- Content that defines the page — the product, the article, the user profile
+- Content that might produce a 404 or redirect
+- Content that should be visible without JavaScript
+
+**Do stream** (wrap in `<Suspense>`):
+- Recommendations, related items, activity feeds
+- Analytics widgets, personalization
+- Anything slow that isn't essential to the page's identity
+
+The rule: if missing content means the page shouldn't exist, don't stream it.
+
+## No `loading.tsx`
+
+There is no `loading.tsx` convention. timber does not insert Suspense boundaries for you. If you want a loading state, you place `<Suspense>` explicitly. This keeps you in control of what streams and what blocks.
+
+## The Layout Suspense Footgun
+
+Wrapping `children` in `<Suspense>` inside a layout surrenders HTTP correctness for every page in that subtree:
+
+```tsx
+// ⚠️ Don't do this
+export default function Layout({ children }: { children: React.ReactNode }) {
+  return (
+    <Shell>
+      <Suspense fallback={<Skeleton />}>{children}</Suspense>
+    </Shell>
+  );
+}
+```
+
+The framework warns in dev mode when this is detected. For navigation loading states, use `usePendingNavigation()` instead.
+
+## `deferSuspenseFor`
+
+Sometimes Suspense content resolves fast enough that you'd rather wait for it than show a fallback. `deferSuspenseFor` holds the SSR stream for a specified duration:
+
+```tsx title="app/products/[id]/page.tsx" use="schema"
+import { Suspense } from 'react';
+import { SEGMENT_PATH } from './$segment';
+import { deny, getSegmentParams } from '@timber-js/app/server';
+
+declare function getProduct(id: string): Promise<{ id: string; name: string } | null>;
+declare function ProductHeader(props: { product: { name: string } }): React.ReactElement;
+declare function ReviewsSkeleton(): React.ReactElement;
+declare function ProductReviews(props: { productId: string }): React.ReactElement;
+
+export const deferSuspenseFor = 200; // milliseconds
+
+export default async function ProductPage() {
+  const { id } = getSegmentParams(SEGMENT_PATH);
+  const product = await getProduct(id);
+  if (!product) deny(404);
+
+  return (
+    <div>
+      <ProductHeader product={product} />
+      <Suspense fallback={<ReviewsSkeleton />}>
+        <ProductReviews productId={product.id} />
+      </Suspense>
+    </div>
+  );
+}
+```
+
+If reviews resolve within 200ms, they render inline — no fallback shown. If they take longer, the fallback flushes and reviews stream in when ready.
+
+## Signal Promotion
+
+When `deny()` or `redirect()` fires inside a `<Suspense>` boundary:
+
+**Before the flush** — the signal is promoted to pre-flush semantics. The framework sends the correct HTTP status code and renders the appropriate status file.
+
+**After the flush** — the status code is already committed. The signal triggers an error boundary in the client, and timber adds `<meta name="robots" content="noindex">`.
+
+`deferSuspenseFor` extends the window where signals can be promoted.
+
+**The rule:** don't rely on Suspense-wrapped content to control the status code. If content must drive the status code, fetch it outside `<Suspense>`. Signal promotion is a safety net, not a guarantee.
+
+## Early Hints (103)
+
+Before the flush, timber sends 103 Early Hints with CSS, fonts, and JS URLs. These fire at route-match time — before middleware runs — based on the build manifest. The browser starts fetching resources while the server is still working.

package/docs/learn/09-caching.mdx

@@ -0,0 +1,136 @@
+---
+title: 'Caching'
+description: 'Explicit caching with timber.cache — TTL, tags, staleWhileRevalidate, and pluggable backends.'
+slug: 'caching'
+---
+
+# Caching
+
+timber.js does not cache anything by default. No patched `fetch`, no implicit data cache. If you want caching, you ask for it explicitly.
+
+## timber.cache vs React.cache
+
+This is the number one confusion point. They are different things:
+
+|                     | `timber.cache`              | `React.cache`        |
+| ------------------- | --------------------------- | -------------------- |
+| Scope               | Cross-request (persistent)  | Single request       |
+| TTL/tags            | Yes                         | No                   |
+| Works in middleware  | Yes                         | No                   |
+| Use case            | Database queries, API calls | Request-scoped dedup |
+
+`React.cache` deduplicates within a single request — if three components call `getUser(id)`, only one database query runs. `timber.cache` persists across requests with TTL — the same query serves cached results for 60 seconds.
+
+```tsx title="lib/data.ts"
+import { cache } from 'react';
+import { cache as timberCache } from '@timber-js/app/cache';
+
+declare const db: {
+  users: { findUnique(opts: { where: { id: string } }): Promise<{ id: string; name: string }> };
+  products: { findPopular(): Promise<{ id: string; name: string }[]> };
+};
+
+// Deduplicates within one request
+export const getUser = cache(async (id: string) => {
+  return db.users.findUnique({ where: { id } });
+});
+
+// Caches across requests for 60 seconds
+export const getPopularProducts = timberCache(
+  async () => {
+    return db.products.findPopular();
+  },
+  { ttl: 60, tags: ['products'] }
+);
+```
+
+## `timber.cache()` Options
+
+```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,                                   // Cache for 60 seconds
+    key: (userId) => `user:${userId}`,         // Explicit cache key (optional)
+    staleWhileRevalidate: true,                // Serve stale while refetching
+    tags: (userId) => [`user:${userId}`],      // For tag-based invalidation
+  }
+);
+```
+
+`tags` accepts a static array (`['products']`) or a function that receives the same arguments as the wrapped function.
+
+## Cache Keys
+
+Without an explicit `key`, the cache key is derived from the call site plus a deterministic serialization of the arguments.
+
+### Content-Derived Cache Identities
+
+The call-site identity is content-based — derived from the source code of the `cache()` call, not its position in the file. This means:
+
+- **Unchanged code = cache survives deploys.** If you redeploy without changing a cached function, its entries remain valid on persistent handlers like Redis or KV.
+- **Changed code = automatic invalidation.** Editing the wrapped function or its options changes the cache identity, which invalidates old entries without manual cache busting.
+
+This works for namespace imports, re-exports, and other patterns where the call site isn't trivially traceable. For callsites that can't be statically traced, a deterministic source-hash runtime fallback ensures cache identities never collide across instances.
+
+Object key order doesn't matter — `{ a: 1, b: 2 }` and `{ b: 2, a: 1 }` produce the same key. `Date`, `URL`, and anything with a `toJSON()` method serialize the way `JSON.stringify` would; `Map` and `Set` are serialized by their entries.
+
+Arguments that can't be serialized faithfully — functions, symbols, or class instances whose data lives behind getters with no `toJSON()` — throw a `TypeError` instead of silently colliding. If you hit this, pass an explicit `key`:
+
+```ts
+cache(fn, { ttl: 60, key: (session) => `events:${session.userId}` });
+```
+
+## Invalidation
+
+Invalidate by tag:
+
+```ts
+import { revalidateTag } from '@timber-js/app/server';
+
+// In a server action after updating a product:
+revalidateTag('products');
+revalidateTag(`user:${userId}`);
+```
+
+Invalidation wins races against in-flight cached functions: if a cached function is mid-execution when you invalidate one of its tags (the usual mutation flow — update the database, then `revalidateTag`), its result is not written back to the cache, and callers arriving after the invalidation re-execute instead of joining the superseded execution. This guard is per-process; with a shared handler (Redis/KV), an invalidation from a *different* instance can still race a concurrent write on this one.
+
+## `staleWhileRevalidate`
+
+When enabled, expired entries are served immediately while a background refetch runs:
+
+- **0–60s:** Fresh. Served from cache.
+- **60s+:** Stale. Served immediately, background refetch starts.
+- **Next request after refetch:** Gets fresh data.
+
+On serverless platforms (Cloudflare Workers, Lambda), the background refetch is automatically registered with the platform's `waitUntil` so it completes even after the response is sent. If the refetch fails, the stale entry continues to be served and the error is logged.
+
+## Singleflight
+
+When multiple concurrent requests miss the cache for the same key, only one executes the underlying function. The rest wait for the result. The result is written to the cache exactly once, by the execution that ran the function. This is built in — no opt-in needed.
+
+## Cache Handlers
+
+The default handler is in-memory. Configure a different backend in `timber.config.ts`:
+
+```ts title="timber.config.ts"
+import { MemoryCacheHandler } from '@timber-js/app/cache';
+
+export default {
+  cacheHandler: new MemoryCacheHandler(),
+};
+```
+
+Implement the `CacheHandler` interface for Redis, Cloudflare KV, or any other backend. See the [Cache API Reference](/docs/api-cache).
+
+import SlowStaticComponent from '@/ui/SlowStaticComponent';
+
+<SlowStaticComponent />