codeweaver 3.1.2 → 4.0.0

package/src/{utilities/cache/redis-cache.ts → core/cache/redis-cache.class.ts}

@@ -1,16 +1,21 @@
-import { AsyncCache } from "utils-decorators";
-import { Redis } from "ioredis";
+import { Redis, RedisKey } from "ioredis";
+import { AsyncCache } from "./basic-types";
 
 /**
  * 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> {
+  private startTimeMs?: number;
+
   public constructor(
-    private cache?: Redis,
     private capacity?: number,
+    private durationMs?: number,
+    private cache?: Redis,
     private namespace?: string
   ) {
+    this.startTimeMs = this.startTimeMs ?? Date.now();
+    this.durationMs = this.durationMs ?? Number.POSITIVE_INFINITY;
     this.cache = this.cache ?? new Redis();
     this.capacity = this.capacity ?? Number.POSITIVE_INFINITY;
     this.namespace = this.namespace ?? "redis";
@@ -20,13 +25,55 @@ export class RedisCache<T> implements AsyncCache<T> {
     return `${this.namespace}:${key}`;
   }
 
+  public async size(): Promise<number> {
+    return await this.cache!.dbsize();
+  }
+
+  public async keys(pattern: string): Promise<string[]> {
+    return await Array.fromAsync((await this.cache!.keys(pattern)) ?? []);
+  }
+
+  /**
+   * Returns all the field names (keys) in a Redis hash.
+   * @param key The Redis key (hash) to query.
+   * @returns An array of field names (keys) in the hash.
+   */
+  public async hkeys(key: RedisKey): Promise<string[]> {
+    return await Array.fromAsync((await this.cache!.hkeys(key)) ?? []);
+  }
+
+  /**
+   * Whether the cache is still valid.
+   * This is a computed property that returns true if the cache
+   * has not yet expired, and false otherwise.
+   * @returns true if the cache is still valid, false otherwise
+   */
+  public get isValid(): boolean {
+    return this.startTimeMs! + this.durationMs! > Date.now();
+  }
+
+  /**
+   * Resets the cache if it has expired.
+   * If the cache has expired, resets the cache by clearing it and updating the start time.
+   * @returns true if the cache was reset, false otherwise.
+   */
+  public async resetIfExpired(): Promise<boolean> {
+    if (this.isValid == false) {
+      await this.clear();
+      this.startTimeMs = Date.now();
+      return true;
+    }
+    return false;
+  }
+
   /**
    * 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> {
+  public async set(key: string, value: T): Promise<void> {
+    if ((await this.resetIfExpired()) == true) return;
     const k = this.keyFor(key);
 
     if (value != null) {
@@ -50,7 +97,7 @@ export class RedisCache<T> implements AsyncCache<T> {
    * - 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> {
+  public async get(key: string): Promise<T> {
     const k = this.keyFor(key);
     const raw = (await this.cache?.get(k)) ?? null;
     if (raw == null) {
@@ -66,14 +113,15 @@ export class RedisCache<T> implements AsyncCache<T> {
   /**
    * Asynchronously delete a value by key.
    */
-  async delete(key: string): Promise<void> {
+  public 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> {
+  public async has(key: string): Promise<boolean> {
+    if ((await this.resetIfExpired()) == true) return false;
     const exists = await this.cache?.exists(this.keyFor(key));
     return exists === 1;
   }
@@ -82,10 +130,10 @@ export class RedisCache<T> implements AsyncCache<T> {
    * Asynchronously clear the cache (namespace-scoped).
    * Use with caution in a shared Redis instance.
    */
-  async clear(key: string): Promise<void> {
+  public 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 pattern = `${this.namespace}:*`;
     const stream = this.cache?.scanStream({ match: pattern });
     const pipeline = this.cache?.pipeline();
     stream?.on("data", (keys: string[]) => {
@@ -105,7 +153,7 @@ export class RedisCache<T> implements AsyncCache<T> {
   /**
    * Optional: gracefully close the Redis connection.
    */
-  async close(): Promise<void> {
+  public async close(): Promise<void> {
     await this.cache?.quit();
   }
 }

package/src/core/container/basic-types.ts

@@ -0,0 +1,10 @@
+export type Constructor<T = any> = new (...args: any[]) => T;
+
+export interface Provider<T = any> {
+  /** The concrete class to instantiate (may be the same as token or a different implementation). */
+  useClass: Constructor<T>;
+  /** Cached singleton instance, if one has been created. */
+  instance?: T;
+  /** Whether to treat the provider as a singleton. Defaults to true. */
+  singleton?: boolean;
+}

package/src/{utilities → core/container}/container.ts

@@ -1,17 +1,7 @@
 import "reflect-metadata";
+import { Constructor, Provider } from "./basic-types";
 
-export type Constructor<T = any> = new (...args: any[]) => T;
-
-interface Provider<T = any> {
-  /** The concrete class to instantiate (may be the same as token or a different implementation). */
-  useClass: Constructor<T>;
-  /** Cached singleton instance, if one has been created. */
-  instance?: T;
-  /** Whether to treat the provider as a singleton. Defaults to true. */
-  singleton?: boolean;
-}
-
-const InjectableRegistry: Array<Constructor<any>> = [];
+const injectableRegistry: Array<Constructor<any>> = [];
 
 /**
  * A tiny dependency injection container.
@@ -39,7 +29,7 @@ class Container {
    *   - useClass?: The concrete class to instantiate for this token.
    *   - singleton?: Whether to reuse a single instance (default: true).
    */
-  register<T>(
+  public register<T>(
     token: Constructor<T>,
     options?: { useClass?: Constructor<T>; singleton?: boolean }
   ): void {
@@ -61,7 +51,7 @@ class Container {
    * @param token - The token (class constructor) to resolve.
    * @returns An instance of the requested type T.
    */
-  resolve<T>(token: Constructor<T>): T {
+  public resolve<T>(token: Constructor<T>): T {
     const provider = this.registrations.get(token);
 
     if (!provider) {
@@ -113,7 +103,7 @@ class Container {
  *   metadata is actually readable.
  */
 function bootstrapContainer(container: Container) {
-  for (const constructorFunction of InjectableRegistry) {
+  for (const constructorFunction of injectableRegistry) {
     // Read per-class options if you added metadata
     const meta = Reflect.getMetadata("di:injectable", constructorFunction) as
       | { singleton?: boolean }
@@ -135,14 +125,14 @@ export function Injectable(options?: {
 }): ClassDecorator {
   return (target: any) => {
     // Push into registry for later registration
-    InjectableRegistry.push(target);
+    injectableRegistry.push(target);
     // You could also attach metadata if you want to customize per-class
     Reflect.defineMetadata("di:injectable", options ?? {}, target);
   };
 }
 
 /** A single, shared DI container for the app. */
-const container = new Container();
+export const container = new Container();
 bootstrapContainer(container);
 
 /**

package/src/core/container/index.ts

@@ -0,0 +1,2 @@
+export * from "./basic-types";
+export * from "./container";

package/src/{utilities → core/error}/error-handling.ts

@@ -1,68 +1,4 @@
-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);
-}
+import { ResponseError } from "./response-error";
 
 /**
  * A generic alias representing a tuple of [result, error].

package/src/core/error/index.ts

@@ -0,0 +1,3 @@
+export * from "./response-error";
+export * from "./send-http-error";
+export * from "./error-handling";

package/src/core/error/response-error.ts

@@ -0,0 +1,45 @@
+/**
+ * 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 override 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 override stack?: string
+  ) {
+    // Ensure the base Error class gets the message for standard properties like name, stack, etc.
+    super(message);
+  }
+}

package/src/core/error/send-http-error.ts

@@ -0,0 +1,15 @@
+import { Response } from "express";
+import { ResponseError } from "./response-error";
+
+/**
+ * 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);
+}

package/src/core/file/file-helpers.ts

@@ -0,0 +1,166 @@
+import { promises as fs } from "fs";
+import * as path from "path";
+import * as yaml from "js-yaml";
+
+/**
+ * A union type representing valid JSON-like values.
+ * - Primitives: string, number, boolean, null
+ * - Objects: { [key: string]: JsonValue }
+ * - Arrays: JsonValue[]
+ */
+export type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | { [key: string]: JsonValue }
+  | JsonValue[];
+
+/**
+ * Reads a file and parses its contents as JSON or YAML depending on the file extension.
+ *
+ * - If the extension is ".json", parses with JSON.parse.
+ * - If the extension is ".yaml" or ".yml", parses with js-yaml's YAML loader.
+ * - For any other extension, throws an error indicating unsupported extension.
+ *
+ * @template T - The expected return type (defaults to JsonValue).
+ * @param {string} filePath - The path to the file to read.
+ * @returns {Promise<T>} The parsed value typed as T.
+ * @throws {Error} If the file cannot be read, the extension is unsupported, or parsing fails.
+ *
+ * Edge cases:
+ * - If the YAML/JSON content does not match the requested T, a runtime cast is performed.
+ * - If the file does not exist, an error is thrown by the underlying readFile call.
+ */
+export async function readJsonOrYaml<T = JsonValue>(
+  filePath: string
+): Promise<T> {
+  const ext = path.extname(filePath).toLowerCase();
+
+  try {
+    const data = await fs.readFile(filePath, "utf-8");
+    if (ext === ".json") {
+      return JSON.parse(data) as T;
+    } else if (ext === ".yaml" || ext === ".yml") {
+      return yaml.load(data) as T;
+    } else {
+      throw new Error(
+        `Unsupported file extension: ${ext}. Only .json, .yaml, .yml are supported.`
+      );
+    }
+  } catch (err) {
+    throw new Error(`Failed to read ${filePath}: ${(err as Error).message}`);
+  }
+}
+
+/**
+ * Serializes data to JSON or YAML and writes it to disk, based on the file extension.
+ *
+ * - If the extension is ".json", the data is serialized with JSON.stringify (pretty-printed with 2 spaces).
+ * - If the extension is ".yaml" or ".yml", the data is serialized with js-yaml's dump.
+ * - For any other extension, throws an error indicating unsupported extension.
+ *
+ * @template T - Type of the data to write (defaults to JsonValue).
+ * @param {string} filePath - The path to write the file to.
+ * @param {T} data - The data to serialize and write.
+ * @returns {Promise<void>} Resolves when the write completes.
+ * @throws {Error} If the extension is unsupported or the write fails.
+ */
+export async function writeJsonOrYaml<T = JsonValue>(
+  filePath: string,
+  data: T
+): Promise<void> {
+  const ext = path.extname(filePath).toLowerCase();
+
+  try {
+    const serialized =
+      ext === ".json"
+        ? JSON.stringify(data, null, 2)
+        : ext === ".yaml" || ext === ".yml"
+        ? yaml.dump(data)
+        : null;
+
+    if (serialized === null) {
+      throw new Error(
+        `Unsupported file extension: ${ext}. Only .json, .yaml, .yml are supported.`
+      );
+    }
+
+    await fs.writeFile(filePath, serialized, "utf-8");
+  } catch (err) {
+    throw new Error(`Failed to write ${filePath}: ${(err as Error).message}`);
+  }
+}
+
+/**
+ * Updates a top-level key in a JSON/YAML file. If the file does not exist, starts with an empty object.
+ *
+ * - Loads existing data from the file (JSON or YAML) if present and valid.
+ * - If the file does not exist, initializes data as an empty object.
+ * - Sets data[key] = value and saves the updated object back to disk.
+ * - If the existing content is not an object, it will be replaced with a new object.
+ *
+ * @template K extends string - The key type (string literal type or string).
+ * @template V extends JsonValue - The value to assign to the key.
+ * @param {string} filePath - The path to the file to update.
+ * @param {K} key - The key to set on the root object.
+ * @param {V} value - The value to assign to the key.
+ * @returns {Promise<void>} Resolves when the update/write completes.
+ * @throws {Error} If reading the file fails with an unsupported extension, or writing fails.
+ *
+ * Notes:
+ * - This function operates at the top level only (not nested paths).
+ */
+export async function updateJsonOrYaml<K extends string, V extends JsonValue>(
+  filePath: string,
+  key: K,
+  value: V
+): Promise<void> {
+  const ext = path.extname(filePath).toLowerCase();
+
+  // Load existing data
+  let data: any;
+  try {
+    if (ext === ".json" || ext === ".yaml" || ext === ".yml") {
+      data = await readJsonOrYaml<any>(filePath);
+    } else {
+      throw new Error(`Unsupported file extension: ${ext}.`);
+    }
+  } catch (err) {
+    // If file doesn't exist, start with an empty object
+    if (
+      (err as Error).message.includes("Failed to read") &&
+      (await fileExists(filePath)) === false
+    ) {
+      data = {};
+    } else {
+      throw err;
+    }
+  }
+
+  // Ensure we have an object to update
+  if (typeof data !== "object" || data === null) {
+    data = {} as Record<string, any>;
+  }
+
+  // Update the key
+  data[key] = value;
+
+  // Save back
+  await writeJsonOrYaml(filePath, data);
+}
+
+/**
+ * Helper to check if a file exists.
+ *
+ * @param {string} filePath - The path to check.
+ * @returns {Promise<boolean>} True if the file exists, false otherwise.
+ */
+async function fileExists(filePath: string): Promise<boolean> {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/core/file/index.ts

@@ -0,0 +1 @@
+export * from "./file-helpers";

package/src/{utilities → core/helpers}/assignment.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { parallelMap } from "./parallel/parallel";
+import { parallelMap } from "../parallel/parallel";
 
 /**
  * Strictly assign obj (type T1) to T2 using a Zod schema.
@@ -13,7 +13,7 @@ import { parallelMap } from "./parallel/parallel";
  * @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>(
+export async function assign<T1 extends object, T2 extends object>(
   destination: T2,
   source: T1,
   destinationSchema?: z.ZodObject<any>

package/src/core/helpers/comparison.ts

@@ -0,0 +1,86 @@
+/**
+ * Compare two values for deep equality using parallel, recursive checks.
+ *
+ * This function performs a structural equality check between two values.
+ * It handles primitives, null, Date, RegExp, Arrays, and plain objects.
+ * Object properties are checked in parallel via Promise.all for potential
+ * performance benefits on large objects.
+ *
+ * Notes:
+ * - For objects, keys must match exactly; values are compared recursively.
+ * - For Arrays, element order and values must match.
+ * - For Dates, times (getTime) must be identical.
+ * - For RegExp, string representations (via toString) must match.
+ * - Functions are compared by reference (i.e., a === b) since they cannot be
+ *   meaningfully “deep-equal” compared here.
+ * - If you enable a cycle-detection mechanism, circular references are handled
+ *   by tracking seen pairs to avoid infinite recursion.
+ *
+ * @template T - Type of the first value (and, by structural typing, the second).
+ * @param a - The first value to compare.
+ * @param b - The second value to compare.
+ * @returns A Promise that resolves to true if `a` and `b` are deeply equal, otherwise false.
+ *
+ * @example
+ * true: simple primitives
+ * await equal(1, 1); // true
+ *
+ * @example
+ * true: identical objects
+ * await equal({ x: 1, y: [2, 3] }, { x: 1, y: [2, 3] }); // true
+ *
+ * @example
+ * false: different structure
+ * await equal({ a: 1 }, { a: 1, b: 2 }); // false
+ *
+ * @example
+ * false: different array contents
+ * await equal([1, 2], [1, 3]); // false
+ */
+export async function equal<T>(
+  a: T,
+  b: T,
+  _seen = new WeakMap<object, WeakMap<object, boolean>>()
+): Promise<boolean> {
+  if (a === b) return true;
+  if (typeof a !== typeof b) return false;
+  if (a === null || b === null) return a === b;
+
+  const ta = typeof a;
+  if (ta !== "object") return a === b;
+
+  // Cycle detection for objects
+  const A = a as object;
+  const B = b as object;
+  if (_seen.has(A)) {
+    const inner = _seen.get(A)!;
+    if (inner.has(B as object)) return inner.get(B as object)!;
+  } else {
+    _seen.set(A, new WeakMap<object, boolean>());
+  }
+
+  // Update trace
+  _seen.get(A)!.set(B as object, true);
+
+  if (a instanceof Date && b instanceof Date)
+    return a.getTime() === b.getTime();
+  if (a instanceof RegExp && b instanceof RegExp)
+    return a.toString() === b.toString();
+
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== (b as any).length) return false;
+    const checks = a.map((_, i) => equal((a as any)[i], (b as any)[i], _seen));
+    const results = await Promise.all(checks);
+    return results.every(Boolean);
+  }
+
+  const aKeys = Object.keys(a as Object);
+  const bKeys = Object.keys(b as Object);
+  if (aKeys.length !== bKeys.length) return false;
+  const keySet = new Set<string>(aKeys);
+  for (const k of bKeys) if (!keySet.has(k)) return false;
+
+  const checks = aKeys.map((k) => equal((a as any)[k], (b as any)[k], _seen));
+  const results = await Promise.all(checks);
+  return results.every(Boolean);
+}

package/src/{utilities → core/helpers}/conversion.ts

@@ -1,5 +1,5 @@
 import { z, ZodRawShape } from "zod";
-import { parallelMap } from "./parallel/parallel";
+import { parallelMap } from "../parallel/parallel";
 
 /**
  * Helper: normalize and validate a numeric string for integer parsing.
@@ -11,7 +11,7 @@ function parseIntegerStrict(input: string): number {
 
   // Empty or just sign is invalid
   if (s.length === 0 || s === "+" || s === "-") {
-    throw new TypeError("Invalid integer");
+    throw new TypeError("Invalid sign");
   }
 
   // Use a regex to ensure the entire string is an optional sign followed by digits