@ozanarslan/corpus 0.0.1

package/dist/Context/index.d.ts

@@ -0,0 +1,162 @@
+/**
+ * The per-request object every handler receives.
+ *
+ * A {@link Context} carries the incoming request alongside the parsed views of
+ * it — {@link Context.body}, {@link Context.params}, {@link Context.search} —
+ * and the {@link Res} being built up in reply. It is created once per request by
+ * the {@link ContextFactory} on {@link App.contextFactory} and threaded through
+ * the whole {@link Middleware} chain, so it is also the place to hang state that
+ * one handler produces and another consumes.
+ *
+ * The parsed fields start out empty and are filled by {@link App} during the
+ * request lifecycle, but only for the surfaces a route's handlers actually read
+ * — {@link getContextAccess} decides that, so an untouched body is never parsed.
+ *
+ * @module Context
+ */
+import { Res } from "../Res";
+import type { Server } from "../Server";
+import type { Maybe, MaybePromise } from "../utils/is";
+/**
+ * Declaration target for {@link Context.data}, the request-scoped state shared
+ * between {@link Middleware} and route handlers.
+ *
+ * Empty by design. Augment it from your own code so everything a middleware sets
+ * is typed where a handler reads it:
+ *
+ * ```ts
+ * declare module "@ozanarslan/corpus" {
+ *   interface ContextDataInterface {
+ *     user: User;
+ *   }
+ * }
+ * ```
+ */
+interface ContextDataInterface {
+}
+/**
+ * Builds the {@link Context} for an incoming request. Assigned to
+ * {@link App.contextFactory}; replace it to have an app construct a
+ * {@link Context} subclass.
+ *
+ * @param request - The incoming request.
+ * @param server - The {@link Server} that accepted it, absent when the request
+ * was dispatched without one.
+ * @returns The context the request will be handled with.
+ * @typeParam B - Parsed {@link Context.body} type.
+ * @typeParam S - Parsed {@link Context.search} type.
+ * @typeParam P - Parsed {@link Context.params} type.
+ * @typeParam R - Response body type carried by {@link Context.res}.
+ */
+type ContextFactory<B = unknown, S = unknown, P = unknown, R = unknown> = (request: Request, server: Maybe<Server>) => Context<B, S, P, R>;
+/**
+ * A function that handles a request given its {@link Context}. This is the shape
+ * of a {@link RouteBase} handler and of the app-level hooks
+ * {@link App.handleNotFound} and {@link App.handlePreflight}.
+ *
+ * A {@link Middleware} handler is a {@link MiddlewareHandler} instead, since it
+ * additionally receives `next`.
+ *
+ * @param context - The {@link Context} for the request.
+ * @returns The response body, a {@link Res}, or a promise of either. Returning
+ * `undefined` leaves {@link Context.res} as the handler mutated it.
+ * @typeParam B - Parsed {@link Context.body} type.
+ * @typeParam S - Parsed {@link Context.search} type.
+ * @typeParam P - Parsed {@link Context.params} type.
+ * @typeParam R - Response body type.
+ */
+type ContextHandler<B = unknown, S = unknown, P = unknown, R = unknown> = (context: Context<B, S, P, R>) => MaybePromise<R>;
+/**
+ * Everything a handler needs to know about one request, and everything it uses
+ * to answer it.
+ *
+ * The type parameters are supplied by the route the context belongs to, so a
+ * handler sees its own validated shapes rather than `unknown`.
+ *
+ * {@link Context.res} and {@link Context.url} are lazy: neither the response
+ * object nor the parsed URL is constructed until something reads it, so a
+ * handler that returns a body without touching either pays for neither.
+ *
+ * The parsed containers are created with {@link createSafeObject}, so a payload
+ * carrying a `__proto__` key cannot reach `Object.prototype` through them.
+ *
+ * @typeParam B - Parsed {@link Context.body} type.
+ * @typeParam S - Parsed {@link Context.search} type.
+ * @typeParam P - Parsed {@link Context.params} type.
+ * @typeParam R - Response body type carried by {@link Context.res}.
+ */
+declare class Context<B = unknown, S = unknown, P = unknown, R = unknown> {
+    /**
+     * Creates a context with empty parsed containers; {@link App} fills them
+     * during the request lifecycle.
+     *
+     * @param req - The incoming request.
+     * @param server - The {@link Server} that accepted it. Absent when the request
+     * was dispatched without one, which is why {@link Context.server} is optional
+     * at every use site — including the WebSocket upgrade.
+     */
+    constructor(req: Request, server: Maybe<Server>);
+    /**
+     * The parsed request body, decoded by {@link BodyParser} and validated against
+     * the route's {@link RouteConfig} body schema.
+     *
+     * Empty for {@link Method.GET} and {@link Method.HEAD} requests, and for any
+     * route whose handlers never read it.
+     */
+    body: B;
+    /**
+     * The path parameters matched by the route, parsed by
+     * {@link ParsersRegistry.urlParamsParser} and validated against the route's
+     * params schema. A wildcard segment is available under the `*` key.
+     */
+    params: P;
+    /**
+     * The query string, parsed by {@link ParsersRegistry.searchParamsParser} and
+     * validated against the route's search schema. Empty when the request carried
+     * no query string.
+     */
+    search: S;
+    /**
+     * Free-form request-scoped state, shared across the whole
+     * {@link Middleware} chain and the route handler. This is how a middleware
+     * hands something — an authenticated user, a request id — to what runs after
+     * it. Type it by augmenting {@link ContextDataInterface}.
+     */
+    data: ContextDataInterface;
+    /**
+     * The {@link Server} that accepted the request. Needed to upgrade a connection
+     * to a {@link WebSocketRoute}; absent when the request was dispatched without
+     * a server.
+     */
+    readonly server: Maybe<Server>;
+    /**
+     * The untouched incoming request. Read it for headers and for the raw body;
+     * the parsed views live on {@link Context.body} and its siblings.
+     */
+    readonly req: Request;
+    /** Backing store for {@link Context.res}, constructed on first access. */
+    private _res;
+    /**
+     * The response under construction. Mutate it to set status, headers or body
+     * before returning, or assign a whole new {@link Res} to replace it.
+     *
+     * A {@link Middleware} that replaces this after `next()` resolves wins over
+     * whatever the downstream handler returned — see {@link composeHandlerChain}.
+     *
+     * @returns The response object, created on first access.
+     */
+    get res(): Res<R>;
+    set res(value: Res<R>);
+    /** Backing store for {@link Context.url}, parsed on first access. */
+    private _url;
+    /**
+     * The request URL, parsed once and reused.
+     *
+     * @returns The parsed `URL`. Prefer {@link Context.params} and
+     * {@link Context.search} for path and query values; reach for this when you
+     * need the pathname or origin itself, as {@link BundleRoute} does.
+     */
+    get url(): URL;
+}
+export { Context, type ContextDataInterface, type ContextFactory, type ContextHandler };
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/Context/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AAC5B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAItD;;;;;;;;;;;;;;GAcG;AACH,UAAU,oBAAoB;CAAG;AAEjC;;;;;;;;;;;;;GAaG;AACH,KAAK,cAAc,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,IAAI,CACzE,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,KACjB,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;AAEzB;;;;;;;;;;;;;;;GAeG;AACH,KAAK,cAAc,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,IAAI,CACzE,OAAO,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KACxB,YAAY,CAAC,CAAC,CAAC,CAAC;AAErB;;;;;;;;;;;;;;;;;;GAkBG;AACH,cAAM,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO;IAC/D;;;;;;;;OAQG;gBACS,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC;IAW/C;;;;;;OAMG;IACH,IAAI,EAAE,CAAC,CAAC;IAER;;;;OAIG;IACH,MAAM,EAAE,CAAC,CAAC;IAEV;;;;OAIG;IACH,MAAM,EAAE,CAAC,CAAC;IAEV;;;;;OAKG;IACH,IAAI,EAAE,oBAAoB,CAAC;IAE3B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAE/B;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IAEtB,0EAA0E;IAC1E,OAAO,CAAC,IAAI,CAAkB;IAE9B;;;;;;;;OAQG;IACH,IAAI,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,CAEhB;IAED,IAAI,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC,EAEpB;IAED,qEAAqE;IACrE,OAAO,CAAC,IAAI,CAAY;IAExB;;;;;;OAMG;IACH,IAAI,GAAG,IAAI,GAAG,CAEb;CACD;AAED,OAAO,EAAE,OAAO,EAAE,KAAK,oBAAoB,EAAE,KAAK,cAAc,EAAE,KAAK,cAAc,EAAE,CAAC"}

package/dist/Controller/index.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Grouping for routes that share a path prefix and a common preamble.
+ *
+ * A {@link Controller} is a thin factory: each method constructs the
+ * corresponding {@link RouteBase} subclass with the prefix already joined on,
+ * records its id, and returns it. The routes are ordinary routes registered on
+ * the nearest {@link App} exactly as if they had been constructed directly —
+ * a controller adds no dispatch layer of its own.
+ *
+ * ```ts
+ * import { Controller } from "@ozanarslan/corpus";
+ *
+ * const users = new Controller("/users");
+ * users.beforeEach = (c) => authenticate(c);
+ *
+ * users.route("GET /:id", (c) => findUser(c.params.id));
+ * ```
+ *
+ * @module Controller
+ */
+import type { ContextHandler } from "../Context";
+import { BundleRoute } from "../RouteBase/BundleRoute";
+import { FileRoute } from "../RouteBase/FileRoute";
+import { Route } from "../RouteBase/Route";
+import { StaticRoute } from "../RouteBase/StaticRoute";
+import { WebSocketRoute } from "../RouteBase/WebSocketRoute";
+import type { Optional } from "../utils/is";
+import { type WithPrefix } from "../utils/path";
+/**
+ * Registers routes under a shared path prefix.
+ *
+ * Every method mirrors the constructor of the route class it creates, so moving
+ * a route into a controller means changing the call site and nothing else. The
+ * prefix is folded into the endpoint at construction time and into the endpoint
+ * *type* through {@link WithPrefix}, so the returned route stays as narrowly
+ * typed as one written out by hand.
+ *
+ * {@link Controller.beforeEach} runs ahead of the handler for the route kinds
+ * that have a user-supplied handler — {@link Controller.route} and
+ * {@link Controller.staticRoute}. The other kinds resolve their responses
+ * internally and are unaffected.
+ *
+ * {@link Controller.routeIds} makes the group addressable afterwards, which is
+ * how a {@link Middleware} can be attached to every route in a controller at
+ * once.
+ *
+ * @typeParam Px - The literal prefix type, carried into every endpoint type the
+ * controller produces.
+ */
+declare class Controller<Px extends Optional<string> = Optional<string>> {
+    prefix?: Px | undefined;
+    /**
+     * Creates a controller.
+     *
+     * @param prefix - Path segment prepended to every endpoint registered through
+     * this controller. Omit it to group routes without changing their paths — the
+     * shared {@link Controller.beforeEach} and {@link Controller.routeIds} still
+     * apply.
+     */
+    constructor(prefix?: Px | undefined);
+    /**
+     * Ids of every {@link RouteBase} registered through this controller, in the
+     * order they were created.
+     *
+     * Pass them to a {@link Middleware} to target the whole group:
+     *
+     * ```ts
+     * new Middleware([...users.routeIds], handler);
+     * ```
+     */
+    readonly routeIds: Set<string>;
+    /**
+     * Runs before the handler of every {@link Controller.route} and
+     * {@link Controller.staticRoute} created by this controller.
+     *
+     * Its return value is discarded — this is for side effects on the
+     * {@link Context}, such as authenticating a request or populating
+     * {@link Context.data}. Throwing here aborts the request before the handler
+     * runs, which is the intended way to reject one.
+     *
+     * Assign it before registering routes: each route captures the controller, not
+     * the function, but a route registered while it is unset still checks it at
+     * request time. For behaviour that must wrap the response as well as precede
+     * it, use a {@link Middleware} targeting {@link Controller.routeIds} instead.
+     */
+    beforeEach?: ContextHandler;
+    /**
+     * Registers a dynamic route under this controller. Behaves identically to {@link Route}
+     * but automatically prepends the controller prefix and runs `beforeEach` before the handler.
+     *
+     * @param args - The {@link Route} constructor arguments: the route address
+     * (a `"METHOD /endpoint"` string or a method/endpoint pair), the
+     * {@link ContextHandler}, and an optional {@link RouteConfig}.
+     * @returns The registered {@link Route}, its endpoint type prefixed.
+     * @typeParam B - Parsed {@link Context.body} type.
+     * @typeParam S - Parsed {@link Context.search} type.
+     * @typeParam P - Parsed {@link Context.params} type.
+     * @typeParam R - Response body type.
+     * @typeParam E - The endpoint literal, before the prefix is applied.
+     */
+    route<B = unknown, S = unknown, P = unknown, R = unknown, E extends string = string>(...args: ConstructorParameters<typeof Route<B, S, P, R, E>>): Route<B, S, P, R, WithPrefix<Px, E>>;
+    /**
+     * Registers a static route under this controller. Behaves identically to {@link StaticRoute}
+     * but automatically prepends the controller prefix.
+     *
+     * {@link Controller.beforeEach} runs only when a callback is supplied, since
+     * that is where the controller has a handler to wrap; a static route that just
+     * serves its file is left alone.
+     *
+     * @param args - The {@link StaticRoute} constructor arguments: the route
+     * address, the file path, an optional callback receiving the
+     * {@link Context} and the file contents, and an optional
+     * {@link RouteConfig}.
+     * @returns The registered {@link StaticRoute}, its endpoint type prefixed.
+     * @typeParam B - Parsed {@link Context.body} type.
+     * @typeParam S - Parsed {@link Context.search} type.
+     * @typeParam P - Parsed {@link Context.params} type.
+     * @typeParam E - The endpoint literal, before the prefix is applied.
+     */
+    staticRoute<B = unknown, S = unknown, P = unknown, E extends string = string>(...args: ConstructorParameters<typeof StaticRoute<B, S, P, E>>): StaticRoute<B, S, P, WithPrefix<Px, E>>;
+    /**
+     * Registers a file route under this controller. Behaves identically to {@link FileRoute}
+     * but automatically prepends the controller prefix.
+     *
+     * {@link Controller.beforeEach} does not apply: a file route resolves its
+     * response internally and takes no handler to wrap.
+     *
+     * @param args - The {@link FileRoute} constructor arguments: the route address
+     * and the file definition.
+     * @returns The registered {@link FileRoute}, its endpoint type prefixed.
+     * @typeParam E - The endpoint literal, before the prefix is applied.
+     */
+    fileRoute<E extends string = string>(...args: ConstructorParameters<typeof FileRoute<E>>): FileRoute<WithPrefix<Px, E>>;
+    /**
+     * Registers a websocket route under this controller. Behaves identically to {@link WebSocketRoute}
+     * but automatically prepends the controller prefix.
+     *
+     * The address is a plain endpoint rather than a method-and-endpoint pair, since
+     * an upgrade is always a {@link Method.GET}.
+     * {@link Controller.beforeEach} does not apply — the socket lifecycle
+     * callbacks are not a {@link ContextHandler}.
+     *
+     * @param args - The {@link WebSocketRoute} constructor arguments: the endpoint
+     * followed by the socket lifecycle callbacks.
+     * @returns The registered {@link WebSocketRoute}, its endpoint type prefixed.
+     * @typeParam E - The endpoint literal, before the prefix is applied.
+     */
+    websocketRoute<E extends string = string>(...args: ConstructorParameters<typeof WebSocketRoute<E>>): WebSocketRoute<WithPrefix<Px, E>>;
+    /**
+     * Registers a bundle route under this controller. Behaves identically to {@link BundleRoute}
+     * but automatically prepends the controller prefix.
+     *
+     * {@link Controller.beforeEach} does not apply: a bundle route resolves files
+     * internally and takes no handler to wrap.
+     *
+     * @param args - The {@link BundleRoute} constructor arguments: the endpoint,
+     * the directory to serve, and an optional {@link BundleRouteDefinition}.
+     * @returns The registered {@link BundleRoute}, its endpoint type prefixed.
+     * @typeParam E - The endpoint literal, before the prefix is applied.
+     */
+    bundleRoute<E extends string = string>(...args: ConstructorParameters<typeof BundleRoute<E>>): BundleRoute<WithPrefix<Px, E>>;
+}
+export { Controller };
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/Controller/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEhD,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAoB,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAEjE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,cAAM,UAAU,CAAC,EAAE,SAAS,QAAQ,CAAC,MAAM,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC;IAS3C,MAAM,CAAC,EAAE,EAAE;IAR9B;;;;;;;OAOG;gBACgB,MAAM,CAAC,EAAE,EAAE,YAAA;IAE9B;;;;;;;;;OASG;IACH,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,CAAqB;IAEnD;;;;;;;;;;;;;OAaG;IACH,UAAU,CAAC,EAAE,cAAc,CAAC;IAE5B;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,EAClF,GAAG,IAAI,EAAE,qBAAqB,CAAC,OAAO,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,GACzD,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,UAAU,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;IAiBvC;;;;;;;;;;;;;;;;;OAiBG;IACH,WAAW,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,EAC3E,GAAG,IAAI,EAAE,qBAAqB,CAAC,OAAO,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,GAC5D,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,UAAU,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;IAoB1C;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,EAClC,GAAG,IAAI,EAAE,qBAAqB,CAAC,OAAO,SAAS,CAAC,CAAC,CAAC,CAAC,GACjD,SAAS,CAAC,UAAU,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;IAU/B;;;;;;;;;;;;;OAaG;IACH,cAAc,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,EACvC,GAAG,IAAI,EAAE,qBAAqB,CAAC,OAAO,cAAc,CAAC,CAAC,CAAC,CAAC,GACtD,cAAc,CAAC,UAAU,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;IAQpC;;;;;;;;;;;OAWG;IACH,WAAW,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,EACpC,GAAG,IAAI,EAAE,qBAAqB,CAAC,OAAO,WAAW,CAAC,CAAC,CAAC,CAAC,GACnD,WAAW,CAAC,UAAU,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;CAOjC;AAED,OAAO,EAAE,UAAU,EAAE,CAAC"}

package/dist/Cookies/index.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Cookie reading and writing, built on Bun's native cookie primitives.
+ *
+ * {@link Cookies} extends `Bun.CookieMap`, so it keeps the whole native API —
+ * `get`, `set`, `delete`, iteration — and adds the two constructions the
+ * framework needs: parsing an inbound `Cookie` header and parsing outbound
+ * `Set-Cookie` headers back into a map.
+ *
+ * The two header formats are not interchangeable, which is why they get separate
+ * entry points: a `Cookie` header is a list of name/value pairs on one line with
+ * no attributes, while each `Set-Cookie` header is a single cookie carrying its
+ * own `Path`, `Max-Age`, `HttpOnly` and the rest.
+ *
+ * @module Cookies
+ */
+/**
+ * Parses an inbound `Cookie` header into individual cookies.
+ *
+ * The header is a semicolon-separated list of name/value pairs with no
+ * attributes, so each pair is re-serialised on its own before being handed to
+ * Bun's parser. Malformed fragments that yield no name are skipped rather than
+ * throwing — a single bad pair from a client should not fail the request.
+ *
+ * @param cookieHeader - The raw `Cookie` header value.
+ * @returns The parsed cookies, in header order. Values keep whatever encoding
+ * the client sent.
+ */
+declare function parseCookieHeader(cookieHeader: string): Array<Bun.Cookie>;
+/**
+ * Parses `Set-Cookie` header values into individual cookies, attributes
+ * included.
+ *
+ * Each header carries exactly one cookie, so no splitting is needed — unlike
+ * {@link parseCookieHeader}, which has to break one header into many pairs.
+ *
+ * @param headers - The raw `Set-Cookie` header values, one per cookie. Use
+ * `Headers.getSetCookie()` to obtain them; a plain `get` collapses repeated
+ * headers into one string and loses the boundaries.
+ * @returns The parsed cookies, in the order given.
+ */
+declare function parseSetCookieHeaders(headers: string[]): Array<Bun.Cookie>;
+/**
+ * A cookie map with header-parsing constructors.
+ *
+ * Everything `Bun.CookieMap` offers is available unchanged; the two static
+ * methods are the additions. Use {@link Cookies.fromHeader} for what a client
+ * sent and {@link Cookies.fromSetCookieHeaders} for what a server is sending
+ * back — reading a response's own cookies, or following them in a client.
+ */
+declare class Cookies extends Bun.CookieMap {
+    /**
+     * Creates a cookie map, forwarding to the native constructor.
+     *
+     * `Bun.CookieMap` is a native class that ignores `new.target`, so instances
+     * come back with the base prototype and none of the subclass members attached.
+     * The prototype is reattached here, which is what makes subclassing work at
+     * all.
+     *
+     * @param args - The native {@link Bun.CookieMap} constructor arguments.
+     */
+    constructor(...args: ConstructorParameters<typeof Bun.CookieMap>);
+    /**
+     * Builds a map from an inbound `Cookie` header.
+     *
+     * @param cookieHeader - The raw `Cookie` header value, as sent by the client.
+     * @returns The cookies it carried. Repeated names resolve to the last
+     * occurrence.
+     */
+    static fromHeader(cookieHeader: string): Cookies;
+    /**
+     * Builds a map from outbound `Set-Cookie` headers, preserving each cookie's
+     * attributes.
+     *
+     * @param headers - The raw `Set-Cookie` values, one per cookie.
+     * @returns The cookies they describe. Repeated names resolve to the last
+     * occurrence.
+     */
+    static fromSetCookieHeaders(headers: string[]): Cookies;
+}
+export { Cookies, parseCookieHeader, parseSetCookieHeaders };
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/Cookies/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;;;GAWG;AACH,iBAAS,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAQlE;AAED;;;;;;;;;;;GAWG;AACH,iBAAS,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAMnE;AAED;;;;;;;GAOG;AACH,cAAM,OAAQ,SAAQ,GAAG,CAAC,SAAS;IAClC;;;;;;;;;OASG;gBACS,GAAG,IAAI,EAAE,qBAAqB,CAAC,OAAO,GAAG,CAAC,SAAS,CAAC;IAOhE;;;;;;OAMG;IACH,MAAM,CAAC,UAAU,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO;IAMhD;;;;;;;OAOG;IACH,MAAM,CAAC,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO;CAKvD;AAED,OAAO,EAAE,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,CAAC"}

package/dist/Cors/index.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Cross-origin resource sharing.
+ *
+ * Constructing a {@link Cors} attaches it to the nearest {@link App}, which then
+ * calls it from two places: {@link App.respond} runs {@link Cors.handler} on
+ * every outgoing response, after the {@link Middleware} chain has finished, and
+ * {@link App.handlePreflight} delegates to {@link Cors.handlePreflight} for
+ * `OPTIONS` requests carrying
+ * {@link HeaderKey.AccessControlRequestMethod}. Running last is deliberate — a
+ * middleware that short-circuits the chain cannot drop the CORS headers.
+ *
+ * With no {@link Cors} attached, an app answers preflights with
+ * {@link Status.NO_CONTENT} and sends no CORS headers at all.
+ *
+ * ```ts
+ * import { Cors } from "@ozanarslan/corpus";
+ *
+ * new Cors({ allowedOrigins: ["https://example.com"], credentials: true });
+ * ```
+ *
+ * @module Cors
+ */
+import type { ContextHandler } from "../Context";
+import { HeaderKey } from "../Headers";
+/**
+ * The CORS policy. Every field is optional; an omitted field means the
+ * corresponding header is not sent, with the exception of the origin, which
+ * falls back to a wildcard.
+ */
+type CorsOptions = {
+    /** Which origins are allowed to access the resource. Use ["*"] for any origin, or specific domains. */
+    allowedOrigins?: string[];
+    /** Which HTTP methods are allowed (GET, POST, etc.) */
+    allowedMethods?: string[];
+    /** Which headers can be sent in the request */
+    allowedHeaders?: HeaderKey[];
+    /** Which headers should be exposed to the client/browser JavaScript
+     * These are response headers that the client can read
+     * @example ['RateLimit-Limit', 'RateLimit-Remaining', 'X-Custom-Header']
+     */
+    exposedHeaders?: HeaderKey[];
+    /** Whether to expose cookies and auth headers to the client */
+    credentials?: boolean;
+    /** How long (in seconds) browsers can cache preflight results. Default: 86400 (24 hours) */
+    maxAge?: number;
+    /**
+     * Whether {@link HeaderKey.AccessControlMaxAge} is sent on ordinary responses
+     * as well as on preflights. Preflights always carry it; browsers ignore it
+     * elsewhere.
+     */
+    includeMaxAgeResponseHeader?: boolean;
+};
+/**
+ * The public shape of a CORS policy, implemented by {@link Cors}. This is the
+ * type {@link App.cors} holds, so a custom policy only has to satisfy the
+ * contract.
+ */
+interface CorsInterface {
+    /** The configured {@link CorsOptions}. */
+    opts?: CorsOptions;
+    /** Preflight handler for OPTIONS requests. */
+    handlePreflight: ContextHandler;
+    /** Applies CORS headers to an outgoing response. */
+    handler: ContextHandler;
+}
+/**
+ * Default {@link CorsInterface} implementation.
+ *
+ * Both entry points share {@link Cors.applyHeaders}, so a preflight and a real
+ * response describe the same policy. The preflight builds a fresh
+ * {@link Status.NO_CONTENT} {@link Res} — it never reaches a route handler —
+ * while the response path writes onto the {@link Res} that is already being
+ * returned.
+ */
+declare class Cors implements CorsInterface {
+    opts?: CorsOptions | undefined;
+    /**
+     * Creates a policy and attaches it to the nearest {@link App}.
+     *
+     * @param opts - The {@link CorsOptions} to enforce. Omitting them yields a
+     * permissive wildcard origin with no method, header or exposure restrictions.
+     */
+    constructor(opts?: CorsOptions | undefined);
+    /**
+     * Attaches this policy to the nearest {@link App}, replacing any policy
+     * already set. Called by the constructor; an app holds exactly one.
+     */
+    register(): void;
+    /**
+     * Adds the CORS headers to an outgoing response.
+     *
+     * Called by {@link App.respond} for every response, after the handler chain
+     * has produced its result.
+     *
+     * @param c - The {@link Context} for the request, read for its `Origin` header
+     * and written to through {@link Context.res}.
+     */
+    handler: ContextHandler;
+    /**
+     * Preflight handler for OPTIONS requests.
+     *
+     * Answers with an empty {@link Status.NO_CONTENT} response carrying the full
+     * policy, including {@link HeaderKey.AccessControlMaxAge} so the browser can
+     * cache the result and skip the round trip on subsequent requests.
+     *
+     * @param c - The {@link Context} for the preflight request.
+     * @returns The preflight {@link Res}.
+     */
+    handlePreflight: ContextHandler;
+    /**
+     * Applies CORS headers to a Headers object given the request origin.
+     *
+     * Origin resolution has three outcomes. A wildcard policy sends `*`. A policy
+     * listing origins sends the request's own origin when it is listed, and no
+     * origin header at all when it is not — an unlisted origin is rejected by
+     * omission rather than by an error status. A wildcard policy combined with
+     * `credentials` reflects the request origin instead of `*`, because the spec
+     * forbids the wildcard in credentialed mode. Whenever the origin is reflected,
+     * {@link HeaderKey.Vary} is appended so caches key on it.
+     *
+     * The remaining list headers are written only when their option is a non-empty
+     * array, so an unset method or header list leaves the browser's defaults
+     * alone.
+     *
+     * @param headers - The response headers to write into.
+     * @param reqOrigin - The request's `Origin` header, or an empty string when it
+     * sent none.
+     * @param includeMaxAge - Whether to send
+     * {@link HeaderKey.AccessControlMaxAge}. Set for preflights, where it governs
+     * how long the browser caches the result. Defaults to `false`.
+     */
+    protected applyHeaders(headers: Headers, reqOrigin: string, includeMaxAge?: boolean): void;
+}
+export { Cors, type CorsInterface };
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/Cors/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEhD,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAItC;;;;GAIG;AACH,KAAK,WAAW,GAAG;IAClB,uGAAuG;IACvG,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,uDAAuD;IACvD,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,+CAA+C;IAC/C,cAAc,CAAC,EAAE,SAAS,EAAE,CAAC;IAC7B;;;OAGG;IACH,cAAc,CAAC,EAAE,SAAS,EAAE,CAAC;IAC7B,+DAA+D;IAC/D,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,4FAA4F;IAC5F,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,2BAA2B,CAAC,EAAE,OAAO,CAAC;CACtC,CAAC;AAEF;;;;GAIG;AACH,UAAU,aAAa;IACtB,0CAA0C;IAC1C,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,8CAA8C;IAC9C,eAAe,EAAE,cAAc,CAAC;IAChC,oDAAoD;IACpD,OAAO,EAAE,cAAc,CAAC;CACxB;AAED;;;;;;;;GAQG;AACH,cAAM,IAAK,YAAW,aAAa;IAOf,IAAI,CAAC,EAAE,WAAW;IANrC;;;;;OAKG;gBACgB,IAAI,CAAC,EAAE,WAAW,YAAA;IAIrC;;;OAGG;IACH,QAAQ,IAAI,IAAI;IAIhB;;;;;;;;OAQG;IACH,OAAO,EAAE,cAAc,CAErB;IAEF;;;;;;;;;OASG;IACH,eAAe,EAAE,cAAc,CAI7B;IAEF;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,SAAS,CAAC,YAAY,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,aAAa,UAAQ,GAAG,IAAI;CA2CxF;AAED,OAAO,EAAE,IAAI,EAAE,KAAK,aAAa,EAAE,CAAC"}

package/dist/Exception/index.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Throwing HTTP errors with a status attached.
+ *
+ * All errors are caught by {@link App.handleError}, whatever their type. What an
+ * {@link Exception} adds is the {@link Status} to answer with: it is rendered
+ * through {@link Exception.toRes}, message and detail intact, while an ordinary
+ * error becomes an opaque {@link Status.INTERNAL_SERVER_ERROR} so an accidental
+ * `TypeError` does not leak its message to the client.
+ *
+ * Throwing one is the intended way to end a request early:
+ *
+ * ```ts
+ * import { Exception, Status } from "@ozanarslan/corpus";
+ *
+ * if (!user) throw new Exception("User not found", Status.NOT_FOUND);
+ * ```
+ *
+ * Subclass it for errors you raise often, so the status and message live in one
+ * place rather than at every throw site.
+ *
+ * @module Exception
+ */
+import { Res, Status } from "../Res";
+/**
+ * An error carrying the {@link Status} it should be answered with.
+ *
+ * Beyond a status, an exception can carry {@link Exception.data} — either
+ * arbitrary detail to include in the error body, or a fully formed {@link Res}
+ * when the error response needs its own headers or shape.
+ */
+declare class Exception extends Error {
+    /**
+     * Creates an exception for subclasses, which assign
+     * {@link Exception.message}, {@link Exception.status} and
+     * {@link Exception.data} themselves.
+     */
+    constructor();
+    /**
+     * Creates an exception to throw from a handler.
+     *
+     * @param message - Human-readable description. It is sent to the client, so
+     * write it for whoever receives the response.
+     * @param status - The {@link Status} to answer with.
+     * @param data - Optional detail attached to the response body under `error`,
+     * such as validation failures. Pass a {@link Res} instead to control the whole
+     * error response — see {@link Exception.toRes}.
+     */
+    constructor(message: string, status: Status, data?: unknown);
+    /** Human-readable description, sent to the client in the error body. */
+    message: string;
+    /** The {@link Status} the response is sent with. */
+    status: Status;
+    /**
+     * Optional detail. An arbitrary value is placed under `error` in the response
+     * body; a {@link Res} is used as the response itself.
+     */
+    data?: unknown;
+    /**
+     * Renders the exception as the response to send.
+     *
+     * When {@link Exception.data} is a {@link Res}, that response is used directly:
+     * its status is overwritten with {@link Exception.status}, the Exception
+     * message gets discarded. Otherwise a fresh {@link Res} is built with the
+     * message and the detail under `error`.
+     *
+     * @returns The {@link Res} for this error. Called by
+     * {@link App.handleError}.
+     */
+    toRes(): Res;
+    /**
+     * Checks the exception's status, by numeric value or by {@link Status} name.
+     *
+     * Useful when catching an exception to branch on what went wrong:
+     *
+     * ```ts
+     * if (err instanceof Exception && err.isStatusOf("NOT_FOUND")) { … }
+     * ```
+     *
+     * @param status - A {@link Status} value or one of its keys.
+     * @returns `true` when {@link Exception.status} matches.
+     */
+    isStatusOf(status: Status | keyof typeof Status): boolean;
+}
+export { Exception };
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/Exception/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AAGpC;;;;;;GAMG;AACH,cAAM,SAAU,SAAQ,KAAK;IAC5B;;;;OAIG;;IAEH;;;;;;;;;OASG;gBACS,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO;IAY3D,wEAAwE;IAC/D,OAAO,EAAG,MAAM,CAAC;IAE1B,oDAAoD;IACpD,MAAM,EAAG,MAAM,CAAC;IAEhB;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IAEf;;;;;;;;;;OAUG;IACH,KAAK,IAAI,GAAG;IAQZ;;;;;;;;;;;OAWG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,OAAO,MAAM,GAAG,OAAO;CAGzD;AAED,OAAO,EAAE,SAAS,EAAE,CAAC"}