@shadow-library/fastify 0.0.6 → 0.0.8

package/README.md

@@ -1,24 +1,461 @@
-# Shadow Fastify Server
+# @shadow-library/fastify
 
-This TypeScript package is a powerful Node.js server implementation built as a wrapper around the Fastify package. It offers features such as body, query,
-and URL parameter validation using AJV for speed, response formatting with fast-json-stringify, and a unified approach to authentication and authorization.
-The package uses decorators to define controller classes and HTTP methods, and includes a render decorator for templating engine support.
+A powerful TypeScript-first Fastify wrapper featuring decorator-based routing, automatic validation, response serialization, and comprehensive middleware support.
 
 ## Features
 
-**Fastify Wrapper:** Built on top of the high-performance Fastify framework.
-**Validation:** Fast validation for body, query, and URL parameters using AJV.
-**Response Serialization:** Consistent serialization of response types with fast-json-stringify to ensure only expected fields are returned.
-**Decorator-Based:** Use decorators to define controllers and HTTP methods.
-**Authentication and Authorization:** Unified methods to implement authentication and authorization.
-**Templating Support:** Render decorator for integrating templating engines.
+- 🚀 **High Performance**: Built on top of Fastify, one of the fastest Node.js web frameworks
+- 🎯 **Decorator-Based**: Clean, intuitive API using TypeScript decorators
+- ✅ **Automatic Validation**: Fast validation for body, query, and URL parameters using AJV
+- 📝 **Response Serialization**: Consistent response formatting with fast-json-stringify
+- 🔒 **Authentication & Authorization**: Built-in support for guards and middleware
+- 🛡️ **Error Handling**: Comprehensive error handling with custom error types
+- 🔄 **Middleware Support**: Flexible middleware system with lifecycle hooks
+- 📊 **Type Safety**: Full TypeScript support with schema generation
+- 🎨 **Templating Ready**: Built-in support for templating engines
 
-## Usage
+## Installation
 
-```ts
-import {} from '@shadow-library/server';
+```bash
+# npm
+npm install @shadow-library/fastify
+
+# yarn
+yarn add @shadow-library/fastify
+
+# pnpm
+pnpm add @shadow-library/fastify
+
+# bun
+bun add @shadow-library/fastify
+```
+
+## Quick Start
+
+### 1. Create a Controller
+
+```typescript
+import { HttpController, Get, Post, Body, RespondFor } from '@shadow-library/fastify';
+import { Schema, Field } from '@shadow-library/class-schema';
+
+@Schema()
+class CreateUserDto {
+  @Field(() => String, { minLength: 2, maxLength: 50 })
+  name: string;
+
+  @Field(() => String, { format: 'email' })
+  email: string;
+}
+
+@Schema()
+class UserResponse {
+  @Field(() => Number)
+  id: number;
+
+  @Field(() => String)
+  name: string;
+
+  @Field(() => String)
+  email: string;
+}
+
+@HttpController('/api/users')
+export class UserController {
+  @Get()
+  @RespondFor(200, [UserResponse])
+  async getUsers(): Promise<UserResponse[]> {
+    return [{ id: 1, name: 'John Doe', email: 'john@example.com' }];
+  }
+
+  @Post()
+  @RespondFor(201, UserResponse)
+  async createUser(@Body() userData: CreateUserDto): Promise<UserResponse> {
+    // Your business logic here
+    return { id: 2, ...userData };
+  }
+}
+```
+
+### 2. Create a Module
+
+```typescript
+import { FastifyModule } from '@shadow-library/fastify';
+import { UserController } from './user.controller';
+
+export const AppModule = FastifyModule.forRoot({
+  controllers: [UserController],
+  port: 3000,
+  host: '0.0.0.0',
+});
+```
+
+### 3. Bootstrap Your Application
+
+```typescript
+import { ShadowFactory } from '@shadow-library/app';
+import { Logger } from '@shadow-library/common';
+import { AppModule } from './app.module';
+
+Logger.addDefaultTransports();
+
+async function bootstrap() {
+  const app = await ShadowFactory.create(AppModule);
+  await app.start();
+}
+
+bootstrap();
+```
+
+## API Reference
+
+### Decorators
+
+#### Route Decorators
+
+```typescript
+@Get(path?: string)        // GET requests
+@Post(path?: string)       // POST requests
+@Put(path?: string)        // PUT requests
+@Patch(path?: string)      // PATCH requests
+@Delete(path?: string)     // DELETE requests
+@Options(path?: string)    // OPTIONS requests
+@Head(path?: string)       // HEAD requests
+```
+
+#### Parameter Decorators
+
+```typescript
+@Body(schema?: JSONSchema)     // Request body
+@Params(schema?: JSONSchema)   // URL parameters
+@Query(schema?: JSONSchema)    // Query parameters
+@Request() / @Req()            // Raw Fastify request
+@Response() / @Res()           // Raw Fastify response
+```
+
+#### Response Decorators
+
+```typescript
+@RespondFor(statusCode: number, schema: Class | JSONSchema)
+@HttpStatus(statusCode: number)
+```
+
+#### Controller Decorator
+
+```typescript
+@HttpController(prefix?: string)
 ```
 
+### Example: Advanced Usage with Authentication
+
+```typescript
+import { HttpController, Get, Post, Middleware, Body, Params } from '@shadow-library/fastify';
+
+// Custom Authentication Guard
+@Middleware({ type: 'preHandler', weight: 100 })
+class AuthGuard {
+  use(request: HttpRequest, reply: HttpResponse, done: HttpCallback) {
+    const token = request.headers.authorization?.replace('Bearer ', '');
+    if (!token) {
+      return reply.status(401).send({ error: 'Unauthorized' });
+    }
+    // Validate token logic here
+    done();
+  }
+}
+
+@HttpController('/api/protected')
+export class ProtectedController {
+  @Get('/profile')
+  @RespondFor(200, UserResponse)
+  async getProfile(@Request() req): Promise<UserResponse> {
+    // Access authenticated user from request
+    return req.user;
+  }
+}
+```
+
+### Error Handling
+
+```typescript
+import { ServerError, ServerErrorCode } from '@shadow-library/fastify';
+
+@HttpController('/api')
+export class ExampleController {
+  @Get('/error')
+  throwError() {
+    // Throws a predefined server error
+    throw new ServerError(ServerErrorCode.S008);
+  }
+
+  @Get('/custom-error')
+  throwCustomError() {
+    // Throws a custom error
+    throw new Error('Something went wrong');
+  }
+}
+```
+
+### Child Routes and Route Resolution
+
+```typescript
+@HttpController('/api')
+export class RoutesController {
+  constructor(@Inject(Router) private readonly fastifyRouter: FastifyRouter) {}
+
+  @Get('/unified')
+  async unifiedRoute(@Query() query: Record<string, any>) {
+    const results = [];
+    for (const route of query.routes?.split(',') ?? []) {
+      const result = await this.fastifyRouter.resolveChildRoute(route);
+      results.push(result);
+    }
+    return { results };
+  }
+}
+```
+
+## Configuration
+
+### Module Configuration
+
+```typescript
+const AppModule = FastifyModule.forRoot({
+  // Basic server configuration
+  host: 'localhost',
+  port: 8080,
+
+  // Controllers to register
+  controllers: [UserController, AuthController],
+
+  // Additional providers
+  providers: [UserService, AuthService],
+
+  // Error handling
+  errorHandler: new CustomErrorHandler(),
+
+  // Security
+  maskSensitiveData: true,
+
+  // Request ID generation
+  requestIdLogLabel: 'rid',
+  genReqId: () => uuid(),
+
+  // Router options
+  routerOptions: {
+    ignoreTrailingSlash: true,
+    ignoreDuplicateSlashes: true,
+  },
+
+  // Response schemas for error handling
+  responseSchema: {
+    '4xx': ErrorResponseSchema,
+    '5xx': ErrorResponseSchema,
+  },
+
+  // Extend Fastify instance before registering controllers
+  fastifyFactory: async fastify => {
+    // Register plugins, add hooks, or configure Fastify
+    await fastify.register(require('@fastify/cors'), {
+      origin: true,
+    });
+
+    fastify.addHook('onRequest', async (request, reply) => {
+      console.log(`Incoming request: ${request.method} ${request.url}`);
+    });
+
+    return fastify;
+  },
+});
+```
+
+### Async Configuration
+
+```typescript
+const AppModule = FastifyModule.forRootAsync({
+  useFactory: async (configService: ConfigService) => ({
+    host: configService.get('HOST'),
+    port: configService.get('PORT'),
+    controllers: [UserController],
+  }),
+  inject: [ConfigService],
+});
+```
+
+### Extending Fastify Instance
+
+Use the `fastifyFactory` option to customize the Fastify instance before controllers are registered. This is perfect for adding plugins, global hooks, or custom configurations:
+
+```typescript
+import cors from '@fastify/cors';
+import helmet from '@fastify/helmet';
+import rateLimit from '@fastify/rate-limit';
+
+const AppModule = FastifyModule.forRoot({
+  controllers: [UserController],
+  fastifyFactory: async fastify => {
+    // Register security plugins
+    await fastify.register(helmet, {
+      contentSecurityPolicy: {
+        directives: {
+          defaultSrc: ["'self'"],
+          styleSrc: ["'self'", "'unsafe-inline'"],
+        },
+      },
+    });
+
+    // Add CORS support
+    await fastify.register(cors, {
+      origin: (origin, callback) => {
+        const allowedOrigins = ['http://localhost:3000', 'https://myapp.com'];
+        if (!origin || allowedOrigins.includes(origin)) {
+          callback(null, true);
+        } else {
+          callback(new Error('Not allowed by CORS'), false);
+        }
+      },
+      credentials: true,
+    });
+
+    // Add rate limiting
+    await fastify.register(rateLimit, {
+      max: 100,
+      timeWindow: '1 minute',
+    });
+
+    // Add global hooks
+    fastify.addHook('onRequest', async (request, reply) => {
+      console.log(`[${new Date().toISOString()}] ${request.method} ${request.url}`);
+    });
+
+    fastify.addHook('onResponse', async (request, reply) => {
+      const responseTime = reply.elapsedTime;
+      console.log(`Response sent in ${responseTime}ms`);
+    });
+
+    // Add custom context or decorators
+    fastify.decorate('config', {
+      apiVersion: 'v1',
+      environment: process.env.NODE_ENV,
+    });
+
+    // Register custom content type parsers
+    fastify.addContentTypeParser('text/plain', { parseAs: 'string' }, (req, body, done) => {
+      done(null, body);
+    });
+
+    return fastify;
+  },
+});
+```
+
+#### Common Use Cases for fastifyFactory:
+
+- **Security**: Add helmet, CORS, rate limiting
+- **Logging**: Custom request/response logging hooks
+- **Authentication**: Register authentication plugins
+- **File Upload**: Configure multipart/file upload handling
+- **Custom Parsers**: Add support for custom content types
+- **Swagger/OpenAPI**: Register documentation plugins
+- **Database**: Add database connection decorators
+- **Caching**: Configure caching plugins
+
+## Middleware
+
+Create custom middleware by implementing the `Middleware` decorator:
+
+```typescript
+@Middleware({ type: 'preHandler', weight: 50 })
+export class LoggingMiddleware {
+  use(request: HttpRequest, reply: HttpResponse, done: HttpCallback) {
+    console.log(`${request.method} ${request.url}`);
+    done();
+  }
+}
+
+// Or generate middleware dynamically
+@Middleware({ type: 'preValidation', weight: 75 })
+export class ValidationMiddleware {
+  generate(route: RouteMetadata) {
+    return (request: HttpRequest, reply: HttpResponse, done: HttpCallback) => {
+      // Custom validation logic based on route metadata
+      done();
+    };
+  }
+}
+```
+
+## Validation
+
+The package uses `@shadow-library/class-schema` for automatic validation:
+
+```typescript
+@Schema()
+class CreateProductDto {
+  @Field(() => String, {
+    minLength: 1,
+    maxLength: 100,
+    description: 'Product name',
+  })
+  name: string;
+
+  @Field(() => Number, {
+    minimum: 0,
+    description: 'Product price in cents',
+  })
+  price: number;
+
+  @Field(() => [String], {
+    maxItems: 10,
+    description: 'Product tags',
+  })
+  tags?: string[];
+}
+```
+
+## Response Serialization
+
+Define response schemas for automatic serialization and documentation:
+
+```typescript
+@Schema()
+class ProductResponse {
+  @Field(() => Number)
+  id: number;
+
+  @Field(() => String)
+  name: string;
+
+  @Field(() => Number)
+  price: number;
+
+  @Field(() => Date)
+  createdAt: Date;
+}
+
+@HttpController('/products')
+export class ProductController {
+  @Get('/:id')
+  @RespondFor(200, ProductResponse)
+  @RespondFor(404, ErrorResponse)
+  async getProduct(@Params() params: { id: number }): Promise<ProductResponse> {
+    // Only the fields defined in ProductResponse will be serialized
+    return this.productService.findById(params.id);
+  }
+}
+```
+
+## Examples
+
+Check out the [examples](./examples) directory for complete working examples:
+
+- **hello-world**: Basic HTTP controller with GET/POST routes
+- **user-auth**: Advanced example with authentication guards
+- **child-routes**: Route resolution and unified endpoints
+
+## Contributing
+
+Contributions are welcome! Please read the [Contributing Guide](./CONTRIBUTING.md) for details.
+
 ## License
 
-This package is licensed under the MIT License. See the `LICENSE` file for more information.
+This package is licensed under the MIT License. See the [LICENSE](./LICENSE) file for more information.

package/cjs/classes/default-error-handler.js

@@ -6,28 +6,29 @@ const constants_1 = require("../constants.js");
 const server_error_1 = require("../server.error.js");
 const unexpectedError = new server_error_1.ServerError(server_error_1.ServerErrorCode.S001);
 const validationError = new server_error_1.ServerError(server_error_1.ServerErrorCode.S003);
+const invalidRequestError = new server_error_1.ServerError(server_error_1.ServerErrorCode.S006);
 class DefaultErrorHandler {
     logger = common_1.Logger.getLogger(constants_1.NAMESPACE, 'DefaultErrorHandler');
     parseFastifyError(err) {
         if (err.statusCode === 500)
             return { statusCode: 500, error: unexpectedError.toObject() };
-        return { statusCode: err.statusCode, error: { code: err.code, type: common_1.ErrorType.CLIENT_ERROR, message: err.message } };
+        return { statusCode: err.statusCode, error: { ...invalidRequestError.toObject(), message: err.message } };
     }
     handle(err, _req, res) {
         this.logger.warn('Handling error', err);
         if (err.cause)
-            this.logger.warn('Caused by:', err.cause);
+            this.logger.warn('Caused by', err.cause);
         if (err instanceof server_error_1.ServerError)
             return res.status(err.getStatusCode()).send(err.toObject());
         else if (err instanceof common_1.ValidationError)
-            return res.status(400).send({ ...err.toObject(), code: validationError.getCode() });
+            return res.status(validationError.getStatusCode()).send({ ...err.toObject(), ...validationError.toObject() });
         else if (err instanceof common_1.AppError)
             return res.status(500).send(err.toObject());
         else if (err.name === 'FastifyError') {
             const { statusCode, error } = this.parseFastifyError(err);
             return res.status(statusCode).send(error);
         }
-        this.logger.error('Unhandler error has occurred:', err);
+        this.logger.error('Unhandled error has occurred', err);
         return res.status(500).send(unexpectedError.toObject());
     }
 }

package/cjs/decorators/http-input.decorator.d.ts

@@ -1,4 +1,5 @@
 import { JSONSchema } from '@shadow-library/class-schema';
+import { Class } from 'type-fest';
 export declare enum RouteInputType {
     BODY = "body",
     PARAMS = "params",
@@ -6,7 +7,7 @@ export declare enum RouteInputType {
     REQUEST = "request",
     RESPONSE = "response"
 }
-export type RouteInputSchemas = Partial<Record<'body' | 'params' | 'query', JSONSchema>>;
+export type RouteInputSchemas = Partial<Record<'body' | 'params' | 'query', JSONSchema | Class<unknown>>>;
 export declare function HttpInput(type: RouteInputType, schema?: JSONSchema): ParameterDecorator;
 export declare const Body: (schema?: JSONSchema) => ParameterDecorator;
 export declare const Params: (schema?: JSONSchema) => ParameterDecorator;

package/cjs/decorators/http-input.decorator.js

@@ -5,9 +5,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Res = exports.Response = exports.Req = exports.Request = exports.Query = exports.Params = exports.Body = exports.RouteInputType = void 0;
 exports.HttpInput = HttpInput;
-const assert_1 = __importDefault(require("assert"));
+const node_assert_1 = __importDefault(require("node:assert"));
 const app_1 = require("@shadow-library/app");
-const class_schema_1 = require("@shadow-library/class-schema");
 const constants_1 = require("../constants.js");
 var RouteInputType;
 (function (RouteInputType) {
@@ -19,16 +18,16 @@ var RouteInputType;
 })(RouteInputType || (exports.RouteInputType = RouteInputType = {}));
 function HttpInput(type, schema) {
     return (target, propertyKey, index) => {
-        (0, assert_1.default)(propertyKey, 'Cannot apply decorator to a constructor parameter');
+        (0, node_assert_1.default)(propertyKey, 'Cannot apply decorator to a constructor parameter');
         const inputs = Reflect.getMetadata(constants_1.HTTP_CONTROLLER_INPUTS, target, propertyKey) ?? [];
         Reflect.defineMetadata(constants_1.HTTP_CONTROLLER_INPUTS, inputs, target, propertyKey);
         inputs[index] = type;
         if (!schema) {
             const paramTypes = Reflect.getMetadata(constants_1.PARAMTYPES_METADATA, target, propertyKey);
-            schema = class_schema_1.ClassSchema.generate(paramTypes[index]);
+            schema = paramTypes[index];
         }
         const descriptor = Reflect.getOwnPropertyDescriptor(target, propertyKey);
-        (0, assert_1.default)(descriptor, 'Cannot apply decorator to a non-method');
+        (0, node_assert_1.default)(descriptor, 'Cannot apply decorator to a non-method');
         (0, app_1.Route)({ schemas: { [type]: schema } })(target, propertyKey, descriptor);
     };
 }

package/cjs/decorators/index.d.ts

@@ -3,3 +3,4 @@ export * from './http-input.decorator.js';
 export * from './http-output.decorator.js';
 export * from './http-route.decorator.js';
 export * from './middleware.decorator.js';
+export * from './sensitive.decorator.js';

package/cjs/decorators/index.js

@@ -19,3 +19,4 @@ __exportStar(require("./http-input.decorator.js"), exports);
 __exportStar(require("./http-output.decorator.js"), exports);
 __exportStar(require("./http-route.decorator.js"), exports);
 __exportStar(require("./middleware.decorator.js"), exports);
+__exportStar(require("./sensitive.decorator.js"), exports);

package/cjs/decorators/middleware.decorator.js

@@ -4,7 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Middleware = Middleware;
-const assert_1 = __importDefault(require("assert"));
+const node_assert_1 = __importDefault(require("node:assert"));
 const app_1 = require("@shadow-library/app");
 const constants_1 = require("../constants.js");
 const propertyKeys = ['generate', 'use'];
@@ -15,7 +15,7 @@ function Middleware(options = {}) {
         options.weight = 0;
     return target => {
         const key = propertyKeys.find(key => key in target.prototype);
-        (0, assert_1.default)(key, `Cannot apply @Middleware to a class without a 'generate()' or 'use()' method`);
+        (0, node_assert_1.default)(key, `Cannot apply @Middleware to a class without a 'generate()' or 'use()' method`);
         (0, app_1.Controller)({ ...options, [constants_1.HTTP_CONTROLLER_TYPE]: 'middleware', generates: key === 'generate' })(target);
     };
 }

package/cjs/decorators/sensitive.decorator.d.ts

@@ -0,0 +1,4 @@
+import { MaskOptions } from '@shadow-library/common';
+export type SensitiveDataType = 'secret' | 'email' | 'number' | 'words';
+export declare function Sensitive(type?: SensitiveDataType): PropertyDecorator;
+export declare function Sensitive(maskOptions: MaskOptions): PropertyDecorator;

package/cjs/decorators/sensitive.decorator.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Sensitive = Sensitive;
+const class_schema_1 = require("@shadow-library/class-schema");
+function Sensitive(typeOrMaskOptions = 'secret') {
+    return (target, propertyKey) => {
+        const options = { sensitive: true };
+        if (typeof typeOrMaskOptions === 'string')
+            options.type = typeOrMaskOptions;
+        else
+            options.maskOptions = typeOrMaskOptions;
+        const decorator = (0, class_schema_1.FieldMetadata)({ 'x-fastify': options });
+        decorator(target, propertyKey);
+    };
+}

package/cjs/interfaces/middleware.interface.d.ts

@@ -1,9 +1,12 @@
-import { RouteMetdata } from '@shadow-library/app';
-import { HttpRequest, HttpResponse } from './route-handler.interface.js';
-export type MiddlewareHandler = (request: HttpRequest, response: HttpResponse) => Promise<any>;
+import { RouteMetadata } from '@shadow-library/app';
+import { HttpCallback, HttpRequest, HttpResponse, RouteHandler } from './route-handler.interface.js';
 export interface MiddlewareGenerator {
-    generate(metadata: RouteMetdata): MiddlewareHandler | undefined | Promise<MiddlewareHandler | undefined>;
+    cacheKey?: (metadata: RouteMetadata) => string;
+    generate(metadata: RouteMetadata): RouteHandler | undefined | Promise<RouteHandler | undefined>;
 }
-export interface HttpMiddleware {
-    use(request: HttpRequest, response: HttpResponse): Promise<any>;
+export interface AsyncHttpMiddleware {
+    use(request: HttpRequest, response: HttpResponse): Promise<unknown>;
+}
+export interface CallbackHttpMiddleware {
+    use(request: HttpRequest, response: HttpResponse, done: HttpCallback): void;
 }

package/cjs/interfaces/route-handler.interface.d.ts

@@ -1,4 +1,8 @@
-import { FastifyReply, FastifyRequest } from 'fastify';
+import { SyncValue } from '@shadow-library/common';
+import { DoneFuncWithErrOrRes, FastifyReply, FastifyRequest } from 'fastify';
 export type HttpRequest = FastifyRequest;
 export type HttpResponse = FastifyReply;
-export type RouteHandler = (req: HttpRequest, res: HttpResponse) => unknown | Promise<unknown>;
+export type HttpCallback = DoneFuncWithErrOrRes;
+export type CallbackRouteHandler = (request: HttpRequest, response: HttpResponse, done: HttpCallback) => SyncValue<unknown>;
+export type AsyncRouteHandler = (request: HttpRequest, response: HttpResponse) => Promise<unknown>;
+export type RouteHandler<T extends (...args: any[]) => any = any> = ReturnType<T> extends Promise<unknown> ? AsyncRouteHandler : CallbackRouteHandler;

package/cjs/interfaces/server-metadata.interface.d.ts

@@ -1,24 +1,25 @@
-import { RouteMetdata } from '@shadow-library/app';
+import { RouteMetadata } from '@shadow-library/app';
 import { JSONSchema } from '@shadow-library/class-schema';
 import { RouteShorthandOptions } from 'fastify';
 import { HTTP_CONTROLLER_TYPE } from '../constants.js';
 import { HttpMethod, RouteInputSchemas } from '../decorators/index.js';
 declare module '@shadow-library/app' {
-    interface RouteMetdata extends Omit<RouteShorthandOptions, 'config'> {
+    interface RouteMetadata extends Omit<RouteShorthandOptions, 'config'> {
         method?: HttpMethod;
         path?: string;
         schemas?: RouteInputSchemas & {
             response?: Record<number | string, JSONSchema>;
         };
         rawBody?: boolean;
+        silentValidation?: boolean;
         status?: number;
         headers?: Record<string, string | (() => string)>;
         redirect?: string;
         render?: string | true;
     }
-    interface ControllerMetdata {
+    interface ControllerMetadata {
         [HTTP_CONTROLLER_TYPE]?: 'router' | 'middleware';
         path?: string;
     }
 }
-export type ServerMetadata = RouteMetdata;
+export type ServerMetadata = RouteMetadata;

package/cjs/module/error-response.dto.d.ts

@@ -6,5 +6,5 @@ export declare class ErrorResponseDto {
     code: string;
     type: string;
     message: string;
-    fields: ErrorFieldDto[];
+    fields?: ErrorFieldDto[];
 }