codeweaver 2.0.0 → 2.1.0

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.
  *

package/src/utilities/types.ts

@@ -1,23 +0,0 @@
-/**
- * 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]>;