codeweaver 3.1.3 → 4.0.1

package/src/core/helpers/decorators.ts

@@ -0,0 +1,316 @@
+import "reflect-metadata";
+import { AsyncFn } from "./types";
+
+/**
+ * Factory for creating a method decorator with optional pre- and post-execution hooks.
+ *
+ * @template DecoratorArgs, MethodArgs
+ *
+ * @param before
+ *   Optional hook invoked before the original method runs.
+ *   - Parameters: (decoratorArgs, methodArgs, target, propertyKey, descriptor)
+ *     - decoratorArgs: The arguments passed to the decorator.
+ *     - methodArgs: The arguments passed to the decorated method.
+ *     - target: The prototype of the class for instance methods.
+ *     - propertyKey: The name of the method being decorated.
+ *     - descriptor: The method's PropertyDescriptor.
+ *   - Returns: Promise<boolean> indicating whether the original method should execute.
+ *   - If it resolves to false, the original method will not run.
+ *
+ * @param after
+ *   Optional hook invoked after the original method completes.
+ *   - Parameters: (methodResult, decoratorArgs, methodArgs, target, propertyKey, descriptor)
+ *     - methodResult: The value returned by the original method (or null if it didn't run).
+ *     - decoratorArgs: The arguments passed to the decorator.
+ *     - methodArgs: The arguments passed to the decorated method.
+ *     - target: The prototype of the class for instance methods.
+ *     - propertyKey: The name of the method being decorated.
+ *     - descriptor: The method's PropertyDescriptor.
+ *   - Returns: Promise<void>.
+ *
+ * @returns A decorator factory which, when invoked with decoratorArgs, yields a MethodDecorator.
+ *
+ * Notes:
+ * - Be explicit about what the hooks receive and what they control.
+ * - Clarify return values and behavior when before returns false.
+ * - Keep terminology consistent with your codebase (hook vs. decorator vs. wrapper).
+ * - If you rely on Reflect metadata, you can store metadata inside the hooks.
+ *
+ * Example usage:
+ *
+ * const Decorator = createMethodDecorator<[string], [number]>(
+ *   async (decoratorArgs, methodArgs, target, propertyKey, descriptor) => { ... },           // before
+ *   async (result, decoratorArgs, methodArgs, target, propertyKey, descriptor) => { ... } // after
+ * );
+ */
+export function createMethodDecorator<
+  DecoratorArgs extends any[] = any[],
+  MethodArgs extends any[] = any[]
+>(
+  before?: (
+    decoratorArgs: DecoratorArgs,
+    methodArgs: MethodArgs,
+    method: AsyncFn,
+    rawMethodArgs: any[],
+    classInstance: any,
+    target: Object,
+    propertyKey: string | symbol,
+    descriptor: PropertyDescriptor
+  ) => Promise<any>,
+  after?: (
+    methodResult: any,
+    decoratorArgs: DecoratorArgs,
+    methodArgs: MethodArgs,
+    method: AsyncFn,
+    rawMethodArgs: any[],
+    classInstance: any,
+    target: Object,
+    propertyKey: string | symbol,
+    descriptor: PropertyDescriptor
+  ) => Promise<any>
+): (...decoratorArgs: DecoratorArgs) => MethodDecorator {
+  return (...decoratorArgs: DecoratorArgs) => {
+    return (
+      target: Object,
+      propertyKey: string | symbol,
+      descriptor: PropertyDescriptor
+    ) => {
+      const originalMethod = descriptor.value as (
+        ...args: any[]
+      ) => Promise<any>;
+
+      // If there is no function to wrap, bail out gracefully
+      if (typeof originalMethod !== "function") {
+        throw new Error("Cannot wrap non-function.");
+      }
+
+      // Wrap the original method to insert before/after hooks
+      descriptor.value = async function (...methodArgs: any[]) {
+        // Run the optional before hook. If not provided, default to allowing execution.
+        const beforeCallbackResult =
+          before != null
+            ? await before(
+                decoratorArgs,
+                methodArgs as MethodArgs,
+                originalMethod,
+                methodArgs,
+                this,
+                target,
+                propertyKey,
+                descriptor
+              )
+            : null;
+
+        // Execute the original method only if allowed
+        const methodResult =
+          beforeCallbackResult === null
+            ? await originalMethod.apply(this, methodArgs)
+            : beforeCallbackResult;
+
+        // Run the optional after hook with the obtained result
+        const afterCallbackResult =
+          after != null
+            ? await after(
+                methodResult,
+                decoratorArgs,
+                methodArgs as MethodArgs,
+                originalMethod,
+                methodArgs,
+                this,
+                target,
+                propertyKey,
+                descriptor
+              )
+            : methodResult;
+
+        // Return the original result (even if before denied, it's null per above)
+        return afterCallbackResult === null
+          ? methodResult
+          : afterCallbackResult;
+      };
+    };
+  };
+}
+
+type ParamDecoratorFactory<DecoratorArgs extends any[] = any[]> = (
+  ...args: DecoratorArgs
+) => ParameterDecorator;
+
+/**
+ * Factory to create a parameter decorator with optional runtime logic.
+ *
+ * The returned decorator can be used to attach per-parameter behavior or metadata
+ * to a method parameter. The `handler` is invoked when the decorator runs, giving
+ * you access to the decorator arguments, the resolved parameter type (if available),
+ * the index of the decorated parameter, the target (prototype) and the method name.
+ *
+ * Notes:
+ * - propertyKey can be string or symbol (or undefined in edge cases).
+ * - If you rely on Reflect metadata, you can store metadata inside the handler.
+ */
+export function createParamDecorator<
+  DecoratorArgs extends any[] = any[],
+  MethodArgs extends any[] = any[],
+  ParamType = any
+>(
+  handler: (
+    decoratorArgs: DecoratorArgs,
+    methodArgs: MethodArgs | undefined,
+    parameter: ParamType | undefined,
+    parameterIndex: number,
+    target: Object,
+    propertyKey?: string | symbol
+  ) => void | Promise<void>
+): ParamDecoratorFactory<DecoratorArgs> {
+  // Return a factory that captures the decoratorArgs and returns a real ParameterDecorator
+  return (...decoratorArgs: DecoratorArgs) => {
+    return (
+      target: Object,
+      propertyKey: string | symbol | undefined,
+      parameterIndex: number
+    ) => {
+      // Resolve the parameter type if available (design:paramtypes)
+      let parameter: ParamType | undefined = undefined;
+      let methodArgs: MethodArgs | undefined = undefined;
+      if (typeof propertyKey !== "undefined" && target != null) {
+        try {
+          const types = Reflect.getMetadata(
+            "design:paramtypes",
+            target,
+            propertyKey
+          );
+          if (Array.isArray(types) && typeof parameterIndex === "number") {
+            methodArgs = types as MethodArgs;
+            parameter = types[parameterIndex] as ParamType;
+          }
+        } catch {
+          // metadata not available; swallow
+        }
+      }
+
+      // Run user-supplied handler
+      // Note: allow handler to be sync or async
+      const maybePromise = handler(
+        decoratorArgs,
+        methodArgs,
+        parameter,
+        parameterIndex,
+        target,
+        propertyKey
+      );
+
+      void maybePromise;
+    };
+  };
+}
+
+// Hook results
+type BeforeGetResult = boolean | Promise<boolean>;
+type AfterGetResult = void | Promise<void>;
+type BeforeSetResult = boolean | Promise<boolean>;
+type AfterSetResult = void | Promise<void>;
+
+// Common argument lists
+type GetArgs<DecoratorArgs extends any[] = any[]> = {
+  decoratorArgs: DecoratorArgs;
+  target: Object;
+  propertyKey: string | symbol;
+  // current value (if you want to know what the value was before reading)
+  currentValue?: any;
+};
+
+type SetArgs<DecoratorArgs extends any[] = any[]> = {
+  decoratorArgs: DecoratorArgs;
+  target: Object;
+  propertyKey: string | symbol;
+  newValue: any;
+  // current value (before set)
+  currentValue?: any;
+};
+
+/**
+ * Factory for creating a property decorator with separate hooks for
+ * get and set operations. Each hook is optional and can be composed
+ * independently.
+ */
+export function createPropertyDecorator<
+  DecoratorArgs extends any[] = any[],
+  // Value type can be inferred from usage; here we keep it generic
+  Value = any
+>(options?: {
+  beforeGet?: (ctx: GetArgs<DecoratorArgs>) => BeforeGetResult;
+  afterGet?: (ctx: GetArgs<DecoratorArgs> & { value: Value }) => AfterGetResult;
+  beforeSet?: (ctx: SetArgs<DecoratorArgs>) => BeforeSetResult;
+  afterSet?: (ctx: SetArgs<DecoratorArgs> & { value: Value }) => AfterSetResult;
+}): (...decoratorArgs: DecoratorArgs) => PropertyDecorator {
+  return (...decoratorArgs: DecoratorArgs) => {
+    return (target: Object, propertyKey: string | symbol) => {
+      // Backing field to store the value
+      const backingKey = Symbol(`__${String(propertyKey)}`);
+
+      // Retrieve existing descriptor if any
+      const descriptor = Object.getOwnPropertyDescriptor(
+        target,
+        propertyKey
+      ) || {
+        configurable: true,
+        enumerable: true,
+      };
+
+      Object.defineProperty(target, propertyKey, {
+        configurable: descriptor.configurable ?? true,
+        enumerable: descriptor.enumerable ?? true,
+        get: function (): Value {
+          const currentValue = this[backingKey];
+          const ctx: GetArgs<DecoratorArgs> = {
+            decoratorArgs,
+            target,
+            propertyKey,
+            currentValue,
+          };
+
+          const run = async () => {
+            const allowRead = options?.beforeGet
+              ? await options.beforeGet(ctx)
+              : true;
+            const value = allowRead ? currentValue : currentValue;
+            if (options?.afterGet) {
+              await options.afterGet({ ...ctx, value } as any);
+            }
+            return value as Value;
+          };
+
+          // Return a promise if any hook is async
+          // Otherwise, return synchronously
+          // Here we opt to return a Promise to keep behavior consistent with async hooks
+          return run() as unknown as Value;
+        },
+        set: function (newValue: any) {
+          const currentValue = this[propertyKey as string];
+          const ctx: SetArgs<DecoratorArgs> = {
+            decoratorArgs,
+            target,
+            propertyKey,
+            newValue,
+            currentValue,
+          };
+
+          const run = async () => {
+            const allowWrite = options?.beforeSet
+              ? await options.beforeSet(ctx)
+              : true;
+            if (allowWrite) {
+              this[backingKey] = newValue;
+            }
+            if (options?.afterSet) {
+              await options.afterSet({ ...ctx, value: newValue } as any);
+            }
+          };
+
+          // Fire asynchronously to mirror async hooks
+          void run();
+        },
+      });
+    };
+  };
+}

package/src/core/helpers/format.ts

@@ -0,0 +1,9 @@
+/**
+ * Formats a string by replacing placeholders with provided arguments.
+ * Placeholders are in the format {index}, where index is the zero-based position of the argument.
+ */
+export function format(template: string, ...args: any[]): string {
+  return template.replace(/{(\d+)}/g, (match, index) => {
+    return args[index] !== undefined ? args[index] : match;
+  });
+}

package/src/core/helpers/index.ts

@@ -0,0 +1,7 @@
+export * from "./assignment";
+export * from "./conversion";
+export * from "./comparison";
+export * from "./range";
+export * from "./types";
+export * from "./format";
+export * from "./decorators";

package/src/core/helpers/range.ts

@@ -0,0 +1,67 @@
+/**
+ * Generate a range of numbers.
+ *
+ * Creates an array of numbers starting at `start`, up to (and optionally including)
+ * `end`, incrementing by `step`. The function supports both positive and negative steps.
+ *
+ * @param start - The starting value of the range (inclusive by default).
+ * @param end - The end value of the range. The range will stop before this value unless you enable `inclusiveEnd`.
+ * @param step - The difference between successive numbers. Must be non-zero. Defaults to 1.
+ * @param inclusiveEnd - If true, includes the `end` value in the result (when stepping towards it). Defaults to false.
+ * @returns An array of numbers representing the generated range.
+ *
+ * @throws If `step` is 0.
+ *
+ * @example
+ * [1, 2, 3, 4, 5]
+ * range(1, 6);
+ *
+ * @example
+ * [1, 3, 5]
+ * range(1, 6, 2);
+ *
+ * @example
+ * [1, 2, 3, 4, 5] (inclusive end)
+ * range(1, 5, 1, true);
+ *
+ * @example
+ * [5, 3, 1] (negative step, exclusive end)
+ * range(5, 0, -2);
+ *
+ * @example
+ * [5, 3, 1, -1] (negative step, inclusive end)
+ * range(5, -2, -2, true);
+ */
+export function range(
+  start: number,
+  end: number,
+  step = 1,
+  inclusiveEnd: boolean = false
+): number[] {
+  if (step === 0) throw new Error("step must be non-zero");
+  // Helper to build an array from a function over indices
+  // For inclusiveEnd = false:
+  //   if step > 0 -> [start, start+step, ..., < end]
+  //   if step < 0 -> [start, start+step, ..., > end]
+  // We'll compute count and then map over [0..count-1]
+  if (inclusiveEnd === false) {
+    if (step > 0) {
+      const count = Math.max(0, Math.ceil((end - start) / step));
+      return Array.from({ length: count }, (_, i) => start + i * step);
+    } else {
+      const count = Math.max(0, Math.ceil((start - end) / -step));
+      return Array.from({ length: count }, (_, i) => start + i * step);
+    }
+  }
+
+  // inclusiveEnd = true
+  if (step > 0) {
+    // include end if reachable: values are start, start+step, ..., end
+    const count = start <= end ? Math.floor((end - start) / step) + 1 : 0;
+    return Array.from({ length: count }, (_, i) => start + i * step);
+  } else {
+    // step < 0
+    const count = start >= end ? Math.floor((start - end) / -step) + 1 : 0;
+    return Array.from({ length: count }, (_, i) => start + i * step);
+  }
+}

package/src/core/helpers/types.ts

@@ -0,0 +1,3 @@
+export type SyncFn = (...args: any[]) => any;
+export type AsyncFn = (...args: any[]) => Promise<any>;
+export type Fn = (...args: any[]) => Promise<any> | any;

package/src/core/logger/index.ts

@@ -0,0 +1,4 @@
+import { resolve } from "@/core/container";
+import { WinstonLoggerService } from "./winston-logger.service";
+
+export const logger = resolve(WinstonLoggerService);

package/src/{utilities/logger/logger.config.ts → core/logger/winston-logger.config.ts}

@@ -85,7 +85,7 @@ const customLevels = {
 
 winston.addColors(customLevels.colors);
 
-export const logger = winston.createLogger({
+export const winstonLogger = winston.createLogger({
   levels: customLevels.levels,
   level: "trace",
   transports: [consoleTransport, fileTransport],

package/src/{utilities → core}/logger/winston-logger.service.ts

@@ -1,5 +1,5 @@
-import { logger } from "./logger.config";
-import { Injectable } from "../container";
+import { winstonLogger } from "./winston-logger.config";
+import { Injectable } from "../container/container";
 import { LoggerService } from "./logger.service";
 
 @Injectable({ singleton: true })
@@ -11,6 +11,6 @@ export class WinstonLoggerService extends LoggerService {
    * Constructs a new LoggerService instance.
    */
   public constructor() {
-    super(logger);
+    super(winstonLogger);
   }
 }

package/src/core/message-broker/bullmq/basic-types.ts

@@ -0,0 +1,67 @@
+import { JobsOptions } from "bullmq";
+import { BrokerSerializer } from "../utilities";
+
+/**
+ * Configuration options for a BullMQ queue.
+ */
+export interface QueueConfig {
+  name: string;
+  connection?: any; // redis options or a BullMQ connection object
+  defaultJobOptions?: JobsOptions;
+  limiter?: { max: number; duration: number } | undefined;
+  prefix?: string;
+}
+
+/**
+ * Configuration options for a BullMQ producer.
+ */
+export interface ProducerConfig<T = any> {
+  queueName: string;
+  connection?: any;
+  defaultJobOptions?: JobsOptions;
+  serializer?: BrokerSerializer<T>;
+  retry?: { attempts?: number; backoffMs?: number; maxMs?: number };
+}
+
+/**
+ * Configuration options for a BullMQ message.
+ */
+export interface BrokerMessage<T = any> {
+  topic: string;
+  payload: T;
+  headers?: any;
+  timestamp: number;
+  id?: string;
+}
+
+/**
+ * Configuration options for a BullMQ consumer.
+ */
+export interface ConsumerConfig<T = any> {
+  queueName: string;
+  connection?: any;
+  concurrency?: number;
+  processor: (job: {
+    id: string;
+    data: T;
+    attemptsMade: number;
+    timestamp: number;
+  }) => Promise<void> | void;
+  serializer?: BrokerSerializer<T>;
+}
+
+/**
+ * Configuration options for a BullMQ broker.
+ */
+export interface Broker {
+  publish<T>(topic: string, message: T, options?: any): Promise<void>;
+  subscribe<T>(
+    topic: string,
+    handler: (msg: BrokerMessage<T>) => Promise<void> | void,
+    options?: any
+  ): Promise<void>;
+  unsubscribe<T>(
+    topic: string,
+    handler: (msg: BrokerMessage<T>) => Promise<void> | void
+  ): Promise<void>;
+}

package/src/core/message-broker/bullmq/broker.ts

@@ -0,0 +1,141 @@
+import { Queue, JobScheduler, Worker } from "bullmq";
+import { Broker, BrokerMessage } from "./basic-types";
+
+/**
+ * Topic handler function type.
+ */
+type TopicHandler<T = any> = (msg: BrokerMessage<T>) => Promise<void> | void;
+
+/**
+ * BullMQ message broker implementation.
+ */
+export class BullMqBroker implements Broker {
+  private queues = new Map<string, Queue>();
+  private workers = new Map<string, Worker>();
+  private topicHandlers = new Map<string, Set<TopicHandler<any>>>();
+
+  /**
+   * Constructor for a BullMQ message broker.
+   * @param options - Optional configuration options for the broker.
+   * If provided, the connection option will be used when creating queues.
+   */
+  constructor(private connection?: any) {}
+
+  /**
+   * Returns a BullMQ queue for a given topic.
+   * If the queue does not exist, it will be created with the given connection options.
+   * @param topic - The topic to get the queue for.
+   * @returns The BullMQ queue for the given topic.
+   */
+  private getQueueForTopic(topic: string): Queue {
+    const key = `topic:${topic}`;
+    if (!this.queues.has(key)) {
+      const q = new Queue(key, {
+        connection: this.connection,
+      });
+      this.queues.set(key, q);
+    }
+    // cast safe as Queue
+    return this.queues.get(key)!;
+  }
+
+  /**
+   * Returns a worker for a given topic.
+   * If the worker does not exist, it will be created with the given connection options.
+   * The worker will be responsible for processing all messages published to the given topic.
+   * @param topic - The topic to get the worker for.
+   * @returns The worker for the given topic.
+   */
+  private getWorkerForTopic(topic: string): Worker {
+    const key = `topic:${topic}`;
+    if (!this.workers.has(key)) {
+      const worker = new Worker(
+        key,
+        async (job: any) => {
+          const payload = job.data;
+          const msg: BrokerMessage = {
+            topic,
+            payload,
+            timestamp: Date.now(),
+            id: job.id,
+          };
+          const handlers = this.topicHandlers.get(topic);
+          if (handlers && handlers.size > 0) {
+            for (const h of Array.from(handlers)) {
+              await h(msg);
+            }
+          }
+        },
+        { connection: this.connection }
+      );
+      this.workers.set(key, worker);
+    }
+    return this.workers.get(key)!;
+  }
+
+  /**
+   * Publishes a message to a topic.
+   * @param topic - The topic to publish the message to.
+   * @param message - The message payload to publish.
+   * @param _options - Optional configuration options.
+   * @returns A promise resolved when the message has been published to the topic.
+   */
+  public async publish<T>(
+    topic: string,
+    message: T,
+    _options?: any
+  ): Promise<void> {
+    const q = this.getQueueForTopic(topic);
+    await q.add("message", message);
+  }
+
+  /**
+   * Subscribes a handler to a topic.
+   * @param topic - The topic to subscribe to.
+   * @param handler - The handler to invoke when a message is received from the topic.
+   * @param _options - Optional configuration options.
+   * @returns A promise resolved when the handler has been subscribed to the topic.
+   */
+  public async subscribe<T>(
+    topic: string,
+    handler: (msg: BrokerMessage<T>) => Promise<void> | void,
+    _options?: any
+  ): Promise<void> {
+    // register handler
+    if (!this.topicHandlers.has(topic))
+      this.topicHandlers.set(topic, new Set());
+    this.topicHandlers.get(topic)!.add(handler as TopicHandler<T>);
+
+    // ensure a worker exists for the topic
+    this.getWorkerForTopic(topic);
+  }
+
+  /**
+   * Unsubscribes a handler from a topic.
+   * @param topic - The topic to unsubscribe from.
+   * @param handler - The handler to remove from the topic.
+   * @returns A promise resolved when the handler has been removed from the topic.
+   */
+  public async unsubscribe<T>(
+    topic: string,
+    handler: (msg: BrokerMessage<T>) => Promise<void> | void
+  ): Promise<void> {
+    const set = this.topicHandlers.get(topic);
+    if (set) {
+      set.delete(handler as TopicHandler<T>);
+    }
+  }
+
+  /**
+   * Gracefully shuts down the broker, closing all workers and queues.
+   * @returns A promise resolved when all workers and queues have been closed.
+   */
+  public async close(): Promise<void> {
+    // graceful shutdown
+    for (const w of this.workers.values()) await w.close();
+    for (const q of this.queues.values()) await q.close();
+    this.workers.clear();
+    this.queues.clear();
+    this.topicHandlers.clear();
+  }
+}

package/src/core/message-broker/bullmq/index.ts

@@ -0,0 +1,3 @@
+export * from "./basic-types";
+export * from "./queue";
+export * from "./worker";