@mpen/routekit 0.1.0 → 0.1.2

package/src/router/response/core.ts

@@ -1,181 +0,0 @@
-import { CommonHeaders, HttpStatus } from '@mpen/http'
-import type { RouterBodyInit, RouterHeadersInit } from '../fetch-types'
-
-const routekitResponseBrand: unique symbol = Symbol('RoutekitResponse')
-const routekitBodyBrand: unique symbol = Symbol('RoutekitBody')
-
-/**
- * Logical route result used by Routekit before it is finalized into a native [`Response`]{@link Response}.
- *
- * @example
- * ```ts
- * const result = ok({payload: 'ready'})
- * ```
- */
-export 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.
- */
-export 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'})
- * ```
- */
-export interface RoutekitBody<T = unknown> {
-    readonly [routekitBodyBrand]: true
-    /**
-     * Logical response body value.
-     */
-    value: T
-}
-
-function hasContentType(headers: Headers): boolean {
-    return headers.has(CommonHeaders.CONTENT_TYPE)
-}
-
-function isArrayBufferView(value: unknown): value is ArrayBufferView {
-    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.
- */
-export function isResponseBodyInit(value: unknown): value is RouterBodyInit | null | undefined {
-    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.
- */
-export function isRoutekitResponse(value: unknown): value is RoutekitResponse {
-    return !!value && (value as RoutekitResponse)[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}.
- */
-export function isRoutekitBody(value: unknown): value is RoutekitBody {
-    return !!value && (value as RoutekitBody)[routekitBodyBrand] === true
-}
-
-/**
- * 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.
- */
-export function response<const T>(responseBody: T): RoutekitResponse<T, HttpStatus.OK>
-export function response<const T>(
-    responseBody: T,
-    init: Omit<RoutekitResponseInit, 'status'>,
-): RoutekitResponse<T, HttpStatus.OK>
-export function response<const T, const Status extends number>(
-    responseBody: T,
-    init: RoutekitResponseInit<Status> & { status: Status },
-): RoutekitResponse<T, Status>
-export function response<const T>(
-    responseBody: T,
-    init: RoutekitResponseInit = {},
-): RoutekitResponse<T, number> {
-    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.
- */
-export function body<const T>(value: T): RoutekitBody<T> {
-    return {
-        [routekitBodyBrand]: true,
-        value,
-    }
-}

package/src/router/response/directives.ts

@@ -1,233 +0,0 @@
-import type { HttpStatus } from '@mpen/http'
-import type { RouterHeadersInit } from '../fetch-types'
-import type { StreamFramer } from './framers'
-
-const routekitDirectiveBrand: unique symbol = Symbol('RoutekitDirective')
-
-interface BaseDirective {
-    readonly [routekitDirectiveBrand]: true
-}
-
-/**
- * Generator directive that sets the response status.
- */
-export interface StatusDirective extends BaseDirective {
-    kind: 'status'
-    status: number | HttpStatus
-}
-
-/**
- * Generator directive that merges response headers.
- */
-export interface HeadersDirective extends BaseDirective {
-    kind: 'headers'
-    headers: Headers
-}
-
-/**
- * Generator directive that sets response status and merges response headers.
- */
-export interface HeadDirective extends BaseDirective {
-    kind: 'head'
-    status: number | HttpStatus
-    headers: Headers
-}
-
-/**
- * Generator directive that starts structured streaming with a framer.
- */
-export interface StreamDirective<T = unknown> extends BaseDirective {
-    kind: 'stream'
-    framer: StreamFramer<T>
-    headers: Headers
-}
-
-/**
- * Generator directive that emits one stream chunk.
- */
-export interface ChunkDirective<T = unknown> extends BaseDirective {
-    kind: 'chunk'
-    value: T
-}
-
-/**
- * Values that generator-style handlers may yield.
- */
-export type RoutekitYield =
-    | StatusDirective
-    | HeadersDirective
-    | HeadDirective
-    | StreamDirective
-    | ChunkDirective
-    | undefined
-
-/**
- * Test whether a value is a generator directive.
- *
- * @example
- * ```ts
- * if (isRoutekitDirective(value)) console.log(value.kind)
- * ```
- *
- * @param value - Value to inspect.
- * @returns Whether `value` is a Routekit generator directive.
- */
-export function isRoutekitDirective(value: unknown): value is Exclude<RoutekitYield, undefined> {
-    return !!value && (value as BaseDirective)[routekitDirectiveBrand] === true
-}
-
-/**
- * Test whether a value is a status directive.
- *
- * @param value - Value to inspect.
- * @returns Whether `value` was created by [`status`]{@link status}.
- */
-export function isStatusDirective(value: unknown): value is StatusDirective {
-    return isRoutekitDirective(value) && value.kind === 'status'
-}
-
-/**
- * Test whether a value is a headers directive.
- *
- * @param value - Value to inspect.
- * @returns Whether `value` was created by [`headers`]{@link headers}.
- */
-export function isHeadersDirective(value: unknown): value is HeadersDirective {
-    return isRoutekitDirective(value) && value.kind === 'headers'
-}
-
-/**
- * Test whether a value is a head directive.
- *
- * @param value - Value to inspect.
- * @returns Whether `value` was created by [`head`]{@link head}.
- */
-export function isHeadDirective(value: unknown): value is HeadDirective {
-    return isRoutekitDirective(value) && value.kind === 'head'
-}
-
-/**
- * Test whether a value is a stream directive.
- *
- * @param value - Value to inspect.
- * @returns Whether `value` was created by [`stream`]{@link stream}.
- */
-export function isStreamDirective(value: unknown): value is StreamDirective {
-    return isRoutekitDirective(value) && value.kind === 'stream'
-}
-
-/**
- * Test whether a value is a chunk directive.
- *
- * @param value - Value to inspect.
- * @returns Whether `value` was created by [`chunk`]{@link chunk}.
- */
-export function isChunkDirective(value: unknown): value is ChunkDirective {
-    return isRoutekitDirective(value) && value.kind === 'chunk'
-}
-
-function makeDirective<T extends BaseDirective>(directive: Omit<T, typeof routekitDirectiveBrand>) {
-    return {
-        [routekitDirectiveBrand]: true,
-        ...directive,
-    } as T
-}
-
-/**
- * Create a generator directive that sets the response status.
- *
- * @example
- * ```ts
- * yield status(HttpStatus.ACCEPTED)
- * ```
- *
- * @param statusCode - HTTP status code to use.
- * @returns Status directive.
- */
-export function status(statusCode: number | HttpStatus): StatusDirective {
-    return makeDirective<StatusDirective>({
-        kind: 'status',
-        status: statusCode,
-    })
-}
-
-/**
- * Create a generator directive that merges response headers.
- *
- * @example
- * ```ts
- * yield headers({'cache-control': 'no-store'})
- * ```
- *
- * @param init - Headers to merge into the response.
- * @returns Headers directive.
- */
-export function headers(init: RouterHeadersInit): HeadersDirective {
-    return makeDirective<HeadersDirective>({
-        kind: 'headers',
-        headers: new Headers(init),
-    })
-}
-
-/**
- * Create a generator directive that sets response status and headers.
- *
- * @example
- * ```ts
- * yield head(HttpStatus.OK, {'cache-control': 'no-store'})
- * ```
- *
- * @param statusCode - HTTP status code to use.
- * @param init - Headers to merge into the response.
- * @returns Head directive.
- */
-export function head(statusCode: number | HttpStatus, init: RouterHeadersInit = {}): HeadDirective {
-    return makeDirective<HeadDirective>({
-        kind: 'head',
-        status: statusCode,
-        headers: new Headers(init),
-    })
-}
-
-/**
- * Create a generator directive that selects a structured stream framer.
- *
- * @example
- * ```ts
- * yield stream(sseFramer())
- * ```
- *
- * @param framer - Stream framer to use for subsequent chunks.
- * @param init - Additional stream headers.
- * @returns Stream directive.
- */
-export function stream<const T>(
-    framer: StreamFramer<T>,
-    init: RouterHeadersInit = {},
-): StreamDirective<T> {
-    const streamHeaders = new Headers(framer.headers)
-    new Headers(init).forEach((value, key) => streamHeaders.set(key, value))
-    return makeDirective<StreamDirective<T>>({
-        kind: 'stream',
-        framer,
-        headers: streamHeaders,
-    })
-}
-
-/**
- * Create a generator directive that emits one stream chunk.
- *
- * @example
- * ```ts
- * yield chunk({event: 'ready'})
- * ```
- *
- * @param value - Chunk value to stream.
- * @returns Chunk directive.
- */
-export function chunk<const T>(value: T): ChunkDirective<T> {
-    return makeDirective<ChunkDirective<T>>({
-        kind: 'chunk',
-        value,
-    })
-}

package/src/router/response/formats/content/bodyless.ts

@@ -1,54 +0,0 @@
-import { HttpStatus } from '@mpen/http'
-import { response, type RoutekitResponse, type RoutekitResponseInit } from '../../core'
-
-/**
- * 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.
- */
-export function empty<const Status extends number = HttpStatus.NO_CONTENT>(
-    statusCode: Status = HttpStatus.NO_CONTENT as Status,
-    init: Omit<RoutekitResponseInit, 'status'> = {},
-): RoutekitResponse<undefined, Status> {
-    return response(undefined, { ...init, status: statusCode })
-}
-
-/**
- * Create a `204 No Content` response.
- *
- * @example
- * ```ts
- * return noContent()
- * ```
- *
- * @returns Routekit logical response with no body.
- */
-export function noContent(): RoutekitResponse<undefined, HttpStatus.NO_CONTENT> {
-    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.
- */
-export function redirect<const Status extends number = HttpStatus.FOUND>(
-    url: string,
-    statusCode: Status = HttpStatus.FOUND as Status,
-): RoutekitResponse<undefined, Status> {
-    return empty(statusCode, { headers: { Location: url } })
-}

package/src/router/response/formats/content/content.ts

@@ -1,79 +0,0 @@
-import { CommonContentTypes, CommonHeaders, HttpStatus } from '@mpen/http'
-import { fullWide } from '../../../lib/format'
-import { response, type RoutekitResponse, type RoutekitResponseInit } from '../../core'
-
-/**
- * Create a represented `text/plain` response.
- *
- * @example
- * ```ts
- * return text('pong')
- * ```
- *
- * @param value - Text response body.
- * @param init - Response status and headers.
- * @returns Routekit logical response with `Content-Type` set.
- */
-export function text(value: string): RoutekitResponse<string, HttpStatus.OK>
-export function text(
-    value: string,
-    init: Omit<RoutekitResponseInit, 'status'>,
-): RoutekitResponse<string, HttpStatus.OK>
-export function text<const Status extends number>(
-    value: string,
-    init: RoutekitResponseInit<Status> & { status: Status },
-): RoutekitResponse<string, Status>
-export function text(
-    value: string,
-    init: RoutekitResponseInit<number> = {},
-): RoutekitResponse<string, number> {
-    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,
-    })
-}
-
-/**
- * Create a represented `text/html` response.
- *
- * @example
- * ```ts
- * return html('<h1>Hello</h1>')
- * ```
- *
- * @param value - HTML response body.
- * @param init - Response status and headers.
- * @returns Routekit logical response with `Content-Type` set.
- */
-export function html(value: string): RoutekitResponse<string, HttpStatus.OK>
-export function html(
-    value: string,
-    init: Omit<RoutekitResponseInit, 'status'>,
-): RoutekitResponse<string, HttpStatus.OK>
-export function html<const Status extends number>(
-    value: string,
-    init: RoutekitResponseInit<Status> & { status: Status },
-): RoutekitResponse<string, Status>
-export function html(
-    value: string,
-    init: RoutekitResponseInit<number> = {},
-): RoutekitResponse<string, number> {
-    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,
-    })
-}

package/src/router/response/formats/content/index.ts

@@ -1,2 +0,0 @@
-export { html, text } from './content'
-export { empty, noContent, redirect } from './bodyless'

package/src/router/response/formats/json-rpc/index.ts

@@ -1,2 +0,0 @@
-// JSON-RPC 2.0 response format placeholder
-export {}

package/src/router/response/formats/problem/badRequest.ts

@@ -1,90 +0,0 @@
-import { HttpStatus } from '@mpen/http'
-import type { RoutekitResponse } from '../../core'
-import { problem, type ProblemResponseInit } from './responses'
-import type { ProblemResponse } from './types'
-
-/**
- * Options accepted by [`badRequest`]{@link badRequest}.
- *
- * @example
- * ```ts
- * badRequest({
- *     message: 'The request is malformed.',
- * })
- * ```
- *
- * @typeParam Code - Machine-readable primary error code.
- */
-export interface BadRequestInit<Code extends string = 'bad_request'> extends Omit<
-    ProblemResponseInit<Code>,
-    'code' | 'status' | 'message'
-> {
-    /**
-     * Machine-readable error code. Defaults to `'bad_request'`.
-     */
-    code?: Code
-
-    /**
-     * Human-readable problem message.
-     */
-    message?: string
-
-    /**
-     * HTTP status code for this response. Defaults to `400`.
-     */
-    status?: number | HttpStatus
-}
-
-/**
- * Create a standard 400 Bad Request problem response envelope.
- *
- * @example
- * ```ts
- * return badRequest('Invalid query parameter format.')
- * ```
- *
- * @param message - Human-readable problem message.
- * @param init - Optional extra problem response options.
- * @returns Routekit logical response with a `'bad_request'` [`ProblemResponse`]{@link ProblemResponse}.
- */
-export function badRequest(
-    message: string,
-    init?: Omit<BadRequestInit<'bad_request'>, 'message'>,
-): RoutekitResponse<ProblemResponse<'bad_request'>>
-
-/**
- * Create a standard 400 Bad Request problem response envelope.
- *
- * @example
- * ```ts
- * return badRequest({ message: 'Malformed payload.' })
- * ```
- *
- * @param init - Optional problem response options.
- * @returns Routekit logical response with a [`ProblemResponse`]{@link ProblemResponse}.
- * @typeParam Code - Machine-readable primary error code.
- */
-export function badRequest<const Code extends string = 'bad_request'>(
-    init?: BadRequestInit<Code>,
-): RoutekitResponse<ProblemResponse<Code>>
-
-export function badRequest<const Code extends string = 'bad_request'>(
-    messageOrInit?: string | BadRequestInit<Code>,
-    init?: Omit<BadRequestInit<Code>, 'message'>,
-): RoutekitResponse<ProblemResponse<Code>> {
-    if (typeof messageOrInit === 'string') {
-        return problem({
-            ...init,
-            code: (init?.code ?? 'bad_request') as Code,
-            message: messageOrInit,
-            status: init?.status ?? HttpStatus.BAD_REQUEST,
-        })
-    }
-
-    return problem({
-        ...messageOrInit,
-        code: (messageOrInit?.code ?? 'bad_request') as Code,
-        message: messageOrInit?.message ?? 'Bad request',
-        status: messageOrInit?.status ?? HttpStatus.BAD_REQUEST,
-    })
-}