@mpen/routekit 0.1.0

package/src/router/response/openapi.test.ts

@@ -0,0 +1,96 @@
+#!/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'
+
+describe('openapi', () => {
+    it('builds OpenAPI paths from route schemas and metadata', async () => {
+        const router = new Router()
+        router.add({
+            path: '/users/:id',
+            method: HttpMethod.GET,
+            schema: {
+                request: {
+                    path: {
+                        type: 'object',
+                        properties: {
+                            id: { type: 'string' },
+                        },
+                        required: ['id'],
+                    },
+                },
+                response: {
+                    body: {
+                        200: {
+                            type: 'object',
+                            properties: {
+                                id: { type: 'string' },
+                                email: { type: 'string', format: 'email' },
+                            },
+                            required: ['id', 'email'],
+                        },
+                    },
+                },
+            },
+            meta: {
+                openapi: {
+                    summary: 'Get user',
+                    responses: {
+                        404: { description: 'Not found' },
+                    },
+                },
+            },
+            handler: () => new Response('ok'),
+        })
+
+        router.add({
+            path: '/swagger.json',
+            method: HttpMethod.GET,
+            handler: openapi({
+                info: {
+                    title: 'Example API',
+                    version: '1.0.0',
+                    description: 'Demo API',
+                },
+                servers: [{ url: 'https://api.example.com' }],
+                components: {
+                    schemas: {
+                        User: {
+                            type: 'object',
+                            required: ['id', 'email'],
+                            properties: {
+                                id: { type: 'string' },
+                                email: { type: 'string', format: 'email' },
+                            },
+                        },
+                    },
+                },
+                security: [{ bearerAuth: [] }],
+            }),
+        })
+
+        const response = await router.fetch(new Request('https://example.com/swagger.json'))
+        const document = (await response.json()) as any
+
+        expect(document.openapi).toBe('3.0.3')
+        expect(document.info).toEqual({
+            title: 'Example API',
+            version: '1.0.0',
+            description: 'Demo API',
+        })
+        expect(document.servers).toEqual([{ url: 'https://api.example.com' }])
+        expect(document.paths['/users/{id}'].get.summary).toBe('Get user')
+        expect(document.paths['/users/{id}'].get.responses['200'].description).toBe('OK')
+        expect(document.paths['/users/{id}'].get.parameters).toEqual([
+            {
+                name: 'id',
+                in: 'path',
+                required: true,
+                schema: { type: 'string' },
+            },
+        ])
+        expect(document.components.schemas.User.properties.email.format).toBe('email')
+        expect(document.security).toEqual([{ bearerAuth: [] }])
+    })
+})

package/src/router/response/openapi.ts

@@ -0,0 +1 @@
+export * from '../handlers/openapi/openapi'

package/src/router/response/serializers.ts

@@ -0,0 +1,66 @@
+import { CommonContentTypes } from '@mpen/http'
+import type { RouterBodyInit } from '../fetch-types'
+
+type MaybePromise<T> = T | Promise<T>
+
+/**
+ * Serializer used by the router when a logical response has no explicit `Content-Type`.
+ *
+ * @example
+ * ```ts
+ * const json = jsonResponseBodySerializer()
+ * ```
+ */
+export interface ResponseBodySerializer<T = unknown> {
+    /**
+     * Media types this serializer can produce. Entries may include an Accept-style
+     * `q` parameter for server-side preference during content negotiation.
+     */
+    mediaTypes: readonly string[]
+    /**
+     * Return `true` when this serializer can encode the provided value.
+     *
+     * @param value - Logical response body to inspect.
+     * @returns Whether `value` can be serialized by this serializer.
+     */
+    canSerialize?(value: unknown): value is T
+    /**
+     * Encode a logical response body into a native Fetch response body.
+     *
+     * @param value - Logical response body to encode.
+     * @returns Native response body data.
+     */
+    serialize(value: T): MaybePromise<RouterBodyInit | null>
+}
+
+/**
+ * Create the default JSON response body serializer.
+ *
+ * @example
+ * ```ts
+ * const router = new Router().setResponseBodySerializers([jsonResponseBodySerializer()])
+ * ```
+ *
+ * @returns Serializer for `application/json`.
+ */
+export function jsonResponseBodySerializer(): ResponseBodySerializer<unknown> {
+    return {
+        mediaTypes: [CommonContentTypes.JSON],
+        canSerialize: (_value): _value is unknown => true,
+        serialize: (value) => (value === undefined ? null : JSON.stringify(value)),
+    }
+}
+
+/**
+ * Create the default response body serializer list.
+ *
+ * @example
+ * ```ts
+ * const serializers = defaultResponseBodySerializers()
+ * ```
+ *
+ * @returns Default response body serializers.
+ */
+export function defaultResponseBodySerializers(): ResponseBodySerializer[] {
+    return [jsonResponseBodySerializer()]
+}

package/src/router/response/stream.ts

@@ -0,0 +1,35 @@
+export function createStartStream<R = any>(
+    fn: (controller: ReadableStreamDefaultController<R>) => void | Promise<void>,
+) {
+    return new ReadableStream({
+        start(controller) {
+            fn(controller)
+        },
+    })
+}
+
+interface StreamWriter<R = any> {
+    write(chunk: R): void
+    // error(e?: any): void
+}
+
+export function createAsyncStream<R = any>(
+    fn: (controller: StreamWriter<R>) => void | Promise<void>,
+) {
+    return new ReadableStream({
+        start(controller) {
+            const writer: StreamWriter<R> = {
+                write: controller.enqueue.bind(controller),
+                // error: controller.error.bind(controller),
+            }
+            Promise.try(fn, writer).then(
+                () => {
+                    controller.close()
+                },
+                (err) => {
+                    controller.error(err)
+                },
+            )
+        },
+    })
+}