@mpen/routekit 0.1.0 → 0.1.2

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

@@ -1,410 +0,0 @@
-import * as v from 'valibot'
-import { validationProblem, type ValidationProblemInit } from './responses'
-import type { ProblemIssue, ProblemIssuePathSegment, ProblemResponse } from './types'
-import type { RoutekitResponse } from '../../core'
-import {
-    createValibotRouteBuilder as baseCreateValibotRouteBuilder,
-    ValibotValidationError,
-    type ValibotRouteBuilder,
-    type ValibotRouteHelperDefaults,
-} from '../../../routes/valibot/valibot'
-import type { ContextFromMiddlewareInput, MiddlewareInput } from '../../../types'
-import { HttpStatus } from '@mpen/http'
-
-type AnySchema = v.BaseSchema<any, any, any>
-type StringSchema = v.BaseSchema<any, string, any>
-type ProblemSchemaResult<CodeSchema extends StringSchema, Schema extends AnySchema> = v.BaseSchema<
-    v.InferInput<Schema>,
-    ProblemResponse<v.InferOutput<CodeSchema> & string>,
-    v.InferIssue<Schema>
->
-
-function pathSegmentFromValibotKey(key: unknown): ProblemIssuePathSegment | undefined {
-    if (typeof key === 'string' || typeof key === 'number') return key
-    return undefined
-}
-
-function pathFromValibotIssue(issue: v.BaseIssue<unknown>): ProblemIssuePathSegment[] | undefined {
-    const path = issue.path
-        ?.map((item) => pathSegmentFromValibotKey(item.key))
-        .filter((item): item is ProblemIssuePathSegment => item !== undefined)
-    return path?.length ? path : undefined
-}
-
-function collectValibotIssues(issue: v.BaseIssue<unknown>, target: ProblemIssue[]): ProblemIssue[] {
-    if (issue.issues?.length) {
-        for (const child of issue.issues) {
-            collectValibotIssues(child, target)
-        }
-        return target
-    }
-    target.push(issueFromValibotIssue(issue))
-    return target
-}
-
-function createSuccessSchema<const DataSchema extends AnySchema>(dataSchema: DataSchema) {
-    return v.object({
-        success: v.literal(true),
-        data: dataSchema,
-    })
-}
-
-function createSuccessSchemaWithMeta<
-    const DataSchema extends AnySchema,
-    const MetaSchema extends AnySchema,
->(dataSchema: DataSchema, metaSchema: MetaSchema) {
-    return v.object({
-        success: v.literal(true),
-        data: dataSchema,
-        meta: v.optional(metaSchema),
-    })
-}
-
-type SuccessSchemaResult<
-    DataSchema extends AnySchema,
-    MetaSchema extends AnySchema | undefined,
-> = MetaSchema extends AnySchema
-    ? ReturnType<typeof createSuccessSchemaWithMeta<DataSchema, MetaSchema>>
-    : ReturnType<typeof createSuccessSchema<DataSchema>>
-
-/**
- * Create a Valibot schema for standard response issues.
- *
- * @example
- * ```ts
- * const schema = problemIssueSchema(v.picklist(['required', 'invalid_type']))
- * ```
- *
- * @param codeSchema - Optional issue code schema. Defaults to `v.string()`.
- * @returns Valibot object schema for [`ProblemIssue`]{@link ProblemIssue}.
- * @typeParam CodeSchema - Valibot schema used for issue codes.
- */
-export function problemIssueSchema<const CodeSchema extends StringSchema = StringSchema>(
-    codeSchema: CodeSchema = v.string() as unknown as CodeSchema,
-) {
-    return v.object({
-        code: codeSchema,
-        message: v.string(),
-        path: v.optional(v.pipe(v.array(v.union([v.string(), v.number()])), v.readonly())),
-        expected: v.optional(v.string()),
-        received: v.optional(v.string()),
-    })
-}
-
-/**
- * Create a Valibot schema for standard primary error metadata.
- *
- * @example
- * ```ts
- * const schema = problemErrorSchema(v.picklist(['not_found', 'validation_failed']))
- * ```
- *
- * @param codeSchema - Optional primary error code schema. Defaults to `v.string()`.
- * @returns Valibot object schema for problem error metadata.
- * @typeParam CodeSchema - Valibot schema used for primary error codes.
- */
-export function problemErrorSchema<const CodeSchema extends StringSchema = StringSchema>(
-    codeSchema: CodeSchema = v.string() as unknown as CodeSchema,
-) {
-    return v.object({
-        code: codeSchema,
-        message: v.string(),
-        title: v.optional(v.string()),
-    })
-}
-
-/**
- * Create a Valibot schema for successful standard response envelopes.
- *
- * @example
- * ```ts
- * const schema = okSchema(v.object({ id: v.string() }))
- * ```
- *
- * @param dataSchema - Valibot schema for the response payload.
- * @param metaSchema - Optional Valibot schema for response metadata.
- * @returns Valibot object schema for a successful standard response.
- * @typeParam DataSchema - Valibot schema used for the response payload.
- * @typeParam MetaSchema - Optional Valibot schema used for response metadata.
- */
-export function okSchema<
-    const DataSchema extends AnySchema,
-    const MetaSchema extends AnySchema | undefined = undefined,
->(dataSchema: DataSchema, metaSchema?: MetaSchema): SuccessSchemaResult<DataSchema, MetaSchema> {
-    if (metaSchema) {
-        return createSuccessSchemaWithMeta(dataSchema, metaSchema) as SuccessSchemaResult<
-            DataSchema,
-            MetaSchema
-        >
-    }
-    return createSuccessSchema(dataSchema) as SuccessSchemaResult<DataSchema, MetaSchema>
-}
-
-/**
- * Create a Valibot schema for standard problem response envelopes.
- *
- * @example
- * ```ts
- * const schema = problemSchema({
- *     code: v.picklist(['not_found', 'validation_failed']),
- * })
- * ```
- *
- * @param options - Optional primary error and issue schemas.
- * @returns Valibot object schema for a standard problem response.
- * @typeParam CodeSchema - Valibot schema used for primary error codes.
- * @typeParam IssueSchema - Valibot schema used for response issues.
- */
-export function problemSchema<
-    const CodeSchema extends StringSchema = StringSchema,
-    const IssueSchema extends AnySchema = ReturnType<typeof problemIssueSchema>,
->(
-    options: {
-        code?: CodeSchema
-        issue?: IssueSchema
-    } = {},
-) {
-    const codeSchema = options.code ?? (v.string() as unknown as CodeSchema)
-    const issueSchema = options.issue ?? (problemIssueSchema() as unknown as IssueSchema)
-
-    const schema = v.object({
-        success: v.literal(false),
-        error: problemErrorSchema(codeSchema),
-        issues: v.optional(v.pipe(v.array(issueSchema), v.readonly())),
-    })
-
-    return schema as unknown as ProblemSchemaResult<CodeSchema, typeof schema>
-}
-
-/**
- * Create a Valibot schema for the full standard response union.
- *
- * @example
- * ```ts
- * const schema = standardResponseSchema(v.object({ id: v.string() }), {
- *     code: v.picklist(['not_found']),
- * })
- * ```
- *
- * @param dataSchema - Valibot schema for the successful response payload.
- * @param options - Optional metadata, primary error, and issue schemas.
- * @returns Valibot union schema for successful and problem responses.
- * @typeParam DataSchema - Valibot schema used for the response payload.
- * @typeParam MetaSchema - Optional Valibot schema used for response metadata.
- * @typeParam CodeSchema - Valibot schema used for primary error codes.
- * @typeParam IssueSchema - Valibot schema used for response issues.
- */
-export function standardResponseSchema<
-    const DataSchema extends AnySchema,
-    const MetaSchema extends AnySchema | undefined = undefined,
-    const CodeSchema extends StringSchema = StringSchema,
-    const IssueSchema extends AnySchema = ReturnType<typeof problemIssueSchema>,
->(
-    dataSchema: DataSchema,
-    options: {
-        meta?: MetaSchema
-        code?: CodeSchema
-        issue?: IssueSchema
-    } = {},
-) {
-    const successEnvelopeSchema =
-        options.meta === undefined ? okSchema(dataSchema) : okSchema(dataSchema, options.meta)
-    return v.union([
-        successEnvelopeSchema,
-        problemSchema({ code: options.code, issue: options.issue }),
-    ])
-}
-
-/**
- * Convert a Valibot issue into a standard response issue.
- *
- * @example
- * ```ts
- * const parsed = v.safeParse(v.object({ id: v.string() }), { id: 123 })
- * if (!parsed.success) {
- *     const issue = issueFromValibotIssue(parsed.issues[0])
- * }
- * ```
- *
- * @param issue - Valibot issue to convert.
- * @returns Standard response issue.
- */
-export function issueFromValibotIssue(issue: v.BaseIssue<unknown>): ProblemIssue {
-    const path = pathFromValibotIssue(issue)
-    return {
-        code: issue.type,
-        message: issue.message,
-        ...(path ? { path } : {}),
-        ...(issue.expected == null ? {} : { expected: issue.expected }),
-        received: issue.received,
-    }
-}
-
-/**
- * Convert Valibot issues into standard response issues.
- *
- * @example
- * ```ts
- * const parsed = v.safeParse(v.object({ id: v.string() }), { id: 123 })
- * if (!parsed.success) {
- *     const issues = issuesFromValibotIssues(parsed.issues)
- * }
- * ```
- *
- * @param issues - Valibot issues to convert.
- * @returns Standard response issues.
- */
-export function issuesFromValibotIssues(issues: readonly v.BaseIssue<unknown>[]): ProblemIssue[] {
-    return issues.flatMap((issue) => collectValibotIssues(issue, []))
-}
-
-/**
- * Create a validation problem response from Valibot issues.
- *
- * @example
- * ```ts
- * const route = createValibotRouteBuilder()
- * route({
- *     onRequestValidationError: (_component, issues) => validationProblemFromValibotIssues(issues),
- *     handler: () => ok({ saved: true }),
- * })
- * ```
- *
- * @param issues - Valibot issues to convert and include in the response.
- * @param init - Optional problem response overrides and headers.
- * @returns Routekit logical response with a validation [`ProblemResponse`]{@link ProblemResponse}.
- * @typeParam Code - Machine-readable primary error code.
- */
-export function validationProblemFromValibotIssues<const Code extends string = 'validation_failed'>(
-    issues: readonly v.BaseIssue<unknown>[],
-    init: ValidationProblemInit<Code> = {},
-): RoutekitResponse<ProblemResponse<Code>> {
-    return validationProblem(issuesFromValibotIssues(issues), init)
-}
-
-/**
- * A Valibot validation error handler that maps request validation errors to problem-compliant responses.
- *
- * This handler returns `422 Unprocessable Content` with error code `validation_failed:body` for request body
- * validation failures, and `400 Bad Request` with `validation_failed:query` or `validation_failed:path` for
- * query and path parameter validation failures respectively.
- *
- * @example
- * ```ts
- * const route = createValibotRouteBuilder({
- *     onRequestValidationError: problemValidationErrorHandler,
- * })
- * ```
- *
- * @param component - The request component that failed validation.
- * @param issues - A non-empty tuple of Valibot validation issues.
- * @returns A Routekit handler result containing the formatted problem response.
- */
-export function problemValidationErrorHandler(
-    component: ValibotValidationError,
-    issues: [v.BaseIssue<unknown>, ...v.BaseIssue<unknown>[]],
-): RoutekitResponse<
-    ProblemResponse<'validation_failed:body' | 'validation_failed:query' | 'validation_failed:path'>
-> {
-    let code: 'validation_failed:body' | 'validation_failed:query' | 'validation_failed:path'
-    let status: number
-
-    switch (component) {
-        case ValibotValidationError.REQUEST_BODY:
-            code = 'validation_failed:body'
-            status = HttpStatus.UNPROCESSABLE_ENTITY
-            break
-        case ValibotValidationError.QUERY_PARAMETERS:
-            code = 'validation_failed:query'
-            status = HttpStatus.BAD_REQUEST
-            break
-        case ValibotValidationError.URL_PATH:
-            code = 'validation_failed:path'
-            status = HttpStatus.BAD_REQUEST
-            break
-        default:
-            code = 'validation_failed:body'
-            status = HttpStatus.UNPROCESSABLE_ENTITY
-            break
-    }
-
-    return validationProblemFromValibotIssues(issues, {
-        code,
-        status,
-        message: `Validation failed: ${
-            component === ValibotValidationError.REQUEST_BODY
-                ? 'body'
-                : component === ValibotValidationError.QUERY_PARAMETERS
-                  ? 'query'
-                  : 'path'
-        }`,
-    })
-}
-
-/**
- * Create a Valibot route builder pre-configured with problem-spec-compliant request validation errors.
- *
- * This route builder automatically configures standard error schemas for `400 Bad Request` and
- * `422 Unprocessable Content` statuses. It also uses [`problemValidationErrorHandler`]{@link problemValidationErrorHandler}
- * as its default validation error handler to output structured JSON responses when validation fails.
- *
- * @example
- * ```ts
- * const route = createValibotRouteBuilder()
- *
- * router.post('/todos', route({
- *     schema: {
- *         request: {
- *             body: v.object({ title: v.string() })
- *         }
- *     },
- *     handler: ({ body }) => ok({ title: body.title })
- * }))
- * ```
- *
- * @param defaults - Additional defaults to apply to built routes.
- * @returns A problem-spec-compliant Valibot route builder.
- * @typeParam BuilderCtx - Custom context registered by middlewares (e.g. Services, Auth).
- */
-export function createValibotRouteBuilder<
-    BuilderMiddleware extends MiddlewareInput<any>,
-    BuilderCtx extends object = ContextFromMiddlewareInput<BuilderMiddleware>,
->(
-    defaults: ValibotRouteHelperDefaults<BuilderCtx, BuilderMiddleware> & {
-        middleware: BuilderMiddleware
-    },
-): ValibotRouteBuilder<BuilderCtx, BuilderMiddleware>
-export function createValibotRouteBuilder<
-    BuilderCtx extends object = object,
-    BuilderMiddleware extends MiddlewareInput<BuilderCtx> = undefined,
->(
-    defaults?: ValibotRouteHelperDefaults<BuilderCtx, BuilderMiddleware>,
-): ValibotRouteBuilder<BuilderCtx, BuilderMiddleware>
-export function createValibotRouteBuilder<
-    BuilderCtx extends object = object,
-    BuilderMiddleware extends MiddlewareInput<BuilderCtx> = undefined,
->(
-    defaults: ValibotRouteHelperDefaults<BuilderCtx, BuilderMiddleware> = {},
-): ValibotRouteBuilder<BuilderCtx, BuilderMiddleware> {
-    const defaultSchema = {
-        response: {
-            body: {
-                400: v.union([
-                    problemSchema({ code: v.literal('validation_failed:query') }),
-                    problemSchema({ code: v.literal('validation_failed:path') }),
-                ]),
-                422: problemSchema({
-                    code: v.literal('validation_failed:body'),
-                }),
-            },
-        },
-    }
-
-    const mergedDefaults: ValibotRouteHelperDefaults<BuilderCtx, BuilderMiddleware> = {
-        onRequestValidationError: problemValidationErrorHandler,
-        validationResponses: defaultSchema.response.body,
-        ...defaults,
-    }
-
-    return baseCreateValibotRouteBuilder(mergedDefaults)
-}

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

@@ -1 +0,0 @@
-export { badRequest, ok, unprocessableContent } from './responses'

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

@@ -1,59 +0,0 @@
-import { HttpStatus } from '@mpen/http'
-import { response, type RoutekitResponse, type RoutekitResponseInit } from '../../core'
-
-/**
- * Create a `200 OK` logical response.
- *
- * @example
- * ```ts
- * return ok({payload: 'ready'})
- * ```
- *
- * @param responseBody - Logical response body.
- * @param init - Response headers.
- * @returns Routekit logical response.
- */
-export function ok<const T>(
-    responseBody: T,
-    init: Omit<RoutekitResponseInit, 'status'> = {},
-): RoutekitResponse<T, HttpStatus.OK> {
-    return response(responseBody, { ...init, status: HttpStatus.OK })
-}
-
-/**
- * Create a `400 Bad Request` logical response.
- *
- * @example
- * ```ts
- * return badRequest({message: 'Invalid request'})
- * ```
- *
- * @param responseBody - Logical response body.
- * @param init - Response headers.
- * @returns Routekit logical response.
- */
-export function badRequest<const T>(
-    responseBody: T,
-    init: Omit<RoutekitResponseInit, 'status'> = {},
-): RoutekitResponse<T, HttpStatus.BAD_REQUEST> {
-    return response(responseBody, { ...init, status: HttpStatus.BAD_REQUEST })
-}
-
-/**
- * Create a `422 Unprocessable Content` logical response.
- *
- * @example
- * ```ts
- * return unprocessableContent({message: 'Email is already taken'})
- * ```
- *
- * @param responseBody - Logical response body.
- * @param init - Response headers.
- * @returns Routekit logical response.
- */
-export function unprocessableContent<const T>(
-    responseBody: T,
-    init: Omit<RoutekitResponseInit, 'status'> = {},
-): RoutekitResponse<T, HttpStatus.UNPROCESSABLE_ENTITY> {
-    return response(responseBody, { ...init, status: HttpStatus.UNPROCESSABLE_ENTITY })
-}

package/src/router/response/formats/status/status.test.ts

@@ -1,21 +0,0 @@
-#!/usr/bin/env -S bun test
-import { describe, expect, it } from 'bun:test'
-import { HttpStatus } from '@mpen/http'
-import { badRequest, unprocessableContent } from './responses'
-
-describe('status response helpers', () => {
-    it('creates bad request responses', () => {
-        const result = badRequest({ message: 'Invalid request' }, { headers: { 'x-error': '1' } })
-
-        expect(result.status).toBe(HttpStatus.BAD_REQUEST)
-        expect(result.body).toEqual({ message: 'Invalid request' })
-        expect(result.headers.get('x-error')).toBe('1')
-    })
-
-    it('creates unprocessable content responses', () => {
-        const result = unprocessableContent({ message: 'Email is already taken' })
-
-        expect(result.status).toBe(HttpStatus.UNPROCESSABLE_ENTITY)
-        expect(result.body).toEqual({ message: 'Email is already taken' })
-    })
-})

package/src/router/response/framers.ts

@@ -1,85 +0,0 @@
-import { CommonHeaders } from '@mpen/http'
-import type { RouterHeadersInit } from '../fetch-types'
-
-type MaybePromise<T> = T | Promise<T>
-type BodyChunk = string | Uint8Array | Buffer
-
-/**
- * Framer used by streaming generators to encode structured chunks.
- *
- * @example
- * ```ts
- * yield stream(sseFramer())
- * yield chunk({event: 'ready'})
- * ```
- */
-export interface StreamFramer<T = unknown> {
-    /**
-     * Content type for the stream.
-     */
-    contentType: string
-    /**
-     * Headers to add when this stream starts.
-     */
-    headers?: RouterHeadersInit
-    /**
-     * Return `true` when this framer can encode the provided chunk.
-     *
-     * @param value - Stream chunk to inspect.
-     * @returns Whether `value` can be framed.
-     */
-    canFrame?: (value: unknown) => value is T
-    /**
-     * Encode one logical stream chunk.
-     *
-     * @param value - Stream chunk to encode.
-     * @returns Encoded stream bytes or text.
-     */
-    frame(value: T): MaybePromise<BodyChunk>
-    /**
-     * Optional final stream bytes emitted when the generator completes.
-     *
-     * @returns Encoded closing bytes or text.
-     */
-    close?(): MaybePromise<BodyChunk | undefined>
-}
-
-/**
- * Create an SSE stream framer.
- *
- * @example
- * ```ts
- * yield stream(sseFramer())
- * yield chunk({event: 'ready'})
- * ```
- *
- * @returns Stream framer for `text/event-stream`.
- */
-export function sseFramer(): StreamFramer<unknown> {
-    return {
-        contentType: 'text/event-stream; charset=utf-8',
-        headers: {
-            [CommonHeaders.CACHE_CONTROL]: 'no-cache',
-            [CommonHeaders.CONNECTION]: 'keep-alive',
-        },
-        frame: (value) => `data: ${JSON.stringify(value) ?? 'null'}\n\n`,
-    }
-}
-
-/**
- * Create a JSON Lines stream framer.
- *
- * @example
- * ```ts
- * yield stream(jsonLinesFramer())
- * yield chunk({event: 'ready'})
- * ```
- *
- * @returns Stream framer for `application/jsonl`.
- */
-export function jsonLinesFramer(): StreamFramer<unknown> {
-    return {
-        contentType: 'application/jsonl; charset=utf-8',
-        frame: (value) => `${JSON.stringify(value) ?? 'null'}\n`,
-    }
-}

package/src/router/response/index.ts

@@ -1,28 +0,0 @@
-export { body, isResponseBodyInit, isRoutekitBody, isRoutekitResponse, response } from './core'
-export type { RoutekitBody, RoutekitResponse, RoutekitResponseInit } from './core'
-export {
-    chunk,
-    head,
-    headers,
-    isChunkDirective,
-    isHeadersDirective,
-    isHeadDirective,
-    isRoutekitDirective,
-    isStatusDirective,
-    isStreamDirective,
-    status,
-    stream,
-} from './directives'
-export type {
-    ChunkDirective,
-    HeadDirective,
-    HeadersDirective,
-    RoutekitYield,
-    StatusDirective,
-    StreamDirective,
-} from './directives'
-export { jsonLinesFramer, sseFramer } from './framers'
-export type { StreamFramer } from './framers'
-export { defaultResponseBodySerializers, jsonResponseBodySerializer } from './serializers'
-export type { ResponseBodySerializer } from './serializers'
-export { createAsyncStream, createStartStream } from './stream'