@ozanarslan/corpus 0.0.1

package/dist/App/index.d.ts

@@ -0,0 +1,377 @@
+/**
+ * The application root: owns the {@link Server}, the route table, the
+ * {@link Middleware} registry, and the request lifecycle that ties them
+ * together.
+ *
+ * An {@link App} is the only thing that talks to Bun's HTTP server.
+ * {@link RouteBase} implementations and {@link Middleware} instances register
+ * themselves against an app, and at {@link App.listen} time the app compiles
+ * them into a single {@link ServerRouteMap} plus a fallback {@link ServerHandler}.
+ *
+ * ```ts
+ * const app = new App({ port: 3000, prefix: "/api" });
+ * await app.listen();
+ * ```
+ *
+ * @module App
+ */
+import { type ContextFactory, type ContextHandler, Context } from "../Context";
+import type { CorsInterface } from "../Cors";
+import type { Middleware } from "../Middleware";
+import { type RouteBase } from "../RouteBase";
+import type { Server, ServerHandler, ServerRouteMap } from "../Server";
+import { type MaybePromise, type Nullable, type Optional, type OrString } from "../utils/is";
+/**
+ * TLS material used to serve an {@link App} over HTTPS.
+ *
+ * Passing this to {@link App} switches {@link App.baseUrl} to the `https`
+ * scheme and hands the certificate straight to Bun's server.
+ */
+interface TlsOptions {
+    /** PEM-encoded certificate chain, as a string or a file buffer. */
+    cert: string | Buffer;
+    /** PEM-encoded private key matching {@link TlsOptions.cert}. */
+    key: string | Buffer;
+    /** Optional PEM-encoded certificate authority bundle for client verification. */
+    ca?: string | Buffer;
+}
+/**
+ * Construction options for {@link App}. Every field is optional; omitted fields
+ * keep the defaults declared on {@link App}.
+ */
+interface AppOptions {
+    /** TCP port to bind. See {@link App.port}. */
+    port?: number;
+    /**
+     * Path prefix prepended to the endpoint of every {@link RouteBase} registered
+     * on the app. See {@link App.prefix}.
+     */
+    prefix?: string;
+    /** Interface to bind. See {@link App.hostname}. */
+    hostname?: OrString<"0.0.0.0" | "127.0.0.1" | "localhost">;
+    /** Seconds a connection may stay idle before Bun closes it. See {@link App.idleTimeout}. */
+    idleTimeout?: number;
+    /** {@link TlsOptions} to serve the app over HTTPS. See {@link App.tls}. */
+    tls?: TlsOptions;
+    /**
+     * App-wide request body ceiling in bytes, handed to Bun's server. An
+     * individual {@link RouteBase} can tighten this through its own
+     * {@link Config}, which {@link enforceBodyLimit} applies per request.
+     */
+    maxRequestBodySize?: number;
+}
+/**
+ * Handles an {@link Error} raised anywhere in the request lifecycle. Assigned to
+ * {@link App.handleError}.
+ *
+ * @param error - The thrown error, typically an {@link Exception}.
+ * @param context - The {@link Context} the error was raised in. Absent only when
+ * the failure happened before a {@link Context} could be built.
+ * @returns The value to respond with — a {@link Res}, a plain body that
+ * {@link App.respond} will assign to {@link Res.body}, or a promise of either.
+ */
+type ErrorHandler<R = unknown> = (error: Error, context?: Context) => MaybePromise<R>;
+/**
+ * The public shape of an application instance, implemented by {@link App}.
+ *
+ * Depend on this type rather than the {@link App} class when you need to accept
+ * an app without pinning the implementation.
+ */
+interface AppInterface {
+    /** The running {@link Server}, or `null` before {@link AppInterface.listen} and after {@link AppInterface.close}. */
+    server: Nullable<Server>;
+    /** {@link CorsInterface} policy applied to every response and to preflight requests. */
+    cors: Optional<CorsInterface>;
+    /** {@link RouteBase} instances registered on this app, in registration order. */
+    routes: Array<RouteBase>;
+    /** {@link Middleware} instances keyed by the {@link RouteBase.id} they target; `"*"` holds the global ones. */
+    middlewares: Map<string, Array<Middleware>>;
+    /** TCP port to bind. */
+    port: number;
+    /** Path prefix prepended to every {@link RouteBase} endpoint on this app. */
+    prefix: string;
+    /** Interface to bind. */
+    hostname: OrString<"0.0.0.0" | "127.0.0.1" | "localhost">;
+    /** Seconds a connection may stay idle before Bun closes it. */
+    idleTimeout?: number;
+    /** {@link TlsOptions} material; when set, the app is served over HTTPS. */
+    tls?: TlsOptions;
+    /** Origin the app is reachable at. */
+    get baseUrl(): string;
+    /** Compiles {@link RouteBase} and {@link Middleware} registrations and starts the {@link Server}. */
+    listen(): Promise<void>;
+    /** Stops the {@link Server} and releases the port. */
+    close(closeActiveConnections?: boolean): Promise<void>;
+    /** Hook run just before the {@link Server} starts. */
+    handleBeforeListen: Optional<() => MaybePromise<void>>;
+    /** Hook run just before the {@link Server} stops. */
+    handleBeforeClose: Optional<() => MaybePromise<void>>;
+    /** {@link ErrorHandler} that converts a thrown {@link Error} into a response value. */
+    handleError: ErrorHandler;
+    /** {@link ContextHandler} that produces the response for requests matching no {@link RouteBase}. */
+    handleNotFound: ContextHandler;
+    /** {@link ContextHandler} that produces the response for CORS preflight requests. */
+    handlePreflight: ContextHandler;
+    /** {@link ContextFactory} that builds the {@link Context} for each incoming request. */
+    contextFactory: ContextFactory;
+    /** Registers a {@link Middleware} against each {@link RouteBase.id} it targets. */
+    addMiddleware(middleware: Middleware): void;
+    /** Resolves the {@link Middleware} instances that apply to a {@link RouteBase.id}. */
+    findMiddlewares(routeId: string): Array<Middleware>;
+}
+/**
+ * An HTTP application.
+ *
+ * The app is a container first: {@link RouteBase} implementations and
+ * {@link Middleware} instances attach to it as they are constructed. Nothing is
+ * compiled until {@link App.listen}, at which point {@link App.composeRoutes}
+ * turns routes into a {@link ServerRouteMap} and folds the matching
+ * {@link Middleware} handlers into each route's chain.
+ *
+ * Every request follows the same path — build a {@link Context}, resolve
+ * {@link Context.params}, {@link Context.search} and {@link Context.body}
+ * through the parsers registry, run the {@link composeHandlerChain} chain, apply
+ * {@link CorsInterface}, and serialise the {@link Res}. Anything thrown along
+ * the way is routed to {@link App.handleError}.
+ *
+ * Constructing an app calls {@link registerApp}, so it is discoverable without
+ * being passed around.
+ */
+declare class App implements AppInterface {
+    /**
+     * Creates an app and registers it globally with {@link registerApp}.
+     *
+     * @param opts - {@link AppOptions} overriding port, hostname, prefix, idle
+     * timeout, {@link TlsOptions} and body size. Any field left out keeps the
+     * default declared on the corresponding {@link App} property.
+     */
+    constructor(opts?: AppOptions);
+    /**
+     * The live {@link Server}. `null` until {@link App.listen} is called and again
+     * after {@link App.close}.
+     */
+    server: Nullable<Server>;
+    /**
+     * {@link CorsInterface} policy for this app. When set,
+     * {@link CorsInterface.handler} runs after every handler chain in
+     * {@link App.respond} and {@link CorsInterface.handlePreflight} answers
+     * preflight requests. Left unset, {@link App.handlePreflight} replies with
+     * {@link Status.NO_CONTENT} and no CORS headers are added.
+     */
+    cors: Optional<CorsInterface>;
+    /** {@link RouteBase} instances attached to this app, in registration order. */
+    routes: Array<RouteBase>;
+    /**
+     * {@link Middleware} instances indexed by the {@link RouteBase.id} they
+     * target. The `"*"` key holds middlewares that run on every route as well as
+     * on the {@link App.handleNotFound} path.
+     */
+    middlewares: Map<string, Array<Middleware>>;
+    /** Port the {@link Server} binds to. Defaults to `3000`. */
+    port: number;
+    /** Prefix prepended to every {@link RouteBase} endpoint on this app. Defaults to `""`. */
+    prefix: string;
+    /** Interface the {@link Server} binds to. Defaults to `"0.0.0.0"`. */
+    hostname: OrString<"0.0.0.0" | "127.0.0.1" | "localhost">;
+    /** Seconds an idle connection is kept open before Bun closes it. */
+    idleTimeout?: number;
+    /** {@link TlsOptions} material. When present the app is served over HTTPS. */
+    tls?: TlsOptions;
+    /**
+     * App-wide body ceiling in bytes passed to Bun. A {@link RouteBase} may
+     * declare a tighter limit in its {@link Config}, enforced per request by
+     * {@link enforceBodyLimit}.
+     */
+    maxRequestBodySize?: number;
+    /**
+     * Origin the app is reachable at, for example `http://0.0.0.0:3000`.
+     *
+     * @returns The {@link Server} URL once listening; otherwise a URL derived from
+     * {@link App.tls}, {@link App.hostname} and {@link App.port}.
+     */
+    get baseUrl(): string;
+    /**
+     * Compiles {@link App.composeRoutes} and {@link App.composeFetch} and hands
+     * them to `Bun.serve`, wiring the WebSocket callbacks through to the handlers
+     * carried by each {@link WebSocketRoute}. Unroutable middlewares are reported
+     * first by {@link App.warnUnmatchedMiddlewares}.
+     *
+     * Calling this when {@link App.server} already exists is a no-op that returns
+     * the existing one, so it is safe to reach for lazily.
+     *
+     * @returns The running {@link Server}.
+     */
+    protected createServer(): Server;
+    /**
+     * Starts the app.
+     *
+     * Installs `SIGINT` and `SIGTERM` handlers that call {@link App.close}, runs
+     * {@link App.handleBeforeListen}, then compiles and starts the {@link Server}
+     * via {@link App.createServer}. A failure at any of these steps is logged and
+     * the app is closed rather than left half-started.
+     *
+     * @returns A promise that resolves once the {@link Server} is listening.
+     */
+    listen(): Promise<void>;
+    /**
+     * Stops the app.
+     *
+     * Runs {@link App.handleBeforeClose}, stops the {@link Server}, and clears
+     * {@link App.server}. Outside the `test` value of {@link Config.nodeEnv} this
+     * also exits the process, so tests can close apps without tearing down the
+     * runner.
+     *
+     * @param closeActiveConnections - Whether in-flight connections are severed
+     * immediately rather than allowed to drain. Defaults to `true`.
+     * @returns A promise that resolves once the {@link Server} has stopped.
+     */
+    close(closeActiveConnections?: boolean): Promise<void>;
+    /**
+     * Compiles {@link App.routes} into the {@link ServerRouteMap} Bun expects,
+     * keyed by endpoint and then by {@link Method}.
+     *
+     * Each entry is a full request pipeline wrapped in {@link App.finalize}:
+     * wildcard segments are lifted into {@link Req.params} (Bun does not treat
+     * them as params), then params, search and body are parsed and validated
+     * against the {@link RouteBase} {@link Config} — but only the ones the handler
+     * chain actually reads, as reported by {@link getContextAccess}. Routes with
+     * {@link RouteVariant.websocket} upgrade the connection into a
+     * {@link WebSocketRoute} instead of responding, and {@link Method.GET} and
+     * {@link Method.HEAD} skip body work entirely.
+     *
+     * @returns A {@link ServerRouteMap} ready to hand to `Bun.serve`.
+     * @throws {@link Exception} with {@link Status.UPGRADE_REQUIRED} when a
+     * WebSocket upgrade is rejected.
+     */
+    protected composeRoutes(): ServerRouteMap;
+    /**
+     * Builds the {@link ServerHandler} Bun uses for requests that matched no
+     * {@link RouteBase}.
+     *
+     * Preflight requests — {@link Method.OPTIONS} carrying
+     * {@link HeaderKey.AccessControlRequestMethod} — go to
+     * {@link App.handlePreflight}. Everything else runs the global (`"*"`)
+     * {@link Middleware} chain followed by {@link App.handleNotFound}, so global
+     * middlewares still observe traffic to unknown endpoints.
+     *
+     * @returns The `fetch` handler for `Bun.serve`, wrapped by
+     * {@link App.finalize}.
+     */
+    protected composeFetch(): ServerHandler;
+    /**
+     * Wraps a {@link ContextHandler} into the {@link ServerHandler} Bun calls,
+     * giving it a {@link Context} from {@link App.contextFactory} and guaranteeing
+     * that every outcome — value or throw — leaves as a `Response`.
+     *
+     * This is the single boundary where errors are caught, so every throw reaches
+     * {@link App.handleError} through {@link App.respondWithError}.
+     *
+     * @param handler - The {@link ContextHandler} to run for the request.
+     * @returns A {@link ServerHandler} suitable for a {@link ServerRouteMap} entry
+     * or for `Bun.serve`'s `fetch`.
+     */
+    protected finalize(handler: ContextHandler): ServerHandler;
+    /**
+     * Turns a handler's return value into the response sent over the wire.
+     *
+     * A returned {@link Res} replaces {@link Context.res} wholesale; any other
+     * defined value becomes {@link Res.body}; `undefined` leaves the existing
+     * {@link Res} untouched, which is how handlers that mutate
+     * {@link Context.res} directly are supported. {@link CorsInterface.handler}
+     * runs last and separately from the {@link Middleware} chain, so CORS headers
+     * cannot be clobbered by a short-circuiting middleware.
+     *
+     * @param context - The {@link Context} for the request.
+     * @param result - Whatever the handler chain returned.
+     * @returns The native `Response` produced by {@link Res.toNativeResponse}.
+     */
+    protected respond(context: Context, result: unknown): Promise<Response>;
+    /**
+     * Runs {@link App.handleError} and responds with its result.
+     *
+     * If the error handler itself throws, that second failure is logged and a bare
+     * {@link Status.INTERNAL_SERVER_ERROR} is returned — the request never escapes
+     * without a response.
+     *
+     * @param context - The {@link Context} the failure occurred in.
+     * @param err - The {@link Error} thrown by the handler chain.
+     * @returns The error response.
+     */
+    protected respondWithError(context: Context, err: Error): Promise<Response>;
+    /**
+     * Hook run inside {@link App.listen}, before the {@link Server} is created.
+     * Use it for setup that must complete before traffic is accepted; throwing
+     * here aborts startup and closes the app.
+     */
+    handleBeforeListen: Optional<() => MaybePromise<void>>;
+    /**
+     * Hook run inside {@link App.close}, before the {@link Server} is stopped. Use
+     * it to release resources the app owns.
+     */
+    handleBeforeClose: Optional<() => MaybePromise<void>>;
+    /**
+     * Default {@link ErrorHandler}. An {@link Exception} is rendered through
+     * {@link Exception.toRes}; anything else becomes an opaque
+     * {@link Status.INTERNAL_SERVER_ERROR} {@link Res}, so internal failures never
+     * leak their message. Replace it to customise error output.
+     *
+     * @param err - The thrown {@link Error}.
+     * @returns The {@link Res} to send.
+     */
+    handleError: ErrorHandler;
+    /**
+     * Default {@link ContextHandler} for unmatched requests. Replace it to
+     * customise the 404 body.
+     *
+     * @param c - The {@link Context} for the unmatched request.
+     * @returns A {@link Status.NOT_FOUND} {@link Res} naming the method and URL
+     * that did not resolve.
+     */
+    handleNotFound: ContextHandler;
+    /**
+     * Default {@link ContextHandler} for CORS preflight requests. Delegates to
+     * {@link CorsInterface.handlePreflight} when {@link App.cors} is configured.
+     *
+     * @param c - The {@link Context} for the preflight request.
+     * @returns The CORS preflight response, or an empty
+     * {@link Status.NO_CONTENT} {@link Res} when no {@link CorsInterface} is set.
+     */
+    handlePreflight: ContextHandler;
+    /**
+     * Default {@link ContextFactory}. Replace it to have the app build a
+     * {@link Context} subclass carrying your own per-request state.
+     *
+     * @param request - The incoming request.
+     * @param server - The {@link Server} that accepted it.
+     * @returns A new {@link Context}.
+     */
+    contextFactory: ContextFactory;
+    /**
+     * Registers a {@link Middleware} under every {@link RouteBase.id} in
+     * {@link Middleware.routeIds}, so one instance can serve several routes.
+     *
+     * @param middleware - The {@link Middleware} to register.
+     */
+    addMiddleware(middleware: Middleware): void;
+    /**
+     * Resolves the {@link Middleware} instances that apply to a route, global ones
+     * first so they wrap the route-specific ones.
+     *
+     * @param routeId - The {@link RouteBase.id} to resolve for, or `"*"` to get
+     * only the global middlewares without duplicating them.
+     * @returns The middlewares in execution order.
+     */
+    findMiddlewares(routeId: string): Array<Middleware>;
+    /**
+     * Logs a warning for every {@link Middleware} whose target
+     * {@link RouteBase.id} is not registered on this app and which therefore can
+     * never run — usually a typo or a route that was never attached.
+     *
+     * Runs from {@link App.createServer} rather than {@link App.addMiddleware},
+     * because registration order is not guaranteed and a middleware may legally be
+     * added before its route.
+     */
+    protected warnUnmatchedMiddlewares(): void;
+}
+export { App, type AppInterface };
+//# sourceMappingURL=index.d.ts.map

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

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

package/dist/C.namespace.d.ts

@@ -0,0 +1,27 @@
+export { App, type AppInterface } from "./App";
+export { BodyParser, type BodyParserInterface } from "./ParserBase/BodyParser";
+export { BundleRoute } from "./RouteBase/BundleRoute";
+export { Config } from "./Config";
+export { Context, type ContextFactory } from "./Context";
+export { Controller } from "./Controller";
+export { Cookies } from "./Cookies";
+export { Cors, type CorsInterface } from "./Cors";
+export { Exception } from "./Exception";
+export { FileRoute } from "./RouteBase/FileRoute";
+export { FormDataParser } from "./ParserBase/FormDataParser";
+export { HeaderKey, type CacheControlDefinition, type ContentDispositionDefinition } from "./Headers";
+export { Middleware, type MiddlewareDefinition, type MiddlewareUseOn, type MiddlewareHandler } from "./Middleware";
+export { ParserBase, type ParserBaseInterface } from "./ParserBase";
+export { RateLimiter, RateLimiterMemoryStore, type RateLimiterStoreInterface, type RateLimiterConfig } from "./RateLimiter";
+export { Method } from "./Request";
+export { Res, Status } from "./Res";
+export { Route } from "./RouteBase/Route";
+export { RouteBase, RouteVariant, type RouteAddress, type RouteConfig } from "./RouteBase";
+export { SchemaParser, type SchemaParserInterface, type InferModel } from "./ParserBase/SchemaParser";
+export { SearchParamsParser } from "./ParserBase/SearchParamsParser";
+export type { Server, ServerWebSocket, ServerHandler, ServerRouteMap } from "./Server";
+export { StaticRoute } from "./RouteBase/StaticRoute";
+export { URLParamsParser } from "./ParserBase/URLParamsParser";
+export { WebSocketRoute, type WebSocketRouteDefinition, type WebSocketOnOpen, type WebSocketOnClose, type WebSocketOnMessage } from "./RouteBase/WebSocketRoute";
+export { XFile } from "./XFile";
+//# sourceMappingURL=C.namespace.d.ts.map

package/dist/C.namespace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"C.namespace.d.ts","sourceRoot":"","sources":["../src/C.namespace.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,GAAG,EAAE,KAAK,YAAY,EAAE,MAAM,OAAO,CAAC;AAE/C,OAAO,EAAE,UAAU,EAAE,KAAK,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAE/E,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAEtD,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAElC,OAAO,EAAE,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC;AAEzD,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE1C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,IAAI,EAAE,KAAK,aAAa,EAAE,MAAM,QAAQ,CAAC;AAElD,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAQ7D,OAAO,EAAE,SAAS,EAAE,KAAK,sBAAsB,EAAE,KAAK,4BAA4B,EAAE,MAAM,WAAW,CAAC;AAEtG,OAAO,EAAE,UAAU,EAAE,KAAK,oBAAoB,EAAE,KAAK,eAAe,EAAE,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEnH,OAAO,EAAE,UAAU,EAAE,KAAK,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAEpE,OAAO,EAAE,WAAW,EAAE,sBAAsB,EAAE,KAAK,yBAAyB,EAAE,KAAK,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAE5H,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAEnC,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AAEpC,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAE1C,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,KAAK,YAAY,EAAE,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAE3F,OAAO,EAAE,YAAY,EAAE,KAAK,qBAAqB,EAAE,KAAK,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAEtG,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAErE,YAAY,EAAE,MAAM,EAAE,eAAe,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAEvF,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAEtD,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAE/D,OAAO,EAAE,cAAc,EAAE,KAAK,wBAAwB,EAAE,KAAK,eAAe,EAAE,KAAK,gBAAgB,EAAE,KAAK,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAEjK,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC"}

package/dist/Config/index.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Typed access to environment variables and the current runtime environment.
+ *
+ * {@link Config} is a static façade over `process.env` — nothing is cached, so a
+ * read always reflects the current value. Beyond convenience, it is what the
+ * framework itself consults for environment-dependent behaviour: {@link App}
+ * checks {@link Config.nodeEnv} before exiting the process on
+ * {@link App.close}.
+ *
+ * Declare your variables on {@link Env} in your own code to get autocompletion
+ * and a checked key for every lookup.
+ *
+ * ```ts
+ * const port = Config.get("PORT", { parser: Number, fallback: 3000 });
+ * const secret = Config.require("JWT_SECRET");
+ * ```
+ *
+ * @module Config
+ */
+import { type OrString } from "../utils/is";
+/**
+ * Declaration target for an application's environment variables.
+ *
+ * Empty by design. Augment it from your own code and every key you add becomes a
+ * suggested {@link EnvKey}:
+ *
+ * ```ts
+ * declare module "corpus" {
+ *   interface Env {
+ *     DATABASE_URL: string;
+ *     JWT_SECRET: string;
+ *   }
+ * }
+ * ```
+ */
+interface Env {
+}
+/**
+ * The value of `NODE_ENV`. The three known environments are suggested, but any
+ * string is accepted — {@link OrString} keeps the literals as hints rather than
+ * as a closed set.
+ */
+type NodeEnv = OrString<"development" | "production" | "test">;
+/**
+ * A variable name accepted by the {@link Config} lookups. Keys declared on
+ * {@link Env} are suggested; any other string still resolves.
+ */
+type EnvKey = OrString<keyof Env>;
+/**
+ * Static accessor for environment variables.
+ *
+ * Every read goes straight to `process.env`, so a variable set after startup —
+ * by a test, or by {@link Config.set} — is visible immediately.
+ *
+ * The three lookups differ in how they treat a missing value:
+ * {@link Config.get} returns `undefined` or a fallback, {@link Config.require}
+ * throws, and {@link Config.has} only reports presence.
+ */
+declare class Config {
+    /**
+     * The live `process.env` object.
+     *
+     * @returns The environment, unwrapped. Reading it directly bypasses the
+     * parsing and fallback handling of {@link Config.get}.
+     */
+    static get env(): NodeJS.ProcessEnv;
+    /**
+     * The current environment name.
+     *
+     * @returns The value of `NODE_ENV`, or `"development"` when it is unset — an
+     * unconfigured process is treated as a development one.
+     */
+    static get nodeEnv(): NodeEnv;
+    /**
+     * @returns `true` when {@link Config.nodeEnv} is `"production"`.
+     */
+    static get isProd(): boolean;
+    /**
+     * @returns `true` when {@link Config.nodeEnv} is `"development"`, including
+     * when `NODE_ENV` is unset.
+     */
+    static get isDev(): boolean;
+    /**
+     * @returns `true` when {@link Config.nodeEnv} is `"test"`. {@link App.close}
+     * checks this to avoid exiting the process out from under a test runner.
+     */
+    static get isTest(): boolean;
+    /**
+     * Reports whether a variable is set, without reading its value.
+     *
+     * @param key - The variable name to check.
+     * @returns `true` when the variable is defined. An empty string counts as
+     * defined.
+     */
+    static has(key: EnvKey): boolean;
+    /**
+     * Reads a variable as a raw string.
+     *
+     * @param key - The variable name to read.
+     * @returns The value, or `undefined` when unset.
+     */
+    static get(key: EnvKey): string | undefined;
+    /**
+     * Reads a variable with a guaranteed result, since a fallback covers the unset
+     * case.
+     *
+     * @param key - The variable name to read.
+     * @param opts - Lookup options.
+     * @param opts.parser - Converts the raw string into the value you want. Not
+     * applied to the fallback, which is used as given.
+     * @param opts.fallback - Returned when the variable is unset.
+     * @returns The parsed value, or the fallback.
+     */
+    static get<T = string>(key: EnvKey, opts: {
+        parser?: (raw: string) => T;
+        fallback: T;
+    }): T;
+    /**
+     * Reads and converts a variable with no fallback.
+     *
+     * @param key - The variable name to read.
+     * @param opts - Lookup options.
+     * @param opts.parser - Converts the raw string into the value you want.
+     * @param opts.fallback - Returned when the variable is unset.
+     * @returns The parsed value, or `undefined` when the variable is unset.
+     */
+    static get<T = string>(key: EnvKey, opts: {
+        parser: (raw: string) => T;
+        fallback?: T;
+    }): T | undefined;
+    /**
+     * Reads a variable that the application cannot run without.
+     *
+     * @param key - The variable name to read.
+     * @returns The raw value.
+     * @throws {@link Error} when the variable is unset.
+     */
+    static require(key: EnvKey): string;
+    /**
+     * Reads and converts a variable that the application cannot run without.
+     *
+     * @param key - The variable name to read.
+     * @param parser - Converts the raw string into the value you want.
+     * @returns The parsed value.
+     * @throws {@link Error} when the variable is unset. The parser is never called
+     * in that case, so it can assume a real value.
+     */
+    static require<T = string>(key: EnvKey, parser: (raw: string) => T): T;
+    /**
+     * Writes a variable into the environment, stringifying the value the way the
+     * environment stores everything.
+     *
+     * Mutates the real `process.env`, so the change is visible to every reader in
+     * the process, not only to {@link Config}.
+     *
+     * @param key - The variable name to write.
+     * @param value - The value to store; numbers and booleans are converted to
+     * their string form.
+     */
+    static set(key: string, value: string | number | boolean): void;
+}
+export { Config, type Env };
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/Config/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAuB,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEhE;;;;;;;;;;;;;;GAcG;AACH,UAAU,GAAG;CAAG;AAEhB;;;;GAIG;AACH,KAAK,OAAO,GAAG,QAAQ,CAAC,aAAa,GAAG,YAAY,GAAG,MAAM,CAAC,CAAC;AAE/D;;;GAGG;AACH,KAAK,MAAM,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC;AAElC;;;;;;;;;GASG;AACH,cAAM,MAAM;IACX;;;;;OAKG;IACH,MAAM,KAAK,GAAG,IAAI,MAAM,CAAC,UAAU,CAElC;IAED;;;;;OAKG;IACH,MAAM,KAAK,OAAO,IAAI,OAAO,CAE5B;IAED;;OAEG;IACH,MAAM,KAAK,MAAM,IAAI,OAAO,CAE3B;IAED;;;OAGG;IACH,MAAM,KAAK,KAAK,IAAI,OAAO,CAE1B;IAED;;;OAGG;IACH,MAAM,KAAK,MAAM,IAAI,OAAO,CAE3B;IAED;;;;;;OAMG;IACH,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIhC;;;;;OAKG;IACH,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAC3C;;;;;;;;;;OAUG;IACH,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,CAAC,CAAC;QAAC,QAAQ,EAAE,CAAC,CAAA;KAAE,GAAG,CAAC;IAC1F;;;;;;;;OAQG;IACH,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,MAAM,EACpB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;QAAE,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,CAAC,CAAC;QAAC,QAAQ,CAAC,EAAE,CAAC,CAAA;KAAE,GAChD,CAAC,GAAG,SAAS;IAehB;;;;;;OAMG;IACH,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IACnC;;;;;;;;OAQG;IACH,MAAM,CAAC,OAAO,CAAC,CAAC,GAAG,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,CAAC,GAAG,CAAC;IAStE;;;;;;;;;;OAUG;IACH,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI;CAG/D;AAED,OAAO,EAAE,MAAM,EAAE,KAAK,GAAG,EAAE,CAAC"}

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

@@ -0,0 +1,50 @@
+/**
+ * Works out which parts of a request a route actually uses, so the rest can be
+ * skipped.
+ *
+ * Parsing a body, a query string and path parameters costs work, and most
+ * handlers only use one of them. Before serving a route, {@link App} asks this
+ * module what the handler chain reads and then parses only that.
+ *
+ * The answer comes from reading the handler's own source: `fn.toString()` gives
+ * back the function's text, and every mention of the context parameter is
+ * checked. `c.body` is a read of the body. `({ params }) => …` is a read of the
+ * params. Anything less obvious — passing `c` to another function, returning it,
+ * indexing it with a variable — means the handler could reach anything, so
+ * everything gets parsed.
+ *
+ * That fallback is the rule the whole module follows: when in doubt, parse it
+ * all. Guessing "unused" wrongly would hand a handler an empty body it was
+ * counting on. Guessing "used" wrongly just does some work nobody needed.
+ *
+ * @module ContextAccess
+ */
+import type { RouteConfig } from "../../RouteBase";
+import { type Optional } from "../../utils/is";
+/**
+ * The context properties whose population can be skipped. Order is irrelevant;
+ * this exists so the key list, the record type, and the runtime loops can never
+ * drift apart.
+ */
+declare const KEYS: readonly ["body", "search", "params"];
+/** One of the skippable {@link Context} properties: `body`, `search` or `params`. */
+type ContextAccessKey = (typeof KEYS)[number];
+/** Which properties to parse. `true` means the handler chain might read it. */
+type ContextAccess = Record<ContextAccessKey, boolean>;
+/**
+ * Combines every handler in a route's chain into one answer.
+ *
+ * A property is parsed if any handler reads it, so a {@link Middleware} that
+ * needs the body still gets one even when the route handler ignores it. A key
+ * with a schema in the route's {@link RouteConfig} is always parsed — skipping
+ * it would let an invalid payload through unvalidated.
+ *
+ * @param handlers - Every function in the chain, middleware and route handler
+ * alike.
+ * @param config - The route's config, read for its schemas.
+ * @returns Which properties {@link App} should populate on the
+ * {@link Context}.
+ */
+declare function getContextAccess(handlers: ReadonlyArray<Function>, config: Optional<RouteConfig>): ContextAccess;
+export { getContextAccess };
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/Context/ContextAccess/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAA4B,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AAErE;;;;GAIG;AACH,QAAA,MAAM,IAAI,uCAAwC,CAAC;AAEnD,qFAAqF;AACrF,KAAK,gBAAgB,GAAG,CAAC,OAAO,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9C,+EAA+E;AAC/E,KAAK,aAAa,GAAG,MAAM,CAAC,gBAAgB,EAAE,OAAO,CAAC,CAAC;AAiQvD;;;;;;;;;;;;;GAaG;AACH,iBAAS,gBAAgB,CACxB,QAAQ,EAAE,aAAa,CAAC,QAAQ,CAAC,EACjC,MAAM,EAAE,QAAQ,CAAC,WAAW,CAAC,GAC3B,aAAa,CAiBf;AAED,OAAO,EAAE,gBAAgB,EAAE,CAAC"}