@ozanarslan/corpus 0.0.1

package/dist/Globals/AppsRegistry/index.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Process-wide registry of every {@link AppInterface} instance that has been
+ * constructed.
+ *
+ * The registry is what lets {@link RouteBase} implementations and
+ * {@link Middleware} attach themselves without being handed an app: they call
+ * {@link getNearestApp} and find the most recently constructed one. The array
+ * lives on {@link Globals}, so it survives module re-evaluation and is shared
+ * across the whole process.
+ *
+ * @module AppsRegistry
+ */
+import type { AppInterface } from "../../App";
+/**
+ * The registry itself: every {@link AppInterface} in construction order, oldest
+ * first. The last entry is the one {@link getNearestApp} resolves to.
+ */
+type AppsRegistry = Array<AppInterface>;
+/**
+ * Reads the registry from {@link Globals}, creating an empty one on first
+ * access.
+ *
+ * @returns The shared {@link AppsRegistry}. The array is live — mutating it
+ * mutates the registry.
+ */
+declare function getOrInitAppsRegistry(): AppsRegistry;
+/**
+ * Resolves the {@link AppInterface} that newly constructed routes and
+ * middlewares should attach to: the most recently registered one.
+ *
+ * With a single app — the common case — this is simply that app. With several,
+ * "nearest" means last constructed, so an app must be instantiated before the
+ * routes belonging to it.
+ *
+ * @returns The most recently registered {@link AppInterface}.
+ * @throws {@link Error} when no app has been constructed yet.
+ */
+declare function getNearestApp(): AppInterface;
+/**
+ * Appends an app to the registry, making it the one {@link getNearestApp}
+ * returns. Called by the {@link App} constructor; there is no reason to call it
+ * by hand.
+ *
+ * @param app - The {@link AppInterface} to register.
+ */
+declare function registerApp(app: AppInterface): void;
+export { type AppsRegistry, getOrInitAppsRegistry, getNearestApp, registerApp };
+//# sourceMappingURL=index.d.ts.map

package/dist/Globals/AppsRegistry/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/Globals/AppsRegistry/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AAI1C;;;GAGG;AACH,KAAK,YAAY,GAAG,KAAK,CAAC,YAAY,CAAC,CAAC;AAExC;;;;;;GAMG;AACH,iBAAS,qBAAqB,IAAI,YAAY,CAM7C;AAED;;;;;;;;;;GAUG;AACH,iBAAS,aAAa,IAAI,YAAY,CAKrC;AAED;;;;;;GAMG;AACH,iBAAS,WAAW,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI,CAG5C;AAED,OAAO,EAAE,KAAK,YAAY,EAAE,qBAAqB,EAAE,aAAa,EAAE,WAAW,EAAE,CAAC"}

package/dist/Globals/ParsersRegistry/index.d.ts

@@ -0,0 +1,93 @@
+/**
+ * The single place every parsing decision in the framework is resolved from —
+ * and the single place to replace them.
+ *
+ * Nothing in corpus constructs a parser inline. {@link App} resolves the
+ * registry while compiling routes, and {@link BodyParser} reaches back into it
+ * for {@link FormDataParser} and {@link SearchParamsParser} rather than owning
+ * instances of its own. Replacing an entry therefore changes how the whole
+ * framework parses that surface, across every {@link RouteBase} on every
+ * {@link App}, without touching a single route definition.
+ *
+ * Every slot is plug and play. Each is typed as an interface
+ * ({@link ParserBaseInterface}, {@link BodyParserInterface},
+ * {@link SchemaParserInterface}), never as a concrete class, so a replacement
+ * only has to satisfy the contract — subclassing the default is optional.
+ *
+ * ```ts
+ * // Replace one parser; the rest keep their defaults.
+ * setParsersRegistry({ bodyParser: new MyBodyParser() });
+ *
+ * await app.listen();
+ * ```
+ *
+ * Overrides must be in place before {@link App.listen}: routes read the registry
+ * as they are compiled, so anything swapped in afterwards is never reached.
+ *
+ * The registry lives on {@link Globals}, so it is created once per process and
+ * shared by every {@link App}.
+ *
+ * @module ParsersRegistry
+ */
+import type { ParserBaseInterface } from "../../ParserBase";
+import { type BodyParserInterface } from "../../ParserBase/BodyParser";
+import { type SchemaParserInterface } from "../../ParserBase/SchemaParser";
+/**
+ * The set of parsers the framework resolves at request time. Every field is an
+ * interface, so each one can be replaced independently through
+ * {@link setParsersRegistry}.
+ */
+interface ParsersRegistry {
+    /**
+     * Turns the raw path parameters matched by a {@link RouteBase} into
+     * {@link Context.params}. Defaults to {@link URLParamsParser}.
+     */
+    urlParamsParser: ParserBaseInterface<Record<string, string>>;
+    /**
+     * Turns a query string into {@link Context.search}. Defaults to
+     * {@link SearchParamsParser}, which {@link BodyParser} also reuses for
+     * `application/x-www-form-urlencoded` bodies.
+     */
+    searchParamsParser: ParserBaseInterface<URLSearchParams>;
+    /**
+     * Turns `multipart/form-data` into an object. Defaults to
+     * {@link FormDataParser} and is reached through {@link BodyParser} rather than
+     * called directly.
+     */
+    formDataParser: ParserBaseInterface<FormData>;
+    /**
+     * Reads and decodes request and response bodies by content type. Defaults to
+     * {@link BodyParser}.
+     */
+    bodyParser: BodyParserInterface;
+    /**
+     * Validates already-parsed params, search and body against the schemas
+     * declared in a route's {@link Config}. Defaults to {@link SchemaParser},
+     * which supports Zod and ArkType.
+     */
+    schemaParser: SchemaParserInterface;
+}
+/**
+ * Reads the registry from {@link Globals}, constructing the defaults on first
+ * access.
+ *
+ * Called by {@link App} during route compilation and by {@link BodyParser} when
+ * it needs a sibling parser.
+ *
+ * @returns The shared {@link ParsersRegistry}.
+ */
+declare function getOrInitParsersRegistry(): ParsersRegistry;
+/**
+ * Overrides one or more parsers. Only the provided keys are replaced;
+ * unspecified parsers keep their current implementation.
+ *
+ * Must be called before {@link App.listen} — routes resolve their parsers as
+ * they are compiled, so a later override has no effect on an already-listening
+ * app.
+ *
+ * @param overrides - The {@link ParsersRegistry} entries to swap in. Each value
+ * need only satisfy its interface; it does not have to extend the default class.
+ */
+declare function setParsersRegistry(overrides: Partial<ParsersRegistry>): void;
+export { type ParsersRegistry, getOrInitParsersRegistry, setParsersRegistry };
+//# sourceMappingURL=index.d.ts.map

package/dist/Globals/ParsersRegistry/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/Globals/ParsersRegistry/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAGH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACxD,OAAO,EAAE,KAAK,mBAAmB,EAAc,MAAM,yBAAyB,CAAC;AAE/E,OAAO,EAAE,KAAK,qBAAqB,EAAgB,MAAM,2BAA2B,CAAC;AAIrF;;;;GAIG;AACH,UAAU,eAAe;IACxB;;;OAGG;IACH,eAAe,EAAE,mBAAmB,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC7D;;;;OAIG;IACH,kBAAkB,EAAE,mBAAmB,CAAC,eAAe,CAAC,CAAC;IACzD;;;;OAIG;IACH,cAAc,EAAE,mBAAmB,CAAC,QAAQ,CAAC,CAAC;IAC9C;;;OAGG;IACH,UAAU,EAAE,mBAAmB,CAAC;IAChC;;;;OAIG;IACH,YAAY,EAAE,qBAAqB,CAAC;CACpC;AAED;;;;;;;;GAQG;AACH,iBAAS,wBAAwB,IAAI,eAAe,CAanD;AAED;;;;;;;;;;GAUG;AACH,iBAAS,kBAAkB,CAAC,SAAS,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,IAAI,CAErE;AAED,OAAO,EAAE,KAAK,eAAe,EAAE,wBAAwB,EAAE,kBAAkB,EAAE,CAAC"}

package/dist/Globals/index.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Typed process-wide state, stored on `globalThis` under package-namespaced
+ * symbols.
+ *
+ * Two things in the framework must be singletons regardless of how many times
+ * the module is evaluated: the {@link AppsRegistry} that {@link getNearestApp}
+ * resolves against, and the {@link ParsersRegistry} that every route reads while
+ * compiling. Module-level variables cannot guarantee that — a duplicated
+ * dependency, a re-import under a different resolution, or a test runner
+ * reloading modules each produces a second copy, and two apps registries means
+ * routes registering onto an app that is never served.
+ *
+ * The keys are `Symbol.for("@ozanarslan/corpus:<key>")`, so they are shared
+ * across every copy of the package in the process and cannot collide with
+ * another library's globals.
+ *
+ * @module Globals
+ */
+import type { AppsRegistry } from "./AppsRegistry";
+import type { ParsersRegistry } from "./ParsersRegistry";
+/**
+ * What lives in the global store, and the type of each entry. Adding a key here
+ * requires a matching entry in {@link GLOBAL_SYMBOLS}, which the `satisfies`
+ * clause enforces.
+ */
+interface GlobalRegistry {
+    /** Whether one-time framework setup has run. */
+    initialized: boolean;
+    /** The shared {@link AppsRegistry} — every {@link App} constructed in this process. */
+    apps: AppsRegistry;
+    /** The shared {@link ParsersRegistry} — the parsers routes resolve at compile time. */
+    parsers: ParsersRegistry;
+}
+/**
+ * The symbol for each {@link GlobalRegistry} entry.
+ *
+ * Registered through `Symbol.for`, so every copy of the package in the process
+ * resolves to the same symbol and therefore to the same stored value.
+ */
+declare const GLOBAL_SYMBOLS: {
+    readonly initialized: symbol;
+    readonly apps: symbol;
+    readonly parsers: symbol;
+};
+/**
+ * Typed accessor for the global store.
+ *
+ * Keys are constrained to {@link GlobalRegistry}, so every read and write is
+ * checked against the type declared for that entry.
+ */
+declare class Globals {
+    /** The backing store: `globalThis`, typed for symbol access. */
+    private static readonly store;
+    /**
+     * Returns the symbol an entry is stored under.
+     *
+     * Useful for inspecting or clearing global state directly — in a test that
+     * needs a clean process, for instance.
+     *
+     * @param key - The {@link GlobalRegistry} entry.
+     * @returns Its symbol from {@link GLOBAL_SYMBOLS}.
+     */
+    static getSymbol<K extends keyof GlobalRegistry>(key: K): (typeof GLOBAL_SYMBOLS)[K];
+    /**
+     * Reads an entry, creating it on first access.
+     *
+     * The initialiser runs only when the entry is absent, which is what makes this
+     * safe to call from anywhere: the first caller creates the value and every
+     * later one gets that same instance. This is how
+     * {@link getOrInitAppsRegistry} and {@link getOrInitParsersRegistry} work.
+     *
+     * @param key - The {@link GlobalRegistry} entry.
+     * @param init - Builds the initial value. Not called if the entry exists.
+     * @returns The stored value.
+     */
+    static create<K extends keyof GlobalRegistry>(key: K, init: () => GlobalRegistry[K]): GlobalRegistry[K];
+    /**
+     * Reads an entry that is expected to exist.
+     *
+     * @param key - The {@link GlobalRegistry} entry.
+     * @returns The stored value.
+     * @throws {@link Error} when the entry has not been created. Use
+     * {@link Globals.create} when the caller may be the first.
+     */
+    static get<K extends keyof GlobalRegistry>(key: K): GlobalRegistry[K];
+    /**
+     * Writes an entry, replacing any existing value.
+     *
+     * @param key - The {@link GlobalRegistry} entry.
+     * @param value - The value to store.
+     */
+    static set<K extends keyof GlobalRegistry>(key: K, value: GlobalRegistry[K]): void;
+    /**
+     * Reports whether an entry has been created, without creating it or throwing.
+     *
+     * @param key - The {@link GlobalRegistry} entry.
+     * @returns `true` when the entry exists.
+     */
+    static has<K extends keyof GlobalRegistry>(key: K): boolean;
+    /**
+     * Removes an entry, so the next {@link Globals.create} rebuilds it from
+     * scratch. Mainly useful for resetting state between tests.
+     *
+     * @param key - The {@link GlobalRegistry} entry.
+     */
+    static delete<K extends keyof GlobalRegistry>(key: K): void;
+}
+export { type GlobalRegistry, Globals, GLOBAL_SYMBOLS };
+//# sourceMappingURL=index.d.ts.map

package/dist/Globals/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/Globals/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAKjE;;;;GAIG;AACH,UAAU,cAAc;IAEvB,gDAAgD;IAChD,WAAW,EAAE,OAAO,CAAC;IACrB,uFAAuF;IACvF,IAAI,EAAE,YAAY,CAAC;IACnB,uFAAuF;IACvF,OAAO,EAAE,eAAe,CAAC;CACzB;AAWD;;;;;GAKG;AACH,QAAA,MAAM,cAAc;;;;CAIqC,CAAC;AAE1D;;;;;GAKG;AACH,cAAM,OAAO;IACZ,gEAAgE;IAChE,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAyC;IAEtE;;;;;;;;OAQG;IACH,MAAM,CAAC,SAAS,CAAC,CAAC,SAAS,MAAM,cAAc,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,CAAC,CAAC;IAIpF;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,MAAM,cAAc,EAC3C,GAAG,EAAE,CAAC,EACN,IAAI,EAAE,MAAM,cAAc,CAAC,CAAC,CAAC,GAC3B,cAAc,CAAC,CAAC,CAAC;IAMpB;;;;;;;OAOG;IACH,MAAM,CAAC,GAAG,CAAC,CAAC,SAAS,MAAM,cAAc,EAAE,GAAG,EAAE,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC;IAOrE;;;;;OAKG;IACH,MAAM,CAAC,GAAG,CAAC,CAAC,SAAS,MAAM,cAAc,EAAE,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,IAAI;IAKlF;;;;;OAKG;IACH,MAAM,CAAC,GAAG,CAAC,CAAC,SAAS,MAAM,cAAc,EAAE,GAAG,EAAE,CAAC,GAAG,OAAO;IAK3D;;;;;OAKG;IACH,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,MAAM,cAAc,EAAE,GAAG,EAAE,CAAC,GAAG,IAAI;CAI3D;AAED,OAAO,EAAE,KAAK,cAAc,EAAE,OAAO,EAAE,cAAc,EAAE,CAAC"}

package/dist/Headers/index.d.ts

@@ -0,0 +1,208 @@
+/**
+ * Header names, header-value builders, and the `Headers` extensions the
+ * framework relies on.
+ *
+ * Two things happen here. {@link HeaderKey} gives the common header names as
+ * documented constants, so header access is autocompleted and typo-free rather
+ * than stringly typed. {@link patchGlobalHeaders} then extends the global
+ * `Headers` class with conveniences the native API lacks: non-string values,
+ * bulk assignment through {@link Headers.setMany}, and structured builders for
+ * `Cache-Control` and `Content-Disposition`.
+ *
+ * The patch is what lets {@link Res}, {@link FileRoute} and {@link BundleRoute}
+ * write headers without stringifying every value by hand. It applies to the
+ * process's own `Headers`, so it must be installed once at startup, before any
+ * request is served.
+ *
+ * @module Headers
+ */
+import type { MaybeArray, Nullable, Optional, OrString } from "../utils/is";
+import type { ValueOf } from "../utils/object";
+/**
+ * A value accepted by the patched header setters. Numbers and booleans are
+ * stringified on the way in, so a byte length or a flag can be passed as-is.
+ */
+type HeadersInitValue = string | number | boolean;
+/**
+ * What {@link Headers.setMany} accepts: entry pairs, a plain object, or another
+ * `Headers` instance.
+ */
+type CustomHeadersInit = [string, HeadersInitValue][] | Record<string, HeadersInitValue> | Headers;
+/** Just some common headers. See [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers) for the full spec. */
+declare const HeaderKey: {
+    /** Controls caching mechanisms for requests and responses. */
+    readonly CacheControl: "Cache-Control";
+    /** Specifies the media type of the resource or data. */
+    readonly ContentType: "Content-Type";
+    /** Indicates the size of the entity-body in bytes. */
+    readonly ContentLength: "Content-Length";
+    /** Whether to display payload inline within the page or prompt the user to download it as an attachment. */
+    readonly ContentDisposition: "Content-Disposition";
+    /** Specifies the character encodings that are acceptable. */
+    readonly AcceptEncoding: "Accept-Encoding";
+    /** Informs the server about the types of data that can be sent back. */
+    readonly Accept: "Accept";
+    /** Contains the credentials to authenticate with the server. */
+    readonly Authorization: "Authorization";
+    /** The user agent string of the client software. */
+    readonly UserAgent: "User-Agent";
+    /** The domain name of the server and port number. */
+    readonly Host: "Host";
+    /** The address of the previous web page from which the current request originated. */
+    readonly Referer: "Referer";
+    /** Indicates whether the connection should be kept alive. */
+    readonly Connection: "Connection";
+    /** Requests that the server switch to a different protocol (e.g. WebSocket). */
+    readonly Upgrade: "Upgrade";
+    /** Used to specify directives that must be obeyed by caching mechanisms. */
+    readonly Pragma: "Pragma";
+    /** The date and time at which the message was sent. */
+    readonly Date: "Date";
+    /** Makes the request conditional based on the ETag of the resource. */
+    readonly IfNoneMatch: "If-None-Match";
+    /** Makes the request conditional based on the last modification date. */
+    readonly IfModifiedSince: "If-Modified-Since";
+    /** An identifier for a specific version of a resource. */
+    readonly ETag: "ETag";
+    /** The date and time after which the response is considered stale. */
+    readonly Expires: "Expires";
+    /** The last modification date of the resource. */
+    readonly LastModified: "Last-Modified";
+    /** Indicates the URL to redirect a page to. */
+    readonly Location: "Location";
+    /** Defines the authentication method that should be used. */
+    readonly WWWAuthenticate: "WWW-Authenticate";
+    /** Determines how long the results of a preflight request can be cached. */
+    readonly AccessControlMaxAge: "Access-Control-Max-Age";
+    /** Indicates whether the response can be shared with resources with credentials. */
+    readonly AccessControlAllowCredentials: "Access-Control-Allow-Credentials";
+    /** Indicates which HTTP method will be used in the actual CORS request. */
+    readonly AccessControlRequestMethod: "Access-Control-Request-Method";
+    /** Indicates which headers can be exposed to the browser in a CORS response. */
+    readonly AccessControlExposeHeaders: "Access-Control-Expose-Headers";
+    /** Indicates which origins are allowed to access the resource. */
+    readonly AccessControlAllowOrigin: "Access-Control-Allow-Origin";
+    /** Specifies the HTTP methods allowed when accessing the resource in a CORS request. */
+    readonly AccessControlAllowMethods: "Access-Control-Allow-Methods";
+    /** Specifies the HTTP headers allowed in a CORS request. */
+    readonly AccessControlAllowHeaders: "Access-Control-Allow-Headers";
+    /** Sends cookies from the server to the client. */
+    readonly SetCookie: "Set-Cookie";
+    /** Sends cookies from the client to the server. */
+    readonly Cookie: "Cookie";
+    /** Determines which headers should be used to select a response from cache when content negotiation is in use. */
+    readonly Vary: "Vary";
+    /** Set to "nosniff" by default in {@link Res}. */
+    readonly XContentTypeOptions: "X-Content-Type-Options";
+};
+/**
+ * A header name. The {@link HeaderKey} constants are suggested, but
+ * {@link OrString} keeps any custom header name assignable — the enum is a
+ * convenience, not a restriction.
+ */
+type HeaderKey = OrString<ValueOf<typeof HeaderKey>>;
+/**
+ * A caching policy, rendered into a `Cache-Control` value by
+ * {@link createCacheControlHeader}. Used by {@link FileRoute.cache} and by each
+ * entry of a {@link BundleRouteDefinition}.
+ */
+interface CacheControlDefinition {
+    /** Allows shared caches — proxies and CDNs — to store the response, not just the browser. */
+    public?: boolean;
+    /** How long the response stays fresh, in seconds. */
+    maxAge?: number;
+    /** Promises the response will never change, so the browser skips revalidation entirely. Only meaningful with a content hash in the URL. */
+    immutable?: boolean;
+    /** Caches the response but revalidates before every use. Overrides the other directives except `noStore`. */
+    noCache?: boolean;
+    /** Forbids storing the response anywhere. Overrides every other directive. */
+    noStore?: boolean;
+}
+/**
+ * Renders a {@link CacheControlDefinition} into a `Cache-Control` header value.
+ *
+ * The two prohibitive directives take precedence and are emitted alone, since
+ * combining them with freshness directives is contradictory: `noStore` wins over
+ * everything, then `noCache`. Otherwise the remaining directives are joined in
+ * order.
+ *
+ * @param def - The caching policy to render.
+ * @returns The header value, or an empty string when the definition sets
+ * nothing.
+ */
+declare function createCacheControlHeader(def: CacheControlDefinition): string;
+/**
+ * How a response body should be presented, rendered by
+ * {@link createContentDispositionHeader}.
+ */
+interface ContentDispositionDefinition {
+    /** `"inline"` to display in the browser, `"attachment"` to prompt a download. */
+    disposition: "attachment" | "inline";
+    /** The name to save the file under. Omit it to let the client decide. */
+    filename?: string;
+}
+/**
+ * Renders a {@link ContentDispositionDefinition} into a `Content-Disposition`
+ * header value.
+ *
+ * @param def - The disposition to render.
+ * @returns The header value, with a quoted `filename` parameter when one is
+ * given.
+ */
+declare function createContentDispositionHeader(def: ContentDispositionDefinition): string;
+/**
+ * Reads a header from any `HeadersInit` shape, without constructing a `Headers`.
+ *
+ * Header names are case-insensitive, so every shape is matched case-insensitively:
+ * a `Headers` instance is probed with both casings, and the array and object
+ * forms are scanned with lowercased comparison.
+ *
+ * @param headers - The headers to read, in any accepted form. `undefined` and
+ * `null` are allowed and yield `null`.
+ * @param name - The header to look for.
+ * @returns The value, or `null` when absent.
+ */
+declare function readHeader(headers: Optional<HeadersInit>, name: HeaderKey): Nullable<string>;
+/**
+ * Installs the extended `Headers` behaviour declared above onto the global
+ * class. Call it once at startup, before any request is served.
+ *
+ * The patch is applied twice over, deliberately. The prototype methods are
+ * replaced so headers *the runtime* created — those on an incoming `Request`, or
+ * on a `Response` built elsewhere — gain the same behaviour. The global class is
+ * then also replaced with a subclass, so instances constructed after the patch
+ * carry the methods as own class members rather than only as prototype
+ * assignments.
+ *
+ * The subclass overrides `Symbol.hasInstance` to defer to the native class, so
+ * `instanceof Headers` stays true for objects the runtime created before or
+ * outside the patch. Without it, the swap would silently break every
+ * `instanceof` check against headers the framework did not construct.
+ */
+declare function patchGlobalHeaders(): void;
+declare global {
+    /**
+     * The `Headers` surface after {@link patchGlobalHeaders} has run.
+     *
+     * The existing methods are re-declared to accept a {@link HeaderKey} and a
+     * {@link HeadersInitValue}; the rest are additions.
+     */
+    interface Headers {
+        /** Adds a value without replacing existing ones. An array appends each item as its own header line. */
+        append(name: HeaderKey, value: MaybeArray<HeadersInitValue>): void;
+        /** Sets a header, replacing any existing value. Numbers and booleans are stringified. */
+        set(name: HeaderKey, value: HeadersInitValue): void;
+        /** Reads a header, falling back to the lowercased name. */
+        get(name: HeaderKey): Nullable<string>;
+        /** Reports whether a header is present, falling back to the lowercased name. */
+        has(name: HeaderKey): boolean;
+        /** Sets many headers at once. See {@link CustomHeadersInit}. */
+        setMany(init: CustomHeadersInit): void;
+        /** Sets `Cache-Control` from a {@link CacheControlDefinition}. */
+        setCacheControl(def: CacheControlDefinition): void;
+        /** Sets `Content-Disposition` from a {@link ContentDispositionDefinition}. */
+        setContentDisposition(def: ContentDispositionDefinition): void;
+    }
+}
+export { patchGlobalHeaders, createCacheControlHeader, createContentDispositionHeader, readHeader, HeaderKey, type ContentDispositionDefinition, type CacheControlDefinition, };
+//# sourceMappingURL=index.d.ts.map

package/dist/Headers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/Headers/index.ts"],"names":[],"mappings":"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"}

package/dist/Middleware/index.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Logic that runs around a route handler — before it, after it, or instead of
+ * it.
+ *
+ * A {@link Middleware} receives the {@link Context} and a `next` function. What
+ * runs before `await next()` happens on the way in; what runs after it happens
+ * on the way out, with the downstream result in hand. Returning early instead of
+ * calling `next()` short-circuits the chain, which is how authentication rejects
+ * a request without the route handler ever running.
+ *
+ * Constructing one registers it on the nearest {@link App}, which folds it into
+ * each targeted route's chain at compile time via {@link composeHandlerChain}.
+ * Targeting is by route id, but {@link Middleware.useOn} accepts routes and
+ * {@link Controller} instances directly and resolves the ids itself.
+ *
+ * ```ts
+ * import { Middleware } from "@ozanarslan/corpus";
+ *
+ * new Middleware({
+ *   useOn: usersController,
+ *   handler: async (c, next) => {
+ *     const started = performance.now();
+ *     const result = await next();
+ *     c.res.headers.set("X-Response-Time", performance.now() - started);
+ *     return result;
+ *   },
+ * });
+ * ```
+ *
+ * @module Middleware
+ */
+import type { Context } from "../Context";
+import type { Controller } from "../Controller";
+import type { RouteBase } from "../RouteBase";
+import type { MaybePromise, OrString } from "../utils/is";
+/**
+ * A middleware's handler function. Like a {@link ContextHandler}, but with the
+ * rest of the chain passed in.
+ *
+ * What the return value means is resolved by {@link composeHandlerChain}: a
+ * returned value short-circuits the chain, `undefined` after calling `next()`
+ * passes the downstream result through, and `undefined` without calling `next()`
+ * lets the chain continue anyway.
+ *
+ * @param context - The {@link Context} for the request, shared with every other
+ * handler in the chain. Use {@link Context.data} to pass state downstream.
+ * @param next - Runs the rest of the chain and resolves to its result. Calling
+ * it more than once throws.
+ * @returns The response value, or `undefined` to defer to the chain.
+ * @typeParam R - The result type passed along the chain.
+ */
+type MiddlewareHandler<R = unknown> = (context: Context, next: () => MaybePromise<R>) => MaybePromise<R>;
+/**
+ * What a middleware applies to.
+ *
+ * A {@link RouteBase} targets that route, a {@link Controller} targets every
+ * route registered through it, a string targets a route id directly, and an
+ * array combines any of these. The literal `"*"` targets every route on the app,
+ * including requests that match none — global middlewares also run ahead of
+ * {@link App.handleNotFound}.
+ */
+type MiddlewareUseOn = Array<RouteBase | Controller | string> | RouteBase | Controller | OrString<"*">;
+/** Construction arguments for a {@link Middleware}. */
+type MiddlewareDefinition = {
+    /** What the middleware applies to. Defaults to `"*"` — every route. */
+    useOn?: MiddlewareUseOn;
+    /** The {@link MiddlewareHandler} to run. */
+    handler: MiddlewareHandler;
+};
+/**
+ * A handler registered to run around some or all of an app's routes.
+ *
+ * Middlewares execute in the order {@link App.findMiddlewares} returns them:
+ * global ones first, then route-specific ones, then the route handler. Since the
+ * chain nests, a global middleware wraps everything after it — its post-`next()`
+ * code runs last.
+ *
+ * Targeting a route id that no route claims is not an error, but the middleware
+ * will never run; {@link App.warnUnmatchedMiddlewares} logs a warning at startup
+ * when that happens.
+ */
+declare class Middleware {
+    /**
+     * Creates a middleware for subclasses, which declare
+     * {@link Middleware.handler} and {@link Middleware.useOn} as class fields and
+     * call {@link Middleware.register} themselves.
+     */
+    constructor();
+    /**
+     * Creates a middleware and registers it on the nearest {@link App}.
+     *
+     * @param definition - The {@link MiddlewareDefinition}: the handler, and
+     * optionally what it applies to.
+     */
+    constructor(definition: MiddlewareDefinition);
+    /**
+     * Registers this middleware on the nearest {@link App} through
+     * {@link App.addMiddleware}. Called by the constructor.
+     *
+     * Registration order relative to routes does not matter — targets are resolved
+     * to ids here, and the app only matches them when it compiles routes.
+     */
+    register(): void;
+    /**
+     * What this middleware applies to. Defaults to `"*"`, meaning every route on
+     * the app.
+     */
+    useOn: MiddlewareUseOn;
+    /** The function that runs when a targeted route is hit. */
+    handler: MiddlewareHandler;
+    /**
+     * The route ids resolved from {@link Middleware.useOn}, which
+     * {@link App.addMiddleware} indexes the middleware under.
+     *
+     * Each target contributes its ids: a route its own, a {@link Controller} all
+     * of {@link Controller.routeIds}, and a string itself. Duplicates are
+     * collapsed, so a route listed both directly and through its controller is
+     * still wrapped once.
+     *
+     * @returns The ids, or `["*"]` for a global middleware.
+     */
+    get routeIds(): Array<string>;
+}
+export { Middleware, type MiddlewareDefinition, type MiddlewareUseOn, type MiddlewareHandler };
+//# sourceMappingURL=index.d.ts.map

package/dist/Middleware/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/Middleware/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEzD;;;;;;;;;;;;;;;GAeG;AACH,KAAK,iBAAiB,CAAC,CAAC,GAAG,OAAO,IAAI,CACrC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,MAAM,YAAY,CAAC,CAAC,CAAC,KACvB,YAAY,CAAC,CAAC,CAAC,CAAC;AAErB;;;;;;;;GAQG;AACH,KAAK,eAAe,GACjB,KAAK,CAAC,SAAS,GAAG,UAAU,GAAG,MAAM,CAAC,GACtC,SAAS,GACT,UAAU,GACV,QAAQ,CAAC,GAAG,CAAC,CAAC;AAEjB,uDAAuD;AACvD,KAAK,oBAAoB,GAAG;IAC3B,uEAAuE;IACvE,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,4CAA4C;IAC5C,OAAO,EAAE,iBAAiB,CAAC;CAC3B,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,cAAM,UAAU;IACf;;;;OAIG;;IAEH;;;;;OAKG;gBACS,UAAU,EAAE,oBAAoB;IAS5C;;;;;;OAMG;IACH,QAAQ,IAAI,IAAI;IAIhB;;;OAGG;IACH,KAAK,EAAE,eAAe,CAAO;IAE7B,2DAA2D;IAC3D,OAAO,EAAG,iBAAiB,CAAC;IAE5B;;;;;;;;;;OAUG;IACH,IAAI,QAAQ,IAAI,KAAK,CAAC,MAAM,CAAC,CAc5B;CACD;AAED,OAAO,EAAE,UAAU,EAAE,KAAK,oBAAoB,EAAE,KAAK,eAAe,EAAE,KAAK,iBAAiB,EAAE,CAAC"}