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

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,121 @@
+---
+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. The call-site identity is content-based — it survives restarts and deploys for unchanged `cache()` calls, and changes when you edit the wrapped function or its options (which invalidates the old entries on persistent handlers like Redis). 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).

package/docs/learn/10-middleware.mdx

@@ -0,0 +1,156 @@
+---
+title: 'Middleware'
+description: 'proxy.ts for global concerns, middleware.ts for per-segment logic.'
+slug: 'middleware'
+---
+
+# Middleware
+
+```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: {
+    '[userId]': codec.string,
+  },
+});
+```
+
+timber.js has two middleware layers: `proxy.ts` for global concerns and `middleware.ts` for per-segment logic.
+
+## Middleware vs Access
+
+Before diving in, the first question: should this be middleware or `access.ts`?
+
+|               | `middleware.ts`                        | `access.ts`                       |
+| ------------- | -------------------------------------- | --------------------------------- |
+| Runs          | Before rendering                       | Inside React tree                 |
+| Purpose       | Headers, redirects, cache warming      | Auth, data gating                 |
+| `React.cache` | Not available                          | Active — shares scope with layout |
+| Slots         | N/A                                    | Graceful degradation              |
+
+Use `middleware.ts` for request-level decisions: should this request proceed? What headers does it need? Use `access.ts` for auth — it has `React.cache` and supports slot degradation.
+
+## `proxy.ts` — Global Middleware
+
+`app/proxy.ts` runs on every request before route matching:
+
+```ts title="app/proxy.ts"
+export default [
+  cors({ origins: ['https://example.com'] }),
+  rateLimit({ requests: 100, window: '1m' }),
+  securityHeaders(),
+];
+```
+
+```ts title="app/proxy.ts"
+export default async function proxy(req: Request, next: () => Promise<Response>) {
+  const start = performance.now();
+  const res = await next();
+  console.log(`${req.method} ${req.url} — ${performance.now() - start}ms`);
+  return res;
+}
+```
+
+`proxy.ts` has `next()` — it can wrap the entire request lifecycle. This is where you observe and modify responses.
+
+## `middleware.ts` — Per-Segment Middleware
+
+`middleware.ts` files run after route matching, before rendering. They're scoped to their route segment.
+
+```ts title="app/dashboard/middleware.ts"
+import { redirect } from '@timber-js/app/server';
+import type { MiddlewareContext } from '@timber-js/app/server';
+
+declare function getSession(req: Request): Promise<{ userId: string } | null>;
+
+export default async function middleware(ctx: MiddlewareContext) {
+  const session = await getSession(ctx.req);
+  if (!session) redirect('/login');
+}
+```
+
+**Key differences from proxy.ts:** Middleware does not have `next()`. It's a gate — it either short-circuits (redirect, deny, return a Response) or passes through silently. It cannot observe or modify the render result.
+
+**Key difference from Next.js:** Next.js has a single global `middleware.ts`. timber lets you place `middleware.ts` at any route segment.
+
+## Middleware Context
+
+```ts
+export default async function middleware(ctx: MiddlewareContext) {
+  ctx.req;              // The incoming Request
+  ctx.segmentParams;    // Route params (already coerced by schema.ts)
+  ctx.headers;          // Response headers (writable)
+  ctx.requestHeaders;   // Request headers (injectable)
+}
+```
+
+Middleware can inject request headers that components read later:
+
+```ts title="app/middleware.ts"
+import type { MiddlewareContext } from '@timber-js/app/server';
+
+declare function detectLocale(req: Request): string;
+
+export async function middleware(ctx: MiddlewareContext) {
+  const locale = detectLocale(ctx.req);
+  ctx.requestHeaders.set('x-locale', locale);
+}
+```
+
+```tsx title="app/page.tsx"
+import { getHeaders } from '@timber-js/app/server';
+
+declare function Content(props: { locale: string | null }): React.ReactElement;
+
+export default async function Page() {
+  const locale = (getHeaders()).get('x-locale');
+  return <Content locale={locale} />;
+}
+```
+
+## Execution Order
+
+For a request to `/dashboard/settings`:
+
+1. `proxy.ts` (global)
+2. `app/middleware.ts` (root, if exists)
+3. `app/dashboard/middleware.ts` (segment)
+4. `app/dashboard/settings/middleware.ts` (segment)
+5. `access.ts` checks (inside React tree)
+6. Render
+
+## Cache Warming
+
+Use middleware to fire off data fetches before rendering starts:
+
+```ts title="app/users/[userId]/middleware.ts" use="schema"
+import { SEGMENT_PATH } from './$segment';
+import { getSegmentParams } from '@timber-js/app/server';
+import type { MiddlewareContext } from '@timber-js/app/server';
+
+declare function getUser(userId: string): Promise<{ id: string; name: string }>;
+declare function getUserPosts(userId: string): Promise<{ id: string; title: string }[]>;
+
+export async function middleware(ctx: MiddlewareContext) {
+  const { userId } = getSegmentParams(SEGMENT_PATH);
+  await Promise.all([
+    getUser(userId),
+    getUserPosts(userId),
+  ]);
+}
+```
+
+```tsx title="app/users/[userId]/page.tsx" use="schema"
+import { SEGMENT_PATH } from './$segment';
+
+export default async function UserPage() {
+  const { userId } = getSegmentParams(SEGMENT_PATH);
+  const user = await getUser(userId);       // cache hit
+  const posts = await getUserPosts(userId); // cache hit
+  return <Profile user={user} posts={posts} />;
+}
+```
+
+Without cache warming, these fetches waterfall. With middleware, both fire in parallel before rendering begins.

package/docs/learn/11-error-handling.mdx

@@ -0,0 +1,147 @@
+---
+title: 'Error Handling'
+description: 'Status codes, deny(), error boundaries, and status-code files.'
+slug: 'error-handling'
+---
+
+# Error Handling
+
+```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,
+  },
+});
+```
+
+timber.js distinguishes between two error phases. The phase determines how the error is handled and what HTTP status code the client sees.
+
+## Handler-Phase Errors
+
+Errors thrown before rendering (in middleware, access checks, or the page function before JSX) produce a clean HTTP error. No React involved — the server sends the status code and a minimal body.
+
+## Render-Phase Errors
+
+Errors thrown during React rendering are caught by error boundaries. Because timber buffers until `onShellReady`, errors outside `<Suspense>` still produce correct HTTP status codes.
+
+## `deny()`
+
+`deny()` produces the correct HTTP status and renders the matching status file:
+
+```tsx title="app/products/[id]/page.tsx" use="schema"
+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 canView(product: { id: string }): boolean;
+declare function ProductView(props: { product: { id: string; name: 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
+  if (!canView(product)) deny(); // Default: 403
+
+  return <ProductView product={product} />;
+}
+```
+
+`deny()` called outside `<Suspense>` produces a real HTTP status code. Called inside `<Suspense>` (after the flush), it triggers the nearest error boundary and injects `<meta name="robots" content="noindex">`.
+
+## Status-Code Files
+
+Place status-specific error UIs alongside your routes:
+
+```
+app/
+  dashboard/
+    page.tsx
+    error.tsx      # Catches any unhandled error
+    404.tsx        # "Not found" UI
+    403.tsx        # "Forbidden" UI
+    5xx.tsx        # Catch-all server errors
+    4xx.tsx        # Catch-all client errors
+```
+
+Priority order (innermost to outermost):
+
+1. Specific status files (`403.tsx`, `503.tsx`)
+2. Category catch-alls (`4xx.tsx`, `5xx.tsx`)
+3. Next.js-compatible files: `not-found.tsx` (404), `forbidden.tsx` (403), `unauthorized.tsx` (401)
+4. `error.tsx` — catches anything unmatched
+5. Parent segments → framework default
+
+## `error.tsx`
+
+The general error boundary. It's a client component:
+
+```tsx title="app/dashboard/error.tsx"
+'use client';
+
+export default function DashboardError({
+  error,
+  reset,
+}: {
+  error: Error;
+  reset: () => void;
+}) {
+  return (
+    <div>
+      <h2>Something went wrong</h2>
+      <p>{error.message}</p>
+      <button onClick={reset}>Try again</button>
+    </div>
+  );
+}
+```
+
+Error boundaries wrap page content inside layouts — the layout shell (nav, sidebar) stays visible when an error fires.
+
+When a `deny()` has no matching status-code file, it falls through to the nearest `error.tsx`. The component still receives a real `error` (its message is `Access denied with status <N>`), and additionally receives `status` and `dangerouslyPassData` so you can render denial-specific UI:
+
+```tsx title="app/error.tsx"
+'use client';
+
+export default function ErrorPage({
+  error,
+  reset,
+  status,
+}: {
+  error: Error;
+  reset: () => void;
+  status?: number; // set when this boundary is serving a deny()
+}) {
+  if (status === 404) {
+    return <h2>Not found</h2>;
+  }
+  return (
+    <div>
+      <h2>Something went wrong</h2>
+      <p>{error.message}</p>
+      <button onClick={reset}>Try again</button>
+    </div>
+  );
+}
+```
+
+The HTTP status stays correct either way — `deny(404)` falling through to `error.tsx` still responds with a 404, never a 500.
+
+## Structured Error Data
+
+`deny()` accepts optional JSON-serializable data that is passed to the error page via `dangerouslyPassData`:
+
+```tsx
+import { deny } from '@timber-js/app/server';
+
+if (!product) {
+  deny({
+    status: 404,
+    data: { title: 'Product not found', resourceId: params.id },
+  });
+}
+```
+
+The error boundary receives the structured data via the `dangerouslyPassData` prop, surviving the RSC → client boundary where plain error properties are stripped.