@mpen/routekit 0.1.0 → 0.1.1

package/src/router/lib/media-type.test.ts

@@ -1,122 +0,0 @@
-#!/usr/bin/env -S bun test
-import { describe, expect, it } from 'bun:test'
-import {
-    isJsonContentType,
-    mediaRangeAccepts,
-    mediaRangeQuality,
-    mediaRangeToContentType,
-    mediaTypeMatches,
-    parseAcceptHeader,
-    parseContentType,
-    parseMediaType,
-} from './media-type'
-
-describe(parseMediaType.name, function () {
-    it('parses types with parameters', function () {
-        const media = parseMediaType('multipart/form-data; boundary=abc; charset=UTF-8')
-        expect(media).toEqual({
-            type: 'multipart/form-data',
-            boundary: 'abc',
-            charset: 'utf-8',
-        })
-    })
-
-    it('parses quoted parameters', function () {
-        const media = parseMediaType('multipart/form-data; boundary="xyz-123"')
-        expect(media).toEqual({
-            type: 'multipart/form-data',
-            boundary: 'xyz-123',
-        })
-    })
-
-    it('parses with no parameters', function () {
-        const media = parseMediaType('application/json')
-        expect(media).toEqual({
-            type: 'application/json',
-        })
-    })
-
-    it('preserves q as a content-type parameter instead of accept metadata', function () {
-        const media = parseMediaType('application/json; q=0.7')
-        expect(media).toEqual({
-            type: 'application/json',
-            parameters: { q: '0.7' },
-        })
-    })
-
-    it('rejects invalid content-type values', function () {
-        expect(parseContentType('application/json, text/plain')).toBeNull()
-        expect(parseContentType('application')).toBeNull()
-        expect(parseContentType('*/*')).toBeNull()
-    })
-})
-
-describe(mediaTypeMatches.name, function () {
-    it('matches types and charsets when compatible', function () {
-        const accept = parseMediaType('application/json; charset=utf-8')!
-        const contentType = parseMediaType('application/json; charset=UTF8')!
-        expect(mediaTypeMatches(accept, contentType)).toBe(true)
-    })
-
-    it('matches when charset is missing on either side', function () {
-        const accept = parseMediaType('application/json; charset=utf-8')!
-        const contentType = parseMediaType('application/json')!
-        expect(mediaTypeMatches(accept, contentType)).toBe(true)
-        expect(mediaTypeMatches(contentType, accept)).toBe(true)
-    })
-
-    it('rejects mismatched media types', function () {
-        const accept = parseMediaType('application/json')!
-        const contentType = parseMediaType('text/plain')!
-        expect(mediaTypeMatches(accept, contentType)).toBe(false)
-    })
-})
-
-describe(parseAcceptHeader.name, function () {
-    it('sorts by descending q and preserves order for ties', function () {
-        const accept = parseAcceptHeader(
-            'text/plain;q=0.5, application/json, text/html;q=0.9, image/png;q=0.9',
-        )
-        expect(accept).toEqual([
-            { type: 'application/json', q: 1 },
-            { type: 'text/html', q: 0.9 },
-            { type: 'image/png', q: 0.9 },
-            { type: 'text/plain', q: 0.5 },
-        ])
-    })
-})
-
-describe(mediaRangeQuality.name, function () {
-    it('reads q preference from media ranges', function () {
-        expect(mediaRangeQuality('application/*+json;q=0.5')).toBe(0.5)
-        expect(mediaRangeQuality('application/json')).toBe(1)
-    })
-})
-
-describe(mediaRangeToContentType.name, function () {
-    it('strips q preference from formatted content types', function () {
-        expect(mediaRangeToContentType('application/json; charset=utf-8; q=0.5')).toBe(
-            'application/json; charset=utf-8',
-        )
-    })
-})
-
-describe(isJsonContentType.name, function () {
-    it('accepts exact and structured JSON content types', function () {
-        expect(isJsonContentType('application/json; charset=utf-8')).toBe(true)
-        expect(isJsonContentType('application/problem+json')).toBe(true)
-    })
-
-    it('rejects substring and non-json content types', function () {
-        expect(isJsonContentType('fooapplication/jsonbar')).toBe(false)
-        expect(isJsonContentType('text/plain')).toBe(false)
-    })
-})
-
-describe(mediaRangeAccepts.name, function () {
-    it('matches wildcard media ranges', function () {
-        expect(mediaRangeAccepts('*/*', 'application/json')).toBe(true)
-        expect(mediaRangeAccepts('application/*', 'application/json')).toBe(true)
-        expect(mediaRangeAccepts('application/*+json', 'application/problem+json')).toBe(true)
-    })
-})

package/src/router/lib/media-type.ts

@@ -1,289 +0,0 @@
-import type { AcceptMediaRange, ContentType, MediaType } from '../types'
-import { normalizeCharsetName } from './charset'
-
-const tokenPattern = /^[!#$%&'*+.^_`|~0-9a-z-]+$/i
-const rangeTokenPattern = /^(?:\*|[!#$%&'*+.^_`|~0-9a-z-]+)$/i
-
-function normalizeToken(value: string): string {
-    return value.trim()
-}
-
-function normalizeType(value: string): string {
-    return normalizeToken(value).toLowerCase()
-}
-
-function isValidType(value: string, allowRange: boolean): boolean {
-    const [type, subtype, extra] = value.split('/')
-    if (!type || !subtype || extra !== undefined) return false
-    if (!allowRange && (type.includes('*') || subtype.includes('*'))) return false
-    const pattern = allowRange ? rangeTokenPattern : tokenPattern
-    if (!pattern.test(type) || !pattern.test(subtype)) return false
-    if (type === '*' && subtype !== '*') return false
-    return true
-}
-
-function splitParameters(value: string): string[] {
-    const parts: string[] = []
-    let current = ''
-    let inQuote = false
-    let escaped = false
-
-    for (const char of value) {
-        if (escaped) {
-            current += char
-            escaped = false
-            continue
-        }
-        if (char === '\\' && inQuote) {
-            escaped = true
-            current += char
-            continue
-        }
-        if (char === '"') {
-            inQuote = !inQuote
-            current += char
-            continue
-        }
-        if (char === ';' && !inQuote) {
-            parts.push(current)
-            current = ''
-            continue
-        }
-        current += char
-    }
-    parts.push(current)
-    return parts
-}
-
-function unquote(value: string): string {
-    const trimmed = value.trim()
-    if (!trimmed.startsWith('"') || !trimmed.endsWith('"')) return trimmed
-    return trimmed.slice(1, -1).replace(/\\(["\\])/g, '$1')
-}
-
-function parseParameterizedMediaType(
-    value: string,
-    options: { allowRange: boolean },
-): ContentType | null {
-    const [rawType = '', ...rawParams] = splitParameters(value)
-    const type = normalizeType(rawType)
-    if (!type || !isValidType(type, options.allowRange)) return null
-
-    const parameters: Record<string, string> = {}
-    const result: ContentType = { type }
-    for (const param of rawParams) {
-        const separatorIndex = param.indexOf('=')
-        if (separatorIndex <= 0) continue
-        const key = param.slice(0, separatorIndex).trim().toLowerCase()
-        if (!key || !tokenPattern.test(key)) continue
-        const paramValue = unquote(param.slice(separatorIndex + 1))
-        parameters[key] = paramValue
-        if (key === 'charset') result.charset = normalizeCharsetName(paramValue)
-        if (key === 'boundary') result.boundary = paramValue
-    }
-
-    const extraParameters = Object.fromEntries(
-        Object.entries(parameters).filter(([key]) => key !== 'charset' && key !== 'boundary'),
-    )
-    if (Object.keys(extraParameters).length > 0) {
-        result.parameters = extraParameters
-    }
-
-    return result
-}
-
-function parseMediaRange(value: string): ContentType | null {
-    return parseParameterizedMediaType(value, { allowRange: true })
-}
-
-function normalizeQuality(value: string | number | undefined): number {
-    if (value === undefined) return 1
-    const q = typeof value === 'number' ? value : Number.parseFloat(value)
-    return Number.isFinite(q) && q >= 0 && q <= 1 ? q : 1
-}
-
-function formatContentType(value: ContentType): string {
-    const params: string[] = []
-    if (value.charset) params.push(`charset=${value.charset}`)
-    if (value.boundary) params.push(`boundary=${value.boundary}`)
-    for (const [key, paramValue] of Object.entries(value.parameters ?? {})) {
-        if (key === 'q') continue
-        params.push(`${key}=${paramValue}`)
-    }
-    return [value.type, ...params].join('; ')
-}
-
-/**
- * Normalize a concrete media type.
- *
- * @param value - Media type to normalize.
- * @returns Normalized media type.
- */
-export function normalizeMediaType(value: MediaType): MediaType {
-    const type = normalizeType(value.type)
-    const charset = value.charset ? normalizeCharsetName(value.charset) : undefined
-    const boundary = value.boundary ? normalizeToken(value.boundary) : undefined
-    const parameters = value.parameters
-        ? Object.fromEntries(
-              Object.entries(value.parameters).map(([key, paramValue]) => [
-                  key.trim().toLowerCase(),
-                  paramValue.trim(),
-              ]),
-          )
-        : undefined
-    const result: MediaType = { type }
-    if (charset) result.charset = charset
-    if (boundary) result.boundary = boundary
-    if (parameters && Object.keys(parameters).length > 0) result.parameters = parameters
-    return result
-}
-
-/**
- * Parse a single HTTP `Content-Type` header value.
- *
- * @param value - Header value to parse.
- * @returns Parsed content type, or `null` when the value is invalid or missing.
- */
-export function parseContentType(value: string | null | undefined): ContentType | null {
-    if (!value) return null
-    return parseParameterizedMediaType(value, { allowRange: false })
-}
-
-/**
- * Parse a concrete media type value.
- *
- * @param value - Media type value to parse.
- * @returns Parsed media type, or `null` when the value is invalid.
- */
-export function parseMediaType(value: string): MediaType | null {
-    return parseContentType(value)
-}
-
-/**
- * Return the preference weight from an Accept-style media range.
- *
- * @param value - Media range value to inspect.
- * @returns The parsed `q` value, or `1` when none is provided.
- */
-export function mediaRangeQuality(value: string | AcceptMediaRange | MediaType): number {
-    if (typeof value !== 'string') {
-        return normalizeQuality('q' in value ? value.q : value.parameters?.q)
-    }
-    return normalizeQuality(parseMediaRange(value)?.parameters?.q)
-}
-
-/**
- * Format an Accept-style media range as a concrete `Content-Type`.
- *
- * @param value - Media range value to format.
- * @returns The media type without any `q` preference parameter, or `null` when invalid.
- */
-export function mediaRangeToContentType(value: string | MediaType): string | null {
-    const parsed = typeof value === 'string' ? parseMediaRange(value) : normalizeMediaType(value)
-    if (!parsed) return null
-    return formatContentType(parsed)
-}
-
-/**
- * Parse an Accept header into quality-sorted media ranges.
- *
- * @param value - Accept header value to parse.
- * @returns Media ranges sorted by descending `q` values, preserving original order for ties.
- */
-export function parseAcceptHeader(value: string | null | undefined): AcceptMediaRange[] {
-    const entries: Array<{ media: AcceptMediaRange; index: number }> = []
-    for (const [index, entry] of (value ?? '').split(',').entries()) {
-        const parsed = parseMediaRange(entry.trim())
-        if (!parsed) continue
-        const qParameter = parsed.parameters?.q
-        const parsedQ = qParameter === undefined ? 1 : Number.parseFloat(qParameter)
-        const q = Number.isFinite(parsedQ) && parsedQ >= 0 && parsedQ <= 1 ? parsedQ : 1
-        const parameters = { ...(parsed.parameters ?? {}) }
-        delete parameters.q
-        const media: AcceptMediaRange = { ...parsed, q }
-        delete media.parameters
-        if (Object.keys(parameters).length > 0) media.parameters = parameters
-        entries.push({
-            media,
-            index,
-        })
-    }
-
-    entries.sort((a, b) => {
-        if (b.media.q !== a.media.q) return b.media.q - a.media.q
-        return a.index - b.index
-    })
-
-    return entries.map((entry) => {
-        const { parameters, ...media } = entry.media
-        return parameters && Object.keys(parameters).length > 0 ? { ...media, parameters } : media
-    })
-}
-
-/**
- * Test whether a media type is a JSON document type.
- *
- * @param value - Content type or header value to inspect.
- * @returns Whether the media type is `application/json` or an `application/*+json` type.
- */
-export function isJsonContentType(
-    value: string | ContentType | null | undefined,
-): value is ContentType {
-    const contentType = typeof value === 'string' ? parseContentType(value) : value
-    if (!contentType) return false
-    const [type, subtype] = contentType.type.split('/', 2)
-    return type === 'application' && (subtype === 'json' || subtype.endsWith('+json'))
-}
-
-/**
- * Test whether an accepted concrete media type matches an incoming content type.
- *
- * @param accept - Media type accepted by a route.
- * @param contentType - Incoming request content type.
- * @returns Whether the accepted media type matches the content type.
- */
-export function mediaTypeMatches(accept: MediaType, contentType: ContentType): boolean {
-    const normalizedAccept = normalizeMediaType(accept)
-    const normalizedContent = normalizeMediaType(contentType)
-    if (normalizedAccept.type !== normalizedContent.type) return false
-    if (normalizedAccept.charset && normalizedContent.charset) {
-        if (
-            normalizeCharsetName(normalizedAccept.charset) !==
-            normalizeCharsetName(normalizedContent.charset)
-        )
-            return false
-    }
-    if (normalizedAccept.boundary && normalizedContent.boundary) {
-        if (normalizedAccept.boundary !== normalizedContent.boundary) return false
-    }
-    return true
-}
-
-/**
- * Test whether an HTTP media range accepts a concrete media type.
- *
- * @param range - Accept-style media range.
- * @param mediaType - Concrete media type to test.
- * @returns Whether the range accepts the media type.
- */
-export function mediaRangeAccepts(
-    range: string | AcceptMediaRange | MediaType,
-    mediaType: string | MediaType,
-): boolean {
-    const parsedRange =
-        typeof range === 'string' ? parseMediaRange(range) : normalizeMediaType(range)
-    const produced = typeof mediaType === 'string' ? parseContentType(mediaType) : mediaType
-    if (!parsedRange || !produced) return false
-    const normalizedRange = parsedRange.type.toLowerCase()
-    const normalizedProduced = produced.type.toLowerCase()
-    if (normalizedRange === '*/*') return true
-    if (normalizedRange === normalizedProduced) return true
-    const [rangeType, rangeSubtype] = normalizedRange.split('/', 2)
-    const [producedType, producedSubtype] = normalizedProduced.split('/', 2)
-    if (!rangeType || !rangeSubtype || !producedType || !producedSubtype) return false
-    if (rangeSubtype === '*' && rangeType === producedType) return true
-    if (rangeSubtype.startsWith('*+')) {
-        return rangeType === producedType && producedSubtype.endsWith(rangeSubtype.slice(1))
-    }
-    return false
-}

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

@@ -1,18 +0,0 @@
-#!/usr/bin/env -S bun test
-import { describe, expect, it } from 'bun:test'
-import { joinPrefixPathname, stripPrefixPathname } from './pathname'
-
-describe('pathname helpers', function () {
-    it('joins prefixes and pathnames', function () {
-        expect(joinPrefixPathname('', '/items')).toBe('/items')
-        expect(joinPrefixPathname('api', 'items')).toBe('/api/items')
-        expect(joinPrefixPathname('/api/', '/items')).toBe('/api/items')
-        expect(joinPrefixPathname('/api', '/')).toBe('/api')
-    })
-
-    it('strips prefixes from pathnames', function () {
-        expect(stripPrefixPathname('/api', '/api/items')).toBe('/items')
-        expect(stripPrefixPathname('/api', '/api')).toBe('/')
-        expect(stripPrefixPathname('/api', '/other')).toBe(null)
-    })
-})

package/src/router/lib/pathname.ts

@@ -1,19 +0,0 @@
-export function joinPrefixPathname(prefix: string, pathname: string): string {
-    if (!prefix) return pathname
-    if (!prefix.startsWith('/')) prefix = '/' + prefix
-    if (prefix.endsWith('/')) prefix = prefix.slice(0, -1)
-    if (pathname === '/') return prefix || '/'
-    if (!pathname.startsWith('/')) pathname = '/' + pathname
-    return prefix + pathname || '/'
-}
-
-export function stripPrefixPathname(prefix: string, pathname: string): string | null {
-    if (!prefix) return pathname
-    if (!prefix.startsWith('/')) prefix = '/' + prefix
-    if (prefix.endsWith('/')) prefix = prefix.slice(0, -1)
-    if (prefix === '/') return pathname
-
-    if (pathname === prefix) return '/'
-    if (pathname.startsWith(prefix + '/')) return pathname.slice(prefix.length)
-    return null
-}

package/src/router/lib/route-names.ts

@@ -1,70 +0,0 @@
-function sanitizeNamePart(part: string): string {
-    const replaced = part.replace(/:([a-zA-Z_$][a-zA-Z0-9_$]*)/g, '$$$1')
-    const cleaned = replaced.replace(/[^a-zA-Z0-9_$]/g, '')
-    if (cleaned.length === 0) return 'index'
-    if (!/^[a-zA-Z_$]/.test(cleaned)) return '_' + cleaned
-    return cleaned
-}
-
-export function sanitizeNameParts(parts: string[]): string[] {
-    return parts.map(sanitizeNamePart).filter(Boolean)
-}
-
-export function splitNameString(name: string): string[] {
-    const parts: string[] = []
-    let current = ''
-    let escaping = false
-
-    for (const char of name) {
-        if (escaping) {
-            current += char
-            escaping = false
-            continue
-        }
-        if (char === '\\') {
-            escaping = true
-            continue
-        }
-        if (char === '.') {
-            parts.push(current)
-            current = ''
-            continue
-        }
-        current += char
-    }
-    parts.push(current)
-
-    return parts.filter((p) => p.length > 0)
-}
-
-function upperFirst(str: string): string {
-    return str.slice(0, 1).toUpperCase() + str.slice(1)
-}
-
-function lowerFirst(str: string): string {
-    return str.slice(0, 1).toLowerCase() + str.slice(1)
-}
-
-function segmentToDefaultName(segment: string): string {
-    const paramMatch = segment.match(/^:([a-zA-Z0-9_]+)(?:\\(.+\\))?$/)
-    if (paramMatch) {
-        const key = paramMatch[1]
-        if (key) return 'By' + upperFirst(key)
-    }
-
-    const cleaned = segment.split(/[^a-zA-Z0-9]+/).filter(Boolean)
-    if (cleaned.length === 0) return 'Index'
-    return cleaned.map(upperFirst).join('')
-}
-
-export function pattToName(_method: string, patt: URLPattern): string[] {
-    const pathname = patt.pathname
-    const parts = pathname.split('/').filter((p) => p.length > 0)
-
-    if (parts.length === 0) {
-        return []
-    }
-
-    const combined = parts.map(segmentToDefaultName).join('')
-    return sanitizeNameParts([lowerFirst(combined)])
-}

package/src/router/lib/route-normalize.test.ts

@@ -1,36 +0,0 @@
-#!/usr/bin/env -S bun test
-import { describe, expect, it } from 'bun:test'
-import { HttpMethod } from '@mpen/http'
-import { normalizeRoute } from './route-normalize'
-
-describe('normalizeRoute', function () {
-    it('builds a URLPattern and default name', function () {
-        const route = normalizeRoute({
-            method: HttpMethod.GET,
-            path: '/users/:id',
-            handler: function () {
-                return new Response('ok')
-            },
-        })
-
-        expect(route.path).toBeInstanceOf(URLPattern)
-        expect(route.name).toEqual(['usersById'])
-        expect(route.method).toBe(HttpMethod.GET)
-    })
-
-    it('normalizes accept entries into media types', function () {
-        const route = normalizeRoute({
-            method: HttpMethod.POST,
-            path: '/upload',
-            accept: ['Application/JSON; charset=UTF-8', { type: 'text/plain' }],
-            handler: function () {
-                return new Response('ok')
-            },
-        })
-
-        expect(route.accept).toEqual([
-            { type: 'application/json', charset: 'utf-8' },
-            { type: 'text/plain' },
-        ])
-    })
-})

package/src/router/lib/route-normalize.ts

@@ -1,67 +0,0 @@
-import type {
-    AddedContextFromMiddlewareInput,
-    AnyContext,
-    MediaType,
-    MiddlewareInput,
-    NormalizedRoute,
-    Route,
-} from '../types'
-import type { HttpMethod } from '@mpen/http'
-import { normalizeMediaType, parseMediaType } from './media-type'
-import { pattToName, sanitizeNameParts, splitNameString } from './route-names'
-
-function normalizeRouteName(
-    name: Route['name'],
-    method: HttpMethod | HttpMethod[] | undefined,
-    path: URLPattern,
-): string[] {
-    const methodName = Array.isArray(method) ? method[0] : method
-    if (!name) {
-        return pattToName(methodName ?? 'ANY', path)
-    }
-    if (typeof name === 'string') {
-        return sanitizeNameParts(splitNameString(name))
-    }
-    return sanitizeNameParts(name)
-}
-
-export function normalizeRoute<
-    Ctx extends object = AnyContext,
-    RouteMiddleware extends MiddlewareInput<Ctx> = undefined,
-    HandlerCtx extends object = Ctx & AddedContextFromMiddlewareInput<RouteMiddleware>,
->(route: Route<Ctx, RouteMiddleware, HandlerCtx>): NormalizedRoute<HandlerCtx> {
-    if (!route.path) {
-        throw new Error('Route is missing a path')
-    }
-    const path =
-        typeof route.path === 'string' ? new URLPattern({ pathname: route.path }) : route.path
-    const method = route.method
-    const accept = route.accept
-    let normalizedAccept: MediaType[] | undefined
-    if (accept) {
-        const acceptList = Array.isArray(accept) ? accept : [accept]
-        normalizedAccept = acceptList.map((entry) => {
-            if (typeof entry === 'string') {
-                const parsed = parseMediaType(entry)
-                if (!parsed) {
-                    throw new Error(`Invalid accept media type: ${entry}`)
-                }
-                return parsed
-            }
-            return normalizeMediaType(entry)
-        })
-        if (normalizedAccept.length === 0) {
-            normalizedAccept = undefined
-        }
-    }
-    return {
-        name: normalizeRouteName(route.name, route.method, path),
-        path,
-        handler: route.handler,
-        ...(route.match === undefined ? {} : { match: route.match }),
-        ...(route.meta === undefined ? {} : { meta: route.meta }),
-        ...(route.schema === undefined ? {} : { schema: route.schema }),
-        ...(method === undefined ? {} : { method }),
-        ...(normalizedAccept === undefined ? {} : { accept: normalizedAccept }),
-    }
-}

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

@@ -1,56 +0,0 @@
-import type { JsonSchema, RouteSchema } from '../types'
-
-function unionJsonSchemas(left: JsonSchema, right: JsonSchema): JsonSchema {
-    return { anyOf: [left, right] }
-}
-
-/**
- * Merge route schema contributions from routes and middleware.
- *
- * Response declarations at the same status are alternatives. Request declarations describe
- * parsed context fields and therefore may only be declared once within an executed chain.
- *
- * @param schemas - Schema contributions in middleware execution order followed by the route.
- * @returns The combined schema contribution, or `undefined` if none were supplied.
- */
-export function mergeRouteSchemas(
-    ...schemas: Array<RouteSchema | undefined>
-): RouteSchema | undefined {
-    const request: NonNullable<RouteSchema['request']> = {}
-    const responseBody: NonNullable<NonNullable<RouteSchema['response']>['body']> = {}
-    let hasRequest = false
-    let hasResponse = false
-
-    for (const schema of schemas) {
-        if (!schema) continue
-        if (schema.request) {
-            for (const component of ['query', 'path', 'body'] as const) {
-                const declaration = schema.request[component]
-                if (declaration === undefined) continue
-                if (request[component] !== undefined) {
-                    throw new Error(
-                        `Multiple middleware or route schemas declare request.${component}.`,
-                    )
-                }
-                request[component] = declaration as never
-                hasRequest = true
-            }
-        }
-        for (const [status, declaration] of Object.entries(schema.response?.body ?? {})) {
-            if (declaration === undefined) continue
-            const normalizedStatus = status === 'default' ? status : Number(status)
-            const existing = responseBody[normalizedStatus]
-            responseBody[normalizedStatus] =
-                existing === undefined
-                    ? declaration
-                    : unionJsonSchemas(existing, declaration as JsonSchema)
-            hasResponse = true
-        }
-    }
-
-    if (!hasRequest && !hasResponse) return undefined
-    return {
-        ...(hasRequest ? { request } : {}),
-        ...(hasResponse ? { response: { body: responseBody } } : {}),
-    }
-}