codeweaver 2.1.0 → 2.3.0

package/.env.example

@@ -0,0 +1,20 @@
+# Environment
+NODE_ENV=development              # or "production" depending on your deployment
+
+# Server
+HTTP=http://localhost:3000
+PORT=3000
+
+# Feature flags
+SWAGGER=true
+
+# Timeouts and limits
+TIMEOUT=30
+
+# Rate limiting (separate vars)
+RATE_LIMIT_TIME_SPAN=60
+RATE_LIMIT_ALLOWED_CALLS=100
+
+# Memoization and cache
+MEMOIZE_TIME=300
+CACHE_SIZE=1000

package/README.md

@@ -10,10 +10,14 @@
 - **Express**: A lightweight web framework for building server-side applications in Node.js.
 - **TypeScript**: Adds strong typing for enhanced development experience and reduced runtime errors.
 - **Modular Router Structure**: Automates importing and mounting routers, ensuring a clean separation of endpoints and logic for easier scalability.
+- **Dependency resolver**: A simple dependency resolver that uses a lightweight container to manage and inject dependencies at runtime.
 - **Swagger Integration**: Automatically generates interactive API documentation, facilitating easier understanding of available endpoints for developers and consumers.
 - **Async Handlers**: Utilizes async/await syntax for cleaner, more maintainable asynchronous code without callback nesting.
 - **Zod**: Implements schema validation for input data.
-- **utils-decorators**: A collection of middleware utilities (throttling, caching, and error handling) designed to strengthen application resilience.
+- **Utils-decorators**: A collection of middleware utilities utils-decorators (throttling, caching, and error handling) designed to strengthen application resilience.
+- **Logger**: A Winston-based logger (with LogForm) that provides scalable, leveled logging, structured JSON output, and pluggable transports (console and file)
+
+Here's a revised Installation section that explicitly supports pnpm in addition to npm. I kept the formatting and steps intact, adding clear pnpm equivalents.
 
 ## Installation
 
@@ -29,9 +33,19 @@ To get started with the project, follow these steps:
 
 2. **Install dependencies**:
 
-   ```bash
-   npm install
-   ```
+   Choose your package manager and install:
+
+   - Using npm:
+
+     ```bash
+     npm install
+     ```
+
+   - Using pnpm:
+
+     ```bash
+     pnpm install
+     ```
 
 3. **Run the application**:
 
@@ -39,14 +53,29 @@ To get started with the project, follow these steps:
    npm start
    ```
 
+   Or, if you used pnpm:
+
+   ```bash
+   pnpm start
+   ```
+
 4. **Visit the Swagger UI**: Open your browser and go to `http://localhost:3000/api-docs` to view the automatically generated API documentation.
 
 5. **Build**: Compile the TypeScript files for the production environment:
 
-   ```bash
-   npm run build
-   npm run serve
-   ```
+   - Using npm:
+
+     ```bash
+     npm run build
+     npm run serve
+     ```
+
+   - Using pnpm:
+
+     ```bash
+     pnpm run build
+     pnpm run serve
+     ```
 
 ## Sample Project Structure
 
@@ -89,9 +118,10 @@ Example of a basic router:
 import { Router, Request, Response } from "express";
 import asyncHandler from "express-async-handler";
 import UserController from "./user.controller";
+import { resolve } from "@/utilities/container";
 
 const router = Router();
-const userController = new UserController();
+const userController = resolve(UserController);
 
 /**
  * @swagger
@@ -210,17 +240,13 @@ import config from "@/config";
 import { users } from "@/db";
 import { User } from "@/entities/user.entity";
 import { MapAsyncCache } from "@/utilities/cache/memory-cache";
+import { Injectable } from "@/utilities/container";
 
 function exceedHandler() {
   const message = "Too much call in allowed window";
   throw new ResponseError(message, 429);
 }
 
-function userNotFoundHandler(e: ResponseError) {
-  const message = "User not found.";
-  throw new ResponseError(message, 404, e?.message);
-}
-
 function invalidInputHandler(e: ResponseError) {
   const message = "Invalid input";
   throw new ResponseError(message, 400, e?.message);
@@ -229,6 +255,7 @@ function invalidInputHandler(e: ResponseError) {
 const usersCache = new MapAsyncCache<UserDto[]>(config.cacheSize);
 const userCache = new MapAsyncCache<UserDto>(config.cacheSize);
 
+@Injectable()
 /**
  * Controller for handling user-related operations
  * @class UserController

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codeweaver",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "main": "src/main.ts",
   "bin": {
     "create-codeweaver-app": "./command.js"
@@ -37,9 +37,14 @@
     "dotenv": "^17.2.3",
     "express": "^5.1.0",
     "express-async-handler": "^1.2.0",
+    "express-winston": "^4.2.0",
     "ioredis": "^5.8.2",
+    "logform": "^2.7.0",
+    "reflect-metadata": "^0.2.2",
     "swagger-jsdoc": "^3.7.0",
     "utils-decorators": "^2.10.0",
+    "winston": "^3.18.3",
+    "winston-daily-rotate-file": "^5.0.0",
     "zod": "^4.0.14"
   },
   "devDependencies": {

package/src/config.ts

@@ -4,8 +4,9 @@ import {
   rateLimitTimeSpan,
   rateLimitAllowedCalls,
   timeout,
-  portNumber,
+  port,
   cacheSize,
+  http,
 } from "./constants";
 import { SwaggerOptions } from "./swagger-options";
 import { stringToBoolean } from "./utilities/conversion";
@@ -19,6 +20,7 @@ import { stringToBoolean } from "./utilities/conversion";
  */
 interface Config {
   devMode: boolean;
+  http: string;
   port: number;
   swagger: boolean;
   swaggerOptions: SwaggerOptions;
@@ -29,11 +31,10 @@ interface Config {
   cacheSize: number;
 }
 
-const port = Number(process.env.PORT) || portNumber;
-
 let config: Config = {
   devMode: process.env.NODE_ENV !== productionEnvironment,
-  port,
+  http: process.env.HTTP || http,
+  port: Number(process.env.PORT) || port,
   swagger: stringToBoolean(process.env.SWAGGER || "true"),
   swaggerOptions: {
     swaggerDefinition: {
@@ -57,9 +58,10 @@ let config: Config = {
     ], // Path to the API docs
   },
   timeout: Number(process.env.TIMEOUT) || timeout,
-  rateLimitTimeSpan: Number(process.env.RATE_LIMIT) || rateLimitTimeSpan,
+  rateLimitTimeSpan:
+    Number(process.env.RATE_LIMIT_TIME_SPAN) || rateLimitTimeSpan,
   rateLimitAllowedCalls:
-    Number(process.env.RATE_LIMIT) || rateLimitAllowedCalls,
+    Number(process.env.RATE_LIMIT_ALLOWED_CALLS) || rateLimitAllowedCalls,
   memoizeTime: Number(process.env.MEMOIZE_TIME) || memoizeTime,
   cacheSize: Number(process.env.CACHE_SIZE) || cacheSize,
 };

package/src/constants.ts

@@ -1,7 +1,12 @@
+export const http = "http://localhost";
+export const port = 3000;
 export const timeout = 20000;
 export const rateLimitTimeSpan = 60000;
 export const rateLimitAllowedCalls = 300;
 export const memoizeTime = 1000 * 60 * 60;
 export const cacheSize = 1000;
 export const productionEnvironment = "production";
-export const portNumber = 3000;
+export const swaggerPath = "/api-docs";
+export const routerDir = "/routers";
+export const routerExtension = ".router";
+export const defaultRouter = "index";

package/src/main.ts

@@ -3,7 +3,16 @@ import fs from "fs";
 import path from "path";
 import config from "./config";
 import { ResponseError } from "./utilities/error-handling";
-require("./app");
+import { resolve } from "./utilities/container";
+import { WinstonLoggerService } from "./utilities/logger/winston-logger.service";
+import "dotenv/config";
+import {
+  defaultRouter,
+  routerDir,
+  routerExtension,
+  swaggerPath,
+} from "./constants";
+//import cors from "cors";
 
 /**
  * Recursively loads Express routers from directory
@@ -29,17 +38,20 @@ function loadRouters(routerPath: string, basePath: string = "") {
 
     // Only handle router files
     if (
-      !entry.name.endsWith(".router.ts") &&
-      !entry.name.endsWith(".router.js")
+      !entry.name.endsWith(`${routerExtension}.ts`) &&
+      !entry.name.endsWith(`${routerExtension}.js`)
     ) {
       continue;
     }
 
     // Build route path safely
     const routePath = path
-      .join(basePath, entry.name.replace(/\.router\.[tj]s$/, ""))
+      .join(
+        basePath,
+        entry.name.replace(new RegExp(`\\${routerExtension}\\.([tj]s)$`), "")
+      )
       .replace(/\\/g, "/")
-      .replace(/\/?index$/g, "");
+      .replace(new RegExp(`\\/?${defaultRouter}$`), "");
 
     // Optional: skip if the target path would be empty (maps to /)
     const mountPath = "/" + (routePath || "");
@@ -52,11 +64,12 @@ function loadRouters(routerPath: string, basePath: string = "") {
 }
 
 const app = express();
+//app.use(cors());
 app.use(express.json());
 app.use(express.urlencoded({ extended: true }));
 
 // Automatically import all routers from the /src/routers directory
-const routersPath = path.join(__dirname, "/routers");
+const routersPath = path.join(__dirname, routerDir);
 loadRouters(routersPath);
 
 // Swagger setup
@@ -64,22 +77,42 @@ if (config.swagger) {
   const swaggerJsDoc = require("swagger-jsdoc");
   const swaggerUi = require("swagger-ui-express");
   const swaggerDocs = swaggerJsDoc(config.swaggerOptions);
-  app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(swaggerDocs));
+  app.use(swaggerPath, swaggerUi.serve, swaggerUi.setup(swaggerDocs));
 }
 
+const logger = resolve(WinstonLoggerService);
+
 // General error handler
 app.use(
-  (err: ResponseError, req: Request, res: Response, next: NextFunction) => {
-    res.status(err.status ?? 500).json(err);
+  (error: ResponseError, req: Request, res: Response, next: NextFunction) => {
+    const status = error.status ?? 500;
+    const errorObject = {
+      status,
+      code: error.code,
+      input: error.input,
+      stack: error.stack,
+      cause: error.cause,
+    };
+
+    res.status(status).json(error);
+    if (status < 500) {
+      logger.warn(error.message, "Invalid request", error.details, errorObject);
+    } else {
+      if (status == 401 || status == 403) {
+        logger.fatal(error.message, "Forbidden", error.details, errorObject);
+      } else {
+        logger.error(error.message, "Server error", error.details, errorObject);
+      }
+    }
   }
 );
 
 // Start the server
 app.listen(config.port, () => {
-  console.log(`Server is running on http://localhost:${config.port}`);
+  console.log(`Server is running on ${config.http}:${config.port}`);
   if (config.devMode) {
     console.log(
-      `Swagger UI is available at http://localhost:${config.port}/api-docs`
+      `Swagger UI is available at ${config.http}:${config.port}${swaggerPath}`
     );
   }
 });

package/src/routers/orders/index.router.ts

@@ -1,9 +1,10 @@
 import { Router, Request, Response } from "express";
 import asyncHandler from "express-async-handler";
 import OrderController from "./order.controller";
+import { resolve } from "@/utilities/container";
 
 const router = Router();
-const orderController = new OrderController();
+const orderController = resolve(OrderController);
 
 /**
  * @swagger
@@ -60,7 +61,7 @@ router.post(
   asyncHandler(async (req: Request, res: Response) => {
     const order = await orderController.validateOrderCreationDto(req.body);
     await orderController.create(order);
-    res.status(201).send();;
+    res.status(201).send();
   })
 );
 

package/src/routers/orders/order.controller.ts

@@ -10,17 +10,13 @@ import config from "@/config";
 import { orders } from "@/db";
 import { Order, ZodOrder } from "@/entities/order.entity";
 import { MapAsyncCache } from "@/utilities/cache/memory-cache";
+import { Injectable } from "@/utilities/container";
 
 function exceedHandler() {
   const message = "Too much call in allowed window";
   throw new ResponseError(message, 429);
 }
 
-function orderNotFoundHandler(e: ResponseError) {
-  const message = "Order not found.";
-  throw new ResponseError(message, 404, e.message);
-}
-
 function invalidInputHandler(e: ResponseError) {
   const message = "Invalid input";
   throw new ResponseError(message, 400, e.message);
@@ -29,6 +25,7 @@ function invalidInputHandler(e: ResponseError) {
 const ordersCache = new MapAsyncCache<OrderDto[]>(config.cacheSize);
 const orderCache = new MapAsyncCache<OrderDto>(config.cacheSize);
 
+@Injectable()
 /**
  * Controller for handling order-related operations
  * @class OrderController
@@ -38,7 +35,7 @@ export default class OrderController {
   // constructor(private readonly orderService: OrderService) { }
 
   @onError({
-    func: orderNotFoundHandler,
+    func: invalidInputHandler,
   })
   /**
    * Validates a string ID and converts it to a number.

package/src/routers/products/index.router.ts

@@ -1,9 +1,10 @@
 import { Router, Request, Response } from "express";
 import asyncHandler from "express-async-handler";
 import ProductController from "./product.controller";
+import { resolve } from "@/utilities/container";
 
 const router = Router();
-const productController = new ProductController();
+const productController = resolve(ProductController);
 
 // CRUD Routes
 

package/src/routers/products/product.controller.ts

@@ -18,17 +18,13 @@ import config from "@/config";
 import { ResponseError } from "@/utilities/error-handling";
 import { products } from "@/db";
 import { Product, ZodProduct } from "@/entities/product.entity";
+import { Injectable } from "@/utilities/container";
 
 function exceedHandler() {
   const message = "Too much call in allowed window";
   throw new ResponseError(message, 429);
 }
 
-function productNotFoundHandler(e: ResponseError) {
-  const message = "Product not found.";
-  throw new ResponseError(message, 404, e.message);
-}
-
 function invalidInputHandler(e: ResponseError) {
   const message = "Invalid input";
   throw new ResponseError(message, 400, e.message);
@@ -37,6 +33,7 @@ function invalidInputHandler(e: ResponseError) {
 const productsCache = new MapAsyncCache<ProductDto[]>(config.cacheSize);
 const productCache = new MapAsyncCache<ProductDto>(config.cacheSize);
 
+@Injectable()
 /**
  * Controller for handling product-related operations
  * @class ProductController
@@ -46,7 +43,7 @@ export default class ProductController {
   // constructor(private readonly productService: ProductService) { }
 
   @onError({
-    func: productNotFoundHandler,
+    func: invalidInputHandler,
   })
   /**
    * Validates a string ID and converts it to a number.
@@ -138,9 +135,6 @@ export default class ProductController {
     keyResolver: (id: number) => id.toString(),
     expirationTimeMs: config.memoizeTime,
   })
-  @onError({
-    func: productNotFoundHandler,
-  })
   @rateLimit({
     timeSpanMs: config.rateLimitTimeSpan,
     allowedCalls: config.rateLimitAllowedCalls,

package/src/routers/users/index.router.ts

@@ -1,9 +1,10 @@
 import { Router, Request, Response } from "express";
 import asyncHandler from "express-async-handler";
 import UserController from "./user.controller";
+import { resolve } from "@/utilities/container";
 
 const router = Router();
-const userController = new UserController();
+const userController = resolve(UserController);
 
 /**
  * @swagger

package/src/routers/users/user.controller.ts

@@ -11,17 +11,13 @@ import config from "@/config";
 import { users } from "@/db";
 import { User } from "@/entities/user.entity";
 import { MapAsyncCache } from "@/utilities/cache/memory-cache";
+import { Injectable } from "@/utilities/container";
 
 function exceedHandler() {
   const message = "Too much call in allowed window";
   throw new ResponseError(message, 429);
 }
 
-function userNotFoundHandler(e: ResponseError) {
-  const message = "User not found.";
-  throw new ResponseError(message, 404, e?.message);
-}
-
 function invalidInputHandler(e: ResponseError) {
   const message = "Invalid input";
   throw new ResponseError(message, 400, e?.message);
@@ -30,6 +26,7 @@ function invalidInputHandler(e: ResponseError) {
 const usersCache = new MapAsyncCache<UserDto[]>(config.cacheSize);
 const userCache = new MapAsyncCache<UserDto>(config.cacheSize);
 
+@Injectable()
 /**
  * Controller for handling user-related operations
  * @class UserController

package/src/utilities/container.ts

@@ -0,0 +1,159 @@
+import "reflect-metadata";
+
+export type Constructor<T = any> = new (...args: any[]) => T;
+
+interface Provider<T = any> {
+  /** The concrete class to instantiate (may be the same as token or a different implementation). */
+  useClass: Constructor<T>;
+  /** Cached singleton instance, if one has been created. */
+  instance?: T;
+  /** Whether to treat the provider as a singleton. Defaults to true. */
+  singleton?: boolean;
+}
+
+const InjectableRegistry: Array<Constructor<any>> = [];
+
+/**
+ * A tiny dependency injection container.
+ *
+ * Features:
+ * - Register tokens (classes) with optional options.
+ * - Resolve instances with automatic dependency resolution via design:paramtypes metadata.
+ * - Simple singleton lifetime by default (one instance per token).
+ *
+ * Notes:
+ * - Requires reflect-metadata to be loaded and "emitDecoratorMetadata"/"experimentalDecorators"
+ *   enabled in tsconfig for design:paramtypes to exist.
+ */
+class Container {
+  private registrations = new Map<Constructor, Provider>();
+
+  /**
+   * Register a class as a provider for the given token.
+   *
+   * If no options.useClass is provided, the token itself is used as the concrete class.
+   * If options.singleton is not provided, the provider defaults to singleton = true.
+   *
+   * @param token - The token (class constructor) that represents the dependency.
+   * @param options - Optional provider options.
+   *   - useClass?: The concrete class to instantiate for this token.
+   *   - singleton?: Whether to reuse a single instance (default: true).
+   */
+  register<T>(
+    token: Constructor<T>,
+    options?: { useClass?: Constructor<T>; singleton?: boolean }
+  ): void {
+    const useClass = options?.useClass ?? token;
+    const singleton = options?.singleton ?? true;
+    this.registrations.set(token, { useClass, singleton });
+  }
+
+  /**
+   * Resolve an instance for the given token.
+   *
+   * Behavior:
+   * - If the token is not registered, attempt to instantiate directly (without DI).
+   * - If a singleton instance already exists for the token, return it.
+   * - Otherwise, resolve the concrete class (provider.useClass), construct it
+   *   by recursively resolving its constructor parameter types, and cache
+   *   the instance if singleton is true.
+   *
+   * @param token - The token (class constructor) to resolve.
+   * @returns An instance of the requested type T.
+   */
+  resolve<T>(token: Constructor<T>): T {
+    const provider = this.registrations.get(token);
+
+    if (!provider) {
+      // If not registered, try to instantiate directly (without DI)
+      return this.construct(token);
+    }
+
+    if (provider.instance) {
+      return provider.instance;
+    }
+
+    // Resolve dependencies for the concrete class
+    const target = provider.useClass;
+    const instance = this.construct(target);
+
+    if (provider.singleton) {
+      provider.instance = instance;
+    }
+
+    return instance;
+  }
+
+  /**
+   * Internal helper to instantiate a class, resolving its constructor dependencies
+   * via design:paramtypes metadata.
+   *
+   * @param constructorFunction - The constructor function of the class to instantiate.
+   * @returns A new instance of type T with dependencies injected.
+   */
+  private construct<T>(constructorFunction: Constructor<T>): T {
+    const paramTypes: any[] =
+      Reflect.getMetadata("design:paramtypes", constructorFunction) || [];
+    const args = paramTypes.map((paramType) => this.resolve(paramType));
+    return new constructorFunction(...args);
+  }
+}
+/**
+ * Bootstraps a container by wiring up all registered injectables.
+ *
+ * This helper walks the InjectableRegistry and registers each class with the container,
+ * honoring per-class options (like singleton) that may have been stored as metadata.
+ *
+ * Why this exists:
+ * - Keeps your registration centralized and automatic, so you don't have to call
+ *   container.register(...) repeatedly for every service.
+ *
+ * Usage reminder:
+ * - Ensure Reflect Metadata is loaded before calling this, so that the di:injectable
+ *   metadata is actually readable.
+ */
+function bootstrapContainer(container: Container) {
+  for (const constructorFunction of InjectableRegistry) {
+    // Read per-class options if you added metadata
+    const meta = Reflect.getMetadata("di:injectable", constructorFunction) as
+      | { singleton?: boolean }
+      | undefined;
+    const singleton = meta?.singleton ?? false;
+    container.register(constructorFunction, { singleton });
+  }
+}
+
+/**
+ * Marks a class for automatic DI registration.
+ * Options:
+ *  - singleton: whether to register as a singleton (default true)
+ *  - token: optional explicit token to register for (defaults to class constructor)
+ */
+export function Injectable(options?: {
+  singleton?: boolean;
+  token?: any;
+}): ClassDecorator {
+  return (target: any) => {
+    // Push into registry for later registration
+    InjectableRegistry.push(target);
+    // You could also attach metadata if you want to customize per-class
+    Reflect.defineMetadata("di:injectable", options ?? {}, target);
+  };
+}
+
+/** A single, shared DI container for the app. */
+const container = new Container();
+bootstrapContainer(container);
+
+/**
+ * Resolve a service wherever needed.
+ *
+ * Example
+ *
+ * import { resolve } from "@/utilities/container";
+ * const loggerService = resolve(LoggerService);
+ * loggerService.log(...);
+ */
+export function resolve<T>(token: Constructor<T>): T {
+  return container.resolve(token);
+}

package/src/utilities/error-handling.ts

@@ -154,3 +154,39 @@ export function isSuccessful<T>(result: ReturnInfo<T>): boolean {
 export function hasError<T>(result: ReturnInfo<T>): boolean {
   return result[1] !== null;
 }
+
+/**
+ * Indicates whether a ReturnInfo value represents an error.
+ *
+ * This is the logical negation of isSuccess for a given ReturnInfo.
+ *
+ * @template T
+ * @param result - The ReturnInfo tuple [value | null, error | null]
+ * @returns true if an error is present (i.e., error is not null); false otherwise
+ */
+export function then<T>(
+  result: ReturnInfo<T>,
+  callback: (object: T) => void
+): void {
+  if (isSuccessful(result)) {
+    callback(successfulResult(result)!);
+  }
+}
+
+/**
+ * Indicates whether a ReturnInfo value represents an error.
+ *
+ * This is the logical negation of isSuccess for a given ReturnInfo.
+ *
+ * @template T
+ * @param result - The ReturnInfo tuple [value | null, error | null]
+ * @returns true if an error is present (i.e., error is not null); false otherwise
+ */
+export function catchError<T>(
+  result: ReturnInfo<T>,
+  callback: (error: ResponseError) => void
+): void {
+  if (hasError(result)) {
+    callback(error(result)!);
+  }
+}

package/src/utilities/logger/base-logger.interface.ts

@@ -0,0 +1,11 @@
+// src/logging/BaseLogger.ts
+
+export type LogLevel = "fatal" | "error" | "warn" | "info" | "debug" | "trace";
+
+export interface Meta {
+  [key: string]: unknown;
+}
+
+export interface BaseLogger {
+  log(level: LogLevel, message: string, meta?: Meta): void;
+}

package/src/utilities/logger/logger.config.ts

@@ -0,0 +1,95 @@
+import * as winston from "winston";
+import { TransformableInfo } from "logform";
+import "winston-daily-rotate-file"; // Import the DailyRotateFile transport to extend winston transports
+
+// Console format: colorized and pretty printed
+// Custom formatting to include timestamp, context, level, and message
+//
+// Example: "2023-10-05T12:00:00.000Z [MyContext] info: This is a log message"
+const consoleFormat = winston.format.combine(
+  winston.format.colorize({ all: true }),
+  winston.format.timestamp(),
+  winston.format.printf(
+    ({
+      timestamp,
+      level,
+      message,
+      context,
+      ...meta
+    }: TransformableInfo): string => {
+      const contextStr = context ? `[${context as string}]` : "[main]";
+
+      const metaStr = Object.keys(meta).length ? JSON.stringify(meta) : "";
+
+      return `${timestamp as string} ${contextStr} ${level}: ${
+        message as string
+      } ${metaStr}`;
+    }
+  )
+);
+
+// File format: JSON with timestamp
+// This format is suitable for structured logging and easier parsing by
+// log management systems
+//
+// Example: {"timestamp":"2023-10-05T12:00:00.000Z", "level":"info",
+// "message":"This is a log message", "context":"MyContext"}
+const fileFormat = winston.format.combine(
+  winston.format.timestamp(),
+  winston.format.json()
+);
+
+// Console transport for logging to the console with colorized output
+// and custom formatting that includes timestamp, context, level, and message.
+const consoleTransport = new winston.transports.Console({
+  format: consoleFormat,
+});
+
+// File transport for logging to files with daily rotation.
+// It logs everything at the trace level and formats logs as JSON.
+// The logs are stored in the "logs" directory with a date pattern
+// in the filename.
+// The logs are zipped and rotated daily, keeping logs for 14 days.
+const fileTransport = new winston.transports.DailyRotateFile({
+  dirname: "logs",
+  filename: "app-%DATE%.log",
+  datePattern: "YYYY-MM-DD",
+  zippedArchive: true,
+  maxSize: "20m",
+  maxFiles: "14d",
+  level: "trace", // log everything to file / external service
+  format: fileFormat,
+});
+
+// Add custom colors for log levels to enhance console output readability
+// This allows log levels to be displayed in different colors in the console.
+// Define a custom logger with explicit levels
+const customLevels = {
+  levels: {
+    fatal: 0,
+    error: 1,
+    warn: 2,
+    info: 3,
+    debug: 4,
+    trace: 5,
+  },
+  colors: {
+    fatal: "red bold",
+    error: "red",
+    warn: "yellow",
+    info: "green",
+    debug: "blue",
+    trace: "grey",
+  },
+};
+
+winston.addColors(customLevels.colors);
+
+export const logger = winston.createLogger({
+  levels: customLevels.levels,
+  level: "trace",
+  transports: [consoleTransport, fileTransport],
+  exitOnError: false,
+  exceptionHandlers: [consoleTransport, fileTransport],
+  rejectionHandlers: [consoleTransport, fileTransport],
+});

package/src/utilities/logger/logger.service.ts

@@ -0,0 +1,122 @@
+import { BaseLogger, LogLevel, Meta } from "./base-logger.interface";
+
+/**
+ * LoggerService is a custom logger service that integrates Winston for advanced logging capabilities.
+ */
+export class LoggerService {
+  /**
+   * Constructs a new LoggerService instance.
+   *
+   * @param logger - Injected logger instance
+   */
+  public constructor(private logger: BaseLogger) {}
+
+  /**
+   * Logs an informational message with optional context and metadata.
+   * This method combines the provided metadata with the context and log level,
+   * and sends the log entry to the appropriate transports.
+   *
+   * @param message - The message to log
+   * @param context - Optional context information (e.g., module or method name)
+   * @param meta - Additional metadata to include in the log entry
+   */
+  public log(level: LogLevel, message: string, meta: Meta = {}): void {
+    meta.timestamp = new Date().toISOString();
+    this.logger.log(level, message, meta);
+  }
+
+  /**
+   * Logs an informational message with optional context and metadata.
+   * This method combines the provided metadata with the context and log level,
+   * and sends the log entry to the appropriate transports.
+   *
+   * @param message - The message to log
+   * @param context - Optional context information (e.g., module or method name)
+   * @param meta - Additional metadata to include in the log entry
+   */
+  public info(message: string, context?: string, meta: Meta = {}): void {
+    this.log("info", message, { context, ...meta });
+  }
+
+  /**
+   * Logs a fatal error message with optional trace, context, and metadata.
+   * This method combines the provided metadata with the trace and context,
+   * and sends the log entry to the appropriate transports.
+   *
+   * @param message - The fatal error message to log
+   * @param trace - Optional trace information for the error
+   * @param context - Optional context information (e.g., module or method name)
+   * @param meta - Additional metadata to include in the log entry
+   */
+  public fatal(
+    message: string,
+    context?: string,
+    trace?: string,
+    meta: Meta = {}
+  ): void {
+    this.log("fatal", message, { context, trace, ...meta });
+  }
+
+  /**
+   * Logs an error message with optional trace, context, and metadata.
+   * This method combines the provided metadata with the trace and context,
+   * and sends the log entry to the appropriate transports.
+   *
+   * @param message - The error message to log
+   * @param trace - Optional trace information for the error
+   * @param context - Optional context information (e.g., module or method name)
+   * @param meta - Additional metadata to include in the log entry
+   */
+  public error(
+    message: string,
+    context?: string,
+    trace?: string,
+    meta: Meta = {}
+  ): void {
+    this.log("error", message, { context, trace, ...meta });
+  }
+
+  /**
+   * Logs a warning message with optional context and metadata.
+   * This method combines the provided metadata with the context and log level,
+   * and sends the log entry to the appropriate transports.
+   *
+   * @param message - The warning message to log
+   * @param context - Optional context information (e.g., module or method name)
+   * @param meta - Additional metadata to include in the log entry
+   */
+  public warn(
+    message: string,
+    context?: string,
+    trace?: string,
+    ...meta: unknown[]
+  ): void {
+    this.log("warn", message, { context, trace, ...meta });
+  }
+
+  /**
+   * Logs a debug message with optional context and metadata.
+   * This method combines the provided metadata with the context and log level,
+   * and sends the log entry to the appropriate transports.
+   *
+   * @param message - The debug message to log
+   * @param context - Optional context information (e.g., module or method name)
+   * @param meta - Additional metadata to include in the log entry
+   */
+  public debug(message: string, context?: string, ...meta: unknown[]): void {
+    this.log("debug", message, { context, ...meta });
+  }
+
+  /**
+   * Logs a trace message with optional context and metadata.
+   * This method combines the provided metadata with the context and log level,
+   * and sends the log entry to the appropriate transports.
+   *
+   * @param message - The trace message to log
+   * @param context - Optional context information (e.g., module or method name)
+   * @param meta - Additional metadata to include in the log entry
+   */
+  public trace(message: string, context?: string, ...meta: unknown[]): void {
+    this.log("trace", message, { context, ...meta });
+  }
+}

package/src/utilities/logger/winston-logger.service.ts

@@ -0,0 +1,16 @@
+import { logger } from "./logger.config";
+import { Injectable } from "../container";
+import { LoggerService } from "./logger.service";
+
+@Injectable({ singleton: true })
+/**
+ * WinstonLoggerService is a custom logger service that integrates Winston for advanced logging capabilities.
+ */
+export class WinstonLoggerService extends LoggerService {
+  /**
+   * Constructs a new LoggerService instance.
+   */
+  public constructor() {
+    super(logger);
+  }
+}

package/.vscode/settings.json

@@ -1,3 +0,0 @@
-{
-  "cSpell.words": ["microframework"]
-}

package/src/app.ts

@@ -1,3 +0,0 @@
-// TODO:
-
-export = null;