@mpen/routekit 0.1.0 → 0.1.2

package/src/router/handlers/openapi/openapi.ts

@@ -1,293 +0,0 @@
-import { HttpMethod, StatusText } from '@mpen/http'
-import type { HttpStatus } from '@mpen/http'
-import type { Router } from '../../router'
-import type { Handler, JsonObjectSchema, JsonSchema, NormalizedRoute, RouteMeta } from '../../types'
-import { ok } from '../../response/formats/status'
-
-/**
- * OpenAPI document `info` section.
- */
-export type OpenApiInfo = {
-    title: string
-    version: string
-    description?: string
-    termsOfService?: string
-    contact?: Record<string, unknown>
-    license?: Record<string, unknown>
-}
-
-/**
- * OpenAPI server definition.
- */
-export type OpenApiServer = {
-    url: string
-    description?: string
-    variables?: Record<string, unknown>
-}
-
-/**
- * OpenAPI operation object.
- */
-export type OpenApiOperation = Record<string, unknown>
-
-/**
- * OpenAPI paths dictionary keyed by pathname then method.
- */
-export type OpenApiPaths = Record<string, Record<string, OpenApiOperation>>
-
-/**
- * OpenAPI document returned by the `openapi` plugin handler.
- */
-export 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.
- */
-export type OpenApiOptions = {
-    info: OpenApiInfo
-    servers?: OpenApiServer[]
-    components?: Record<string, unknown>
-    security?: Array<Record<string, string[]>>
-    openapi?: string
-}
-
-type OpenApiParameter = {
-    name: string
-    in: 'path' | 'query'
-    required?: boolean
-    schema: JsonSchema
-}
-
-type OpenApiRequestBody = {
-    required?: boolean
-    content: Record<string, { schema: JsonSchema }>
-}
-
-type OpenApiResponse = {
-    description: string
-    content?: Record<string, { schema: JsonSchema }>
-}
-
-const DEFAULT_OPENAPI_VERSION = '3.0.3'
-const DEFAULT_METHODS: HttpMethod[] = [
-    HttpMethod.GET,
-    HttpMethod.PUT,
-    HttpMethod.POST,
-    HttpMethod.DELETE,
-    HttpMethod.OPTIONS,
-    HttpMethod.HEAD,
-    HttpMethod.PATCH,
-    HttpMethod.TRACE,
-]
-
-function routePathToOpenApi(pathname: string): string {
-    return pathname.replace(/:([A-Za-z0-9_]+)/g, '{$1}')
-}
-
-function normalizeOpenApiMethods(route: NormalizedRoute<any>): string[] {
-    const rawMethods = route.method
-        ? Array.isArray(route.method)
-            ? route.method
-            : [route.method]
-        : DEFAULT_METHODS
-    const normalized = new Set<string>()
-    for (const method of rawMethods) {
-        if (method === HttpMethod.CONNECT) continue
-        normalized.add(method.toLowerCase())
-    }
-    return [...normalized]
-}
-
-function buildParameterEntries(
-    schema: JsonObjectSchema,
-    location: 'path' | 'query',
-): OpenApiParameter[] {
-    const properties = schema.properties
-    const requiredList = Array.isArray(schema.required)
-        ? schema.required.filter((value): value is string => 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 as JsonSchema) ?? {},
-        }))
-    }
-    return [
-        {
-            name: location,
-            in: location,
-            required: location === 'path',
-            schema,
-        },
-    ]
-}
-
-function openApiRequestContentTypes(route: NormalizedRoute<any>): string[] {
-    if (!route.accept || route.accept.length === 0) return ['application/json']
-    const normalized = new Set<string>()
-    for (const accept of route.accept) {
-        normalized.add(accept.type)
-    }
-    return [...normalized]
-}
-
-function openApiResponseContentTypes(): string[] {
-    return ['application/json']
-}
-
-function defaultResponseDescription(status: string): string {
-    const numericStatus = Number(status)
-    if (Number.isInteger(numericStatus)) {
-        return StatusText[numericStatus as HttpStatus] ?? String(status)
-    }
-    return status
-}
-
-function buildOperationFromSchema(route: NormalizedRoute<any>): OpenApiOperation {
-    const schema = route.schema
-    const operation: OpenApiOperation = {}
-    if (!schema) {
-        operation.responses = { 200: { description: 'OK' } }
-        return operation
-    }
-
-    const parameters: OpenApiParameter[] = []
-    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 !== undefined) {
-        const content = Object.fromEntries(
-            openApiRequestContentTypes(route).map((contentType) => [
-                contentType,
-                { schema: schema.request!.body! },
-            ]),
-        )
-        operation.requestBody = {
-            required: true,
-            content,
-        } satisfies OpenApiRequestBody
-    }
-
-    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 === undefined) return []
-                const response: OpenApiResponse = {
-                    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: OpenApiOperation,
-    custom?: RouteMeta['openapi'],
-): OpenApiOperation {
-    if (!custom) return generated
-
-    const merged: OpenApiOperation = { ...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 as OpenApiRequestBody
-        const customRequestBody = custom.requestBody as OpenApiRequestBody
-        merged.requestBody = {
-            ...generatedRequestBody,
-            ...customRequestBody,
-            content: {
-                ...(generatedRequestBody.content ?? {}),
-                ...(customRequestBody.content ?? {}),
-            },
-        }
-    }
-
-    if (generated.responses && custom.responses) {
-        merged.responses = {
-            ...(generated.responses as Record<string, unknown>),
-            ...(custom.responses as Record<string, unknown>),
-        }
-    }
-
-    return merged
-}
-
-function buildOperation(route: NormalizedRoute<any>): OpenApiOperation {
-    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.
- */
-export function openapi(options: OpenApiOptions): Handler<OpenApiDocument> {
-    return function openapiHandler(this: Router<any>) {
-        const routes = this.getRoutes()
-        const paths: OpenApiPaths = {}
-
-        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)
-            }
-        }
-
-        const document: OpenApiDocument = {
-            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 } : {}),
-        }
-
-        return ok(document)
-    }
-}

package/src/router/integration/zod-openapi.test.ts

@@ -1,74 +0,0 @@
-#!/usr/bin/env -S bun test
-import { describe, expect, it } from 'bun:test'
-import { HttpMethod } from '@mpen/http'
-import { Router } from '../router'
-import { openapi } from '../handlers/openapi'
-import type { OpenApiDocument } from '../handlers/openapi'
-import { createZodRouteBuilder } from '../routes/zod'
-import { z } from 'zod'
-
-type JsonSchemaObject = {
-    type?: string
-    properties: Record<string, JsonSchemaObject>
-}
-
-type OperationWithSchemas = {
-    requestBody: {
-        content: Record<string, { schema: JsonSchemaObject }>
-    }
-    responses: Record<string, { content: Record<string, { schema: JsonSchemaObject }> }>
-    parameters: unknown[]
-}
-
-describe('openapi', () => {
-    it('consumes route schemas generated by createZodRouteBuilder', async () => {
-        const route = createZodRouteBuilder()
-        const router = new Router()
-        router.add(
-            route({
-                path: '/users/:id',
-                method: HttpMethod.POST,
-                schema: {
-                    request: {
-                        path: z.object({ id: z.string() }),
-                        query: z.object({ include: z.string() }),
-                        body: z.object({ name: z.string() }),
-                    },
-                    response: {
-                        body: {
-                            200: z.object({ ok: z.boolean() }),
-                        },
-                    },
-                },
-                validateResponse: false,
-                handler: () => new Response('ok'),
-            }),
-        )
-
-        router.add({
-            path: '/swagger.json',
-            method: HttpMethod.GET,
-            handler: openapi({
-                info: { title: 'Example API', version: '1.0.0' },
-            }),
-        })
-
-        const response = await router.fetch(new Request('https://example.com/swagger.json'))
-        const document = (await response.json()) as OpenApiDocument
-        const operation = document.paths['/users/{id}'].post as OperationWithSchemas
-
-        expect(operation.requestBody.content['application/json'].schema.type).toBe('object')
-        expect(operation.requestBody.content['application/json'].schema.properties.name.type).toBe(
-            'string',
-        )
-        expect(
-            operation.responses['200'].content['application/json'].schema.properties.ok.type,
-        ).toBe('boolean')
-        expect(operation.parameters).toEqual(
-            expect.arrayContaining([
-                expect.objectContaining({ name: 'id', in: 'path' }),
-                expect.objectContaining({ name: 'include', in: 'query' }),
-            ]),
-        )
-    })
-})

package/src/router/lib/charset.test.ts

@@ -1,22 +0,0 @@
-#!/usr/bin/env -S bun test
-import { describe, expect, it } from 'bun:test'
-import { normalizeCharsetName } from './charset'
-
-describe(normalizeCharsetName.name, () => {
-    it('returns preferred MIME names for common aliases', () => {
-        expect(normalizeCharsetName('UTF8')).toBe('utf-8')
-        expect(normalizeCharsetName('latin1')).toBe('iso-8859-1')
-        expect(normalizeCharsetName('ANSI_X3.4-1968')).toBe('us-ascii')
-    })
-
-    it('ignores punctuation and whitespace differences', () => {
-        expect(normalizeCharsetName(' utf_16 ')).toBe('utf-16')
-        expect(normalizeCharsetName('utf 8')).toBe('utf-8')
-        expect(normalizeCharsetName('Shift-JIS')).toBe('shift_jis')
-    })
-
-    it('returns an empty string for missing input', () => {
-        expect(normalizeCharsetName('')).toBe('')
-        expect(normalizeCharsetName('   ')).toBe('')
-    })
-})

package/src/router/lib/charset.ts

@@ -1,133 +0,0 @@
-/**
- * Normalize a charset label to a lowercase "Preferred MIME Name" where possible.
- *
- * - Charset comparison is case-insensitive (IANA).
- * - Uses Preferred MIME Names when mapped.
- * - Unknown charsets return a cleaned lowercase form.
- */
-export function normalizeCharsetName(input: string): string {
-    if (!input?.length) return ''
-
-    const raw = input.trim()
-    if (raw.length === 0) return ''
-
-    const keyA = normalizeKey(raw)
-    const hitA = ALIAS_TO_PREFERRED_LOWER.get(keyA)
-    if (hitA) return hitA
-
-    // Secondary fuzzy match: ignore punctuation differences (utf8 vs utf-8)
-    const keyB = stripKey(keyA)
-    const hitB = STRIPPED_ALIAS_TO_PREFERRED_LOWER.get(keyB)
-    if (hitB) return hitB
-
-    // Fallback: normalized lowercase token
-    return keyA
-}
-
-function normalizeKey(s: string): string {
-    // IANA says comparison is case-insensitive; we normalize to lowercase. :contentReference[oaicite:4]{index=4}
-    return s
-        .trim()
-        .toLowerCase()
-        .replace(/\s+/g, '') // drop internal spaces
-        .replace(/_/g, '-') // common alias form
-}
-
-function stripKey(s: string): string {
-    // Keep only alnum for fuzzy matching across punctuation variants.
-    return s.replace(/[^a-z0-9]+/g, '')
-}
-
-/**
- * Minimal, practical alias set.
- * Extend this map as needed (ideally generated from IANA CSV for full coverage). :contentReference[oaicite:5]{index=5}
- */
-const ALIAS_TO_PREFERRED_LOWER = new Map<string, string>([
-    // Unicode
-    ['utf-8', 'utf-8'],
-    ['utf8', 'utf-8'],
-    ['unicode-1-1-utf-8', 'utf-8'],
-
-    ['utf-16', 'utf-16'],
-    ['utf16', 'utf-16'],
-    ['utf-16le', 'utf-16le'],
-    ['utf-16be', 'utf-16be'],
-
-    // ASCII
-    ['us-ascii', 'us-ascii'],
-    ['ascii', 'us-ascii'],
-    ['ansi_x3.4-1968', 'us-ascii'],
-    ['ansi_x3.4-1986', 'us-ascii'],
-    ['iso646-us', 'us-ascii'],
-    ['cp367', 'us-ascii'],
-    ['ibm367', 'us-ascii'],
-
-    // ISO-8859 (Latin / Cyrillic / etc.)
-    ['iso-8859-1', 'iso-8859-1'],
-    ['iso_8859-1:1987', 'iso-8859-1'],
-    ['iso_8859-1', 'iso-8859-1'],
-    ['latin1', 'iso-8859-1'],
-    ['l1', 'iso-8859-1'],
-    ['cp819', 'iso-8859-1'],
-    ['ibm819', 'iso-8859-1'],
-
-    ['iso-8859-2', 'iso-8859-2'],
-    ['latin2', 'iso-8859-2'],
-    ['l2', 'iso-8859-2'],
-
-    ['iso-8859-3', 'iso-8859-3'],
-    ['latin3', 'iso-8859-3'],
-    ['l3', 'iso-8859-3'],
-
-    ['iso-8859-4', 'iso-8859-4'],
-    ['latin4', 'iso-8859-4'],
-    ['l4', 'iso-8859-4'],
-
-    ['iso-8859-5', 'iso-8859-5'],
-    ['cyrillic', 'iso-8859-5'],
-
-    ['iso-8859-6', 'iso-8859-6'],
-    ['arabic', 'iso-8859-6'],
-
-    ['iso-8859-7', 'iso-8859-7'],
-    ['greek', 'iso-8859-7'],
-    ['greek8', 'iso-8859-7'],
-
-    ['iso-8859-8', 'iso-8859-8'],
-    ['hebrew', 'iso-8859-8'],
-
-    ['iso-8859-9', 'iso-8859-9'],
-    ['latin5', 'iso-8859-9'],
-    ['l5', 'iso-8859-9'],
-
-    // Common “windows” encodings
-    ['windows-1252', 'windows-1252'],
-    ['cp1252', 'windows-1252'],
-
-    ['windows-1251', 'windows-1251'],
-    ['cp1251', 'windows-1251'],
-
-    // East Asian (common on the web)
-    ['shift_jis', 'shift_jis'],
-    ['shift-jis', 'shift_jis'],
-    ['sjis', 'shift_jis'],
-    ['ms_kanji', 'shift_jis'],
-
-    ['euc-jp', 'euc-jp'],
-    ['eucjp', 'euc-jp'],
-
-    ['euc-kr', 'euc-kr'],
-    ['euckr', 'euc-kr'],
-
-    ['iso-2022-jp', 'iso-2022-jp'],
-    ['iso-2022-kr', 'iso-2022-kr'],
-
-    ['big5', 'big5'],
-
-    ['gbk', 'gbk'],
-    ['gb18030', 'gb18030'],
-])
-
-const STRIPPED_ALIAS_TO_PREFERRED_LOWER = new Map<string, string>(
-    Array.from(ALIAS_TO_PREFERRED_LOWER.entries(), ([k, v]) => [stripKey(k), v]),
-)

package/src/router/lib/collections.ts

@@ -1,3 +0,0 @@
-import type { OneOrMany } from '../types'
-
-export const toArray = <T>(v: OneOrMany<T>): T[] => (Array.isArray(v) ? v : [v])

package/src/router/lib/format.test.ts

@@ -1,67 +0,0 @@
-#!/usr/bin/env -S bun test
-import { describe, expect, it } from 'bun:test'
-import { fullWide } from './format'
-
-describe(fullWide.name, () => {
-    it('formats finite numbers without grouping or exponential notation', () => {
-        expect(fullWide(1234567)).toBe('1234567')
-        expect(fullWide(1e21)).toBe('1000000000000000000000')
-        expect(fullWide(1234.5)).toBe('1234.5')
-        expect(fullWide(0.0000001)).toBe('0.0000001')
-    })
-
-    it('formats bigint values as base-10 strings', () => {
-        expect(fullWide(123_456_789_012_345_678_901_234_567_890n)).toBe(
-            '123456789012345678901234567890',
-        )
-    })
-
-    it('trims leading zeroes', () => {
-        expect(fullWide('000123')).toBe('123')
-        expect(fullWide('+000123')).toBe('123')
-        expect(fullWide('-000123')).toBe('-123')
-    })
-
-    it('trims trailing zeros zeroes', () => {
-        expect(fullWide('1230')).toBe('1230')
-        expect(fullWide('1230.')).toBe('1230')
-        expect(fullWide('1230.0')).toBe('1230')
-        expect(fullWide('1230.01')).toBe('1230.01')
-        expect(fullWide('1230.010')).toBe('1230.01')
-        expect(fullWide('1230.010200')).toBe('1230.0102')
-
-        expect(fullWide('+1230')).toBe('1230')
-        expect(fullWide('+1230.')).toBe('1230')
-        expect(fullWide('+1230.0')).toBe('1230')
-        expect(fullWide('+1230.01')).toBe('1230.01')
-        expect(fullWide('+1230.010')).toBe('1230.01')
-
-        expect(fullWide('-1230')).toBe('-1230')
-        expect(fullWide('-1230.')).toBe('-1230')
-        expect(fullWide('-1230.0')).toBe('-1230')
-        expect(fullWide('-1230.01')).toBe('-1230.01')
-        expect(fullWide('-1230.010')).toBe('-1230.01')
-    })
-
-    it('formats decimal strings without losing precision', () => {
-        expect(fullWide('0.000000000000000001')).toBe('0.000000000000000001')
-        expect(fullWide('123456789012345678901234567890.125')).toBe(
-            '123456789012345678901234567890.125',
-        )
-    })
-
-    it('returns safe integer bounds for infinite numeric values', () => {
-        expect(fullWide(Number.POSITIVE_INFINITY)).toBe(String(Number.MAX_SAFE_INTEGER))
-        expect(fullWide(Number.NEGATIVE_INFINITY)).toBe(String(Number.MIN_SAFE_INTEGER))
-    })
-
-    it('returns zero for NaN numeric values', () => {
-        expect(fullWide(Number.NaN)).toBe('0')
-    })
-
-    it('returns safe integer bounds for infinite string values', () => {
-        expect(fullWide('Infinity')).toBe(String(Number.MAX_SAFE_INTEGER))
-        expect(fullWide('+Infinity')).toBe(String(Number.MAX_SAFE_INTEGER))
-        expect(fullWide('-Infinity')).toBe(String(Number.MIN_SAFE_INTEGER))
-    })
-})

package/src/router/lib/format.ts

@@ -1,35 +0,0 @@
-export type FormattableNumber = Parameters<Intl.NumberFormat['format']>[0]
-
-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.
- */
-export function fullWide(n: FormattableNumber): string {
-    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)
-}

package/src/router/lib/host.ts

@@ -1,4 +0,0 @@
-export function isLocalhost(hostname: string): boolean {
-    const lower = hostname.toLowerCase()
-    return lower === 'localhost' || lower === '127.0.0.1' || lower === '::1' || lower === '0.0.0.0'
-}

package/src/router/lib/json-schema.ts

@@ -1,6 +0,0 @@
-export const enum JsonSchemaTarget {
-    DRAFT_04 = 'draft-04',
-    DRAFT_07 = 'draft-07',
-    DRAFT_2020_12 = 'draft-2020-12',
-    OPENAPI_3_0 = 'openapi-3.0',
-}