@ailura/nestjs-hono-adapter 1.0.0

package/src/static-assets.ts

@@ -0,0 +1,247 @@
+import { serveStatic } from '@hono/node-server/serve-static';
+import type { MiddlewareHandler } from 'hono';
+
+import type {
+  NestContext,
+  NestHono,
+  NodeEnv,
+} from './context.ts';
+
+/**
+ * The options Nest accepts for static assets. They are declared
+ * here because Nest types the parameter as `any` on both the
+ * application and the adapter, so nothing can be taken from a
+ * signature.
+ *
+ * The options Hono's handler decides for itself are refused
+ * rather than ignored, so a deployment finds out at startup
+ * instead of from a response that quietly differs from the one
+ * that was asked for.
+ */
+interface StaticAssetsOptions {
+  readonly dotfiles?: string;
+  readonly etag?: boolean;
+  readonly extensions?: readonly string[];
+  readonly fallthrough?: boolean;
+  readonly immutable?: boolean;
+  readonly index?: string | false;
+  readonly maxAge?: number | string;
+  readonly prefix?: string;
+  readonly redirect?: boolean;
+  readonly setHeaders?: unknown;
+}
+
+/** The index file a directory request is answered with. */
+const DEFAULT_INDEX = 'index.html';
+
+/** The header a cache lifetime is written with. */
+const CACHE_CONTROL = 'cache-control';
+
+/** How long each named unit lasts, in milliseconds. */
+const MILLISECOND = 1;
+const SECOND = 1000;
+const MINUTE = 60_000;
+const HOUR = 3_600_000;
+const DAY = 86_400_000;
+const WEEK = 604_800_000;
+const YEAR = 31_536_000_000;
+
+/** The milliseconds one unit of a duration lasts. */
+const UNIT_MS = new Map<string, number>([
+  ['d', DAY],
+  ['h', HOUR],
+  ['m', MINUTE],
+  ['ms', MILLISECOND],
+  ['s', SECOND],
+  ['w', WEEK],
+  ['y', YEAR],
+]);
+
+/** A cache lifetime, spelled the way the `ms` package spells it. */
+const DURATION =
+  /^(?<amount>\d+(?:\.\d+)?)\s*(?<unit>ms|s|m|h|d|w|y)?$/u;
+
+/** Names the option the Hono handler cannot honour. */
+function unsupported(name: string): TypeError {
+  return new TypeError(
+    'The Hono adapter cannot honour the static asset ' +
+      `option ${name}.`,
+  );
+}
+
+/** The directories a call named, as a list. */
+function toDirectories(
+  path: string | readonly string[],
+): readonly string[] {
+  if (typeof path === 'string') {
+    return [path];
+  }
+
+  return path;
+}
+
+/** Refuses the options that hook into another server. */
+function assertNoHooks(options: StaticAssetsOptions): void {
+  if (options.setHeaders !== undefined) {
+    throw unsupported('setHeaders');
+  }
+
+  if (options.extensions !== undefined) {
+    throw unsupported('extensions');
+  }
+
+  if (options.etag === false) {
+    throw unsupported('etag: false');
+  }
+}
+
+/** Refuses the options that ask for another serving mode. */
+function assertNoOtherModes(
+  options: StaticAssetsOptions,
+): void {
+  if (options.fallthrough === false) {
+    throw unsupported('fallthrough: false');
+  }
+
+  if (options.dotfiles !== undefined) {
+    throw unsupported('dotfiles');
+  }
+
+  if (options.index === false) {
+    throw unsupported('index: false');
+  }
+
+  if (
+    options.immutable === true &&
+    options.maxAge === undefined
+  ) {
+    throw new TypeError(
+      'The Hono adapter writes immutability with a maximum ' +
+        'age, so maxAge has to be named with it.',
+    );
+  }
+}
+
+function assertSupported(options: StaticAssetsOptions): void {
+  assertNoHooks(options);
+  assertNoOtherModes(options);
+}
+
+/** The milliseconds a cache lifetime names. */
+function toMilliseconds(maxAge: number | string): number {
+  if (typeof maxAge === 'number') {
+    return maxAge;
+  }
+
+  const match = DURATION.exec(maxAge.trim());
+  if (match === null) {
+    throw unsupported(`maxAge: ${maxAge}`);
+  }
+
+  const { amount, unit } = match.groups ?? {};
+  const scale = UNIT_MS.get(unit ?? 'ms');
+  if (scale === undefined) {
+    throw unsupported(`maxAge: ${maxAge}`);
+  }
+
+  return Number(amount) * scale;
+}
+
+/** The header a served file is cached with. */
+function cacheControl(options: StaticAssetsOptions): string {
+  const milliseconds = toMilliseconds(options.maxAge ?? 0);
+  const seconds = Math.floor(milliseconds / SECOND);
+  const base = `public, max-age=${seconds}`;
+  if (options.immutable === true) {
+    return `${base}, immutable`;
+  }
+
+  return base;
+}
+
+/** Writes the cache lifetime a deployment asked for. */
+function setCacheControl(
+  context: NestContext,
+  options: StaticAssetsOptions,
+): void {
+  if (options.maxAge === undefined) {
+    return;
+  }
+
+  context.header(CACHE_CONTROL, cacheControl(options));
+}
+
+/** The index file a directory request is answered with. */
+function indexOf(options: StaticAssetsOptions): string {
+  if (typeof options.index === 'string') {
+    return options.index;
+  }
+
+  return DEFAULT_INDEX;
+}
+
+/** The request path without the prefix the assets hang under. */
+function withoutPrefix(
+  requestPath: string,
+  prefix: string | undefined,
+): string {
+  if (prefix === undefined || prefix === '') {
+    return requestPath;
+  }
+
+  return requestPath.slice(prefix.length);
+}
+
+/** The paths one mount answers on. */
+function mountPaths(
+  prefix: string | undefined,
+): readonly string[] {
+  if (prefix === undefined || prefix === '') {
+    return ['/*'];
+  }
+
+  return [prefix, `${prefix}/*`];
+}
+
+/** The handler that serves one directory. */
+function directoryHandler(
+  directory: string,
+  options: StaticAssetsOptions,
+): MiddlewareHandler<NodeEnv> {
+  return serveStatic({
+    index: indexOf(options),
+    onFound: (_file: string, context: NestContext) => {
+      setCacheControl(context, options);
+    },
+    rewriteRequestPath: (path: string) =>
+      withoutPrefix(path, options.prefix),
+    root: directory,
+  });
+}
+
+/**
+ * Mounts the directories a deployment named, under the prefix
+ * it asked for.
+ *
+ * A request that names no file in them travels on, which is
+ * what Nest's own middleware does: the routes behind it answer,
+ * and an answer the deployment asked for is written before
+ * that.
+ */
+function mountStaticAssets(
+  hono: NestHono,
+  path: string | readonly string[],
+  options: StaticAssetsOptions,
+): void {
+  assertSupported(options);
+  const mounts = mountPaths(options.prefix);
+
+  for (const directory of toDirectories(path)) {
+    for (const mount of mounts) {
+      hono.use(mount, directoryHandler(directory, options));
+    }
+  }
+}
+
+export { mountStaticAssets, toDirectories };
+export type { StaticAssetsOptions };

package/src/version-filter.ts

@@ -0,0 +1,170 @@
+import {
+  VERSION_NEUTRAL,
+  VersioningType,
+} from '@nestjs/common';
+import type { VersioningOptions } from '@nestjs/common';
+import type { NestHandler, NestRequest } from './bridge.ts';
+
+/**
+ * Mirrors VersionValue in version-options.interface, which
+ *
+ * @nestjs/common does not export: reading it from an internal
+ * path would tie the package to a path Nest may move.
+ */
+type VersionValue =
+  | string
+  | typeof VERSION_NEUTRAL
+  | (string | typeof VERSION_NEUTRAL)[];
+
+function readHeader(
+  request: NestRequest,
+  name: string,
+): string | undefined {
+  return (
+    request.headers[name] ?? request.headers[name.toLowerCase()]
+  );
+}
+
+function isNeutral(version: VersionValue): boolean {
+  return (
+    Array.isArray(version) && version.includes(VERSION_NEUTRAL)
+  );
+}
+
+/**
+ * Normalises a version, or a list of them, into a list. The
+ * neutral marker is a symbol, so the list type is widened to
+ * match it.
+ */
+function toVersionList(
+  value: string | VersionValue,
+): (string | symbol)[] {
+  if (Array.isArray(value)) {
+    return value;
+  }
+  return [value];
+}
+
+function matchesVersion(
+  version: VersionValue,
+  supplied: string | string[] | undefined,
+): boolean {
+  if (supplied === undefined) {
+    return false;
+  }
+  const suppliedVersions = toVersionList(supplied);
+  const acceptedVersions = toVersionList(version);
+  return acceptedVersions.some((accepted) =>
+    suppliedVersions.includes(accepted),
+  );
+}
+
+/**
+ * Reads the version parameter out of the `Accept` header, which
+ * looks like `application/json;v=1`.
+ */
+function readMediaTypeParameter(
+  request: NestRequest,
+): string | undefined {
+  const accept = readHeader(request, 'accept');
+  if (accept === undefined) {
+    return undefined;
+  }
+  const [, parameter] = accept.split(';');
+  return parameter;
+}
+
+/**
+ * Answers every request whose version the extractor resolves to
+ * one this route serves.
+ */
+function createCustomFilter(
+  handler: NestHandler,
+  version: VersionValue,
+  extractor: (request: unknown) => string | string[],
+): NestHandler {
+  return (request, response, next) => {
+    if (matchesVersion(version, extractor(request))) {
+      return handler(request, response, next);
+    }
+    return next();
+  };
+}
+
+function createMediaTypeFilter(
+  handler: NestHandler,
+  version: VersionValue,
+  key: string,
+): NestHandler {
+  return (request, response, next) => {
+    const parameter = readMediaTypeParameter(request);
+    if (parameter === undefined) {
+      if (isNeutral(version)) {
+        return handler(request, response, next);
+      }
+      return next();
+    }
+    const [, supplied] = parameter.split(key);
+    if (matchesVersion(version, supplied)) {
+      return handler(request, response, next);
+    }
+    return next();
+  };
+}
+
+function createHeaderFilter(
+  handler: NestHandler,
+  version: VersionValue,
+  name: string,
+): NestHandler {
+  return (request, response, next) => {
+    const supplied = readHeader(request, name.toLowerCase());
+    if (supplied === undefined) {
+      if (isNeutral(version)) {
+        return handler(request, response, next);
+      }
+      return next();
+    }
+    if (matchesVersion(version, supplied)) {
+      return handler(request, response, next);
+    }
+    return next();
+  };
+}
+
+/**
+ * Guards a route handler by request version for the versioning
+ * styles the route path does not already resolve. The logic
+ * mirrors Nest's own adapters, so a versioned route behaves the
+ * same way on Hono.
+ *
+ * URI versioning is a plain path prefix and needs no filter. A
+ * request that asks for an unknown version is passed on rather
+ * than rejected, which is how Nest keeps an older version
+ * serving the same route.
+ */
+function createVersionFilter(
+  handler: NestHandler,
+  version: VersionValue,
+  options: VersioningOptions,
+): NestHandler {
+  if (
+    version === VERSION_NEUTRAL ||
+    options.type === VersioningType.URI
+  ) {
+    return handler;
+  }
+  if (options.type === VersioningType.CUSTOM) {
+    return createCustomFilter(
+      handler,
+      version,
+      options.extractor,
+    );
+  }
+  if (options.type === VersioningType.MEDIA_TYPE) {
+    return createMediaTypeFilter(handler, version, options.key);
+  }
+  return createHeaderFilter(handler, version, options.header);
+}
+
+export { createVersionFilter, type VersionValue };

package/src/versioned-route.ts

@@ -0,0 +1,30 @@
+import type { AbstractHttpAdapter } from '@nestjs/core';
+
+import type { NestHandler } from './bridge.ts';
+
+/**
+ * A versioned route as the adapter contract declares it. It is
+ * derived from the base class rather than written out, because
+ * Nest types the value such a route resolves to as `Function`.
+ */
+type VersionedRoute = ReturnType<
+  AbstractHttpAdapter['applyVersionFilter']
+>;
+
+/**
+ * Narrows a version filter to the type the contract asks for.
+ *
+ * The contract says a versioned route resolves to a `Function`,
+ * which no handler answering with a response can satisfy. The
+ * router only ever calls the function it is handed, so the two
+ * differ in the type alone. Confining the assertion here keeps
+ * the rest of the adapter free of them, and `no-unsafe-type-
+ * assertion` is disabled for this file alone.
+ */
+function asVersionedRoute(
+  handler: NestHandler,
+): VersionedRoute {
+  return handler as VersionedRoute;
+}
+
+export { asVersionedRoute, type VersionedRoute };

package/src/views.ts

@@ -0,0 +1,188 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import { NotFoundException } from '@nestjs/common';
+
+import type { NestContext } from './context.ts';
+import { toDirectories } from './static-assets.ts';
+
+/** The data a template is rendered with. */
+type ViewData = Record<string, unknown>;
+
+/**
+ * Renders a template's source into the answer.
+ *
+ * The engine is handed the source rather than a file name, so
+ * every engine is reached the same way: the lines that compile
+ * and run a template belong to the application, which already
+ * knows which engine it uses.
+ */
+type ViewEngine = (
+  source: string,
+  data: ViewData,
+) => string | Promise<string>;
+
+/** The views a deployment configures. */
+interface ViewOptions {
+  readonly directory?: string | readonly string[];
+  readonly engine: ViewEngine;
+}
+
+function isRecord(value: unknown): value is ViewData {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    !Array.isArray(value)
+  );
+}
+
+/** The value a handler returned, as the object a template reads. */
+function asData(options: unknown): ViewData {
+  if (isRecord(options)) {
+    return options;
+  }
+
+  return {};
+}
+
+/** The engine a deployment configured, when it configured one. */
+function engineOf(
+  views: ViewOptions | undefined,
+): ViewEngine | undefined {
+  if (views === undefined) {
+    return undefined;
+  }
+
+  return views.engine;
+}
+
+/** The directories a deployment configured, when it named any. */
+function directoriesOf(
+  views: ViewOptions | undefined,
+): readonly string[] {
+  if (views === undefined) {
+    return [];
+  }
+
+  const { directory } = views;
+  if (directory === undefined) {
+    return [];
+  }
+
+  return toDirectories(directory);
+}
+
+/** The extension a view engine names. */
+function toExtension(engine: string): string {
+  if (engine.startsWith('.')) {
+    return engine;
+  }
+
+  return `.${engine}`;
+}
+
+/** The file a view name reads, completed with the extension. */
+function fileNameFor(view: string, extension: string): string {
+  if (extension === '' || path.extname(view) !== '') {
+    return view;
+  }
+
+  return `${view}${extension}`;
+}
+
+/** Reads the first template that exists in the directories. */
+async function readFrom(
+  fileName: string,
+  directories: readonly string[],
+  position: number,
+): Promise<string> {
+  const directory = directories[position];
+  if (directory === undefined) {
+    throw new NotFoundException(
+      `No view named ${fileName} was found.`,
+    );
+  }
+
+  try {
+    return await readFile(
+      path.join(directory, fileName),
+      'utf8',
+    );
+  } catch {
+    // The next directory may hold it; the last one reports.
+    return readFrom(fileName, directories, position + 1);
+  }
+}
+
+/**
+ * Renders the templates a deployment configured.
+ *
+ * The engine is optional because an application that renders
+ * nothing never configures one: naming an engine is what makes
+ * it required, and that happens at startup rather than at the
+ * first request that renders.
+ */
+class ViewRenderer {
+  private readonly engine: ViewEngine | undefined;
+  private directories: readonly string[] = [];
+  private extension = '';
+
+  public constructor(views: ViewOptions | undefined) {
+    this.engine = engineOf(views);
+    this.directories = directoriesOf(views);
+  }
+
+  /** Names the engine, by the extension it renders. */
+  public useEngine(name: string): void {
+    if (this.engine === undefined) {
+      throw new TypeError(
+        'The adapter renders with the engine it was given, so ' +
+          'pass `views.engine` before naming one.',
+      );
+    }
+
+    this.extension = toExtension(name);
+  }
+
+  /** Names the directories a view is read from. */
+  public useDirectories(
+    directory: string | readonly string[],
+  ): void {
+    this.directories = toDirectories(directory);
+  }
+
+  /** Renders one view into the response Nest handed over. */
+  public async render(
+    response: NestContext,
+    view: string,
+    options: unknown,
+  ): Promise<void> {
+    const { engine } = this;
+    if (engine === undefined) {
+      throw new TypeError(
+        'No view engine was configured, so no view renders.',
+      );
+    }
+
+    const fileName = fileNameFor(view, this.extension);
+    const source = await readFrom(
+      fileName,
+      this.directoriesFor(),
+      0,
+    );
+    const html = await engine(source, asData(options));
+    response.html(html);
+  }
+
+  /** The directories to read from, the working one by default. */
+  private directoriesFor(): readonly string[] {
+    if (this.directories.length === 0) {
+      return [process.cwd()];
+    }
+
+    return this.directories;
+  }
+}
+
+export { ViewRenderer };
+export type { ViewData, ViewEngine, ViewOptions };