@getsoda/core 0.2.1 → 0.3.0

package/src/http/arguments.ts

@@ -18,7 +18,7 @@
 
 import type { FormFields, FormLimits } from './body.ts'
 import type { ContextKey } from './context-key.ts'
-import type { Context, ParamNameOf } from './context.ts'
+import type { Context, ContextParams, ParamNameOf } from './context.ts'
 import type { Parsed, ValueParser } from './parsers.ts'
 import { isStandardSchema } from './schema.ts'
 import type { InferOutput, StandardSchemaV1 } from './schema.ts'
@@ -33,6 +33,10 @@ export interface Argument<T, K extends ArgumentKind = ArgumentKind, N extends st
   /** Parameter, query, header or cookie name; the key description for `value`; empty for `body` and `context`. */
   readonly name: N
   readonly read: (ctx: Context) => T | Promise<T>
+  /** The parser or schema the value goes through, for API descriptions such as OpenAPI. */
+  readonly source?: ValueParser<unknown> | StandardSchemaV1
+  /** Set by `form()`: the body is a form, not JSON. */
+  readonly multipart?: true
 }
 
 /** Arguments accepted by a route with path `P`: `param()` names must exist in it. */
@@ -40,13 +44,27 @@ export type ArgumentFor<P extends string> =
   | Argument<unknown, 'param', ParamNameOf<P>>
   | Argument<unknown, Exclude<ArgumentKind, 'param'>>
 
-/** Values a method receives for an argument list. */
-export type ArgumentValues<A extends readonly Argument<unknown>[]> = {
-  -readonly [K in keyof A]: A[K] extends Argument<infer T> ? T : never
+declare const RAW_PARAM: unique symbol
+
+/**
+ * Value of `param(name)` without parser, typed by the route path:
+ * `string` for `:id`, `string | undefined` for `:id?`.
+ */
+export interface RawParam {
+  readonly [RAW_PARAM]: true
+}
+
+/** Values a method receives for an argument list on a route with path `P`. */
+export type ArgumentValues<A extends readonly Argument<unknown>[], P extends string = string> = {
+  -readonly [K in keyof A]: A[K] extends Argument<infer T, ArgumentKind, infer N>
+    ? [T] extends [RawParam]
+      ? ContextParams<P>[N]
+      : T
+    : never
 }
 
-/** Path parameter. Like `@Param('id', ParseIntPipe)`. */
-export function param<const N extends string>(name: N): Argument<string | undefined, 'param', N>
+/** Path parameter, typed by the route path, or by `parser`. Like `@Param('id', ParseIntPipe)`. */
+export function param<const N extends string>(name: N): Argument<RawParam, 'param', N>
 export function param<const N extends string, V extends ValueParser<unknown>>(
   name: N,
   parser: V
@@ -55,6 +73,7 @@ export function param(name: string, parser?: ValueParser<unknown>): Argument<unk
   return {
     kind: 'param',
     name,
+    source: parser,
     read: parser === undefined ? (ctx) => ctx.param(name) : (ctx) => ctx.param(name, parser),
   }
 }
@@ -66,6 +85,7 @@ export function query(name: string, parser?: ValueParser<unknown>): Argument<unk
   return {
     kind: 'query',
     name,
+    source: parser,
     read: parser === undefined ? (ctx) => ctx.query(name) : (ctx) => ctx.query(name, parser),
   }
 }
@@ -77,6 +97,7 @@ export function header(name: string, parser?: ValueParser<unknown>): Argument<un
   return {
     kind: 'header',
     name,
+    source: parser,
     read: parser === undefined ? (ctx) => ctx.header(name) : (ctx) => ctx.header(name, parser),
   }
 }
@@ -88,6 +109,7 @@ export function cookie(name: string, parser?: ValueParser<unknown>): Argument<un
   return {
     kind: 'cookie',
     name,
+    source: parser,
     read: parser === undefined ? (ctx) => ctx.cookie(name) : (ctx) => ctx.cookie(name, parser),
   }
 }
@@ -99,6 +121,7 @@ export function body(schema?: StandardSchemaV1): Argument<unknown, 'body'> {
   return {
     kind: 'body',
     name: '',
+    source: schema,
     read: schema === undefined ? (ctx) => ctx.body() : (ctx) => ctx.body(schema),
   }
 }
@@ -128,6 +151,8 @@ export function form(schemaOrLimits?: StandardSchemaV1 | FormLimits, limits?: Fo
   return {
     kind: 'body',
     name: '',
+    source: isStandardSchema(schemaOrLimits) ? schemaOrLimits : undefined,
+    multipart: true,
     read: isStandardSchema(schemaOrLimits) ? (ctx) => ctx.form(schemaOrLimits, limits) : (ctx) => ctx.form(schemaOrLimits),
   }
 }

package/src/http/cookies.ts

@@ -84,6 +84,8 @@ type Result<O extends ParserOptions> = O extends { readonly optional: true } ? s
  * forged cookie is no better than none.
  */
 export const signed = <const O extends ParserOptions = {}>(signer: CookieSigner, options?: O): Parser<Result<O>> => ({
+  jsonSchema: { type: 'string' },
+  optional: options?.optional === true,
   parse: (value, name) => {
     const unsigned = value === undefined ? undefined : signer.unsign(value)
 

package/src/http/decorators.ts

@@ -41,6 +41,8 @@ export interface RouteMetadata {
   readonly path: string
   /** Declared arguments; `undefined` when the method receives the context. */
   readonly args: readonly Argument<unknown>[] | undefined
+  /** Declared with `@Sse()`: the result is streamed as server-sent events. */
+  readonly sse: boolean
 }
 
 /**
@@ -65,18 +67,25 @@ export type RouteHandlerMethod<This, P extends string> =
 /**
  * Decorator of a route without argument list: `@Get(':id')`.
  */
-export type RouteDecorator<P extends string> = <This, M extends RouteHandlerMethod<This, P>>(
-  method: M,
+export type RouteDecorator<P extends string> = <This, M extends (this: This, ...args: any[]) => unknown>(
+  method: M extends RouteHandlerMethod<This, P> ? M : RouteHandlerHint<P>,
   context: ClassMethodDecoratorContext<This, M>
 ) => void
 
+/**
+ * What the compiler shows for a method that does not fit a route without
+ * argument list, such as `findOne(id: string)` under `@Get(':id')`.
+ */
+export type RouteHandlerHint<P extends string> =
+  `Without an argument list, the method receives the context: (ctx: Context<'${P}'>). To receive values, list them: @Get('${P}', [param('name')]).`
+
 /**
  * Decorator of a route with an argument list: `@Get(':id', [param('id', int())])`.
  * The method must accept the values of the arguments, in order.
  */
-export type ArgumentsRouteDecorator<A extends readonly Argument<unknown>[]> = <
+export type ArgumentsRouteDecorator<A extends readonly Argument<unknown>[], P extends string = string> = <
   This,
-  M extends (this: This, ...args: ArgumentValues<A>) => unknown,
+  M extends (this: This, ...args: ArgumentValues<A, P>) => unknown,
 >(
   method: M,
   context: ClassMethodDecoratorContext<This, M>
@@ -94,8 +103,8 @@ export type ArgumentsRouteDecorator<A extends readonly Argument<unknown>[]> = <
  */
 export interface RouteDecoratorFactory {
   <const P extends string = '/'>(path?: P): RouteDecorator<P>
-  <const P extends string, const A extends readonly ArgumentFor<P>[]>(path: P, args: A): ArgumentsRouteDecorator<A>
-  <const A extends readonly ArgumentFor<'/'>[]>(args: A): ArgumentsRouteDecorator<A>
+  <const P extends string, const A extends readonly ArgumentFor<P>[]>(path: P, args: A): ArgumentsRouteDecorator<A, P>
+  <const A extends readonly ArgumentFor<'/'>[]>(args: A): ArgumentsRouteDecorator<A, '/'>
 }
 
 /**
@@ -163,7 +172,7 @@ export const Controller =
 /**
  * Creates the route decorator factory of one HTTP method (any method name, extensions included).
  */
-const routeFactory = (method: string, decorator: string): RouteDecoratorFactory =>
+const routeFactory = (method: string, decorator: string, sse = false): RouteDecoratorFactory =>
   ((pathOrArgs?: string | readonly Argument<unknown>[], args?: readonly Argument<unknown>[]) =>
     (target: object, context: MethodContext) => {
       assertPublicMethod(decorator, context)
@@ -172,7 +181,7 @@ const routeFactory = (method: string, decorator: string): RouteDecoratorFactory
       const list = typeof pathOrArgs === 'string' ? args : pathOrArgs
 
       // Decorators run bottom-up: unshift keeps the source order.
-      metadataOf(target).routes.unshift({ method, path, args: list })
+      metadataOf(target).routes.unshift({ method, path, args: list, sse })
     }) as RouteDecoratorFactory
 
 /**
@@ -184,8 +193,8 @@ export interface MethodRouteDecoratorFactory {
     method: string,
     path: P,
     args: A
-  ): ArgumentsRouteDecorator<A>
-  <const A extends readonly ArgumentFor<'/'>[]>(method: string, args: A): ArgumentsRouteDecorator<A>
+  ): ArgumentsRouteDecorator<A, P>
+  <const A extends readonly ArgumentFor<'/'>[]>(method: string, args: A): ArgumentsRouteDecorator<A, '/'>
 }
 
 /**
@@ -215,6 +224,12 @@ export const Head = routeFactory('HEAD', 'Head')
 /** Route for every method; a route for a concrete method on the same path wins. */
 export const All = routeFactory('ALL', 'All')
 
+/**
+ * `GET` route streaming server-sent events: the method returns an async
+ * iterable of `SseMessage`, such as an `async function*`. Like Nest's `@Sse()`.
+ */
+export const Sse = routeFactory('GET', 'Sse', true)
+
 /**
  * Status of the responses built from the returned value (not of a returned `Response`).
  * Defaults to `201` for `POST` and `200` otherwise, as in Nest.

package/src/http/errors.ts

@@ -3,6 +3,8 @@
  * Errors raised while declaring and collecting controllers.
  */
 
+import { hideFrameworkFrames } from '../utils/errors.ts'
+
 /**
  * Reason of a `ControllerError`.
  *
@@ -11,6 +13,8 @@
  * - `INVALID_STATUS`: `@HttpCode()` with a status a `Response` cannot have, or twice on one method.
  * - `INVALID_HEADER`: `@Header()` with a name or value `Headers` rejects.
  * - `UNKNOWN_PARAM`: `param('x')` in an argument list names no parameter of the route path.
+ * - `INVALID_PATH`: a WebSocket gateway path that is not static.
+ * - `DUPLICATE_ROUTE`: a gateway on the path of another gateway or route.
  */
 export type ControllerErrorCode =
   | 'NOT_A_CONTROLLER'
@@ -18,6 +22,8 @@ export type ControllerErrorCode =
   | 'INVALID_STATUS'
   | 'INVALID_HEADER'
   | 'UNKNOWN_PARAM'
+  | 'INVALID_PATH'
+  | 'DUPLICATE_ROUTE'
 
 /**
  * Error thrown by the controller decorators (when the class is defined) and by
@@ -31,5 +37,6 @@ export class ControllerError extends Error {
     message: string
   ) {
     super(message)
+    hideFrameworkFrames(this)
   }
 }

package/src/http/index.ts

@@ -4,18 +4,21 @@
  */
 
 export { body, context, cookie, form, header, param, query, value } from './arguments.ts'
-export type { Argument, ArgumentFor, ArgumentKind, ArgumentValues } from './arguments.ts'
+export type { Argument, ArgumentFor, ArgumentKind, ArgumentValues, RawParam } from './arguments.ts'
 export { Context } from './context.ts'
 export { CookieSigner, signed } from './cookies.ts'
 export { ContextKey } from './context-key.ts'
 export type { ContextParams, ParamNameOf } from './context.ts'
-export { All, Controller, Delete, Get, Head, Header, HttpCode, Options, Patch, Post, Put, Route } from './decorators.ts'
+export { All, Controller, Delete, Get, Head, Header, HttpCode, Options, Patch, Post, Put, Route, Sse } from './decorators.ts'
+export { formatSseMessage } from './sse.ts'
+export type { SseMessage } from './sse.ts'
 export type {
   ArgumentsRouteDecorator,
   MethodMetadataDecorator,
   MethodRouteDecoratorFactory,
   RouteDecorator,
   RouteDecoratorFactory,
+  RouteHandlerHint,
   RouteHandlerMethod,
 } from './decorators.ts'
 export { ControllerError } from './errors.ts'
@@ -37,8 +40,8 @@ export {
 export type { HttpExceptionBody, HttpExceptionOptions } from './exceptions.ts'
 export { boolean, int, number, uuid } from './parsers.ts'
 export type { Parsed, Parser, ParserOptions, ValueParser } from './parsers.ts'
-export { buildRoutes, controllerRoutes } from './routes.ts'
-export type { BuiltRoutes, ControllerRoutesOptions, MappedController } from './routes.ts'
+export { buildRoutes, controllerRoutes, ROUTES } from './routes.ts'
+export type { BuiltRoutes, ControllerRoutesOptions, MappedController, MappedRoute, RouteRegistry } from './routes.ts'
 export type { InferOutput, StandardSchemaV1 } from './schema.ts'
 export type { AnyParams, PathParams } from './types.ts'
 export { Catch, createDecorator, UseFilters, UseGuards, UseInterceptors } from './enhancers.ts'

package/src/http/parsers.ts

@@ -20,6 +20,10 @@ import type { InferOutput, StandardSchemaV1 } from './schema.ts'
  */
 export interface Parser<T> {
   readonly parse: (value: string | undefined, name: string) => T
+  /** JSON Schema of the accepted strings, for API descriptions such as OpenAPI. */
+  readonly jsonSchema?: Readonly<Record<string, unknown>>
+  /** `true` when a missing value is accepted. */
+  readonly optional?: boolean
 }
 
 /** What `param()`, `query()` and `header()` accept to convert a value. */
@@ -46,8 +50,11 @@ export const failure = (name: string, expected: string): BadRequestException =>
 const createParser = <T>(
   expected: string,
   convert: (value: string) => T | undefined,
-  options: ParserOptions
+  options: ParserOptions,
+  jsonSchema: Readonly<Record<string, unknown>>
 ): Parser<T | undefined> => ({
+  jsonSchema,
+  optional: options.optional === true,
   parse: (value, name) => {
     if (value === undefined) {
       if (options.optional === true) {
@@ -79,7 +86,8 @@ export const int = <const O extends ParserOptions = {}>(options?: O): Parser<Res
 
       return Number.isSafeInteger(number) ? number : undefined
     },
-    options ?? {}
+    options ?? {},
+    { type: 'integer' }
   ) as Parser<Result<number, O>>
 
 /** Finite decimal number: `'1.5'`, `'-2'`, `'1e3'`. */
@@ -91,18 +99,21 @@ export const number = <const O extends ParserOptions = {}>(options?: O): Parser<
 
       return Number.isFinite(parsed) ? parsed : undefined
     },
-    options ?? {}
+    options ?? {},
+    { type: 'number' }
   ) as Parser<Result<number, O>>
 
 /** `'true'` or `'false'`. */
 export const boolean = <const O extends ParserOptions = {}>(options?: O): Parser<Result<boolean, O>> =>
-  createParser('boolean string', (value) => (value === 'true' ? true : value === 'false' ? false : undefined), options ?? {}) as Parser<
-    Result<boolean, O>
-  >
+  createParser('boolean string', (value) => (value === 'true' ? true : value === 'false' ? false : undefined), options ?? {}, {
+    type: 'boolean',
+  }) as Parser<Result<boolean, O>>
 
 /** UUID of any version, case-insensitive. */
 export const uuid = <const O extends ParserOptions = {}>(options?: O): Parser<Result<string, O>> =>
-  createParser('UUID string', (value) => (UUID.test(value) ? value : undefined), options ?? {}) as Parser<Result<string, O>>
+  createParser('UUID string', (value) => (UUID.test(value) ? value : undefined), options ?? {}, { type: 'string', format: 'uuid' }) as Parser<
+    Result<string, O>
+  >
 
 /**
  * Applies a parser or a synchronous Standard Schema to a raw value.

package/src/http/pipeline.ts

@@ -21,10 +21,10 @@ import { getCaughtExceptions } from './enhancers.ts'
 import type { CallHandler, CanActivate, ExceptionFilter, FilterLike, Guard, Interceptor, InterceptorLike } from './enhancers.ts'
 import { errorResponse, ForbiddenException } from './exceptions.ts'
 
-type GuardStep = (ctx: Context) => unknown
-type InterceptorStep = (ctx: Context, next: CallHandler) => unknown
+export type GuardStep = (ctx: Context) => unknown
+export type InterceptorStep = (ctx: Context, next: CallHandler) => unknown
 
-interface FilterStep {
+export interface FilterStep {
   /** Empty: catches everything. */
   readonly types: readonly ClassToken<unknown>[]
   readonly handle: (error: unknown, ctx: Context) => Response | Promise<Response>
@@ -174,7 +174,7 @@ export interface PipelineParts {
   /** In the order they are tried: method, class, global. */
   readonly filters: readonly FilterStep[]
   readonly invoke: (ctx: Context) => unknown
-  readonly respond: (value: unknown) => Response
+  readonly respond: (value: unknown, ctx: Context) => Response
   readonly onError: (error: unknown, req: Request) => void
 }
 
@@ -230,11 +230,11 @@ export const createPipeline = (parts: PipelineParts): Handler => {
 
       if (isThenable(result)) {
         return Promise.resolve(result)
-          .then(respond)
+          .then((value) => respond(value, ctx))
           .catch((error: unknown) => fail(error, ctx))
       }
 
-      return respond(result)
+      return respond(result, ctx)
     } catch (error) {
       return fail(error, ctx)
     }

package/src/http/routes.ts

@@ -11,9 +11,11 @@
  * ```
  */
 
+import { InjectionToken } from '../di/index.ts'
 import type { Constructor, Container, ControllerEntry, ModuleClass } from '../di/index.ts'
 import type { RouteDefinition } from '../routing/index.ts'
 import { parsePath } from '../routing/path.ts'
+import { methodNames } from '../utils/object.ts'
 import { isThenable } from '../utils/promise.ts'
 import type { Argument } from './arguments.ts'
 import type { Context, RouteInfo } from './context.ts'
@@ -25,6 +27,10 @@ import { ControllerError } from './errors.ts'
 import { createEnhancerResolver, createPipeline } from './pipeline.ts'
 import type { EnhancerResolver } from './pipeline.ts'
 import { createResponder } from './response.ts'
+import { createSseResponder } from './sse.ts'
+import { getGatewayPath } from '../websocket/decorators.ts'
+import { buildGateway } from '../websocket/gateway.ts'
+import type { BuiltGateway } from '../websocket/gateway.ts'
 
 /**
  * Options of `controllerRoutes`.
@@ -62,29 +68,6 @@ const joinPaths = (...parts: readonly string[]): string => {
   return path || '/'
 }
 
-/**
- * Public method names along the prototype chain, most derived first, without duplicates.
- */
-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
-}
-
 /** Every `param()` must name a parameter of the full path, controller prefix included. */
 const assertParamsExist = (args: readonly Argument<unknown>[], path: string, name: string): void => {
   const names = new Set<string>()
@@ -157,6 +140,9 @@ const resolveAll = <T, S>(
 class RoutesBuilder {
   readonly routes: RouteDefinition[] = []
   readonly controllers: MappedController[] = []
+  readonly gateways: BuiltGateway[] = []
+  /** Routes of the controller being added. */
+  #mapped: MappedRoute[] = []
   /** Guards, interceptors and filters created from classes, in creation order. */
   readonly enhancers: unknown[] = []
   readonly #options: ControllerRoutesOptions
@@ -174,6 +160,14 @@ class RoutesBuilder {
   }
 
   addController(entry: ControllerEntry): void {
+    const gatewayPath = getGatewayPath(entry.controller)
+
+    if (gatewayPath !== undefined) {
+      this.#addGateway(entry, gatewayPath)
+
+      return
+    }
+
     const controllerPath = getControllerPath(entry.controller)
 
     if (controllerPath === undefined) {
@@ -185,14 +179,32 @@ class RoutesBuilder {
 
     const basePath = joinPaths(this.#options.prefix ?? '', controllerPath)
 
-    const start = this.routes.length
+    this.#mapped = []
 
     // The most derived function: an override without route decorators has no metadata.
     for (const name of methodNames(entry.instance as object)) {
       this.#addMethod(entry, basePath, name)
     }
 
-    this.controllers.push({ controller: entry.controller, path: basePath, routes: this.routes.slice(start) })
+    this.controllers.push({ controller: entry.controller, path: basePath, routes: this.#mapped })
+  }
+
+  /** A gateway: its handshake gets the guards and filters of the class and the global ones. */
+  #addGateway(entry: ControllerEntry, gatewayPath: string): void {
+    const local = this.#resolverOf(entry)
+    const controller = getClassEnhancers(entry.controller)
+    const options = this.#options
+
+    this.gateways.push(
+      buildGateway({
+        entry,
+        path: joinPaths(options.prefix ?? '', gatewayPath),
+        guards: resolveAll([options.guards ?? [], controller.guards, []], this.#global.guard, local.guard),
+        filters: resolveAll([options.filters ?? [], controller.filters, []], this.#global.filter, local.filter).reverse(),
+        metadata: controller.metadata,
+        onError: this.#onError,
+      })
+    )
   }
 
   #resolverOf(entry: ControllerEntry): EnhancerResolver {
@@ -238,6 +250,9 @@ class RoutesBuilder {
         assertParamsExist(route.args, path, `${entry.controller.name}.${name}`)
       }
 
+      const status = statusOf(metadata, route)
+
+      this.#mapped.push({ info, args: route.args, status, sse: route.sse })
       this.routes.push({
         method: route.method,
         path,
@@ -248,7 +263,7 @@ class RoutesBuilder {
           interceptors,
           filters,
           invoke: createInvoker(instance, method, route.args),
-          respond: createResponder(statusOf(metadata, route), metadata.headers),
+          respond: route.sse ? createSseResponder(metadata.headers, this.#onError) : createResponder(status, metadata.headers),
           onError: this.#onError,
         }),
       })
@@ -256,14 +271,36 @@ class RoutesBuilder {
   }
 }
 
-/** A controller and the routes made from it, as `createApp` logs them at startup. */
+/** A route as declared: what startup logs and API descriptions (OpenAPI) show. */
+export interface MappedRoute {
+  /** Controller, method name, HTTP method, full path and custom metadata. */
+  readonly info: RouteInfo
+  /** Declared arguments; `undefined` when the method receives the context. */
+  readonly args: readonly Argument<unknown>[] | undefined
+  /** Status of the responses built from returned values. */
+  readonly status: number
+  /** Declared with `@Sse()`. */
+  readonly sse: boolean
+}
+
+/** A controller and the routes made from it. */
 export interface MappedController {
   readonly controller: Constructor<unknown>
   /** Path of the controller, with the global prefix. */
   readonly path: string
-  readonly routes: readonly RouteDefinition[]
+  readonly routes: readonly MappedRoute[]
 }
 
+/**
+ * The routes of the application, grouped by controller: `inject(ROUTES)`.
+ * Filled once the routes are built, so read it when serving, not in a constructor.
+ */
+export interface RouteRegistry {
+  readonly controllers: readonly MappedController[]
+}
+
+export const ROUTES = new InjectionToken<RouteRegistry>('ROUTES')
+
 /**
  * Routes of every controller, and the guards, interceptors and filters created
  * for them from classes (whose lifecycle hooks the application runs).
@@ -272,6 +309,8 @@ export interface BuiltRoutes {
   readonly routes: RouteDefinition[]
   /** In module order. */
   readonly controllers: readonly MappedController[]
+  /** WebSocket gateways, in module order. */
+  readonly gateways: readonly BuiltGateway[]
   /** In creation order. */
   readonly enhancers: readonly unknown[]
 }
@@ -286,7 +325,7 @@ export const buildRoutes = (container: Container, options: ControllerRoutesOptio
     builder.addController(entry)
   }
 
-  return { routes: builder.routes, controllers: builder.controllers, enhancers: builder.enhancers }
+  return { routes: builder.routes, controllers: builder.controllers, gateways: builder.gateways, enhancers: builder.enhancers }
 }
 
 /**

package/src/http/schema.ts

@@ -67,7 +67,8 @@ const OMITTED = 'Further validation errors were omitted'
 export const isStandardSchema = (value: unknown): value is StandardSchemaV1 =>
   typeof value === 'object' && value !== null && '~standard' in value
 
-const formatIssues = (issues: readonly StandardSchemaV1.Issue[], prefix: string): string[] => {
+/** Messages of `issues`, each with the path of its value under `prefix`. */
+export const formatIssues = (issues: readonly StandardSchemaV1.Issue[], prefix: string): string[] => {
   const messages: string[] = []
   let remaining = MAX_MESSAGES_LENGTH