# Hono (narrator proof)
# Hono (narrator proof)
What this repository is for is not stated in prose this page can quote, so it cannot be established from this repository alone.
- **Terms of use** — MIT [package.json:650].
- **Version** — `4.13.1` [package.json:3].
- **Editions** — whether this repository is the whole product or one edition of it cannot be established from this repository alone.
- **Running it** — no run path was found in the parsed corpus, so how to start it cannot be established from this repository alone.
## What is in here
Each part names what it holds before how much of it there is. The counts are read from the evidence census computed for this snapshot, one per part at most.
- [Utils](subsystem-src-utils) — jwt; enums and type aliases. A file to open: `accept.ts` [src/utils/accept.ts:1]. 148 entities under `src/utils` [census].
- [Helper](subsystem-src-helper) — ssg, css, websocket, cookie; type aliases and classes. A file to open: `accepts.ts` [src/helper/accepts/accepts.ts:5]. 109 entities under `src/helper` [census].
- [Jsx](subsystem-src-jsx) — dom, hooks, intrinsic element; type aliases and classes. A file to open: `base.ts` [src/jsx/base.ts:27]. 147 entities under `src/jsx` [census].
- [Middleware](subsystem-src-middleware) — language, timing, cache, compress; HTTP endpoints. A file to open: `index.ts` [src/middleware/basic-auth/index.ts:118]. 110 entities under `src/middleware` [census].
- [Client](subsystem-src-client) — type aliases and class. A file to open: `fetch-result-please.ts` [src/client/fetch-result-please.ts:14]. 25 entities under `src/client` [census].
- [Docs](subsystem-docs) — no symbol kind this page can name. A file to open: `CODE_OF_CONDUCT.md` [docs/CODE_OF_CONDUCT.md:1]. 73 entities under `docs` [census].
- [Adapter](subsystem-src-adapter) — aws lambda, bun, lambda edge, cloudflare workers; type aliases and classes. A file to open: `conninfo.ts` [src/adapter/aws-lambda/conninfo.ts:45]. 71 entities under `src/adapter` [census].
- [Router](subsystem-src-router) — reg exp router, trie router, linear router, pattern router; type aliases and classes. A file to open: `router.ts` [src/router/linear-router/router.ts:11]. 21 entities under `src/router` [census].
- **Repository root and unclaimed files** — validator, .github, preset, request; type aliases and classes. A file to open: `pull_request_template.md` [.github/pull_request_template.md:1]. 110 entities in files no part claims [census].
## Trust and security, as the code carries it
Topics below come from sweeping symbol names and file paths in the parsed corpus. They are not read from a security document: a page that takes its topics from what a document enumerates inherits whatever that document left out.
- **Authentication** — `basicAuth` [src/middleware/basic-auth/index.ts:80], `handler` [src/middleware/basic-auth/index.ts:118], `bearerAuth` [src/middleware/bearer-auth/index.ts:104].
- **Authorization** — `PermissionsPolicyDirective` [src/middleware/secure-headers/permissions-policy.ts:3].
- **Secrets and configuration** — `isTokenHeader` [src/utils/jwt/jwt.ts:44], `TokenHeader` [src/utils/jwt/jwt.ts:38], `JwtTokenAudience` [src/utils/jwt/types.ts:106].
- **Transport and browser boundaries** — `deleteCookie` [src/helper/cookie/index.ts:141], `generateCookie` [src/helper/cookie/index.ts:78], `generateSignedCookie` [src/helper/cookie/index.ts:104].
- **Input validation** — `joinPaths` [src/helper/ssg/utils.ts:50], `validateOptions` [src/middleware/language/language.ts:204], `ValidationTargets` [src/types.ts:2683].
- **Cryptography** — `createHash` [src/utils/crypto.ts:33], `sha1` [src/utils/crypto.ts:21], `sha256` [src/utils/crypto.ts:15].
No symbol name or path in the parsed corpus matched rate limiting and abuse and audit and access logging. That is a statement about the names this codebase uses, not a finding about what it does.
## What this repository carries
One row per capability lane, scoped to where the evidence for it sits. A lane marked as not found means nothing in the parsed corpus matched it — which is a fact about this parse, and the honest place to start looking rather than the end of the question.
| Capability | In this repository | Where |
|---|---|---|
| Database models | not found | — |
| HTTP endpoints | 40 [census] | `src/middleware/basic-auth/index.ts`, `src/middleware/body-limit/index.ts` |
| Controllers | not found | — |
| Configuration | not found | — |
| Automated tests | not found | — |
| Written documentation | yes | `.github/pull_request_template.md`, `LICENSE` |
| Licence | yes | `LICENSE` |
## Where next
Five ways in. Each one names pages that exist in this documentation, or says what the repository holds instead.
- **Deploying it** — no deployment descriptor and no deployment page were found; how this is deployed cannot be established from this repository alone.
- **Understanding the architecture** — [System Overview](system-overview), [Utils](subsystem-src-utils), [Helper](subsystem-src-helper) and [Jsx](subsystem-src-jsx).
- **Contributing a change** — [Documentation health](documentation-health) and [docs/CONTRIBUTING.md:1].
- **Reviewing security** — the topics above, starting at [src/middleware/basic-auth/index.ts:80].
- **Extending it** — [Middleware](subsystem-src-middleware).
## Before you rely on it
Each item is something the evidence for this snapshot raises, not a generic release checklist.
- 38 of 40 HTTP endpoints [census] declare no guard or middleware [parsed surface] — check that against what the surface is meant to expose.
- No test file was found in the parsed corpus — nothing here runs a check before a release.
## How this page was assembled
Every count above is read from the evidence census computed for this snapshot; every other claim points at a file and a line you can open.
The census covers 814 entities and 430 relationships across 9 parts [census], and it passed its own independent recount [census].
# Hono (narrator proof)
## Overview
Auto-generated technical documentation for **Hono (narrator proof)** — 814 entities (291 functions, 191 types, 102 doc comments, 72 constants).
## Entry Points
- `ALL /` → handler
- `GET /content-length` → handler
- `GET /Cache-Control` → handler
- `GET /` → header
- `GET /Cache-Control` → handler
- `GET /` → directive
- `GET /Vary` → handler
- `PUT /` → res
- `PUT /` → res
- `GET /Content-Type` → handler
- `GET /Content-Type` → handler
- `GET /Content-Length` → handler
- `GET /Vary` → handler
- `DELETE /Content-Length` → handler
- `GET /ETag` → handler
- `GET /Cache-Control` → handler
- `DELETE /Content-Length` → handler
- `DELETE /Content-Type` → handler
- `GET /ETag` → handler
- `DELETE /` → key
- `GET /` → headerName
- `GET /` → headerName
- `GET /` → handler
- `DELETE /Allow` → handler
- `DELETE /Content-Length` → handler
- `GET /` → methodFormName
- `DELETE /` → methodFormName
- `DELETE /content-type` → handler
- `DELETE /content-length` → handler
- `DELETE /` → headerName
## Key Components
_The most-referenced entities — start here._
- **HTTPException** (class) — referenced 12×
- **html** (function) — referenced 11×
- **METHOD_NAME_ALL** (constant) — referenced 10×
- **useContext** (function) — referenced 7×
- **DOM_RENDERER** (constant) — referenced 6×
- **UnsupportedPathError** (class) — referenced 4×
- **getCookie** (function) — referenced 4×
- **decodeBase64** (function) — referenced 4×
- **HtmlEscapedCallbackPhase** (constant) — referenced 4×
- **resolveCallback** (function) — referenced 4×
## Subsystems
Ordered by how much of the rest of the system depends on them, not by how much code they
contain. A small module many things import shapes this codebase more than a large one nothing
imports.
| Subsystem | Depended on by | Entities | Starts at |
|---|---|---|---|
| **Utils** | 6 | 148 | `Accept`, `parseAccept` |
| **Helper** | 5 | 109 | `Accept`, `acceptsConfig` |
| **Jsx** | 2 | 147 | `RenderToStringOptions`, `RenderToReadableStreamOptions` |
| **Middleware** | 1 | 110 | `handler`, `handler` |
| **Client** | 1 | 25 | `BuildSearchParamsFn`, `ClientRequestOptions` |
| **Docs** | 0 | 73 | `Contributor Covenant Code of Conduct`, `Contribution Guide` |
| **Adapter** | 0 | 71 | `getConnInfo`, `LambdaEvent` |
| **Router** | 0 | 21 | `LinearRouter`, `PatternRouter` |
`Client`, `Docs` depend on no other subsystem here — they are the leaves.
## How this code is named
These conventions cover most of the codebase. Learning them is faster than reading an index —
each one lets you find any member of its family without looking it up.
| Pattern | Where | Count | Examples |
|---|---|---|---|
| `use*` | exported symbols | 23 | `useId`, `useRef`, `useMemo`, `useState` |
| `create*` | exported symbols | 17 | `createRef`, `createBody`, `createRoot`, `createPool` |
| `jsx*` | exported symbols | 6 | `jsxFn`, `jsxDEV`, `jsxAttr`, `jsxEscape` |
| `build*` | exported symbols | 5 | `buildNode`, `buildDataStack`, `buildInitParams`, `buildStyleString` |
| `parse*` | exported symbols | 5 | `parseBody`, `parseAccept`, `parseSigned`, `parseResponse` |
| `serve*` | exported symbols | 5 | `serveStatic` |
# Documentation health
706 symbols have a reference page in this documentation. This page says how each of them came to be described, because "documented" covers four situations a reader should not have to treat alike.
## Where the descriptions come from
| | Symbols | What it means for a reader |
|---|---:|---|
| Written by the author | 129 of 706 | A doc comment in the source. Nothing generated improves on this. |
| Generated, with citations | 31 of 706 | Points at specific `file:line` ranges you can open and check. |
| Generated, without citations | 38 of 706 | Often right, but nothing anchors it. Treat as a starting point. |
| Not described | 508 of 706 | The page shows structure only — signature, members, references. |
**160 of 706 descriptions can be checked against source** — 129 because the author wrote them next to the code, 31 because the generator cited the lines it read. The rest are shown, and marked, for what they are.
## Why there is no coverage percentage
A percentage counts whether a comment exists, so the cheapest way to raise it is to add empty
ones. SonarQube withdrew its comment-density metric over this; studies of "covered" API
documentation classify 43–51% of it as carrying no information; and a missing-comment warning
has been measured producing 1,774 junk comments in a single codebase. The counts above cannot
be moved that way — a doc comment that only restates the symbol name is not counted as one.
## Where the gaps are
Undescribed symbols by the part of the system they sit in — worst first, so the next unit
of documentation effort has an address. This is the table to bring to planning.
| Area | Undescribed | Of | Share |
|---|---:|---:|---:|
| [`src/jsx`](subsystem-src-jsx) | 131 | 147 | 89% |
| [`src/utils`](subsystem-src-utils) | 122 | 148 | 82% |
| [`src/helper`](subsystem-src-helper) | 79 | 109 | 72% |
| [`src/middleware`](subsystem-src-middleware) | 62 | 110 | 56% |
| `src/types.ts` | 37 | 41 | 90% |
| [`src/adapter`](subsystem-src-adapter) | 36 | 71 | 51% |
| [`src/client`](subsystem-src-client) | 19 | 25 | 76% |
| [`src/router`](subsystem-src-router) | 11 | 21 | 52% |
| `src/validator` | 4 | 6 | 67% |
| `src/context.ts` | 2 | 9 | 22% |
| `src/preset` | 2 | 2 | 100% |
| `src/router.ts` | 1 | 10 | 10% |
| `src/hono-base.ts` | 1 | 1 | 100% |
| `src/request` | 1 | 1 | 100% |
## What can be checked
A claim on these pages is anchored when it points at something a reader can open: a `file:line` range in the source, or a `[census]` tag naming the arithmetic behind a number. Anything else is prose you would have to take on trust. These counts say which is which. They do not say the anchored claims are right — only that they can be checked.
| | Count | What it means |
|---|---:|---|
| Pages read by this audit | 717 [census] | Every page in the set as it stood before this section was written. This section's own claims are not counted below. |
| Pages carrying an anchored claim | 38 of 717 [census] | The page points at source or at a census at least once. |
| Anchored claims | 829 [census] | One per `file:line` reference and per census tag. Brackets inside code samples are code, and are not counted. |
| … pointing at source | 814 of 829 [census] | A path and a line you can open. |
| … pointing at a census | 15 of 829 [census] | A number computed before anything was written. |
Whether those citations land in files that exist was NOT CHECKED for this build: the audit was given no way to look a path up. The count above is of citations made, not of citations verified — and reporting them as sound on that basis would be the invention this page exists to catch.
Every count in this section and the two below is arithmetic over these pages, redone on each build; `[census]` marks a figure read from that arithmetic rather than written by hand.
## Where the docs and the code disagree
One lint reads every page for a single pattern: a sentence stating runtime behaviour — what listens, what validates, what retries — whose only evidence is a prose document. A README saying the server listens on a port is testimony ABOUT the code, not the behaviour itself, and a sentence citing it for the behaviour has quietly turned one into the other. The honest forms either cite the source that listens, or keep the attribution in the sentence.
1 of 717 pages carries a sentence like that, 4 sentences in all [census]. Each is quoted below exactly as written, with the page it is on and the document it leans on. This lint flags innocent sentences and misses guilty ones — it is a list to review, not a list of errors.
```text
page: Docs (subsystem-docs)
cites: docs/CONTRIBUTING.md
claim: [docs/CONTRIBUTING.md:27-31] Dependency setup then runs `bun install --frozen-lockfile`, and the local-development example combines cloning the repository, changing into it, and running that same install command.
```
```text
page: Docs (subsystem-docs)
cites: docs/MIGRATION.md
claim: [docs/MIGRATION.md:39-49] Other changes in that same upgrade include a changed default for JSX renderer `docType`, the absence of `children` from `FC`, removed MIME types, and type-sensitive route and validator chaining.
```
```text
page: Docs (subsystem-docs)
cites: docs/MIGRATION.md
claim: [docs/MIGRATION.md:76-103] For Cloudflare Workers, the guide marks `serveStatic` in Service Worker mode obsolete, identifies that mode with `app.fire()`, and recommends Module Worker mode using `export default app`.
```
```text
page: Docs (subsystem-docs)
cites: docs/CODE_OF_CONDUCT.md
claim: [docs/CODE_OF_CONDUCT.md:39-44] They may remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that do not align with the policy, and they communicate moderation reasons when appropriate.
```
## What we have not written yet
The evidence census lists, for each part of this repository, the reader-topics that part's contents warrant: a part holding database models owes its readers a data model however few models it holds. This section holds that list against the headings the pages for each part actually carry.
Every topic the census says this repository warrants — 19 [census] across 9 parts — has a page carrying a heading that answers for it. That is a statement about headings, not about depth: a section can exist and still be thin.
A topic counts as written when any page for its part carries a heading naming it — "Fields" answers for a data model, "Endpoint" for an API surface, "Dependencies" for wiring. The match is deliberately loose in that direction: a topic covered under a heading nobody predicted must not be reported as missing, so the error this makes is silence, never a false accusation of absence.
3 pages name no source path [census], so they were matched to no part and can cover no topic above — the pages about this documentation itself are among them.
# resolveCallback
**Kind:** Function
**Source:** [`src/utils/html.ts`](https://github.com/honojs/hono/blob/main/src/utils/html.ts#L142)
**Part of:** [Utils](subsystem-src-utils)
## Signature
```ts
async function resolveCallback(str: string | HtmlEscapedString | Promise, phase: (typeof HtmlEscapedCallbackPhase)[keyof typeof HtmlEscapedCallbackPhase], preserveCallbacks: boolean, context: object, buffer: [string]): Promise
```
## Parameters
| Name | Type |
|---|---|
| `str` | `string | HtmlEscapedString | Promise` |
| `phase` | `(typeof HtmlEscapedCallbackPhase)[keyof typeof HtmlEscapedCallbackPhase]` |
| `preserveCallbacks` | `boolean` |
| `context` | `object` |
| `buffer` | `[string]` |
**Returns:** `Promise`
## Used by
4 references from 4 files. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (4)
- `Data` — `src/context.ts`:26
- `SSEMessage` — `src/helper/streaming/sse.ts`:6
- `childrenToString` — `src/jsx/components.ts`:14
- `StreamingContext` — `src/jsx/streaming.ts`:30
# escapeToBuffer
**Kind:** Function
**Source:** [`src/utils/html.ts`](https://github.com/honojs/hono/blob/main/src/utils/html.ts#L90)
**Part of:** [Utils](subsystem-src-utils)
## Signature
```ts
function escapeToBuffer(str: string, buffer: StringBuffer): void
```
## Parameters
| Name | Type |
|---|---|
| `str` | `string` |
| `buffer` | `StringBuffer` |
**Returns:** `void`
## Used by
4 references from 4 files. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (4)
- `createCssContext` — `src/helper/css/index.ts`:72
- `html` — `src/helper/html/index.ts`:11
- `Props` — `src/jsx/base.ts`:27
- `jsxAttr` — `src/jsx/jsx-runtime.ts`:16
# decodeBase64
**Kind:** Function
**Source:** [`src/utils/encode.ts`](https://github.com/honojs/hono/blob/main/src/utils/encode.ts#L25)
**Part of:** [Utils](subsystem-src-utils)
## Signature
```ts
function decodeBase64(str: string): Uint8Array
```
## Parameters
| Name | Type |
|---|---|
| `str` | `string` |
**Returns:** `Uint8Array`
## Used by
4 references from 4 files. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (4)
- `LambdaEvent` — `src/adapter/aws-lambda/handler.ts`:23
- `CloudFrontRequest` — `src/adapter/lambda-edge/handler.ts`:41
- `Auth` — `src/utils/basic-auth.ts`:7
- `HonoJsonWebKey` — `src/utils/jwt/jws.ts`:23
# HtmlEscapedCallbackPhase
**Kind:** Constant
**Source:** [`src/utils/html.ts`](https://github.com/honojs/hono/blob/main/src/utils/html.ts#L6)
**Part of:** [Utils](subsystem-src-utils)
## Definition
```ts
{
Stringify: 1,
BeforeStream: 2,
Stream: 3,
} as const
```
## Value
```ts
{
Stringify: 1,
BeforeStream: 2,
Stream: 3,
} as const
```
## Used by
4 references from 4 files. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (4)
- `Data` — `src/context.ts`:26
- `SSEMessage` — `src/helper/streaming/sse.ts`:6
- `childrenToString` — `src/jsx/components.ts`:14
- `StreamingContext` — `src/jsx/streaming.ts`:30
# stringBufferToString
**Kind:** Function
**Source:** [`src/utils/html.ts`](https://github.com/honojs/hono/blob/main/src/utils/html.ts#L53)
**Part of:** [Utils](subsystem-src-utils)
## Signature
```ts
async function stringBufferToString(buffer: StringBuffer, callbacks: HtmlEscapedCallback[] | undefined): Promise
```
## Parameters
| Name | Type |
|---|---|
| `buffer` | `StringBuffer` |
| `callbacks` | `HtmlEscapedCallback[] | undefined` |
**Returns:** `Promise`
## Used by
3 references from 3 files. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (3)
- `html` — `src/helper/html/index.ts`:11
- `Props` — `src/jsx/base.ts`:27
- `jsxAttr` — `src/jsx/jsx-runtime.ts`:16
# checkOptionalParameter
**Kind:** Function
**Source:** [`src/utils/url.ts`](https://github.com/honojs/hono/blob/main/src/utils/url.ts#L171)
**Part of:** [Utils](subsystem-src-utils)
## Signature
```ts
function checkOptionalParameter(path: string): string[] | null
```
## Parameters
| Name | Type |
|---|---|
| `path` | `string` |
**Returns:** `string[] | null`
## Used by
3 references from 3 files. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (3)
- `LinearRouter` — `src/router/linear-router/router.ts`:11
- `RegExpRouter` — `src/router/reg-exp-router/router.ts`:47
- `TrieRouter` — `src/router/trie-router/router.ts`:5
# parseAccept
**Kind:** Function
**Source:** [`src/utils/accept.ts`](https://github.com/honojs/hono/blob/main/src/utils/accept.ts#L211)
**Part of:** [Utils](subsystem-src-utils)
## Signature
```ts
function parseAccept(acceptHeader: string): Accept[]
```
## Parameters
| Name | Type |
|---|---|
| `acceptHeader` | `string` |
**Returns:** `Accept[]`
## Used by
3 references from 3 files. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (3)
- `handler` — `src/middleware/compress/index.ts`:139
- `DetectorType` — `src/middleware/language/language.ts`:10
- `Accept` — `src/helper/accepts/accepts.ts`:5
# encodeBase64
**Kind:** Function
**Source:** [`src/utils/encode.ts`](https://github.com/honojs/hono/blob/main/src/utils/encode.ts#L15)
**Part of:** [Utils](subsystem-src-utils)
## Signature
```ts
function encodeBase64(buf: ArrayBufferLike): string
```
## Parameters
| Name | Type |
|---|---|
| `buf` | `ArrayBufferLike` |
**Returns:** `string`
## Used by
3 references from 3 files. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (3)
- `key` — `src/middleware/secure-headers/secure-headers.ts`:139
- `LambdaEvent` — `src/adapter/aws-lambda/handler.ts`:23
- `CloudFrontRequest` — `src/adapter/lambda-edge/handler.ts`:41
# StreamingApi
**Kind:** Class
**Source:** [`src/utils/stream.ts`](https://github.com/honojs/hono/blob/main/src/utils/stream.ts#L6)
**Part of:** [Utils](subsystem-src-utils)
`StreamingApi` coordinates streamed output, delayed work, piping, and cancellation in `src/utils/stream.ts`. It exposes async write methods alongside abort handling so callers can stop work when the stream is no longer active.
## Methods
| Method | Signature | Returns |
|---|---|---|
| `write` | `write(input: Uint8Array | string)` | `Promise` |
| `writeln` | `writeln(input: string)` | `Promise` |
| `sleep` | `sleep(ms: number)` | `Promise` |
| `close` | `close()` | `void` |
| `pipe` | `pipe(body: ReadableStream)` | `void` |
| `onAbort` | `onAbort(listener: () => void | Promise)` | `void` |
| `abort` | `abort()` | `void` |
## Properties
| Property | Type |
|---|---|
| `responseReadable` | `ReadableStream` |
| `aborted` | `boolean` |
| `closed` | `boolean` |
## When something fails
- `StreamingApi` handles failure in 2 places: it discards it silently in all 2.
## Diagram
```mermaid
graph LR
Caller --> StreamingApi
StreamingApi --> Write[write / writeln]
StreamingApi --> Delay[sleep]
StreamingApi --> Pipe[pipe]
StreamingApi --> Abort[onAbort / abort]
StreamingApi --> Close[close]
```
## Usage
```ts
import type { StreamingApi } from "./utils/stream";
async function handleStream(stream: StreamingApi) {
stream.onAbort(() => {
console.log("Stream aborted");
});
await stream.write();
await stream.writeln();
await stream.sleep();
stream.close();
}
```
## AI Coding Instructions
- Await `write()` and `writeln()` before dependent streamed work.
- Register `onAbort()` handlers before starting long-running work.
- Stop pending work when an abort handler runs; do not continue writing after cancellation.
- Call `close()` when streaming is complete.
- Keep stream lifecycle handling in the caller that owns the request or response.
## Used by
2 references from 2 files. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (2)
- `SSEMessage` — `src/helper/streaming/sse.ts`:6
- `stream` — `src/helper/streaming/stream.ts`:7
# timingSafeEqual
**Kind:** Function
**Source:** [`src/utils/buffer.ts`](https://github.com/honojs/hono/blob/main/src/utils/buffer.ts#L76)
**Part of:** [Utils](subsystem-src-utils)
## Signature
```ts
async function timingSafeEqual(a, b, hashFunction: Function): Promise
```
## Parameters
| Name | Type |
|---|---|
| `a` | `any` |
| `b` | `any` |
| `hashFunction` | `Function` |
**Returns:** `Promise`
## Used by
2 references from 2 files. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (2)
- `handler` — `src/middleware/basic-auth/index.ts`:118
- `bearerAuth` — `src/middleware/bearer-auth/index.ts`:104
# getPattern
**Kind:** Function
**Source:** [`src/utils/url.ts`](https://github.com/honojs/hono/blob/main/src/utils/url.ts#L51)
**Part of:** [Utils](subsystem-src-utils)
## Signature
```ts
function getPattern(label: string, next: string): Pattern | null
```
## Parameters
| Name | Type |
|---|---|
| `label` | `string` |
| `next` | `string` |
**Returns:** `Pattern | null`
## Used by
2 references from 2 files. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (2)
- `Node` — `src/router/trie-router/node.ts`:25
- `matchedRoutes` — `src/helper/route/index.ts`:32
# parseBody
**Kind:** Function
**Source:** [`src/utils/body.ts`](https://github.com/honojs/hono/blob/main/src/utils/body.ts#L97)
**Part of:** [Utils](subsystem-src-utils)
## Signature
```ts
async function parseBody(request: HonoRequest | Request, options)
```
## Parameters
| Name | Type |
|---|---|
| `request` | `HonoRequest | Request` |
| `options` | `any` |
## Used by
2 references from 2 files. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (2)
- `methodFormName` — `src/middleware/method-override/index.ts`:79
- `HonoRequest` — `src/request.ts`:34
# bufferToFormData
**Kind:** Function
**Source:** [`src/utils/buffer.ts`](https://github.com/honojs/hono/blob/main/src/utils/buffer.ts#L106)
**Part of:** [Utils](subsystem-src-utils)
## Signature
```ts
function bufferToFormData(arrayBuffer: ArrayBuffer, contentType: string): Promise
```
## Parameters
| Name | Type |
|---|---|
| `arrayBuffer` | `ArrayBuffer` |
| `contentType` | `string` |
**Returns:** `Promise`
## Used by
2 references from 2 files. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (2)
- `BodyData` — `src/utils/body.ts`:39
- `ValidationFunction` — `src/validator/validator.ts`:14
# resolveCallbackSync
**Kind:** Function
**Source:** [`src/utils/html.ts`](https://github.com/honojs/hono/blob/main/src/utils/html.ts#L129)
**Part of:** [Utils](subsystem-src-utils)
## Signature
```ts
function resolveCallbackSync(str: string | HtmlEscapedString): string
```
## Parameters
| Name | Type |
|---|---|
| `str` | `string | HtmlEscapedString` |
**Returns:** `string`
## Used by
2 references from 2 files. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (2)
- `html` — `src/helper/html/index.ts`:11
- `Props` — `src/jsx/base.ts`:27
# findTargetHandler
**Kind:** Function
**Source:** [`src/utils/handler.ts`](https://github.com/honojs/hono/blob/main/src/utils/handler.ts#L9)
**Part of:** [Utils](subsystem-src-utils)
## Signature
```ts
function findTargetHandler(handler: Function): Function
```
## Parameters
| Name | Type |
|---|---|
| `handler` | `Function` |
**Returns:** `Function`
## Used by
2 references from 2 files. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (2)
- `inspectRoutes` — `src/helper/dev/index.ts`:27
- `dirname` — `src/helper/ssg/utils.ts`:11
# splitRoutingPath
**Kind:** Function
**Source:** [`src/utils/url.ts`](https://github.com/honojs/hono/blob/main/src/utils/url.ts#L16)
**Part of:** [Utils](subsystem-src-utils)
## Signature
```ts
function splitRoutingPath(routePath: string): string[]
```
## Parameters
| Name | Type |
|---|---|
| `routePath` | `string` |
**Returns:** `string[]`
## Used by
2 references from 2 files. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (2)
- `Node` — `src/router/trie-router/node.ts`:25
- `matchedRoutes` — `src/helper/route/index.ts`:32
# sha256
**Kind:** Function
**Source:** [`src/utils/crypto.ts`](https://github.com/honojs/hono/blob/main/src/utils/crypto.ts#L15)
**Part of:** [Utils](subsystem-src-utils)
## Signature
```ts
async function sha256(data: Data): Promise
```
## Parameters
| Name | Type |
|---|---|
| `data` | `Data` |
**Returns:** `Promise`
## Used by
2 references from 2 files. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (2)
- `handler` — `src/middleware/cache/index.ts`:310
- `equal` — `src/utils/buffer.ts`:8
# tryDecodeURIComponent
**Kind:** Function
**Source:** [`src/utils/url.ts`](https://github.com/honojs/hono/blob/main/src/utils/url.ts#L208)
**Part of:** [Utils](subsystem-src-utils)
## Signature
```ts
function tryDecodeURIComponent(str: string): string
```
## Parameters
| Name | Type |
|---|---|
| `str` | `string` |
**Returns:** `string`
## Used by
2 references from 2 files. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (2)
- `HonoRequest` — `src/request.ts`:34
- `Cookie` — `src/utils/cookie.ts`:8
# isMiddleware
**Kind:** Function
**Source:** [`src/utils/handler.ts`](https://github.com/honojs/hono/blob/main/src/utils/handler.ts#L8)
**Part of:** [Utils](subsystem-src-utils)
## Signature
```ts
function isMiddleware(handler: Function)
```
## Parameters
| Name | Type |
|---|---|
| `handler` | `Function` |
## Relationships
- IMPORTS → `COMPOSED_HANDLER`
## Used by
2 references from 2 files. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (2)
- `inspectRoutes` — `src/helper/dev/index.ts`:27
- `dirname` — `src/helper/ssg/utils.ts`:11
# COMPRESSIBLE_CONTENT_TYPE_REGEX
**Kind:** Constant
**Source:** [`src/utils/compress.ts`](https://github.com/honojs/hono/blob/main/src/utils/compress.ts#L9)
**Part of:** [Utils](subsystem-src-utils)
## Definition
```ts
/^\s*(?:text\/(?!event-stream(?:[;\s]|$))[^;\s]+|application\/(?:javascript|json|xml|xml-dtd|ecmascript|dart|msgpack|postscript|rtf|tar|toml|vnd\.dart|vnd\.ms-fontobject|vnd\.ms-opentype|vnd\.msgpack|wasm|x-httpd-php|x-javascript|x-msgpack|x-ns-proxy-autoconfig|x-sh|x-tar|x-virtualbox-hdd|x-virtualbox-ova|x-virtualbox-ovf|x-virtualbox-vbox|x-virtualbox-vdi|x-virtualbox-vhd|x-virtualbox-vmdk|x-www-…
```
## Value
```ts
/^\s*(?:text\/(?!event-stream(?:[;\s]|$))[^;\s]+|application\/(?:javascript|json|xml|xml-dtd|ecmascript|dart|msgpack|postscript|rtf|tar|toml|vnd\.dart|vnd\.ms-fontobject|vnd\.ms-opentype|vnd\.msgpack|wasm|x-httpd-php|x-javascript|x-msgpack|x-ns-proxy-autoconfig|x-sh|x-tar|x-virtualbox-hdd|x-virtualbox-ova|x-virtualbox-ovf|x-virtualbox-vbox|x-virtualbox-vdi|x-virtualbox-vhd|x-virtualbox-vmdk|x-www-…
```
## Used by
2 references from 2 files. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (2)
- `handler` — `src/middleware/compress/index.ts`:139
- `ServeStaticOptions` — `src/middleware/serve-static/index.ts`:13
# COMPOSED_HANDLER
**Kind:** Constant
**Source:** [`src/utils/constants.ts`](https://github.com/honojs/hono/blob/main/src/utils/constants.ts#L4)
**Part of:** [Utils](subsystem-src-utils)
Constant used to mark a composed handler.
`COMPOSED_HANDLER` is a shared marker for handlers created through composition. Code that creates or inspects composed handlers can use this constant to apply and detect the same marker consistently.
## Definition
```ts
'__COMPOSED_HANDLER'
```
## Value
```ts
'__COMPOSED_HANDLER'
```
## Diagram
```mermaid
graph LR
A[Handler composition] --> B[Composed handler]
B --> C[COMPOSED_HANDLER marker]
C --> D[Handler detection logic]
```
## Usage
```ts
import { COMPOSED_HANDLER } from './utils/constants';
function isComposedHandler(handler: object): boolean {
return COMPOSED_HANDLER in handler;
}
// A handler created by composition is marked with COMPOSED_HANDLER.
if (isComposedHandler(handler)) {
// Apply composed-handler behavior.
}
```
## AI Coding Instructions
- Import `COMPOSED_HANDLER` from `src/utils/constants.ts` instead of duplicating its marker value.
- Apply the marker where handlers are composed, not where ordinary handlers are created.
- Check for the marker before running behavior that is specific to composed handlers.
- Keep marker creation and marker detection aligned so both paths use `COMPOSED_HANDLER`.
## Used by
2 references from 2 files. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (2)
- `HonoOptions` — `src/hono-base.ts`:46
- `isMiddleware` — `src/utils/handler.ts`:8
# Jwt
**Kind:** Constant
**Source:** [`src/utils/jwt/index.ts`](https://github.com/honojs/hono/blob/main/src/utils/jwt/index.ts#L7)
**Part of:** [Utils](subsystem-src-utils)
## Definition
```ts
{ sign, verify, decode, verifyWithJwks }
```
## Value
```ts
{ sign, verify, decode, verifyWithJwks }
```
## Relationships
- IMPORTS → `decode`
- IMPORTS → `sign`
- IMPORTS → `verify`
- IMPORTS → `verifyWithJwks`
## Used by
2 references from 2 files. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (2)
- `headerName` — `src/middleware/jwk/jwk.ts`:81
- `headerName` — `src/middleware/jwt/jwt.ts`:81
# utf8Encoder
**Kind:** Constant
**Source:** [`src/utils/jwt/utf8.ts`](https://github.com/honojs/hono/blob/main/src/utils/jwt/utf8.ts#L6)
**Part of:** [Utils](subsystem-src-utils)
## Definition
```ts
TextEncoder
```
## Value
```ts
new TextEncoder()
```
## Used by
2 references from 2 files. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (2)
- `HonoJsonWebKey` — `src/utils/jwt/jws.ts`:23
- `TokenHeader` — `src/utils/jwt/jwt.ts`:38
# verify
**Kind:** Function
**Source:** [`src/utils/jwt/jwt.ts`](https://github.com/honojs/hono/blob/main/src/utils/jwt/jwt.ts#L96)
**Part of:** [Utils](subsystem-src-utils)
## Signature
```ts
async function verify(token: string, publicKey: SignatureKey, algOrOptions: SignatureAlgorithm | VerifyOptionsWithAlg): Promise
```
## Parameters
| Name | Type |
|---|---|
| `token` | `string` |
| `publicKey` | `SignatureKey` |
| `algOrOptions` | `SignatureAlgorithm | VerifyOptionsWithAlg` |
**Returns:** `Promise`
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `Jwt` — `src/utils/jwt/index.ts`:7
# verifyWithJwks
**Kind:** Function
**Source:** [`src/utils/jwt/jwt.ts`](https://github.com/honojs/hono/blob/main/src/utils/jwt/jwt.ts#L197)
**Part of:** [Utils](subsystem-src-utils)
## Signature
```ts
async function verifyWithJwks(token: string, options: { keys?: HonoJsonWebKey[] jwks_uri?: string verification?: VerifyOptions allowedAlgorithms: readonly AsymmetricAlgorithm[] }, init: RequestInit): Promise
```
## Parameters
| Name | Type |
|---|---|
| `token` | `string` |
| `options` | `{ keys?: HonoJsonWebKey[] jwks_uri?: string verification?: VerifyOptions allowedAlgorithms: readonly AsymmetricAlgorithm[] }` |
| `init` | `RequestInit` |
**Returns:** `Promise`
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `Jwt` — `src/utils/jwt/index.ts`:7
# parseSigned
**Kind:** Function
**Source:** [`src/utils/cookie.ts`](https://github.com/honojs/hono/blob/main/src/utils/cookie.ts#L146)
**Part of:** [Utils](subsystem-src-utils)
## Signature
```ts
async function parseSigned(cookie: string, secret: string | BufferSource, name: string): Promise
```
## Parameters
| Name | Type |
|---|---|
| `cookie` | `string` |
| `secret` | `string | BufferSource` |
| `name` | `string` |
**Returns:** `Promise`
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `getCookie` — `src/helper/cookie/index.ts`:27
# convertIPv6ToBinary
**Kind:** Function
**Source:** [`src/utils/ipaddr.ts`](https://github.com/honojs/hono/blob/main/src/utils/ipaddr.ts#L157)
**Part of:** [Utils](subsystem-src-utils)
Convert IPv6 to Uint8Array
`convertIPv6ToBinary` accepts an IPv6 address string and converts it into a `Uint8Array`. It belongs to the IP address utility layer, where callers can use the byte representation for address processing and comparisons.
## Signature
```ts
function convertIPv6ToBinary(ipv6: string): bigint
```
## Parameters
| Name | Type |
|---|---|
| `ipv6` | `string` |
**Returns:** `bigint`
## Diagram
```mermaid
graph LR
Address[IPv6 address string] --> Convert[convertIPv6ToBinary]
Convert --> Bytes[Uint8Array]
```
## Usage
```ts
import { convertIPv6ToBinary } from './utils/ipaddr';
const address = 'fe80::abcd';
const bytes = convertIPv6ToBinary(address);
console.log(bytes);
```
## AI Coding Instructions
- Pass IPv6 address strings to `convertIPv6ToBinary`; do not use it for IPv4 addresses.
- Treat the returned value as binary address data rather than a formatted address string.
- Keep address parsing and conversion logic in `src/utils/ipaddr.ts`.
- Match existing caller behavior for invalid or malformed IPv6 input.
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `IPRestrictionRule` — `src/middleware/ip-restriction/index.ts`:38
# serializeSigned
**Kind:** Function
**Source:** [`src/utils/cookie.ts`](https://github.com/honojs/hono/blob/main/src/utils/cookie.ts#L270)
**Part of:** [Utils](subsystem-src-utils)
## Signature
```ts
async function serializeSigned(name: string, value: string, secret: string | BufferSource, opt: CookieOptions): Promise
```
## Parameters
| Name | Type |
|---|---|
| `name` | `string` |
| `value` | `string` |
| `secret` | `string | BufferSource` |
| `opt` | `CookieOptions` |
**Returns:** `Promise`
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `getCookie` — `src/helper/cookie/index.ts`:27
# sign
**Kind:** Function
**Source:** [`src/utils/jwt/jwt.ts`](https://github.com/honojs/hono/blob/main/src/utils/jwt/jwt.ts#L56)
**Part of:** [Utils](subsystem-src-utils)
## Signature
```ts
async function sign(payload: JWTPayload, privateKey: SignatureKey, alg: SignatureAlgorithm): Promise
```
## Parameters
| Name | Type |
|---|---|
| `payload` | `JWTPayload` |
| `privateKey` | `SignatureKey` |
| `alg` | `SignatureAlgorithm` |
**Returns:** `Promise`
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `Jwt` — `src/utils/jwt/index.ts`:7
# parse
**Kind:** Function
**Source:** [`src/utils/cookie.ts`](https://github.com/honojs/hono/blob/main/src/utils/cookie.ts#L109)
**Part of:** [Utils](subsystem-src-utils)
## Signature
```ts
function parse(cookie: string, name: string): Cookie
```
## Parameters
| Name | Type |
|---|---|
| `cookie` | `string` |
| `name` | `string` |
**Returns:** `Cookie`
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `getCookie` — `src/helper/cookie/index.ts`:27
# verifying
**Kind:** Function
**Source:** [`src/utils/jwt/jws.ts`](https://github.com/honojs/hono/blob/main/src/utils/jwt/jws.ts#L39)
**Part of:** [Utils](subsystem-src-utils)
## Signature
```ts
async function verifying(publicKey: SignatureKey, alg: SignatureAlgorithm, signature: BufferSource, data: BufferSource): Promise
```
## Parameters
| Name | Type |
|---|---|
| `publicKey` | `SignatureKey` |
| `alg` | `SignatureAlgorithm` |
| `signature` | `BufferSource` |
| `data` | `BufferSource` |
**Returns:** `Promise`
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `TokenHeader` — `src/utils/jwt/jwt.ts`:38
# mergePath
**Kind:** Function
**Source:** [`src/utils/url.ts`](https://github.com/honojs/hono/blob/main/src/utils/url.ts#L158)
**Part of:** [Utils](subsystem-src-utils)
Merge paths.
`mergePath` combines path values into a single URL path. Use it when building route, endpoint, or asset paths so callers do not need to concatenate path strings manually.
## Signature
```ts
function mergePath(base: string | undefined, sub: string | undefined, rest: string[]): string
```
## Parameters
| Name | Type |
|---|---|
| `base` | `string | undefined` |
| `sub` | `string | undefined` |
| `rest` | `string[]` |
**Returns:** `string`
## Diagram
```mermaid
graph LR
A[Base path] --> C[mergePath]
B[Path segment] --> C
C --> D[Merged path]
```
## Usage
```ts
import { mergePath } from './utils/url';
const usersPath = mergePath('/api/', '/users');
console.log(usersPath); // /api/users
```
## AI Coding Instructions
- Pass path segments to `mergePath` instead of concatenating strings with `/`.
- Keep path inputs consistent with existing callers, especially leading and trailing slashes.
- Use this helper when constructing routes, API endpoints, or asset paths in shared URL-building code.
- Do not assume it handles full URLs, query parameters, or hash fragments unless its implementation supports them.
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `HonoOptions` — `src/hono-base.ts`:46
# signing
**Kind:** Function
**Source:** [`src/utils/jwt/jws.ts`](https://github.com/honojs/hono/blob/main/src/utils/jwt/jws.ts#L29)
**Part of:** [Utils](subsystem-src-utils)
## Signature
```ts
async function signing(privateKey: SignatureKey, alg: SignatureAlgorithm, data: BufferSource): Promise
```
## Parameters
| Name | Type |
|---|---|
| `privateKey` | `SignatureKey` |
| `alg` | `SignatureAlgorithm` |
| `data` | `BufferSource` |
**Returns:** `Promise`
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `TokenHeader` — `src/utils/jwt/jwt.ts`:38
# convertIPv6BinaryToString
**Kind:** Function
**Source:** [`src/utils/ipaddr.ts`](https://github.com/honojs/hono/blob/main/src/utils/ipaddr.ts#L327)
**Part of:** [Utils](subsystem-src-utils)
Convert a binary representation of an IPv6 address to a string.
`convertIPv6BinaryToString` converts an IPv6 address from its binary representation into a string. Use it at boundaries where binary address data must be displayed, logged, or passed to code that expects an IPv6 string.
## Signature
```ts
function convertIPv6BinaryToString(ipV6: bigint): string
```
## Parameters
| Name | Type |
|---|---|
| `ipV6` | `bigint` |
**Returns:** `string`
## Diagram
```mermaid
graph LR
A[Binary IPv6 value] --> B[convertIPv6BinaryToString]
B --> C[IPv6 string]
```
## Usage
```ts
import { convertIPv6BinaryToString } from "./utils/ipaddr";
// Obtain the binary IPv6 value from a network, parser, or storage layer.
declare const binaryIPv6: string;
const ipv6Address = convertIPv6BinaryToString(binaryIPv6);
console.log(ipv6Address);
```
## AI Coding Instructions
- Pass the binary IPv6 value to this function, not an already formatted IPv6 string.
- Keep binary-to-string conversion at input or output boundaries rather than spreading address formatting logic across callers.
- Preserve the binary value unchanged before conversion; changing its order changes the resulting address.
- Use the returned string for display, logging, serialization, or APIs that accept textual IPv6 addresses.
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `IPRestrictionRule` — `src/middleware/ip-restriction/index.ts`:38
# createPool
**Kind:** Function
**Source:** [`src/utils/concurrent.ts`](https://github.com/honojs/hono/blob/main/src/utils/concurrent.ts#L12)
**Part of:** [Utils](subsystem-src-utils)
## Signature
```ts
function createPool({
concurrency,
interval,
}: { concurrency?: number interval?: number }): Pool
```
## Parameters
| Name | Type |
|---|---|
| `{
concurrency,
interval,
}` | `{ concurrency?: number interval?: number }` |
**Returns:** `Pool`
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `DEFAULT_OUTPUT_DIR` — `src/helper/ssg/ssg.ts`:27
# serialize
**Kind:** Function
**Source:** [`src/utils/cookie.ts`](https://github.com/honojs/hono/blob/main/src/utils/cookie.ts#L261)
**Part of:** [Utils](subsystem-src-utils)
## Signature
```ts
function serialize(name: Name, value: string, opt: CookieConstraint): string
```
## Parameters
| Name | Type |
|---|---|
| `name` | `Name` |
| `value` | `string` |
| `opt` | `CookieConstraint` |
**Returns:** `string`
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `getCookie` — `src/helper/cookie/index.ts`:27
# getMimeType
**Kind:** Function
**Source:** [`src/utils/mime.ts`](https://github.com/honojs/hono/blob/main/src/utils/mime.ts#L6)
**Part of:** [Utils](subsystem-src-utils)
## Signature
```ts
function getMimeType(filename: string, mimes: Record): string | undefined
```
## Parameters
| Name | Type |
|---|---|
| `filename` | `string` |
| `mimes` | `Record` |
**Returns:** `string | undefined`
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `ServeStaticOptions` — `src/middleware/serve-static/index.ts`:13
# getPath
**Kind:** Function
**Source:** [`src/utils/url.ts`](https://github.com/honojs/hono/blob/main/src/utils/url.ts#L106)
**Part of:** [Utils](subsystem-src-utils)
## Signature
```ts
function getPath(request: Request): string
```
## Parameters
| Name | Type |
|---|---|
| `request` | `Request` |
**Returns:** `string`
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `HonoOptions` — `src/hono-base.ts`:46
# raw
**Kind:** Function
**Source:** [`src/utils/html.ts`](https://github.com/honojs/hono/blob/main/src/utils/html.ts#L40)
**Part of:** [Utils](subsystem-src-utils)
## Signature
```ts
function raw(value: unknown, callbacks: HtmlEscapedCallback[]): HtmlEscapedString
```
## Parameters
| Name | Type |
|---|---|
| `value` | `unknown` |
| `callbacks` | `HtmlEscapedCallback[]` |
**Returns:** `HtmlEscapedString`
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `html` — `src/helper/html/index.ts`:11
# auth
**Kind:** Function
**Source:** [`src/utils/basic-auth.ts`](https://github.com/honojs/hono/blob/main/src/utils/basic-auth.ts#L9)
**Part of:** [Utils](subsystem-src-utils)
## Signature
```ts
function auth(req: Request)
```
## Parameters
| Name | Type |
|---|---|
| `req` | `Request` |
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `handler` — `src/middleware/basic-auth/index.ts`:118
# decode
**Kind:** Function
**Source:** [`src/utils/jwt/jwt.ts`](https://github.com/honojs/hono/blob/main/src/utils/jwt/jwt.ts#L264)
**Part of:** [Utils](subsystem-src-utils)
## Signature
```ts
function decode(token: string): { header: TokenHeader; payload: JWTPayload }
```
## Parameters
| Name | Type |
|---|---|
| `token` | `string` |
**Returns:** `{ header: TokenHeader; payload: JWTPayload }`
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `Jwt` — `src/utils/jwt/index.ts`:7
# getQueryParams
**Kind:** Function
**Source:** [`src/utils/url.ts`](https://github.com/honojs/hono/blob/main/src/utils/url.ts#L310)
**Part of:** [Utils](subsystem-src-utils)
## Signature
```ts
function getQueryParams(url: string, key: string): string[] | undefined | Record
```
## Parameters
| Name | Type |
|---|---|
| `url` | `string` |
| `key` | `string` |
**Returns:** `string[] | undefined | Record`
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `HonoRequest` — `src/request.ts`:34
# distinctRemoteAddr
**Kind:** Function
**Source:** [`src/utils/ipaddr.ts`](https://github.com/honojs/hono/blob/main/src/utils/ipaddr.ts#L59)
**Part of:** [Utils](subsystem-src-utils)
Distinct Remote Addr
`distinctRemoteAddr` derives a distinct remote-address value from the address data passed to it. It belongs to the IP-address utility layer and centralizes remote-address handling for callers that need a consistent value.
## Signature
```ts
function distinctRemoteAddr(remoteAddr: string): AddressType
```
## Parameters
| Name | Type |
|---|---|
| `remoteAddr` | `string` |
**Returns:** `AddressType`
## Diagram
```mermaid
graph LR
Input[Remote address data] --> Function[distinctRemoteAddr]
Function --> Output[Distinct remote address]
```
## Usage
```ts
import { distinctRemoteAddr } from "./utils/ipaddr";
const remoteAddress = request.socket.remoteAddress;
const address = distinctRemoteAddr(remoteAddress);
if (address) {
auditLog({ remoteAddress: address });
}
```
## AI Coding Instructions
- Keep remote-address parsing and normalization inside `src/utils/ipaddr.ts`.
- Pass the address value in the format expected by `distinctRemoteAddr`.
- Check the returned value before using it in logs, access checks, or storage.
- Do not duplicate remote-address handling logic at call sites.
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `IPRestrictionRule` — `src/middleware/ip-restriction/index.ts`:38
# getExtension
**Kind:** Function
**Source:** [`src/utils/mime.ts`](https://github.com/honojs/hono/blob/main/src/utils/mime.ts#L18)
**Part of:** [Utils](subsystem-src-utils)
## Signature
```ts
function getExtension(mimeType: string): string | undefined
```
## Parameters
| Name | Type |
|---|---|
| `mimeType` | `string` |
**Returns:** `string | undefined`
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `DEFAULT_OUTPUT_DIR` — `src/helper/ssg/ssg.ts`:27
# splitPath
**Kind:** Function
**Source:** [`src/utils/url.ts`](https://github.com/honojs/hono/blob/main/src/utils/url.ts#L8)
**Part of:** [Utils](subsystem-src-utils)
## Signature
```ts
function splitPath(path: string): string[]
```
## Parameters
| Name | Type |
|---|---|
| `path` | `string` |
**Returns:** `string[]`
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `Node` — `src/router/trie-router/node.ts`:25
# getPathNoStrict
**Kind:** Function
**Source:** [`src/utils/url.ts`](https://github.com/honojs/hono/blob/main/src/utils/url.ts#L141)
**Part of:** [Utils](subsystem-src-utils)
## Signature
```ts
function getPathNoStrict(request: Request): string
```
## Parameters
| Name | Type |
|---|---|
| `request` | `Request` |
**Returns:** `string`
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `HonoOptions` — `src/hono-base.ts`:46
# convertIPv4ToBinary
**Kind:** Function
**Source:** [`src/utils/ipaddr.ts`](https://github.com/honojs/hono/blob/main/src/utils/ipaddr.ts#L148)
**Part of:** [Utils](subsystem-src-utils)
Convert IPv4 to Uint8Array
Converts an IPv4 address string into a `Uint8Array` representation. It supports code in `src/utils/ipaddr.ts` that needs address data in byte form.
## Signature
```ts
function convertIPv4ToBinary(ipv4: string): bigint
```
## Parameters
| Name | Type |
|---|---|
| `ipv4` | `string` |
**Returns:** `bigint`
## Diagram
```mermaid
graph LR
Input[IPv4 address string] --> Convert[convertIPv4ToBinary]
Convert --> Output[Uint8Array]
```
## Usage
```ts
import { convertIPv4ToBinary } from './utils/ipaddr';
declare const ipv4Address: string;
const addressBytes = convertIPv4ToBinary(ipv4Address);
console.log(addressBytes);
```
## AI Coding Instructions
- Pass a valid IPv4 address string to this function.
- Keep the returned value as a `Uint8Array` when passing address data to byte-oriented APIs.
- Handle invalid address input at the caller when the surrounding flow requires user-facing errors.
- Import the helper from `src/utils/ipaddr.ts` rather than duplicating address-to-byte conversion logic.
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `IPRestrictionRule` — `src/middleware/ip-restriction/index.ts`:38
# decodeBase64Url
**Kind:** Function
**Source:** [`src/utils/encode.ts`](https://github.com/honojs/hono/blob/main/src/utils/encode.ts#L6)
**Part of:** [Utils](subsystem-src-utils)
## Signature
```ts
function decodeBase64Url(str: string): Uint8Array
```
## Parameters
| Name | Type |
|---|---|
| `str` | `string` |
**Returns:** `Uint8Array`
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `TokenHeader` — `src/utils/jwt/jwt.ts`:38
# getColorEnabledAsync
**Kind:** Function
**Source:** [`src/utils/color.ts`](https://github.com/honojs/hono/blob/main/src/utils/color.ts#L36)
**Part of:** [Utils](subsystem-src-utils)
Get whether color change on terminal is enabled or disabled.
If `NO_COLOR` environment variable is set, this function returns `false`.
`getColorEnabledAsync` asynchronously determines whether terminal color changes are enabled. When the `NO_COLOR` environment variable is set, it returns `false` so callers can avoid emitting color formatting.
## Signature
```ts
async function getColorEnabledAsync(): Promise
```
**Returns:** `Promise`
## Diagram
```mermaid
graph LR
A[Caller] --> B[getColorEnabledAsync]
B --> C{NO_COLOR set?}
C -->|Yes| D[Return false]
C -->|No| E[Return color-enabled status]
```
## Usage
```ts
import { getColorEnabledAsync } from './utils/color';
const colorEnabled = await getColorEnabledAsync();
if (colorEnabled) {
console.log('\u001b[32mSuccess\u001b[0m');
} else {
console.log('Success');
}
```
## AI Coding Instructions
- Always `await` `getColorEnabledAsync` before deciding whether to write terminal color escape sequences.
- Respect a `false` result and emit plain text when color changes are disabled.
- Do not override the `NO_COLOR` environment variable behavior in calling code.
- Keep terminal output formatting decisions close to the code that writes to the terminal.
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `logger` — `src/middleware/logger/index.ts`:81
# AlgorithmTypes
**Kind:** Enum
**Source:** [`src/utils/jwt/jwa.ts`](https://github.com/honojs/hono/blob/main/src/utils/jwt/jwa.ts#L7)
**Part of:** [Utils](subsystem-src-utils)
## Values
- `HS256`
- `HS384`
- `HS512`
- `RS256`
- `RS384`
- `RS512`
- `PS256`
- `PS384`
- `PS512`
- `ES256`
- `ES384`
- `ES512`
- `EdDSA`
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `TokenHeader` — `src/utils/jwt/jwt.ts`:38
# getColorEnabled
**Kind:** Function
**Source:** [`src/utils/color.ts`](https://github.com/honojs/hono/blob/main/src/utils/color.ts#L14)
**Part of:** [Utils](subsystem-src-utils)
## Signature
```ts
function getColorEnabled(): boolean
```
**Returns:** `boolean`
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `inspectRoutes` — `src/helper/dev/index.ts`:27
# encodeBase64Url
**Kind:** Function
**Source:** [`src/utils/encode.ts`](https://github.com/honojs/hono/blob/main/src/utils/encode.ts#L10)
**Part of:** [Utils](subsystem-src-utils)
## Signature
```ts
function encodeBase64Url(buf: ArrayBufferLike): string
```
## Parameters
| Name | Type |
|---|---|
| `buf` | `ArrayBufferLike` |
**Returns:** `string`
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `TokenHeader` — `src/utils/jwt/jwt.ts`:38
# CryptoKeyUsage
**Kind:** Enum
**Source:** [`src/utils/jwt/types.ts`](https://github.com/honojs/hono/blob/main/src/utils/jwt/types.ts#L117)
**Part of:** [Utils](subsystem-src-utils)
## Values
- `Encrypt`
- `Decrypt`
- `Sign`
- `Verify`
- `DeriveKey`
- `DeriveBits`
- `WrapKey`
- `UnwrapKey`
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `HonoJsonWebKey` — `src/utils/jwt/jws.ts`:23
# JwtTokenAudience
**Kind:** Class
**Source:** [`src/utils/jwt/types.ts`](https://github.com/honojs/hono/blob/main/src/utils/jwt/types.ts#L106)
**Part of:** [Utils](subsystem-src-utils)
**Extends:** `Error`
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `TokenHeader` — `src/utils/jwt/jwt.ts`:38
# JwtTokenIssuedAt
**Kind:** Class
**Source:** [`src/utils/jwt/types.ts`](https://github.com/honojs/hono/blob/main/src/utils/jwt/types.ts#L48)
**Part of:** [Utils](subsystem-src-utils)
**Extends:** `Error`
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `TokenHeader` — `src/utils/jwt/jwt.ts`:38
# getQueryParam
**Kind:** Constant
**Source:** [`src/utils/url.ts`](https://github.com/honojs/hono/blob/main/src/utils/url.ts#L302)
**Part of:** [Utils](subsystem-src-utils)
## Definition
```ts
( url: string, key?: string ) => string | undefined | Record
```
## Value
```ts
_getQueryParam as (
url: string,
key?: string
) => string | undefined | Record
```
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `HonoRequest` — `src/request.ts`:34
# convertIPv4MappedIPv6ToIPv4
**Kind:** Function
**Source:** [`src/utils/ipaddr.ts`](https://github.com/honojs/hono/blob/main/src/utils/ipaddr.ts#L320)
**Part of:** [Utils](subsystem-src-utils)
Extract the IPv4 portion from an IPv4-mapped IPv6 address
`convertIPv4MappedIPv6ToIPv4` extracts the IPv4 address portion from an IPv4-mapped IPv6 address. It is intended for address-handling paths where network inputs may represent IPv4 clients in IPv6 notation.
## Signature
```ts
function convertIPv4MappedIPv6ToIPv4(ipv6binary: bigint): bigint
```
## Parameters
| Name | Type |
|---|---|
| `ipv6binary` | `bigint` |
**Returns:** `bigint`
## Diagram
```mermaid
graph LR
A[Network address input] --> B[convertIPv4MappedIPv6ToIPv4]
B --> C[IPv4 address portion]
```
## Usage
```ts
import { convertIPv4MappedIPv6ToIPv4 } from './utils/ipaddr';
const remoteAddress = request.socket.remoteAddress;
if (remoteAddress) {
const clientAddress = convertIPv4MappedIPv6ToIPv4(remoteAddress);
console.log(clientAddress);
}
```
## AI Coding Instructions
- Call this function when processing network addresses from sockets, proxies, or request metadata.
- Pass the raw address string into the function before comparing it with IPv4 allowlists or blocklists.
- Do not treat this function as a general IPv6 parser or formatter.
- Add tests for IPv4-mapped IPv6 inputs and address inputs that are not IPv4-mapped.
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `IPRestrictionRule` — `src/middleware/ip-restriction/index.ts`:38
# isIPv4MappedIPv6
**Kind:** Function
**Source:** [`src/utils/ipaddr.ts`](https://github.com/honojs/hono/blob/main/src/utils/ipaddr.ts#L313)
**Part of:** [Utils](subsystem-src-utils)
Check if a binary IPv6 address is an IPv4-mapped IPv6 address (::ffff:x.x.x.x)
`isIPv4MappedIPv6` checks whether a binary IPv6 address matches the IPv4-mapped IPv6 form: `::ffff:x.x.x.x`. It helps address parsing and routing code identify IPv6 byte arrays that represent embedded IPv4 addresses.
## Signature
```ts
function isIPv4MappedIPv6(ipv6binary: bigint): boolean
```
## Parameters
| Name | Type |
|---|---|
| `ipv6binary` | `bigint` |
**Returns:** `boolean`
## Diagram
```mermaid
graph LR
A[Binary IPv6 address] --> B[isIPv4MappedIPv6]
B --> C{Matches ::ffff IPv4-mapped prefix?}
C -->|Yes| D[true]
C -->|No| E[false]
```
## Usage
```ts
import { isIPv4MappedIPv6 } from './utils/ipaddr.js'
function handleAddress(binaryAddress: Uint8Array): void {
if (isIPv4MappedIPv6(binaryAddress)) {
console.log('Address is an IPv4-mapped IPv6 address')
return
}
console.log('Address is not IPv4-mapped')
}
```
## AI Coding Instructions
- Pass the binary IPv6 byte representation; do not pass a textual IP address directly.
- Keep this check before extracting or handling the embedded IPv4 portion of an address.
- Preserve the byte order produced by the IPv6 parser when passing addresses to this function.
- Test both IPv4-mapped and non-mapped IPv6 byte arrays when changing address parsing code.
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `IPRestrictionRule` — `src/middleware/ip-restriction/index.ts`:38
# JwtAlgorithmMismatch
**Kind:** Class
**Source:** [`src/utils/jwt/types.ts`](https://github.com/honojs/hono/blob/main/src/utils/jwt/types.ts#L20)
**Part of:** [Utils](subsystem-src-utils)
**Extends:** `Error`
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `TokenHeader` — `src/utils/jwt/jwt.ts`:38
# JwtAlgorithmNotAllowed
**Kind:** Class
**Source:** [`src/utils/jwt/types.ts`](https://github.com/honojs/hono/blob/main/src/utils/jwt/types.ts#L85)
**Part of:** [Utils](subsystem-src-utils)
**Extends:** `Error`
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `TokenHeader` — `src/utils/jwt/jwt.ts`:38
# JwtAlgorithmNotImplemented
**Kind:** Class
**Source:** [`src/utils/jwt/types.ts`](https://github.com/honojs/hono/blob/main/src/utils/jwt/types.ts#L6)
**Part of:** [Utils](subsystem-src-utils)
**Extends:** `Error`
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `HonoJsonWebKey` — `src/utils/jwt/jws.ts`:23
# JwtAlgorithmRequired
**Kind:** Class
**Source:** [`src/utils/jwt/types.ts`](https://github.com/honojs/hono/blob/main/src/utils/jwt/types.ts#L13)
**Part of:** [Utils](subsystem-src-utils)
**Extends:** `Error`
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `TokenHeader` — `src/utils/jwt/jwt.ts`:38
# JwtHeaderInvalid
**Kind:** Class
**Source:** [`src/utils/jwt/types.ts`](https://github.com/honojs/hono/blob/main/src/utils/jwt/types.ts#L64)
**Part of:** [Utils](subsystem-src-utils)
**Extends:** `Error`
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `TokenHeader` — `src/utils/jwt/jwt.ts`:38
# JwtHeaderRequiresKid
**Kind:** Class
**Source:** [`src/utils/jwt/types.ts`](https://github.com/honojs/hono/blob/main/src/utils/jwt/types.ts#L71)
**Part of:** [Utils](subsystem-src-utils)
**Extends:** `Error`
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `TokenHeader` — `src/utils/jwt/jwt.ts`:38
# JwtPayloadRequiresAud
**Kind:** Class
**Source:** [`src/utils/jwt/types.ts`](https://github.com/honojs/hono/blob/main/src/utils/jwt/types.ts#L99)
**Part of:** [Utils](subsystem-src-utils)
**Extends:** `Error`
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `TokenHeader` — `src/utils/jwt/jwt.ts`:38
# JwtSymmetricAlgorithmNotAllowed
**Kind:** Class
**Source:** [`src/utils/jwt/types.ts`](https://github.com/honojs/hono/blob/main/src/utils/jwt/types.ts#L78)
**Part of:** [Utils](subsystem-src-utils)
**Extends:** `Error`
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `TokenHeader` — `src/utils/jwt/jwt.ts`:38
# JwtTokenExpired
**Kind:** Class
**Source:** [`src/utils/jwt/types.ts`](https://github.com/honojs/hono/blob/main/src/utils/jwt/types.ts#L41)
**Part of:** [Utils](subsystem-src-utils)
**Extends:** `Error`
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `TokenHeader` — `src/utils/jwt/jwt.ts`:38
# JwtTokenInvalid
**Kind:** Class
**Source:** [`src/utils/jwt/types.ts`](https://github.com/honojs/hono/blob/main/src/utils/jwt/types.ts#L27)
**Part of:** [Utils](subsystem-src-utils)
**Extends:** `Error`
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `TokenHeader` — `src/utils/jwt/jwt.ts`:38
# JwtTokenIssuer
**Kind:** Class
**Source:** [`src/utils/jwt/types.ts`](https://github.com/honojs/hono/blob/main/src/utils/jwt/types.ts#L57)
**Part of:** [Utils](subsystem-src-utils)
**Extends:** `Error`
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `TokenHeader` — `src/utils/jwt/jwt.ts`:38
# JwtTokenNotBefore
**Kind:** Class
**Source:** [`src/utils/jwt/types.ts`](https://github.com/honojs/hono/blob/main/src/utils/jwt/types.ts#L34)
**Part of:** [Utils](subsystem-src-utils)
**Extends:** `Error`
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `TokenHeader` — `src/utils/jwt/jwt.ts`:38
# JwtTokenSignatureMismatched
**Kind:** Class
**Source:** [`src/utils/jwt/types.ts`](https://github.com/honojs/hono/blob/main/src/utils/jwt/types.ts#L92)
**Part of:** [Utils](subsystem-src-utils)
**Extends:** `Error`
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `TokenHeader` — `src/utils/jwt/jwt.ts`:38
# tryDecodeURI
**Kind:** Function
**Source:** [`src/utils/url.ts`](https://github.com/honojs/hono/blob/main/src/utils/url.ts#L104)
**Part of:** [Utils](subsystem-src-utils)
Try to apply decodeURI() to given string.
If it fails, skip invalid percent encoding or invalid UTF-8 sequences, and apply decodeURI() to the rest as much as possible.
`tryDecodeURI` attempts to decode a URI string with `decodeURI()`. If decoding fails because the input contains invalid percent encoding or invalid UTF-8 sequences, it skips the invalid data and decodes the remaining portions where possible.
## Signature
```ts
function tryDecodeURI(str: string): string
```
## Parameters
| Name | Type |
|---|---|
| `str` | `string` |
**Returns:** `string`
## Diagram
```mermaid
graph LR
Input[URI string] --> Decode[Attempt decodeURI]
Decode -->|Success| Result[Return decoded string]
Decode -->|Failure| Recover[Skip invalid encoding data]
Recover --> Partial[Decode remaining portions]
Partial --> Result
```
## Usage
```ts
import { tryDecodeURI } from './utils/url';
const value = 'https://example.com/search?q=hello%20world%ZZ';
const decoded = tryDecodeURI(value);
console.log(decoded);
// https://example.com/search?q=hello world%ZZ
```
## AI Coding Instructions
- Keep this helper focused on tolerant URI decoding behavior.
- Use `decodeURI()` rather than `decodeURIComponent()` so URI delimiters retain their expected handling.
- Do not throw when malformed percent encoding or invalid UTF-8 data is present.
- Preserve undecodable input data while decoding portions that can be decoded.
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `ServeStaticOptions` — `src/middleware/serve-static/index.ts`:13
# INVALID_IP_ADDRESS_ERROR_CODE
**Kind:** Constant
**Source:** [`src/utils/ipaddr.ts`](https://github.com/honojs/hono/blob/main/src/utils/ipaddr.ts#L41)
**Part of:** [Utils](subsystem-src-utils)
## Definition
```ts
'ERR_INVALID_IP_ADDRESS'
```
## Value
```ts
'ERR_INVALID_IP_ADDRESS'
```
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `IPRestrictionRule` — `src/middleware/ip-restriction/index.ts`:38
# utf8Decoder
**Kind:** Constant
**Source:** [`src/utils/jwt/utf8.ts`](https://github.com/honojs/hono/blob/main/src/utils/jwt/utf8.ts#L7)
**Part of:** [Utils](subsystem-src-utils)
## Definition
```ts
TextDecoder
```
## Value
```ts
new TextDecoder()
```
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `TokenHeader` — `src/utils/jwt/jwt.ts`:38
# createHash
**Kind:** Function
**Source:** [`src/utils/crypto.ts`](https://github.com/honojs/hono/blob/main/src/utils/crypto.ts#L33)
**Part of:** [Utils](subsystem-src-utils)
## Signature
```ts
async function createHash(data: Data, algorithm: Algorithm): Promise
```
## Parameters
| Name | Type |
|---|---|
| `data` | `Data` |
| `algorithm` | `Algorithm` |
**Returns:** `Promise`
# equal
**Kind:** Function
**Source:** [`src/utils/buffer.ts`](https://github.com/honojs/hono/blob/main/src/utils/buffer.ts#L8)
**Part of:** [Utils](subsystem-src-utils)
## Signature
```ts
function equal(a: ArrayBuffer, b: ArrayBuffer): boolean
```
## Parameters
| Name | Type |
|---|---|
| `a` | `ArrayBuffer` |
| `b` | `ArrayBuffer` |
**Returns:** `boolean`
## Relationships
- IMPORTS → `sha256`
# getFilePathWithoutDefaultDocument
**Kind:** Function
**Source:** [`src/utils/filepath.ts`](https://github.com/honojs/hono/blob/main/src/utils/filepath.ts#L32)
**Part of:** [Utils](subsystem-src-utils)
## Signature
```ts
function getFilePathWithoutDefaultDocument(options: Omit): string | undefined
```
## Parameters
| Name | Type |
|---|---|
| `options` | `Omit` |
**Returns:** `string | undefined`
# RequestHeader
**Kind:** Type
**Source:** [`src/utils/headers.ts`](https://github.com/honojs/hono/blob/main/src/utils/headers.ts#L8)
**Part of:** [Utils](subsystem-src-utils)
## Definition
```ts
| 'A-IM' | 'Accept' | 'Accept-Additions' | 'Accept-CH' | 'Accept-Charset' | 'Accept-Datetime' | 'Accept-Encoding' | 'Accept-Features' | 'Accept-Language' | 'Accept-Patch' | 'Accept-Post' | 'Accept-Query' | 'Accept-Ranges' | 'Accept-Signature' | 'Access-Control' | 'Access-Control-Allow-Credentials' | 'Access-Control-Allow-Headers' | 'Access-Control-Allow-Methods' | 'Access-Control-Allow-Origin' | 'Access-Control-Expose-Headers' | 'Access-Control-Max-Age' | 'Access-Control-Request-Headers' | 'Access-Control-Request-Method' | 'Activate-Storage-Access' | 'Age' | 'Allow' | 'ALPN' | 'Alt-Svc' | 'Alt-Used' | 'Alternates' | 'AMP-Cache-Transform' | 'Apply-To-Redirect-Ref' | 'Authentication-Control' | 'Authentication-Info' | 'Authorization' | 'Available-Dictionary' | 'C-Ext' | 'C-Man' | 'C-Opt' | 'C-PEP' | 'C-PEP-Info' | 'Cache-Control' | 'Cache-Group-Invalidation' | 'Cache-Groups' | 'Cache-Status' | 'Cal-Managed-ID' | 'CalDAV-Timezones' | 'Capsule-Protocol' | 'CDN-Cache-Control' | 'CDN-Loop' | 'Cert-Not-After' | 'Cert-Not-Before' | 'Clear-Site-Data' | 'Client-Cert' | 'Client-Cert-Chain' | 'Close' | 'CMCD-Object' | 'CMCD-Request' | 'CMCD-Session' | 'CMCD-Status' | 'CMSD-Dynamic' | 'CMSD-Static' | 'Concealed-Auth-Export' | 'Configuration-Context' | 'Connection' | 'Content-Base' | 'Content-Digest' | 'Content-Disposition' | 'Content-Encoding' | 'Content-ID' | 'Content-Language' | 'Content-Length' | 'Content-Location' | 'Content-MD5' | 'Content-Range' | 'Content-Script-Type' | 'Content-Security-Policy' | 'Content-Security-Policy-Report-Only' | 'Content-Style-Type' | 'Content-Type' | 'Content-Version' | 'Cookie' | 'Cookie2' | 'Cross-Origin-Embedder-Policy' | 'Cross-Origin-Embedder-Policy-Report-Only' | 'Cross-Origin-Opener-Policy' | 'Cross-Origin-Opener-Policy-Report-Only' | 'Cross-Origin-Resource-Policy' | 'CTA-Common-Access-Token' | 'DASL' | 'Date' | 'DAV' | 'Default-Style' | 'Delta-Base' | 'Deprecation' | 'Depth' | 'Derived-From' | 'Destination' | 'Detached-JWS' | 'Differential-ID' | 'Dictionary-ID' | 'Digest' | 'DPoP' | 'DPoP-Nonce' | 'Early-Data' | 'EDIINT-Features' | 'ETag' | 'Expect' | 'Expect-CT' | 'Expires' | 'Ext' | 'Forwarded' | 'From' | 'GetProfile' | 'Hobareg' | 'Host' | 'HTTP2-Settings' | 'If' | 'If-Match' | 'If-Modified-Since' | 'If-None-Match' | 'If-Range' | 'If-Schedule-Tag-Match' | 'If-Unmodified-Since' | 'IM' | 'Include-Referred-Token-Binding-ID' | 'Incremental' | 'Isolation' | 'Keep-Alive' | 'Label' | 'Last-Event-ID' | 'Last-Modified' | 'Link' | 'Link-Template' | 'Location' | 'Lock-Token' | 'Man' | 'Max-Forwards' | 'Memento-Datetime' | 'Meter' | 'Method-Check' | 'Method-Check-Expires' | 'MIME-Version' | 'Negotiate' | 'NEL' | 'OData-EntityId' | 'OData-Isolation' | 'OData-MaxVersion' | 'OData-Version' | 'Opt' | 'Optional-WWW-Authenticate' | 'Ordering-Type' | 'Origin' | 'Origin-Agent-Cluster' | 'OSCORE' | 'OSLC-Core-Version' | 'Overwrite' | 'P3P' | 'PEP' | 'PEP-Info' | 'Permissions-Policy' | 'PICS-Label' | 'Ping-From' | 'Ping-To' | 'Position' | 'Pragma' | 'Prefer' | 'Preference-Applied' | 'Priority' | 'ProfileObject' | 'Protocol' | 'Protocol-Info' | 'Protocol-Query' | 'Protocol-Request' | 'Proxy-Authenticate' | 'Proxy-Authentication-Info' | 'Proxy-Authorization' | 'Proxy-Features' | 'Proxy-Instruction' | 'Proxy-Status' | 'Public' | 'Public-Key-Pins' | 'Public-Key-Pins-Report-Only' | 'Range' | 'Redirect-Ref' | 'Referer' | 'Referer-Root' | 'Referrer-Policy' | 'Refresh' | 'Repeatability-Client-ID' | 'Repeatability-First-Sent' | 'Repeatability-Request-ID' | 'Repeatability-Result' | 'Replay-Nonce' | 'Reporting-Endpoints' | 'Repr-Digest' | 'Retry-After' | 'Safe' | 'Schedule-Reply' | 'Schedule-Tag' | 'Sec-Fetch-Dest' | 'Sec-Fetch-Mode' | 'Sec-Fetch-Site' | 'Sec-Fetch-Storage-Access' | 'Sec-Fetch-User' | 'Sec-GPC' | 'Sec-Purpose' | 'Sec-Token-Binding' | 'Sec-WebSocket-Accept' | 'Sec-WebSocket-Extensions' | 'Sec-WebSocket-Key' | 'Sec-WebSocket-Protocol' | 'Sec-WebSocket-Version' | 'Security-Scheme' | 'Server' | 'Server-Timing' | 'Set…
```
# tryDecode
**Kind:** Function
**Source:** [`src/utils/url.ts`](https://github.com/honojs/hono/blob/main/src/utils/url.ts#L81)
**Part of:** [Utils](subsystem-src-utils)
## Signature
```ts
function tryDecode(str: string, decoder: Decoder): string
```
## Parameters
| Name | Type |
|---|---|
| `str` | `string` |
| `decoder` | `Decoder` |
**Returns:** `string`
# expandIPv6
**Kind:** Function
**Source:** [`src/utils/ipaddr.ts`](https://github.com/honojs/hono/blob/main/src/utils/ipaddr.ts#L13)
**Part of:** [Utils](subsystem-src-utils)
Expand IPv6 Address
`expandIPv6` expands an IPv6 address that uses compressed notation into its expanded colon-separated form. It is used by IP address handling code when later operations need each address segment represented explicitly.
## Signature
```ts
function expandIPv6(ipV6: string): string
```
## Parameters
| Name | Type |
|---|---|
| `ipV6` | `string` |
**Returns:** `string`
## Diagram
```mermaid
graph LR
A[Compressed IPv6 address] --> B[expandIPv6]
B --> C[Split address segments]
C --> D[Expand omitted segments]
D --> E[Expanded IPv6 address]
```
## Usage
```ts
import { expandIPv6 } from './utils/ipaddr';
const address = 'a::b';
const expandedAddress = expandIPv6(address);
console.log(expandedAddress);
```
## AI Coding Instructions
- Pass IPv6 address strings to `expandIPv6` before code that requires explicit address segments.
- Keep compressed-address handling inside this utility rather than duplicating expansion logic in callers.
- Preserve colon-separated IPv6 formatting when changing this function.
- Check how callers handle invalid or already-expanded addresses before changing return behavior.
# getFilePath
**Kind:** Function
**Source:** [`src/utils/filepath.ts`](https://github.com/honojs/hono/blob/main/src/utils/filepath.ts#L12)
**Part of:** [Utils](subsystem-src-utils)
## Signature
```ts
function getFilePath(options: FilePathOptions): string | undefined
```
## Parameters
| Name | Type |
|---|---|
| `options` | `FilePathOptions` |
**Returns:** `string | undefined`
# decodeHeader
**Kind:** Function
**Source:** [`src/utils/jwt/jwt.ts`](https://github.com/honojs/hono/blob/main/src/utils/jwt/jwt.ts#L281)
**Part of:** [Utils](subsystem-src-utils)
## Signature
```ts
function decodeHeader(token: string): TokenHeader
```
## Parameters
| Name | Type |
|---|---|
| `token` | `string` |
**Returns:** `TokenHeader`
# isTokenHeader
**Kind:** Function
**Source:** [`src/utils/jwt/jwt.ts`](https://github.com/honojs/hono/blob/main/src/utils/jwt/jwt.ts#L44)
**Part of:** [Utils](subsystem-src-utils)
## Signature
```ts
function isTokenHeader(obj: unknown): obj is TokenHeader
```
## Parameters
| Name | Type |
|---|---|
| `obj` | `unknown` |
**Returns:** `obj is TokenHeader`
# ResponseHeader
**Kind:** Type
**Source:** [`src/utils/headers.ts`](https://github.com/honojs/hono/blob/main/src/utils/headers.ts#L266)
**Part of:** [Utils](subsystem-src-utils)
## Definition
```ts
| 'Accept-Query' | 'Access-Control-Allow-Credentials' | 'Access-Control-Allow-Headers' | 'Access-Control-Allow-Methods' | 'Access-Control-Allow-Origin' | 'Access-Control-Expose-Headers' | 'Access-Control-Max-Age' | 'Activate-Storage-Access' | 'Age' | 'Allow' | 'Cache-Control' | 'Cache-Group-Invalidation' | 'Cache-Groups' | 'Clear-Site-Data' | 'Content-Disposition' | 'Content-Encoding' | 'Content-Language' | 'Content-Length' | 'Content-Location' | 'Content-Range' | 'Content-Security-Policy' | 'Content-Security-Policy-Report-Only' | 'Content-Type' | 'Cookie' | 'Cross-Origin-Embedder-Policy' | 'Cross-Origin-Opener-Policy' | 'Cross-Origin-Resource-Policy' | 'Date' | 'ETag' | 'Expires' | 'Incremental' | 'Last-Modified' | 'Location' | 'Permissions-Policy' | 'Pragma' | 'Retry-After' | 'Save-Data' | 'Sec-CH-Prefers-Color-Scheme' | 'Sec-CH-Prefers-Reduced-Motion' | 'Sec-CH-UA' | 'Sec-CH-UA-Arch' | 'Sec-CH-UA-Bitness' | 'Sec-CH-UA-Form-Factor' | 'Sec-CH-UA-Full-Version' | 'Sec-CH-UA-Full-Version-List' | 'Sec-CH-UA-Mobile' | 'Sec-CH-UA-Model' | 'Sec-CH-UA-Platform' | 'Sec-CH-UA-Platform-Version' | 'Sec-CH-UA-WoW64' | 'Sec-Fetch-Dest' | 'Sec-Fetch-Mode' | 'Sec-Fetch-Site' | 'Sec-Fetch-User' | 'Sec-GPC' | 'Server' | 'Server-Timing' | 'Service-Worker-Navigation-Preload' | 'Set-Cookie' | 'Set-Txn' | 'Strict-Transport-Security' | 'Timing-Allow-Origin' | 'Trailer' | 'Transfer-Encoding' | 'Unencoded-Digest' | 'Upgrade' | 'Vary' | 'Want-Unencoded-Digest' | 'Warning' | 'WWW-Authenticate' | 'X-Content-Type-Options' | 'X-DNS-Prefetch-Control' | 'X-Frame-Options' | 'X-Permitted-Cross-Domain-Policies' | 'X-Powered-By' | 'X-Robots-Tag' | 'X-XSS-Protection'
```
# bufferToString
**Kind:** Function
**Source:** [`src/utils/buffer.ts`](https://github.com/honojs/hono/blob/main/src/utils/buffer.ts#L98)
**Part of:** [Utils](subsystem-src-utils)
## Signature
```ts
function bufferToString(buffer: ArrayBuffer): string
```
## Parameters
| Name | Type |
|---|---|
| `buffer` | `ArrayBuffer` |
**Returns:** `string`
# convertIPv4BinaryToString
**Kind:** Function
**Source:** [`src/utils/ipaddr.ts`](https://github.com/honojs/hono/blob/main/src/utils/ipaddr.ts#L300)
**Part of:** [Utils](subsystem-src-utils)
Convert a binary representation of an IPv4 address to a string.
`convertIPv4BinaryToString` converts a binary IPv4 address representation into its string form. Use it at boundaries where binary address data must be displayed, logged, serialized, or passed to string-based APIs.
## Signature
```ts
function convertIPv4BinaryToString(ipV4: bigint): string
```
## Parameters
| Name | Type |
|---|---|
| `ipV4` | `bigint` |
**Returns:** `string`
## Diagram
```mermaid
graph LR
A[Binary IPv4 input] --> B[convertIPv4BinaryToString]
B --> C[IPv4 string output]
```
## Usage
```ts
import { convertIPv4BinaryToString } from './utils/ipaddr';
type BinaryIPv4 = Parameters[0];
function formatAddress(binaryAddress: BinaryIPv4): string {
return convertIPv4BinaryToString(binaryAddress);
}
```
## AI Coding Instructions
- Pass input in the binary format expected by `convertIPv4BinaryToString`; do not pass an already formatted address string.
- Keep binary-to-string conversion near display, logging, serialization, or API boundaries.
- Treat the return value as an IPv4 string suitable for string-based consumers.
- Do not assume malformed binary input is validated unless the implementation explicitly checks it.
# ClientErrorStatusCode
**Kind:** Type
**Source:** [`src/utils/http-status.ts`](https://github.com/honojs/hono/blob/main/src/utils/http-status.ts#L10)
**Part of:** [Utils](subsystem-src-utils)
## Definition
```ts
| 400 | 401 | 402 | 403 | 404 | 405 | 406 | 407 | 408 | 409 | 410 | 411 | 412 | 413 | 414 | 415 | 416 | 417 | 418 | 421 | 422 | 423 | 424 | 425 | 426 | 428 | 429 | 431 | 451
```
# JSONParsed
**Kind:** Type
**Source:** [`src/utils/types.ts`](https://github.com/honojs/hono/blob/main/src/utils/types.ts#L53)
**Part of:** [Utils](subsystem-src-utils)
Convert a type to a JSON-compatible type.
Non-JSON values such as `Date` implement `.toJSON()`,
so they can be transformed to a value assignable to `JSONObject`
`JSON.stringify()` throws a `TypeError` when it encounters a `bigint` value,
unless a custom `replacer` function or `.toJSON()` method is provided.
This behaviour can be controlled by the `TError` generic type parameter,
which defaults to `bigint | ReadonlyArray`.
You can set it to `never` to disable this check.
`JSONParsed` maps a TypeScript type to the shape produced by JSON serialization. Values with a `.toJSON()` method, such as `Date`, are converted through that method, while `bigint` values are rejected by default because `JSON.stringify()` throws for them.
## Definition
```ts
T extends { toJSON(): infer J } ? (() => J) extends () => JSONPrimitive ? J : (() => J) extends () => { toJSON(): unknown } ? {} : JSONParsed : T extends JSONPrimitive ? T : T extends InvalidJSONValue ? never : T extends ReadonlyArray ? { [K in keyof T]: JSONParsed, TError> } extends infer A ? A extends ReadonlyArray ? A : JSONParsed, TError>[] : never : T extends Set | Map | Record ? {} : T extends object ? T[keyof T] extends TError ? never : { [K in keyof OmitSymbolKeys as IsInvalid extends true ? never : K]: boolean extends IsInvalid ? JSONParsed | undefined : JSONParsed } : T extends unknown ? T extends TError ? never : JSONValue : never
```
## Diagram
```mermaid
graph LR
T[Input type T] --> P[JSONParsed]
P --> J[JSON-compatible type]
D[Date or value with toJSON()] --> J
B[bigint value] --> E[TError check]
E -->|default| R[Rejected]
E -->|TError = never| J
```
## Usage
```ts
import type { JSONParsed } from "./utils/types";
type Input = {
createdAt: Date;
tags: readonly string[];
};
type SerializedInput = JSONParsed;
const value: SerializedInput = {
createdAt: new Date().toJSON(),
tags: ["release"],
};
declare const source: { total: bigint };
// bigint is checked by default.
type CheckedValue = JSONParsed;
// Disable the bigint check when serialization is handled separately.
type AllowedValue = JSONParsed;
```
## AI Coding Instructions
- Use `JSONParsed` for types representing data after JSON serialization.
- Expect values with `.toJSON()` methods to resolve to their JSON return type.
- Keep the default `TError` setting when `bigint` values should be rejected.
- Set `TError` to `never` only when `bigint` serialization is handled with a replacer or custom `.toJSON()` method.
# ParseBodyOptions
**Kind:** Type
**Source:** [`src/utils/body.ts`](https://github.com/honojs/hono/blob/main/src/utils/body.ts#L43)
**Part of:** [Utils](subsystem-src-utils)
## Definition
```ts
{ all: boolean dot: boolean }
```
# sha1
**Kind:** Function
**Source:** [`src/utils/crypto.ts`](https://github.com/honojs/hono/blob/main/src/utils/crypto.ts#L21)
**Part of:** [Utils](subsystem-src-utils)
## Signature
```ts
async function sha1(data: Data): Promise
```
## Parameters
| Name | Type |
|---|---|
| `data` | `Data` |
**Returns:** `Promise`
# getQueryStrings
**Kind:** Function
**Source:** [`src/utils/url.ts`](https://github.com/honojs/hono/blob/main/src/utils/url.ts#L136)
**Part of:** [Utils](subsystem-src-utils)
## Signature
```ts
function getQueryStrings(url: string): string
```
## Parameters
| Name | Type |
|---|---|
| `url` | `string` |
**Returns:** `string`
# JWTPayload
**Kind:** Type
**Source:** [`src/utils/jwt/types.ts`](https://github.com/honojs/hono/blob/main/src/utils/jwt/types.ts#L131)
**Part of:** [Utils](subsystem-src-utils)
JWT Payload
`JWTPayload` describes the decoded payload data carried by a JSON Web Token. JWT parsing, validation, and authorization code can use this type to pass token claims through the application with a shared shape.
## Definition
```ts
{ [key: string]: unknown exp?: number nbf?: number iat?: number iss?: string aud?: string | string[] }
```
## Diagram
```mermaid
graph LR
Token[JWT] -->|decode and validate| Payload[JWTPayload]
Payload --> Auth[Authorization logic]
Payload --> Request[Request context]
```
## Usage
```ts
import type { JWTPayload } from './utils/jwt/types';
declare function getVerifiedPayload(request: Request): JWTPayload;
function authorizeRequest(request: Request) {
const payload = getVerifiedPayload(request);
// Read claims declared by JWTPayload before making access decisions.
return payload;
}
```
## AI Coding Instructions
- Import `JWTPayload` with `import type` when it is only used for TypeScript checking.
- Only create a `JWTPayload` after the JWT has been decoded and validated.
- Keep claim access aligned with the fields declared in `src/utils/jwt/types.ts`.
- Do not treat decoded payload data as trusted until JWT signature and expiry checks have completed.
# Pool
**Kind:** Interface
**Source:** [`src/utils/concurrent.ts`](https://github.com/honojs/hono/blob/main/src/utils/concurrent.ts#L8)
**Part of:** [Utils](subsystem-src-utils)
`Pool` defines an asynchronous work contract that returns a value of type `T`. Its `run` method lets concurrency code invoke pooled work through a shared `Promise`-based interface.
## Diagram
```mermaid
graph LR
Caller[Caller] --> Pool[Pool]
Pool --> Run[run()]
Run --> Result[Promise]
```
## Usage
```ts
async function execute(pool: Pool): Promise {
return pool.run();
}
declare const taskPool: Pool;
const result = await execute(taskPool);
console.log(result);
```
## AI Coding Instructions
- Treat `run` as asynchronous and await or return its `Promise`.
- Preserve the generic `T` type when passing a `Pool` between functions.
- Implement `run` so it resolves with the expected result type.
- Handle rejected promises at the caller or at the integration boundary.
## How it works
`Pool` is an exported TypeScript interface for an object that runs a zero-argument callback and returns a `Promise` for the callback’s result. Its sole member is the generic `run(fn: () => T): Promise` method. [src/utils/concurrent.ts:8-10]
`createPool()` returns this interface and implements its concurrency behavior. It defaults an omitted or falsy `concurrency` value to `1024`; a concurrency value of `Infinity` returns a `Pool` whose `run` method immediately invokes the callback through an async function, without tracking active work. [src/utils/concurrent.ts:6,12-25]
For finite concurrency, each started callback occupies a marker in an internal `Set`. When the active-marker count is at least the configured limit, `run` creates or reuses a result promise, schedules another attempt with `setTimeout`, and returns that promise without invoking the callback yet. [src/utils/concurrent.ts:28-40] Once a callback can start, `run` awaits it and returns its result. [src/utils/concurrent.ts:39-52] Tests invoke multiple `run` calls and verify that only up to the configured concurrency are running before the blocked callbacks are released. [src/utils/concurrent.test.ts:13-37]
When `createPool` receives a truthy `interval`, a completed callback’s marker remains in the active set until a timer deletes it after that many milliseconds; otherwise, the marker is deleted immediately after the callback resolves. [src/utils/concurrent.ts:41-46] Consequently, the interval delays later callbacks after completion, and the tests check that groups of callbacks begin at least approximately one interval apart. [src/utils/concurrent.test.ts:40-67]
The visible implementation has no input validation for the callback, concurrency, or interval. [src/utils/concurrent.ts:8-18] It also does not catch callback failures: if `await fn()` throws or rejects, execution exits before marker deletion, so the occupied marker remains in the finite pool. [src/utils/concurrent.ts:39-46]
# AsymmetricAlgorithm
**Kind:** Type
**Source:** [`src/utils/jwt/jwa.ts`](https://github.com/honojs/hono/blob/main/src/utils/jwt/jwa.ts#L27)
**Part of:** [Utils](subsystem-src-utils)
## Definition
```ts
| 'RS256' | 'RS384' | 'RS512' | 'PS256' | 'PS384' | 'PS512' | 'ES256' | 'ES384' | 'ES512' | 'EdDSA'
```
# CookieOptions
**Kind:** Type
**Source:** [`src/utils/cookie.ts`](https://github.com/honojs/hono/blob/main/src/utils/cookie.ts#L17)
**Part of:** [Utils](subsystem-src-utils)
## Definition
```ts
{ domain?: string expires?: Date httpOnly?: boolean maxAge?: number path?: string secure?: boolean sameSite?: 'Strict' | 'Lax' | 'None' | 'strict' | 'lax' | 'none' partitioned?: boolean priority?: 'Low' | 'Medium' | 'High' | 'low' | 'medium' | 'high' prefix?: CookiePrefixOptions } & PartitionedCookieConstraint
```
# VerifyOptions
**Kind:** Type
**Source:** [`src/utils/jwt/jwt.ts`](https://github.com/honojs/hono/blob/main/src/utils/jwt/jwt.ts#L78)
**Part of:** [Utils](subsystem-src-utils)
## Definition
```ts
{ iss?: string | RegExp nbf?: boolean exp?: boolean iat?: boolean aud?: string | string[] | RegExp }
```
# AcceptHeader
**Kind:** Type
**Source:** [`src/utils/headers.ts`](https://github.com/honojs/hono/blob/main/src/utils/headers.ts#L345)
**Part of:** [Utils](subsystem-src-utils)
## Definition
```ts
| 'Accept' | 'Accept-Charset' | 'Accept-Encoding' | 'Accept-Language' | 'Accept-Patch' | 'Accept-Post' | 'Accept-Ranges'
```
# RequiredKeysOf
**Kind:** Type
**Source:** [`src/utils/types.ts`](https://github.com/honojs/hono/blob/main/src/utils/types.ts#L104)
**Part of:** [Utils](subsystem-src-utils)
## Definition
```ts
Exclude< { [Key in keyof BaseType]: BaseType extends Record ? Key : never }[keyof BaseType], undefined >
```
# StatusCode
**Kind:** Type
**Source:** [`src/utils/http-status.ts`](https://github.com/honojs/hono/blob/main/src/utils/http-status.ts#L63)
**Part of:** [Utils](subsystem-src-utils)
If you want to use an unofficial status, use `UnofficialStatusCode`.
`StatusCode` represents the set of supported official HTTP status codes in the HTTP utilities module. Use it when APIs accept or return standard status values; use `UnofficialStatusCode` when an unofficial status is required.
## Definition
```ts
| InfoStatusCode | SuccessStatusCode | RedirectStatusCode | ClientErrorStatusCode | ServerErrorStatusCode | UnofficialStatusCode
```
## Diagram
```mermaid
graph LR
Response[HTTP response] --> StatusCode[StatusCode]
StatusCode --> Official[Official HTTP status]
Unofficial[Unofficial status] --> UnofficialStatusCode[UnofficialStatusCode]
```
## Usage
```ts
import type { StatusCode } from "./utils/http-status";
function setResponseStatus(status: StatusCode) {
return { status };
}
declare const statusFromHandler: StatusCode;
const response = setResponseStatus(statusFromHandler);
```
## AI Coding Instructions
- Use `StatusCode` for standard HTTP status values exposed by handlers, responses, and middleware.
- Use `UnofficialStatusCode` instead of widening `StatusCode` when working with an unofficial status.
- Keep status-related function parameters typed as `StatusCode` when unofficial values are not supported.
- Treat `StatusCode` as a type-only constraint; perform runtime validation at input boundaries when status values come from external data.
# Accept
**Kind:** Interface
**Source:** [`src/utils/accept.ts`](https://github.com/honojs/hono/blob/main/src/utils/accept.ts#L1)
**Part of:** [Utils](subsystem-src-utils)
`Accept` represents a parsed media type from an HTTP `Accept` header. It stores the media `type`, associated parameters, and the `q` quality value used when selecting a preferred response format.
## Properties
| Property | Type |
|---|---|
| `type` | `string` |
| `params` | `Record` |
| `q` | `number` |
## Diagram
```mermaid
graph LR
Header[HTTP Accept header] --> Accept[Accept]
Accept --> Type[type: string]
Accept --> Params[params: Record<string, string>]
Accept --> Quality[q: number]
```
## Usage
```ts
import type { Accept } from "./utils/accept";
const acceptedType: Accept = {
type: "application/json",
params: {
charset: "utf-8",
},
q: 1,
};
if (acceptedType.type === "application/json" && acceptedType.q > 0) {
console.log("Return a JSON response");
}
```
## AI Coding Instructions
- Treat `type` as the parsed media type, such as `application/json` or `text/html`.
- Store media-type parameters in `params` as string key-value pairs.
- Use `q` when comparing acceptable response formats; higher values indicate higher preference.
- Preserve parsed parameter values as strings rather than coercing them to other types.
- Keep this interface aligned with the `Accept` header parsing and response content-negotiation code.
# CookieConstraint
**Kind:** Type
**Source:** [`src/utils/cookie.ts`](https://github.com/honojs/hono/blob/main/src/utils/cookie.ts#L31)
**Part of:** [Utils](subsystem-src-utils)
## Definition
```ts
Name extends `__Secure-${string}` ? CookieOptions & SecureCookieConstraint : Name extends `__Host-${string}` ? CookieOptions & HostCookieConstraint : CookieOptions
```
# TokenHeader
**Kind:** Interface
**Source:** [`src/utils/jwt/jwt.ts`](https://github.com/honojs/hono/blob/main/src/utils/jwt/jwt.ts#L38)
**Part of:** [Utils](subsystem-src-utils)
`TokenHeader` defines the header data for a JWT token. It identifies the signing algorithm, fixes the token type as `'JWT'`, and includes a key identifier for key selection during verification.
## Properties
| Property | Type |
|---|---|
| `alg` | `SignatureAlgorithm` |
| `typ` | `'JWT'` |
| `kid` | `string` |
## Diagram
```mermaid
graph LR
Header[TokenHeader] --> Algorithm[alg: SignatureAlgorithm]
Header --> Type[typ: JWT]
Header --> KeyId[kid: string]
Header --> Token[JWT header]
```
## Usage
```ts
import type { TokenHeader } from './utils/jwt/jwt';
import type { SignatureAlgorithm } from './utils/jwt/jwa';
declare function getSigningAlgorithm(): SignatureAlgorithm;
const header: TokenHeader = {
alg: getSigningAlgorithm(),
typ: 'JWT',
kid: 'active-signing-key',
};
```
## AI Coding Instructions
- Set `typ` to the exact literal `'JWT'`.
- Supply an `alg` value that matches the signing or verification configuration.
- Set `kid` to the identifier expected by the key lookup process.
- Keep header construction aligned with the JWT signing and verification code paths.
## How it works
`TokenHeader` is an exported TypeScript interface for the decoded or constructed header portion of a JWT. It declares a required `alg` signature-algorithm field, plus optional `typ` and `kid` fields. [`src/utils/jwt/jwt.ts:38-42`](src/utils/jwt/jwt.ts#L38-L42)
- `alg` must have the `SignatureAlgorithm` type. That type accepts `HS256`, `HS384`, `HS512`, `RS256`, `RS384`, `RS512`, `PS256`, `PS384`, `PS512`, `ES256`, `ES384`, `ES512`, or `EdDSA`. [`src/utils/jwt/jwa.ts:7-23`](src/utils/jwt/jwa.ts#L7-L23)
- `typ`, when present, is the literal string `'JWT'`; `kid`, when present, is a string. [`src/utils/jwt/jwt.ts:38-42`](src/utils/jwt/jwt.ts#L38-L42)
JWT signing constructs a header with the selected algorithm and `typ: 'JWT'`. When the signing key is an object containing `alg`, signing replaces the function’s algorithm argument with that key’s `alg` value and also places the key’s `kid` value in the header. The header is JSON-serialized, UTF-8 encoded, Base64URL encoded, and becomes the first dot-separated token part. [`src/utils/jwt/jwt.ts:31-32`](src/utils/jwt/jwt.ts#L31-L32) [`src/utils/jwt/jwt.ts:56-75`](src/utils/jwt/jwt.ts#L56-L75)
`isTokenHeader` is the runtime type guard associated with this interface. It returns `true` only for a non-null object that has an `alg` property whose value occurs in `AlgorithmTypes`, and whose `typ` property is either absent or exactly `'JWT'`. [`src/utils/jwt/jwt.ts:44-54`](src/utils/jwt/jwt.ts#L44-L54) It does not check that `kid` is a string, and it does not reject additional properties; its checks are limited to `alg` and `typ`. [`src/utils/jwt/jwt.ts:45-51`](src/utils/jwt/jwt.ts#L45-L51)
Decoded headers are cast to `TokenHeader` after Base64URL decoding and JSON parsing; `decode` and `decodeHeader` only reject tokens that do not have exactly three parts or whose decoding/parsing throws. Neither function calls `isTokenHeader`. [`src/utils/jwt/jwt.ts:264-290`](src/utils/jwt/jwt.ts#L264-L290)
Signature verification calls `isTokenHeader` and throws `JwtHeaderInvalid` when the decoded header fails that guard. It then requires `header.alg` to equal the caller-selected algorithm, throwing `JwtAlgorithmMismatch` otherwise. [`src/utils/jwt/jwt.ts:123-129`](src/utils/jwt/jwt.ts#L123-L129) JWK-set verification also validates the header, requires a truthy `kid` or throws `JwtHeaderRequiresKid`, rejects symmetric header algorithms, and requires the header algorithm to occur in `options.allowedAlgorithms`. [`src/utils/jwt/jwt.ts:209-225`](src/utils/jwt/jwt.ts#L209-L225)
## Relationships
- IMPORTS → `decodeBase64Url`
- IMPORTS → `encodeBase64Url`
- IMPORTS → `AlgorithmTypes`
- IMPORTS → `signing`
- IMPORTS → `verifying`
- IMPORTS → `JwtAlgorithmMismatch`
- IMPORTS → `JwtAlgorithmNotAllowed`
- IMPORTS → `JwtAlgorithmRequired`
- IMPORTS → `JwtHeaderInvalid`
- IMPORTS → `JwtHeaderRequiresKid`
- IMPORTS → `JwtPayloadRequiresAud`
- IMPORTS → `JwtSymmetricAlgorithmNotAllowed`
- IMPORTS → `JwtTokenAudience`
- IMPORTS → `JwtTokenExpired`
- IMPORTS → `JwtTokenInvalid`
- IMPORTS → `JwtTokenIssuedAt`
- IMPORTS → `JwtTokenIssuer`
- IMPORTS → `JwtTokenNotBefore`
- IMPORTS → `JwtTokenSignatureMismatched`
- IMPORTS → `utf8Decoder`
- IMPORTS → `utf8Encoder`
# UnionToIntersection
**Kind:** Type
**Source:** [`src/utils/types.ts`](https://github.com/honojs/hono/blob/main/src/utils/types.ts#L12)
**Part of:** [Utils](subsystem-src-utils)
## Definition
```ts
(U extends any ? (k: U) => void : never) extends ( k: infer I ) => void ? I : never
```
# HtmlEscaped
**Kind:** Type
**Source:** [`src/utils/html.ts`](https://github.com/honojs/hono/blob/main/src/utils/html.ts#L17)
**Part of:** [Utils](subsystem-src-utils)
## Definition
```ts
{ isEscaped: true callbacks?: HtmlEscapedCallback[] }
```
# VerifyOptionsWithAlg
**Kind:** Type
**Source:** [`src/utils/jwt/jwt.ts`](https://github.com/honojs/hono/blob/main/src/utils/jwt/jwt.ts#L91)
**Part of:** [Utils](subsystem-src-utils)
## Definition
```ts
{ alg: SignatureAlgorithm } & VerifyOptions
```
# BodyData
**Kind:** Type
**Source:** [`src/utils/body.ts`](https://github.com/honojs/hono/blob/main/src/utils/body.ts#L39)
**Part of:** [Utils](subsystem-src-utils)
## Definition
```ts
SimplifyBodyData< Record> >
```
## Relationships
- IMPORTS → `bufferToFormData`
# HonoJsonWebKey
**Kind:** Interface
**Source:** [`src/utils/jwt/jws.ts`](https://github.com/honojs/hono/blob/main/src/utils/jwt/jws.ts#L23)
**Part of:** [Utils](subsystem-src-utils)
`HonoJsonWebKey` represents a JSON Web Key with a required `kid` property. The key identifier lets JWT handling code select the matching key from a key set when processing a token.
## Properties
| Property | Type |
|---|---|
| `kid` | `string` |
## Diagram
```mermaid
graph LR
JWT[JWT header] --> KID[kid]
KID --> JWK[HonoJsonWebKey]
JWK --> Verify[JWT verification]
```
## Usage
```ts
import type { HonoJsonWebKey } from 'hono/utils/jwt/jws'
const signingKey = {
kid: 'active-signing-key',
} as HonoJsonWebKey
const keys: HonoJsonWebKey[] = [signingKey]
const key = keys.find((candidate) => candidate.kid === 'active-signing-key')
```
## AI Coding Instructions
- Set `kid` to the identifier expected by the JWT header.
- Keep `kid` values unique within a key set.
- Preserve the remaining JSON Web Key fields when passing keys to JWT signing or verification code.
- Match keys by `kid` before importing them for cryptographic operations.
## How it works
`HonoJsonWebKey` is an exported TypeScript interface that extends the platform `JsonWebKey` type with an optional string `kid` property. [`src/utils/jwt/jws.ts:21-25`](src/utils/jwt/jws.ts#L21-L25)
It has no runtime implementation, validation, error path, or direct side effect of its own; it is a type declaration. [`src/utils/jwt/jws.ts:23-25`](src/utils/jwt/jws.ts#L23-L25)
It is one accepted member of `SignatureKey`, alongside a string or `CryptoKey`, so it can be passed to JWT signing and verification routines. [`src/utils/jwt/jws.ts:27-37`](src/utils/jwt/jws.ts#L27-L37) [`src/utils/jwt/jws.ts:39-48`](src/utils/jwt/jws.ts#L39-L48) When such an object is imported as a signing or verification key, the code passes it to Web Crypto as a JWK with `crypto.subtle.importKey('jwk', ...)`; import failures are propagated by the awaited Web Crypto call. [`src/utils/jwt/jws.ts:66-75`](src/utils/jwt/jws.ts#L66-L75) [`src/utils/jwt/jws.ts:95-104`](src/utils/jwt/jws.ts#L95-L104)
For `Jwt.sign`, if the supplied key is an object containing `alg`, its `alg` value selects the signing algorithm and its `kid` value is written into the JWT header. [`src/utils/jwt/jwt.ts:56-75`](src/utils/jwt/jwt.ts#L56-L75)
For JWKS verification, `verifyWithJwks` accepts an array of `HonoJsonWebKey` values, requires the decoded token header to contain `kid`, and selects the first key whose `kid` strictly equals the header’s `kid`. [`src/utils/jwt/jwt.ts:197-216`](src/utils/jwt/jwt.ts#L197-L216) [`src/utils/jwt/jwt.ts:228-251`](src/utils/jwt/jwt.ts#L228-L251) If no matching key exists, it throws `JwtTokenInvalid`; if the selected key declares `alg` and it differs from the JWT header algorithm, it throws `JwtAlgorithmMismatch`. [`src/utils/jwt/jwt.ts:248-256`](src/utils/jwt/jwt.ts#L248-L256)
## Relationships
- IMPORTS → `getRuntimeKey`
- IMPORTS → `decodeBase64`
- IMPORTS → `CryptoKeyUsage`
- IMPORTS → `JwtAlgorithmNotImplemented`
- IMPORTS → `utf8Encoder`
# InvalidIPAddressError
**Kind:** Type
**Source:** [`src/utils/ipaddr.ts`](https://github.com/honojs/hono/blob/main/src/utils/ipaddr.ts#L42)
**Part of:** [Utils](subsystem-src-utils)
## Definition
```ts
TypeError & { code: typeof INVALID_IP_ADDRESS_ERROR_CODE }
```
# JSONObject
**Kind:** Type
**Source:** [`src/utils/types.ts`](https://github.com/honojs/hono/blob/main/src/utils/types.ts#L25)
**Part of:** [Utils](subsystem-src-utils)
## Definition
```ts
{ [key: string]: JSONPrimitive | JSONArray | JSONObject | object | InvalidJSONValue }
```
# SimplifyDeepArray
**Kind:** Type
**Source:** [`src/utils/types.ts`](https://github.com/honojs/hono/blob/main/src/utils/types.ts#L98)
**Part of:** [Utils](subsystem-src-utils)
A simple extension of Simplify that will deeply traverse array elements.
`SimplifyDeepArray` extends `Simplify` by recursively processing array element types. It preserves the array structure while simplifying each non-array element type, making nested array types easier to inspect and consume.
## Definition
```ts
T extends any[] ? { [E in keyof T]: SimplifyDeepArray } : Simplify
```
## Diagram
```mermaid
graph LR
Input[Input type] --> Check{Is an array?}
Check -->|Yes| Recurse[Apply SimplifyDeepArray to element type]
Recurse --> Array[Return array of simplified elements]
Check -->|No| Simplify[Apply Simplify]
```
## Usage
```ts
type ApiRecord = {
id: string;
metadata: {
createdBy: string;
};
};
type NestedRecords = ApiRecord[][];
type SimplifiedRecords = SimplifyDeepArray;
// SimplifiedRecords is:
// Array>
```
## AI Coding Instructions
- Use `SimplifyDeepArray` when a type may contain nested arrays whose element types need simplification.
- Keep the recursive array check before applying `Simplify` to non-array values.
- Do not replace array element recursion with a shallow `Simplify`, or nested array elements will remain unsimplified.
- Use `SimplifyDeepArray` for type-level readability only; it does not transform runtime values.
# Equal
**Kind:** Type
**Source:** [`src/utils/types.ts`](https://github.com/honojs/hono/blob/main/src/utils/types.ts#L8)
**Part of:** [Utils](subsystem-src-utils)
## Definition
```ts
(() => T extends X ? 1 : 2) extends () => T extends Y ? 1 : 2 ? true : false
```
# HasRequiredKeys
**Kind:** Type
**Source:** [`src/utils/types.ts`](https://github.com/honojs/hono/blob/main/src/utils/types.ts#L111)
**Part of:** [Utils](subsystem-src-utils)
## Definition
```ts
RequiredKeysOf extends never ? false : true
```
# RemoveBlankRecord
**Kind:** Type
**Source:** [`src/utils/types.ts`](https://github.com/honojs/hono/blob/main/src/utils/types.ts#L18)
**Part of:** [Utils](subsystem-src-utils)
## Definition
```ts
T extends Record ? (K extends string ? T : never) : never
```
# Auth
**Kind:** Type
**Source:** [`src/utils/basic-auth.ts`](https://github.com/honojs/hono/blob/main/src/utils/basic-auth.ts#L7)
**Part of:** [Utils](subsystem-src-utils)
## Definition
```ts
(req: Request) => { username: string; password: string } | undefined
```
## Relationships
- IMPORTS → `decodeBase64`
# BaseMime
**Kind:** Type
**Source:** [`src/utils/mime.ts`](https://github.com/honojs/hono/blob/main/src/utils/mime.ts#L33)
**Part of:** [Utils](subsystem-src-utils)
Union types for BaseMime
`BaseMime` is a union type that represents the base MIME values defined in `src/utils/mime.ts`. It constrains APIs and variables that work with those MIME values so callers can pass only members of the union.
## Definition
```ts
(typeof _baseMimes)[keyof typeof _baseMimes]
```
## Diagram
```mermaid
graph LR
Input[Content-Type value] --> BaseMime[BaseMime]
BaseMime --> Headers[HTTP headers]
BaseMime --> Validation[Type-safe MIME handling]
```
## Usage
```ts
import type { BaseMime } from './utils/mime';
function createHeaders(mime: BaseMime) {
return {
'Content-Type': mime,
};
}
declare const mime: BaseMime;
const headers = createHeaders(mime);
```
## AI Coding Instructions
- Import `BaseMime` with `import type` when it is only used as a TypeScript type.
- Use `BaseMime` for function parameters, configuration fields, and header builders that accept base MIME values.
- Keep MIME literals aligned with the union declared in `src/utils/mime.ts`.
- Do not cast arbitrary strings to `BaseMime`; validate external input before passing it to typed APIs.
# ContentfulStatusCode
**Kind:** Type
**Source:** [`src/utils/http-status.ts`](https://github.com/honojs/hono/blob/main/src/utils/http-status.ts#L72)
**Part of:** [Utils](subsystem-src-utils)
## Definition
```ts
Exclude
```
# ContentlessStatusCode
**Kind:** Type
**Source:** [`src/utils/http-status.ts`](https://github.com/honojs/hono/blob/main/src/utils/http-status.ts#L71)
**Part of:** [Utils](subsystem-src-utils)
## Definition
```ts
101 | 204 | 205 | 304
```
# Cookie
**Kind:** Type
**Source:** [`src/utils/cookie.ts`](https://github.com/honojs/hono/blob/main/src/utils/cookie.ts#L8)
**Part of:** [Utils](subsystem-src-utils)
## Definition
```ts
Record
```
## Relationships
- IMPORTS → `tryDecodeURIComponent`
# CookiePrefixOptions
**Kind:** Type
**Source:** [`src/utils/cookie.ts`](https://github.com/honojs/hono/blob/main/src/utils/cookie.ts#L29)
**Part of:** [Utils](subsystem-src-utils)
## Definition
```ts
'host' | 'secure'
```
# CustomHeader
**Kind:** Type
**Source:** [`src/utils/headers.ts`](https://github.com/honojs/hono/blob/main/src/utils/headers.ts#L355)
**Part of:** [Utils](subsystem-src-utils)
## Definition
```ts
string & {}
```
# decodeURIComponent_
**Kind:** Constant
**Source:** [`src/utils/url.ts`](https://github.com/honojs/hono/blob/main/src/utils/url.ts#L319)
**Part of:** [Utils](subsystem-src-utils)
## Definition
```ts
decodeURIComponent
```
## Value
```ts
decodeURIComponent
```
# DeprecatedStatusCode
**Kind:** Type
**Source:** [`src/utils/http-status.ts`](https://github.com/honojs/hono/blob/main/src/utils/http-status.ts#L8)
**Part of:** [Utils](subsystem-src-utils)
## Definition
```ts
305 | 306
```
# Expect
**Kind:** Type
**Source:** [`src/utils/types.ts`](https://github.com/honojs/hono/blob/main/src/utils/types.ts#L7)
**Part of:** [Utils](subsystem-src-utils)
## Definition
```ts
T
```
# HtmlEscapedCallback
**Kind:** Type
**Source:** [`src/utils/html.ts`](https://github.com/honojs/hono/blob/main/src/utils/html.ts#L16)
**Part of:** [Utils](subsystem-src-utils)
## Definition
```ts
(opts: HtmlEscapedCallbackOpts) => Promise | undefined
```
# HtmlEscapedString
**Kind:** Type
**Source:** [`src/utils/html.ts`](https://github.com/honojs/hono/blob/main/src/utils/html.ts#L21)
**Part of:** [Utils](subsystem-src-utils)
## Definition
```ts
string & HtmlEscaped
```
# IfAnyThenEmptyObject
**Kind:** Type
**Source:** [`src/utils/types.ts`](https://github.com/honojs/hono/blob/main/src/utils/types.ts#L21)
**Part of:** [Utils](subsystem-src-utils)
## Definition
```ts
0 extends 1 & T ? {} : T
```
# InfoStatusCode
**Kind:** Type
**Source:** [`src/utils/http-status.ts`](https://github.com/honojs/hono/blob/main/src/utils/http-status.ts#L6)
**Part of:** [Utils](subsystem-src-utils)
## Definition
```ts
100 | 101 | 102 | 103
```
# InterfaceToType
**Kind:** Type
**Source:** [`src/utils/types.ts`](https://github.com/honojs/hono/blob/main/src/utils/types.ts#L102)
**Part of:** [Utils](subsystem-src-utils)
## Definition
```ts
T extends Function ? T : { [K in keyof T]: InterfaceToType }
```
# InvalidJSONValue
**Kind:** Type
**Source:** [`src/utils/types.ts`](https://github.com/honojs/hono/blob/main/src/utils/types.ts#L28)
**Part of:** [Utils](subsystem-src-utils)
## Definition
```ts
undefined | symbol | ((...args: unknown[]) => unknown)
```
# IsAny
**Kind:** Type
**Source:** [`src/utils/types.ts`](https://github.com/honojs/hono/blob/main/src/utils/types.ts#L114)
**Part of:** [Utils](subsystem-src-utils)
## Definition
```ts
boolean extends (T extends never ? true : false) ? true : false
```
# JSONArray
**Kind:** Type
**Source:** [`src/utils/types.ts`](https://github.com/honojs/hono/blob/main/src/utils/types.ts#L24)
**Part of:** [Utils](subsystem-src-utils)
## Definition
```ts
(JSONPrimitive | JSONObject | JSONArray)[]
```
# JSONPrimitive
**Kind:** Type
**Source:** [`src/utils/types.ts`](https://github.com/honojs/hono/blob/main/src/utils/types.ts#L23)
**Part of:** [Utils](subsystem-src-utils)
## Definition
```ts
string | boolean | number | null
```
# JSONValue
**Kind:** Type
**Source:** [`src/utils/types.ts`](https://github.com/honojs/hono/blob/main/src/utils/types.ts#L39)
**Part of:** [Utils](subsystem-src-utils)
## Definition
```ts
JSONObject | JSONArray | JSONPrimitive
```
# NotEqual
**Kind:** Type
**Source:** [`src/utils/types.ts`](https://github.com/honojs/hono/blob/main/src/utils/types.ts#L10)
**Part of:** [Utils](subsystem-src-utils)
## Definition
```ts
true extends Equal ? false : true
```
# Pattern
**Kind:** Type
**Source:** [`src/utils/url.ts`](https://github.com/honojs/hono/blob/main/src/utils/url.ts#L6)
**Part of:** [Utils](subsystem-src-utils)
## Definition
```ts
readonly [string, string, RegExp | true] | '*'
```
# RedirectStatusCode
**Kind:** Type
**Source:** [`src/utils/http-status.ts`](https://github.com/honojs/hono/blob/main/src/utils/http-status.ts#L9)
**Part of:** [Utils](subsystem-src-utils)
## Definition
```ts
300 | 301 | 302 | 303 | 304 | DeprecatedStatusCode | 307 | 308
```
# ServerErrorStatusCode
**Kind:** Type
**Source:** [`src/utils/http-status.ts`](https://github.com/honojs/hono/blob/main/src/utils/http-status.ts#L40)
**Part of:** [Utils](subsystem-src-utils)
## Definition
```ts
500 | 501 | 502 | 503 | 504 | 505 | 506 | 507 | 508 | 510 | 511
```
# SignatureAlgorithm
**Kind:** Type
**Source:** [`src/utils/jwt/jwa.ts`](https://github.com/honojs/hono/blob/main/src/utils/jwt/jwa.ts#L23)
**Part of:** [Utils](subsystem-src-utils)
## Definition
```ts
keyof typeof AlgorithmTypes
```
# SignatureKey
**Kind:** Type
**Source:** [`src/utils/jwt/jws.ts`](https://github.com/honojs/hono/blob/main/src/utils/jwt/jws.ts#L27)
**Part of:** [Utils](subsystem-src-utils)
## Definition
```ts
string | HonoJsonWebKey | CryptoKey
```
# SignedCookie
**Kind:** Type
**Source:** [`src/utils/cookie.ts`](https://github.com/honojs/hono/blob/main/src/utils/cookie.ts#L9)
**Part of:** [Utils](subsystem-src-utils)
## Definition
```ts
Record
```
# Simplify
**Kind:** Type
**Source:** [`src/utils/types.ts`](https://github.com/honojs/hono/blob/main/src/utils/types.ts#L93)
**Part of:** [Utils](subsystem-src-utils)
Useful to flatten the type output to improve type hints shown in editors. And also to transform an interface into a type to aide with assignability.
`Simplify` remaps the properties of `T` into a plain object type, which makes expanded type hints easier to read in editors. It can also convert an interface-shaped type into a type alias shape for assignability checks.
## Definition
```ts
{ [KeyType in keyof T]: T[KeyType] } & {}
```
## Diagram
```mermaid
graph LR
A[Input type T] --> B[Simplify]
B --> C[Remapped object properties]
C --> D[Clearer editor type hints]
C --> E[Type alias assignability]
```
## Usage
```ts
type Simplify = {
[Key in keyof T]: T[Key];
};
interface User {
id: string;
name: string;
}
type UserRecord = Simplify;
const user: UserRecord = {
id: "user_123",
name: "Ada",
};
```
## AI Coding Instructions
- Apply `Simplify` when an intersection or mapped type produces hard-to-read editor hints.
- Keep `Simplify` type-only; it does not transform values at runtime.
- Use it near public type boundaries where consumers benefit from a remapped object shape.
- Do not expect `Simplify` to change property values, optionality, or readonly modifiers.
# StringBuffer
**Kind:** Type
**Source:** [`src/utils/html.ts`](https://github.com/honojs/hono/blob/main/src/utils/html.ts#L37)
**Part of:** [Utils](subsystem-src-utils)
StringBuffer contains string and Promise alternately
The length of the array will be odd, the odd numbered element will be a string,
and the even numbered element will be a Promise.
When concatenating into a single string, it must be processed from the tail.
`StringBuffer` stores alternating `string` and `Promise` values for HTML assembly. Its array length is odd: odd-numbered elements are strings, even-numbered elements are `Promise`, and consumers must concatenate entries from the tail to preserve output order.
## Definition
```ts
(string | Promise)[]
```
## Diagram
```mermaid
graph LR
Start["String segment"] --> Async["Promise<string>"]
Async --> End["String segment"]
End --> Tail["Process from tail"]
Tail --> HTML["Combined HTML string"]
```
## Usage
```ts
import type { StringBuffer } from './utils/html';
const buffer: StringBuffer = [
'',
Promise.resolve('
Loaded content
'),
'',
];
async function joinBuffer(buffer: StringBuffer): Promise {
let html = '';
for (const entry of [...buffer].reverse()) {
html = `${await entry}${html}`;
}
return html;
}
const html = await joinBuffer(buffer);
//
Loaded content
```
## AI Coding Instructions
- Keep entries alternating between `string` and `Promise`, with strings at the beginning and end.
- Preserve the odd-length array shape when creating or transforming a `StringBuffer`.
- Concatenate entries from the tail; processing from the head can produce incorrect ordering around async content.
- Await promise entries before prepending their resolved HTML to the accumulated output.
# StringBufferWithCallbacks
**Kind:** Type
**Source:** [`src/utils/html.ts`](https://github.com/honojs/hono/blob/main/src/utils/html.ts#L38)
**Part of:** [Utils](subsystem-src-utils)
## Definition
```ts
StringBuffer & { callbacks: HtmlEscapedCallback[] }
```
# StringLiteralUnion
**Kind:** Type
**Source:** [`src/utils/types.ts`](https://github.com/honojs/hono/blob/main/src/utils/types.ts#L120)
**Part of:** [Utils](subsystem-src-utils)
String literal types with auto-completion
`StringLiteralUnion` combines a set of string literal values with `string` while preserving editor autocomplete for the known literals. It is used when an API accepts predefined string options but must also allow custom string values.
## Definition
```ts
T | (string & Record)
```
## Diagram
```mermaid
graph LR
A[Known string literals] --> C[StringLiteralUnion]
B[Custom string values] --> C
C --> D[Autocomplete for known values]
C --> E[Accepts any string]
```
## Usage
```ts
import type { StringLiteralUnion } from "../utils/types";
type Theme = StringLiteralUnion<"light" | "dark">;
const defaultTheme: Theme = "light";
const customTheme: Theme = "system";
```
## AI Coding Instructions
- Use `StringLiteralUnion` for string options that have known values and allow arbitrary custom values.
- Keep the known options as string literal unions, such as `"light" | "dark"`.
- Do not replace this type with `string` when autocomplete for known values is expected.
- Use the type in public option and configuration definitions where custom string extensions are valid.
# SuccessStatusCode
**Kind:** Type
**Source:** [`src/utils/http-status.ts`](https://github.com/honojs/hono/blob/main/src/utils/http-status.ts#L7)
**Part of:** [Utils](subsystem-src-utils)
## Definition
```ts
200 | 201 | 202 | 203 | 204 | 205 | 206 | 207 | 208 | 226
```
# SymmetricAlgorithm
**Kind:** Type
**Source:** [`src/utils/jwt/jwa.ts`](https://github.com/honojs/hono/blob/main/src/utils/jwt/jwa.ts#L25)
**Part of:** [Utils](subsystem-src-utils)
## Definition
```ts
'HS256' | 'HS384' | 'HS512'
```
# UnOfficalStatusCode
**Kind:** Type
**Source:** [`src/utils/http-status.ts`](https://github.com/honojs/hono/blob/main/src/utils/http-status.ts#L58)
**Part of:** [Utils](subsystem-src-utils)
## Definition
```ts
UnofficialStatusCode
```
# UnofficialStatusCode
**Kind:** Type
**Source:** [`src/utils/http-status.ts`](https://github.com/honojs/hono/blob/main/src/utils/http-status.ts#L52)
**Part of:** [Utils](subsystem-src-utils)
`UnofficialStatusCode` can be used to specify an unofficial status code.
`UnofficialStatusCode` represents HTTP status codes that are not part of the standard status-code set. Use it when an API response or error path needs to declare an unofficial HTTP status value with type checking.
## Definition
```ts
-1
```
## Diagram
```mermaid
graph LR
Application[Application code] --> Status[UnofficialStatusCode]
Status --> Response[HTTP response status]
```
## Usage
```ts
import type { UnofficialStatusCode } from './utils/http-status';
type ErrorResponse = {
statusCode: UnofficialStatusCode;
message: string;
};
const response: ErrorResponse = {
statusCode: 419,
message: 'Session expired',
};
```
## AI Coding Instructions
- Use `UnofficialStatusCode` for response paths that return a supported unofficial HTTP status value.
- Keep standard HTTP status codes typed through the corresponding standard status-code type.
- Do not cast arbitrary numbers to `UnofficialStatusCode`; add a value only when it belongs in the type definition.
- Preserve the type when passing status codes through response helpers and error handlers.
# useContext
**Kind:** Function
**Source:** [`src/jsx/context.ts`](https://github.com/honojs/hono/blob/main/src/jsx/context.ts#L259)
**Part of:** [Jsx](subsystem-src-jsx)
Read the current value of a context created with createContext.
Safe to call from async components after `await`. See createContext
for the per-runtime isolation guarantees.
`useContext` reads the current value from a context created with `createContext`. It can be called in synchronous or asynchronous components, including after an `await`, while keeping context values isolated per runtime.
## Signature
```ts
function useContext(context: Context): T
```
## Parameters
| Name | Type |
|---|---|
| `context` | `Context` |
**Returns:** `T`
## Diagram
```mermaid
graph LR
A[createContext] --> B[Context]
B --> C[Context.Provider]
C --> D[Component]
D --> E[useContext]
E --> F[Current context value]
```
## Usage
```tsx
import { createContext, useContext } from 'hono/jsx'
const ThemeContext = createContext('light')
const ThemeLabel = async () => {
await Promise.resolve()
const theme = useContext(ThemeContext)
return Theme: {theme}
}
const App = () => (
)
```
## AI Coding Instructions
- Create contexts with `createContext` before reading them with `useContext`.
- Pass the context object returned by `createContext` directly to `useContext`.
- Read context inside a component that is rendered below the matching `Context.Provider`.
- `useContext` may run after `await` in an async component.
## Used by
7 references from 7 files. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (7)
- `Props` — `src/jsx/base.ts`:27
- `childrenToString` — `src/jsx/components.ts`:14
- `FormContext` — `src/jsx/dom/hooks/index.ts`:24
- `clearCache` — `src/jsx/dom/intrinsic-element/components.ts`:18
- `HasRenderToDom` — `src/jsx/dom/render.ts`:30
- `title` — `src/jsx/intrinsic-element/components.ts`:121
- `StreamingContext` — `src/jsx/streaming.ts`:30
# DOM_RENDERER
**Kind:** Constant
**Source:** [`src/jsx/constants.ts`](https://github.com/honojs/hono/blob/main/src/jsx/constants.ts#L1)
**Part of:** [Jsx](subsystem-src-jsx)
## Definition
```ts
Symbol('RENDERER')
```
## Value
```ts
Symbol('RENDERER')
```
## Used by
6 references from 6 files. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (6)
- `createCssContext` — `src/helper/css/index.ts`:72
- `Props` — `src/jsx/base.ts`:27
- `childrenToString` — `src/jsx/components.ts`:14
- `Context` — `src/jsx/context.ts`:8
- `HasRenderToDom` — `src/jsx/dom/render.ts`:30
- `StreamingContext` — `src/jsx/streaming.ts`:30
# styleObjectForEach
**Kind:** Function
**Source:** [`src/jsx/utils.ts`](https://github.com/honojs/hono/blob/main/src/jsx/utils.ts#L169)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function styleObjectForEach(style: Record, fn: (key: string, value: string | null) => void): void
```
## Parameters
| Name | Type |
|---|---|
| `style` | `Record` |
| `fn` | `(key: string, value: string | null) => void` |
**Returns:** `void`
## Used by
3 references from 3 files. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (3)
- `Props` — `src/jsx/base.ts`:27
- `HasRenderToDom` — `src/jsx/dom/render.ts`:30
- `jsxAttr` — `src/jsx/jsx-runtime.ts`:16
# useState
**Kind:** Function
**Source:** [`src/jsx/hooks/index.ts`](https://github.com/honojs/hono/blob/main/src/jsx/hooks/index.ts#L182)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function useState(initialState: T | (() => T)): [T, UpdateStateFunction]
```
## Parameters
| Name | Type |
|---|---|
| `initialState` | `T | (() => T)` |
**Returns:** `[T, UpdateStateFunction]`
## Used by
3 references from 3 files. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (3)
- `Root` — `src/jsx/dom/client.ts`:11
- `FormContext` — `src/jsx/dom/hooks/index.ts`:24
- `clearCache` — `src/jsx/dom/intrinsic-element/components.ts`:18
# captureRenderContext
**Kind:** Function
**Source:** [`src/jsx/context.ts`](https://github.com/honojs/hono/blob/main/src/jsx/context.ts#L196)
**Part of:** [Jsx](subsystem-src-jsx)
Capture the current render store and return a resumer that re-establishes it
around a deferred continuation (e.g. a re-render after a suspended promise
settles). Shared by every suspension point so none reimplements it.
`captureRenderContext` saves the render store that is active when it is called and returns a resumer function. Call the resumer around deferred work, such as a continuation after a suspended promise settles, so that work runs with the original render context.
## Signature
```ts
function captureRenderContext(): ((callback: () => T) => T)
```
**Returns:** `((callback: () => T) => T)`
## Diagram
```mermaid
graph LR
A[Active render store] --> B[captureRenderContext]
B --> C[Resumer function]
D[Deferred continuation] --> C
C --> E[Restore captured render store]
E --> F[Run continuation]
F --> G[Restore previous render store]
```
## Usage
```ts
import { captureRenderContext } from './context'
function continueAfterPromise(promise: Promise, rerender: () => void) {
const resume = captureRenderContext()
promise.then(() => {
resume(() => {
rerender()
})
})
}
```
## AI Coding Instructions
- Capture the render context before scheduling asynchronous or deferred work.
- Invoke deferred continuations through the returned resumer rather than calling them directly.
- Preserve the existing render store after the continuation completes; do not assign global render state without restoring it.
- Share this helper across suspension paths so promise handlers and retry logic follow the same context-restoration behavior.
## Used by
3 references from 3 files. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (3)
- `Props` — `src/jsx/base.ts`:27
- `childrenToString` — `src/jsx/components.ts`:14
- `StreamingContext` — `src/jsx/streaming.ts`:30
# DOM_ERROR_HANDLER
**Kind:** Constant
**Source:** [`src/jsx/constants.ts`](https://github.com/honojs/hono/blob/main/src/jsx/constants.ts#L2)
**Part of:** [Jsx](subsystem-src-jsx)
## Definition
```ts
Symbol('ERROR_HANDLER')
```
## Value
```ts
Symbol('ERROR_HANDLER')
```
## Used by
3 references from 3 files. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (3)
- `ErrorBoundary` — `src/jsx/dom/components.ts`:7
- `createContextProviderFunction` — `src/jsx/dom/context.ts`:7
- `HasRenderToDom` — `src/jsx/dom/render.ts`:30
# DOM_STASH
**Kind:** Constant
**Source:** [`src/jsx/constants.ts`](https://github.com/honojs/hono/blob/main/src/jsx/constants.ts#L3)
**Part of:** [Jsx](subsystem-src-jsx)
## Definition
```ts
Symbol('STASH')
```
## Value
```ts
Symbol('STASH')
```
## Used by
3 references from 3 files. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (3)
- `HasRenderToDom` — `src/jsx/dom/render.ts`:30
- `STASH_EFFECT` — `src/jsx/hooks/index.ts`:9
- `StreamingContext` — `src/jsx/streaming.ts`:30
# globalContexts
**Kind:** Constant
**Source:** [`src/jsx/context.ts`](https://github.com/honojs/hono/blob/main/src/jsx/context.ts#L13)
**Part of:** [Jsx](subsystem-src-jsx)
## Definition
```ts
Context[]
```
## Value
```ts
[]
```
## Used by
3 references from 3 files. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (3)
- `Props` — `src/jsx/base.ts`:27
- `createContextProviderFunction` — `src/jsx/dom/context.ts`:7
- `HasRenderToDom` — `src/jsx/dom/render.ts`:30
# JSXNode
**Kind:** Class
**Source:** [`src/jsx/base.ts`](https://github.com/honojs/hono/blob/main/src/jsx/base.ts#L171)
**Part of:** [Jsx](subsystem-src-jsx)
`JSXNode` represents a JSX node and exposes conversion methods for rendering its contents. Call `toString()` to obtain rendered text, or call `toStringToBuffer()` when integrating with buffer-oriented output handling.
**Implements:** `HtmlEscaped`
## Methods
| Method | Signature | Returns |
|---|---|---|
| `toString` | `toString()` | `string | Promise` |
| `toStringToBuffer` | `toStringToBuffer(buffer: StringBufferWithCallbacks)` | `void` |
## Properties
| Property | Type |
|---|---|
| `tag` | `string | Function` |
| `props` | `Props` |
| `key` | `string` |
| `children` | `Child[]` |
| `isEscaped` | `true` |
## Where it refuses work
- `JSXNode` stops the work with `Error` when `typeof tag !== 'function' && !isValidTagName(tag)`.
- `JSXNode` stops the work with `Error` when `children.length > 0` — “Can only set one of `children` or `props.dangerouslySetInnerHTML`.”.
- `JSXNode` stops the work with `Error` when `!key.startsWith('on') && key !== 'ref'`.
## Diagram
```mermaid
graph LR
JSXNode --> ToString["toString(): string | Promise"]
JSXNode --> ToBuffer["toStringToBuffer(): void"]
ToString --> Text["Rendered string"]
ToBuffer --> BufferOutput["Buffer-oriented output"]
```
## Usage
```ts
import { JSXNode } from "./jsx/base";
async function renderNode(node: JSXNode): Promise {
return await node.toString();
}
function writeNodeToBuffer(node: JSXNode): void {
node.toStringToBuffer();
}
```
## AI Coding Instructions
- Handle `toString()` as potentially asynchronous; use `await` when consuming its result.
- Keep string rendering and buffer-oriented output separate by calling the method that matches the caller's output path.
- Do not assume `toStringToBuffer()` returns rendered content; its return type is `void`.
- Pass `JSXNode` instances through rendering boundaries rather than converting them early when later output handling may differ.
## Used by
2 references from 2 files. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (2)
- `title` — `src/jsx/intrinsic-element/components.ts`:121
- `StreamingContext` — `src/jsx/streaming.ts`:30
# renderToReadableStream
**Kind:** Function
**Source:** [`src/jsx/streaming.ts`](https://github.com/honojs/hono/blob/main/src/jsx/streaming.ts#L146)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function renderToReadableStream(content: HtmlEscapedString | JSXNode | Promise, onError: (e: unknown) => string | void): ReadableStream
```
## Parameters
| Name | Type |
|---|---|
| `content` | `HtmlEscapedString | JSXNode | Promise` |
| `onError` | `(e: unknown) => string | void` |
**Returns:** `ReadableStream`
## Used by
2 references from 2 files. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (2)
- `RenderToStringOptions` — `src/jsx/dom/server.ts`:11
- `RequestContext` — `src/middleware/jsx-renderer/index.ts`:14
# jsxDEV
**Kind:** Function
**Source:** [`src/jsx/jsx-dev-runtime.ts`](https://github.com/honojs/hono/blob/main/src/jsx/jsx-dev-runtime.ts#L12)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function jsxDEV(tag: string | Function, props: Record, key: string): JSXNode
```
## Parameters
| Name | Type |
|---|---|
| `tag` | `string | Function` |
| `props` | `Record` |
| `key` | `string` |
**Returns:** `JSXNode`
## Relationships
- IMPORTS → `jsxFn`
- IMPORTS → `Fragment`
## Used by
2 references from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (2)
- `jsxAttr` — `src/jsx/jsx-runtime.ts`:16
- `jsxAttr` — `src/jsx/jsx-runtime.ts`:16
# useCallback
**Kind:** Function
**Source:** [`src/jsx/hooks/index.ts`](https://github.com/honojs/hono/blob/main/src/jsx/hooks/index.ts#L299)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function useCallback(callback: T, deps: readonly unknown[]): T
```
## Parameters
| Name | Type |
|---|---|
| `callback` | `T` |
| `deps` | `readonly unknown[]` |
**Returns:** `T`
## Used by
2 references from 2 files. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (2)
- `FormContext` — `src/jsx/dom/hooks/index.ts`:24
- `clearCache` — `src/jsx/dom/intrinsic-element/components.ts`:18
# createContext
**Kind:** Function
**Source:** [`src/jsx/context.ts`](https://github.com/honojs/hono/blob/main/src/jsx/context.ts#L213)
**Part of:** [Jsx](subsystem-src-jsx)
Create a context whose value can be provided with `` and
read with useContext.
Server-side renders are isolated per request, so a provided value never leaks
into a concurrent request — even across `await` in an async component, when
`AsyncLocalStorage` is available (Node.js >= 20.16, Deno, Bun, Cloudflare
Workers with `nodejs_compat`). Without it, reading context after `await`
returns the default value; synchronous components and `use()`-based
suspension are unaffected.
`createContext` creates a context object with a default value, a `` component, and a value that `useContext` can read. During server rendering, context state is isolated by request; reading context after `await` in an async component depends on `AsyncLocalStorage` availability.
## Signature
```ts
function createContext(defaultValue: T): Context
```
## Parameters
| Name | Type |
|---|---|
| `defaultValue` | `T` |
**Returns:** `Context`
## Diagram
```mermaid
graph LR
Default[Default value] --> Context[createContext]
Context --> Provider[Context.Provider]
Provider --> Tree[Component tree]
Tree --> Consumer[useContext]
Consumer --> Value[Current context value]
```
## Usage
```tsx
import { createContext, useContext } from "./jsx";
const ThemeContext = createContext("light");
function ThemeLabel() {
const theme = useContext(ThemeContext);
return Theme: {theme};
}
export function App() {
return (
);
}
```
## AI Coding Instructions
- Create contexts outside component render functions so consumers reference the same context object.
- Wrap consumers with `` when they need a value other than the default.
- Use `useContext(Context)` only inside a component render or supported hook execution path.
- In async server components, avoid relying on context reads after `await` when `AsyncLocalStorage` is unavailable.
## Used by
2 references from 2 files. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (2)
- `Props` — `src/jsx/base.ts`:27
- `StreamingContext` — `src/jsx/streaming.ts`:30
# isValidAttributeName
**Kind:** Function
**Source:** [`src/jsx/utils.ts`](https://github.com/honojs/hono/blob/main/src/jsx/utils.ts#L49)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function isValidAttributeName(name: string): boolean
```
## Parameters
| Name | Type |
|---|---|
| `name` | `string` |
**Returns:** `boolean`
## Used by
2 references from 2 files. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (2)
- `Props` — `src/jsx/base.ts`:27
- `jsxAttr` — `src/jsx/jsx-runtime.ts`:16
# shouldDeDupeByKey
**Kind:** Function
**Source:** [`src/jsx/intrinsic-element/common.ts`](https://github.com/honojs/hono/blob/main/src/jsx/intrinsic-element/common.ts#L18)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function shouldDeDupeByKey(tagName: string, supportSort: boolean): boolean
```
## Parameters
| Name | Type |
|---|---|
| `tagName` | `string` |
| `supportSort` | `boolean` |
**Returns:** `boolean`
## Used by
2 references from 2 files. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (2)
- `clearCache` — `src/jsx/dom/intrinsic-element/components.ts`:18
- `title` — `src/jsx/intrinsic-element/components.ts`:121
# Fragment
**Kind:** Function
**Source:** [`src/jsx/base.ts`](https://github.com/honojs/hono/blob/main/src/jsx/base.ts#L421)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function Fragment({
children,
}: { key?: string children?: Child | HtmlEscapedString }): HtmlEscapedString
```
## Parameters
| Name | Type |
|---|---|
| `{
children,
}` | `{ key?: string children?: Child | HtmlEscapedString }` |
**Returns:** `HtmlEscapedString`
## Used by
2 references from 2 files. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (2)
- `childrenToString` — `src/jsx/components.ts`:14
- `jsxDEV` — `src/jsx/jsx-dev-runtime.ts`:12
# createContext
**Kind:** Function
**Source:** [`src/jsx/dom/context.ts`](https://github.com/honojs/hono/blob/main/src/jsx/dom/context.ts#L45)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function createContext(defaultValue: T): Context
```
## Parameters
| Name | Type |
|---|---|
| `defaultValue` | `T` |
**Returns:** `Context`
## Used by
2 references from 2 files. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (2)
- `FormContext` — `src/jsx/dom/hooks/index.ts`:24
- `HasRenderToDom` — `src/jsx/dom/render.ts`:30
# isStylesheetLinkWithPrecedence
**Kind:** Function
**Source:** [`src/jsx/intrinsic-element/common.ts`](https://github.com/honojs/hono/blob/main/src/jsx/intrinsic-element/common.ts#L15)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function isStylesheetLinkWithPrecedence(props: Props): boolean
```
## Parameters
| Name | Type |
|---|---|
| `props` | `Props` |
**Returns:** `boolean`
## Used by
2 references from 2 files. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (2)
- `clearCache` — `src/jsx/dom/intrinsic-element/components.ts`:18
- `title` — `src/jsx/intrinsic-element/components.ts`:121
# normalizeIntrinsicElementKey
**Kind:** Function
**Source:** [`src/jsx/utils.ts`](https://github.com/honojs/hono/blob/main/src/jsx/utils.ts#L11)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function normalizeIntrinsicElementKey(key: string): string
```
## Parameters
| Name | Type |
|---|---|
| `key` | `string` |
**Returns:** `string`
## Used by
2 references from 2 files. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (2)
- `Props` — `src/jsx/base.ts`:27
- `HasRenderToDom` — `src/jsx/dom/render.ts`:30
# toArray
**Kind:** Function
**Source:** [`src/jsx/children.ts`](https://github.com/honojs/hono/blob/main/src/jsx/children.ts#L3)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function toArray(children: Child): Child[]
```
## Parameters
| Name | Type |
|---|---|
| `children` | `Child` |
**Returns:** `Child[]`
## Used by
2 references from 2 files. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (2)
- `HasRenderToDom` — `src/jsx/dom/render.ts`:30
- `title` — `src/jsx/intrinsic-element/components.ts`:121
# deDupeKeyMap
**Kind:** Constant
**Source:** [`src/jsx/intrinsic-element/common.ts`](https://github.com/honojs/hono/blob/main/src/jsx/intrinsic-element/common.ts#L3)
**Part of:** [Jsx](subsystem-src-jsx)
## Definition
```ts
Record
```
## Value
```ts
{
title: [],
script: ['src'],
style: ['data-href'],
link: ['href'],
meta: ['name', 'httpEquiv', 'charset', 'itemProp'],
}
```
## Used by
2 references from 2 files. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (2)
- `clearCache` — `src/jsx/dom/intrinsic-element/components.ts`:18
- `title` — `src/jsx/intrinsic-element/components.ts`:121
# buildDataStack
**Kind:** Constant
**Source:** [`src/jsx/dom/render.ts`](https://github.com/honojs/hono/blob/main/src/jsx/dom/render.ts#L106)
**Part of:** [Jsx](subsystem-src-jsx)
## Definition
```ts
[Context, Node][]
```
## Value
```ts
[]
```
## Used by
2 references from 2 files. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (2)
- `STASH_EFFECT` — `src/jsx/hooks/index.ts`:9
- `StreamingContext` — `src/jsx/streaming.ts`:30
# dataPrecedenceAttr
**Kind:** Constant
**Source:** [`src/jsx/intrinsic-element/common.ts`](https://github.com/honojs/hono/blob/main/src/jsx/intrinsic-element/common.ts#L13)
**Part of:** [Jsx](subsystem-src-jsx)
## Definition
```ts
'data-precedence'
```
## Value
```ts
'data-precedence'
```
## Used by
2 references from 2 files. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (2)
- `clearCache` — `src/jsx/dom/intrinsic-element/components.ts`:18
- `title` — `src/jsx/intrinsic-element/components.ts`:121
# DOM_INTERNAL_TAG
**Kind:** Constant
**Source:** [`src/jsx/constants.ts`](https://github.com/honojs/hono/blob/main/src/jsx/constants.ts#L4)
**Part of:** [Jsx](subsystem-src-jsx)
## Definition
```ts
Symbol('INTERNAL')
```
## Value
```ts
Symbol('INTERNAL')
```
## Used by
2 references from 2 files. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (2)
- `HasRenderToDom` — `src/jsx/dom/render.ts`:30
- `setInternalTagFlag` — `src/jsx/dom/utils.ts`:3
# DOM_MEMO
**Kind:** Constant
**Source:** [`src/jsx/constants.ts`](https://github.com/honojs/hono/blob/main/src/jsx/constants.ts#L5)
**Part of:** [Jsx](subsystem-src-jsx)
## Definition
```ts
Symbol('MEMO')
```
## Value
```ts
Symbol('MEMO')
```
## Used by
2 references from 2 files. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (2)
- `Props` — `src/jsx/base.ts`:27
- `HasRenderToDom` — `src/jsx/dom/render.ts`:30
# domRenderers
**Kind:** Constant
**Source:** [`src/jsx/intrinsic-element/common.ts`](https://github.com/honojs/hono/blob/main/src/jsx/intrinsic-element/common.ts#L11)
**Part of:** [Jsx](subsystem-src-jsx)
## Definition
```ts
Record
```
## Value
```ts
{}
```
## Used by
2 references from 2 files. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (2)
- `Props` — `src/jsx/base.ts`:27
- `clearCache` — `src/jsx/dom/intrinsic-element/components.ts`:18
# PERMALINK
**Kind:** Constant
**Source:** [`src/jsx/constants.ts`](https://github.com/honojs/hono/blob/main/src/jsx/constants.ts#L6)
**Part of:** [Jsx](subsystem-src-jsx)
## Definition
```ts
Symbol('PERMALINK')
```
## Value
```ts
Symbol('PERMALINK')
```
## Used by
2 references from 2 files. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (2)
- `FormContext` — `src/jsx/dom/hooks/index.ts`:24
- `title` — `src/jsx/intrinsic-element/components.ts`:121
# jsxFn
**Kind:** Function
**Source:** [`src/jsx/base.ts`](https://github.com/honojs/hono/blob/main/src/jsx/base.ts#L342)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function jsxFn(tag: string | Function, props: Props, children: Child[]): JSXNode
```
## Parameters
| Name | Type |
|---|---|
| `tag` | `string | Function` |
| `props` | `Props` |
| `children` | `Child[]` |
**Returns:** `JSXNode`
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `jsxDEV` — `src/jsx/jsx-dev-runtime.ts`:12
# update
**Kind:** Function
**Source:** [`src/jsx/dom/render.ts`](https://github.com/honojs/hono/blob/main/src/jsx/dom/render.ts#L740)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
async function update(context: Context, node: NodeObject): Promise
```
## Parameters
| Name | Type |
|---|---|
| `context` | `Context` |
| `node` | `NodeObject` |
**Returns:** `Promise`
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `STASH_EFFECT` — `src/jsx/hooks/index.ts`:9
# runWithRenderContext
**Kind:** Function
**Source:** [`src/jsx/context.ts`](https://github.com/honojs/hono/blob/main/src/jsx/context.ts#L161)
**Part of:** [Jsx](subsystem-src-jsx)
Establish the request-scoped context store for a render.
`resumeStore` continues a suspended subtree in the same store on the fallback
path (ignored when `AsyncLocalStorage` is available, where isolation is
automatic).
Without `AsyncLocalStorage` a render can't be followed across `await`, so the
store lives in `fallbackStore` only during synchronous work (mirroring
React's request storage). Reading context after `await` then finds no store
and falls back to the default value — never another request's value.
`runWithRenderContext` creates the request-scoped context store used while rendering a JSX tree. When `AsyncLocalStorage` is available, the store remains isolated across asynchronous work; otherwise, the fallback store exists only for synchronous rendering and context reads after `await` return their default values.
## Signature
```ts
function runWithRenderContext(callback: () => T, resumeStore: RenderStore): T
```
## Parameters
| Name | Type |
|---|---|
| `callback` | `() => T` |
| `resumeStore` | `RenderStore` |
**Returns:** `T`
## Diagram
```mermaid
graph LR
Render[Render callback] --> Run[runWithRenderContext]
Run --> ALS{AsyncLocalStorage available?}
ALS -->|Yes| RequestStore[Request-scoped async store]
ALS -->|No| FallbackStore[Temporary fallback store]
RequestStore --> ContextRead[Context reads]
FallbackStore --> ContextRead
FallbackStore --> Cleanup[Restore previous fallback store]
```
## Usage
```tsx
import { runWithRenderContext } from './jsx/context';
import { renderPage } from './render';
const html = runWithRenderContext(() => {
return renderPage();
});
// Context reads performed during renderPage use this render's store.
return new Response(html, {
headers: { 'content-type': 'text/html' },
});
```
## AI Coding Instructions
- Wrap each top-level render entry point with `runWithRenderContext` so context values are scoped to that render.
- Keep fallback-mode context-dependent rendering synchronous; context reads after `await` use the context default value when `AsyncLocalStorage` is unavailable.
- Pass `resumeStore` only when resuming a suspended subtree that must continue with its prior context values.
- Restore the previous fallback store after callback execution so one render cannot expose context values to another render.
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `Props` — `src/jsx/base.ts`:27
# createCssJsxDomObjects
**Kind:** Function
**Source:** [`src/jsx/dom/css.ts`](https://github.com/honojs/hono/blob/main/src/jsx/dom/css.ts#L77)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function createCssJsxDomObjects({ id })
```
## Parameters
| Name | Type |
|---|---|
| `{ id }` | `any` |
## Relationships
- IMPORTS → `CLASS_NAME`
- IMPORTS → `DEFAULT_STYLE_ID`
- IMPORTS → `PSEUDO_GLOBAL_SELECTOR`
- IMPORTS → `SELECTOR`
- IMPORTS → `SELECTORS`
- IMPORTS → `STYLE_STRING`
- IMPORTS → `cssCommon`
- IMPORTS → `cxCommon`
- IMPORTS → `keyframesCommon`
- IMPORTS → `viewTransitionCommon`
- IMPORTS → `rawCssString`
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `createCssContext` — `src/helper/css/index.ts`:72
# createPortal
**Kind:** Function
**Source:** [`src/jsx/dom/render.ts`](https://github.com/honojs/hono/blob/main/src/jsx/dom/render.ts#L815)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function createPortal(children: Child, container: HTMLElement, key: string): Child
```
## Parameters
| Name | Type |
|---|---|
| `children` | `Child` |
| `container` | `HTMLElement` |
| `key` | `string` |
**Returns:** `Child`
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `clearCache` — `src/jsx/dom/intrinsic-element/components.ts`:18
# useMemo
**Kind:** Function
**Source:** [`src/jsx/hooks/index.ts`](https://github.com/honojs/hono/blob/main/src/jsx/hooks/index.ts#L352)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function useMemo(factory: () => T, deps: readonly unknown[]): T
```
## Parameters
| Name | Type |
|---|---|
| `factory` | `() => T` |
| `deps` | `readonly unknown[]` |
**Returns:** `T`
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `clearCache` — `src/jsx/dom/intrinsic-element/components.ts`:18
# buildNode
**Kind:** Function
**Source:** [`src/jsx/dom/render.ts`](https://github.com/honojs/hono/blob/main/src/jsx/dom/render.ts#L667)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function buildNode(node: Child): Node | undefined
```
## Parameters
| Name | Type |
|---|---|
| `node` | `Child` |
**Returns:** `Node | undefined`
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `Root` — `src/jsx/dom/client.ts`:11
# createContextProviderFunction
**Kind:** Function
**Source:** [`src/jsx/dom/context.ts`](https://github.com/honojs/hono/blob/main/src/jsx/dom/context.ts#L7)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function createContextProviderFunction(values: T[]): Function
```
## Parameters
| Name | Type |
|---|---|
| `values` | `T[]` |
**Returns:** `Function`
## Relationships
- IMPORTS → `DOM_ERROR_HANDLER`
- IMPORTS → `globalContexts`
- IMPORTS → `setInternalTagFlag`
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `Context` — `src/jsx/context.ts`:8
# renderNode
**Kind:** Function
**Source:** [`src/jsx/dom/render.ts`](https://github.com/honojs/hono/blob/main/src/jsx/dom/render.ts#L783)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function renderNode(node: NodeObject, container: Container): void
```
## Parameters
| Name | Type |
|---|---|
| `node` | `NodeObject` |
| `container` | `Container` |
**Returns:** `void`
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `Root` — `src/jsx/dom/client.ts`:11
# childrenToString
**Kind:** Function
**Source:** [`src/jsx/components.ts`](https://github.com/honojs/hono/blob/main/src/jsx/components.ts#L14)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
async function childrenToString(children: Child[]): Promise
```
## Parameters
| Name | Type |
|---|---|
| `children` | `Child[]` |
**Returns:** `Promise`
## Relationships
- IMPORTS → `html`
- IMPORTS → `HtmlEscapedCallbackPhase`
- IMPORTS → `resolveCallback`
- IMPORTS → `Fragment`
- IMPORTS → `DOM_RENDERER`
- IMPORTS → `captureRenderContext`
- IMPORTS → `useContext`
- IMPORTS → `ErrorBoundary`
- IMPORTS → `StreamingContext`
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `StreamingContext` — `src/jsx/streaming.ts`:30
# isValidTagName
**Kind:** Function
**Source:** [`src/jsx/utils.ts`](https://github.com/honojs/hono/blob/main/src/jsx/utils.ts#L32)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function isValidTagName(name: unknown): name is string
```
## Parameters
| Name | Type |
|---|---|
| `name` | `unknown` |
**Returns:** `name is string`
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `Props` — `src/jsx/base.ts`:27
# title
**Kind:** Function
**Source:** [`src/jsx/intrinsic-element/components.ts`](https://github.com/honojs/hono/blob/main/src/jsx/intrinsic-element/components.ts#L121)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function title({ children, ...props })
```
## Parameters
| Name | Type |
|---|---|
| `{ children, ...props }` | `any` |
## Relationships
- IMPORTS → `html`
- IMPORTS → `JSXNode`
- IMPORTS → `getNameSpaceContext`
- IMPORTS → `toArray`
- IMPORTS → `PERMALINK`
- IMPORTS → `useContext`
- IMPORTS → `dataPrecedenceAttr`
- IMPORTS → `deDupeKeyMap`
- IMPORTS → `isStylesheetLinkWithPrecedence`
- IMPORTS → `shouldDeDupeByKey`
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `Props` — `src/jsx/base.ts`:27
# use
**Kind:** Function
**Source:** [`src/jsx/hooks/index.ts`](https://github.com/honojs/hono/blob/main/src/jsx/hooks/index.ts#L336)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function use(promise: Promise): T
```
## Parameters
| Name | Type |
|---|---|
| `promise` | `Promise` |
**Returns:** `T`
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `clearCache` — `src/jsx/dom/intrinsic-element/components.ts`:18
# JSXFragmentNode
**Kind:** Class
**Source:** [`src/jsx/base.ts`](https://github.com/honojs/hono/blob/main/src/jsx/base.ts#L321)
**Part of:** [Jsx](subsystem-src-jsx)
`JSXFragmentNode` represents a JSX fragment node within the JSX node model. Its `toStringToBuffer()` method writes the fragment’s string form to the active output buffer instead of returning a string.
**Extends:** `JSXNode`
## Methods
| Method | Signature | Returns |
|---|---|---|
| `toStringToBuffer` | `toStringToBuffer(buffer: StringBufferWithCallbacks)` | `void` |
## Diagram
```mermaid
graph LR
Fragment[JSXFragmentNode] --> Writer[toStringToBuffer()]
Writer --> Buffer[Output Buffer]
```
## Usage
```ts
import { JSXFragmentNode } from "./jsx/base";
function writeFragment(fragment: JSXFragmentNode): void {
fragment.toStringToBuffer();
}
```
## AI Coding Instructions
- Call `toStringToBuffer()` when rendering a fragment through the buffer-based output path.
- Do not expect `toStringToBuffer()` to return rendered content; it returns `void`.
- Keep fragment rendering consistent with other JSX node types in `src/jsx/base.ts`.
- Pass `JSXFragmentNode` instances through code that manages the active output buffer.
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `Context` — `src/jsx/context.ts`:8
# setInternalTagFlag
**Kind:** Function
**Source:** [`src/jsx/dom/utils.ts`](https://github.com/honojs/hono/blob/main/src/jsx/dom/utils.ts#L3)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function setInternalTagFlag(fn: Function): Function
```
## Parameters
| Name | Type |
|---|---|
| `fn` | `Function` |
**Returns:** `Function`
## Relationships
- IMPORTS → `DOM_INTERNAL_TAG`
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `createContextProviderFunction` — `src/jsx/dom/context.ts`:7
# registerAction
**Kind:** Function
**Source:** [`src/jsx/dom/hooks/index.ts`](https://github.com/honojs/hono/blob/main/src/jsx/dom/hooks/index.ts#L32)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function registerAction(action: Promise)
```
## Parameters
| Name | Type |
|---|---|
| `action` | `Promise` |
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `clearCache` — `src/jsx/dom/intrinsic-element/components.ts`:18
# ErrorBoundary
**Kind:** Constant
**Source:** [`src/jsx/dom/components.ts`](https://github.com/honojs/hono/blob/main/src/jsx/dom/components.ts#L7)
**Part of:** [Jsx](subsystem-src-jsx)
## Definition
```ts
FC< PropsWithChildren<{ fallback?: Child fallbackRender?: FallbackRender onError?: ErrorHandler }> >
```
## Value
```ts
(({ children, fallback, fallbackRender, onError }: any) => {
const res = Fragment({ children })
;(res as any)[DOM_ERROR_HANDLER] = (err: any) => {
if (err instanceof Promise) {
throw err
}
onError?.(err)
return fallbackRender?.(err) || fallback
}
return res
}) as any
```
## Relationships
- IMPORTS → `DOM_ERROR_HANDLER`
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `childrenToString` — `src/jsx/components.ts`:14
# Suspense
**Kind:** Constant
**Source:** [`src/jsx/dom/components.ts`](https://github.com/honojs/hono/blob/main/src/jsx/dom/components.ts#L25)
**Part of:** [Jsx](subsystem-src-jsx)
## Definition
```ts
FC>
```
## Value
```ts
(({
children,
fallback,
}: any) => {
const res = Fragment({ children })
;(res as any)[DOM_ERROR_HANDLER] = (err: any, retry: () => void) => {
if (!(err instanceof Promise)) {
throw err
}
err.finally(retry)
return fallback
}
return res
}) as any
```
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `StreamingContext` — `src/jsx/streaming.ts`:30
# FormContext
**Kind:** Constant
**Source:** [`src/jsx/dom/hooks/index.ts`](https://github.com/honojs/hono/blob/main/src/jsx/dom/hooks/index.ts#L24)
**Part of:** [Jsx](subsystem-src-jsx)
## Definition
```ts
Context
```
## Value
```ts
createContext({
pending: false,
data: null,
method: null,
action: null,
})
```
## Relationships
- IMPORTS → `PERMALINK`
- IMPORTS → `useContext`
- IMPORTS → `useCallback`
- IMPORTS → `useState`
- IMPORTS → `createContext`
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `clearCache` — `src/jsx/dom/intrinsic-element/components.ts`:18
# clearCache
**Kind:** Function
**Source:** [`src/jsx/dom/intrinsic-element/components.ts`](https://github.com/honojs/hono/blob/main/src/jsx/dom/intrinsic-element/components.ts#L18)
**Part of:** [Jsx](subsystem-src-jsx)
## Relationships
- IMPORTS → `useContext`
- IMPORTS → `use`
- IMPORTS → `useCallback`
- IMPORTS → `useMemo`
- IMPORTS → `useState`
- IMPORTS → `dataPrecedenceAttr`
- IMPORTS → `deDupeKeyMap`
- IMPORTS → `domRenderers`
- IMPORTS → `isStylesheetLinkWithPrecedence`
- IMPORTS → `shouldDeDupeByKey`
- IMPORTS → `FormContext`
- IMPORTS → `registerAction`
- IMPORTS → `createPortal`
- IMPORTS → `getNameSpaceContext`
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `jsxDEV` — `src/jsx/dom/jsx-dev-runtime.ts`:10
# StreamingContext
**Kind:** Constant
**Source:** [`src/jsx/streaming.ts`](https://github.com/honojs/hono/blob/main/src/jsx/streaming.ts#L30)
**Part of:** [Jsx](subsystem-src-jsx)
Used to specify nonce for scripts generated by `Suspense` and `ErrorBoundary`.
`StreamingContext` carries a CSP nonce for inline scripts emitted by `Suspense` and `ErrorBoundary` during JSX streaming. Wrap streamed JSX with its provider so generated scripts receive the same nonce allowed by the response's Content Security Policy.
## Definition
```ts
JSXContext<{ scriptNonce: string } | null>
```
## Value
```ts
createContext<{
scriptNonce: string
} | null>(null)
```
## Diagram
```mermaid
graph LR
A[StreamingContext.Provider] --> B[Streaming JSX render]
B --> C[Suspense]
B --> D[ErrorBoundary]
C --> E[Generated script with nonce]
D --> E
```
## Usage
```tsx
import { StreamingContext } from 'hono/jsx/streaming'
const nonce = 'request-csp-nonce'
const app = (
Loading…
}>
)
```
## AI Coding Instructions
- Set the nonce from the request's Content Security Policy configuration.
- Wrap the streamed JSX tree with `StreamingContext.Provider` before rendering.
- Keep the nonce consistent with the nonce sent in the `Content-Security-Policy` response header.
- Use this context when `Suspense` or `ErrorBoundary` can emit inline streaming scripts.
## Relationships
- IMPORTS → `html`
- IMPORTS → `HtmlEscapedCallbackPhase`
- IMPORTS → `resolveCallback`
- IMPORTS → `JSXNode`
- IMPORTS → `childrenToString`
- IMPORTS → `DOM_RENDERER`
- IMPORTS → `DOM_STASH`
- IMPORTS → `captureRenderContext`
- IMPORTS → `createContext`
- IMPORTS → `useContext`
- IMPORTS → `Suspense`
- IMPORTS → `buildDataStack`
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `childrenToString` — `src/jsx/components.ts`:14
# getNameSpaceContext
**Kind:** Function
**Source:** [`src/jsx/base.ts`](https://github.com/honojs/hono/blob/main/src/jsx/base.ts#L56)
**Part of:** [Jsx](subsystem-src-jsx)
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `title` — `src/jsx/intrinsic-element/components.ts`:121
# getNameSpaceContext
**Kind:** Function
**Source:** [`src/jsx/dom/render.ts`](https://github.com/honojs/hono/blob/main/src/jsx/dom/render.ts#L111)
**Part of:** [Jsx](subsystem-src-jsx)
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `clearCache` — `src/jsx/dom/intrinsic-element/components.ts`:18
# STASH_EFFECT
**Kind:** Constant
**Source:** [`src/jsx/hooks/index.ts`](https://github.com/honojs/hono/blob/main/src/jsx/hooks/index.ts#L9)
**Part of:** [Jsx](subsystem-src-jsx)
## Definition
```ts
1
```
## Value
```ts
1
```
## Relationships
- IMPORTS → `DOM_STASH`
- IMPORTS → `buildDataStack`
- IMPORTS → `update`
## Used by
1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.
### Imported by (1)
- `HasRenderToDom` — `src/jsx/dom/render.ts`:30
# build
**Kind:** Function
**Source:** [`src/jsx/dom/render.ts`](https://github.com/honojs/hono/blob/main/src/jsx/dom/render.ts#L497)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function build(context: Context, node: NodeObject, children: Child[]): void
```
## Parameters
| Name | Type |
|---|---|
| `context` | `Context` |
| `node` | `NodeObject` |
| `children` | `Child[]` |
**Returns:** `void`
# ErrorBoundary
**Kind:** Function
**Source:** [`src/jsx/components.ts`](https://github.com/honojs/hono/blob/main/src/jsx/components.ts#L55)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
async function ErrorBoundary({ children, fallback, fallbackRender, onError })
```
## Parameters
| Name | Type |
|---|---|
| `{ children, fallback, fallbackRender, onError }` | `any` |
# useSyncExternalStore
**Kind:** Function
**Source:** [`src/jsx/hooks/index.ts`](https://github.com/honojs/hono/blob/main/src/jsx/hooks/index.ts#L401)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function useSyncExternalStore(subscribe: (callback: () => void) => () => void, getSnapshot: () => T, getServerSnapshot: () => T): T
```
## Parameters
| Name | Type |
|---|---|
| `subscribe` | `(callback: () => void) => () => void` |
| `getSnapshot` | `() => T` |
| `getServerSnapshot` | `() => T` |
**Returns:** `T`
# cloneElement
**Kind:** Function
**Source:** [`src/jsx/base.ts`](https://github.com/honojs/hono/blob/main/src/jsx/base.ts#L440)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function cloneElement(element: T, props: Partial, children: Child[]): T
```
## Parameters
| Name | Type |
|---|---|
| `element` | `T` |
| `props` | `Partial` |
| `children` | `Child[]` |
**Returns:** `T`
# createRoot
**Kind:** Function
**Source:** [`src/jsx/dom/client.ts`](https://github.com/honojs/hono/blob/main/src/jsx/dom/client.ts#L23)
**Part of:** [Jsx](subsystem-src-jsx)
Create a root object for rendering
`createRoot` creates a root object bound to a DOM container for JSX rendering. Use the returned root to render application content into that container and manage its mounted output.
## Signature
```ts
function createRoot(element: HTMLElement | DocumentFragment, options: RootOptions): Root
```
## Parameters
| Name | Type |
|---|---|
| `element` | `HTMLElement | DocumentFragment` |
| `options` | `RootOptions` |
**Returns:** `Root`
## Diagram
```mermaid
graph LR
Container[DOM container] --> CreateRoot[createRoot]
CreateRoot --> Root[Root object]
Root --> Render[render JSX]
Render --> DOM[Rendered DOM]
```
## Usage
```ts
import { createRoot } from "./jsx/dom/client";
const container = document.getElementById("app");
if (container) {
const root = createRoot(container);
root.render(Hello, world!);
}
```
## AI Coding Instructions
- Pass a valid DOM container to `createRoot` before rendering JSX.
- Keep the returned root instance and call its rendering methods instead of creating a new root for each update.
- Create the root at the application entry point where the target container is available.
- Ensure JSX output is rendered through the root associated with the intended container.
# composeRef
**Kind:** Function
**Source:** [`src/jsx/dom/intrinsic-element/components.ts`](https://github.com/honojs/hono/blob/main/src/jsx/dom/intrinsic-element/components.ts#L24)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function composeRef(ref: RefObject | Function | undefined, cb: (e: T) => void | (() => void)): ((e: T) => () => void)
```
## Parameters
| Name | Type |
|---|---|
| `ref` | `RefObject | Function | undefined` |
| `cb` | `(e: T) => void | (() => void)` |
**Returns:** `((e: T) => () => void)`
# jsxAttr
**Kind:** Function
**Source:** [`src/jsx/jsx-runtime.ts`](https://github.com/honojs/hono/blob/main/src/jsx/jsx-runtime.ts#L16)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function jsxAttr(key: string, v: string | Promise | Record): HtmlEscapedString | Promise
```
## Parameters
| Name | Type |
|---|---|
| `key` | `string` |
| `v` | `string | Promise | Record` |
**Returns:** `HtmlEscapedString | Promise`
## Relationships
- IMPORTS → `html`
- IMPORTS → `html`
- IMPORTS → `escapeToBuffer`
- IMPORTS → `stringBufferToString`
- IMPORTS → `isValidAttributeName`
- IMPORTS → `styleObjectForEach`
- IMPORTS → `jsxDEV`
- IMPORTS → `jsxDEV`
# Suspense
**Kind:** Function
**Source:** [`src/jsx/streaming.ts`](https://github.com/honojs/hono/blob/main/src/jsx/streaming.ts#L42)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
async function Suspense({
children,
fallback,
})
```
## Parameters
| Name | Type |
|---|---|
| `{
children,
fallback,
}` | `any` |
# useReducer
**Kind:** Function
**Source:** [`src/jsx/hooks/index.ts`](https://github.com/honojs/hono/blob/main/src/jsx/hooks/index.ts#L245)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function useReducer(reducer: (state: T, action: A) => T, initialArg: T, init: (initialState: T) => T): [T, (action: A) => void]
```
## Parameters
| Name | Type |
|---|---|
| `reducer` | `(state: T, action: A) => T` |
| `initialArg` | `T` |
| `init` | `(initialState: T) => T` |
**Returns:** `[T, (action: A) => void]`
# form
**Kind:** Function
**Source:** [`src/jsx/dom/intrinsic-element/components.ts`](https://github.com/honojs/hono/blob/main/src/jsx/dom/intrinsic-element/components.ts#L319)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function form(props)
```
## Parameters
| Name | Type |
|---|---|
| `props` | `any` |
# jsxDEV
**Kind:** Function
**Source:** [`src/jsx/dom/jsx-dev-runtime.ts`](https://github.com/honojs/hono/blob/main/src/jsx/dom/jsx-dev-runtime.ts#L10)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function jsxDEV(tag: string | Function, props: Props, key: string): JSXNode
```
## Parameters
| Name | Type |
|---|---|
| `tag` | `string | Function` |
| `props` | `Props` |
| `key` | `string` |
**Returns:** `JSXNode`
## Relationships
- IMPORTS → `clearCache`
# shallowEqual
**Kind:** Function
**Source:** [`src/jsx/base.ts`](https://github.com/honojs/hono/blob/main/src/jsx/base.ts#L376)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function shallowEqual(a: Props, b: Props): boolean
```
## Parameters
| Name | Type |
|---|---|
| `a` | `Props` |
| `b` | `Props` |
**Returns:** `boolean`
# useActionState
**Kind:** Function
**Source:** [`src/jsx/dom/hooks/index.ts`](https://github.com/honojs/hono/blob/main/src/jsx/dom/hooks/index.ts#L79)
**Part of:** [Jsx](subsystem-src-jsx)
This hook returns the current state and a function to update the state by form action
`useActionState` stores state produced by a form action and returns that state with a function for submitting updates. Pass the returned action function to a form’s `action` prop so form data can drive the next state.
## Signature
```ts
function useActionState(fn: Function, initialState: T, permalink: string): [T, Function]
```
## Parameters
| Name | Type |
|---|---|
| `fn` | `Function` |
| `initialState` | `T` |
| `permalink` | `string` |
**Returns:** `[T, Function]`
## Diagram
```mermaid
graph LR
Form[Form submission] --> Action[Action function]
Action --> Hook[useActionState]
Hook --> State[Current state]
Hook --> FormAction[Form action handler]
FormAction --> Form
```
## Usage
```tsx
import { useActionState } from "your-library";
type FormState = {
message: string;
};
async function saveName(
previousState: FormState,
formData: FormData,
): Promise {
const name = formData.get("name");
if (typeof name !== "string" || name.trim() === "") {
return { message: "Enter a name." };
}
await saveProfile({ name });
return { message: `Saved ${name}.` };
}
export function ProfileForm() {
const [state, formAction] = useActionState(saveName, {
message: "",
});
return (
);
}
```
## AI Coding Instructions
- Pass an action function that accepts the previous state and submitted form data, then returns the next state.
- Keep the initial state shape aligned with every state returned by the action.
- Attach the returned action function directly to a form’s `action` prop.
- Validate `FormData` values before using them, since values may be missing or have an unexpected type.
# useImperativeHandle
**Kind:** Function
**Source:** [`src/jsx/hooks/index.ts`](https://github.com/honojs/hono/blob/main/src/jsx/hooks/index.ts#L388)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function useImperativeHandle(ref: RefObject, createHandle: () => T, deps: readonly unknown[]): void
```
## Parameters
| Name | Type |
|---|---|
| `ref` | `RefObject` |
| `createHandle` | `() => T` |
| `deps` | `readonly unknown[]` |
**Returns:** `void`
# hydrateRoot
**Kind:** Function
**Source:** [`src/jsx/dom/client.ts`](https://github.com/honojs/hono/blob/main/src/jsx/dom/client.ts#L76)
**Part of:** [Jsx](subsystem-src-jsx)
Create a root object and hydrate app to the target element.
In hono/jsx/dom, hydrate is equivalent to render.
`hydrateRoot` creates a root object for a target DOM element and hydrates the application into that element. In `hono/jsx/dom`, hydration follows the same rendering behavior as `render`, connecting JSX output to the existing target container.
## Signature
```ts
function hydrateRoot(element: HTMLElement | DocumentFragment, reactNode: Child, options: RootOptions): Root
```
## Parameters
| Name | Type |
|---|---|
| `element` | `HTMLElement | DocumentFragment` |
| `reactNode` | `Child` |
| `options` | `RootOptions` |
**Returns:** `Root`
## Diagram
```mermaid
graph LR
App[JSX application] --> Hydrate[hydrateRoot]
Target[Target DOM element] --> Hydrate
Hydrate --> Root[Root object]
Root --> DOM[Rendered DOM]
```
## Usage
```tsx
import { hydrateRoot } from 'hono/jsx/dom/client'
import { App } from './app'
const container = document.getElementById('app')
if (container) {
hydrateRoot(container, )
}
```
## AI Coding Instructions
- Pass the DOM element that should contain the application as the first argument.
- Pass the application JSX node as the second argument.
- Keep client entry code responsible for locating the target element before calling `hydrateRoot`.
- Treat hydration in `hono/jsx/dom` the same way as rendering when integrating application startup code.
# useDeferredValue
**Kind:** Function
**Source:** [`src/jsx/hooks/index.ts`](https://github.com/honojs/hono/blob/main/src/jsx/hooks/index.ts#L158)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function useDeferredValue(value: T, rest: [T | undefined]): T
```
## Parameters
| Name | Type |
|---|---|
| `value` | `T` |
| `rest` | `[T | undefined]` |
**Returns:** `T`
# useOptimistic
**Kind:** Function
**Source:** [`src/jsx/dom/hooks/index.ts`](https://github.com/honojs/hono/blob/main/src/jsx/dom/hooks/index.ts#L52)
**Part of:** [Jsx](subsystem-src-jsx)
This hook returns the current state and a function to update the state optimistically
The current state is updated optimistically and then reverted to the original state when all actions are resolved
`useOptimistic` returns the current optimistic state and a function that applies an optimistic update. Updates are shown immediately while related actions are pending, then the state returns to the original value after those actions resolve.
## Signature
```ts
function useOptimistic(state: T, updateState: (currentState: T, action: N) => T): [T, (action: N) => void]
```
## Parameters
| Name | Type |
|---|---|
| `state` | `T` |
| `updateState` | `(currentState: T, action: N) => T` |
**Returns:** `[T, (action: N) => void]`
## Diagram
```mermaid
graph LR
A[Current state] --> B[useOptimistic]
B --> C[Optimistic state]
D[Pending action] --> E[Apply optimistic update]
E --> C
D --> F[Action resolves]
F --> A
```
## Usage
```tsx
import { useOptimistic } from "react";
function LikeButton({ likes }: { likes: number }) {
const [optimisticLikes, addOptimisticLike] = useOptimistic(
likes,
(currentLikes, increment: number) => currentLikes + increment,
);
async function handleLike() {
addOptimisticLike(1);
await fetch("/api/likes", {
method: "POST",
});
}
return (
);
}
```
## AI Coding Instructions
- Pass the confirmed server or parent state as the base value for `useOptimistic`.
- Define the update function as a pure function that derives optimistic state from the current state and action input.
- Call the optimistic update function as part of the action that performs the related asynchronous work.
- Do not treat optimistic state as the source of truth; update the base state when the action result is available.
- Handle action failures so the surrounding state remains consistent after optimistic updates are reverted.
# createCssContext
**Kind:** Function
**Source:** [`src/jsx/dom/css.ts`](https://github.com/honojs/hono/blob/main/src/jsx/dom/css.ts#L180)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function createCssContext({
id,
classNameSlug,
onInvalidSlug,
}: { id: Readonly classNameSlug?: ClassNameSlug onInvalidSlug?: OnInvalidSlug }): DefaultContextType
```
## Parameters
| Name | Type |
|---|---|
| `{
id,
classNameSlug,
onInvalidSlug,
}` | `{ id: Readonly classNameSlug?: ClassNameSlug onInvalidSlug?: OnInvalidSlug }` |
**Returns:** `DefaultContextType`
# memo
**Kind:** Function
**Source:** [`src/jsx/base.ts`](https://github.com/honojs/hono/blob/main/src/jsx/base.ts#L406)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function memo(component: FC, propsAreEqual: (prevProps: Readonly, nextProps: Readonly) => boolean): FC
```
## Parameters
| Name | Type |
|---|---|
| `component` | `FC` |
| `propsAreEqual` | `(prevProps: Readonly, nextProps: Readonly) => boolean` |
**Returns:** `FC`
# flushSync
**Kind:** Function
**Source:** [`src/jsx/dom/render.ts`](https://github.com/honojs/hono/blob/main/src/jsx/dom/render.ts#L801)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function flushSync(callback: () => void): void
```
## Parameters
| Name | Type |
|---|---|
| `callback` | `() => void` |
**Returns:** `void`
# link
**Kind:** Function
**Source:** [`src/jsx/dom/intrinsic-element/components.ts`](https://github.com/honojs/hono/blob/main/src/jsx/dom/intrinsic-element/components.ts#L298)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function link(props)
```
## Parameters
| Name | Type |
|---|---|
| `props` | `any` |
# script
**Kind:** Function
**Source:** [`src/jsx/intrinsic-element/components.ts`](https://github.com/honojs/hono/blob/main/src/jsx/intrinsic-element/components.ts#L136)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function script({
children,
...props
})
```
## Parameters
| Name | Type |
|---|---|
| `{
children,
...props
}` | `any` |
# style
**Kind:** Function
**Source:** [`src/jsx/dom/intrinsic-element/components.ts`](https://github.com/honojs/hono/blob/main/src/jsx/dom/intrinsic-element/components.ts#L284)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function style(props)
```
## Parameters
| Name | Type |
|---|---|
| `props` | `any` |
# title
**Kind:** Function
**Source:** [`src/jsx/dom/intrinsic-element/components.ts`](https://github.com/honojs/hono/blob/main/src/jsx/dom/intrinsic-element/components.ts#L257)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function title(props)
```
## Parameters
| Name | Type |
|---|---|
| `props` | `any` |
# form
**Kind:** Function
**Source:** [`src/jsx/intrinsic-element/components.ts`](https://github.com/honojs/hono/blob/main/src/jsx/intrinsic-element/components.ts#L182)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function form(props)
```
## Parameters
| Name | Type |
|---|---|
| `props` | `any` |
# render
**Kind:** Function
**Source:** [`src/jsx/dom/render.ts`](https://github.com/honojs/hono/blob/main/src/jsx/dom/render.ts#L796)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function render(jsxNode: Child, container: Container): void
```
## Parameters
| Name | Type |
|---|---|
| `jsxNode` | `Child` |
| `container` | `Container` |
**Returns:** `void`
# Root
**Kind:** Interface
**Source:** [`src/jsx/dom/client.ts`](https://github.com/honojs/hono/blob/main/src/jsx/dom/client.ts#L11)
**Part of:** [Jsx](subsystem-src-jsx)
`Root` represents a mounted JSX DOM tree created by the client renderer. It exposes methods to render the tree and to remove the mounted tree from its container.
## Diagram
```mermaid
graph LR
App[JSX application] --> Root[Root]
Root --> Render[render()]
Root --> Unmount[unmount()]
Render --> DOM[DOM container]
Unmount --> DOM
```
## Usage
```ts
import { createRoot } from "./jsx/dom/client";
const container = document.getElementById("app");
if (!container) {
throw new Error("Missing app container");
}
const root = createRoot(container);
root.render();
window.addEventListener("beforeunload", () => {
root.unmount();
});
```
## AI Coding Instructions
- Call `render()` after creating a `Root` to mount or update its JSX DOM tree.
- Call `unmount()` when the owning application or view is removed.
- Keep the `Root` instance associated with the DOM container it was created for.
- Do not call `render()` after `unmount()` unless the client renderer supports remounting.
## How it works
`Root` is the interface for the object returned by `createRoot`. It has two void-returning lifecycle methods: `render(children: Child)` and `unmount()` ([src/jsx/dom/client.ts:11-14](src/jsx/dom/client.ts#L11-L14)). `Child` includes strings, numbers, JSX nodes, `null`, `undefined`, booleans, promises of strings, and nested child arrays ([src/jsx/base.ts:162-170](src/jsx/base.ts#L162-L170)).
- **Creation:** `createRoot` accepts an `HTMLElement` or `DocumentFragment` render target and returns a `Root` ([src/jsx/dom/client.ts:23-26](src/jsx/dom/client.ts#L23-L26)). Passing a non-empty options object writes `createRoot options are not supported yet` to `console.warn` ([src/jsx/dom/client.ts:33-35](src/jsx/dom/client.ts#L33-L35)).
- **`render(children)`:** On its first call, the root creates a function node whose state is initialized from the passed value; it retains that state setter for later calls ([src/jsx/dom/client.ts:47-58](src/jsx/dom/client.ts#L47-L58)). The DOM renderer builds this node, applies it into a `DocumentFragment`, then replaces every child of the target container with that fragment ([src/jsx/dom/render.ts:783-794](src/jsx/dom/render.ts#L783-L794)). On later calls, `render` passes the new value to the retained state setter ([src/jsx/dom/client.ts:43-45](src/jsx/dom/client.ts#L43-L45)); the setter changes state only when the new value is not `Object.is`-equal to the current value and then schedules an update ([src/jsx/hooks/index.ts:199-240](src/jsx/hooks/index.ts#L199-L240)).
- **`unmount()`:** If the root has rendered, `unmount` calls its stored state setter with `null`, then marks the root as unmounted ([src/jsx/dom/client.ts:61-64](src/jsx/dom/client.ts#L61-L64)). A later `render` call throws `Error('Cannot update an unmounted root')` ([src/jsx/dom/client.ts:38-42](src/jsx/dom/client.ts#L38-L42)). Calling `unmount` before the first render does not invoke a setter, but still marks the root unmounted ([src/jsx/dom/client.ts:27-31](src/jsx/dom/client.ts#L27-L31), [src/jsx/dom/client.ts:61-64](src/jsx/dom/client.ts#L61-L64)).
## Relationships
- IMPORTS → `useState`
- IMPORTS → `buildNode`
- IMPORTS → `renderNode`
# script
**Kind:** Function
**Source:** [`src/jsx/dom/intrinsic-element/components.ts`](https://github.com/honojs/hono/blob/main/src/jsx/dom/intrinsic-element/components.ts#L272)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function script(props)
```
## Parameters
| Name | Type |
|---|---|
| `props` | `any` |
# style
**Kind:** Function
**Source:** [`src/jsx/intrinsic-element/components.ts`](https://github.com/honojs/hono/blob/main/src/jsx/intrinsic-element/components.ts#L151)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function style({
children,
...props
})
```
## Parameters
| Name | Type |
|---|---|
| `{
children,
...props
}` | `any` |
# useInsertionEffect
**Kind:** Function
**Source:** [`src/jsx/hooks/index.ts`](https://github.com/honojs/hono/blob/main/src/jsx/hooks/index.ts#L294)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function useInsertionEffect(effect: () => void | (() => void), deps: readonly unknown[]): void
```
## Parameters
| Name | Type |
|---|---|
| `effect` | `() => void | (() => void)` |
| `deps` | `readonly unknown[]` |
**Returns:** `void`
# useLayoutEffect
**Kind:** Function
**Source:** [`src/jsx/hooks/index.ts`](https://github.com/honojs/hono/blob/main/src/jsx/hooks/index.ts#L290)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function useLayoutEffect(effect: () => void | (() => void), deps: readonly unknown[]): void
```
## Parameters
| Name | Type |
|---|---|
| `effect` | `() => void | (() => void)` |
| `deps` | `readonly unknown[]` |
**Returns:** `void`
# useRef
**Kind:** Function
**Source:** [`src/jsx/hooks/index.ts`](https://github.com/honojs/hono/blob/main/src/jsx/hooks/index.ts#L323)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function useRef(initialValue: T | null): RefObject
```
## Parameters
| Name | Type |
|---|---|
| `initialValue` | `T | null` |
**Returns:** `RefObject`
# useRef
**Kind:** Function
**Source:** [`src/jsx/hooks/index.ts`](https://github.com/honojs/hono/blob/main/src/jsx/hooks/index.ts#L323)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function useRef(initialValue: T | null): RefObject
```
## Parameters
| Name | Type |
|---|---|
| `initialValue` | `T | null` |
**Returns:** `RefObject`
# useRef
**Kind:** Function
**Source:** [`src/jsx/hooks/index.ts`](https://github.com/honojs/hono/blob/main/src/jsx/hooks/index.ts#L323)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function useRef(initialValue: T | null): RefObject
```
## Parameters
| Name | Type |
|---|---|
| `initialValue` | `T | null` |
**Returns:** `RefObject`
# useRef
**Kind:** Function
**Source:** [`src/jsx/hooks/index.ts`](https://github.com/honojs/hono/blob/main/src/jsx/hooks/index.ts#L323)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function useRef(initialValue: T | null): RefObject
```
## Parameters
| Name | Type |
|---|---|
| `initialValue` | `T | null` |
**Returns:** `RefObject`
# forwardRef
**Kind:** Function
**Source:** [`src/jsx/hooks/index.ts`](https://github.com/honojs/hono/blob/main/src/jsx/hooks/index.ts#L379)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function forwardRef(Component: (props: P, ref?: RefObject) => JSX.Element): ((props: P & { ref?: RefObject }) => JSX.Element)
```
## Parameters
| Name | Type |
|---|---|
| `Component` | `(props: P, ref?: RefObject) => JSX.Element` |
**Returns:** `((props: P & { ref?: RefObject }) => JSX.Element)`
# link
**Kind:** Function
**Source:** [`src/jsx/intrinsic-element/components.ts`](https://github.com/honojs/hono/blob/main/src/jsx/intrinsic-element/components.ts#L162)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function link({ children, ...props })
```
## Parameters
| Name | Type |
|---|---|
| `{ children, ...props }` | `any` |
# startViewTransition
**Kind:** Function
**Source:** [`src/jsx/hooks/index.ts`](https://github.com/honojs/hono/blob/main/src/jsx/hooks/index.ts#L79)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function startViewTransition(callback: () => void): void
```
## Parameters
| Name | Type |
|---|---|
| `callback` | `() => void` |
**Returns:** `void`
# meta
**Kind:** Function
**Source:** [`src/jsx/intrinsic-element/components.ts`](https://github.com/honojs/hono/blob/main/src/jsx/intrinsic-element/components.ts#L171)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function meta({ children, ...props })
```
## Parameters
| Name | Type |
|---|---|
| `{ children, ...props }` | `any` |
# booleanAttributes
**Kind:** Constant
**Source:** [`src/jsx/base.ts`](https://github.com/honojs/hono/blob/main/src/jsx/base.ts#L85)
**Part of:** [Jsx](subsystem-src-jsx)
## Definition
```ts
[
'allowfullscreen',
'async',
'autofocus',
'autoplay',
'checked',
'controls',
'default',
'defer',
'disabled',
'download',
'formnovalidate',
'hidden',
'inert',
'ismap',
'itemscope',
'loop',
'multiple',
'muted',
'nomodule',
'novalidate',
'open',
'playsinline',
'readonly',
'required',
'reversed',
'selected',
]
```
## Value
```ts
[
'allowfullscreen',
'async',
'autofocus',
'autoplay',
'checked',
'controls',
'default',
'defer',
'disabled',
'download',
'formnovalidate',
'hidden',
'inert',
'ismap',
'itemscope',
'loop',
'multiple',
'muted',
'nomodule',
'novalidate',
'open',
'playsinline',
'readonly',
'required',
'reversed',
'selected',
]
```
# useEffect
**Kind:** Function
**Source:** [`src/jsx/hooks/index.ts`](https://github.com/honojs/hono/blob/main/src/jsx/hooks/index.ts#L288)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function useEffect(effect: () => void | (() => void), deps: readonly unknown[]): void
```
## Parameters
| Name | Type |
|---|---|
| `effect` | `() => void | (() => void)` |
| `deps` | `readonly unknown[]` |
**Returns:** `void`
# useTransition
**Kind:** Function
**Source:** [`src/jsx/hooks/index.ts`](https://github.com/honojs/hono/blob/main/src/jsx/hooks/index.ts#L126)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function useTransition(): [boolean, (callback: () => void | Promise) => void]
```
**Returns:** `[boolean, (callback: () => void | Promise) => void]`
# NodeObject
**Kind:** Type
**Source:** [`src/jsx/dom/render.ts`](https://github.com/honojs/hono/blob/main/src/jsx/dom/render.ts#L41)
**Part of:** [Jsx](subsystem-src-jsx)
## Definition
```ts
{ pP: Props | undefined nN: Node | undefined vC: Node[] pC?: Node[] vR: Node[] n?: string f?: boolean s?: boolean c: Container | undefined e: SupportedElement | Text | undefined p?: PreserveNodeType a?: boolean o?: NodeObject [DOM_STASH]: | [ number, any[][], LocalJSXContexts, [Context, Function, NodeObject], ] | [number, any[][]] } & JSXNode
```
# isValidElement
**Kind:** Function
**Source:** [`src/jsx/base.ts`](https://github.com/honojs/hono/blob/main/src/jsx/base.ts#L436)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function isValidElement(element: unknown): element is JSXNode
```
## Parameters
| Name | Type |
|---|---|
| `element` | `unknown` |
**Returns:** `element is JSXNode`
# meta
**Kind:** Function
**Source:** [`src/jsx/dom/intrinsic-element/components.ts`](https://github.com/honojs/hono/blob/main/src/jsx/dom/intrinsic-element/components.ts#L314)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function meta(props)
```
## Parameters
| Name | Type |
|---|---|
| `props` | `any` |
# startTransition
**Kind:** Function
**Source:** [`src/jsx/hooks/index.ts`](https://github.com/honojs/hono/blob/main/src/jsx/hooks/index.ts#L119)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function startTransition(callback: () => void): void
```
## Parameters
| Name | Type |
|---|---|
| `callback` | `() => void` |
**Returns:** `void`
# useDebugValue
**Kind:** Function
**Source:** [`src/jsx/hooks/index.ts`](https://github.com/honojs/hono/blob/main/src/jsx/hooks/index.ts#L373)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function useDebugValue(_value: unknown, _formatter: (value: unknown) => string): void
```
## Parameters
| Name | Type |
|---|---|
| `_value` | `unknown` |
| `_formatter` | `(value: unknown) => string` |
**Returns:** `void`
# Children
**Kind:** Constant
**Source:** [`src/jsx/children.ts`](https://github.com/honojs/hono/blob/main/src/jsx/children.ts#L5)
**Part of:** [Jsx](subsystem-src-jsx)
## Definition
```ts
{
map: (children: Child[], fn: (child: Child, index: number) => Child): Child[] =>
toArray(children).map(fn),
forEach: (children: Child[], fn: (child: Child, index: number) => void): void => {
toArray(children).forEach(fn)
},
count: (children: Child[]): number => toArray(children).length,
only: (_children: Child[]): Child => {
const children = toArray(_children)
if (child…
```
## Value
```ts
{
map: (children: Child[], fn: (child: Child, index: number) => Child): Child[] =>
toArray(children).map(fn),
forEach: (children: Child[], fn: (child: Child, index: number) => void): void => {
toArray(children).forEach(fn)
},
count: (children: Child[]): number => toArray(children).length,
only: (_children: Child[]): Child => {
const children = toArray(_children)
if (child…
```
# Context
**Kind:** Type
**Source:** [`src/jsx/dom/render.ts`](https://github.com/honojs/hono/blob/main/src/jsx/dom/render.ts#L91)
**Part of:** [Jsx](subsystem-src-jsx)
## Definition
```ts
| [ PendingType, boolean, UpdateHook, boolean, boolean, [Context, Function, NodeObject][], ] | [PendingType, boolean, UpdateHook, boolean] | [PendingType, boolean, UpdateHook] | [PendingType, boolean] | [PendingType] | []
```
# button
**Kind:** Function
**Source:** [`src/jsx/dom/intrinsic-element/components.ts`](https://github.com/honojs/hono/blob/main/src/jsx/dom/intrinsic-element/components.ts#L426)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function button(props)
```
## Parameters
| Name | Type |
|---|---|
| `props` | `any` |
# button
**Kind:** Function
**Source:** [`src/jsx/intrinsic-element/components.ts`](https://github.com/honojs/hono/blob/main/src/jsx/intrinsic-element/components.ts#L209)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function button(props)
```
## Parameters
| Name | Type |
|---|---|
| `props` | `any` |
# input
**Kind:** Function
**Source:** [`src/jsx/dom/intrinsic-element/components.ts`](https://github.com/honojs/hono/blob/main/src/jsx/dom/intrinsic-element/components.ts#L423)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function input(props)
```
## Parameters
| Name | Type |
|---|---|
| `props` | `any` |
# input
**Kind:** Function
**Source:** [`src/jsx/intrinsic-element/components.ts`](https://github.com/honojs/hono/blob/main/src/jsx/intrinsic-element/components.ts#L207)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function input(props)
```
## Parameters
| Name | Type |
|---|---|
| `props` | `any` |
# RenderToReadableStreamOptions
**Kind:** Interface
**Source:** [`src/jsx/dom/server.ts`](https://github.com/honojs/hono/blob/main/src/jsx/dom/server.ts#L32)
**Part of:** [Jsx](subsystem-src-jsx)
`RenderToReadableStreamOptions` configures how server-rendered JSX is emitted as a readable stream. It controls identifier and namespace settings, bootstrap scripts, chunking behavior, cancellation through an `AbortSignal`, and error handling.
## Properties
| Property | Type |
|---|---|
| `identifierPrefix` | `string` |
| `namespaceURI` | `string` |
| `nonce` | `string` |
| `bootstrapScriptContent` | `string` |
| `bootstrapScripts` | `string[]` |
| `bootstrapModules` | `string[]` |
| `progressiveChunkSize` | `number` |
| `signal` | `AbortSignal` |
| `onError` | `(error: unknown) => string | void` |
## Diagram
```mermaid
graph LR
App[JSX application] --> Render[renderToReadableStream]
Options[RenderToReadableStreamOptions] --> Render
Options --> IDs[identifierPrefix]
Options --> Namespace[namespaceURI]
Options --> Scripts[Bootstrap scripts and modules]
Options --> Stream[progressiveChunkSize]
Options --> Abort[signal]
Options --> Errors[onError]
Render --> Output[ReadableStream]
```
## Usage
```ts
import { renderToReadableStream } from "react-dom/server";
import type { RenderToReadableStreamOptions } from "react-dom/server";
const controller = new AbortController();
const options: RenderToReadableStreamOptions = {
identifierPrefix: "app-",
namespaceURI: "http://www.w3.org/2000/svg",
nonce: "request-nonce",
bootstrapScriptContent: "window.__SSR_READY__ = true;",
bootstrapScripts: ["/assets/client.js"],
bootstrapModules: ["/assets/client.mjs"],
signal: controller.signal,
onError(error) {
console.error("Server render failed:", error);
return "render-error";
},
};
const stream = await renderToReadableStream(, options);
return new Response(stream, {
headers: {
"Content-Type": "text/html",
},
});
```
## AI Coding Instructions
- Pass a stable `identifierPrefix` when multiple rendered roots can appear in the same document.
- Set `nonce` when the page uses a Content Security Policy that restricts inline scripts.
- Use either `bootstrapScripts` or `bootstrapModules` according to the client asset format being loaded.
- Pass a request-scoped `AbortSignal` so rendering stops when the client disconnects or the request is cancelled.
- Handle errors in `onError`; return a string when the renderer needs an error identifier, or return `void` after logging the error.
## How it works
`RenderToReadableStreamOptions` is the exported TypeScript interface for the optional second argument to `renderToReadableStream`; every member is optional. [src/jsx/dom/server.ts:32-42](src/jsx/dom/server.ts#L32-L42) [src/jsx/dom/server.ts:50-53](src/jsx/dom/server.ts#L50-L53)
Its declared members are:
- `identifierPrefix?: string`
- `namespaceURI?: string`
- `nonce?: string`
- `bootstrapScriptContent?: string`
- `bootstrapScripts?: string[]`
- `bootstrapModules?: string[]`
- `progressiveChunkSize?: number`
- `signal?: AbortSignal`
- `onError?: (error: unknown) => string | void`
[src/jsx/dom/server.ts:32-42](src/jsx/dom/server.ts#L32-L42)
At runtime, `renderToReadableStream` checks the option object’s keys. If it contains any key other than `onError`, it calls `console.warn('options are not supported yet, except onError')`. [src/jsx/dom/server.ts:54-56](src/jsx/dom/server.ts#L54-L56) The function forwards only `options.onError` to the underlying streaming renderer. [src/jsx/dom/server.ts:62](src/jsx/dom/server.ts#L62)
Consequently, the source does not show runtime handling for `identifierPrefix`, `namespaceURI`, `nonce`, `bootstrapScriptContent`, `bootstrapScripts`, `bootstrapModules`, `progressiveChunkSize`, or `signal`; their presence triggers the warning above. [src/jsx/dom/server.ts:32-42](src/jsx/dom/server.ts#L32-L42) [src/jsx/dom/server.ts:54-56](src/jsx/dom/server.ts#L54-L56) [src/jsx/dom/server.ts:62](src/jsx/dom/server.ts#L62)
`onError` is used by the underlying renderer for errors during stream startup and for rejected deferred callbacks. If absent, that renderer defaults it to `console.trace`. [src/jsx/streaming.ts:146-149](src/jsx/streaming.ts#L146-L149) Rejected deferred callbacks are logged with `console.log`, passed to `onError`, and replaced with an empty string for subsequent processing. [src/jsx/streaming.ts:171-195](src/jsx/streaming.ts#L171-L195) Errors caught while starting the stream are passed to `onError`; after the `try`/`catch`, the stream is closed unless it was cancelled. [src/jsx/streaming.ts:152-167](src/jsx/streaming.ts#L152-L167) [src/jsx/streaming.ts:203-217](src/jsx/streaming.ts#L203-L217)
# useViewTransition
**Kind:** Function
**Source:** [`src/jsx/hooks/index.ts`](https://github.com/honojs/hono/blob/main/src/jsx/hooks/index.ts#L89)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function useViewTransition(): [boolean, (callback: () => void) => void]
```
**Returns:** `[boolean, (callback: () => void) => void]`
# Child
**Kind:** Type
**Source:** [`src/jsx/base.ts`](https://github.com/honojs/hono/blob/main/src/jsx/base.ts#L162)
**Part of:** [Jsx](subsystem-src-jsx)
## Definition
```ts
| string | Promise | number | JSXNode | null | undefined | boolean | Child[]
```
# EffectData
**Kind:** Type
**Source:** [`src/jsx/hooks/index.ts`](https://github.com/honojs/hono/blob/main/src/jsx/hooks/index.ts#L14)
**Part of:** [Jsx](subsystem-src-jsx)
## Definition
```ts
[ readonly unknown[] | undefined, (() => void | (() => void)) | undefined, (() => void) | undefined, (() => void) | undefined, (() => void) | undefined, ]
```
# Fragment
**Kind:** Function
**Source:** [`src/jsx/dom/jsx-dev-runtime.ts`](https://github.com/honojs/hono/blob/main/src/jsx/dom/jsx-dev-runtime.ts#L23)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function Fragment(props: Record): JSXNode
```
## Parameters
| Name | Type |
|---|---|
| `props` | `Record` |
**Returns:** `JSXNode`
# jsxEscape
**Kind:** Function
**Source:** [`src/jsx/jsx-runtime.ts`](https://github.com/honojs/hono/blob/main/src/jsx/jsx-runtime.ts#L51)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function jsxEscape(value: string)
```
## Parameters
| Name | Type |
|---|---|
| `value` | `string` |
# UpdateHook
**Kind:** Type
**Source:** [`src/jsx/dom/render.ts`](https://github.com/honojs/hono/blob/main/src/jsx/dom/render.ts#L86)
**Part of:** [Jsx](subsystem-src-jsx)
## Definition
```ts
( context: Context, node: Node, cb: (context: Context) => void ) => Promise
```
# Context
**Kind:** Interface
**Source:** [`src/jsx/context.ts`](https://github.com/honojs/hono/blob/main/src/jsx/context.ts#L8)
**Part of:** [Jsx](subsystem-src-jsx)
`Context` defines a context container with the available `values` and a React `Provider` component. The provider receives a current `value` and wraps child content so the selected context value can be supplied within the JSX tree.
## Properties
| Property | Type |
|---|---|
| `values` | `T[]` |
| `Provider` | `FC>` |
## Diagram
```mermaid
graph LR
Context["Context<T>"]
Values["values: T[]"]
Provider["Provider"]
Value["value: T"]
Children["children"]
Context --> Values
Context --> Provider
Provider --> Value
Provider --> Children
```
## Usage
```tsx
import type { FC, PropsWithChildren, ReactNode } from "react";
import type { Context } from "./context";
type Theme = "light" | "dark";
declare const ThemeProvider: FC>;
const themeContext: Context = {
values: ["light", "dark"],
Provider: ThemeProvider,
};
function WithTheme({
value,
children,
}: {
value: Theme;
children: ReactNode;
}) {
const Provider = themeContext.Provider;
return {children};
}
```
## AI Coding Instructions
- Keep `values` typed as the same generic type passed to `Context`.
- Pass a `value` prop to `Provider` whenever rendering it.
- Preserve `children` when wrapping content with a context provider.
- Define the provider with `FC>` so its value type matches the context values.
## Relationships
- IMPORTS → `html`
- IMPORTS → `JSXFragmentNode`
- IMPORTS → `DOM_RENDERER`
- IMPORTS → `createContextProviderFunction`
# PendingType
**Kind:** Type
**Source:** [`src/jsx/dom/render.ts`](https://github.com/honojs/hono/blob/main/src/jsx/dom/render.ts#L82)
**Part of:** [Jsx](subsystem-src-jsx)
## Definition
```ts
| 0 | 1 | 2
```
# createRef
**Kind:** Function
**Source:** [`src/jsx/hooks/index.ts`](https://github.com/honojs/hono/blob/main/src/jsx/hooks/index.ts#L375)
**Part of:** [Jsx](subsystem-src-jsx)
## Signature
```ts
function createRef(): RefObject
```
**Returns:** `RefObject`
# MemorableFC
**Kind:** Type
**Source:** [`src/jsx/base.ts`](https://github.com/honojs/hono/blob/main/src/jsx/base.ts#L403)
**Part of:** [Jsx](subsystem-src-jsx)
## Definition
```ts
FC & { [DOM_MEMO]: (prevProps: Readonly, nextProps: Readonly) => boolean }
```
# PreserveNodeType
**Kind:** Type
**Source:** [`src/jsx/dom/render.ts`](https://github.com/honojs/hono/blob/main/src/jsx/dom/render.ts#L37)
**Part of:** [Jsx](subsystem-src-jsx)
## Definition
```ts
| 1 | 2
```
# RenderToStringOptions
**Kind:** Interface
**Source:** [`src/jsx/dom/server.ts`](https://github.com/honojs/hono/blob/main/src/jsx/dom/server.ts#L11)
**Part of:** [Jsx](subsystem-src-jsx)
`RenderToStringOptions` configures server-side JSX rendering to a string. Its `identifierPrefix` field sets a prefix for generated identifiers, helping separate IDs when rendering multiple independent trees.
## Properties
| Property | Type |
|---|---|
| `identifierPrefix` | `string` |
## Diagram
```mermaid
graph LR
Options[RenderToStringOptions] --> Prefix[identifierPrefix: string]
Prefix --> Renderer[Server-side JSX renderer]
Renderer --> HTML[Rendered HTML string]
```
## Usage
```ts
import { renderToString } from "./jsx/dom/server";
const options: RenderToStringOptions = {
identifierPrefix: "profile-",
};
const html = renderToString(, options);
```
## AI Coding Instructions
- Pass `identifierPrefix` when rendered output may share a document with other rendered trees.
- Keep the prefix stable between server rendering and client hydration when generated IDs must match.
- Use distinct prefixes for separate application roots to avoid identifier collisions.
- Treat `identifierPrefix` as a string value; do not pass `null` or omit it when the calling API requires options.
## How it works
`RenderToStringOptions` is an exported TypeScript interface for the second argument of `renderToString`. It declares one optional string property, `identifierPrefix`. [src/jsx/dom/server.ts:11-13]
`renderToString` defaults its `options` argument to `{}`. [src/jsx/dom/server.ts:21] At runtime, it checks whether `options` has any own enumerable keys; when it does, it writes `options are not supported yet` through `console.warn`. [src/jsx/dom/server.ts:22-24] The implementation does not read `identifierPrefix` or otherwise apply an option value while producing the string. [src/jsx/dom/server.ts:21-29]
The rendering call can throw `Error('Async component is not supported in renderToString')` if `element?.toString() ?? ''` does not result in a string; this behavior is independent of `RenderToStringOptions`. [src/jsx/dom/server.ts:25-28]
## Relationships
- IMPORTS → `renderToReadableStream`
# useFormStatus
**Kind:** Function
**Source:** [`src/jsx/dom/hooks/index.ts`](https://github.com/honojs/hono/blob/main/src/jsx/dom/hooks/index.ts#L41)
**Part of:** [Jsx](subsystem-src-jsx)
This hook returns the current form status
`useFormStatus` reads the status associated with the nearest parent form while a form action is running. Call it from a component rendered inside that form to update UI based on the current status.
## Signature
```ts
function useFormStatus(): FormStatus
```
**Returns:** `FormStatus`
## Diagram
```mermaid
graph LR
Form[Form] --> Child[Child component]
Child --> Hook[useFormStatus]
Hook --> Status[Current form status]
Status --> UI[Button and feedback UI]
```
## Usage
```tsx
import { useFormStatus } from "react-dom";
function SubmitButton() {
const { pending } = useFormStatus();
return (
);
}
async function saveProfile(formData: FormData) {
await fetch("/api/profile", {
method: "POST",
body: formData,
});
}
export function ProfileForm() {
return (
);
}
```
## AI Coding Instructions
- Call `useFormStatus` from a component nested inside the related `