void 0.22.0 → 0.23.0

package/skills/void/docs/reference/api/rewrites.md

@@ -0,0 +1,76 @@
+---
+outline: deep
+---
+
+# Rewrites {#rewrites}
+
+URL rewrites re-dispatch a request at a different internal path without changing the browser's URL. `c.rewrite()`, `c.originalUrl()`, and `c.isRewritten()` are available on every Hono `Context` the Void runtime hands you. See the [Rewrites guide](../../guide/edge/rewrites.md) for the full overview, including static `routing.rewrites` / `routing.fallbacks` in [`void.config.ts`](../config.md#routing).
+
+## `c.rewrite(destination)` {#c-rewrite-destination}
+
+Re-dispatches the current request at `destination` and returns the resulting `Response`. The browser URL does not change — this is a server-side hop. If `destination` has no query string, the original request query is preserved. If `destination` includes a query string, it replaces the original query. `destination` must start with `/`; known generated routes autocomplete via [`RewriteDestination`](#rewritedestination), while arbitrary strings remain accepted for dynamic paths.
+
+`c.redirect()` also preserves request query params for internal destinations, but it merges rather than replaces: destination params win on collision, and request-only params are appended.
+
+```ts
+import { defineHandler } from 'void';
+
+export const GET = defineHandler((c) => {
+  const locale = c.req.header('accept-language')?.startsWith('de') ? 'de' : 'en';
+  return c.rewrite(`/${locale}${new URL(c.req.url).pathname}`);
+});
+```
+
+**Signature:**
+
+```ts
+interface CloudContext {
+  rewrite(destination: RewriteDestination): Promise<Response>;
+}
+```
+
+**Caveats:**
+
+- `destination` must start with a single `/` and point at an internal path. External URLs, protocol-relative destinations (`//host/...`), and anything non-path-absolute throw immediately — use `fetch()` for cross-origin calls.
+- Destinations whose final path segment ends in a known static-asset extension (e.g. `/hero.png`, `/app.css`, `/data.json`) throw `VoidAssetRewriteError` (exported from `"void"`) before the re-dispatch. Runtime rewrites cannot reach assets — use a static `routing.rewrites` rule or a `_redirects` `200!` entry. `.html` is deliberately excluded from this guard because `.html` paths may be legitimate route handlers. See [Rewrites](../../guide/edge/rewrites.md#runtime-rewrites-cannot-reach-static-assets).
+- Middleware re-runs on every rewrite hop. Guard side-effects with [`c.isRewritten()`](#c-originalurl-c-isrewritten).
+- Client-side SPA navigation via `Link` does not trigger server rewrites; only full HTTP requests do.
+- Purge the destination path to clear rewritten [ISR entries](../../guide/edge/revalidation.md#cache-keys-and-rewrites).
+
+## `c.originalUrl()` / `c.isRewritten()` {#c-originalurl-c-isrewritten}
+
+Context methods for inspecting rewrite state. `c.originalUrl()` returns the pre-rewrite URL as a `URL` object, or `null` on the first, non-rewritten hop. `c.isRewritten()` returns `true` on any re-dispatched context and `false` on the original. Use them for both static and middleware rewrites.
+
+```ts
+import { defineMiddleware } from 'void';
+
+export default defineMiddleware(async (c, next) => {
+  if (!c.isRewritten()) {
+    // Only log the user-visible request, not internal rewrite hops.
+    console.log(`${c.req.method} ${c.req.path}`);
+  }
+  await next();
+});
+```
+
+**Signature:**
+
+```ts
+interface CloudContext {
+  originalUrl(): URL | null;
+  isRewritten(): boolean;
+}
+```
+
+## `RewriteDestination` {#rewritedestination}
+
+```ts
+import type { RewriteDestination } from 'void/routes';
+```
+
+Suggests known route patterns in your editor while also accepting dynamic strings. Used as:
+
+- The parameter type of [`c.rewrite()`](#c-rewrite-destination).
+- The type of `destination` entries in `routing.rewrites` and `routing.fallbacks` in [`void.config.ts`](../config.md#routing).
+
+Like [`RouteMap`](./types.md#routemap), `RewriteDestination` lives in the virtual `void/routes` module and is refreshed whenever routes change.

package/skills/void/docs/reference/api/types.md

@@ -0,0 +1,92 @@
+---
+outline: deep
+---
+
+# Types {#types}
+
+## `CloudContext` {#cloudcontext}
+
+Hono `Context` pre-typed with [`CloudEnv`](#cloudenv). This is the type of the `c` parameter in all route handlers and middleware.
+
+```ts
+import type { CloudContext } from 'void';
+```
+
+## `CloudEnv` {#cloudenv}
+
+Hono environment type for Void workers. Extends Hono's `Env` with Cloudflare bindings and context variables.
+
+```ts
+interface CloudEnv extends Env {
+  Bindings: {
+    DB: D1Database;
+    KV: KVNamespace;
+    STORAGE: R2Bucket;
+    AI: Ai;
+    SANDBOX: DurableObjectNamespace<import('void/sandbox').VoidPlatformSandbox>;
+    [key: string]: unknown;
+  };
+  Variables: CloudContextVariables;
+}
+```
+
+## `CloudContextVariables` {#cloudcontextvariables}
+
+The context variables type used by `c.set()` / `c.get()`. Augment this interface to add typed variables that flow through all middleware and handlers:
+
+```ts
+interface CloudContextVariables {
+  user: AuthUser | null;
+  session: AuthSession | null;
+  [key: string]: unknown;
+}
+```
+
+**Augmentation example:**
+
+```ts
+declare module 'void' {
+  interface CloudContextVariables {
+    requestId: string;
+  }
+}
+
+// c.get("requestId") → string
+```
+
+See [Type Safety](../../guide/type-safety.md#context-variables) for details.
+
+## `TypedHandler<V, R>` {#typedhandler-v-r}
+
+The return type of `defineHandler`, with validator types (`V`) and the handler’s return type (`R`).
+
+```ts
+interface TypedHandler<V extends ValidatorSlots = {}, R = unknown> {
+  (c: CloudContext): Promise<Response> | Response | unknown;
+  readonly __validators: V; // type-level only
+  readonly __output: R; // type-level only
+}
+```
+
+## `HeadDescriptor` {#headdescriptor}
+
+Shape of page head metadata returned by `defineHead`. All fields are optional.
+
+```ts
+interface HeadDescriptor {
+  title?: string;
+  meta?: Array<{ name?: string; property?: string; content?: string; charset?: string }>;
+  link?: Array<{ rel: string; href: string; [key: string]: string | undefined }>;
+  script?: Array<{ src?: string; innerHTML?: string; [key: string]: string | undefined }>;
+  htmlAttrs?: Record<string, string>;
+  bodyAttrs?: Record<string, string>;
+}
+```
+
+## `RouteMap` {#routemap}
+
+Generated route types used by the typed `fetch` client. Contains each route’s methods, inputs, and outputs.
+
+```ts
+import type { RouteMap } from 'void/routes';
+```