@ailura/nestjs-hono-adapter 1.0.0

package/src/query.ts

@@ -0,0 +1,304 @@
+/**
+ * A query string parsed into the shape a controller receives:
+ * every leaf is a string, and a name that appears more than
+ * once or uses brackets becomes a list or a nested object.
+ */
+type ParsedQuery = Record<string, unknown>;
+
+/**
+ * Names that reach the prototype chain. A parser that writes
+ * them hands a caller control over every object in the process,
+ * so they are dropped instead.
+ */
+const FORBIDDEN_NAMES = new Set([
+  '__proto__',
+  'constructor',
+  'prototype',
+]);
+
+const INDEX = /^\d+$/u;
+const BRACKETS = /\[(?<name>[^\]]*)\]/gu;
+const MISSING = -1;
+
+/** One assignment: the names still to walk and the value. */
+interface Target {
+  readonly names: readonly string[];
+  readonly value: string;
+}
+
+function isRecord(
+  value: unknown,
+): value is Record<string, unknown> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    !Array.isArray(value)
+  );
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  if (isRecord(value)) {
+    return value;
+  }
+  return {};
+}
+
+function asList(value: unknown): unknown[] {
+  if (Array.isArray(value)) {
+    return value;
+  }
+  return [];
+}
+
+/**
+ * Says whether the next segment builds a list: `[]` appends,
+ * and a number indexes.
+ */
+function isListStep(name: string): boolean {
+  return name === '' || INDEX.test(name);
+}
+
+/**
+ * Decodes one side of a pair. A sequence that is not valid
+ * percent-encoding is kept as it arrived, which is what the
+ * platform parsers do rather than refusing the request.
+ */
+function decode(value: string): string {
+  const spaced = value.replaceAll('+', ' ');
+  try {
+    return decodeURIComponent(spaced);
+  } catch {
+    return spaced;
+  }
+}
+
+/**
+ * Splits `filter[name][]` into `['filter', 'name', '']`. A name
+ * without brackets is its own single segment.
+ */
+function toNames(name: string): string[] {
+  const first = name.indexOf('[');
+  if (first === MISSING) {
+    return [name];
+  }
+  const names = [name.slice(0, first)];
+  for (const match of name.slice(first).matchAll(BRACKETS)) {
+    const groups = match.groups ?? {};
+    names.push(groups.name ?? '');
+  }
+  return names;
+}
+
+/**
+ * Adds a value to a name that may already hold one. The second
+ * value turns the entry into a list, which is how a repeated
+ * name is read.
+ */
+function repeated(current: unknown, value: string): unknown {
+  if (current === undefined) {
+    return value;
+  }
+  if (Array.isArray(current)) {
+    current.push(value);
+    return current;
+  }
+  return [current, value];
+}
+
+function sidesOf(pair: string): readonly [string, string] {
+  const separator = pair.indexOf('=');
+  if (separator === MISSING) {
+    return [pair, ''];
+  }
+  return [pair.slice(0, separator), pair.slice(separator + 1)];
+}
+
+function withoutQuestionMark(source: string): string {
+  if (source.startsWith('?')) {
+    return source.slice(1);
+  }
+  return source;
+}
+
+function accepts(names: readonly string[]): boolean {
+  if (names.length === 0) {
+    return false;
+  }
+  return !names.some((segment) => FORBIDDEN_NAMES.has(segment));
+}
+
+/**
+ * Builds the tree one pair at a time.
+ *
+ * A step whose next name is `[]` or a number builds a list, and
+ * every other step builds an object; the methods below are
+ * split along that decision so each one stays readable on its
+ * own.
+ */
+class QueryBuilder {
+  private readonly query: ParsedQuery = {};
+
+  public parse(source: string): ParsedQuery {
+    for (const pair of withoutQuestionMark(source).split('&')) {
+      this.addPair(pair);
+    }
+    return this.query;
+  }
+
+  private addPair(pair: string): void {
+    if (pair === '') {
+      return;
+    }
+    const [name, value] = sidesOf(pair);
+    const names = toNames(decode(name));
+    if (!accepts(names)) {
+      return;
+    }
+    this.assign(this.query, { names, value: decode(value) });
+  }
+
+  private assign(
+    container: Record<string, unknown>,
+    target: Target,
+  ): void {
+    const [name, ...rest] = target.names;
+    if (name === undefined) {
+      return;
+    }
+    if (rest.length === 0) {
+      container[name] = repeated(container[name], target.value);
+      return;
+    }
+    this.assignDeeper(container, name, {
+      names: rest,
+      value: target.value,
+    });
+  }
+
+  private assignDeeper(
+    container: Record<string, unknown>,
+    name: string,
+    target: Target,
+  ): void {
+    const [next] = target.names;
+    if (isListStep(next ?? '')) {
+      this.assignList(container, name, target);
+      return;
+    }
+    this.assignRecord(container, name, target);
+  }
+
+  private assignList(
+    container: Record<string, unknown>,
+    name: string,
+    target: Target,
+  ): void {
+    const list = asList(container[name]);
+    container[name] = list;
+    this.intoList(list, target);
+  }
+
+  private assignRecord(
+    container: Record<string, unknown>,
+    name: string,
+    target: Target,
+  ): void {
+    const existing = container[name];
+    if (Array.isArray(existing)) {
+      const nested: Record<string, unknown> = {};
+      existing.push(nested);
+      this.assign(nested, target);
+      return;
+    }
+    container[name] = this.toRecord(existing, target);
+  }
+
+  private intoList(list: unknown[], target: Target): void {
+    const [name, ...rest] = target.names;
+    if (name === undefined) {
+      return;
+    }
+    const nested = { names: rest, value: target.value };
+    if (name === '') {
+      this.addElement(list, nested);
+      return;
+    }
+    this.addIndex(list, name, nested);
+  }
+
+  private addIndex(
+    list: unknown[],
+    name: string,
+    target: Target,
+  ): void {
+    const index = Number(name);
+    if (!Number.isSafeInteger(index) || index < 0) {
+      return;
+    }
+    this.addAt(list, index, target);
+  }
+
+  private addElement(list: unknown[], target: Target): void {
+    const [next] = target.names;
+    if (next === undefined) {
+      list.push(target.value);
+      return;
+    }
+    if (isListStep(next)) {
+      const nested: unknown[] = [];
+      list.push(nested);
+      this.intoList(nested, target);
+      return;
+    }
+    list.push(this.toRecord(undefined, target));
+  }
+
+  private addAt(
+    list: unknown[],
+    index: number,
+    target: Target,
+  ): void {
+    const existing = list[index];
+    if (target.names.length === 0) {
+      list[index] = repeated(existing, target.value);
+      return;
+    }
+    const [next] = target.names;
+    if (isListStep(next ?? '')) {
+      list[index] = this.toList(existing, target);
+      return;
+    }
+    list[index] = this.toRecord(existing, target);
+  }
+
+  private toList(existing: unknown, target: Target): unknown[] {
+    const nested = asList(existing);
+    this.intoList(nested, target);
+    return nested;
+  }
+
+  private toRecord(
+    existing: unknown,
+    target: Target,
+  ): Record<string, unknown> {
+    const nested = asRecord(existing);
+    this.assign(nested, target);
+    return nested;
+  }
+}
+
+/**
+ * Parses a query string, with or without its leading `?`.
+ *
+ * Repeated names become lists, `name[]` appends, `name[0]`
+ * indexes and `name[child]` nests; anything else is a string.
+ * The grammar is the one the platform parsers accept, which is
+ * what a controller written against Express or Fastify expects
+ * to read.
+ */
+function parseQuery(source: string): ParsedQuery {
+  return new QueryBuilder().parse(source);
+}
+
+export { parseQuery };
+export type { ParsedQuery };

package/src/response-helpers.ts

@@ -0,0 +1,60 @@
+import type { NestContext } from './context.ts';
+
+/** The Hono helpers that write the answer for a request. */
+const RESPONSE_HELPERS = [
+  'body',
+  'html',
+  'json',
+  'newResponse',
+  'notFound',
+  'redirect',
+  'text',
+] as const;
+
+type ResponseHelper = (...args: never[]) => Response;
+
+type ResponseHelperCarrier = Record<
+  (typeof RESPONSE_HELPERS)[number],
+  ResponseHelper
+>;
+
+/**
+ * Wraps one helper so that the response it built becomes the
+ * response of the context.
+ */
+function wrapHelper(
+  carrier: ResponseHelperCarrier,
+  name: (typeof RESPONSE_HELPERS)[number],
+  context: NestContext,
+): void {
+  const helper = carrier[name];
+  if (typeof helper !== 'function') {
+    return;
+  }
+  carrier[name] = (...args: never[]): Response => {
+    const response = helper.apply(context, args);
+    context.res = response;
+    return response;
+  };
+}
+
+/**
+ * Makes the Hono response helpers finalize the context.
+ *
+ * A handler that answers through `@Res()` calls one of these
+ * helpers instead of returning a value, and Nest then skips its
+ * own reply path. Hono only finalizes a context when `res` is
+ * assigned, and the helpers do not assign it, so the answer
+ * would be dropped and the client would read an empty response.
+ * Wrapping them on the instance — Hono's helpers are own
+ * properties, not prototype methods — keeps the imperative
+ * style working without taking the response away from Hono.
+ */
+function finalizeOnResponse(context: NestContext): void {
+  const carrier = context as unknown as ResponseHelperCarrier;
+  for (const name of RESPONSE_HELPERS) {
+    wrapHelper(carrier, name, context);
+  }
+}
+
+export { finalizeOnResponse };

package/src/response-writer.ts

@@ -0,0 +1,100 @@
+import { HttpStatus } from '@nestjs/common';
+
+import { buildResponse } from './bridge.ts';
+import type { NestContext } from './context.ts';
+
+/**
+ * Writes what Nest answers onto the context of the request.
+ *
+ * A Hono context doubles as the response object, so a value is
+ * turned into a Web response and stored on it. A status set
+ * through `@HttpCode()` or `@Res()` is remembered per request,
+ * because the adapter is asked for it after the handler ran.
+ */
+class ResponseWriter {
+  private readonly pendingStatus = new WeakMap<
+    NestContext,
+    number
+  >();
+
+  public status(
+    response: NestContext,
+    statusCode: number,
+  ): void {
+    this.pendingStatus.set(response, statusCode);
+  }
+
+  /**
+   * The status Nest asked for, before any body was written. An
+   * event stream needs it while the handler still runs.
+   */
+  public statusOf(response: NestContext): number | undefined {
+    return this.pendingStatus.get(response);
+  }
+
+  public reply(
+    response: NestContext,
+    body: unknown,
+    statusCode?: number,
+  ): void {
+    response.res = buildResponse(
+      response,
+      body,
+      statusCode ?? this.resolve(response),
+    );
+  }
+
+  public end(response: NestContext, message?: string): void {
+    response.res = buildResponse(
+      response,
+      message,
+      this.resolve(response),
+    );
+  }
+
+  public redirect(
+    response: NestContext,
+    statusCode: number,
+    url: string,
+  ): void {
+    response.header('Location', url);
+    response.res = buildResponse(
+      response,
+      undefined,
+      statusCode,
+    );
+  }
+
+  public setHeader(
+    response: NestContext,
+    name: string,
+    value: string,
+  ): void {
+    response.header(name, value);
+  }
+
+  public getHeader(
+    response: NestContext,
+    name: string,
+  ): string | undefined {
+    return response.res.headers.get(name) ?? undefined;
+  }
+
+  public appendHeader(
+    response: NestContext,
+    name: string,
+    value: string,
+  ): void {
+    response.header(name, value, { append: true });
+  }
+
+  public isHeadersSent(response: NestContext): boolean {
+    return response.finalized;
+  }
+
+  private resolve(response: NestContext): number {
+    return this.pendingStatus.get(response) ?? HttpStatus.OK;
+  }
+}
+
+export { ResponseWriter };

package/src/route-adapter.ts

@@ -0,0 +1,261 @@
+import type { ServerType } from '@hono/node-server';
+import { RequestMethod } from '@nestjs/common';
+import type { VersioningOptions } from '@nestjs/common';
+import { AbstractHttpAdapter } from '@nestjs/core';
+
+import type { NestHandler, NestRequest } from './bridge.ts';
+import type { NestContext } from './context.ts';
+import { createVersionFilter } from './version-filter.ts';
+import type { VersionValue } from './version-filter.ts';
+import { asVersionedRoute } from './versioned-route.ts';
+import type { VersionedRoute } from './versioned-route.ts';
+
+/**
+ * Nest's verb enum mapped onto HTTP method names, for the one
+ * place that receives the enum rather than the name.
+ */
+const METHOD_BY_REQUEST_METHOD: Record<number, string> = {
+  [RequestMethod.GET]: 'GET',
+  [RequestMethod.POST]: 'POST',
+  [RequestMethod.PUT]: 'PUT',
+  [RequestMethod.DELETE]: 'DELETE',
+  [RequestMethod.PATCH]: 'PATCH',
+  [RequestMethod.ALL]: 'ALL',
+  [RequestMethod.OPTIONS]: 'OPTIONS',
+  [RequestMethod.HEAD]: 'HEAD',
+  [RequestMethod.SEARCH]: 'SEARCH',
+  [RequestMethod.PROPFIND]: 'PROPFIND',
+  [RequestMethod.PROPPATCH]: 'PROPPATCH',
+  [RequestMethod.MKCOL]: 'MKCOL',
+  [RequestMethod.COPY]: 'COPY',
+  [RequestMethod.MOVE]: 'MOVE',
+  [RequestMethod.LOCK]: 'LOCK',
+  [RequestMethod.UNLOCK]: 'UNLOCK',
+  [RequestMethod.QUERY]: 'QUERY',
+};
+
+/**
+ * Method registered for a route that answers every verb, and
+ * for middleware, which Nest mounts without one.
+ */
+const ALL_METHOD = 'ALL';
+
+/** Path a handler is mounted at when Nest passes it without one. */
+const ROOT_PATH = '/';
+
+/** Either a route path, or the handler to mount at the root. */
+type RouteTarget = string | NestHandler;
+
+function isHandler(value: unknown): value is NestHandler {
+  return typeof value === 'function';
+}
+
+function resolveRoute(
+  target: RouteTarget,
+  handler: NestHandler | undefined,
+): [string, NestHandler] {
+  if (typeof target === 'function') {
+    return [ROOT_PATH, target];
+  }
+  if (handler === undefined) {
+    throw new TypeError(
+      'A route registered with a path also needs a handler.',
+    );
+  }
+  return [target, handler];
+}
+
+/**
+ * The routing half of the Nest adapter contract: every verb a
+ * route can be mapped to, the middleware factory and version
+ * filtering. The concrete adapter supplies the registration, so
+ * this half never touches Hono itself.
+ */
+abstract class RouteAdapter extends AbstractHttpAdapter<
+  ServerType,
+  NestRequest,
+  NestContext
+> {
+  /** Registers one route with the underlying framework. */
+  protected abstract register(
+    method: string,
+    path: string,
+    handler: NestHandler,
+  ): void;
+
+  public override get(
+    target: RouteTarget,
+    handler?: NestHandler,
+  ): void {
+    this.route('GET', target, handler);
+  }
+
+  public override post(
+    target: RouteTarget,
+    handler?: NestHandler,
+  ): void {
+    this.route('POST', target, handler);
+  }
+
+  public override put(
+    target: RouteTarget,
+    handler?: NestHandler,
+  ): void {
+    this.route('PUT', target, handler);
+  }
+
+  public override patch(
+    target: RouteTarget,
+    handler?: NestHandler,
+  ): void {
+    this.route('PATCH', target, handler);
+  }
+
+  public override delete(
+    target: RouteTarget,
+    handler?: NestHandler,
+  ): void {
+    this.route('DELETE', target, handler);
+  }
+
+  public override options(
+    target: RouteTarget,
+    handler?: NestHandler,
+  ): void {
+    this.route('OPTIONS', target, handler);
+  }
+
+  public override head(
+    target: RouteTarget,
+    handler?: NestHandler,
+  ): void {
+    this.route('HEAD', target, handler);
+  }
+
+  public override all(
+    target: RouteTarget,
+    handler?: NestHandler,
+  ): void {
+    this.route(ALL_METHOD, target, handler);
+  }
+
+  public override search(
+    target: RouteTarget,
+    handler?: NestHandler,
+  ): void {
+    this.route('SEARCH', target, handler);
+  }
+
+  public override query(
+    target: RouteTarget,
+    handler?: NestHandler,
+  ): void {
+    this.route('QUERY', target, handler);
+  }
+
+  public override propfind(
+    target: RouteTarget,
+    handler?: NestHandler,
+  ): void {
+    this.route('PROPFIND', target, handler);
+  }
+
+  public override proppatch(
+    target: RouteTarget,
+    handler?: NestHandler,
+  ): void {
+    this.route('PROPPATCH', target, handler);
+  }
+
+  public override mkcol(
+    target: RouteTarget,
+    handler?: NestHandler,
+  ): void {
+    this.route('MKCOL', target, handler);
+  }
+
+  public override copy(
+    target: RouteTarget,
+    handler?: NestHandler,
+  ): void {
+    this.route('COPY', target, handler);
+  }
+
+  public override move(
+    target: RouteTarget,
+    handler?: NestHandler,
+  ): void {
+    this.route('MOVE', target, handler);
+  }
+
+  public override lock(
+    target: RouteTarget,
+    handler?: NestHandler,
+  ): void {
+    this.route('LOCK', target, handler);
+  }
+
+  public override unlock(
+    target: RouteTarget,
+    handler?: NestHandler,
+  ): void {
+    this.route('UNLOCK', target, handler);
+  }
+
+  /**
+   * Mounts global middleware. Nest calls this with a handler,
+   * or with a path and a handler, and both answer every
+   * method.
+   */
+  public override use(...args: unknown[]): void {
+    const [first, second] = args;
+    if (isHandler(first) && second === undefined) {
+      this.route(ALL_METHOD, first);
+      return;
+    }
+    if (typeof first === 'string' && isHandler(second)) {
+      this.route(ALL_METHOD, first, second);
+      return;
+    }
+    throw new TypeError(
+      'Middleware is mounted as a handler, or as a path and a ' +
+        'handler.',
+    );
+  }
+
+  public override createMiddlewareFactory(
+    requestMethod: RequestMethod,
+  ): (path: string, callback: unknown) => void {
+    const method =
+      METHOD_BY_REQUEST_METHOD[requestMethod] ?? ALL_METHOD;
+    return (path, callback) => {
+      if (!isHandler(callback)) {
+        throw new TypeError(
+          'Nest middleware must be registered as a function.',
+        );
+      }
+      this.route(method, path, callback);
+    };
+  }
+
+  public override applyVersionFilter(
+    handler: NestHandler,
+    version: VersionValue,
+    versioningOptions: VersioningOptions,
+  ): VersionedRoute {
+    return asVersionedRoute(
+      createVersionFilter(handler, version, versioningOptions),
+    );
+  }
+
+  private route(
+    method: string,
+    target: RouteTarget,
+    handler?: NestHandler,
+  ): void {
+    const [path, routeHandler] = resolveRoute(target, handler);
+    this.register(method, path, routeHandler);
+  }
+}
+
+export { ALL_METHOD, RouteAdapter };