codeweaver 2.3.1 → 3.0.0

package/src/utilities/assignment.ts

@@ -0,0 +1,48 @@
+import { z } from "zod";
+import { ResponseError } from "./error-handling";
+
+/**
+ * Strictly assign obj (type T1) to T2 using a Zod schema.
+ *
+ * - Extras in source are ignored.
+ * - 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 async function assign<T1 extends object, T2 extends object>(
+  source: T1,
+  destination: T2,
+  schema?: z.ZodObject<any>
+): Promise<T2> {
+  let keys = Object.keys(schema?.shape ?? destination);
+
+  // Iterate schema keys
+  await Promise.all(
+    keys.map(async (key) => {
+      if (source.hasOwnProperty(key)) {
+        (destination as any)[key] = (source as any)[key];
+      }
+    })
+  );
+
+  if (schema != null) {
+    // Validate using the schema on the subset (this will also coerce if the schema has transforms)
+    const parseResult = await schema.safeParseAsync(destination);
+    if (parseResult.success == false) {
+      // 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(
+        `Validation failed for "${path}": ${message}`,
+        500
+      );
+    }
+  }
+
+  return destination;
+}

package/src/utilities/conversion.ts

@@ -109,50 +109,57 @@ export function stringToNumber(input: string): number {
  * - 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 data - 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
+export async function convert<T1 extends object, T2 extends object>(
+  data: T1,
+  schema: z.ZodObject<any>,
+  ignoreValidation: boolean = false
+): Promise<T2> {
+  // 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
-    );
+    throw new ResponseError("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
+  // 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];
+
+  // Iterate schema keys
+  await Promise.all(
+    keysSchema.map(async (key) => {
+      if ((data as any).hasOwnProperty(key)) {
+        candidate[key] = (data as any)[key];
+      }
+    })
+  );
+
+  // Validate against the schema
+  if (ignoreValidation) {
+    const result = await schema.safeParseAsync(candidate);
+    if (result.success == false) {
+      // 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(
+        `Validation failed: ${JSON.stringify(issues)}`,
+        500
+      );
     }
-  }
 
-  // 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
-    );
+    // Return the validated data typed as T2
+    return result.data as T2;
   }
 
-  // 4) Return the validated data typed as T2
-  return result.data as T2;
+  return candidate as T2;
 }

package/src/utilities/error-handling.ts

@@ -64,10 +64,10 @@ export function sendHttpError(res: Response, error: ResponseError): void {
 
 /**
  * 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
+ * - result is either T or undefined if an error occurred
+ * - error is either a ResponseError or undefined if the operation succeeded
  */
-export type ReturnInfo<T> = [T | null, ResponseError | null];
+export type ReturnInfo<T> = [T | undefined, ResponseError | undefined];
 
 /**
  * A Promise-wrapped version of ReturnInfo.
@@ -78,25 +78,25 @@ 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
+ * - value: the function result if it succeeds; undefined if an exception is thrown
+ * - error: the caught Error wrapped as a ResponseError (or the provided error) if the function throws; undefined 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]
+ * @param error - The error object to return when an exception occurs (typically a ResponseError). If no error is provided, undefined is used.
+ * @returns ReturnInfo<T> A tuple: [value or undefined, error or undefined]
  */
 export function invoke<T>(
   func: () => T,
-  error: ResponseError | null
+  error: ResponseError | undefined
 ): ReturnInfo<T> {
   try {
-    return [func(), null];
+    return [func(), undefined];
   } catch {
-    return [null, error];
+    return [undefined, error];
   }
 }
 
@@ -104,14 +104,14 @@ export function invoke<T>(
  * 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.
+ * when the operation succeeded, or undefined 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
+ * @returns The successful value of type T, or undefined if there was an error
  */
-export function successfulResult<T>(input: ReturnInfo<T>): T | null {
-  return input[0];
+export function successfulResult<T>(result: ReturnInfo<T>): T | undefined {
+  return result[0];
 }
 
 /**
@@ -122,24 +122,24 @@ export function successfulResult<T>(input: ReturnInfo<T>): T | null {
  * 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
+ * @param result - 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 undefined if there is no error
  */
-export function error<T>(responseError: ReturnInfo<T>): ResponseError | null {
-  return responseError[1];
+export function error<T>(result: ReturnInfo<T>): ResponseError | undefined {
+  return result[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).
+ * A result is considered successful when there is no error (i.e., the error portion is undefined).
  *
  * @template T
- * @param result - The ReturnInfo tuple [value | null, error | null]
+ * @param result - The ReturnInfo tuple [value | undefined, error | undefined]
  * @returns true if there is no error; false otherwise
  */
 export function isSuccessful<T>(result: ReturnInfo<T>): boolean {
-  return result[1] === null;
+  return result[1] === undefined;
 }
 
 /**
@@ -148,11 +148,11 @@ export function isSuccessful<T>(result: ReturnInfo<T>): boolean {
  * 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
+ * @param result - The ReturnInfo tuple [value | undefined, error | undefined]
+ * @returns true if an error is present (i.e., error is not undefined); false otherwise
  */
 export function hasError<T>(result: ReturnInfo<T>): boolean {
-  return result[1] !== null;
+  return result[1] !== undefined;
 }
 
 /**
@@ -161,12 +161,12 @@ export function hasError<T>(result: ReturnInfo<T>): boolean {
  * 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
+ * @param result - The ReturnInfo tuple [value | undefined, error | undefined]
+ * @returns true if an error is present (i.e., error is not undefined); false otherwise
  */
 export function then<T>(
   result: ReturnInfo<T>,
-  callback: (object: T) => void
+  callback: (value: T) => void
 ): void {
   if (isSuccessful(result)) {
     callback(successfulResult(result)!);
@@ -179,10 +179,10 @@ export function then<T>(
  * 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
+ * @param result - The ReturnInfo tuple [value | undefined, error | undefined]
+ * @returns true if an error is present (i.e., error is not undefined); false otherwise
  */
-export function catchError<T>(
+export function catchIfHasError<T>(
   result: ReturnInfo<T>,
   callback: (error: ResponseError) => void
 ): void {
@@ -190,3 +190,18 @@ export function catchError<T>(
     callback(error(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 | undefined, error | undefined]
+ * @returns true if an error is present (i.e., error is not undefined); false otherwise
+ */
+export function throwIfHasError<T>(result: ReturnInfo<T>): void {
+  if (hasError(result)) {
+    throw error(result);
+  }
+}

package/src/utilities/parallel/chanel.ts

@@ -0,0 +1,142 @@
+import { ResponseError } from "../error-handling";
+
+/**
+ * Event callback type for channel send event.
+ * @template T - Type of the value sent through the channel.
+ * @param {T} value - The value sent to the channel.
+ */
+export type EventCallback<T> = (value: T) => void;
+
+/**
+ * Channel class inspired by Golang channels.
+ * Supports asynchronous send and receive operations,
+ * optional event callback on send, and closing semantics.
+ *
+ * @template T - Type of the values sent through the channel.
+ */
+export class Channel<T> {
+  private queue: T[] = [];
+  private receivers: ((value: T) => void)[] = [];
+  private closed = false;
+  private eventCb?: EventCallback<T>;
+
+  /**
+   * Creates a new Channel.
+   * @param {EventCallback<T>} [eventCb] - Optional callback triggered after each send.
+   */
+  public constructor(eventCb?: EventCallback<T>) {
+    this.eventCb = eventCb;
+  }
+
+  /**
+   * Sends a value to the channel.
+   * If there are waiting receivers, delivers immediately.
+   * Otherwise, buffers the value.
+   * Throws if channel is closed.
+   * @param {T} value - Value to send.
+   * @returns {Promise<void>} Promise resolved when the send completes.
+   */
+  public async send(value: T): Promise<void> {
+    if (this.closed) {
+      throw new ResponseError("Channel is closed", 500);
+    }
+    if (this.receivers.length > 0) {
+      const receiver = this.receivers.shift()!;
+      receiver(value);
+    } else {
+      this.queue.push(value);
+    }
+    if (this.eventCb) {
+      this.eventCb(value);
+    }
+  }
+
+  /**
+   * Receives a value from the channel.
+   * If no buffered value, waits until one is sent.
+   * Throws if channel is closed and no buffered values remain.
+   * @returns {Promise<T>} Promise resolved with the next value.
+   */
+  public async receive(): Promise<T> {
+    if (this.queue.length > 0) {
+      return this.queue.shift()!;
+    }
+    if (this.closed) {
+      throw new ResponseError("Channel is closed", 500);
+    }
+    return await new Promise<T>((resolve) => {
+      this.receivers.push(resolve);
+    });
+  }
+
+  /**
+   * Closes the channel.
+   * Further sends will throw.
+   * Pending receivers receive undefined.
+   */
+  public close() {
+    this.closed = true;
+    while (this.receivers.length > 0) {
+      const receiver = this.receivers.shift()!;
+      receiver(undefined!); // Indicate closed channel to receivers
+    }
+  }
+}
+
+/**
+ * Mutex class inspired by Golang sync.Mutex using Promise chaining.
+ * Supports lock, scoped locking with ulock, and tryLock with timeout.
+ */
+export class Mutex {
+  private mutex = Promise.resolve();
+
+  /**
+   * Locks the mutex asynchronously.
+   * Returns a release function to unlock.
+   * @returns {Promise<() => void>} Promise resolved with the unlock function.
+   */
+  public async lock(): Promise<() => void> {
+    let release: () => void;
+    const lockPromise = new Promise<void>((res) => (release = res));
+    const oldMutex = this.mutex;
+    this.mutex = oldMutex.then(() => lockPromise);
+    await oldMutex;
+    return release!;
+  }
+
+  /**
+   * Executes a given task under mutex lock.
+   * Ensures the mutex is released even if task throws.
+   * @param {() => Promise<void> | void} task - Task to execute exclusively.
+   */
+  public async unlock(task: () => Promise<void> | void): Promise<void> {
+    const release = await this.lock();
+    try {
+      await task();
+    } finally {
+      release();
+    }
+  }
+
+  /**
+   * Attempts to acquire the lock with a timeout.
+   * If timeout expires, returns null.
+   * Otherwise returns the unlock function.
+   * @param {number} timeoutMs - Timeout in milliseconds.
+   * @returns {Promise<(() => void) | null>} Unlock function or null on timeout.
+   */
+  public async tryLock(timeoutMs: number): Promise<(() => void) | null> {
+    let timer: NodeJS.Timeout;
+    const timedOut = new Promise<null>((resolve) => {
+      timer = setTimeout(() => resolve(null), timeoutMs);
+    });
+    const lockPromise = this.lock();
+
+    const result = await Promise.race([lockPromise, timedOut]);
+    if (result === null) {
+      return null;
+    }
+    clearTimeout(timer!);
+    return result as () => void;
+  }
+}

package/src/utilities/parallel/parallel.ts

@@ -0,0 +1,135 @@
+import { ResponseError } from "../error-handling";
+import path from "path";
+import { WorkerPool } from "./worker-pool";
+
+/**
+ * Executes multiple asynchronous or synchronous tasks in parallel and returns their results as an array.
+ *
+ * @template T The type of the result returned by each task.
+ * @param {(() => T)[]} tasks - An array of functions, where each function returns a value or a promise.
+ * @returns {Promise<T[]>} A promise that resolves to an array containing the resolved results of all tasks, preserving order.
+ *
+ * @example
+ * const results = await parallel(
+ *   () => fetchUser(1),
+ *   () => fetchUser(2),
+ *   () => fetchUser(3)
+ * );
+ * console.log(results); // [user1, user2, user3]
+ */
+export async function parallel<T>(...tasks: (() => T)[]): Promise<T[]> {
+  return await Promise.all(tasks.map(async (task) => task()));
+}
+
+/**
+ * Simple parallel mapper.
+ * Executes the provided async mapper function on each item in parallel
+ * and collects the results in the same order as the input.
+ *
+ * @template T - Type of input items
+ * @template U - Type of mapped results
+ * @param items - Array of items to process
+ * @param mapper - Async function that maps a T to a U (or Promise<U>)
+ * @returns {Promise<U[]>} - Resolves to an array of mapped results in input order
+ */
+export async function parallelMap<T, U>(
+  items: T[],
+  mapper: (item: T, index?: number, array?: T[]) => Promise<U> | U
+): Promise<U[]> {
+  // Map each item to its mapped Promise and await all of them in parallel
+  return await Promise.all(
+    items.map(async (item, index, array) => await mapper(item, index, array))
+  );
+}
+
+/**
+ * Concurrency-limited parallel mapper.
+ * Processes items with a configurable maximum number of concurrent operations.
+ * If concurrency is Infinity or not finite, falls back to unbounded Promise.all.
+ *
+ * @template T - Type of input items
+ * @template U - Type of mapped results
+ * @param items - Array of items to process
+ * @param mapper - Async function that maps a T to a U (or Promise<U>)
+ * @param concurrencyLevel - number | Infinity - Max concurrent operations (default: Infinity)
+ * @returns {Promise<U[]>} - Resolves to an array of mapped results in input order
+ */
+export async function parallelMapWithConcurrencyLevel<T, U>(
+  items: T[],
+  mapper: (item: T, index?: number, array?: T[]) => Promise<U> | U,
+  concurrencyLevel: number = Infinity
+): Promise<U[]> {
+  if (!Array.isArray(items)) {
+    throw new ResponseError("Items must be an array", 400);
+  }
+
+  if (concurrencyLevel <= 0) {
+    throw new ResponseError("Concurrency must be greater than 0", 500);
+  }
+
+  // If concurrency is not finite, use the simple Promise.all approach
+  if (!isFinite(concurrencyLevel)) {
+    return await Promise.all(
+      items.map((item) => Promise.resolve(mapper(item)))
+    );
+  }
+
+  const results: U[] = new Array(items.length);
+  let i = 0;
+
+  // Create a fixed number of worker promises that pull from the shared index
+  const workers = Array.from({ length: concurrencyLevel }, async () => {
+    while (i < items.length) {
+      const idx = i++;
+      const item = items[idx];
+      // Store the result in the corresponding position to preserve order
+      results[idx] = await mapper(item, idx, items);
+    }
+  });
+
+  await Promise.all(workers);
+  return results;
+}
+
+/**
+ * Parallel CPU-bound mapper using a fixed-size worker pool.
+ * - Distributes items to workers and collects results in input order.
+ * - Each worker runs a fixed performMapping function defined inside the worker.
+ *
+ * Important: The mapper logic inside the worker is fixed. If you need custom per-item logic,
+ * you should modify the worker to import your actual function or adapt to serialize logic.
+ *
+ * @template T - Input item type
+ * @template R - Result type
+ * @param items - Array of items to process
+ * @param options - Concurrency options (default uses number of CPU cores)
+ * @returns {Promise<R[]>} - Results in the same order as input
+ */
+export async function parallelCpuMap<T, R>(
+  items: T[],
+  mapperWorkerFilePath: string,
+  concurrencyLevel: number = require("os").cpus().length || 1
+): Promise<R[]> {
+  if (!Array.isArray(items)) {
+    throw new TypeError("items must be an array");
+  }
+  if (concurrencyLevel <= 0) {
+    throw new Error("concurrency must be greater than 0");
+  }
+
+  // Worker pool setup
+  const workerPath = path.resolve(__dirname, mapperWorkerFilePath);
+
+  // Instantiate a concrete pool
+  const workerPool = new WorkerPool<T, R>(workerPath, concurrencyLevel);
+
+  try {
+    // Dispatch all items and collect results in order
+    const results = await workerPool.mapAll(items);
+    await workerPool.close();
+    return results;
+  } catch (err) {
+    await workerPool.close();
+    throw err;
+  }
+}

package/src/utilities/parallel/worker-pool.ts

@@ -0,0 +1,99 @@
+import { Worker } from "worker_threads";
+import os from "os";
+import { ResponseError } from "../error-handling";
+
+export type Task<T> = { id: number; payload: T };
+export type Result<R> = { id: number; result?: R; error?: string };
+
+export class WorkerPool<T, R> {
+  private workers: Worker[] = [];
+  private poolSize: number;
+  private nextId = 0;
+
+  // Map task id -> { resolve, reject }
+  private pending = new Map<
+    number,
+    { resolve: (r: R) => void; reject: (e: any) => void }
+  >();
+
+  constructor(workerPath: string, poolSize?: number) {
+    const cores = os.cpus().length || 1;
+    this.poolSize = poolSize && poolSize > 0 ? poolSize : cores;
+
+    for (let i = 0; i < this.poolSize; i++) {
+      const w = new Worker(workerPath);
+      w.on("message", (msg: Result<R>) => this.handleResult(msg));
+      w.on("error", (err) => this.handleError(err, i));
+      w.on("exit", (code) => {
+        if (code !== 0) {
+          // Notify all pending promises about the exit
+          for (const [, p] of this.pending) {
+            p.reject(
+              new ResponseError(`Worker ${i} exited with code ${code}`, 500)
+            );
+          }
+          this.pending.clear();
+        }
+      });
+      this.workers.push(w);
+    }
+  }
+
+  private handleResult(msg: Result<R>) {
+    const { id, result, error } = msg;
+    const entry = this.pending.get(id);
+    if (!entry) return;
+    this.pending.delete(id);
+    if (error) {
+      entry.reject(new Error(error));
+    } else {
+      entry.resolve(result as R);
+    }
+  }
+
+  private handleError(err: any, workerIndex: number) {
+    // Propagate error to all pending tasks assigned to this worker, if tracked
+    // This simple version broadcasts the error to all pending tasks for safety.
+    for (const [id, entry] of this.pending) {
+      entry.reject(
+        new ResponseError(
+          `Worker ${workerIndex} error: ${err?.message ?? err}`,
+          500
+        )
+      );
+    }
+    this.pending.clear();
+  }
+
+  // Run a single payload through a specific worker
+  run(workerIndex: number, payload: T): Promise<R> {
+    const id = this.nextId++;
+    const worker = this.workers[workerIndex];
+    return new Promise<R>((resolve, reject) => {
+      this.pending.set(id, { resolve, reject });
+      worker.postMessage({ id, payload });
+    });
+  }
+
+  // Map all items using a round-robin distribution across workers
+  async mapAll(items: T[]): Promise<R[]> {
+    if (!Array.isArray(items))
+      throw new ResponseError("Items must be an array", 400);
+    const results: R[] = new Array(items.length);
+
+    const workerCount = this.workers.length;
+    const tasks: Promise<void>[] = items.map((payload, idx) => {
+      const workerIndex = idx % workerCount;
+      return this.run(workerIndex, payload).then((r) => {
+        results[idx] = r;
+      });
+    });
+
+    await Promise.all(tasks);
+    return results;
+  }
+
+  async close(): Promise<void> {
+    await Promise.all(this.workers.map((w) => w.terminate()));
+  }
+}