@marcosvnmelo/nestjs-platform-h3 11.1.14-1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) marcosvnmelo <marcosvnmelo.dev@gmail.com> (https://github.com/marcosvnmelo)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,228 @@
+# @marcosvnmelo/nestjs-platform-h3
+
+H3 platform adapter for NestJS.
+
+This package lets you run regular NestJS apps on top of [h3](https://h3.unjs.io), including support for:
+
+- Nest core HTTP features (routing, pipes, guards, interceptors, filters, middleware)
+- CORS and static assets
+- HTTP/1.1, HTTPS, HTTP/2 (h2), and HTTP/2 cleartext (h2c)
+- Multipart uploads (multer-style interceptors + stream interceptors)
+- H3-specific parameter decorators
+
+## Requirements
+
+- Node.js 20+
+- NestJS 11 (`@nestjs/common` and `@nestjs/core`)
+
+## Installation
+
+```bash
+pnpm add @marcosvnmelo/nestjs-platform-h3 h3
+```
+
+## Quick start
+
+```ts
+import { NestFactory } from '@nestjs/core';
+
+import type { NestH3Application } from '@marcosvnmelo/nestjs-platform-h3';
+import { H3Adapter } from '@marcosvnmelo/nestjs-platform-h3';
+
+import { AppModule } from './app.module';
+
+async function bootstrap() {
+  const app = await NestFactory.create<NestH3Application>(
+    AppModule,
+    new H3Adapter(),
+  );
+
+  app.enableCors();
+  app.useStaticAssets('public', { prefix: '/static' });
+
+  await app.listen(3000);
+}
+
+void bootstrap();
+```
+
+## HTTP/2 support
+
+### HTTP/2 over TLS (h2)
+
+```ts
+import { readFileSync } from 'node:fs';
+
+import { NestFactory } from '@nestjs/core';
+
+import type { NestH3Application } from '@marcosvnmelo/nestjs-platform-h3';
+import { H3Adapter } from '@marcosvnmelo/nestjs-platform-h3';
+
+const key = readFileSync('./certs/key.pem');
+const cert = readFileSync('./certs/cert.pem');
+
+const app = await NestFactory.create<NestH3Application>(
+  AppModule,
+  new H3Adapter(),
+  {
+    httpsOptions: { key, cert },
+    http2Options: { http2: true, allowHTTP1: true },
+  },
+);
+```
+
+### HTTP/2 cleartext (h2c)
+
+```ts
+const app = await NestFactory.create<NestH3Application>(
+  AppModule,
+  new H3Adapter(),
+  {
+    http2Options: { http2: true },
+  },
+);
+```
+
+> h2c is useful for server-to-server traffic. Browsers do not support h2c.
+
+## H3 decorators
+
+Use H3-specific decorators when you want direct access to H3 request primitives:
+
+- `@H3Event()`
+- `@H3Request()`
+- `@H3Response()`
+- `@H3Query()`
+- `@H3Params()`
+- `@H3Body()`
+
+Example:
+
+```ts
+import { Controller, Get } from '@nestjs/common';
+
+import { H3Event, H3Query } from '@marcosvnmelo/nestjs-platform-h3';
+
+@Controller('users')
+export class UsersController {
+  @Get()
+  list(@H3Event() event: any, @H3Query('page') page?: string) {
+    return {
+      hasEvent: !!event,
+      page,
+    };
+  }
+}
+```
+
+## Multipart uploads
+
+The library exposes multer-style interceptors and storage engines:
+
+- Interceptors:
+  - `FileInterceptor`
+  - `FilesInterceptor`
+  - `FileFieldsInterceptor`
+  - `AnyFilesInterceptor`
+  - `NoFilesInterceptor`
+  - `FileStreamInterceptor`
+  - `FilesStreamInterceptor`
+  - `AnyFilesStreamInterceptor`
+- Decorators:
+  - `@UploadedFields()`
+  - `@FormBody()`
+  - `@FormField('name')`
+- Storage:
+  - `memoryStorage()`
+  - `diskStorage()`
+
+Single file example:
+
+```ts
+import {
+  Controller,
+  Post,
+  UploadedFile,
+  UseInterceptors,
+} from '@nestjs/common';
+
+import type { H3UploadedFile } from '@marcosvnmelo/nestjs-platform-h3';
+import { FileInterceptor } from '@marcosvnmelo/nestjs-platform-h3';
+
+@Controller('upload')
+export class UploadController {
+  @Post('single')
+  @UseInterceptors(FileInterceptor('file'))
+  uploadSingle(@UploadedFile() file: H3UploadedFile) {
+    return {
+      name: file.originalname,
+      size: file.size,
+      mime: file.mimetype,
+    };
+  }
+}
+```
+
+You can also configure upload defaults globally with `H3MulterModule.register(...)` or `H3MulterModule.registerAsync(...)`.
+
+## Adapter hooks
+
+`H3Adapter` includes lightweight lifecycle hooks:
+
+- `setOnRequestHook((req, res, done) => ...)`
+- `setOnResponseHook((req, res) => ...)`
+
+These are useful for custom request/response instrumentation.
+
+## Public exports
+
+The package exports:
+
+- `H3Adapter`
+- `NestH3Application` interface
+- H3 decorators
+- Multipart module/interceptors/decorators/storage/utilities
+
+## Development
+
+Install dependencies:
+
+```bash
+pnpm install
+```
+
+Build:
+
+```bash
+pnpm run build
+```
+
+Watch mode:
+
+```bash
+pnpm run dev
+```
+
+Run tests:
+
+```bash
+pnpm run test
+```
+
+Lint:
+
+```bash
+pnpm run lint
+```
+
+Format:
+
+```bash
+pnpm run format
+```
+
+Benchmark (builds library + benchmark package):
+
+```bash
+pnpm run benchmark
+```

package/dist/adapters/h3-adapter.d.ts

@@ -0,0 +1,253 @@
+import * as http from 'http';
+import * as http2 from 'http2';
+import * as https from 'https';
+import type { CorsOptions, H3Config, H3Event } from 'h3';
+import { H3 } from 'h3';
+import type { NestApplicationOptions, RequestMethod, VersioningOptions } from '@nestjs/common';
+import type { VersionValue } from '@nestjs/common/interfaces';
+import { AbstractHttpAdapter } from '@nestjs/core/adapters/http-adapter.js';
+import type { ServeStaticOptions } from '../interfaces/serve-static-options.interface';
+/**
+ * HTTP/2 options for the H3 adapter.
+ *
+ * @publicApi
+ */
+export interface H3Http2Options {
+    /**
+     * Enable HTTP/2 support.
+     */
+    http2: true;
+    /**
+     * TLS/SSL options for secure HTTP/2 connections (h2).
+     * Required for HTTP/2 in browsers.
+     */
+    http2Options?: http2.SecureServerOptions;
+    /**
+     * Allow HTTP/1 connections as a fallback via ALPN negotiation.
+     * Defaults to true.
+     */
+    allowHTTP1?: boolean;
+}
+/**
+ * HTTP/2 cleartext options (h2c) - HTTP/2 without TLS.
+ * Note: Browsers do not support h2c, only server-to-server communication.
+ *
+ * @publicApi
+ */
+export interface H3Http2CleartextOptions {
+    /**
+     * Enable HTTP/2 cleartext support (h2c).
+     */
+    http2: true;
+    /**
+     * HTTP/2 server options (without TLS).
+     */
+    http2Options?: http2.ServerOptions;
+}
+/**
+ * Extended application options for H3 with HTTP/2 support.
+ *
+ * @publicApi
+ */
+export interface H3ApplicationOptions extends NestApplicationOptions {
+    /**
+     * HTTP/2 configuration options.
+     */
+    http2Options?: H3Http2Options | H3Http2CleartextOptions;
+}
+type VersionedRoute = <TRequest extends Record<string, any> = any, TResponse = any>(req: TRequest, res: TResponse, next: () => void) => any;
+/**
+ * HTTP/2 compatible server type
+ */
+type H3Server = http.Server | https.Server | http2.Http2Server | http2.Http2SecureServer;
+export declare class H3Adapter extends AbstractHttpAdapter<H3Server, http.IncomingMessage | http2.Http2ServerRequest, http.ServerResponse | http2.Http2ServerResponse> {
+    protected readonly instance: H3;
+    private readonly logger;
+    private isHttp2;
+    private onRequestHook?;
+    private onResponseHook?;
+    /**
+     * Route registry mapping 'METHOD:path' to array of handlers.
+     * Enables multiple versioned handlers for the same path.
+     */
+    private readonly routeMap;
+    /**
+     * Tracks which method:path combinations have been registered with H3.
+     * Prevents duplicate route registrations.
+     */
+    private readonly registeredPaths;
+    constructor(instanceOrOptions?: H3 | H3Config);
+    getInstance<T = H3>(): T;
+    /**
+     * Sets a hook that is called before each request is processed.
+     * The hook can perform async operations and must call `done()` when finished.
+     *
+     * @param onRequestHook - The hook function to call before each request
+     */
+    setOnRequestHook(onRequestHook: (req: any, res: any, done: () => void) => Promise<void> | void): void;
+    /**
+     * Sets a hook that is called after each response is finished.
+     *
+     * @param onResponseHook - The hook function to call after each response
+     */
+    setOnResponseHook(onResponseHook: (req: any, res: any) => Promise<void> | void): void;
+    reply(response: http.ServerResponse | H3Event, body: any, statusCode?: number): http.ServerResponse<http.IncomingMessage> | undefined;
+    status(response: http.ServerResponse | H3Event, statusCode: number): http.ServerResponse<http.IncomingMessage> | H3Event<import("h3").EventHandlerRequest>;
+    end(response: http.ServerResponse | H3Event, message?: string): http.ServerResponse<http.IncomingMessage> | http2.Http2ServerResponse<http2.Http2ServerRequest> | undefined;
+    /**
+     * Render method is part of the AbstractHttpAdapter interface contract.
+     * Template rendering is not yet supported in H3Adapter.
+     */
+    render(response: http.ServerResponse | H3Event, _view: string, _options: any): http.ServerResponse<http.IncomingMessage> | http2.Http2ServerResponse<http2.Http2ServerRequest> | undefined;
+    redirect(response: http.ServerResponse | H3Event, statusCode: number, url: string): void;
+    /**
+     * The prefix parameter is part of the AbstractHttpAdapter interface contract.
+     * It represents the global prefix but is not used in H3's error handler implementation.
+     */
+    setErrorHandler(handler: Function, _prefix?: string): this;
+    /**
+     * The prefix parameter is part of the AbstractHttpAdapter interface contract.
+     * It represents the global prefix but is not used in H3's not-found handler implementation.
+     */
+    setNotFoundHandler(handler: Function, _prefix?: string): this;
+    isHeadersSent(response: http.ServerResponse | H3Event): boolean;
+    getHeader(response: http.ServerResponse | H3Event, name: string): string | number | string[] | undefined;
+    setHeader(response: http.ServerResponse | H3Event, name: string, value: string): void;
+    appendHeader(response: http.ServerResponse | H3Event, name: string, value: string): void;
+    listen(port: string | number, callback?: () => void): any;
+    listen(port: string | number, hostname: string, callback?: () => void): any;
+    close(): Promise<unknown> | undefined;
+    set(..._args: any[]): this;
+    enable(..._args: any[]): this;
+    disable(..._args: any[]): this;
+    engine(..._args: any[]): this;
+    /**
+     * Serves static files from the specified directory.
+     *
+     * @param staticPath - The path to the directory containing static files
+     * @param options - Options for serving static files (prefix, maxAge, etc.)
+     */
+    useStaticAssets(staticPath: string, options?: ServeStaticOptions): this;
+    /**
+     * Parse a max-age string like '1d', '2h', '30m' to milliseconds
+     */
+    private parseMaxAge;
+    setBaseViewsDir(..._args: any[]): this;
+    setViewEngine(..._args: any[]): this;
+    getRequestHostname(request: http.IncomingMessage | H3Event): string;
+    getRequestMethod(request: http.IncomingMessage | H3Event): string;
+    getRequestUrl(request: http.IncomingMessage | H3Event): string;
+    enableCors(options?: CorsOptions): void;
+    /**
+     * The requestMethod parameter is part of the AbstractHttpAdapter interface contract.
+     * H3 middleware uses instance.use() which doesn't filter by HTTP method (similar to Fastify).
+     */
+    createMiddlewareFactory(_requestMethod: RequestMethod): (path: string, callback: Function) => any;
+    /**
+     * Initialize the HTTP server with support for HTTP/1.1, HTTPS, and HTTP/2.
+     *
+     * HTTP/2 can be enabled by passing `http2Options` in the application options:
+     *
+     * @example
+     * ```typescript
+     * // HTTP/2 with TLS (h2)
+     * const app = await NestFactory.create(AppModule, new H3Adapter(), {
+     *   httpsOptions: { key, cert },
+     *   http2Options: { http2: true, allowHTTP1: true }
+     * });
+     *
+     * // HTTP/2 cleartext (h2c) - for server-to-server only
+     * const app = await NestFactory.create(AppModule, new H3Adapter(), {
+     *   http2Options: { http2: true }
+     * });
+     * ```
+     *
+     * @param options - Application options including HTTP/2 configuration
+     */
+    initHttpServer(options: NestApplicationOptions & {
+        http2Options?: H3Http2Options | H3Http2CleartextOptions;
+    }): void;
+    /**
+     * Returns whether the server is running in HTTP/2 mode.
+     *
+     * @returns {boolean} True if HTTP/2 is enabled
+     */
+    isHttp2Enabled(): boolean;
+    /**
+     * Parameters are part of the AbstractHttpAdapter interface contract.
+     * The prefix parameter could be used to conditionally apply parsing based on path prefix.
+     * The rawBody parameter could be used to configure raw body parsing.
+     * Currently, H3 adapter applies body parsing globally for POST, PUT, and PATCH requests.
+     * Multipart form data is skipped to allow interceptors to handle file uploads.
+     */
+    registerParserMiddleware(_prefix?: string, _rawBody?: boolean): void;
+    getType(): string;
+    get(handler: Function): void;
+    get(path: string, handler: Function): void;
+    post(handler: Function): void;
+    post(path: string, handler: Function): void;
+    put(handler: Function): void;
+    put(path: string, handler: Function): void;
+    delete(handler: Function): void;
+    delete(path: string, handler: Function): void;
+    patch(handler: Function): void;
+    patch(path: string, handler: Function): void;
+    options(handler: Function): void;
+    options(path: string, handler: Function): void;
+    head(handler: Function): void;
+    head(path: string, handler: Function): void;
+    /**
+     * Registers a route handler using H3's native routing with handler chaining.
+     * Uses H3's radix tree router for fast O(1) path matching.
+     *
+     * Implementation notes:
+     * - Uses H3's native routing (instance.on()) for optimal performance
+     * - Maintains route map to support multiple versioned handlers per path
+     * - On first registration: creates chain handler and registers with H3
+     * - On subsequent registrations: adds to route map, existing chain handler finds it
+     * - Lazy lookup pattern: chain handler queries route map at request time
+     * - Supports version filtering via next() callback mechanism
+     *
+     * @param method - HTTP method (GET, POST, etc.)
+     * @param routePath - The route path pattern
+     * @param handler - The route handler (possibly wrapped with version filter)
+     */
+    private registerRoute;
+    /**
+     * Executes a NestJS handler within an H3 event context.
+     * Used by native routing chain handler to invoke individual route handlers.
+     *
+     * @param handler - The NestJS route handler (possibly version-wrapped)
+     * @param event - The H3 event
+     * @param params - Route parameters (extracted by H3's router)
+     * @returns Promise that resolves to kHandled (if handled) or undefined (if next() called)
+     */
+    private executeHandler;
+    /**
+     * Invokes the actual NestJS handler and manages response lifecycle.
+     * Optimized to avoid unnecessary listener registration.
+     *
+     * Response handling:
+     * - For async handlers (return promise): resolve when promise completes, no res listener needed
+     * - For sync handlers: wait for res 'finish' event to know when response is sent
+     * - next() callback allows versioned handlers to skip to next handler if version doesn't match
+     * - Returns kHandled to signal H3 that response is handled, or undefined to continue middleware chain
+     *
+     * @param handler - The NestJS route handler function
+     * @param req - Node.js request (HTTP/1 or HTTP/2)
+     * @param res - Node.js response (HTTP/1 or HTTP/2)
+     * @returns Promise resolving to kHandled or undefined
+     */
+    private invokeHandler;
+    /**
+     * Applies version filtering to a route handler.
+     * Supports URI, Header, Media Type, and Custom versioning strategies.
+     *
+     * @param handler - The route handler function
+     * @param version - The version(s) this handler supports
+     * @param versioningOptions - The versioning configuration options
+     * @returns A wrapped handler that filters by version
+     */
+    applyVersionFilter(handler: Function, version: VersionValue, versioningOptions: VersioningOptions): VersionedRoute;
+}
+export {};

package/dist/adapters/index.d.ts

@@ -0,0 +1 @@
+export * from './h3-adapter';

package/dist/decorators/h3-decorators.d.ts

@@ -0,0 +1,168 @@
+/**
+ * Parameter decorator that extracts the underlying H3 event from the request.
+ * The H3 event provides access to H3-specific APIs and utilities.
+ *
+ * @example
+ * ```typescript
+ * import { H3Event } from '@marcosvnmelo/nestjs-platform-h3';
+ *
+ * @Controller('users')
+ * export class UsersController {
+ *   @Get()
+ *   findAll(@H3Event() event: H3EventType) {
+ *     // Access H3-specific APIs
+ *     const query = getQuery(event);
+ *     const cookies = parseCookies(event);
+ *     return { query, cookies };
+ *   }
+ * }
+ * ```
+ *
+ * @returns The H3Event object attached to the request
+ *
+ * @publicApi
+ */
+export declare const H3Event: (...dataOrPipes: unknown[]) => ParameterDecorator;
+/**
+ * Parameter decorator that extracts the raw H3 request object.
+ * This is the Node.js IncomingMessage with H3-specific properties attached.
+ *
+ * @example
+ * ```typescript
+ * import { H3Request } from '@marcosvnmelo/nestjs-platform-h3';
+ *
+ * @Controller('users')
+ * export class UsersController {
+ *   @Get()
+ *   findAll(@H3Request() req: any) {
+ *     // Access request with H3 properties
+ *     console.log(req.query);  // Query parameters
+ *     console.log(req.params); // Route parameters
+ *     console.log(req.body);   // Parsed body
+ *     return { url: req.url };
+ *   }
+ * }
+ * ```
+ *
+ * @returns The request object with H3 properties
+ *
+ * @publicApi
+ */
+export declare const H3Request: (...dataOrPipes: unknown[]) => ParameterDecorator;
+/**
+ * Parameter decorator that extracts the raw H3 response object.
+ * This is the Node.js ServerResponse used by the H3 adapter.
+ *
+ * @example
+ * ```typescript
+ * import { H3Response } from '@marcosvnmelo/nestjs-platform-h3';
+ *
+ * @Controller('users')
+ * export class UsersController {
+ *   @Get()
+ *   findAll(@H3Response() res: ServerResponse) {
+ *     // Access response to set headers, status, etc.
+ *     res.setHeader('X-Custom-Header', 'value');
+ *     return { message: 'success' };
+ *   }
+ * }
+ * ```
+ *
+ * @returns The Node.js ServerResponse object
+ *
+ * @publicApi
+ */
+export declare const H3Response: (...dataOrPipes: unknown[]) => ParameterDecorator;
+/**
+ * Parameter decorator that extracts query parameters from the H3 request.
+ * If a key is provided, returns the specific query parameter value.
+ * If no key is provided, returns all query parameters.
+ *
+ * @example
+ * ```typescript
+ * import { H3Query } from '@marcosvnmelo/nestjs-platform-h3';
+ *
+ * @Controller('users')
+ * export class UsersController {
+ *   // Get all query parameters
+ *   @Get()
+ *   findAll(@H3Query() query: Record<string, string>) {
+ *     return { query };
+ *   }
+ *
+ *   // Get specific query parameter
+ *   @Get('search')
+ *   search(@H3Query('term') searchTerm: string) {
+ *     return { searchTerm };
+ *   }
+ * }
+ * ```
+ *
+ * @param key - Optional key to extract a specific query parameter
+ * @returns The query parameters object or a specific value
+ *
+ * @publicApi
+ */
+export declare const H3Query: (...dataOrPipes: (string | import("@nestjs/common").PipeTransform<any, any> | import("@nestjs/common").Type<import("@nestjs/common").PipeTransform<any, any>> | undefined)[]) => ParameterDecorator;
+/**
+ * Parameter decorator that extracts route parameters from the H3 request.
+ * If a key is provided, returns the specific route parameter value.
+ * If no key is provided, returns all route parameters.
+ *
+ * @example
+ * ```typescript
+ * import { H3Params } from '@marcosvnmelo/nestjs-platform-h3';
+ *
+ * @Controller('users')
+ * export class UsersController {
+ *   // Get all route parameters
+ *   @Get(':id/posts/:postId')
+ *   getPost(@H3Params() params: { id: string; postId: string }) {
+ *     return { params };
+ *   }
+ *
+ *   // Get specific route parameter
+ *   @Get(':id')
+ *   findOne(@H3Params('id') id: string) {
+ *     return { userId: id };
+ *   }
+ * }
+ * ```
+ *
+ * @param key - Optional key to extract a specific route parameter
+ * @returns The route parameters object or a specific value
+ *
+ * @publicApi
+ */
+export declare const H3Params: (...dataOrPipes: (string | import("@nestjs/common").PipeTransform<any, any> | import("@nestjs/common").Type<import("@nestjs/common").PipeTransform<any, any>> | undefined)[]) => ParameterDecorator;
+/**
+ * Parameter decorator that extracts the request body from the H3 request.
+ * If a key is provided, returns the specific body property value.
+ * If no key is provided, returns the entire body.
+ *
+ * @example
+ * ```typescript
+ * import { H3Body } from '@marcosvnmelo/nestjs-platform-h3';
+ *
+ * @Controller('users')
+ * export class UsersController {
+ *   // Get entire body
+ *   @Post()
+ *   create(@H3Body() body: CreateUserDto) {
+ *     return { user: body };
+ *   }
+ *
+ *   // Get specific body property
+ *   @Post('register')
+ *   register(@H3Body('email') email: string) {
+ *     return { email };
+ *   }
+ * }
+ * ```
+ *
+ * @param key - Optional key to extract a specific body property
+ * @returns The body object or a specific value
+ *
+ * @publicApi
+ */
+export declare const H3Body: (...dataOrPipes: (string | import("@nestjs/common").PipeTransform<any, any> | import("@nestjs/common").Type<import("@nestjs/common").PipeTransform<any, any>> | undefined)[]) => ParameterDecorator;

package/dist/decorators/index.d.ts

@@ -0,0 +1 @@
+export * from './h3-decorators';

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './adapters';
+export * from './interfaces';
+export * from './multer';
+export * from './decorators';