@mpen/routekit 0.1.0 → 0.1.2

package/dist/content-BuDOmhH_.mjs

@@ -0,0 +1,102 @@
+import { a as response } from "./core-DbmQauwS.mjs";
+import { CommonContentTypes, CommonHeaders, HttpStatus } from "@mpen/http";
+//#region src/router/lib/format.ts
+const FULL_WIDE_FORMAT = new Intl.NumberFormat("en-US", {
+	useGrouping: false,
+	maximumFractionDigits: 20
+});
+const DECIMAL_STRING = /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/;
+const MAX_SAFE_INTEGER_STRING = String(Number.MAX_SAFE_INTEGER);
+const MIN_SAFE_INTEGER_STRING = String(Number.MIN_SAFE_INTEGER);
+/**
+* Formats a number with full decimal places.
+*
+* e.g. `1e21` formats as "1000000000000000000000" instead of "1e+21"
+*
+* @param n The number to format.
+*/
+function fullWide(n) {
+	if (typeof n === "bigint") return n.toString();
+	if (typeof n === "string") {
+		if (n === "Infinity" || n === "+Infinity") return MAX_SAFE_INTEGER_STRING;
+		if (n === "-Infinity") return MIN_SAFE_INTEGER_STRING;
+		if (!DECIMAL_STRING.test(n)) return "0";
+		return FULL_WIDE_FORMAT.format(n);
+	}
+	if (n === Number.POSITIVE_INFINITY) return MAX_SAFE_INTEGER_STRING;
+	if (n === Number.NEGATIVE_INFINITY) return MIN_SAFE_INTEGER_STRING;
+	if (!Number.isFinite(n)) return "0";
+	return FULL_WIDE_FORMAT.format(n);
+}
+//#endregion
+//#region src/router/response/formats/content/content.ts
+function text(value, init = {}) {
+	const responseHeaders = new Headers(init.headers);
+	responseHeaders.set(CommonHeaders.CONTENT_TYPE, CommonContentTypes.PLAIN_TEXT);
+	responseHeaders.set(CommonHeaders.CONTENT_LENGTH, fullWide(new TextEncoder().encode(value).length));
+	return response(value, {
+		...init,
+		headers: responseHeaders,
+		status: init.status ?? HttpStatus.OK
+	});
+}
+function html(value, init = {}) {
+	const responseHeaders = new Headers(init.headers);
+	responseHeaders.set(CommonHeaders.CONTENT_TYPE, CommonContentTypes.HTML);
+	responseHeaders.set(CommonHeaders.CONTENT_LENGTH, fullWide(new TextEncoder().encode(value).length));
+	return response(value, {
+		...init,
+		headers: responseHeaders,
+		status: init.status ?? HttpStatus.OK
+	});
+}
+//#endregion
+//#region src/router/response/formats/content/bodyless.ts
+/**
+* Create an empty response with the provided status.
+*
+* @example
+* ```ts
+* return empty(HttpStatus.ACCEPTED)
+* ```
+*
+* @param statusCode - HTTP status code to use.
+* @param init - Response headers.
+* @returns Routekit logical response with no body.
+*/
+function empty(statusCode = HttpStatus.NO_CONTENT, init = {}) {
+	return response(void 0, {
+		...init,
+		status: statusCode
+	});
+}
+/**
+* Create a `204 No Content` response.
+*
+* @example
+* ```ts
+* return noContent()
+* ```
+*
+* @returns Routekit logical response with no body.
+*/
+function noContent() {
+	return empty(HttpStatus.NO_CONTENT);
+}
+/**
+* Create a redirect response.
+*
+* @example
+* ```ts
+* return redirect('/login')
+* ```
+*
+* @param url - Redirect target URL.
+* @param statusCode - Redirect status code. Defaults to `302`.
+* @returns Routekit logical response with a `Location` header.
+*/
+function redirect(url, statusCode = HttpStatus.FOUND) {
+	return empty(statusCode, { headers: { Location: url } });
+}
+//#endregion
+export { text as a, html as i, noContent as n, redirect as r, empty as t };

package/dist/core-CzUCxvGk.d.mts

@@ -0,0 +1,140 @@
+import { HttpStatus } from "@mpen/http";
+
+//#region src/router/fetch-types.d.ts
+/**
+ * Headers initializer accepted by the active Fetch runtime.
+ *
+ * @internal
+ */
+type RouterHeadersInit = NonNullable<ConstructorParameters<typeof Headers>[0]>;
+/**
+ * Response body initializer accepted by the active Fetch runtime.
+ *
+ * @internal
+ */
+type RouterBodyInit = NonNullable<ConstructorParameters<typeof Response>[0]>;
+//#endregion
+//#region src/router/response/core.d.ts
+declare const routekitResponseBrand: unique symbol;
+declare const routekitBodyBrand: unique symbol;
+/**
+ * Logical route result used by Routekit before it is finalized into a native [`Response`]{@link Response}.
+ *
+ * @example
+ * ```ts
+ * const result = ok({payload: 'ready'})
+ * ```
+ */
+interface RoutekitResponse<T = unknown, Status extends number = number> {
+  readonly [routekitResponseBrand]: true;
+  /**
+   * HTTP status code to use for the finalized response.
+   */
+  status: Status;
+  /**
+   * Headers to include in the finalized response.
+   */
+  headers: Headers;
+  /**
+   * Logical or represented response body.
+   */
+  body: T;
+}
+/**
+ * Options accepted by logical response helpers.
+ */
+interface RoutekitResponseInit<Status extends number = number> {
+  /**
+   * HTTP status code for the response. Defaults to `200`.
+   */
+  status?: Status;
+  /**
+   * Headers to include in the finalized response.
+   */
+  headers?: RouterHeadersInit;
+}
+/**
+ * Final body wrapper returned from a handler or generator.
+ *
+ * @example
+ * ```ts
+ * return body({payload: 'done'})
+ * ```
+ */
+interface RoutekitBody<T = unknown> {
+  readonly [routekitBodyBrand]: true;
+  /**
+   * Logical response body value.
+   */
+  value: T;
+}
+/**
+ * Test whether a value can be passed directly to the native [`Response`]{@link Response} constructor.
+ *
+ * @example
+ * ```ts
+ * isResponseBodyInit('ok')
+ * ```
+ *
+ * @param value - Value to inspect.
+ * @returns Whether `value` is a native response body.
+ */
+declare function isResponseBodyInit(value: unknown): value is RouterBodyInit | null | undefined;
+/**
+ * Test whether a value is a Routekit logical response.
+ *
+ * @example
+ * ```ts
+ * if (isRoutekitResponse(result)) result.headers.set('x-request-id', id)
+ * ```
+ *
+ * @param value - Value to inspect.
+ * @returns Whether `value` was created by a Routekit response helper.
+ */
+declare function isRoutekitResponse(value: unknown): value is RoutekitResponse;
+/**
+ * Test whether a value is a final body wrapper.
+ *
+ * @example
+ * ```ts
+ * const value = isRoutekitBody(result) ? result.value : result
+ * ```
+ *
+ * @param value - Value to inspect.
+ * @returns Whether `value` was created by [`body`]{@link body}.
+ */
+declare function isRoutekitBody(value: unknown): value is RoutekitBody;
+/**
+ * Create a logical response.
+ *
+ * If `headers` contains `Content-Type`, the body must be compatible with the native
+ * [`Response`]{@link Response} constructor because the router will skip negotiation.
+ *
+ * @example
+ * ```ts
+ * return response({ok: true}, {status: 202})
+ * ```
+ *
+ * @param responseBody - Logical or represented response body.
+ * @param init - Response status and headers.
+ * @returns Routekit logical response.
+ */
+declare function response<const T>(responseBody: T): RoutekitResponse<T, HttpStatus.OK>;
+declare function response<const T>(responseBody: T, init: Omit<RoutekitResponseInit, 'status'>): RoutekitResponse<T, HttpStatus.OK>;
+declare function response<const T, const Status extends number>(responseBody: T, init: RoutekitResponseInit<Status> & {
+  status: Status;
+}): RoutekitResponse<T, Status>;
+/**
+ * Wrap a returned value as the final response body.
+ *
+ * @example
+ * ```ts
+ * return body({payload: 'done'})
+ * ```
+ *
+ * @param value - Logical response body.
+ * @returns Final body wrapper.
+ */
+declare function body<const T>(value: T): RoutekitBody<T>;
+//#endregion
+export { isResponseBodyInit as a, response as c, body as i, RouterBodyInit as l, RoutekitResponse as n, isRoutekitBody as o, RoutekitResponseInit as r, isRoutekitResponse as s, RoutekitBody as t, RouterHeadersInit as u };

package/dist/core-DbmQauwS.mjs

@@ -0,0 +1,81 @@
+import { CommonHeaders, HttpStatus } from "@mpen/http";
+//#region src/router/response/core.ts
+const routekitResponseBrand = Symbol("RoutekitResponse");
+const routekitBodyBrand = Symbol("RoutekitBody");
+function hasContentType(headers) {
+	return headers.has(CommonHeaders.CONTENT_TYPE);
+}
+function isArrayBufferView(value) {
+	return ArrayBuffer.isView(value);
+}
+/**
+* Test whether a value can be passed directly to the native [`Response`]{@link Response} constructor.
+*
+* @example
+* ```ts
+* isResponseBodyInit('ok')
+* ```
+*
+* @param value - Value to inspect.
+* @returns Whether `value` is a native response body.
+*/
+function isResponseBodyInit(value) {
+	return value == null || typeof value === "string" || value instanceof ReadableStream || value instanceof Blob || value instanceof FormData || value instanceof URLSearchParams || value instanceof ArrayBuffer || isArrayBufferView(value);
+}
+/**
+* Test whether a value is a Routekit logical response.
+*
+* @example
+* ```ts
+* if (isRoutekitResponse(result)) result.headers.set('x-request-id', id)
+* ```
+*
+* @param value - Value to inspect.
+* @returns Whether `value` was created by a Routekit response helper.
+*/
+function isRoutekitResponse(value) {
+	return !!value && value[routekitResponseBrand] === true;
+}
+/**
+* Test whether a value is a final body wrapper.
+*
+* @example
+* ```ts
+* const value = isRoutekitBody(result) ? result.value : result
+* ```
+*
+* @param value - Value to inspect.
+* @returns Whether `value` was created by [`body`]{@link body}.
+*/
+function isRoutekitBody(value) {
+	return !!value && value[routekitBodyBrand] === true;
+}
+function response(responseBody, init = {}) {
+	const responseHeaders = new Headers(init.headers);
+	if (hasContentType(responseHeaders) && !isResponseBodyInit(responseBody)) throw new TypeError("Routekit response has Content-Type set, so body must be a native Response body.");
+	return {
+		[routekitResponseBrand]: true,
+		status: init.status ?? HttpStatus.OK,
+		headers: responseHeaders,
+		body: responseBody
+	};
+}
+/**
+* Wrap a returned value as the final response body.
+*
+* @example
+* ```ts
+* return body({payload: 'done'})
+* ```
+*
+* @param value - Logical response body.
+* @returns Final body wrapper.
+*/
+function body(value) {
+	return {
+		[routekitBodyBrand]: true,
+		value
+	};
+}
+//#endregion
+export { response as a, isRoutekitResponse as i, isResponseBodyInit as n, isRoutekitBody as r, body as t };

package/dist/handlers.d.mts

@@ -0,0 +1,72 @@
+import { m as Handler } from "./router-Cwb7ak0J.mjs";
+
+//#region src/router/handlers/openapi/openapi.d.ts
+/**
+ * OpenAPI document `info` section.
+ */
+type OpenApiInfo = {
+  title: string;
+  version: string;
+  description?: string;
+  termsOfService?: string;
+  contact?: Record<string, unknown>;
+  license?: Record<string, unknown>;
+};
+/**
+ * OpenAPI server definition.
+ */
+type OpenApiServer = {
+  url: string;
+  description?: string;
+  variables?: Record<string, unknown>;
+};
+/**
+ * OpenAPI operation object.
+ */
+type OpenApiOperation = Record<string, unknown>;
+/**
+ * OpenAPI paths dictionary keyed by pathname then method.
+ */
+type OpenApiPaths = Record<string, Record<string, OpenApiOperation>>;
+/**
+ * OpenAPI document returned by the `openapi` plugin handler.
+ */
+type OpenApiDocument = {
+  openapi: string;
+  info: OpenApiInfo;
+  servers?: OpenApiServer[];
+  paths: OpenApiPaths;
+  components?: Record<string, unknown>;
+  security?: Array<Record<string, string[]>>;
+};
+/**
+ * Options used to build an OpenAPI document from registered routes.
+ */
+type OpenApiOptions = {
+  info: OpenApiInfo;
+  servers?: OpenApiServer[];
+  components?: Record<string, unknown>;
+  security?: Array<Record<string, string[]>>;
+  openapi?: string;
+};
+/**
+ * Create an OpenAPI response handler that reflects the active router.
+ *
+ * @example
+ * ```ts
+ * router.add({
+ *   path: '/swagger.json',
+ *   method: HttpMethod.GET,
+ *   handler: openapi({
+ *     info: {title: 'Example API', version: '1.0.0'},
+ *     servers: [{url: 'https://api.example.com'}],
+ *   }),
+ * })
+ * ```
+ *
+ * @param options - OpenAPI document options for info, servers, and optional components/security.
+ * @returns A route handler that returns the generated OpenAPI JSON document.
+ */
+declare function openapi(options: OpenApiOptions): Handler<OpenApiDocument>;
+//#endregion
+export { type OpenApiDocument, type OpenApiInfo, type OpenApiOptions, type OpenApiServer, openapi };

package/dist/handlers.mjs

@@ -0,0 +1,153 @@
+import { n as ok } from "./status-C-8mw-FB.mjs";
+import { HttpMethod, StatusText } from "@mpen/http";
+//#region src/router/handlers/openapi/openapi.ts
+const DEFAULT_OPENAPI_VERSION = "3.0.3";
+const DEFAULT_METHODS = [
+	HttpMethod.GET,
+	HttpMethod.PUT,
+	HttpMethod.POST,
+	HttpMethod.DELETE,
+	HttpMethod.OPTIONS,
+	HttpMethod.HEAD,
+	HttpMethod.PATCH,
+	HttpMethod.TRACE
+];
+function routePathToOpenApi(pathname) {
+	return pathname.replace(/:([A-Za-z0-9_]+)/g, "{$1}");
+}
+function normalizeOpenApiMethods(route) {
+	const rawMethods = route.method ? Array.isArray(route.method) ? route.method : [route.method] : DEFAULT_METHODS;
+	const normalized = /* @__PURE__ */ new Set();
+	for (const method of rawMethods) {
+		if (method === HttpMethod.CONNECT) continue;
+		normalized.add(method.toLowerCase());
+	}
+	return [...normalized];
+}
+function buildParameterEntries(schema, location) {
+	const properties = schema.properties;
+	const requiredList = Array.isArray(schema.required) ? schema.required.filter((value) => typeof value === "string") : [];
+	if (properties && typeof properties === "object") return Object.entries(properties).map(([name, propSchema]) => ({
+		name,
+		in: location,
+		required: location === "path" ? true : requiredList.includes(name),
+		schema: propSchema ?? {}
+	}));
+	return [{
+		name: location,
+		in: location,
+		required: location === "path",
+		schema
+	}];
+}
+function openApiRequestContentTypes(route) {
+	if (!route.accept || route.accept.length === 0) return ["application/json"];
+	const normalized = /* @__PURE__ */ new Set();
+	for (const accept of route.accept) normalized.add(accept.type);
+	return [...normalized];
+}
+function openApiResponseContentTypes() {
+	return ["application/json"];
+}
+function defaultResponseDescription(status) {
+	const numericStatus = Number(status);
+	if (Number.isInteger(numericStatus)) return StatusText[numericStatus] ?? String(status);
+	return status;
+}
+function buildOperationFromSchema(route) {
+	const schema = route.schema;
+	const operation = {};
+	if (!schema) {
+		operation.responses = { 200: { description: "OK" } };
+		return operation;
+	}
+	const parameters = [];
+	if (schema.request?.query) parameters.push(...buildParameterEntries(schema.request.query, "query"));
+	if (schema.request?.path) parameters.push(...buildParameterEntries(schema.request.path, "path"));
+	if (parameters.length > 0) operation.parameters = parameters;
+	if (schema.request?.body !== void 0) operation.requestBody = {
+		required: true,
+		content: Object.fromEntries(openApiRequestContentTypes(route).map((contentType) => [contentType, { schema: schema.request.body }]))
+	};
+	if (schema.response?.body && Object.keys(schema.response.body).length > 0) {
+		const contentTypes = openApiResponseContentTypes();
+		operation.responses = Object.fromEntries(Object.entries(schema.response.body).flatMap(([status, responseSchema]) => {
+			if (responseSchema === void 0) return [];
+			const response = { description: defaultResponseDescription(status) };
+			response.content = Object.fromEntries(contentTypes.map((contentType) => [contentType, { schema: responseSchema }]));
+			return [[status, response]];
+		}));
+	} else operation.responses = { 200: { description: "OK" } };
+	return operation;
+}
+function mergeOpenApiOperations(generated, custom) {
+	if (!custom) return generated;
+	const merged = {
+		...generated,
+		...custom
+	};
+	const generatedParameters = Array.isArray(generated.parameters) ? generated.parameters : [];
+	const customParameters = Array.isArray(custom.parameters) ? custom.parameters : [];
+	if (generatedParameters.length > 0 || customParameters.length > 0) merged.parameters = [...customParameters, ...generatedParameters];
+	if (generated.requestBody && custom.requestBody) {
+		const generatedRequestBody = generated.requestBody;
+		const customRequestBody = custom.requestBody;
+		merged.requestBody = {
+			...generatedRequestBody,
+			...customRequestBody,
+			content: {
+				...generatedRequestBody.content ?? {},
+				...customRequestBody.content ?? {}
+			}
+		};
+	}
+	if (generated.responses && custom.responses) merged.responses = {
+		...generated.responses,
+		...custom.responses
+	};
+	return merged;
+}
+function buildOperation(route) {
+	return mergeOpenApiOperations(buildOperationFromSchema(route), route.meta?.openapi);
+}
+/**
+* Create an OpenAPI response handler that reflects the active router.
+*
+* @example
+* ```ts
+* router.add({
+*   path: '/swagger.json',
+*   method: HttpMethod.GET,
+*   handler: openapi({
+*     info: {title: 'Example API', version: '1.0.0'},
+*     servers: [{url: 'https://api.example.com'}],
+*   }),
+* })
+* ```
+*
+* @param options - OpenAPI document options for info, servers, and optional components/security.
+* @returns A route handler that returns the generated OpenAPI JSON document.
+*/
+function openapi(options) {
+	return function openapiHandler() {
+		const routes = this.getRoutes();
+		const paths = {};
+		for (const route of routes) {
+			const pathPattern = routePathToOpenApi(route.path.pathname);
+			const methods = normalizeOpenApiMethods(route);
+			if (methods.length === 0) continue;
+			const pathItem = paths[pathPattern] ?? (paths[pathPattern] = {});
+			for (const method of methods) pathItem[method] = buildOperation(route);
+		}
+		return ok({
+			openapi: options.openapi ?? DEFAULT_OPENAPI_VERSION,
+			info: options.info,
+			paths,
+			...options.servers ? { servers: options.servers } : {},
+			...options.components ? { components: options.components } : {},
+			...options.security ? { security: options.security } : {}
+		});
+	};
+}
+//#endregion
+export { openapi };

package/dist/index.d.mts

@@ -0,0 +1,3 @@
+import { $ as formDataRequestBodyParser, A as RequestMiddlewareEntry, B as RouterMountOptions, C as MiddlewareInput, Ct as isStreamDirective, D as RequestBodyParserInput, Dt as jsonLinesFramer, Et as StreamFramer, F as RouteMeta, G as RequestBodyParser, H as RequestBodyFormData, I as RouteOptions, J as RoutekitRequest, K as RequestBodyStream, L as RoutePath, M as ResponseBodySerializerInput, N as Route, O as RequestContext, Ot as sseFramer, P as RouteMatch, Q as defaultRequestBodyParsers, R as RouteSchema, S as MiddlewareEntry, St as isStatusDirective, T as NormalizedRoute, Tt as stream, U as RequestBodyLengthMismatchError, V as RequestBodyError, W as RequestBodyParseContext, X as UnsupportedRequestBodyMediaTypeError, Y as RoutekitRequestBody, Z as createRoutekitRequest, _ as JsonObjectSchema, _t as headers, a as MiddlewareResponseDeclaration, at as createStartStream, b as MediaType, bt as isHeadersDirective, c as AcceptMediaRange, ct as jsonResponseBodySerializer, d as ContentType, dt as HeadersDirective, et as jsonRequestBodyParser, f as ContextFromMiddlewareInput, ft as RoutekitYield, gt as head, h as HandlerContext, ht as chunk, i as MiddlewareControls, it as createAsyncStream, j as RequestMiddlewareInput, k as RequestMiddleware, l as AddedContextFromMiddlewareInput, lt as ChunkDirective, m as Handler, mt as StreamDirective, n as DeclaredMiddleware, nt as textRequestBodyParser, o as MiddlewareResponseDeclarations, ot as ResponseBodySerializer, p as ContextMiddleware, pt as StatusDirective, q as RequestBodyTooLargeError, r as DefineMiddlewareOptions, rt as urlEncodedRequestBodyParser, s as defineMiddleware, st as defaultResponseBodySerializers, t as Router, tt as responseFromRequestBodyError, u as AnyContext, ut as HeadDirective, v as JsonSchema, vt as isChunkDirective, w as MiddlewareList, wt as status, x as Middleware, xt as isRoutekitDirective, yt as isHeadDirective, z as RouterExtension } from "./router-Cwb7ak0J.mjs";
+import { a as isResponseBodyInit, c as response, i as body, n as RoutekitResponse, o as isRoutekitBody, r as RoutekitResponseInit, s as isRoutekitResponse, t as RoutekitBody } from "./core-CzUCxvGk.mjs";
+export { type AcceptMediaRange, type AddedContextFromMiddlewareInput, type AnyContext, ChunkDirective, type ContentType, type ContextFromMiddlewareInput, type ContextMiddleware, type DeclaredMiddleware, type DefineMiddlewareOptions, type Handler, type HandlerContext, HeadDirective, HeadersDirective, type JsonObjectSchema, type JsonSchema, type MediaType, type Middleware, type MiddlewareControls, type MiddlewareEntry, type MiddlewareInput, type MiddlewareList, type MiddlewareResponseDeclaration, type MiddlewareResponseDeclarations, type NormalizedRoute, RequestBodyError, type RequestBodyFormData, RequestBodyLengthMismatchError, type RequestBodyParseContext, type RequestBodyParser, type RequestBodyParserInput, type RequestBodyStream, RequestBodyTooLargeError, type RequestContext, type RequestMiddleware, type RequestMiddlewareEntry, type RequestMiddlewareInput, ResponseBodySerializer, type ResponseBodySerializerInput, type Route, type RouteMatch, type RouteMeta, type RouteOptions, type RoutePath, type RouteSchema, RoutekitBody, type RoutekitRequest, type RoutekitRequestBody, RoutekitResponse, RoutekitResponseInit, RoutekitYield, Router, type RouterExtension, type RouterMountOptions, StatusDirective, StreamDirective, StreamFramer, UnsupportedRequestBodyMediaTypeError, body, chunk, createAsyncStream, createRoutekitRequest, createStartStream, defaultRequestBodyParsers, defaultResponseBodySerializers, defineMiddleware, formDataRequestBodyParser, head, headers, isChunkDirective, isHeadDirective, isHeadersDirective, isResponseBodyInit, isRoutekitBody, isRoutekitDirective, isRoutekitResponse, isStatusDirective, isStreamDirective, jsonLinesFramer, jsonRequestBodyParser, jsonResponseBodySerializer, response, responseFromRequestBodyError, sseFramer, status, stream, textRequestBodyParser, urlEncodedRequestBodyParser };