# Utils

## What it is responsible for

Utils turns request-facing and low-level values into reusable forms for the rest of the codebase. Its named entry points, `Accept`, `parseAccept`, `Auth`, and `auth`, mark where work enters; related members cover body parsing, cookies, binary-address conversion, MIME/type [helpers](subsystem-src-helper), URI decoding, and terminal-color decisions. `COMPRESSIBLE_CONTENT_TYPE_REGEX` marks a content-type-oriented rule, while `COMPOSED_HANDLER` is explicitly a marker for a composed handler. The subsystem also owns shared type-level shaping: JSON-compatible conversion, flattened editor hints, deep array traversal, and string-literal completion types.

## What it needs, and who needs it

Utils needs `Helper`, its only stated dependency. `src/router`, `src/middleware`, `Adapter`, `Helper`, `src/jsx`, and `src/validator` need Utils. Without Utils, those consumers lose access to the named shared entry points and helpers they depend on, including `parseBody`, `Cookie`, and `getColorEnabled`; the supplied evidence does not identify narrower failure modes or Helper’s specific role.

## Notable members

`parseBody` is the body-parsing member, paired with `ParseBodyOptions` and `BodyData`. `Cookie`, `SignedCookie`, and `CookieOptions` group parsing and serialization through `parse`, `parseSigned`, and `serialize`. `getColorEnabled` and `getColorEnabledAsync` report whether color change on a terminal is enabled or disabled. Address conversion helpers turn IPv4 and IPv6 values into Uint8Array forms and binary representations back into strings, including detection and extraction for IPv4-mapped IPv6 addresses.

148 entities in `src/utils`. **6 other subsystems depend on it**, which makes it the most depended-upon part of this codebase.

## What it is made of

Its 148 entities sit in 27 files under `src/utils`: 60 functions, 57 type aliases, 16 classes, 9 constants and 6 more.
`types.ts` holds 19 of them — more than any other file here.
`StreamingApi` declares 7 methods, the widest surface here.

## Where work enters

- [`Accept`](interface-accept) — `src/utils/accept.ts`:1
- [`parseAccept`](function-parseaccept) — `src/utils/accept.ts`:211
- [`Auth`](type-auth) — `src/utils/basic-auth.ts`:7
- [`auth`](function-auth) — `src/utils/basic-auth.ts`:9

## How it refuses and fails

1 of its components records a refusal or a failure handler.
Its `catch` blocks handle a failure that already happened in 2 places.
`StreamingApi` holds 2 of the silent ones — a failure discarded silently leaves no trace for whoever debugs this later.

## Boundaries

**6 other subsystems depend on this one** — `Router`, `Middleware`, `Adapter`, `Helper`, `Jsx`, `Validator`. Changing what it exposes changes them.

Those 6 hold 65 edges between them, unevenly: `Helper` reaches in across 23 edges, while another holds one. 65 edges arrive against 1 leaving — more of this repository reaches into it than it reaches out to. What they reach is narrower than the folder: 40 of its 148 members carry every inbound edge — `escapeToBuffer` (4), `checkOptionalParameter` (3) and `parseAccept` (3), plus 37 more.

It depends on `Helper`, and on nothing else in this repository.

## 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 |
|---|---|---|---|
| `convert*` | exported symbols | 5 | `convertIPv4ToBinary`, `convertIPv6ToBinary`, `convertIPv4BinaryToString`, `convertIPv6BinaryToString` |