codeweaver 2.0.0 → 2.2.0

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/conversion.ts

@@ -0,0 +1,158 @@
+import { z, ZodRawShape } from "zod";
+import { ResponseError } from "./error-handling";
+
+/**
+ * Helper: normalize and validate a numeric string for integer parsing.
+ * This ensures we reject non-integer strings, empty input, or inputs with extra chars.
+ */
+function parseIntegerStrict(input: string): number {
+  // Trim whitespace
+  const s = input.trim();
+
+  // Empty or just sign is invalid
+  if (s.length === 0 || s === "+" || s === "-") {
+    throw new Error("Invalid integer");
+  }
+
+  // Use a regex to ensure the entire string is an optional sign followed by digits
+  if (!/^[+-]?\d+$/.test(s)) {
+    throw new Error("Invalid integer");
+  }
+
+  // Safe parse
+  const n = Number(s);
+  if (!Number.isSafeInteger(n)) {
+    throw new Error("Integer out of safe range");
+  }
+
+  return n;
+}
+
+/**
+ * Parses a string input into an integer number with strict validation.
+ *
+ * If parsing fails, this function throws a ResponseError describing the invalid input.
+ *
+ * @param input - The string to parse as an integer
+ * @returns The parsed integer
+ * @throws {ResponseError} When the input cannot be parsed as an integer
+ */
+export function stringToInteger(input: string): number {
+  try {
+    return parseIntegerStrict(input);
+  } catch {
+    throw new ResponseError(
+      "The input parameter must be a valid integer.",
+      400
+    );
+  }
+}
+
+/**
+ * Parses a string input into a boolean with explicit validation.
+ *
+ * Accepted true values: "true", "1", "yes", case-insensitive
+ * Accepted false values: "false", "0", "no", case-insensitive
+ * Any other input is invalid.
+ *
+ * If parsing fails, this function throws a ResponseError describing the invalid input.
+ *
+ * @param input - The string to parse as a boolean
+ * @returns The parsed boolean
+ * @throws {ResponseError} When the input cannot be parsed as a boolean
+ */
+export function stringToBoolean(input: string): boolean {
+  const s = input.trim().toLowerCase();
+
+  if (["true", "1", "yes", "y"].includes(s)) {
+    return true;
+  }
+  if (["false", "0", "no", "n"].includes(s)) {
+    return false;
+  }
+
+  throw new ResponseError(
+    "The input parameter must be a boolean (e.g., true/false, 1/0).",
+    400
+  );
+}
+
+/**
+ * Parses a string input into a number with basic validation.
+ *
+ * If parsing fails, this function throws a ResponseError describing the invalid input.
+ *
+ * @param input - The string to parse as a number
+ * @returns The parsed number
+ * @throws {ResponseError} When the input cannot be parsed as a number
+ */
+export function stringToNumber(input: string): number {
+  try {
+    // Trim and convert
+    const n = Number(input.trim());
+
+    // Allow finite numbers only
+    if (!Number.isFinite(n)) {
+      throw new Error("Invalid number");
+    }
+
+    return n;
+  } catch {
+    throw new ResponseError("The input parameter must be a valid number.", 400);
+  }
+}
+
+/**
+ * Strictly convert obj (type T1) to T2 using a Zod schema.
+ *
+ * - Extras in obj are ignored (no throw).
+ * - Validates fields with the schema; on failure, throws with a descriptive message.
+ * - Returns an object typed as T2 (inferred from the schema).
+ *
+ * @param obj - Source object of type T1
+ * @param schema - Zod schema describing the target type T2
+ * @returns T2 inferred from the provided schema
+ */
+export function convert<T1 extends object, T2 extends object>(
+  obj: T1,
+  schema: z.ZodObject<any>
+): T2 {
+  // 1) Derive the runtime keys from the schema's shape
+  const shape = (schema as any)._def?.shape as ZodRawShape | undefined;
+  if (!shape) {
+    throw new ResponseError(
+      "convertStrictlyFromSchema: provided schema has no shape.",
+      500
+    );
+  }
+
+  const keysSchema = Object.keys(shape) as Array<keyof any>;
+
+  // 2) Build a plain object to pass through Zod for validation
+  // Include only keys that exist on the schema (ignore extras in obj)
+  const candidate: any = {};
+  for (const k of keysSchema) {
+    if ((obj as any).hasOwnProperty(k)) {
+      candidate[k] = (obj as any)[k];
+    }
+  }
+
+  // 3) Validate against the schema
+  const result = schema.safeParse(candidate);
+  if (!result.success) {
+    // Modern, non-format error reporting
+    const issues = result.error.issues.map((i) => ({
+      path: i.path, // where the issue occurred
+      message: i.message, // human-friendly message
+      code: i.code, // e.g., "too_small", "invalid_type"
+    }));
+    // You can log issues or throw a structured error
+    throw new ResponseError(
+      `convertStrictlyFromSchema: validation failed: ${JSON.stringify(issues)}`,
+      500
+    );
+  }
+
+  // 4) Return the validated data typed as T2
+  return result.data as T2;
+}

package/src/utilities/error-handling.ts

@@ -1,5 +1,53 @@
 import { Response } from "express";
-import { ReturnInfo, ResponseError } from "./types";
+
+/**
+ * Represents a standardized error response structure for API endpoints.
+ *
+ * This class models an API-friendly error, carrying a human message plus
+ * optional metadata (status, details, input, code, stack). Extends the built-in Error
+ * so it works naturally with try/catch blocks.
+ */
+export class ResponseError extends Error {
+  public constructor(
+    /**
+     * User-facing error message describing what went wrong.
+     */
+    public message: string,
+
+    /**
+     * Optional HTTP status code related to the error (e.g., 400, 404, 500).
+     */
+    public status?: number,
+
+    /**
+     * Optional human-readable details or context about the error.
+     */
+    public details?: string,
+
+    /**
+     * Optional input value that caused the error (useful for logging/diagnostics).
+     */
+    public input?: string,
+
+    /**
+     * Optional application-specific error code (e.g., "INVALID_INPUT").
+     */
+    public code?: string,
+
+    /**
+     * Optional stack trace string (usually provided by runtime).
+     * Note: In many environments, stack is inherited from Error; you may
+     * not need to redefine it here unless you have a specific reason.
+     */
+    public stack?: string
+  ) {
+    // Ensure the base Error class gets the message for standard properties like name, stack, etc.
+    super(message);
+
+    // If a custom stack is provided, you might assign it; otherwise, the runtime stack will be used.
+    if (stack) this.stack = stack;
+  }
+}
 
 /**
  * Sends a standardized HTTP error response.
@@ -14,6 +62,18 @@ export function sendHttpError(res: Response, error: ResponseError): void {
   res.status(error.status ?? 500).json(error);
 }
 
+/**
+ * A generic alias representing a tuple of [result, error].
+ * - result is either T or null if an error occurred
+ * - error is either a ResponseError or null if the operation succeeded
+ */
+export type ReturnInfo<T> = [T | null, ResponseError | null];
+
+/**
+ * A Promise-wrapped version of ReturnInfo.
+ */
+export type AsyncReturnInfo<T> = Promise<ReturnInfo<T>>;
+
 /**
  * Executes a function and captures a potential error as a ReturnInfo tuple.
  *
@@ -29,7 +89,7 @@ export function sendHttpError(res: Response, error: ResponseError): void {
  * @param error - The error object to return when an exception occurs (typically a ResponseError). If no error is provided, null is used.
  * @returns ReturnInfo<T> A tuple: [value or null, error or null]
  */
-export function tryCatch<T>(
+export function invoke<T>(
   func: () => T,
   error: ResponseError | null
 ): ReturnInfo<T> {
@@ -40,30 +100,6 @@ export function tryCatch<T>(
   }
 }
 
-/**
- * Parses a string input into a number (ID) with basic validation.
- *
- * If parsing fails, this function throws a ResponseError describing the invalid input.
- *
- * @param input - The string to parse as an integer ID
- * @returns The parsed number
- * @throws {ResponseError} When the input cannot be parsed as an integer
- */
-export function parseId(input: string): number {
-  try {
-    // parseInt may yield NaN for non-numeric input; this example mirrors the original behavior
-    // If you want stricter validation, you can check isNaN and throw a more explicit error.
-    return parseInt(input);
-  } catch {
-    throw new ResponseError(
-      input,
-      400,
-      "Wrong input",
-      "The id parameter must be an integer number."
-    );
-  }
-}
-
 /**
  * Creates a successful result from a ReturnInfo tuple.
  *
@@ -118,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 });
+  }
+}