@invariant--labs/foundation 1.1.2

package/src/testing/stub.ts

@@ -0,0 +1,170 @@
+import { FakeImplementationError } from "../core/errors";
+import { hashKey } from "../utils";
+
+/** Extracts method names from a type as string literal union */
+type MethodKeys<T> = { [K in keyof T]: T[K] extends (...args: never[]) => unknown ? K : never }[keyof T] & string;
+
+/** Extracts the argument types of a method */
+type MethodArgs<T, K extends keyof T> = T[K] extends (...args: infer P) => unknown ? P : never;
+
+/** Extracts the awaited return value of a method (unwraps Promise) */
+type MethodReturn<T, K extends keyof T> = T[K] extends (...args: never[]) => infer R ? Awaited<R> : never;
+
+/** Extracts the raw return type of a method (preserves Promise) */
+type MethodReturnType<T, K extends keyof T> = T[K] extends (...args: never[]) => infer R ? R : never;
+
+type StubEntry<TResult> = { type: "result"; value: TResult } | { type: "error"; error: Error };
+type StubStore<TSelf> = Map<string, StubEntry<MethodReturn<TSelf, MethodKeys<TSelf>>>>;
+
+/**
+ * Factory for generating stub keys.
+ * Centralizes the logic for global (method-level) and specific (args-level) keys.
+ */
+class StubKeyFactory<TSelf, K extends MethodKeys<TSelf>> {
+  constructor(
+    private readonly methodName: K,
+    private readonly args?: MethodArgs<TSelf, K>,
+  ) {}
+
+  /** Global key for method-level stubs (applies to any args) */
+  global(): string {
+    return this.methodName;
+  }
+
+  /** Specific key for arg-specific stubs */
+  specific(): string {
+    return hashKey({ methodName: this.methodName, params: this.args });
+  }
+}
+
+/**
+ * Builder for specifying method arguments or global method behavior.
+ * Part of the fluent API: `stub.onMethod("name").withArgs(...)` or `stub.onMethod("name").throwError(...)`
+ */
+class StubArgsBuilder<TSelf, K extends MethodKeys<TSelf>> {
+  private readonly keyFactory: StubKeyFactory<TSelf, K>;
+
+  constructor(
+    private readonly store: StubStore<TSelf>,
+    private readonly methodName: K,
+    private readonly className: string,
+  ) {
+    this.keyFactory = new StubKeyFactory(methodName);
+  }
+
+  /**
+   * Specifies the arguments for the stubbed method call.
+   * @param args - The arguments to match when the method is called
+   */
+  withArgs(...args: MethodArgs<TSelf, K>): StubResultBuilder<TSelf, K> {
+    return new StubResultBuilder(this.store, this.methodName, args, this.className);
+  }
+
+  /**
+   * Stubs the method to return a value for any arguments.
+   * @param result - The value to return regardless of arguments
+   */
+  returnValue(result: MethodReturn<TSelf, K>): void {
+    this.store.set(this.keyFactory.global(), { type: "result", value: result });
+  }
+
+  /**
+   * Stubs the method to throw an error for any arguments.
+   * @param error - The error to throw regardless of arguments
+   */
+  throwError(error: Error): void {
+    this.store.set(this.keyFactory.global(), { type: "error", error });
+  }
+}
+
+/**
+ * Builder for defining stub behavior or executing the stub.
+ * Part of the fluent API: `stub.onMethod("name").withArgs(...).returnValue(...)`
+ */
+class StubResultBuilder<TSelf, K extends MethodKeys<TSelf>> {
+  private readonly keyFactory: StubKeyFactory<TSelf, K>;
+
+  constructor(
+    private readonly store: StubStore<TSelf>,
+    methodName: K,
+    args: MethodArgs<TSelf, K>,
+    private readonly className: string,
+  ) {
+    this.keyFactory = new StubKeyFactory(methodName, args);
+  }
+
+  /**
+   * Stubs the method to return a value when called with the specified arguments.
+   * @param result - The value to return
+   */
+  returnValue(result: MethodReturn<TSelf, K>): void {
+    this.store.set(this.keyFactory.specific(), { type: "result", value: result });
+  }
+
+  /**
+   * Stubs the method to throw an error when called with the specified arguments.
+   * @param error - The error to throw
+   */
+  throwError(error: Error): void {
+    this.store.set(this.keyFactory.specific(), { type: "error", error });
+  }
+
+  /**
+   * Executes the stub and returns the configured result or throws the configured error.
+   * @throws {FakeImplementationError} If no stub is configured for the given method and arguments
+   * @throws The configured error if `throwError` was used (with or without args)
+   */
+  execute(): MethodReturnType<TSelf, K> {
+    const entry = this.store.get(this.keyFactory.specific()) ?? this.store.get(this.keyFactory.global());
+
+    if (!entry) {
+      throw new FakeImplementationError(this.className, this.keyFactory.global());
+    }
+
+    if (entry.type === "error") {
+      throw entry.error;
+    }
+
+    return entry.value as MethodReturnType<TSelf, K>;
+  }
+}
+
+/**
+ * Abstract base class for creating type-safe method stubs.
+ *
+ * @example
+ * ```typescript
+ * class FakeUserService extends Stub<FakeUserService> implements UserService {
+ *   async fetchUser(id: string): Promise<User> {
+ *     return this.onMethod("fetchUser").withArgs(id).execute();
+ *   }
+ * }
+ *
+ * // In tests:
+ * const fake = new FakeUserService();
+ *
+ * // Stub specific args
+ * fake.onMethod("fetchUser").withArgs("123").returnValue({ id: "123", name: "John" });
+ * fake.onMethod("fetchUser").withArgs("invalid").throwError(new NotFoundError());
+ *
+ * // Stub for any args (global fallback)
+ * fake.onMethod("fetchUser").returnValue({ id: "default", name: "Default" });
+ * fake.onMethod("fetchUser").throwError(new ServiceUnavailableError());
+ * ```
+ */
+export abstract class Stub<TSelf = unknown> {
+  protected store: StubStore<TSelf> = new Map();
+
+  /**
+   * Starts the stub configuration for a method.
+   * @param methodName - The name of the method to stub
+   */
+  onMethod<K extends MethodKeys<TSelf>>(methodName: K): StubArgsBuilder<TSelf, K> {
+    return new StubArgsBuilder(this.store, methodName, this.constructor.name);
+  }
+
+  /** Clears all stubbed configurations. */
+  clear(): void {
+    this.store.clear();
+  }
+}

package/src/testing/stubs/command-bus.stub.ts

@@ -0,0 +1,33 @@
+import { ModuleRef } from "@nestjs/core";
+import { CommandBus, ICommand } from "@nestjs/cqrs";
+
+export class StubCommandBus extends CommandBus {
+  stubCommandData = new Map<string, unknown>();
+  executedCommand: ICommand[] = [];
+  error?: string;
+
+  constructor() {
+    super({} as ModuleRef);
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  override execute(command: ICommand): Promise<any> {
+    if (this.error) {throw new Error(this.error);}
+    this.executedCommand.push(command);
+    return Promise.resolve(this.stubCommandData.get(command.constructor.name));
+  }
+
+  setCommandResponse(commandType: { name: string }, commandResponse: unknown) {
+    this.stubCommandData.set(commandType.name, commandResponse);
+  }
+
+  setError(error: string) {
+    this.error = error;
+  }
+
+  clear() {
+    this.stubCommandData.clear();
+    this.executedCommand = [];
+    this.error = undefined;
+  }
+}

package/src/testing/stubs/event-bus.stub.ts

@@ -0,0 +1,56 @@
+import { IEvent, IEventBus, IEventPublisher, ObservableBus } from "@nestjs/cqrs";
+import { Observable } from "rxjs";
+
+export class StubEventBus<EventBase extends IEvent = IEvent> extends ObservableBus<EventBase> implements IEventBus<EventBase> {
+  stubEventData: Map<unknown, IEvent> = new Map();
+  error?: string;
+
+  get publisher() {
+    return this;
+  }
+
+  set publisher(_publisher: IEventPublisher<EventBase>) {}
+
+  publishAll(events: IEvent[]): unknown {
+    if (this.error) {
+      throw new Error(this.error);
+    }
+    return events.map((event) => this.stubEventData.set(event, event));
+  }
+
+  publish(event: IEvent): unknown {
+    return this.stubEventData.set(event.constructor.name, event);
+  }
+
+  getEvents() {
+    return this.stubEventData;
+  }
+
+  clear() {
+    this.stubEventData.clear();
+  }
+
+  registerSagas() {
+    return undefined;
+  }
+
+  register() {
+    return undefined;
+  }
+
+  bind() {
+    return undefined;
+  }
+
+  protected registerHandler() {
+    return undefined;
+  }
+
+  protected ofEventId(): Observable<EventBase> {
+    return new Observable();
+  }
+
+  protected registerSaga() {
+    return undefined;
+  }
+}

package/src/testing/stubs/event-publisher.stub.ts

@@ -0,0 +1,24 @@
+/* eslint-disable @typescript-eslint/no-unsafe-assignment */
+import { AggregateRoot, Constructor, IEvent } from "@nestjs/cqrs";
+
+import { StubEventBus } from "./event-bus.stub";
+
+export class StubEventPublisher<EventBase extends IEvent = IEvent> extends StubEventBus<EventBase> {
+  mergeObjectContext<T extends AggregateRoot<EventBase>>(object: T): T {
+    Object.assign(object, {
+      publish: this.publish.bind(this),
+      publishAll: this.publishAll.bind(this),
+    });
+
+    return object;
+  }
+
+  mergeClassContext<T extends Constructor<AggregateRoot<EventBase>>>(metatype: T): T {
+    Object.assign(metatype.prototype, {
+      publish: this.publish.bind(this),
+      publishAll: this.publishAll.bind(this),
+    });
+
+    return metatype;
+  }
+}

package/src/testing/stubs/index.ts

@@ -0,0 +1,5 @@
+export * from "./command-bus.stub";
+export * from "./event-bus.stub";
+export * from "./event-publisher.stub";
+export * from "./query-bus.stub";
+export * from "./stub";

package/src/testing/stubs/query-bus.stub.ts

@@ -0,0 +1,27 @@
+import { IQuery } from "@nestjs/cqrs";
+
+export class StubQueryBus {
+  stubQueryData: Map<string, unknown> = new Map();
+  error?: string;
+
+  execute(query: IQuery) {
+    if (this.error) {
+      throw new Error(this.error);
+    }
+
+    return this.stubQueryData.get(query.constructor.name);
+  }
+
+  setQueryResponse(queryType: IQuery, queryResponse: unknown) {
+    this.stubQueryData.set(queryType.constructor.name, queryResponse);
+  }
+
+  setError(error: string) {
+    this.error = error;
+  }
+
+  clear() {
+    this.stubQueryData.clear();
+    this.error = undefined;
+  }
+}

package/src/testing/stubs/stub.ts

@@ -0,0 +1,170 @@
+import { FakeImplementationError } from "../../core/errors";
+import { hashKey } from "../../utils";
+
+/** Extracts method names from a type as string literal union */
+type MethodKeys<T> = { [K in keyof T]: T[K] extends (...args: never[]) => unknown ? K : never }[keyof T] & string;
+
+/** Extracts the argument types of a method */
+type MethodArgs<T, K extends keyof T> = T[K] extends (...args: infer P) => unknown ? P : never;
+
+/** Extracts the awaited return value of a method (unwraps Promise) */
+type MethodReturn<T, K extends keyof T> = T[K] extends (...args: never[]) => infer R ? Awaited<R> : never;
+
+/** Extracts the raw return type of a method (preserves Promise) */
+type MethodReturnType<T, K extends keyof T> = T[K] extends (...args: never[]) => infer R ? R : never;
+
+type StubEntry<TResult> = { type: "result"; value: TResult } | { type: "error"; error: Error };
+type StubStore<TSelf> = Map<string, StubEntry<MethodReturn<TSelf, MethodKeys<TSelf>>>>;
+
+/**
+ * Factory for generating stub keys.
+ * Centralizes the logic for global (method-level) and specific (args-level) keys.
+ */
+class StubKeyFactory<TSelf, K extends MethodKeys<TSelf>> {
+  constructor(
+    private readonly methodName: K,
+    private readonly args?: MethodArgs<TSelf, K>,
+  ) {}
+
+  /** Global key for method-level stubs (applies to any args) */
+  global(): string {
+    return this.methodName;
+  }
+
+  /** Specific key for arg-specific stubs */
+  specific(): string {
+    return hashKey({ methodName: this.methodName, params: this.args });
+  }
+}
+
+/**
+ * Builder for specifying method arguments or global method behavior.
+ * Part of the fluent API: `stub.onMethod("name").withArgs(...)` or `stub.onMethod("name").throwError(...)`
+ */
+class StubArgsBuilder<TSelf, K extends MethodKeys<TSelf>> {
+  private readonly keyFactory: StubKeyFactory<TSelf, K>;
+
+  constructor(
+    private readonly store: StubStore<TSelf>,
+    private readonly methodName: K,
+    private readonly className: string,
+  ) {
+    this.keyFactory = new StubKeyFactory(methodName);
+  }
+
+  /**
+   * Specifies the arguments for the stubbed method call.
+   * @param args - The arguments to match when the method is called
+   */
+  withArgs(...args: MethodArgs<TSelf, K>): StubResultBuilder<TSelf, K> {
+    return new StubResultBuilder(this.store, this.methodName, args, this.className);
+  }
+
+  /**
+   * Stubs the method to return a value for any arguments.
+   * @param result - The value to return regardless of arguments
+   */
+  returnValue(result: MethodReturn<TSelf, K>): void {
+    this.store.set(this.keyFactory.global(), { type: "result", value: result });
+  }
+
+  /**
+   * Stubs the method to throw an error for any arguments.
+   * @param error - The error to throw regardless of arguments
+   */
+  throwError(error: Error): void {
+    this.store.set(this.keyFactory.global(), { type: "error", error });
+  }
+}
+
+/**
+ * Builder for defining stub behavior or executing the stub.
+ * Part of the fluent API: `stub.onMethod("name").withArgs(...).returnValue(...)`
+ */
+class StubResultBuilder<TSelf, K extends MethodKeys<TSelf>> {
+  private readonly keyFactory: StubKeyFactory<TSelf, K>;
+
+  constructor(
+    private readonly store: StubStore<TSelf>,
+    methodName: K,
+    args: MethodArgs<TSelf, K>,
+    private readonly className: string,
+  ) {
+    this.keyFactory = new StubKeyFactory(methodName, args);
+  }
+
+  /**
+   * Stubs the method to return a value when called with the specified arguments.
+   * @param result - The value to return
+   */
+  returnValue(result: MethodReturn<TSelf, K>): void {
+    this.store.set(this.keyFactory.specific(), { type: "result", value: result });
+  }
+
+  /**
+   * Stubs the method to throw an error when called with the specified arguments.
+   * @param error - The error to throw
+   */
+  throwError(error: Error): void {
+    this.store.set(this.keyFactory.specific(), { type: "error", error });
+  }
+
+  /**
+   * Executes the stub and returns the configured result or throws the configured error.
+   * @throws {FakeImplementationError} If no stub is configured for the given method and arguments
+   * @throws The configured error if `throwError` was used (with or without args)
+   */
+  execute(): MethodReturnType<TSelf, K> {
+    const entry = this.store.get(this.keyFactory.specific()) ?? this.store.get(this.keyFactory.global());
+
+    if (!entry) {
+      throw new FakeImplementationError(this.className, this.keyFactory.global());
+    }
+
+    if (entry.type === "error") {
+      throw entry.error;
+    }
+
+    return entry.value as MethodReturnType<TSelf, K>;
+  }
+}
+
+/**
+ * Abstract base class for creating type-safe method stubs.
+ *
+ * @example
+ * ```typescript
+ * class FakeUserService extends Stub<FakeUserService> implements UserService {
+ *   async fetchUser(id: string): Promise<User> {
+ *     return this.onMethod("fetchUser").withArgs(id).execute();
+ *   }
+ * }
+ *
+ * // In tests:
+ * const fake = new FakeUserService();
+ *
+ * // Stub specific args
+ * fake.onMethod("fetchUser").withArgs("123").returnValue({ id: "123", name: "John" });
+ * fake.onMethod("fetchUser").withArgs("invalid").throwError(new NotFoundError());
+ *
+ * // Stub for any args (global fallback)
+ * fake.onMethod("fetchUser").returnValue({ id: "default", name: "Default" });
+ * fake.onMethod("fetchUser").throwError(new ServiceUnavailableError());
+ * ```
+ */
+export abstract class Stub<TSelf = unknown> {
+  protected store: StubStore<TSelf> = new Map();
+
+  /**
+   * Starts the stub configuration for a method.
+   * @param methodName - The name of the method to stub
+   */
+  onMethod<K extends MethodKeys<TSelf>>(methodName: K): StubArgsBuilder<TSelf, K> {
+    return new StubArgsBuilder(this.store, methodName, this.constructor.name);
+  }
+
+  /** Clears all stubbed configurations. */
+  clear(): void {
+    this.store.clear();
+  }
+}

package/src/utils/array.spec.ts

@@ -0,0 +1,29 @@
+import { chunk } from "./array";
+
+const generateArray = (length: number): number[] => new Array<number>(length).fill(0);
+
+describe("chunk", () => {
+  it("should split 1 array 100 items into 10 array 10 items", () => {
+    const ARRAY = generateArray(100);
+
+    const chunks = chunk(ARRAY, 10);
+
+    expect(chunks.length).toEqual(10);
+    chunks.forEach((chunk) => expect(chunk.length).toEqual(10));
+  });
+
+  it("should split 1 array 95 items into 9 array 10 items and 1 array 5 items", () => {
+    const ARRAY = generateArray(95);
+
+    const chunks = chunk(ARRAY, 10);
+
+    expect(chunks.length).toEqual(10);
+    chunks.forEach((chunk, index) => {
+      if (index !== 9) {
+        expect(chunk.length).toEqual(10);
+      } else {
+        expect(chunk.length).toEqual(5);
+      }
+    });
+  });
+});

package/src/utils/array.ts

@@ -0,0 +1,10 @@
+/* eslint-disable @typescript-eslint/unbound-method */
+import _ from "lodash";
+
+export const uniqBy = _.uniqBy;
+export const maxBy = _.maxBy;
+export const minBy = _.minBy;
+export const chunk = _.chunk;
+export const shuffle = _.shuffle;
+export const sum = _.sum;
+export const sortBy = _.sortBy;

package/src/utils/base64.spec.ts

@@ -0,0 +1,18 @@
+import { base64ToString, stringToBase64 } from "./base64";
+
+const UNICODE_STRING = "foo © bar 𝌆 baz";
+const ENCODED_BASE64 = "Zm9vIMKpIGJhciDwnYyGIGJheg==";
+
+describe("base64", () => {
+  describe("base64ToString", () => {
+    it("should decoded base64 to string", () => {
+      expect(base64ToString(ENCODED_BASE64)).toEqual(UNICODE_STRING);
+    });
+  });
+
+  describe("stringToBase64", () => {
+    it("should encoded string to base64", () => {
+      expect(stringToBase64(UNICODE_STRING)).toEqual(ENCODED_BASE64);
+    });
+  });
+});

package/src/utils/base64.ts

@@ -0,0 +1,6 @@
+import { decode as decodeBase64, encode as encodeBase64 } from "base-64";
+import { decode as decodeUtf8, encode as encodeUtf8 } from "utf8";
+
+export const stringToBase64 = (str: string) => encodeBase64(encodeUtf8(str));
+
+export const base64ToString = (base64: string) => decodeUtf8(decodeBase64(base64));

package/src/utils/collection.ts

@@ -0,0 +1,4 @@
+import _ from "lodash";
+
+export const groupBy = (...args: Parameters<typeof _.groupBy>) => _.groupBy(...args);
+export const uniq = <T>(args: T[]) => _.uniq<T>(args);

package/src/utils/common.ts

@@ -0,0 +1,13 @@
+export type RecursiveKeyOf<TObj extends object> = {
+  [TKey in keyof TObj & (string | number)]: RecursiveKeyOfHandleValue<TObj[TKey], `${TKey}`>;
+}[keyof TObj & (string | number)];
+
+type RecursiveKeyOfInner<TObj extends object> = {
+  [TKey in keyof TObj & (string | number)]: RecursiveKeyOfHandleValue<TObj[TKey], `['${TKey}']` | `.${TKey}`>;
+}[keyof TObj & (string | number)];
+
+type RecursiveKeyOfHandleValue<TValue, Text extends string> = TValue extends unknown[]
+  ? Text
+  : TValue extends object
+    ? Text | `${Text}${RecursiveKeyOfInner<TValue>}`
+    : Text;

package/src/utils/csv.ts

@@ -0,0 +1,49 @@
+/* eslint-disable @typescript-eslint/no-unsafe-assignment */
+import "reflect-metadata";
+import { Transform } from "stream";
+
+const META_KEY = Symbol("csv:columns");
+
+type ColumnMeta = { propertyKey: string; displayName: string };
+
+export function CSVFileRecord(): ClassDecorator {
+  return function (target: object) {
+    Reflect.defineMetadata(META_KEY, [], target);
+  };
+}
+
+export function Column(displayName: string): PropertyDecorator {
+  return function (target: object, propertyKey: string | symbol) {
+    const columns: ColumnMeta[] = Reflect.getMetadata(META_KEY, target) ?? [];
+    columns.push({ propertyKey: propertyKey as string, displayName });
+    Reflect.defineMetadata(META_KEY, columns, target);
+  };
+}
+
+export class CSVStream extends Transform {
+  private headerWritten = false;
+
+  constructor() {
+    super({ objectMode: true });
+  }
+
+  _transform(data: Record<string, string>, _enc: string, done: () => void) {
+    const columns = Reflect.getMetadata(META_KEY, data) as ColumnMeta[] | undefined;
+    if (!columns) {throw new Error("data is not a valid record");}
+
+    if (!this.headerWritten) {
+      this.push(columns.map((c) => c.displayName).join(",") + "\r\n");
+      this.headerWritten = true;
+    }
+
+    const row = columns.map((c) => (data[c.propertyKey] ?? "").toString().replace(/"/g, '""'));
+    this.push(`"${row.join('","')}"\r\n`);
+
+    done();
+  }
+
+  _flush(done: () => void) {
+    this.headerWritten = false;
+    done();
+  }
+}

package/src/utils/date/date-range.ts

@@ -0,0 +1,4 @@
+export interface DateRange {
+  from?: Date;
+  to?: Date;
+}