codeweaver 1.1.0 → 2.1.0

package/src/utilities/error-handling.ts

@@ -0,0 +1,156 @@
+import { Response } from "express";
+
+/**
+ * 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.
+ *
+ * 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);
+}
+
+/**
+ * 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.
+ *
+ * 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 invoke<T>(
+  func: () => T,
+  error: ResponseError | null
+): ReturnInfo<T> {
+  try {
+    return [func(), null];
+  } catch {
+    return [null, error];
+  }
+}
+
+/**
+ * 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/tsconfig.json

@@ -9,11 +9,8 @@
     "forceConsistentCasingInFileNames": true,
     "experimentalDecorators": true,
     "emitDecoratorMetadata": true,
-    "baseUrl": ".",
     "paths": {
-      "@pkg/*": ["src/packages/*"],
-      "@r/*": ["src/routers/*"],
-      "@/*": ["src/*"]
+      "@/*": ["./src/*"]
     }
   },
   "include": ["**/*.ts", "**/*.js"],

package/tsconfig.paths.json

@@ -1,10 +1,8 @@
-{
-  "compilerOptions": {
-    "baseUrl": ".",
-    "paths": {
-      "@pkg/*": ["dist/packages/*"],
-      "@r/*": ["dist/routers/*"],
-      "@/*": ["dist/*"]
-    }
-  }
-}
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["dist/*"]
+    }
+  }
+}

package/src/packages/ts-zod-decorators/index.ts

@@ -1,3 +0,0 @@
-export * from './validate.decorator';
-export * from './zod-output.decorator';
-export * from './zod-input.decorator';

package/src/packages/ts-zod-decorators/validate.decorator.ts

@@ -1,20 +0,0 @@
-/* eslint-disable @typescript-eslint/ban-types */
-import ZodValidator from './validator.class';
-
-export const Validate: MethodDecorator = (
-	target: Object,
-	propertyKey: string | symbol,
-	descriptor: PropertyDescriptor,
-) => {
-	const originalMethod = descriptor.value;
-	descriptor.value = async function (...args: unknown[]) {
-		ZodValidator.validateInput(target, propertyKey as string, args);
-		const result = originalMethod.apply(this, args);
-		let resultValue = result;
-		if (result instanceof Promise) {
-			resultValue = await result;
-			ZodValidator.validateOutput(target, propertyKey as string, resultValue);
-		}
-		return resultValue;
-	};
-};

package/src/packages/ts-zod-decorators/validator.class.ts

@@ -1,72 +0,0 @@
-/* eslint-disable @typescript-eslint/ban-types */
-import * as z from "zod";
-
-type Target = Object;
-type MethodName = string;
-type Metadata = {
-  paramsIndex: number[];
-  inputSchema?: z.ZodObject<any, any>;
-  outputSchema?: z.ZodObject<any, any>;
-};
-
-export default class ZodValidator {
-  private static methodValidatorMap: Map<Target, Map<MethodName, Metadata>> =
-    new Map();
-
-  static registerInputParameterValidationSchema(
-    target: Object,
-    methodName: MethodName,
-    paramIndex: number,
-    schema: z.ZodObject<any, any>
-  ) {
-    let paramMap = this.methodValidatorMap.get(target)!;
-    if (!paramMap) {
-      paramMap = new Map();
-      this.methodValidatorMap.set(target, paramMap);
-    }
-    let metadata = paramMap.get(methodName)!;
-    if (!metadata) {
-      metadata = { paramsIndex: [], inputSchema: schema };
-      paramMap.set(methodName, metadata);
-    }
-    metadata.paramsIndex.push(paramIndex);
-  }
-
-  static registerMethodValidationOutputSchema(
-    target: Object,
-    methodName: MethodName,
-    schema: z.ZodObject<any, any>
-  ) {
-    let paramMap = this.methodValidatorMap.get(target)!;
-    if (!paramMap) {
-      paramMap = new Map();
-      this.methodValidatorMap.set(target, paramMap);
-    }
-    let metadata = paramMap.get(methodName)!;
-    if (!metadata) {
-      metadata = { paramsIndex: [], outputSchema: schema };
-      paramMap.set(methodName, metadata);
-    }
-    metadata.outputSchema = schema;
-  }
-
-  static validateInput(
-    target: Object,
-    methodName: string,
-    paramValues: unknown[]
-  ) {
-    const methodMetadataMap = this.methodValidatorMap.get(target)!;
-    const metadata = methodMetadataMap.get(methodName)!;
-    for (const [index, input] of paramValues.entries()) {
-      if (metadata.paramsIndex.indexOf(index) != -1) {
-        metadata.inputSchema?.parse(input);
-      }
-    }
-  }
-
-  static validateOutput(target: Object, methodName: string, output: unknown) {
-    const methodMetadataMap = this.methodValidatorMap.get(target)!;
-    const metadata = methodMetadataMap.get(methodName)!;
-    metadata.outputSchema?.parse(output);
-  }
-}

package/src/packages/ts-zod-decorators/zod-input.decorator.ts

@@ -1,12 +0,0 @@
-import { ZodObject } from "zod";
-import ZodValidator from "./validator.class";
-
-export const ZodInput =
-  <T extends ZodObject<any, any>>(schema: T): ParameterDecorator =>
-  (target, propertyKey, parameterIndex) =>
-    ZodValidator.registerInputParameterValidationSchema(
-      target,
-      propertyKey as string,
-      parameterIndex,
-      schema
-    );

package/src/packages/ts-zod-decorators/zod-output.decorator.ts

@@ -1,11 +0,0 @@
-import { ZodObject } from "zod";
-import ZodValidator from "./validator.class";
-
-export const ZodOutput =
-  <T extends ZodObject<any, any>>(schema: T): MethodDecorator =>
-  (target, propertyKey) =>
-    ZodValidator.registerMethodValidationOutputSchema(
-      target,
-      propertyKey as string,
-      schema
-    );

package/src/types.ts

@@ -1,16 +0,0 @@
-/**
- * Represents a standardized error response structure for API endpoints
- * @interface
- * @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 interface ResponseError {
-  status: number;
-  name?: string;
-  message: string;
-  stack?: string;
-  details?: string;
-}

package/src/utilities.ts

@@ -1,47 +0,0 @@
-import { Response } from "express";
-import { ResponseError } from "./types";
-
-/**
- * Sends a standardized error response
- * @param {Response} res - Express response object
- * @param {ResponseError} error - Error details object
- */
-export function sendError(res: Response, error: ResponseError): void {
-  res.status(error.status).json(error);
-}
-
-/**
- * Parses and validates ID parameter from string to number
- * @param {string} input - Input string to parse
- * @returns {number|ResponseError} Parsed number or error object
- */
-export function tryParseId(input: string): number | ResponseError {
-  try {
-    return parseInt(input) satisfies number;
-  } catch {
-    return {
-      status: 400,
-      message: "wrong input",
-      details: "The id parameter must be an integer number.",
-    } satisfies ResponseError;
-  }
-}
-
-/**
- * Checks if the provided object is a ResponseError.
- *
- * A ResponseError is an object that contains at least the properties:
- * - message: string
- * - status: number
- *
- * @param obj - The object to check.
- * @returns true if the object is a ResponseError, false otherwise.
- */
-export function isResponseError(obj: unknown): boolean {
-  return (
-    obj != null &&
-    typeof obj === "object" &&
-    "message" in obj &&
-    "status" in obj
-  );
-}