@invariant--labs/foundation 1.1.2 → 1.1.5

package/src/testing/stub.spec.ts

@@ -1,250 +0,0 @@
-import { FakeImplementationError } from "../core/errors";
-import { Stub } from "./stub";
-
-interface UserService {
-  fetchUser(id: string): Promise<User>;
-  createUser(name: string, email: string): Promise<User>;
-  deleteUser(id: string): Promise<void>;
-}
-
-interface User {
-  id: string;
-  name: string;
-  email: string;
-}
-
-class FakeUserService extends Stub<FakeUserService> implements UserService {
-  async fetchUser(id: string): Promise<User> {
-    return this.onMethod("fetchUser").withArgs(id).execute();
-  }
-
-  async createUser(name: string, email: string): Promise<User> {
-    return this.onMethod("createUser").withArgs(name, email).execute();
-  }
-
-  async deleteUser(id: string): Promise<void> {
-    return this.onMethod("deleteUser").withArgs(id).execute();
-  }
-}
-
-describe(Stub.name, () => {
-  let fake: FakeUserService;
-
-  beforeEach(() => {
-    fake = new FakeUserService();
-  });
-
-  describe("onMethod().withArgs().returnValue()", () => {
-    it("should return the stubbed value when executed", async () => {
-      const user: User = { id: "1", name: "John", email: "john@example.com" };
-
-      fake.onMethod("fetchUser").withArgs("1").returnValue(user);
-
-      const result = await fake.fetchUser("1");
-
-      expect(result).toEqual(user);
-    });
-
-    it("should return different values for different arguments", async () => {
-      const user1: User = { id: "1", name: "John", email: "john@example.com" };
-      const user2: User = { id: "2", name: "Jane", email: "jane@example.com" };
-
-      fake.onMethod("fetchUser").withArgs("1").returnValue(user1);
-      fake.onMethod("fetchUser").withArgs("2").returnValue(user2);
-
-      expect(await fake.fetchUser("1")).toEqual(user1);
-      expect(await fake.fetchUser("2")).toEqual(user2);
-    });
-
-    it("should handle methods with multiple arguments", async () => {
-      const user: User = { id: "1", name: "John", email: "john@example.com" };
-
-      fake.onMethod("createUser").withArgs("John", "john@example.com").returnValue(user);
-
-      const result = await fake.createUser("John", "john@example.com");
-
-      expect(result).toEqual(user);
-    });
-
-    it("should handle void return type", async () => {
-      fake.onMethod("deleteUser").withArgs("1").returnValue(undefined);
-
-      await expect(fake.deleteUser("1")).resolves.toBeUndefined();
-    });
-
-    it("should override previous stub when called again with same args", async () => {
-      const user1: User = { id: "1", name: "John", email: "john@example.com" };
-      const user2: User = { id: "1", name: "John Updated", email: "john.updated@example.com" };
-
-      fake.onMethod("fetchUser").withArgs("1").returnValue(user1);
-      fake.onMethod("fetchUser").withArgs("1").returnValue(user2);
-
-      const result = await fake.fetchUser("1");
-
-      expect(result).toEqual(user2);
-    });
-  });
-
-  describe("onMethod().withArgs().throwError()", () => {
-    it("should throw the stubbed error when executed", async () => {
-      const error = new Error("User not found");
-
-      fake.onMethod("fetchUser").withArgs("invalid").throwError(error);
-
-      await expect(fake.fetchUser("invalid")).rejects.toThrow("User not found");
-    });
-
-    it("should throw different errors for different arguments", async () => {
-      fake.onMethod("fetchUser").withArgs("not-found").throwError(new Error("User not found"));
-      fake.onMethod("fetchUser").withArgs("forbidden").throwError(new Error("Access denied"));
-
-      await expect(fake.fetchUser("not-found")).rejects.toThrow("User not found");
-      await expect(fake.fetchUser("forbidden")).rejects.toThrow("Access denied");
-    });
-
-    it("should override returnValue when throwError is called with same args", async () => {
-      const user: User = { id: "1", name: "John", email: "john@example.com" };
-
-      fake.onMethod("fetchUser").withArgs("1").returnValue(user);
-      fake.onMethod("fetchUser").withArgs("1").throwError(new Error("Changed to error"));
-
-      await expect(fake.fetchUser("1")).rejects.toThrow("Changed to error");
-    });
-
-    it("should override throwError when returnValue is called with same args", async () => {
-      const user: User = { id: "1", name: "John", email: "john@example.com" };
-
-      fake.onMethod("fetchUser").withArgs("1").throwError(new Error("Error first"));
-      fake.onMethod("fetchUser").withArgs("1").returnValue(user);
-
-      const result = await fake.fetchUser("1");
-
-      expect(result).toEqual(user);
-    });
-  });
-
-  describe("onMethod().returnValue()", () => {
-    it("should return the stubbed value for any arguments", async () => {
-      const user: User = { id: "default", name: "Default", email: "default@example.com" };
-
-      fake.onMethod("fetchUser").returnValue(user);
-
-      expect(await fake.fetchUser("any-id")).toEqual(user);
-      expect(await fake.fetchUser("another-id")).toEqual(user);
-    });
-
-    it("should be overridden by arg-specific stub", async () => {
-      const defaultUser: User = { id: "default", name: "Default", email: "default@example.com" };
-      const specificUser: User = { id: "1", name: "John", email: "john@example.com" };
-
-      fake.onMethod("fetchUser").returnValue(defaultUser);
-      fake.onMethod("fetchUser").withArgs("1").returnValue(specificUser);
-
-      expect(await fake.fetchUser("1")).toEqual(specificUser);
-      expect(await fake.fetchUser("other")).toEqual(defaultUser);
-    });
-
-    it("should be used as fallback when arg-specific stub is not found", async () => {
-      const defaultUser: User = { id: "default", name: "Default", email: "default@example.com" };
-      const specificUser: User = { id: "1", name: "John", email: "john@example.com" };
-
-      fake.onMethod("fetchUser").withArgs("1").returnValue(specificUser);
-      fake.onMethod("fetchUser").returnValue(defaultUser);
-
-      expect(await fake.fetchUser("1")).toEqual(specificUser);
-      expect(await fake.fetchUser("unknown")).toEqual(defaultUser);
-    });
-
-    it("should be cleared when clear() is called", async () => {
-      const user: User = { id: "default", name: "Default", email: "default@example.com" };
-
-      fake.onMethod("fetchUser").returnValue(user);
-
-      fake.clear();
-
-      await expect(fake.fetchUser("any-id")).rejects.toThrow(FakeImplementationError);
-    });
-  });
-
-  describe("onMethod().throwError()", () => {
-    it("should throw the stubbed error for any arguments", async () => {
-      fake.onMethod("fetchUser").throwError(new Error("Service unavailable"));
-
-      await expect(fake.fetchUser("any-id")).rejects.toThrow("Service unavailable");
-      await expect(fake.fetchUser("another-id")).rejects.toThrow("Service unavailable");
-    });
-
-    it("should be overridden by arg-specific stub", async () => {
-      const user: User = { id: "1", name: "John", email: "john@example.com" };
-
-      fake.onMethod("fetchUser").throwError(new Error("Service unavailable"));
-      fake.onMethod("fetchUser").withArgs("1").returnValue(user);
-
-      expect(await fake.fetchUser("1")).toEqual(user);
-      await expect(fake.fetchUser("other")).rejects.toThrow("Service unavailable");
-    });
-
-    it("should be used as fallback when arg-specific stub is not found", async () => {
-      const user: User = { id: "1", name: "John", email: "john@example.com" };
-
-      fake.onMethod("fetchUser").withArgs("1").returnValue(user);
-      fake.onMethod("fetchUser").throwError(new Error("Not found"));
-
-      expect(await fake.fetchUser("1")).toEqual(user);
-      await expect(fake.fetchUser("unknown")).rejects.toThrow("Not found");
-    });
-
-    it("should be cleared when clear() is called", async () => {
-      fake.onMethod("fetchUser").throwError(new Error("Service unavailable"));
-
-      fake.clear();
-
-      await expect(fake.fetchUser("any-id")).rejects.toThrow(FakeImplementationError);
-    });
-  });
-
-  describe("onMethod().withArgs().execute()", () => {
-    it("should throw FakeImplementationError when no stub is configured", async () => {
-      await expect(fake.fetchUser("unstubbed")).rejects.toThrow(FakeImplementationError);
-    });
-
-    it("should throw FakeImplementationError with class name in message", async () => {
-      await expect(fake.fetchUser("unstubbed")).rejects.toThrow("fake");
-    });
-
-    it("should throw FakeImplementationError when args do not match and no global stub", async () => {
-      const user: User = { id: "1", name: "John", email: "john@example.com" };
-
-      fake.onMethod("fetchUser").withArgs("1").returnValue(user);
-
-      await expect(fake.fetchUser("2")).rejects.toThrow(FakeImplementationError);
-    });
-  });
-
-  describe("clear()", () => {
-    it("should remove all stubbed configurations", async () => {
-      const user: User = { id: "1", name: "John", email: "john@example.com" };
-
-      fake.onMethod("fetchUser").withArgs("1").returnValue(user);
-
-      expect(await fake.fetchUser("1")).toEqual(user);
-
-      fake.clear();
-
-      await expect(fake.fetchUser("1")).rejects.toThrow(FakeImplementationError);
-    });
-
-    it("should allow re-stubbing after clear", async () => {
-      const user1: User = { id: "1", name: "John", email: "john@example.com" };
-      const user2: User = { id: "1", name: "Jane", email: "jane@example.com" };
-
-      fake.onMethod("fetchUser").withArgs("1").returnValue(user1);
-      fake.clear();
-      fake.onMethod("fetchUser").withArgs("1").returnValue(user2);
-
-      const result = await fake.fetchUser("1");
-
-      expect(result).toEqual(user2);
-    });
-  });
-});

package/src/testing/stub.ts

@@ -1,170 +0,0 @@
-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

@@ -1,33 +0,0 @@
-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

@@ -1,56 +0,0 @@
-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

@@ -1,24 +0,0 @@
-/* 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/query-bus.stub.ts

@@ -1,27 +0,0 @@
-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;
-  }
-}