@bractjs/bractjs 0.1.28 → 0.2.0

package/src/shared/route-types.ts

@@ -75,6 +75,41 @@ export type MetaFunction<T = unknown> = (
   args: MetaArgs<T>
 ) => MetaDescriptor[];
 
+export interface HeadersArgs<T = unknown> {
+  /** This route's loader data (the route slice, already awaited). */
+  loaderData: T;
+  params: Record<string, string>;
+  request: Request;
+  /**
+   * The merged headers contributed by ancestors in the chain (root → layout →
+   * this route). Spread these to inherit, or override individual keys. Each
+   * `headers()` in the chain runs in order and sees what came before it.
+   */
+  parentHeaders: Headers;
+}
+
+/**
+ * A route/layout/root module's optional `headers` export, used to set
+ * response headers (e.g. `Cache-Control`, `ETag`, `Vary`) on the document and
+ * `/_data` responses. Runs in chain order (root → layout → route); the
+ * innermost value wins per key. Returns a `HeadersInit` (object, array of
+ * tuples, or `Headers`).
+ */
+export type HeadersFunction<T = unknown> = (
+  args: HeadersArgs<T>
+) => HeadersInit;
+
+/**
+ * A nested route-middleware function. Runs on the server in chain order
+ * (root → layout → route) before `beforeLoad`, the action, and loaders. Call
+ * `next()` to continue, or return a `Response` to short-circuit. The `context`
+ * object is shared and mutable across the whole chain (and into loaders).
+ */
+export type RouteMiddlewareFunction = (
+  ctx: { request: Request; params: Record<string, string>; context: Record<string, unknown> },
+  next: () => Promise<Response>,
+) => Promise<Response>;
+
 export interface BeforeLoadArgs {
   params: Record<string, string>;
   context: Record<string, unknown>;
@@ -105,10 +140,64 @@ export interface ShouldRevalidateArgs {
 
 export type ShouldRevalidateFunction = (args: ShouldRevalidateArgs) => boolean;
 
+/**
+ * A route's optional client loader (RR7-style). Runs in the browser on
+ * navigation to the route instead of just fetching the server loader. Call
+ * `serverLoader()` to get this route's server loader data (the `/_data`
+ * payload's route slice). Set `clientLoader.hydrate = true` to also run it
+ * during the initial hydration of an SSR'd document.
+ *
+ * Whatever it resolves to becomes the route's `useLoaderData()` value.
+ */
+export interface ClientLoaderFunction<T = unknown> {
+  (args: {
+    request: Request;
+    params: Record<string, string>;
+    search: Record<string, unknown>;
+    /** Fetch this route's server loader data (the `/_data` route slice). */
+    serverLoader: () => Promise<unknown>;
+  }): Promise<T> | T;
+  /** Run on initial hydration too (default: only on client navigation). */
+  hydrate?: boolean;
+}
+
+/**
+ * A route's optional client action (RR7-style). Runs in the browser on a
+ * `<Form>`/fetcher submission to the route instead of POSTing directly. Call
+ * `serverAction()` to invoke the server action and get its data. Whatever it
+ * resolves to becomes the route's `useActionData()` value.
+ */
+export type ClientActionFunction<T = unknown> = (args: {
+  request: Request;
+  params: Record<string, string>;
+  formData: FormData;
+  /** Invoke this route's server action and get its returned data. */
+  serverAction: () => Promise<unknown>;
+}) => Promise<T> | T;
+
 export interface RouteModule<TLoader = unknown, TAction = unknown> {
   loader?: LoaderFunction<TLoader>;
   action?: ActionFunction<TAction>;
+  /** Browser-side loader; see {@link ClientLoaderFunction}. */
+  clientLoader?: ClientLoaderFunction<TLoader>;
+  /** Browser-side action; see {@link ClientActionFunction}. */
+  clientAction?: ClientActionFunction<TAction>;
   meta?: MetaFunction<TLoader>;
+  /**
+   * Set response headers (`Cache-Control`, `ETag`, `Vary`, CDN hints, …) for
+   * this route's document and `/_data` responses. Runs in chain order
+   * (root → layout → route); innermost wins per key, and each call receives the
+   * `parentHeaders` accumulated so far. Skipped for mutations and error responses.
+   */
+  headers?: HeadersFunction<TLoader>;
+  /**
+   * Nested middleware for this route/layout/root. Runs on the server in chain
+   * order (root → layout → route) before `beforeLoad`/action/loaders, with a
+   * shared mutable `context`. A single function or an array. Return a
+   * `Response` to short-circuit; call `next()` to continue. Runs *inside* the
+   * global `pipeline` middleware.
+   */
+  middleware?: RouteMiddlewareFunction | RouteMiddlewareFunction[];
   beforeLoad?: BeforeLoadFunction;
   shouldRevalidate?: ShouldRevalidateFunction;
   /**
@@ -141,3 +230,22 @@ export interface RouteDefinition {
   parentId?: string;
   index?: boolean;
 }
+
+/**
+ * One entry in the matched route chain, as returned by `useMatches()`. The
+ * array runs outermost → innermost: root, then each layout, then the leaf
+ * route. Use it for breadcrumbs and conditional chrome driven by each route's
+ * `handle` export.
+ */
+export interface RouteMatch<TData = unknown, THandle = Record<string, unknown>> {
+  /** Stable id of the matched module — its appDir-relative file path (e.g. "routes/blog/[id].tsx", "root.tsx"). */
+  id: string;
+  /** The active URL pathname (same for every entry — they all share the matched location). */
+  pathname: string;
+  /** The matched route params (shared across the chain). */
+  params: Record<string, string>;
+  /** This module's loader data slice (root / the matching layout / the route). */
+  data: TData;
+  /** This module's static `handle` export, or `undefined` if none. */
+  handle: THandle | undefined;
+}

package/types/config.d.ts

@@ -23,6 +23,9 @@ export interface BractJSConfig {
   plugins?: BunPlugin[];
   /** Directory for the transformed-image cache. Default: ".bract-image-cache". */
   imageCacheDir?: string;
+  /** Hard ceiling (bytes) on any incoming request body, enforced by the Bun
+   *  adapter regardless of advertised Content-Length. Default 16 MiB. */
+  maxRequestBodySize?: number;
   /** WebSocket port for dev HMR (used by `bractjs dev` only). Default 3001. */
   hmrPort?: number;
   /** Custom server adapter (Cloudflare Workers, Deno, Node, etc.). Defaults to Bun.serve(). */

package/types/index.d.ts

@@ -93,6 +93,7 @@ import type { MiddlewareFn, MiddlewareContext } from "./middleware.d.ts";
 
 export declare class MiddlewarePipeline {
   use(fn: MiddlewareFn): this;
+  clear(): this;
   run(ctx: MiddlewareContext, handler: () => Promise<Response>): Promise<Response>;
 }
 export declare const pipeline: MiddlewarePipeline;
@@ -106,16 +107,24 @@ export declare function authGuard(options: AuthGuardOptions): MiddlewareFn;
 
 // ── API routes (C1) ───────────────────────────────────────────────────────
 export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+export interface ApiRouteOptions {
+  /** CSRF protection for this route. Default `true` for mutating methods
+   *  (POST/PUT/PATCH/DELETE). Set `false` only for endpoints that don't trust
+   *  ambient credentials (webhooks, token-authenticated/public APIs). */
+  csrf?: boolean;
+}
 export interface ApiRouteDefinition<TMethod extends HttpMethod, TPath extends string, TInput, TOutput> {
   method: TMethod;
   path: TPath;
   handler: (input: TInput, request: Request) => TOutput | Promise<TOutput>;
+  csrf: boolean;
 }
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export declare function route<TMethod extends HttpMethod, TPath extends string, TInput, TOutput>(
   method: TMethod,
   path: TPath,
   handler: (input: TInput, request: Request) => TOutput | Promise<TOutput>,
+  options?: ApiRouteOptions,
 ): ApiRouteDefinition<TMethod, TPath, TInput, TOutput>;
 export type AppApiRoutes = never; // users extend this via codegen
 
@@ -163,6 +172,14 @@ export declare function formText(formData: FormData, key: string): string;
 /** Collect string fields from FormData (all, or a named subset). */
 export declare function formValues(formData: FormData, keys?: string[]): Record<string, string>;
 
+// ── Prototype-pollution guards ────────────────────────────────────────────
+/** Deep-scan a parsed JSON value for `__proto__`/`constructor`/`prototype`
+ *  keys. Fails closed past an internal depth cap. Returns true if found. */
+export declare function hasForbiddenKey(value: unknown, depth?: number): boolean;
+/** Build a null-prototype object from entries, so a key named `__proto__`
+ *  lands as a plain own property instead of mutating the prototype. */
+export declare function nullProtoFromEntries<V>(entries: Iterable<readonly [string, V]>): Record<string, V>;
+
 // ── Search-param validation ───────────────────────────────────────────────
 /** URLSearchParams → plain object; repeated keys collapse into arrays. */
 export declare function searchParamsToObject(sp: URLSearchParams): Record<string, string | string[]>;

package/types/route.d.ts

@@ -63,6 +63,32 @@ export type ActionFunction<T = unknown> = (
 
 export type MetaFunction<T = unknown> = (args: MetaArgs<T>) => MetaDescriptor[];
 
+export interface HeadersArgs<T = unknown> {
+  loaderData: T;
+  params: Record<string, string>;
+  request: Request;
+  /** Headers merged from ancestors in the chain (root → layout → this route). */
+  parentHeaders: Headers;
+}
+
+/**
+ * A module's optional `headers` export — set response headers (`Cache-Control`,
+ * `ETag`, `Vary`, …) on the document and `/_data` responses. Runs in chain
+ * order (root → layout → route); innermost wins per key.
+ */
+export type HeadersFunction<T = unknown> = (args: HeadersArgs<T>) => HeadersInit;
+
+/**
+ * A nested route-middleware function. Runs on the server in chain order
+ * (root → layout → route) before `beforeLoad`/action/loaders, with a shared
+ * mutable `context`. Return a `Response` to short-circuit; call `next()` to
+ * continue.
+ */
+export type RouteMiddlewareFunction = (
+  ctx: { request: Request; params: Record<string, string>; context: Record<string, unknown> },
+  next: () => Promise<Response>,
+) => Promise<Response>;
+
 export interface BeforeLoadArgs {
   params: Record<string, string>;
   context: Record<string, unknown>;
@@ -90,10 +116,38 @@ export interface ShouldRevalidateArgs {
 
 export type ShouldRevalidateFunction = (args: ShouldRevalidateArgs) => boolean;
 
+/** A route's browser-side loader (RR7-style). See the package docs. */
+export interface ClientLoaderFunction<T = unknown> {
+  (args: {
+    request: Request;
+    params: Record<string, string>;
+    search: Record<string, unknown>;
+    serverLoader: () => Promise<unknown>;
+  }): Promise<T> | T;
+  /** Run on initial hydration too (default: only on client navigation). */
+  hydrate?: boolean;
+}
+
+/** A route's browser-side action (RR7-style). See the package docs. */
+export type ClientActionFunction<T = unknown> = (args: {
+  request: Request;
+  params: Record<string, string>;
+  formData: FormData;
+  serverAction: () => Promise<unknown>;
+}) => Promise<T> | T;
+
 export interface RouteModule<TLoader = unknown, TAction = unknown> {
   loader?: LoaderFunction<TLoader>;
   action?: ActionFunction<TAction>;
+  /** Browser-side loader; see {@link ClientLoaderFunction}. */
+  clientLoader?: ClientLoaderFunction<TLoader>;
+  /** Browser-side action; see {@link ClientActionFunction}. */
+  clientAction?: ClientActionFunction<TAction>;
   meta?: MetaFunction<TLoader>;
+  /** Set response headers (Cache-Control/ETag/Vary/…) for this route's document and `/_data` responses. Chain order, innermost wins. */
+  headers?: HeadersFunction<TLoader>;
+  /** Nested middleware (root → layout → route), shared mutable `context`, runs before beforeLoad/action/loaders. A single fn or an array. */
+  middleware?: RouteMiddlewareFunction | RouteMiddlewareFunction[];
   beforeLoad?: BeforeLoadFunction;
   shouldRevalidate?: ShouldRevalidateFunction;
   /** Zod/Valibot-compatible schema validating search params before loaders run (400 on failure). */
@@ -111,7 +165,28 @@ export interface RouteModule<TLoader = unknown, TAction = unknown> {
   default?: ComponentType;
 }
 
-export type Segment = string | { param: string } | { catchAll: string };
+/**
+ * One entry in the matched route chain (see `useMatches`), outermost → innermost:
+ * root, layouts, then the leaf route.
+ */
+export interface RouteMatch<TData = unknown, THandle = Record<string, unknown>> {
+  /** Stable id of the matched module — its appDir-relative file path. */
+  id: string;
+  /** The active URL pathname (shared across the chain). */
+  pathname: string;
+  /** The matched route params (shared across the chain). */
+  params: Record<string, string>;
+  /** This module's loader data slice. */
+  data: TData;
+  /** This module's static `handle` export, or `undefined`. */
+  handle: THandle | undefined;
+}
+
+export type Segment =
+  | string
+  | { param: string }
+  | { optional: string }
+  | { catchAll: string };
 
 export interface RouteFile {
   filePath: string;