codeweaver 1.1.0 → 2.1.0

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

@@ -1,89 +1,35 @@
-import { User, ZodUserCreationDto, UserCreationDto } from "./dto/user.dto";
-import { onError, rateLimit, timeout } from "utils-decorators";
-import { Validate, ZodInput } from "@pkg/ts-zod-decorators";
-import { ResponseError } from "@/types";
-import { tryParseId } from "@/utilities";
-
-// Array to store users (as a mock database)
-const users = [
-  {
-    id: 1,
-    username: "johndoe",
-    email: "johndoe@gmail.com",
-    password: "S3cur3P@ssw0rd",
-  },
-  {
-    id: 2,
-    username: "janesmith",
-    email: "janesmith@yahoo.com",
-    password: "P@ssw0rd2024",
-  },
-  {
-    id: 3,
-    username: "michael89",
-    email: "michael89@hotmail.com",
-    password: "M1chael!2024",
-  },
-  {
-    id: 4,
-    username: "lisa.wong",
-    email: "lisa.wong@example.com",
-    password: "L1saW0ng!2024",
-  },
-  {
-    id: 5,
-    username: "alex_k",
-    email: "alex.k@gmail.com",
-    password: "A1ex#Key2024",
-  },
-  {
-    id: 6,
-    username: "emilyj",
-    email: "emilyj@hotmail.com",
-    password: "Em!ly0101",
-  },
-  {
-    id: 7,
-    username: "davidparker",
-    email: "david.parker@yahoo.com",
-    password: "D@v!d2024",
-  },
-  {
-    id: 8,
-    username: "sophia_m",
-    email: "sophia.m@gmail.com",
-    password: "Sophi@2024",
-  },
-  {
-    id: 9,
-    username: "chrisw",
-    email: "chrisw@outlook.com",
-    password: "Chri$Wong21",
-  },
-  {
-    id: 10,
-    username: "natalie_b",
-    email: "natalie_b@gmail.com",
-    password: "N@talie#B2024",
-  },
-];
+import {
+  ZodUserCreationDto,
+  UserCreationDto,
+  UserDto,
+  ZodUserDto,
+} from "./dto/user.dto";
+import { memoizeAsync, onError, rateLimit, timeout } from "utils-decorators";
+import { ResponseError } from "@/utilities/error-handling";
+import { convert, stringToInteger } from "@/utilities/conversion";
+import config from "@/config";
+import { users } from "@/db";
+import { User } from "@/entities/user.entity";
+import { MapAsyncCache } from "@/utilities/cache/memory-cache";
 
 function exceedHandler() {
   const message = "Too much call in allowed window";
-
-  throw new Error(message, {
-    cause: { status: 500, message } satisfies ResponseError,
-  });
+  throw new ResponseError(message, 429);
 }
 
-function getUserErrorHandler(e: Error) {
+function userNotFoundHandler(e: ResponseError) {
   const message = "User not found.";
+  throw new ResponseError(message, 404, e?.message);
+}
 
-  throw new Error(message, {
-    cause: { status: 404, message, details: e.message } satisfies ResponseError,
-  });
+function invalidInputHandler(e: ResponseError) {
+  const message = "Invalid input";
+  throw new ResponseError(message, 400, e?.message);
 }
 
+const usersCache = new MapAsyncCache<UserDto[]>(config.cacheSize);
+const userCache = new MapAsyncCache<UserDto>(config.cacheSize);
+
 /**
  * Controller for handling user-related operations
  * @class UserController
@@ -92,70 +38,93 @@ function getUserErrorHandler(e: Error) {
 export default class UserController {
   // constructor(private readonly userService: UserService) { }
 
+  @onError({
+    func: invalidInputHandler,
+  })
+  /**
+   * Validates a string ID and converts it to a number.
+   *
+   * @param {string} id - The ID to validate and convert.
+   * @returns {number} The numeric value of the provided ID.
+   */
+  public async validateId(id: string): Promise<number> {
+    return stringToInteger(id);
+  }
+
+  @onError({
+    func: invalidInputHandler,
+  })
+  /**
+   * Validates and creates a new User from the given DTO.
+   *
+   * @param {UserCreationDto} user - The incoming UserCreationDto to validate and transform.
+   * @returns {User} A fully formed User object ready for persistence.
+   */
+  public async validateUserCreationDto(user: UserCreationDto): Promise<User> {
+    const newUser = await ZodUserCreationDto.parseAsync(user);
+    return { ...newUser, id: users.length + 1 };
+  }
+
   @rateLimit({
-    timeSpanMs: 60000,
-    allowedCalls: 300,
+    timeSpanMs: config.rateLimitTimeSpan,
+    allowedCalls: config.rateLimitAllowedCalls,
     exceedHandler,
   })
-  @Validate
   /**
    * Create a new user
-   * @param {UserCreationDto} user - User creation data validated by Zod schema
+   * @param {User} user - User creation data validated by Zod schema
    * @returns {Promise<void>}
    * @throws {ResponseError} 500 - When rate limit exceeded
    * @throws {ResponseError} 400 - Invalid input data
    */
-  public async create(@ZodInput(ZodUserCreationDto) user: UserCreationDto) {
-    users.push({ ...user, id: users.length + 1 } satisfies User);
+  public async create(user: User): Promise<void> {
+    users.push(user);
+    await userCache.set(user.id.toString(), user as User);
+    await usersCache.delete("key");
   }
 
-  @onError({
-    func: getUserErrorHandler,
+  @memoizeAsync({
+    cache: usersCache,
+    keyResolver: () => "key",
+    expirationTimeMs: config.memoizeTime,
   })
+  @timeout(config.timeout)
   @rateLimit({
-    timeSpanMs: 60000,
-    allowedCalls: 300,
+    timeSpanMs: config.rateLimitTimeSpan,
+    allowedCalls: config.rateLimitAllowedCalls,
     exceedHandler,
   })
   /**
-   * Get user by ID
-   * @param {string} id - User ID as string
-   * @returns {Promise<User | ResponseError>} User details or error object
-   * @throws {ResponseError} 404 - User not found
-   * @throws {ResponseError} 400 - Invalid ID format
+   * Get all users
+   * @returns {Promise<UserDto[]>} List of users with hidden password fields
+   * @throws {ResponseError} 500 - When rate limit exceeded
    */
-  public async get(id: string): Promise<User | ResponseError> {
-    const userId = tryParseId(id);
-    if (typeof userId != "number") return userId satisfies ResponseError;
-    const user = users.find((user) => user.id === userId);
-
-    if (!user)
-      return {
-        status: 404,
-        message: "User dose not exist.",
-      } satisfies ResponseError;
-
-    return user satisfies User;
+  public async getAll(): Promise<UserDto[]> {
+    return users as UserDto[];
   }
 
-  @timeout(20000)
+  @memoizeAsync({
+    cache: userCache,
+    keyResolver: (id: number) => id.toString(),
+    expirationTimeMs: config.memoizeTime,
+  })
   @rateLimit({
-    timeSpanMs: 60000,
-    allowedCalls: 300,
+    timeSpanMs: config.rateLimitTimeSpan,
+    allowedCalls: config.rateLimitAllowedCalls,
     exceedHandler,
   })
   /**
-   * Get all users with masked passwords
-   * @returns {Promise<User[]>} List of users with hidden password fields
-   * @throws {ResponseError} 500 - When rate limit exceeded
+   * Get user by ID
+   * @param {number} id - User ID as string
+   * @returns {Promise<UserDto>} User details or error object
+   * @throws {ResponseError} 404 - User not found
+   * @throws {ResponseError} 400 - Invalid ID format
    */
-  public async getAll(): Promise<User[]> {
-    return users.map(
-      (user) =>
-        ({
-          ...user,
-          password: "?",
-        } satisfies User)
-    );
+  public async get(id: number): Promise<UserDto> {
+    const user = users.find((user) => user.id === id);
+    if (user == null) {
+      throw new ResponseError("Product not found");
+    }
+    return convert(user!, ZodUserDto);
   }
 }

package/src/swagger-options.ts

@@ -0,0 +1,39 @@
+/**
+ * Server configuration interface
+ */
+interface Server {
+  /** URL of the base server */
+  url: string;
+}
+
+/**
+ * API information structure
+ */
+interface Info {
+  /** Title of the API */
+  title: string;
+  /** Version of the API */
+  version: string;
+  /** Description of the API */
+  description: string;
+}
+
+/**
+ * Swagger definition structure
+ */
+interface SwaggerDefinition {
+  /** OpenAPI specification version (e.g., "3.0.0") */
+  openApi: string;
+  /** API information object */
+  info: Info;
+  /** List of server configurations */
+  servers: Server[];
+}
+
+/**
+ * Swagger configuration options
+ */
+export interface SwaggerOptions {
+  swaggerDefinition: SwaggerDefinition;
+  apis: string[];
+}

package/src/utilities/assign.ts

@@ -0,0 +1,66 @@
+import { z, ZodRawShape } from "zod";
+import { ResponseError } from "./error-handling";
+
+/**
+ * Strictly assign obj (type T1) to T2 using a Zod schema.
+ *
+ * - Extras in source 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 source - Source object of type T1
+ * @param destination - Destination object to be populated (typed as T2)
+ * @param schema - Zod schema describing the target type T2
+ * @returns T2 representing the destination after assignment
+ */
+export default function assign<T1 extends object, T2 extends object>(
+  source: T1,
+  destination: T2,
+  schema: z.ZodObject<any>,
+  ignoreNullAndUndefined: false
+): T2 {
+  // 1) Validate the subset of keys defined in the schema
+  // Build an object that contains only the keys present in source but are part of the schema
+  const subsetForSchema: any = {};
+
+  // Iterate schema keys
+  for (const key of Object.keys(schema.shape)) {
+    if (Object.prototype.hasOwnProperty.call(source, key)) {
+      if (ignoreNullAndUndefined) {
+        subsetForSchema[key] = (source as any)[key] ?? subsetForSchema[key];
+      } else {
+        subsetForSchema[key] = (source as any)[key];
+      }
+    }
+  }
+
+  // Validate using the schema on the subset (this will also coerce if the schema has transforms)
+  const parseResult = schema.safeParse(subsetForSchema);
+  if (!parseResult.success) {
+    // Build a descriptive error message from the first issue
+    const issue = parseResult.error.issues?.[0];
+    const path = issue?.path?.length ? issue.path.join(".") : "value";
+    const message = issue?.message ?? "Schema validation failed";
+    throw new ResponseError(
+      `assignStrictlyFromSchema: Validation failed for "${path}": ${message}`,
+      500
+    );
+  }
+
+  // 2) Assign validated values to destination strictly
+  // Use the parsed result to ensure types align with the schema
+  const validated = parseResult.data as any;
+
+  // Copy only keys that are in the schema
+  for (const key of Object.keys(schema.shape)) {
+    if (Object.prototype.hasOwnProperty.call(validated, key)) {
+      if (ignoreNullAndUndefined) {
+        subsetForSchema[key] = (source as any)[key] ?? subsetForSchema[key];
+      } else {
+        subsetForSchema[key] = (source as any)[key];
+      }
+    }
+  }
+
+  return destination;
+}

package/src/utilities/cache/memory-cache.ts

@@ -0,0 +1,74 @@
+import { AsyncCache } from "utils-decorators";
+
+/**
+ * A simple in-memory map-based cache implementing AsyncCache<T>.
+ * This is a straightforward wrapper around a Map<string, T>.
+ */
+export class MapAsyncCache<T> implements AsyncCache<T> {
+  public constructor(
+    private capacity?: number,
+    private cache?: Map<string, T>
+  ) {
+    this.capacity = this.capacity ?? Number.POSITIVE_INFINITY;
+    this.cache = this.cache ?? new Map<string, T>();
+  }
+
+  /**
+   * Asynchronously set a value by key.
+   * @param key The cache key
+   * @param value The value to cache
+   */
+  async set(key: string, value: T): Promise<void> {
+    if (value != null) {
+      if (this.cache?.has(key)) {
+        this.cache?.set(key, value);
+      } else {
+        if (
+          (this.capacity ?? Number.POSITIVE_INFINITY) > (this.cache?.size ?? 0)
+        ) {
+          this.cache?.set(key, value);
+        }
+      }
+    } else {
+      this.cache?.delete(key);
+    }
+  }
+
+  /**
+   * Asynchronously get a value by key.
+   * - If the key exists, returns the value.
+   * - If the key does not exist, returns undefined cast to T to satisfy the Promise<T> return type.
+   *
+   * Note: Returning undefined may be surprising for callers expecting a strict A/B.
+   * Consider returning `T | undefined` from AsyncCache if you can adjust the interface,
+   * or throw a ResponseError for "not found" depending on your usage.
+   */
+  async get(key: string): Promise<T> {
+    if (this.cache?.has(key)) {
+      return this.cache?.get(key) ?? (null as T);
+    }
+
+    return null as T;
+  }
+
+  /**
+   * Asynchronously delete a value by key.
+   */
+  async delete(key: string): Promise<void> {
+    this.cache?.delete(key);
+  }
+
+  /**
+   * Asynchronously check if a key exists in the cache.
+   */
+  async has(key: string): Promise<boolean> {
+    return this.cache?.has(key) ?? false;
+  }
+
+  /**
+   * Asynchronously clear the cache.
+   */
+  async clear(key: string): Promise<void> {
+    this.cache?.clear();
+  }
+}

package/src/utilities/cache/redis-cache.ts

@@ -0,0 +1,111 @@
+import { AsyncCache } from "utils-decorators";
+import { Redis } from "ioredis";
+
+/**
+ * A Redis-backed cache adapter implementing AsyncCache<T | null>.
+ * This wraps a Redis instance and provides a similar API to MapAsyncCache.
+ */
+export class RedisCache<T> implements AsyncCache<T> {
+  public constructor(
+    private cache?: Redis,
+    private capacity?: number,
+    private namespace?: string
+  ) {
+    this.cache = this.cache ?? new Redis();
+    this.capacity = this.capacity ?? Number.POSITIVE_INFINITY;
+    this.namespace = this.namespace ?? "redis";
+  }
+
+  private keyFor(key: string): string {
+    return `${this.namespace}:${key}`;
+  }
+
+  /**
+   * Asynchronously set a value by key.
+   * If value is null, delete the key to represent "not present".
+   * Capacity is not strictly enforced in Redis on a per-key basis here; you
+   * could leverage Redis max memory and eviction policies for that.
+   */
+  async set(key: string, value: T): Promise<void> {
+    const k = this.keyFor(key);
+
+    if (value != null) {
+      if (await this.has(key)) {
+        await this.cache?.set(k, JSON.stringify(value));
+      } else {
+        if (
+          (this.capacity ?? Number.POSITIVE_INFINITY) >
+          ((await this.cache?.dbsize()) ?? 0)
+        ) {
+          await this.cache?.set(k, JSON.stringify(value));
+        }
+      }
+    } else {
+      await this.cache?.del(k);
+    }
+  }
+
+  /**
+   * Asynchronously get a value by key.
+   * - If the key exists, returns the parsed value.
+   * - If the key does not exist, returns null to satisfy Promise<T | null>.
+   */
+  async get(key: string): Promise<T> {
+    const k = this.keyFor(key);
+    const raw = (await this.cache?.get(k)) ?? null;
+    if (raw == null) {
+      return null as T;
+    }
+    try {
+      return JSON.parse(raw) as T;
+    } catch {
+      return raw as T;
+    }
+  }
+
+  /**
+   * Asynchronously delete a value by key.
+   */
+  async delete(key: string): Promise<void> {
+    await this.cache?.del(this.keyFor(key));
+  }
+
+  /**
+   * Asynchronously check if a key exists in the cache.
+   */
+  async has(key: string): Promise<boolean> {
+    const exists = await this.cache?.exists(this.keyFor(key));
+    return exists === 1;
+  }
+
+  /**
+   * Asynchronously clear the cache (namespace-scoped).
+   * Use with caution in a shared Redis instance.
+   */
+  async clear(key: string): Promise<void> {
+    // Optional: implement namespace-wide clear if needed
+    // This simple example uses a pattern-based approach for a full clear.
+    const pattern = `${this.namespace}:*${key ? "" : ""}`;
+    const stream = this.cache?.scanStream({ match: pattern });
+    const pipeline = this.cache?.pipeline();
+    stream?.on("data", (keys: string[]) => {
+      if (keys.length) {
+        pipeline?.del(keys);
+      }
+    });
+    await new Promise<void>((resolve, reject) => {
+      stream?.on("end", async () => {
+        await pipeline?.exec();
+        resolve();
+      });
+      stream?.on("error", (err) => reject(err));
+    });
+  }
+
+  /**
+   * Optional: gracefully close the Redis connection.
+   */
+  async close(): Promise<void> {
+    await this.cache?.quit();
+  }
+}

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;
+}