@invariant--labs/foundation 1.1.2

package/src/nestjs/http/interceptors/log-app-ctx.interceptor.ts

@@ -0,0 +1,109 @@
+import { CallHandler, ExecutionContext, Injectable, NestInterceptor } from "@nestjs/common";
+import { GqlContextType, GqlExecutionContext } from "@nestjs/graphql";
+import type { Request } from "express";
+import type { GraphQLResolveInfo } from "graphql";
+
+import { ArchitectureLevel } from "../../../core/types";
+import { LoggerService } from "../../../modules/logger/logger.service";
+
+@Injectable()
+export class LogAppCtxInterceptor implements NestInterceptor {
+  constructor(private readonly loggerService: LoggerService) {}
+
+  intercept(context: ExecutionContext, next: CallHandler) {
+    switch (context.getType<GqlContextType>()) {
+      case "http": {
+        this.setHttpLogContext(context);
+        break;
+      }
+      case "rpc": {
+        this.setRpcLogContext(context);
+        break;
+      }
+      case "ws": {
+        this.setWsLogContext(context);
+        break;
+      }
+      case "graphql": {
+        this.setGraphqlLogContext(context);
+        break;
+      }
+    }
+
+    return next.handle();
+  }
+
+  private setHttpLogContext(context: ExecutionContext) {
+    const className = context.getClass().name;
+    const handlerName = context.getHandler().name;
+    const httpContext = context.switchToHttp();
+    const request = httpContext.getRequest<Request>();
+
+    this.loggerService.ctx({
+      [ArchitectureLevel.INFRASTRUCTURE]: {
+        "web-rest": {
+          className,
+          meta: {
+            handlerName,
+            path: request.url,
+            method: request.method,
+          },
+        },
+      },
+    });
+  }
+
+  private setRpcLogContext(context: ExecutionContext) {
+    const className = context.getClass().name;
+    const handlerName = context.getHandler().name;
+
+    this.loggerService.ctx({
+      [ArchitectureLevel.INFRASTRUCTURE]: {
+        "web-rpc": {
+          className,
+          meta: { handlerName },
+        },
+      },
+    });
+  }
+
+  private setWsLogContext(context: ExecutionContext) {
+    const className = context.getClass().name;
+    const handlerName = context.getHandler().name;
+    const wsContext = context.switchToWs();
+    const pattern = wsContext.getPattern();
+
+    this.loggerService.ctx({
+      [ArchitectureLevel.INFRASTRUCTURE]: {
+        "web-socket": {
+          className,
+          meta: {
+            handlerName,
+            pattern,
+          },
+        },
+      },
+    });
+  }
+
+  private setGraphqlLogContext(context: ExecutionContext) {
+    const className = context.getClass().name;
+    const handlerName = context.getHandler().name;
+    const gqlContext = GqlExecutionContext.create(context);
+    const info = gqlContext.getInfo<GraphQLResolveInfo>();
+
+    this.loggerService.ctx({
+      [ArchitectureLevel.INFRASTRUCTURE]: {
+        "web-graphql": {
+          className,
+          meta: {
+            handlerName,
+            operationName: info.operation.name?.value,
+            operationType: info.operation.operation,
+            fieldName: info.fieldName,
+          },
+        },
+      },
+    });
+  }
+}

package/src/nestjs/http/interceptors/serialize-output.interceptor.ts

@@ -0,0 +1,19 @@
+/* eslint-disable @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-argument */
+import { ClassSerializerInterceptor, mixin, Type, UseInterceptors } from "@nestjs/common";
+import * as ClassTransformer from "class-transformer";
+
+function PojoSerializer<T>(serializedClass: Type<T>): Type<ClassSerializerInterceptor> {
+  class CustomSerializer extends ClassSerializerInterceptor {
+    override transformToPlain(pojoOrInstance: unknown, transformOptions: ClassTransformer.ClassTransformOptions) {
+      transformOptions.strategy ??= "excludeAll";
+      const instance = Object.assign(Object.create(serializedClass.prototype), pojoOrInstance);
+      return super.transformToPlain(instance, transformOptions);
+    }
+  }
+
+  return mixin(CustomSerializer);
+}
+
+export function SerializeOutput<T>(dtoClass: Type<T>) {
+  return UseInterceptors(PojoSerializer(dtoClass));
+}

package/src/nestjs/http/middleware/http-logger.middleware.ts

@@ -0,0 +1,31 @@
+/* eslint-disable @typescript-eslint/no-unsafe-member-access */
+import { Injectable, NestMiddleware } from "@nestjs/common";
+import type { NextFunction, Request, Response } from "express";
+
+import { LoggerService } from "../../../modules/logger/logger.service";
+
+@Injectable()
+export class HttpLoggerMiddleware implements NestMiddleware {
+  constructor(private readonly loggerService: LoggerService) {}
+  use(req?: Request, res?: Response, next?: NextFunction) {
+    try {
+      if (req && res) {
+        const start = Date.now();
+        res.on("close", () => {
+          const graphql = req.body?.operationName ? ` ${req.body.operationName}` : "";
+          this.loggerService.clearCtx();
+          this.loggerService.http(`[${req.method}] ${req.originalUrl}${graphql}`, {
+            body: req.body,
+            method: req.method,
+            metrics: { duration: Date.now() - start },
+            status: res.statusCode,
+          });
+        });
+      }
+    } catch {
+      this.loggerService.warn("something went wrong while logging");
+    }
+
+    next?.();
+  }
+}

package/src/nestjs/http/middleware/index.ts

@@ -0,0 +1,2 @@
+export * from "./http-logger.middleware";
+export * from "./logger.middleware";

package/src/nestjs/http/middleware/logger.middleware.ts

@@ -0,0 +1,21 @@
+import { Injectable, NestMiddleware } from "@nestjs/common";
+import type { NextFunction, Request, Response } from "express";
+import { v4 as uuidv4 } from "uuid";
+
+import { ArchitectureLevel } from "../../../core/types";
+import { LoggerService } from "../../../modules/logger/logger.service";
+
+@Injectable()
+export class LoggerMiddleware implements NestMiddleware {
+  constructor(private readonly loggerService: LoggerService) {}
+  use(req: Request, res: Response, next: NextFunction) {
+    const requestId = uuidv4();
+    this.loggerService.init(req, res, () => {
+      this.loggerService.ctx(
+        { [ArchitectureLevel.INFRASTRUCTURE]: { "web-rest": { className: LoggerMiddleware.name } } },
+        { requestId },
+      );
+      next();
+    });
+  }
+}

package/src/nestjs/http/swagger/index.ts

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

package/src/nestjs/http/swagger/swagger.ts

@@ -0,0 +1,44 @@
+import { INestApplication } from "@nestjs/common";
+import { DocumentBuilder, SwaggerModule } from "@nestjs/swagger";
+import basicAuth from "express-basic-auth";
+
+import { ConfigService } from "../../../core/infrastructure/config";
+
+export function setupSwagger(app: INestApplication) {
+  if (process.env.NODE_ENV !== "development") {
+    setupAuthorization(app);
+  }
+  setupDocumentation(app);
+}
+
+function setupDocumentation(app: INestApplication) {
+  const options = new DocumentBuilder().setTitle("Harbor API").setVersion("1.0").build();
+
+  const document = SwaggerModule.createDocument(app, options);
+  SwaggerModule.setup("docs", app, document, {
+    swaggerOptions: {
+      tagsSorter: "alpha",
+      operationsSorter: "alpha",
+    },
+  });
+}
+
+function setupAuthorization(app: INestApplication) {
+  const configService = app.get(ConfigService);
+
+  app.use(
+    ["/docs"],
+    basicAuth({
+      challenge: true,
+      authorizeAsync: true,
+      authorizer: (email, password, authorize) => {
+        const valid =
+          !!email &&
+          !!password &&
+          email === configService.get("SWAGGER_EMAIL_SWAGGER") &&
+          password === configService.get("SWAGGER_PASSWORD_SWAGGER");
+        authorize(null, valid);
+      },
+    }),
+  );
+}

package/src/nestjs/index.ts

@@ -0,0 +1,2 @@
+export * from "./errors";
+export * from "./http";

package/src/testing/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/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/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/fake-logger.ts

@@ -0,0 +1,20 @@
+import { LoggerService } from "../modules/logger/logger.service";
+import { FakeTransport } from "../modules/logger/transports/fake.transport";
+
+export class FakeLogger extends LoggerService {
+  private transport: FakeTransport;
+
+  constructor() {
+    const transport = new FakeTransport();
+    super({ service: "test", transports: [transport] });
+    this.transport = transport;
+  }
+
+  get logs() {
+    return this.transport.logs;
+  }
+
+  clear() {
+    this.transport.logs = [];
+  }
+}

package/src/testing/index.ts

@@ -0,0 +1,2 @@
+export * from "./fake-logger";
+export * from "./stubs";

package/src/testing/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/stub.spec.ts

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