@mpen/routekit 0.1.0 → 0.1.2

package/src/router/response/formats/problem/rateLimited.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 [`rateLimited`]{@link rateLimited}.
- *
- * @example
- * ```ts
- * rateLimited({
- *     message: 'Too many requests. Please try again later.',
- * })
- * ```
- *
- * @typeParam Code - Machine-readable primary error code.
- */
-export interface RateLimitedInit<Code extends string = 'rate_limited'> extends Omit<
-    ProblemResponseInit<Code>,
-    'code' | 'status' | 'message'
-> {
-    /**
-     * Machine-readable error code. Defaults to `'rate_limited'`.
-     */
-    code?: Code
-
-    /**
-     * Human-readable problem message.
-     */
-    message?: string
-
-    /**
-     * HTTP status code for this response. Defaults to `429`.
-     */
-    status?: number | HttpStatus
-}
-
-/**
- * Create a standard 429 Too Many Requests problem response envelope.
- *
- * @example
- * ```ts
- * return rateLimited('Rate limit exceeded. Please wait 60 seconds.')
- * ```
- *
- * @param message - Human-readable problem message.
- * @param init - Optional extra problem response options.
- * @returns Routekit logical response with a `'rate_limited'` [`ProblemResponse`]{@link ProblemResponse}.
- */
-export function rateLimited(
-    message: string,
-    init?: Omit<RateLimitedInit<'rate_limited'>, 'message'>,
-): RoutekitResponse<ProblemResponse<'rate_limited'>>
-
-/**
- * Create a standard 429 Too Many Requests problem response envelope.
- *
- * @example
- * ```ts
- * return rateLimited({ message: 'Rate limit exceeded.' })
- * ```
- *
- * @param init - Optional problem response options.
- * @returns Routekit logical response with a [`ProblemResponse`]{@link ProblemResponse}.
- * @typeParam Code - Machine-readable primary error code.
- */
-export function rateLimited<const Code extends string = 'rate_limited'>(
-    init?: RateLimitedInit<Code>,
-): RoutekitResponse<ProblemResponse<Code>>
-
-export function rateLimited<const Code extends string = 'rate_limited'>(
-    messageOrInit?: string | RateLimitedInit<Code>,
-    init?: Omit<RateLimitedInit<Code>, 'message'>,
-): RoutekitResponse<ProblemResponse<Code>> {
-    if (typeof messageOrInit === 'string') {
-        return problem({
-            ...init,
-            code: (init?.code ?? 'rate_limited') as Code,
-            message: messageOrInit,
-            status: init?.status ?? HttpStatus.TOO_MANY_REQUESTS,
-        })
-    }
-
-    return problem({
-        ...messageOrInit,
-        code: (messageOrInit?.code ?? 'rate_limited') as Code,
-        message: messageOrInit?.message ?? 'Rate limited',
-        status: messageOrInit?.status ?? HttpStatus.TOO_MANY_REQUESTS,
-    })
-}

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

@@ -1,219 +0,0 @@
-import { HttpStatus } from '@mpen/http'
-import { response, type RoutekitResponse, type RoutekitResponseInit } from '../../core'
-import type { SuccessResponse, ProblemIssue, ProblemResponse } from './types'
-
-/**
- * Default primary error code for validation problem responses.
- *
- * @example
- * ```ts
- * validationProblem([{ code: 'required', message: 'Name is required' }])
- * ```
- */
-export const VALIDATION_PROBLEM_CODE = 'validation_failed'
-
-/**
- * Options accepted by [`ok`]{@link ok}.
- *
- * @example
- * ```ts
- * ok({ id: 'user_123' }, { meta: { requestId: 'req_123' } })
- * ```
- *
- * @typeParam Meta - Optional metadata payload type.
- */
-export interface SuccessResponseInit<Meta = unknown> extends Omit<RoutekitResponseInit, 'status'> {
-    /**
-     * Optional response metadata.
-     */
-    meta?: Meta
-}
-
-/**
- * Options accepted by [`problem`]{@link problem}.
- *
- * @example
- * ```ts
- * problem({
- *     code: 'not_found',
- *     status: 404,
- *     message: 'No user exists for the provided id.',
- *     title: 'User not found',
- * })
- * ```
- *
- * @typeParam Code - Machine-readable primary error code.
- * @typeParam Issue - Issue shape used for validation or business-rule details.
- */
-export interface ProblemResponseInit<
-    Code extends string = string,
-    Issue extends ProblemIssue = ProblemIssue,
-    Status extends number = number,
-> extends Omit<RoutekitResponseInit, 'status'> {
-    /**
-     * Machine-readable error code.
-     */
-    code: Code
-
-    /**
-     * Human-readable problem message clients can display by default.
-     */
-    message: string
-
-    /**
-     * HTTP status code for this response.
-     */
-    status: Status
-
-    /**
-     * Optional short problem heading.
-     */
-    title?: string
-
-    /**
-     * Optional validation or business-rule issues.
-     */
-    issues?: readonly Issue[]
-}
-
-/**
- * Options accepted by [`validationProblem`]{@link validationProblem}.
- *
- * @example
- * ```ts
- * validationProblem([{ code: 'invalid_type', message: 'Expected a string' }], {
- *     message: 'The request body was invalid.',
- * })
- * ```
- *
- * @typeParam Code - Machine-readable primary error code.
- * @typeParam Issue - Issue shape used for validation details.
- */
-export interface ValidationProblemInit<
-    Code extends string = typeof VALIDATION_PROBLEM_CODE,
-    Issue extends ProblemIssue = ProblemIssue,
-    Status extends number = number,
-> extends Omit<ProblemResponseInit<Code, Issue, Status>, 'code' | 'message' | 'status' | 'issues'> {
-    /**
-     * Machine-readable validation error code.
-     */
-    code?: Code
-
-    /**
-     * Human-readable validation summary.
-     */
-    message?: string
-
-    /**
-     * HTTP status code for this response. Defaults to `400`.
-     */
-    status?: Status
-}
-
-function withDefinedOptional<Value extends object, Key extends string, Field>(
-    value: Value,
-    key: Key,
-    field: Field | undefined,
-): Value | (Value & Record<Key, Field>) {
-    if (field === undefined) return value
-    return { ...value, [key]: field } as Value & Record<Key, Field>
-}
-
-/**
- * Create a `200 OK` standard response envelope.
- *
- * @example
- * ```ts
- * router.get('/users/:id', () => ok({ id: 'user_123' }))
- * ```
- *
- * @param data - Successful response payload.
- * @param init - Response headers and optional metadata.
- * @returns Routekit logical response with an [`SuccessResponse`]{@link SuccessResponse} body.
- * @typeParam Data - Successful response payload type.
- * @typeParam Meta - Optional metadata payload type.
- */
-export function ok<const Data, const Meta = unknown>(
-    data: Data,
-    init: SuccessResponseInit<Meta> = {},
-): RoutekitResponse<SuccessResponse<Data, Meta>, HttpStatus.OK> {
-    const { meta, ...responseInit } = init
-    const body = withDefinedOptional(
-        { success: true, data } as const,
-        'meta',
-        meta,
-    ) as SuccessResponse<Data, Meta>
-    return response(body, { ...responseInit, status: HttpStatus.OK })
-}
-
-/**
- * Create a standard problem response envelope.
- *
- * @example
- * ```ts
- * return problem({
- *     code: 'not_found',
- *     status: 404,
- *     message: 'No user exists for the provided id.',
- *     title: 'User not found',
- * })
- * ```
- *
- * @param init - Problem response data, headers, and status.
- * @returns Routekit logical response with a [`ProblemResponse`]{@link ProblemResponse} body.
- * @typeParam Code - Machine-readable primary error code.
- * @typeParam Issue - Issue shape used for validation or business-rule details.
- */
-export function problem<
-    const Code extends string,
-    const Issue extends ProblemIssue = ProblemIssue,
-    const Status extends number = number,
->(
-    init: ProblemResponseInit<Code, Issue, Status>,
-): RoutekitResponse<ProblemResponse<Code, Issue>, Status> {
-    const { code, message, status, title, issues, ...responseInit } = init
-    const error = withDefinedOptional(
-        {
-            code,
-            message,
-        },
-        'title',
-        title,
-    )
-    const body = withDefinedOptional({ success: false, error } as const, 'issues', issues)
-
-    return response(body as ProblemResponse<Code, Issue>, { ...responseInit, status })
-}
-
-/**
- * Create a standard validation problem response envelope.
- *
- * @example
- * ```ts
- * return validationProblem([
- *     { code: 'required', message: 'Email is required', path: ['body', 'email'] },
- * ])
- * ```
- *
- * @param issues - Validation issues to include in the response.
- * @param init - Optional problem response overrides and headers.
- * @returns Routekit logical response with a validation [`ProblemResponse`]{@link ProblemResponse}.
- * @typeParam Issue - Issue shape used for validation details.
- * @typeParam Code - Machine-readable primary error code.
- */
-export function validationProblem<
-    const Issue extends ProblemIssue,
-    const Code extends string = typeof VALIDATION_PROBLEM_CODE,
-    const Status extends number = HttpStatus.BAD_REQUEST,
->(
-    issues: readonly Issue[],
-    init: ValidationProblemInit<Code, Issue, Status> = {},
-): RoutekitResponse<ProblemResponse<Code, Issue>, Status | HttpStatus.BAD_REQUEST> {
-    return problem({
-        ...init,
-        code: init.code ?? (VALIDATION_PROBLEM_CODE as Code),
-        message: init.message ?? 'Validation failed',
-        status: init.status ?? HttpStatus.BAD_REQUEST,
-        issues,
-    })
-}

package/src/router/response/formats/problem/root-errors.ts

@@ -1,48 +0,0 @@
-import { HttpStatus } from '@mpen/http'
-import type { AnyContext, RouterExtension } from '../../../types'
-import { problem } from './responses'
-
-/**
- * Install standard problem-envelope handlers for router-level errors.
- *
- * @example
- * ```ts
- * const router = new Router().install(problemRootErrors())
- * ```
- *
- * @returns Router extension that registers not-found, method, media-type, and internal-error handlers.
- * @typeParam Ctx - Context carried by the router being configured.
- */
-export function problemRootErrors<Ctx extends object = AnyContext>(): RouterExtension<Ctx> {
-    return (router) => {
-        router
-            .onNotFound(() =>
-                problem({
-                    code: 'not_found',
-                    message: 'Not found',
-                    status: HttpStatus.NOT_FOUND,
-                }),
-            )
-            .onMethodNotAllowed(() =>
-                problem({
-                    code: 'method_not_allowed',
-                    message: 'Method not allowed',
-                    status: HttpStatus.METHOD_NOT_ALLOWED,
-                }),
-            )
-            .onUnsupportedMediaType(() =>
-                problem({
-                    code: 'unsupported_media_type',
-                    message: 'Unsupported media type',
-                    status: HttpStatus.UNSUPPORTED_MEDIA_TYPE,
-                }),
-            )
-            .onInternalError(() =>
-                problem({
-                    code: 'internal_server_error',
-                    message: 'Internal server error',
-                    status: HttpStatus.INTERNAL_SERVER_ERROR,
-                }),
-            )
-    }
-}

package/src/router/response/formats/problem/sessionExpired.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 [`sessionExpired`]{@link sessionExpired}.
- *
- * @example
- * ```ts
- * sessionExpired({
- *     message: 'Your login session has expired. Please log in again.',
- * })
- * ```
- *
- * @typeParam Code - Machine-readable primary error code.
- */
-export interface SessionExpiredInit<Code extends string = 'session_expired'> extends Omit<
-    ProblemResponseInit<Code>,
-    'code' | 'status' | 'message'
-> {
-    /**
-     * Machine-readable error code. Defaults to `'session_expired'`.
-     */
-    code?: Code
-
-    /**
-     * Human-readable problem message.
-     */
-    message?: string
-
-    /**
-     * HTTP status code for this response. Defaults to `401`.
-     */
-    status?: number | HttpStatus
-}
-
-/**
- * Create a standard 401 Session Expired problem response envelope.
- *
- * @example
- * ```ts
- * return sessionExpired('Session has timed out.')
- * ```
- *
- * @param message - Human-readable problem message.
- * @param init - Optional extra problem response options.
- * @returns Routekit logical response with a `'session_expired'` [`ProblemResponse`]{@link ProblemResponse}.
- */
-export function sessionExpired(
-    message: string,
-    init?: Omit<SessionExpiredInit<'session_expired'>, 'message'>,
-): RoutekitResponse<ProblemResponse<'session_expired'>>
-
-/**
- * Create a standard 401 Session Expired problem response envelope.
- *
- * @example
- * ```ts
- * return sessionExpired({ message: 'Session expired.' })
- * ```
- *
- * @param init - Optional problem response options.
- * @returns Routekit logical response with a [`ProblemResponse`]{@link ProblemResponse}.
- * @typeParam Code - Machine-readable primary error code.
- */
-export function sessionExpired<const Code extends string = 'session_expired'>(
-    init?: SessionExpiredInit<Code>,
-): RoutekitResponse<ProblemResponse<Code>>
-
-export function sessionExpired<const Code extends string = 'session_expired'>(
-    messageOrInit?: string | SessionExpiredInit<Code>,
-    init?: Omit<SessionExpiredInit<Code>, 'message'>,
-): RoutekitResponse<ProblemResponse<Code>> {
-    if (typeof messageOrInit === 'string') {
-        return problem({
-            ...init,
-            code: (init?.code ?? 'session_expired') as Code,
-            message: messageOrInit,
-            status: init?.status ?? HttpStatus.UNAUTHORIZED,
-        })
-    }
-
-    return problem({
-        ...messageOrInit,
-        code: (messageOrInit?.code ?? 'session_expired') as Code,
-        message: messageOrInit?.message ?? 'Session expired',
-        status: messageOrInit?.status ?? HttpStatus.UNAUTHORIZED,
-    })
-}

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

@@ -1,170 +0,0 @@
-/**
- * Path segment used to locate a validation or business-rule issue.
- *
- * @example
- * ```ts
- * const path: ProblemIssuePathSegment[] = ['body', 'users', 0, 'email']
- * ```
- */
-export type ProblemIssuePathSegment = string | number
-
-/**
- * A single issue associated with a problem response.
- *
- * @example
- * ```ts
- * const issue: ProblemIssue<'required'> = {
- *     code: 'required',
- *     message: 'Email is required',
- *     path: ['body', 'email'],
- * }
- * ```
- *
- * @typeParam Code - Machine-readable issue code.
- */
-export interface ProblemIssue<Code extends string = string> {
-    /**
-     * Machine-readable issue code.
-     */
-    code: Code
-
-    /**
-     * Human-readable issue message.
-     */
-    message: string
-
-    /**
-     * Structured path to the invalid value.
-     */
-    path?: readonly ProblemIssuePathSegment[]
-
-    /**
-     * Expected value description.
-     */
-    expected?: string
-
-    /**
-     * Received value description.
-     */
-    received?: string
-}
-
-/**
- * Primary problem metadata that clients can switch on.
- *
- * @example
- * ```ts
- * const error: ProblemError<'not_found'> = {
- *     code: 'not_found',
- *     message: 'No user exists for the provided id.',
- *     title: 'User not found',
- * }
- * ```
- *
- * @typeParam Code - Machine-readable error code.
- */
-export interface ProblemError<Code extends string = string> {
-    /**
-     * Machine-readable error code.
-     */
-    code: Code
-
-    /**
-     * Human-readable problem message clients can display by default.
-     */
-    message: string
-
-    /**
-     * Optional short problem heading.
-     */
-    title?: string
-}
-
-/**
- * Successful standard response envelope.
- *
- * @example
- * ```ts
- * const response: SuccessResponse<{ id: string }> = {
- *     success: true,
- *     data: { id: 'user_123' },
- * }
- * ```
- *
- * @typeParam Data - Successful response payload type.
- * @typeParam Meta - Optional metadata payload type.
- */
-export interface SuccessResponse<Data = unknown, Meta = unknown> {
-    /**
-     * Discriminator for successful responses.
-     */
-    success: true
-
-    /**
-     * Successful response payload.
-     */
-    data: Data
-
-    /**
-     * Optional response metadata.
-     */
-    meta?: Meta
-}
-
-/**
- * Error standard response envelope.
- *
- * @example
- * ```ts
- * const response: ProblemResponse<'validation_failed'> = {
- *     success: false,
- *     error: {
- *         code: 'validation_failed',
- *         message: 'Validation failed',
- *     },
- *     issues: [{ code: 'required', message: 'Email is required', path: ['body', 'email'] }],
- * }
- * ```
- *
- * @typeParam Code - Machine-readable primary error code.
- * @typeParam Issue - Issue shape used for validation or business-rule details.
- */
-export interface ProblemResponse<
-    Code extends string = string,
-    Issue extends ProblemIssue = ProblemIssue,
-> {
-    /**
-     * Discriminator for problem responses.
-     */
-    success: false
-
-    /**
-     * Primary error clients can switch on.
-     */
-    error: ProblemError<Code>
-
-    /**
-     * Optional validation or business-rule issues.
-     */
-    issues?: readonly Issue[]
-}
-
-/**
- * Standard response union for successful and problem responses.
- *
- * @example
- * ```ts
- * type GetUserResponse = StandardResponse<{ id: string }, 'not_found'>
- * ```
- *
- * @typeParam Data - Successful response payload type.
- * @typeParam Code - Machine-readable primary error code.
- * @typeParam Issue - Issue shape used for validation or business-rule details.
- * @typeParam Meta - Optional metadata payload type.
- */
-export type StandardResponse<
-    Data = unknown,
-    Code extends string = string,
-    Issue extends ProblemIssue = ProblemIssue,
-    Meta = unknown,
-> = SuccessResponse<Data, Meta> | ProblemResponse<Code, Issue>

package/src/router/response/formats/problem/unauthenticated.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 [`unauthenticated`]{@link unauthenticated}.
- *
- * @example
- * ```ts
- * unauthenticated({
- *     message: 'You must be logged in to access this resource.',
- * })
- * ```
- *
- * @typeParam Code - Machine-readable primary error code.
- */
-export interface UnauthenticatedInit<Code extends string = 'unauthenticated'> extends Omit<
-    ProblemResponseInit<Code>,
-    'code' | 'status' | 'message'
-> {
-    /**
-     * Machine-readable error code. Defaults to `'unauthenticated'`.
-     */
-    code?: Code
-
-    /**
-     * Human-readable problem message.
-     */
-    message?: string
-
-    /**
-     * HTTP status code for this response. Defaults to `401`.
-     */
-    status?: number | HttpStatus
-}
-
-/**
- * Create a standard 401 Unauthenticated problem response envelope.
- *
- * @example
- * ```ts
- * return unauthenticated('Missing authorization token.')
- * ```
- *
- * @param message - Human-readable problem message.
- * @param init - Optional extra problem response options.
- * @returns Routekit logical response with a `'unauthenticated'` [`ProblemResponse`]{@link ProblemResponse}.
- */
-export function unauthenticated(
-    message: string,
-    init?: Omit<UnauthenticatedInit<'unauthenticated'>, 'message'>,
-): RoutekitResponse<ProblemResponse<'unauthenticated'>>
-
-/**
- * Create a standard 401 Unauthenticated problem response envelope.
- *
- * @example
- * ```ts
- * return unauthenticated({ message: 'Invalid credentials.' })
- * ```
- *
- * @param init - Optional problem response options.
- * @returns Routekit logical response with a [`ProblemResponse`]{@link ProblemResponse}.
- * @typeParam Code - Machine-readable primary error code.
- */
-export function unauthenticated<const Code extends string = 'unauthenticated'>(
-    init?: UnauthenticatedInit<Code>,
-): RoutekitResponse<ProblemResponse<Code>>
-
-export function unauthenticated<const Code extends string = 'unauthenticated'>(
-    messageOrInit?: string | UnauthenticatedInit<Code>,
-    init?: Omit<UnauthenticatedInit<Code>, 'message'>,
-): RoutekitResponse<ProblemResponse<Code>> {
-    if (typeof messageOrInit === 'string') {
-        return problem({
-            ...init,
-            code: (init?.code ?? 'unauthenticated') as Code,
-            message: messageOrInit,
-            status: init?.status ?? HttpStatus.UNAUTHORIZED,
-        })
-    }
-
-    return problem({
-        ...messageOrInit,
-        code: (messageOrInit?.code ?? 'unauthenticated') as Code,
-        message: messageOrInit?.message ?? 'Unauthenticated',
-        status: messageOrInit?.status ?? HttpStatus.UNAUTHORIZED,
-    })
-}