@timber-js/app 0.2.0-alpha.19 → 0.2.0-alpha.191

package/LICENSE

@@ -0,0 +1,8 @@
+DONTFUCKINGUSE LICENSE
+
+Copyright (c) 2025 Daniel Saewitz
+
+This software may not be used, copied, modified, merged, published,
+distributed, sublicensed, or sold by anyone other than the copyright holder.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.

package/agent-skill.md

@@ -0,0 +1,344 @@
+# timber.js — AI Agent Skill
+
+Use this skill when building, modifying, or debugging a timber.js application. timber.js is a Vite-native React framework with file-system routing, React Server Components, and real HTTP status codes.
+
+timber.js is inspired by, but is NOT Next.js. Do not assume Next.js features, APIs, or conventions work in timber. The routing structure is similar, but the APIs, rendering model, and conventions diverge significantly. Always consult timber docs, not Next.js docs.
+
+Full documentation is available in `node_modules/@timber-js/app/docs/` (MDX files). Read the relevant doc before implementing a feature. This skill covers the essential patterns — the docs go deeper.
+
+## Project structure
+
+```
+app/
+  layout.tsx        # Root layout (required) — wraps all pages
+  page.tsx          # Home page (/)
+  globals.css       # Global styles
+  about/
+    page.tsx        # /about
+  blog/
+    layout.tsx      # Blog layout — wraps blog pages
+    page.tsx        # /blog
+    [slug]/
+      page.tsx      # /blog/:slug
+timber.config.ts    # Framework config (output mode, adapter, cache)
+vite.config.ts      # Vite config — imports timber()
+tsconfig.json
+```
+
+## Segment convention files
+
+Each directory in `app/` is a **segment**. These files have special meaning:
+
+| File            | Purpose                                                       |
+| --------------- | ------------------------------------------------------------- |
+| `page.tsx`      | Route leaf — renders at this URL                              |
+| `layout.tsx`    | Persistent shell — wraps children, survives client navigation |
+| `access.ts`     | Auth gate — runs inside React tree, supports slot degradation |
+| `middleware.ts` | Pre-render hook — headers, redirects, cache warming           |
+| `schema.ts`     | Segment & search param codecs                                 |
+| `error.tsx`     | Error boundary for this subtree                               |
+| `404.tsx`       | Custom 404 page (must be a client component)                  |
+
+There is NO `loading.tsx`. Use `<Suspense>` with the flush point model instead.
+
+## Key imports
+
+```ts
+// Server (server components, middleware, access, actions)
+import { deny, redirect, getHeaders, getCookieJar, getSegmentParams,
+         createActionClient, ActionError, revalidatePath, revalidateTag,
+         waitUntil, getTraceId, withSpan } from '@timber-js/app/server';
+
+// Client (client components)
+import { Link, useRouter, usePathname, useActionState,
+         useSegmentParams, usePendingNavigation, useLinkStatus,
+         useSelectedLayoutSegment } from '@timber-js/app/client';
+
+// Typed params
+import { defineSchema } from '@timber-js/app/params';
+import { codec } from '@timber-js/app/codec';
+import { defineSearchParams } from '@timber-js/app/search-params';
+import { defineCookie } from '@timber-js/app/cookies';
+
+// Caching
+import { cache } from '@timber-js/app/cache';
+
+// Generated segment module (typed params, segment path)
+import { SEGMENT_PATH } from './$segment';
+```
+
+## Pages and layouts
+
+Pages are server components by default — async, server-only, zero client JS:
+
+```tsx
+// app/products/[id]/page.tsx
+import { SEGMENT_PATH } from './$segment';
+import { deny, getSegmentParams } from '@timber-js/app/server';
+
+export default async function ProductPage() {
+  const { id } = getSegmentParams(SEGMENT_PATH);
+  const product = await db.products.find(id);
+  if (!product) return deny(404); // Real HTTP 404
+  return <h1>{product.name}</h1>;
+}
+```
+
+Layouts receive `{ children }` and persist across navigation:
+
+```tsx
+// app/layout.tsx — root layout (required)
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+## Server and client components
+
+**Server components** (default): async, access secrets/DB, zero client JS cost.
+**Client components** (`'use client'`): `useState`, `useEffect`, event handlers, browser APIs.
+
+```tsx
+// app/counter.tsx
+'use client';
+import { useState } from 'react';
+export function Counter() {
+  const [count, setCount] = useState(0);
+  return <button onClick={() => setCount(c => c + 1)}>{count}</button>;
+}
+```
+
+Server components can render client components as children. Client components cannot import server components (pass them as `children` or props instead).
+
+## deny() and redirect()
+
+`deny()` produces real HTTP status codes. `redirect()` sends HTTP redirects.
+
+```ts
+deny();           // 403 (default)
+deny(404);        // 404 Not Found
+deny(503, data);  // 503 with data for error boundary
+
+redirect('/login');                     // 307 temporary
+redirect('/new-page', { permanent: true }); // 308 permanent
+```
+
+## Forms and server actions
+
+Actions use `createActionClient` for reusable middleware:
+
+```ts
+// lib/action.ts
+'use server';
+import { createActionClient, ActionError } from '@timber-js/app/server';
+
+export const actionClient = createActionClient({
+  middleware: async () => {
+    const user = await getUser();
+    if (!user) throw new ActionError('UNAUTHORIZED');
+    return { user };
+  },
+});
+```
+
+```ts
+// app/todos/actions.ts
+'use server';
+import { z } from 'zod/v4';
+import { action } from '@/lib/action';
+import { revalidatePath } from '@timber-js/app/server';
+
+export const createTodo = actionClient
+  .schema(z.object({ title: z.string().min(1) }))
+  .action(async ({ input, ctx }) => {
+    await db.todos.create({ ...input, userId: ctx.user.id });
+    return revalidatePath('/todos');
+  });
+```
+
+```tsx
+// app/todos/todo-form.tsx
+'use client';
+import { useActionState } from '@timber-js/app/client';
+import { createTodo } from './actions';
+
+export function TodoForm() {
+  const [state, formAction, pending, errors] = useActionState(createTodo, null);
+  return (
+    <form action={formAction}>
+      <input name="title" required />
+      {errors.getFieldError('title') && <p>{errors.getFieldError('title')}</p>}
+      <button disabled={pending}>{pending ? 'Adding...' : 'Add'}</button>
+    </form>
+  );
+}
+```
+
+Forms work without JavaScript — they submit as standard POST. With JS, `useActionState` enhances with pending state.
+
+## Access control (access.ts)
+
+```ts
+// app/(authenticated)/access.ts
+import { getCookieJar, redirect } from '@timber-js/app/server';
+
+export default async function access() {
+  const session = getSession(getCookieJar());
+  if (!session) return redirect('/login');
+}
+```
+
+Access runs inside the React tree. It shares `React.cache` scope with layouts. For parallel routes (slots), denied slots degrade gracefully while the rest of the page renders.
+
+## Middleware
+
+Two layers: `proxy.ts` (global, has `next()`) and `middleware.ts` (per-segment, no `next()`).
+
+```ts
+// app/dashboard/middleware.ts
+import { redirect } from '@timber-js/app/server';
+import type { MiddlewareContext } from '@timber-js/app/server';
+
+export default async function middleware(ctx: MiddlewareContext) {
+  const session = await getSession(ctx.req);
+  if (!session) redirect('/login');
+  ctx.headers.set('x-custom', 'value'); // Set response headers
+}
+```
+
+Use middleware for headers, redirects, cache warming. Use `access.ts` for auth.
+
+## Typed params
+
+Define codecs in `app/schema.ts`:
+
+```ts
+// app/schema.ts
+import { defineSchema } from '@timber-js/app/params';
+import { codec } from '@timber-js/app/codec';
+
+export default defineSchema({
+  segmentParams: {
+    '[id]': codec.integer,
+    '[slug]': codec.string,
+  },
+});
+```
+
+## Search params
+
+```ts
+// app/products/search-params.ts
+import { defineSearchParams } from '@timber-js/app/search-params';
+import { codec } from '@timber-js/app/codec';
+
+export const { searchParams } = defineSearchParams({
+  q: codec.string.optional,
+  page: codec.integer.default(1),
+});
+```
+
+Server: `searchParams.get()`. Client: `searchParams.useQueryStates()`.
+
+## Caching
+
+No implicit caching. `fetch()` is never patched. Use `timber.cache()` for cross-request caching:
+
+```ts
+import { cache } from '@timber-js/app/cache';
+
+const getProducts = cache(
+  async () => db.products.findMany(),
+  { ttl: 60, tags: ['products'] }
+);
+```
+
+Use `React.cache` for single-request deduplication.
+
+## The flush point
+
+timber holds the HTTP response until the shell (everything outside `<Suspense>`) resolves. This means:
+
+- Data fetched outside `<Suspense>` can affect the status code (`deny(404)` works)
+- Data inside `<Suspense>` streams after the shell flushes
+- There is no `loading.tsx` — use `<Suspense>` with a fallback explicitly
+
+## Configuration
+
+```ts
+// timber.config.ts
+import { cloudflare } from '@timber-js/app/adapters/cloudflare';
+
+export default {
+  output: 'server',        // or 'static'
+  adapter: cloudflare(),   // or nitro({ preset: 'node-server' })
+};
+```
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite';
+import { timber } from '@timber-js/app';
+
+export default defineConfig({
+  plugins: [timber()],
+});
+```
+
+## Client navigation
+
+```tsx
+import { Link } from '@timber-js/app/client';
+
+<Link href="/about">About</Link>
+<Link href="/products/123" prefetch>Product</Link>
+```
+
+```tsx
+const router = useRouter();
+router.push('/dashboard');
+router.replace('/settings');
+router.refresh();
+```
+
+## Route patterns
+
+- `(group)/` — route group (no URL segment)
+- `_private/` — excluded from routing
+- `[param]/` — dynamic segment
+- `[...catchAll]/` — catch-all segment
+- `@slot/` — parallel route (named slot)
+- `(.)path/` — intercepting route
+
+## Common mistakes to avoid
+
+1. **No `loading.tsx`** — timber doesn't have it. Use `<Suspense>` explicitly.
+2. **Don't patch fetch** — `fetch()` is never cached. Use `timber.cache()` or `React.cache`.
+3. **`deny()` not `throw new Error`** — use `deny(404)` for proper status codes, not error throwing.
+4. **Server actions need `'use server'`** — at the top of the file or the function.
+5. **`access.ts` exports a default function** — not a named export.
+6. **Root layout must include `<html>` and `<body>`** — timber doesn't add these.
+7. **`getSegmentParams` uses ALS** — works in server components, middleware, access, actions. No prop drilling needed.
+8. **`useActionState` returns 4 values** — `[state, formAction, isPending, errors]`. The 4th is timber-specific with `errors.getFieldError()`, `errors.fieldErrors`, `errors.serverError`.
+9. **Middleware has one arg** — `middleware(ctx: MiddlewareContext)`, not `(req, res)`.
+10. **Don't use `next/` imports** — use `@timber-js/app/server`, `@timber-js/app/client`, etc.
+
+## Commands
+
+```bash
+pnpm dev          # Start dev server
+pnpm build        # Production build
+pnpm preview      # Preview production build
+```
+
+## Further reading
+
+Full docs are in `node_modules/@timber-js/app/docs/`. Key files:
+
+- `docs/learn/` — Core concepts (pages, data fetching, forms, caching, middleware)
+- `docs/more/` — Advanced topics (routing, metadata, MDX, content collections, security)
+- `docs/api/` — API reference for every export

package/dist/_chunks/actions-BjbbNRFN.js

@@ -0,0 +1,318 @@
+import { i as revalidationAls } from "./als-registry-C6kcfprT.js";
+import { J as withSpan, _ as RedirectSignal, g as DenySignal } from "./logger-CH7IcMmg.js";
+import { t as cache } from "./cache-api-DllJ-Lyw.js";
+//#region src/server/form-data.ts
+/**
+* FormData preprocessing — schema-agnostic conversion of FormData to typed objects.
+*
+* FormData is all strings. Schema validation expects typed values. This module
+* bridges the gap with intelligent coercion that runs *before* schema validation.
+*
+* Inspired by zod-form-data, but schema-agnostic — works with any Standard Schema
+* library (Zod, Valibot, ArkType).
+*
+* See design/08-forms-and-actions.md §"parseFormData() and coerce helpers"
+*/
+/**
+* Convert FormData into a plain object with intelligent coercion.
+*
+* Handles:
+* - **Duplicate keys → arrays**: `tags=js&tags=ts` → `{ tags: ["js", "ts"] }`
+* - **Nested dot-paths**: `user.name=Alice` → `{ user: { name: "Alice" } }`
+* - **Empty strings → undefined**: Enables `.optional()` semantics in schemas
+* - **Empty Files → undefined**: File inputs with no selection become `undefined`
+* - **Strips `$ACTION_*` fields**: React's internal hidden fields are excluded
+*/
+function parseFormData(formData) {
+	const flat = {};
+	for (const key of new Set(formData.keys())) {
+		if (key.startsWith("$ACTION_")) continue;
+		if (DANGEROUS_KEYS.has(key)) continue;
+		const processed = formData.getAll(key).map(normalizeValue);
+		if (processed.length === 1) flat[key] = processed[0];
+		else flat[key] = processed.filter((v) => v !== void 0 && v !== "");
+	}
+	return expandDotPaths(flat);
+}
+/**
+* Normalize a single FormData entry value.
+* - Empty File objects (no selection) → undefined
+* - Strings pass through as-is (empty strings stay as empty strings so
+*   schema validators like `z.string().min(1, 'Required')` can produce
+*   their custom error messages instead of a generic type mismatch)
+* - Everything else passes through as-is
+*/
+function normalizeValue(value) {
+	if (value instanceof File && value.size === 0 && value.name === "") return;
+	return value;
+}
+/**
+* Expand dot-notation keys into nested objects.
+* `{ "user.name": "Alice", "user.age": "30" }` → `{ user: { name: "Alice", age: "30" } }`
+*
+* Keys without dots are left as-is. Bracket notation (e.g. `items[0]`) is NOT
+* supported — use dot notation (`items.0`) instead.
+*/
+function expandDotPaths(flat) {
+	const result = {};
+	let hasDotPaths = false;
+	for (const key of Object.keys(flat)) if (key.includes(".")) {
+		hasDotPaths = true;
+		break;
+	}
+	if (!hasDotPaths) return flat;
+	for (const [key, value] of Object.entries(flat)) {
+		const parts = key.split(".");
+		if (parts.some((p) => DANGEROUS_KEYS.has(p))) continue;
+		if (parts.length === 1) {
+			result[parts[0]] = value;
+			continue;
+		}
+		let current = result;
+		for (let i = 0; i < parts.length - 1; i++) {
+			const part = parts[i];
+			if (current[part] === void 0 || current[part] === null) current[part] = {};
+			if (typeof current[part] !== "object" || current[part] instanceof File) current[part] = {};
+			current = current[part];
+		}
+		current[parts[parts.length - 1]] = value;
+	}
+	return result;
+}
+var DANGEROUS_KEYS = /* @__PURE__ */ new Set(["__proto__"]);
+/**
+* Schema-agnostic coercion primitives for common FormData patterns.
+*
+* These are plain transform functions — they compose with any schema library's
+* `transform`/`preprocess` pipeline:
+*
+* ```ts
+* // Zod
+* z.preprocess(coerce.number, z.number())
+* // Valibot
+* v.pipe(v.unknown(), v.transform(coerce.number), v.number())
+* ```
+*/
+var coerce = {
+	/**
+	* Coerce an empty string to undefined for optional text fields.
+	* Use with `.optional()` schemas where an empty input means "not provided".
+	*
+	* ```ts
+	* // Zod
+	* z.unknown().transform(coerce.text).pipe(z.string().optional())
+	* // Valibot
+	* v.pipe(v.unknown(), v.transform(coerce.text), v.optional(v.string()))
+	* ```
+	*/
+	text(value) {
+		if (value === void 0 || value === null || value === "") return void 0;
+		if (typeof value === "string") return value;
+	},
+	/**
+	* Coerce a string to a number.
+	* - `"42"` → `42`
+	* - `"3.14"` → `3.14`
+	* - `""` / `undefined` / `null` → `undefined`
+	* - Non-numeric strings → `undefined` (schema validation will catch this)
+	*/
+	number(value) {
+		if (value === void 0 || value === null || value === "") return void 0;
+		if (typeof value === "number") return value;
+		if (typeof value !== "string") return void 0;
+		const num = Number(value);
+		if (Number.isNaN(num)) return void 0;
+		return num;
+	},
+	/**
+	* Coerce a checkbox value to a boolean.
+	* HTML checkboxes submit "on" when checked and are absent when unchecked.
+	* - `"on"` / any truthy string → `true`
+	* - `undefined` / `null` / `""` → `false`
+	*/
+	checkbox(value) {
+		if (value === void 0 || value === null || value === "") return false;
+		if (typeof value === "boolean") return value;
+		return typeof value === "string" && value.length > 0;
+	},
+	/**
+	* Parse a JSON string into an object.
+	* - Valid JSON string → parsed object
+	* - `""` / `undefined` / `null` → `undefined`
+	* - Invalid JSON → `undefined` (schema validation will catch this)
+	*/
+	json(value) {
+		if (value === void 0 || value === null || value === "") return void 0;
+		if (typeof value !== "string") return value;
+		try {
+			return JSON.parse(value);
+		} catch {
+			return;
+		}
+	},
+	/**
+	* Coerce a date string to a Date object.
+	* Handles `<input type="date">` (`"2024-01-15"`), `<input type="datetime-local">`
+	* (`"2024-01-15T10:30"`), and full ISO 8601 strings.
+	* - Valid date string → `Date`
+	* - `""` / `undefined` / `null` → `undefined`
+	* - Invalid date strings → `undefined` (schema validation will catch this)
+	* - Impossible dates that `new Date()` silently normalizes (e.g. Feb 31) → `undefined`
+	*/
+	date(value) {
+		if (value === void 0 || value === null || value === "") return void 0;
+		if (value instanceof Date) return value;
+		if (typeof value !== "string") return void 0;
+		const date = new Date(value);
+		if (Number.isNaN(date.getTime())) return void 0;
+		const ymdMatch = value.match(/^(\d{4})-(\d{2})-(\d{2})/);
+		if (ymdMatch) {
+			const inputYear = Number(ymdMatch[1]);
+			const inputMonth = Number(ymdMatch[2]);
+			const inputDay = Number(ymdMatch[3]);
+			const isUTC = value.length === 10 || value.endsWith("Z");
+			const parsedYear = isUTC ? date.getUTCFullYear() : date.getFullYear();
+			const parsedMonth = isUTC ? date.getUTCMonth() + 1 : date.getMonth() + 1;
+			const parsedDay = isUTC ? date.getUTCDate() : date.getDate();
+			if (inputYear !== parsedYear || inputMonth !== parsedMonth || inputDay !== parsedDay) return;
+		}
+		return date;
+	},
+	/**
+	* Create a File coercion function with optional size and mime type validation.
+	* Returns the File if valid, `undefined` otherwise.
+	*
+	* ```ts
+	* // Basic — just checks it's a real File
+	* z.preprocess(coerce.file(), z.instanceof(File))
+	*
+	* // With constraints
+	* z.preprocess(
+	*   coerce.file({ maxSize: 5 * 1024 * 1024, accept: ['image/png', 'image/jpeg'] }),
+	*   z.instanceof(File)
+	* )
+	* ```
+	*/
+	file(options) {
+		return (value) => {
+			if (value === void 0 || value === null || value === "") return void 0;
+			if (!(value instanceof File)) return void 0;
+			if (value.size === 0 && value.name === "") return void 0;
+			if (options?.maxSize !== void 0 && value.size > options.maxSize) return;
+			if (options?.accept !== void 0 && !options.accept.includes(value.type)) return;
+			return value;
+		};
+	}
+};
+//#endregion
+//#region src/server/actions.ts
+/**
+* Server action primitives: revalidatePath, revalidateTag, and the action handler.
+*
+* - revalidatePath(path) re-renders the route at that path and returns the RSC
+*   flight payload for inline reconciliation.
+* - revalidateTag(tag) invalidates timber.cache entries by tag.
+*
+* Both are callable from anywhere on the server — actions, API routes, handlers.
+*
+* The action handler processes incoming action requests, validates CSRF,
+* enforces body limits, executes the action, and returns the response
+* (with piggybacked RSC payload if revalidatePath was called).
+*
+* See design/08-forms-and-actions.md
+*/
+/**
+* Get the current revalidation state. Throws if called outside an action context.
+* @internal
+*/
+function getRevalidationState() {
+	const state = revalidationAls.getStore();
+	if (!state) throw new Error("revalidatePath/revalidateTag called outside of a server action context. These functions can only be called during action execution.");
+	return state;
+}
+/**
+* Re-render the route at `path` and include the RSC flight payload in the
+* action response. The client reconciles inline — no separate fetch needed.
+*
+* Can be called from server actions, API routes, or any server-side context.
+*
+* @param path - The path to re-render (e.g. '/dashboard', '/todos').
+*/
+function revalidatePath(path) {
+	const state = getRevalidationState();
+	if (!state.paths.includes(path)) state.paths.push(path);
+}
+/**
+* Invalidate all timber.cache entries tagged with `tag`.
+* Does not return a payload — the next request for an invalidated entry re-executes.
+*
+* @param tag - The cache tag to invalidate (e.g. 'products', 'user:123').
+*/
+function revalidateTag(tag) {
+	const state = getRevalidationState();
+	if (!state.tags.includes(tag)) state.tags.push(tag);
+}
+/**
+* Execute a server action and process revalidation.
+*
+* 1. Sets up revalidation state
+* 2. Calls the action function
+* 3. Processes revalidateTag calls (invalidates cache entries)
+* 4. Processes revalidatePath calls (re-renders and captures RSC payload)
+* 5. Returns the action result + optional RSC payload
+*
+* @param actionFn - The server action function to execute.
+* @param args - Arguments to pass to the action.
+* @param config - Handler configuration (cache handler, renderer).
+*/
+async function executeAction(actionFn, args, config = {}, spanMeta) {
+	const state = {
+		paths: [],
+		tags: []
+	};
+	let actionResult;
+	let redirectTo;
+	let redirectStatus;
+	await revalidationAls.run(state, async () => {
+		try {
+			actionResult = await withSpan("timber.action", {
+				...spanMeta?.actionFile ? { "timber.action_file": spanMeta.actionFile } : {},
+				...spanMeta?.actionName ? { "timber.action_name": spanMeta.actionName } : {}
+			}, () => actionFn(...args));
+		} catch (error) {
+			if (error instanceof RedirectSignal) {
+				redirectTo = error.location;
+				redirectStatus = error.status;
+			} else throw error;
+		}
+	});
+	if (state.tags.length > 0) {
+		const results = await Promise.allSettled(state.tags.map((tag) => cache.invalidate({ tag })));
+		for (const r of results) if (r.status === "rejected") console.error("[timber] revalidateTag invalidation failed:", r.reason);
+	}
+	let revalidation;
+	if (state.paths.length > 0 && config.renderer) {
+		const path = state.paths[0];
+		try {
+			revalidation = await config.renderer(path);
+		} catch (renderError) {
+			if (renderError instanceof RedirectSignal) {
+				redirectTo = renderError.location;
+				redirectStatus = renderError.status;
+			} else if (renderError instanceof DenySignal) console.error(`[timber] revalidatePath dropped — target middleware denied (status ${renderError.status})`);
+			else console.error("[timber] revalidatePath render failed:", renderError);
+		}
+	}
+	return {
+		actionResult,
+		revalidation,
+		...redirectTo ? {
+			redirectTo,
+			redirectStatus
+		} : {}
+	};
+}
+//#endregion
+export { parseFormData as a, coerce as i, revalidatePath as n, revalidateTag as r, executeAction as t };
+
+//# sourceMappingURL=actions-BjbbNRFN.js.map