codeweaver 1.1.0 → 2.0.0

package/src/routers/products/{index.ts → index.router.ts}

@@ -1,7 +1,6 @@
 import { Router, Request, Response } from "express";
 import asyncHandler from "express-async-handler";
 import ProductController from "./product.controller";
-import { sendError } from "@/utilities";
 
 const router = Router();
 const productController = new ProductController();
@@ -105,9 +104,7 @@ router.get(
   "/:id",
   asyncHandler(async (req: Request, res: Response) => {
     const product = await productController.get(req.params.id);
-
-    if ("id" in product == false) sendError(res, product);
-    else res.json(product);
+    res.json(product);
   })
 );
 
@@ -168,9 +165,7 @@ router.put(
   "/:id",
   asyncHandler(async (req: Request, res: Response) => {
     const product = await productController.update(req.params.id, req.body);
-
-    if ("id" in product == false) sendError(res, product);
-    else res.json(product);
+    res.json(product);
   })
 );
 
@@ -198,9 +193,7 @@ router.delete(
   "/:id",
   asyncHandler(async (req: Request, res: Response) => {
     const product = await productController.delete(req.params.id);
-
-    if ("id" in product == false) sendError(res, product);
-    else res.json(product);
+    res.json(product);
   })
 );
 

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

@@ -1,14 +1,16 @@
-import { onError, rateLimit, timeout } from "utils-decorators";
+import { memoizeAsync, onError, rateLimit, timeout } from "utils-decorators";
 import {
   Product,
   ProductCreationDto,
+  ProductDto,
   ProductUpdateDto,
   ZodProductCreationDto,
   ZodProductUpdateDto,
 } from "./dto/product.dto";
-import { Validate, ZodInput } from "@pkg/ts-zod-decorators";
-import { ResponseError } from "@/types";
-import { tryParseId } from "@/utilities";
+import { Validate, ZodInput } from "ts-zod4-decorators";
+import { ResponseError } from "@/utilities/types";
+import { parseId } from "@/utilities/error-handling";
+import config from "@/config";
 
 // Array to store products (as a mock database)
 const products: Product[] = [
@@ -89,18 +91,12 @@ const products: Product[] = [
 
 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 getProductErrorHandler(e: Error) {
-  const message = "User not found.";
-
-  throw new Error(message, {
-    cause: { status: 404, message, details: e.message } satisfies ResponseError,
-  });
+  const message = "Product not found.";
+  throw new ResponseError(message, 404, e.message);
 }
 
 /**
@@ -110,8 +106,8 @@ function getProductErrorHandler(e: Error) {
  */
 export default class ProductController {
   @rateLimit({
-    timeSpanMs: 60000,
-    allowedCalls: 300,
+    timeSpanMs: config.rateLimitTimeSpan,
+    allowedCalls: config.rateLimitAllowedCalls,
     exceedHandler,
   })
   @Validate
@@ -122,41 +118,40 @@ export default class ProductController {
    */
   public async create(
     @ZodInput(ZodProductCreationDto) product: ProductCreationDto
-  ) {
+  ): Promise<ProductDto> {
     products.push({
       ...product,
       id: products.length + 1,
     } satisfies Product);
 
-    return product;
+    return product as ProductDto;
   }
 
-  @timeout(20000)
+  @memoizeAsync(config.memoizeTime)
+  @timeout(config.timeout)
   @rateLimit({
-    timeSpanMs: 60000,
-    allowedCalls: 300,
+    timeSpanMs: config.rateLimitTimeSpan,
+    allowedCalls: config.rateLimitAllowedCalls,
     exceedHandler,
   })
   /**
    * Retrieves all products with truncated descriptions
    * @returns List of products with summarized descriptions
    */
-  public async getAll(): Promise<Product[]> {
-    return products.map(
-      (product) =>
-        ({
-          ...product,
-          description: product.description?.substring(0, 50) + "..." || "",
-        } satisfies Product)
-    );
+  public async getAll(): Promise<ProductDto[]> {
+    return products.map((product) => ({
+      ...product,
+      description: product.description?.substring(0, 50) + "..." || "",
+    }));
   }
 
+  @memoizeAsync(config.memoizeTime)
   @onError({
     func: getProductErrorHandler,
   })
   @rateLimit({
-    timeSpanMs: 60000,
-    allowedCalls: 300,
+    timeSpanMs: config.rateLimitTimeSpan,
+    allowedCalls: config.rateLimitAllowedCalls,
     exceedHandler,
   })
   /**
@@ -164,23 +159,16 @@ export default class ProductController {
    * @param id - Product ID as string
    * @returns Product details or error object if not found
    */
-  public async get(id: string): Promise<Product | ResponseError> {
-    const productId = tryParseId(id);
-    if (typeof productId != "number") return productId satisfies ResponseError;
+  public async get(id: string): Promise<ProductDto> {
+    const productId = parseId(id);
     const product = products.find((product) => product.id === productId);
-
-    if (!product)
-      return {
-        status: 404,
-        message: "Product dose not exist.",
-      } satisfies ResponseError;
-
-    return product satisfies Product;
+    if (product == null) throw new ResponseError("User dose not exist.", 404);
+    return product;
   }
 
   @rateLimit({
-    timeSpanMs: 60000,
-    allowedCalls: 300,
+    timeSpanMs: config.rateLimitTimeSpan,
+    allowedCalls: config.rateLimitAllowedCalls,
     exceedHandler,
   })
   @Validate
@@ -188,50 +176,42 @@ export default class ProductController {
    * Updates an existing product
    * @param {string} id - Product ID to update
    * @param {ProductUpdateDto} updateData - Partial product data to update
-   * @returns {Promise<Product | ResponseError>} Updated product or error object
+   * @returns {Promise<Product>} Updated product or error object
    * @throws {ResponseError} 404 - Product not found
    * @throws {ResponseError} 400 - Invalid ID format or update data
    */
   public async update(
     id: string,
     @ZodInput(ZodProductUpdateDto) updateData: ProductUpdateDto
-  ): Promise<Product | ResponseError> {
+  ): Promise<ProductDto> {
     const product = await this.get(id);
     if ("id" in product == false) return product satisfies ResponseError;
 
-    if (product) Object.assign(product, updateData);
-    else
-      return {
-        status: 404,
-        message: "Product not found",
-      } satisfies ResponseError;
+    if (product) {
+      Object.assign(product, updateData);
+    } else {
+      throw new ResponseError("Product dose not exist.", 404);
+    }
 
     return product;
   }
 
   @rateLimit({
-    timeSpanMs: 60000,
-    allowedCalls: 300,
+    timeSpanMs: config.rateLimitTimeSpan,
+    allowedCalls: config.rateLimitAllowedCalls,
     exceedHandler,
   })
   /**
    * Deletes a product by ID
    * @param {string} id - Product ID to delete
-   * @returns {Promise<Product | ResponseError>} Deleted product or error object
+   * @returns {Promise<Product>} Deleted product or error object
    * @throws {ResponseError} 404 - Product not found
    * @throws {ResponseError} 400 - Invalid ID format
    */
-  public async delete(id: string): Promise<Product | ResponseError> {
-    const productId = tryParseId(id);
-    if (typeof productId != "number") return productId satisfies ResponseError;
+  public async delete(id: string): Promise<ProductDto> {
+    const productId = parseId(id);
     const index = products.findIndex((product) => product.id === productId);
-
-    if (index == -1)
-      return {
-        status: 404,
-        message: "Product dose not exist.",
-      } satisfies ResponseError;
-
-    return products.splice(index, 1)[0] satisfies Product;
+    if (index == -1) throw new ResponseError("Product dose not exist.", 404);
+    return products.splice(index, 1)[0];
   }
 }

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

@@ -11,11 +11,13 @@ import { z } from "zod";
 export const ZodUser = z.object({
   id: z.number().min(1).int(),
   username: z.string().min(3),
-  email: z.string().email(),
+  email: z.email(),
   password: z.string().min(6),
 });
 
 export const ZodUserCreationDto = ZodUser.omit({ id: true });
+export const ZodUserDto = ZodUser.omit({ password: true });
 
 export type User = z.infer<typeof ZodUser>;
 export type UserCreationDto = z.infer<typeof ZodUserCreationDto>;
+export type UserDto = z.infer<typeof ZodUserDto>;

package/src/routers/users/{index.ts → index.router.ts}

@@ -1,7 +1,6 @@
 import { Router, Request, Response } from "express";
 import asyncHandler from "express-async-handler";
 import UserController from "./user.controller";
-import { sendError } from "@/utilities";
 
 const router = Router();
 const userController = new UserController();
@@ -73,9 +72,7 @@ router.get(
   "/:id",
   asyncHandler(async (req: Request, res: Response) => {
     const user = await userController.get(req.params.id);
-
-    if ("id" in user == false) sendError(res, user);
-    else res.json(user);
+    res.json(user);
   })
 );
 

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

@@ -1,8 +1,14 @@
-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";
+import {
+  User,
+  ZodUserCreationDto,
+  UserCreationDto,
+  UserDto,
+} from "./dto/user.dto";
+import { memoizeAsync, onError, rateLimit, timeout } from "utils-decorators";
+import { Validate, ZodInput } from "ts-zod4-decorators";
+import { ResponseError } from "@/utilities/types";
+import { parseId } from "@/utilities/error-handling";
+import config from "@/config";
 
 // Array to store users (as a mock database)
 const users = [
@@ -70,18 +76,12 @@ const users = [
 
 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) {
   const message = "User not found.";
-
-  throw new Error(message, {
-    cause: { status: 404, message, details: e.message } satisfies ResponseError,
-  });
+  throw new ResponseError(message, 404, e.message);
 }
 
 /**
@@ -93,8 +93,8 @@ export default class UserController {
   // constructor(private readonly userService: UserService) { }
 
   @rateLimit({
-    timeSpanMs: 60000,
-    allowedCalls: 300,
+    timeSpanMs: config.rateLimitTimeSpan,
+    allowedCalls: config.rateLimitAllowedCalls,
     exceedHandler,
   })
   @Validate
@@ -106,42 +106,37 @@ export default class UserController {
    * @throws {ResponseError} 400 - Invalid input data
    */
   public async create(@ZodInput(ZodUserCreationDto) user: UserCreationDto) {
-    users.push({ ...user, id: users.length + 1 } satisfies User);
+    users.push({ ...user, id: users.length + 1 });
   }
 
+  @memoizeAsync(config.memoizeTime)
   @onError({
     func: getUserErrorHandler,
   })
   @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
+   * @returns {Promise<User>} User details or error object
    * @throws {ResponseError} 404 - User not found
    * @throws {ResponseError} 400 - Invalid ID format
    */
-  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;
-
+  public async get(id: string): Promise<UserDto> {
+    const response = parseId(id);
+    const user = users.find((user) => user.id === response);
+    if (user == null) throw new ResponseError("User dose not exist.", 404);
     return user satisfies User;
   }
 
-  @timeout(20000)
+  @memoizeAsync(config.memoizeTime)
+  @timeout(config.timeout)
   @rateLimit({
-    timeSpanMs: 60000,
-    allowedCalls: 300,
+    timeSpanMs: config.rateLimitTimeSpan,
+    allowedCalls: config.rateLimitAllowedCalls,
     exceedHandler,
   })
   /**
@@ -149,13 +144,10 @@ export default class UserController {
    * @returns {Promise<User[]>} List of users with hidden password fields
    * @throws {ResponseError} 500 - When rate limit exceeded
    */
-  public async getAll(): Promise<User[]> {
-    return users.map(
-      (user) =>
-        ({
-          ...user,
-          password: "?",
-        } satisfies User)
-    );
+  public async getAll(): Promise<UserDto[]> {
+    return users.map((user) => ({
+      ...user,
+      password: "?",
+    }));
   }
 }

package/src/swagger-options.ts

@@ -0,0 +1,54 @@
+import {
+  memoizeTime,
+  productionEnvironment,
+  rateLimitTimeSpan,
+  rateLimitAllowedCalls,
+  timeout,
+  portNumber,
+} from "./constants";
+
+/**
+ * Server configuration interface
+ * @interface
+ * @property {string} url - Base server URL
+ */
+interface Server {
+  url: string;
+}
+
+/**
+ * API information structure
+ * @interface
+ * @property {string} title - API title
+ * @property {string} version - API version
+ * @property {string} description - API description
+ */
+interface Info {
+  title: string;
+  version: string;
+  description: string;
+}
+
+/**
+ * Swagger definition structure
+ * @interface
+ * @property {string} openApi - OpenAPI specification version
+ * @property {Info} info - API information
+ * @property {Server[]} servers - List of server configurations
+ */
+interface SwaggerDefinition {
+  openApi: string;
+  info: Info;
+  servers: Server[];
+}
+
+/**
+ * Swagger configuration options
+ * @interface
+ * @property {SwaggerDefinition} swaggerDefinition - Swagger definition object
+ * @property {string[]} apis - Paths to API documentation files
+ */
+export interface SwaggerOptions {
+  swaggerDefinition: SwaggerDefinition;
+  apis: string[];
+}

package/src/utilities/assign.ts

@@ -0,0 +1,81 @@
+import { z, ZodRawShape } from "zod";
+import { ResponseError } from "./types";
+
+/**
+ * Strictly convert obj (type T1) to T2 using a Zod schema.
+ *
+ * - Throws if obj has extra fields beyond those defined in the schema.
+ * - 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 assignStrictlyFromSchema<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(
+      "assignStrictlyFromSchema: provided schema has no shape.",
+      500
+    );
+  }
+
+  const keysSchema = Object.keys(shape) as Array<keyof any>;
+
+  // 2) Extra keys check
+  const objKeys = Object.keys(obj) as Array<keyof T1>;
+  const extraKeys = objKeys.filter((k) => !keysSchema.includes(k as any));
+  if (extraKeys.length > 0) {
+    throw new ResponseError(
+      `assignStrictlyFromSchema: source object contains extra field(s) not present on target: ${extraKeys.join(
+        ", "
+      )}`,
+      500
+    );
+  }
+
+  // 3) Required-field check for T2 (all keys in schema must be present and non-undefined)
+  const missingOrUndefined = keysSchema.filter((k) => {
+    const v = (obj as any)[k];
+    return v === undefined || v === null;
+  });
+  if (missingOrUndefined.length > 0) {
+    throw new ResponseError(
+      `assignStrictlyFromSchema: missing required field(s): ${missingOrUndefined.join(
+        ", "
+      )}`,
+      500
+    );
+  }
+
+  // 4) Build a plain object to pass through Zod for validation
+  const candidate: any = {};
+  for (const k of keysSchema) {
+    if (k in (obj as any)) {
+      candidate[k] = (obj as any)[k];
+    }
+  }
+
+  // 5) 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 Error(
+      `assignStrictlyFromSchema: validation failed: ${JSON.stringify(issues)}`
+    );
+  }
+
+  // 6) Return the validated data typed as T2
+  return result.data as T2;
+}

package/src/utilities/error-handling.ts

@@ -0,0 +1,120 @@
+import { Response } from "express";
+import { ReturnInfo, ResponseError } from "./types";
+
+/**
+ * Sends a standardized HTTP error response.
+ *
+ * This function sets the response status from the provided error (defaulting to 500)
+ * and serializes the error object as JSON.
+ *
+ * @param res - Express Response object to send the error on
+ * @param error - Error details to return to the client (must include status or default will be 500)
+ */
+export function sendHttpError(res: Response, error: ResponseError): void {
+  res.status(error.status ?? 500).json(error);
+}
+
+/**
+ * Executes a function and captures a potential error as a ReturnInfo tuple.
+ *
+ * Returns a two-element tuple: [value, error]
+ * - value: the function result if it succeeds; null if an exception is thrown
+ * - error: the caught Error wrapped as a ResponseError (or the provided error) if the function throws; null if the function succeeds
+ *
+ * This utility helps avoid try/catch blocks at call sites by returning both the
+ * result and any error in a single value.
+ *
+ * @template T
+ * @param func - The function to execute
+ * @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>(
+  func: () => T,
+  error: ResponseError | null
+): ReturnInfo<T> {
+  try {
+    return [func(), null];
+  } catch {
+    return [null, error];
+  }
+}
+
+/**
+ * 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.
+ *
+ * Given a ReturnInfo<T> of the form [value, error], this returns the value
+ * when the operation succeeded, or null when there was an error.
+ *
+ * @template T
+ * @param input - The ReturnInfo tuple
+ * @returns The successful value of type T, or null if there was an error
+ */
+export function successfulResult<T>(input: ReturnInfo<T>): T | null {
+  return input[0];
+}
+
+/**
+ * Normalizes and wraps an error into the common ReturnInfo shape.
+ *
+ * The function accepts a ReturnInfo-shaped input and extracts the error portion.
+ * If a non-Error value is provided, you should wrap it as a ResponseError beforehand.
+ * If the error is already a ResponseError, it is returned as-is.
+ *
+ * @template T
+ * @param responseError - The error to wrap, either as a ResponseError or as a ReturnInfo<T> where the error is at index 1
+ * @returns The extracted or wrapped ResponseError, or null if there is no error
+ */
+export function error<T>(responseError: ReturnInfo<T>): ResponseError | null {
+  return responseError[1];
+}
+
+/**
+ * Determines whether a ReturnInfo value represents a successful operation.
+ *
+ * A result is considered successful when there is no error (i.e., the error portion is null).
+ *
+ * @template T
+ * @param result - The ReturnInfo tuple [value | null, error | null]
+ * @returns true if there is no error; false otherwise
+ */
+export function isSuccessful<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 hasError<T>(result: ReturnInfo<T>): boolean {
+  return result[1] !== null;
+}

package/src/utilities/types.ts

@@ -0,0 +1,23 @@
+/**
+ * Represents a standardized error response structure for API endpoints
+ * @class
+ * @property {number} [status] - HTTP status code
+ * @property {string} [name] - Error name/type
+ * @property {string} message - Human-readable error message
+ * @property {string} [stack] - Error stack trace (development only)
+ * @property {string} [details] - Additional error details
+ */
+export class ResponseError extends Error {
+  public constructor(
+    public message: string,
+    public status?: number,
+    public details?: string,
+    public code?: string,
+    public stack?: string
+  ) {
+    super(message);
+  }
+}
+
+export type ReturnInfo<T> = [T | null, ResponseError | null];
+export type AsyncReturnInfo<T> = Promise<[T | null, ResponseError | null]>;