@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.211

package/docs/learn/08-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/09-streaming.mdx

@@ -0,0 +1,140 @@
+---
+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.
+
+There is no `loading.tsx` convention — timber never inserts Suspense boundaries for you. See [The Flush Point](/docs/the-flush-point) for why.
+
+## 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.

package/docs/learn/10-caching.mdx

@@ -0,0 +1,270 @@
+---
+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                         | Yes (same request)   |
+| 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.data(
+  async () => {
+    return db.products.findPopular();
+  },
+  { ttl: 60, tags: ['products'] }
+);
+```
+
+## `cache.data()` 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.data(
+  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.data()` 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.data(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}`);
+```
+
+`revalidateTag` works outside actions too. From a `route.ts` handler, say a CMS webhook, it invalidates immediately, and you await it before responding:
+
+```ts title="app/api/cms-webhook/route.ts"
+export async function POST(ctx: RouteContext) {
+  await revalidateTag('products');
+  return new Response(null, { status: 204 });
+}
+```
+
+`revalidatePath` is different: it re-renders a page into a server action's response, so it only works inside an action.
+
+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.
+
+## Caching Components
+
+`cache.data` caches a function's return value. `cache.component` caches a component's **rendered output** — the RSC flight payload — so re-renders skip the entire component tree:
+
+```tsx title="app/blog/[slug]/page.tsx"
+import { cache } from '@timber-js/app/cache';
+import { getSegmentParams } from '@timber-js/app/server';
+
+const PostBody = cache.component(
+  async function PostBody() {
+    const { slug } = getSegmentParams();
+    const post = await getPost(slug);
+    return (
+      <article>
+        <h1>{post.title}</h1>
+        <PostContent content={post.content} />
+      </article>
+    );
+  },
+  { prerender: true }
+);
+
+export async function generateStaticSegmentParams() {
+  return allPosts.map((p) => ({ slug: p.slug }));
+}
+
+export default async function BlogPost() {
+  return <PostBody />;
+}
+```
+
+The same API gives you three tiers of freshness, controlled by two options:
+
+### Static (build-time only)
+
+Rendered at build for each set of params from `generateStaticSegmentParams`. Changes only on redeploy. Request context (`getCookieJar()`, `getHeaders()`) is a build error.
+
+```tsx
+const BlogBody = cache.component(Body, { prerender: true });
+```
+
+### Cached (runtime only)
+
+Rendered on first request, stored with a TTL. Invalidatable by tag. May read request context (with a warning — be careful not to leak per-user data into a shared cache).
+
+```tsx
+const Pricing = cache.component(PricingTable, {
+  ttl: 300,
+  tags: ['pricing'],
+  staleWhileRevalidate: true,
+});
+```
+
+### ISR (build-seeded, runtime-refreshable)
+
+Rendered at build, but refreshable via `revalidateTag` without a redeploy. Unenumerated params fill in on first request.
+
+```tsx
+const DocsPage = cache.component(DocsBody, {
+  prerender: true,
+  ttl: 3600,
+  tags: ['docs'],
+});
+```
+
+### Mixing Tiers on One Page
+
+A page can combine all three — a dynamic shell with cached islands:
+
+```tsx title="app/blog/[slug]/page.tsx"
+import { getCookieJar } from '@timber-js/app/server';
+
+export default async function BlogPost() {
+  const user = await getUser(getCookieJar());
+  return (
+    <>
+      <Nav user={user} /> {/* dynamic — personalized */}
+      <PostBody /> {/* prerendered — from build artifact */}
+      <Suspense fallback={<CommentsSkeleton />}>
+        <Comments /> {/* dynamic — streams per-request */}
+      </Suspense>
+    </>
+  );
+}
+```
+
+### Route-Level Shorthand
+
+For fully static routes, export `prerender` instead of wrapping the component manually:
+
+```ts title="app/about/page.tsx"
+export const prerender = true;
+```
+
+This desugars to `cache.component(...)` around the page's default export. For dynamic routes (`[slug]`), pair it with `generateStaticSegmentParams` so the build knows which params to prerender:
+
+```ts title="app/docs/[slug]/page.tsx"
+export const prerender = { ttl: 3600, tags: ['docs'] };
+
+export async function generateStaticSegmentParams() {
+  return allDocs.map((d) => ({ slug: d.slug }));
+}
+```
+
+Layout `prerender` cascades to descendant pages unless a closer layout or page overrides it.
+
+### Slots: Dynamic Children Through a Cached Shell
+
+When the expensive part is a wrapper (nav, sidebar, layout chrome) but its children are dynamic, use `slots` to cache the shell with holes for live content:
+
+```tsx
+const Shell = cache.component(ExpensiveWrapper, {
+  ttl: 3600,
+  tags: ['marketing'],
+  slots: ['children'],
+});
+
+// The shell serves from cache; children render live per request.
+<Shell theme="dark">
+  <LiveUserFeed />
+</Shell>;
+```
+
+Slot props are excluded from the cache key. Slots are runtime tier only — `prerender` is ignored when `slots` is active.
+
+## Cache Handlers
+
+The default handler is in-memory. Configure a different backend in `timber.cache.ts`:
+
+```ts title="timber.cache.ts"
+import { MemoryCacheHandler } from '@timber-js/app/cache';
+
+export default 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 />