@getsoda/core 0.2.1 → 0.3.0

package/src/http/sse.ts

@@ -0,0 +1,120 @@
+/**
+ * @module
+ * Server-sent events: a route decorated with `@Sse()` returns an async
+ * iterable of messages, streamed as `text/event-stream`, as Nest's `@Sse()`
+ * streams an observable.
+ *
+ * ```ts
+ * @Sse('ticks')
+ * async *ticks(): AsyncGenerator<SseMessage> {
+ *   for (let i = 0; ; i++) {
+ *     yield { data: { tick: i } }
+ *     await Bun.sleep(1000)
+ *   }
+ * }
+ * ```
+ *
+ * When the client disconnects, the iterator is returned: a generator runs its
+ * `finally` blocks. An error thrown while streaming ends the stream and is logged.
+ */
+
+import type { Context } from './context.ts'
+
+/** One event. Fields are those of the `EventSource` protocol. */
+export interface SseMessage {
+  /** A string is sent as is, anything else as JSON. */
+  readonly data: unknown
+  /** Event name, listened to with `source.addEventListener(event, ...)`. */
+  readonly event?: string
+  /** Sent back by the browser as `Last-Event-ID` when it reconnects. */
+  readonly id?: string
+  /** Milliseconds the browser waits before reconnecting. */
+  readonly retry?: number
+}
+
+/** Headers of Nest's SSE responses: no caching, no buffering by nginx. */
+const SSE_HEADERS: readonly [string, string][] = [
+  ['content-type', 'text/event-stream'],
+  ['cache-control', 'private, no-cache, no-store, must-revalidate, max-age=0, no-transform'],
+  ['x-accel-buffering', 'no'],
+]
+
+const NEWLINE = /\r\n|\r|\n/
+const encoder = new TextEncoder()
+
+const assertSingleLine = (name: string, value: string): void => {
+  if (NEWLINE.test(value)) {
+    throw new TypeError(`SSE ${name} must not contain line breaks: ${JSON.stringify(value)}`)
+  }
+}
+
+/** A message in the event stream format, one `data:` line per line of data. */
+export const formatSseMessage = (message: SseMessage): string => {
+  const data = typeof message.data === 'string' ? message.data : JSON.stringify(message.data)
+  let text = ''
+
+  if (message.event !== undefined) {
+    assertSingleLine('event', message.event)
+    text += `event: ${message.event}\n`
+  }
+
+  if (message.id !== undefined) {
+    assertSingleLine('id', message.id)
+    text += `id: ${message.id}\n`
+  }
+
+  if (message.retry !== undefined) {
+    text += `retry: ${Math.trunc(message.retry)}\n`
+  }
+
+  for (const line of (data ?? '').split(NEWLINE)) {
+    text += `data: ${line}\n`
+  }
+
+  return `${text}\n`
+}
+
+const isAsyncIterable = (value: unknown): value is AsyncIterable<SseMessage> =>
+  typeof value === 'object' && value !== null && Symbol.asyncIterator in value
+
+/**
+ * Creates the function streaming what an `@Sse()` route returns. `headers`
+ * come from `@Header()`; errors while streaming go to `onError`.
+ */
+export const createSseResponder = (
+  headers: readonly [string, string][],
+  onError: (error: unknown, req: Request) => void
+): ((value: unknown, ctx: Context) => Response) => {
+  const init: ResponseInit = { status: 200, headers: [...SSE_HEADERS, ...headers] }
+
+  return (value, ctx) => {
+    if (!isAsyncIterable(value)) {
+      throw new TypeError(`${ctx.route.controller.name}.${ctx.route.handler} is an @Sse() route: it must return an async iterable`)
+    }
+
+    const iterator = value[Symbol.asyncIterator]()
+
+    const body = new ReadableStream<Uint8Array>({
+      async pull(controller) {
+        try {
+          const next = await iterator.next()
+
+          if (next.done === true) {
+            controller.close()
+          } else {
+            controller.enqueue(encoder.encode(formatSseMessage(next.value)))
+          }
+        } catch (error) {
+          onError(error, ctx.req)
+          controller.close()
+        }
+      },
+      // The client went away: let the source clean up.
+      async cancel() {
+        await iterator.return?.()
+      },
+    })
+
+    return new Response(body, init)
+  }
+}

package/src/index.ts

@@ -32,7 +32,9 @@
  */
 
 export * from './app/index.ts'
+export * from './config/index.ts'
 export * from './di/index.ts'
 export * from './http/index.ts'
 export * from './logger/index.ts'
 export * from './routing/index.ts'
+export * from './websocket/index.ts'

package/src/openapi/decorators.ts

@@ -0,0 +1,50 @@
+/**
+ * @module
+ * Decorators describing routes in the OpenAPI document, as `@nestjs/swagger` does.
+ */
+
+import { createDecorator } from '../http/enhancers.ts'
+import type { ClassOrMethodDecorator } from '../http/enhancers.ts'
+import type { StandardSchemaV1 } from '../http/schema.ts'
+
+export interface ApiOperationOptions {
+  readonly summary?: string
+  readonly description?: string
+  readonly deprecated?: boolean
+}
+
+export interface ApiResponseOptions {
+  readonly description: string
+  /** Schema of the JSON body; needs a library implementing Standard JSON Schema, such as zod. */
+  readonly schema?: StandardSchemaV1
+}
+
+const operation = createDecorator<ApiOperationOptions>('ApiOperation')
+const tags = createDecorator<readonly string[]>('ApiTags')
+const responses = createDecorator<Readonly<Record<number, ApiResponseOptions>>>('ApiResponses')
+const bearer = createDecorator<boolean>('ApiBearerAuth')
+const exclude = createDecorator<boolean>('ApiExclude')
+
+/** Summary, description and deprecation of an operation. */
+export const ApiOperation = (options: ApiOperationOptions): ClassOrMethodDecorator => operation(options)
+
+/** Tags grouping operations, on a controller or a method (which wins). */
+export const ApiTags = (...names: string[]): ClassOrMethodDecorator => tags(names)
+
+/**
+ * Responses of an operation, by status. Without it, the operation has the
+ * status of its route (`200`, `201` for `POST`, or `@HttpCode()`).
+ *
+ * ```ts
+ * @ApiResponses({ 200: { description: 'The user', schema: User }, 404: { description: 'No such user' } })
+ * ```
+ */
+export const ApiResponses = (byStatus: Readonly<Record<number, ApiResponseOptions>>): ClassOrMethodDecorator => responses(byStatus)
+
+/** Operations need `Authorization: Bearer <token>`, as `JwtGuard` reads. */
+export const ApiBearerAuth = (): ClassOrMethodDecorator => bearer(true)
+
+/** Leaves a controller or a method out of the document. */
+export const ApiExclude = (): ClassOrMethodDecorator => exclude(true)
+
+export const KEYS = { operation: operation.key, tags: tags.key, responses: responses.key, bearer: bearer.key, exclude: exclude.key } as const

package/src/openapi/document.ts

@@ -0,0 +1,221 @@
+/**
+ * @module
+ * Building an OpenAPI 3.1 document from the routes of an application.
+ *
+ * Schemas come from what validates requests: argument parsers (`int()`,
+ * `uuid()`...) and Standard Schemas implementing Standard JSON Schema, as zod
+ * does. Paths with optional parameters give one path per form, as OpenAPI has
+ * no optional path parameters; `@All()` routes are left out, OpenAPI has no
+ * such method.
+ */
+
+import type { Argument } from '../http/arguments.ts'
+import type { Parser } from '../http/parsers.ts'
+import type { MappedController, MappedRoute } from '../http/routes.ts'
+import { isStandardSchema } from '../http/schema.ts'
+import type { StandardSchemaV1 } from '../http/schema.ts'
+import { expandOptional, parsePath } from '../routing/path.ts'
+import type { Segment } from '../routing/path.ts'
+import { KEYS } from './decorators.ts'
+import type { ApiOperationOptions, ApiResponseOptions } from './decorators.ts'
+
+export type JsonSchema = Readonly<Record<string, unknown>>
+
+export interface OpenApiOptions {
+  readonly info: { readonly title: string; readonly version: string; readonly description?: string }
+  readonly servers?: readonly { readonly url: string; readonly description?: string }[]
+}
+
+export interface OpenApiParameter {
+  readonly name: string
+  readonly in: 'path' | 'query' | 'header' | 'cookie'
+  readonly required: boolean
+  readonly schema: JsonSchema
+}
+
+export interface OpenApiOperation {
+  readonly operationId: string
+  readonly summary?: string
+  readonly description?: string
+  readonly deprecated?: boolean
+  readonly tags?: readonly string[]
+  readonly parameters?: readonly OpenApiParameter[]
+  readonly requestBody?: { readonly required: boolean; readonly content: Readonly<Record<string, { readonly schema: JsonSchema }>> }
+  readonly responses: Readonly<Record<string, { readonly description: string; readonly content?: Readonly<Record<string, { readonly schema: JsonSchema }>> }>>
+  readonly security?: readonly Readonly<Record<string, readonly string[]>>[]
+}
+
+export interface OpenApiDocument {
+  readonly openapi: '3.1.0'
+  readonly info: OpenApiOptions['info']
+  readonly servers?: OpenApiOptions['servers']
+  readonly paths: Readonly<Record<string, Readonly<Record<string, OpenApiOperation>>>>
+  readonly components?: { readonly securitySchemes: Readonly<Record<string, JsonSchema>> }
+}
+
+const METHODS = new Set(['GET', 'PUT', 'POST', 'DELETE', 'OPTIONS', 'HEAD', 'PATCH', 'TRACE'])
+const IN = { query: 'query', header: 'header', cookie: 'cookie' } as const
+const STRING: JsonSchema = { type: 'string' }
+const FORM_TYPES = ['multipart/form-data', 'application/x-www-form-urlencoded']
+
+/** Standard JSON Schema: the part of `~standard` a schema library may add. */
+interface WithJsonSchema {
+  readonly '~standard': { readonly jsonSchema?: { readonly input: (options: { readonly target: string }) => Record<string, unknown> } }
+}
+
+/** JSON Schema of what a parser or schema accepts, `{}` when it cannot tell. */
+const toJsonSchema = (source: Argument<unknown>['source']): JsonSchema => {
+  if (source === undefined) {
+    return STRING
+  }
+
+  if (!isStandardSchema(source)) {
+    return (source as Parser<unknown>).jsonSchema ?? STRING
+  }
+
+  const converter = (source as WithJsonSchema)['~standard'].jsonSchema
+
+  if (converter === undefined) {
+    return {}
+  }
+
+  const { $schema: _, ...schema } = converter.input({ target: 'draft-2020-12' })
+
+  return schema
+}
+
+/** A value may be missing when its parser says so, or its schema accepts `undefined`. */
+const isOptional = (source: Argument<unknown>['source']): boolean => {
+  if (source === undefined) {
+    return true
+  }
+
+  if (!isStandardSchema(source)) {
+    return (source as Parser<unknown>).optional === true
+  }
+
+  const result = (source as StandardSchemaV1)['~standard'].validate(undefined)
+
+  return !(result instanceof Promise) && result.issues === undefined
+}
+
+const toOpenApiPath = (segments: readonly Segment[]): string =>
+  `/${segments
+    .map((segment) =>
+      segment.type === 'static' ? decodeURIComponent(segment.value) : `{${segment.type === 'param' ? segment.name : (segment.name ?? 'wildcard')}}`
+    )
+    .join('/')}`
+
+const pathParameters = (segments: readonly Segment[], args: readonly Argument<unknown>[]): OpenApiParameter[] => {
+  const parameters: OpenApiParameter[] = []
+
+  for (const segment of segments) {
+    if (segment.type === 'static') {
+      continue
+    }
+
+    const name = segment.type === 'param' ? segment.name : (segment.name ?? 'wildcard')
+    const declared = args.find((arg) => arg.kind === 'param' && arg.name === name)
+    const pattern = segment.type === 'param' && segment.pattern !== undefined ? { pattern: `^(?:${segment.pattern})$` } : {}
+
+    parameters.push({ name, in: 'path', required: true, schema: { ...toJsonSchema(declared?.source), ...pattern } })
+  }
+
+  return parameters
+}
+
+const requestBody = (args: readonly Argument<unknown>[]): OpenApiOperation['requestBody'] => {
+  const body = args.find((arg) => arg.kind === 'body')
+
+  if (body === undefined) {
+    return undefined
+  }
+
+  const schema = body.source === undefined ? {} : toJsonSchema(body.source)
+  const types = body.multipart === true ? FORM_TYPES : ['application/json']
+
+  return { required: !isOptional(body.source), content: Object.fromEntries(types.map((type) => [type, { schema }])) }
+}
+
+const responsesOf = (route: MappedRoute): OpenApiOperation['responses'] => {
+  const declared = route.info.metadata.get(KEYS.responses) as Readonly<Record<number, ApiResponseOptions>> | undefined
+
+  if (declared === undefined) {
+    return route.sse
+      ? { 200: { description: 'Event stream', content: { 'text/event-stream': { schema: STRING } } } }
+      : { [route.status]: { description: 'Success' } }
+  }
+
+  return Object.fromEntries(
+    Object.entries(declared).map(([status, response]) => [
+      status,
+      response.schema === undefined
+        ? { description: response.description }
+        : { description: response.description, content: { 'application/json': { schema: toJsonSchema(response.schema) } } },
+    ])
+  )
+}
+
+const operationOf = (route: MappedRoute, segments: readonly Segment[], suffix: string): OpenApiOperation => {
+  const { info } = route
+  const args = route.args ?? []
+  const parameters = pathParameters(segments, args)
+
+  for (const arg of args) {
+    if (arg.kind === 'query' || arg.kind === 'header' || arg.kind === 'cookie') {
+      parameters.push({ name: arg.name, in: IN[arg.kind], required: !isOptional(arg.source), schema: toJsonSchema(arg.source) })
+    }
+  }
+
+  const options = (info.metadata.get(KEYS.operation) as ApiOperationOptions | undefined) ?? {}
+  const tags = info.metadata.get(KEYS.tags) as readonly string[] | undefined
+  const body = requestBody(args)
+
+  return {
+    operationId: `${info.controller.name}_${info.handler}${suffix}`,
+    ...options,
+    ...(tags === undefined ? {} : { tags }),
+    ...(parameters.length === 0 ? {} : { parameters }),
+    ...(body === undefined ? {} : { requestBody: body }),
+    responses: responsesOf(route),
+    ...(info.metadata.get(KEYS.bearer) === true ? { security: [{ bearer: [] }] } : {}),
+  }
+}
+
+/** Adds the operations of `route` to `paths`, one per form of its path; `false` when it is left out. */
+const addRoute = (paths: Record<string, Record<string, OpenApiOperation>>, route: MappedRoute): boolean => {
+  const { info } = route
+
+  if (!METHODS.has(info.method) || info.metadata.get(KEYS.exclude) === true) {
+    return false
+  }
+
+  for (const [index, segments] of expandOptional(info.path, parsePath(info.path)).entries()) {
+    const path = toOpenApiPath(segments)
+
+    paths[path] ??= {}
+    paths[path][info.method.toLowerCase()] = operationOf(route, segments, index === 0 ? '' : `_${index}`)
+  }
+
+  return true
+}
+
+/** The OpenAPI document of `controllers`, as `inject(ROUTES).controllers` lists them. */
+export const createOpenApiDocument = (controllers: readonly MappedController[], options: OpenApiOptions): OpenApiDocument => {
+  const paths: Record<string, Record<string, OpenApiOperation>> = {}
+  let bearer = false
+
+  for (const controller of controllers) {
+    for (const route of controller.routes) {
+      bearer = (addRoute(paths, route) && route.info.metadata.get(KEYS.bearer) === true) || bearer
+    }
+  }
+
+  return {
+    openapi: '3.1.0',
+    info: options.info,
+    ...(options.servers === undefined ? {} : { servers: options.servers }),
+    paths,
+    ...(bearer ? { components: { securitySchemes: { bearer: { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' } } } } : {}),
+  }
+}

package/src/openapi/index.ts

@@ -0,0 +1,11 @@
+/**
+ * @module
+ * OpenAPI documents of an application, and a Swagger UI page, as `@nestjs/swagger`.
+ */
+
+export { ApiBearerAuth, ApiExclude, ApiOperation, ApiResponses, ApiTags } from './decorators.ts'
+export type { ApiOperationOptions, ApiResponseOptions } from './decorators.ts'
+export { createOpenApiDocument } from './document.ts'
+export type { JsonSchema, OpenApiDocument, OpenApiOperation, OpenApiOptions, OpenApiParameter } from './document.ts'
+export { OpenApiModule } from './module.ts'
+export type { OpenApiModuleOptions } from './module.ts'

package/src/openapi/module.ts

@@ -0,0 +1,95 @@
+/**
+ * @module
+ * `OpenApiModule`: serves the OpenAPI document of the application, and a
+ * Swagger UI page, as `SwaggerModule.setup()` of `@nestjs/swagger` does.
+ */
+
+import { inject, Module } from '../di/index.ts'
+import type { DynamicModule } from '../di/index.ts'
+import { Controller, Get } from '../http/decorators.ts'
+import { ROUTES } from '../http/routes.ts'
+import { ApiExclude } from './decorators.ts'
+import { createOpenApiDocument } from './document.ts'
+import type { OpenApiDocument, OpenApiOptions } from './document.ts'
+
+export interface OpenApiModuleOptions extends OpenApiOptions {
+  /** Path of the JSON document. Defaults to `/openapi.json`. */
+  readonly path?: string
+  /** Path of a Swagger UI page reading the document, such as `/docs`. None by default. */
+  readonly ui?: string
+}
+
+/** Swagger UI, from a CDN at a fixed version. */
+const SWAGGER_UI = 'https://cdn.jsdelivr.net/npm/swagger-ui-dist@5.34.0'
+
+const page = (title: string, documentUrl: string): string => `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${Bun.escapeHTML(title)}</title>
+<link rel="stylesheet" href="${SWAGGER_UI}/swagger-ui.css">
+</head>
+<body>
+<div id="docs"></div>
+<script src="${SWAGGER_UI}/swagger-ui-bundle.js" crossorigin></script>
+<script>SwaggerUIBundle({ url: ${JSON.stringify(documentUrl)}, dom_id: '#docs' })</script>
+</body>
+</html>
+`
+
+/**
+ * ```ts
+ * @Module({ imports: [OpenApiModule.forRoot({ info: { title: 'Shop', version: '1.0.0' }, ui: '/docs' })] })
+ * class AppModule {}
+ * ```
+ *
+ * The document is built on the first request, from every route of the
+ * application (these two excepted), and kept.
+ */
+@Module({})
+export class OpenApiModule {
+  static forRoot(options: OpenApiModuleOptions): DynamicModule {
+    const documentPath = options.path ?? '/openapi.json'
+
+    @Controller()
+    @ApiExclude()
+    class OpenApiController {
+      readonly #routes = inject(ROUTES)
+      #document: OpenApiDocument | undefined
+
+      @Get(documentPath)
+      document(): OpenApiDocument {
+        this.#document ??= createOpenApiDocument(this.#routes.controllers, options)
+
+        return this.#document
+      }
+    }
+
+    const controllers: (new () => unknown)[] = [OpenApiController]
+
+    if (options.ui !== undefined) {
+      const ui = options.ui
+
+      @Controller()
+      @ApiExclude()
+      class OpenApiUiController {
+        readonly #routes = inject(ROUTES)
+
+        @Get(ui)
+        page(): Response {
+          // The document's own path, global prefix included.
+          const documentUrl = this.#routes.controllers.find((mapped) => mapped.controller === OpenApiController)?.routes[0]?.info.path
+
+          return new Response(page(options.info.title, documentUrl ?? documentPath), {
+            headers: { 'content-type': 'text/html;charset=utf-8' },
+          })
+        }
+      }
+
+      controllers.push(OpenApiUiController)
+    }
+
+    return { module: OpenApiModule, controllers }
+  }
+}

package/src/routing/errors.ts

@@ -3,6 +3,8 @@
  * Errors raised by the route compiler.
  */
 
+import { hideFrameworkFrames } from '../utils/errors.ts'
+
 /**
  * Reason of a `RouteError`.
  *
@@ -26,5 +28,6 @@ export class RouteError extends Error {
     message: string
   ) {
     super(message)
+    hideFrameworkFrames(this)
   }
 }

package/src/testing/index.ts

@@ -0,0 +1,73 @@
+/**
+ * @module
+ * Testing an application over HTTP, as Nest's `Test.createTestingModule()`
+ * with supertest does, on a real Bun server bound to a free port.
+ *
+ * ```ts
+ * import { createTestApp } from '@getsoda/core/testing'
+ *
+ * const app = await createTestApp(AppModule, {
+ *   overrides: [provide(UsersRepository, { useValue: new MemoryUsersRepository() })],
+ * })
+ *
+ * afterAll(() => app.close())
+ *
+ * test('creates a user', async () => {
+ *   const response = await app.request('/users', { method: 'POST', json: { name: 'Bo' } })
+ *
+ *   expect(response.status).toBe(201)
+ * })
+ * ```
+ *
+ * A single service needs no server: `createContainer(Module, { overrides })`.
+ */
+
+import { createApp } from '../app/app.ts'
+import type { App, AppOptions } from '../app/app.ts'
+import type { ModuleImport, Token } from '../di/index.ts'
+
+export interface TestRequestInit extends RequestInit {
+  /** Sent as the JSON body, with `Content-Type: application/json`. */
+  readonly json?: unknown
+}
+
+/** A started application, closed by `close()` or at the end of an `await using` block. */
+export interface TestApp extends AsyncDisposable {
+  readonly app: App
+  /** Where the application listens, on a free port of localhost. */
+  readonly url: URL
+  /** `app.container.get()`: a provider as the root module sees it. */
+  get<T>(token: Token<T>): T
+  /** Sends a request to `path`, relative to the application. */
+  request(path: string, init?: TestRequestInit): Promise<Response>
+  close(): Promise<void>
+}
+
+/**
+ * Creates `root` and serves it on a free port. Options are those of
+ * `createApp`: `overrides` replace providers; the logger is silent unless one is given.
+ */
+export const createTestApp = async (root: ModuleImport, options: AppOptions = {}): Promise<TestApp> => {
+  const app = await createApp(root, { logger: false, ...options })
+  const server = await app.listen({ port: 0, hostname: '127.0.0.1' })
+  const close = () => app.close()
+
+  return {
+    app,
+    url: server.url,
+    get: (token) => app.container.get(token),
+    request: (path, { json, ...init } = {}) => {
+      if (json === undefined) {
+        return fetch(new URL(path, server.url), init)
+      }
+
+      const headers = new Headers(init.headers)
+
+      headers.set('content-type', 'application/json')
+
+      return fetch(new URL(path, server.url), { ...init, headers, body: JSON.stringify(json) })
+    },
+    close,
+    [Symbol.asyncDispose]: close,
+  }
+}

package/src/utils/errors.ts

@@ -0,0 +1,25 @@
+/**
+ * @module
+ * Error utilities.
+ */
+
+import { fileURLToPath } from 'node:url'
+
+/** Where the framework's own files are: `src/` from sources, `dist/` once built. */
+const FRAMEWORK = fileURLToPath(new URL('../', import.meta.url))
+
+/**
+ * Removes the frames of the framework from the stack of an error about the
+ * application's code (a missing provider, an invalid route): the runtime then
+ * points at the application, not at the framework, and the message says the rest.
+ */
+export const hideFrameworkFrames = (error: Error): void => {
+  if (error.stack === undefined) {
+    return
+  }
+
+  error.stack = error.stack
+    .split('\n')
+    .filter((line) => !(line.trimStart().startsWith('at ') && line.includes(FRAMEWORK)))
+    .join('\n')
+}

package/src/utils/object.ts

@@ -12,3 +12,26 @@
  * ```
  */
 export const createNullObject = <T extends object>(): T => Object.create(null) as T
+
+/**
+ * Public method names along the prototype chain, most derived first, without duplicates.
+ */
+export const methodNames = (instance: object): string[] => {
+  const names: string[] = []
+  const seen = new Set<string>(['constructor'])
+
+  for (
+    let prototype: object | null = Object.getPrototypeOf(instance);
+    prototype !== null && prototype !== Object.prototype;
+    prototype = Object.getPrototypeOf(prototype)
+  ) {
+    for (const name of Object.getOwnPropertyNames(prototype)) {
+      if (!seen.has(name)) {
+        seen.add(name)
+        names.push(name)
+      }
+    }
+  }
+
+  return names
+}