@invariant--labs/foundation 1.1.2

package/src/core/errors/fake-implementation.error.ts

@@ -0,0 +1,15 @@
+import { ArchitectureLevel } from "../types";
+import { DetailedError } from "./detailed.error";
+
+export class FakeImplementationError extends DetailedError {
+  constructor(className: string, implementationName: string) {
+    super(
+      `[${className}] This is a fake ${implementationName} method, either\n- You didn't stub the corresponding args in your test\n- OR you forgot to stub the method`,
+      {
+        [ArchitectureLevel.INFRASTRUCTURE]: {
+          "persistence-fake": { className },
+        },
+      },
+    );
+  }
+}

package/src/core/errors/index.ts

@@ -0,0 +1,8 @@
+export * from "./command-failure.error";
+export * from "./command-filter.error";
+export * from "./detailed.error";
+export * from "./domain.error";
+export * from "./entity-not-found.error";
+export * from "./fake-implementation.error";
+export * from "./query-failure.error";
+export * from "./too-many-results.error";

package/src/core/errors/query-failure.error.ts

@@ -0,0 +1,8 @@
+import { ArchitectureLevel } from "../types";
+import { DetailedError } from "./detailed.error";
+
+export class QueryFailureError extends DetailedError {
+  constructor(message: string, className: string, cause?: unknown) {
+    super(message, { [ArchitectureLevel.APPLICATION]: { query: { className } } }, cause);
+  }
+}

package/src/core/errors/too-many-results.error.ts

@@ -0,0 +1,3 @@
+import { CustomError } from "ts-custom-error";
+
+export class TooManyResultsError extends CustomError {}

package/src/core/index.ts

@@ -0,0 +1,4 @@
+export * from "./application";
+export * from "./domain";
+export * from "./errors";
+export * from "./types";

package/src/core/infrastructure/config/config.provider.ts

@@ -0,0 +1,78 @@
+import { Injectable } from "@nestjs/common";
+import * as dotenvSafe from "dotenv-safe";
+
+import { ConfigService } from "./config.service";
+
+@Injectable()
+export class ConfigProvider extends ConfigService {
+  private readonly dotenvValues: Record<string, string>;
+
+  constructor() {
+    super();
+    this.assertNodeEnv();
+
+    const envFilePath = this.getDotenvFileName();
+    if (!envFilePath) {
+      this.dotenvValues = {};
+      return;
+    }
+
+    const result = dotenvSafe.config({ allowEmptyValues: true, path: envFilePath });
+    if (result.error) {throw result.error;}
+    this.dotenvValues = result.parsed ?? {};
+  }
+
+  get(key: string): string | undefined {
+    if (key in process.env) {return process.env[key];}
+    if (key in this.dotenvValues) {return this.dotenvValues[key];}
+    throw new Error(`Configuration key ${key} not found`);
+  }
+
+  getUrl(key: string): string | undefined {
+    const url = this.get(key);
+    if (!url) {return undefined;}
+    if (!url.startsWith("http")) {return `https://${url}`;}
+    return url.endsWith("/") ? url.slice(0, -1) : url;
+  }
+
+  getBoolean(key: string): boolean {
+    return this.get(key) === "true";
+  }
+
+  getNumber(key: string): number | undefined {
+    const value = this.get(key);
+    if (!value) {return undefined;}
+    const num = Number(value);
+    if (Number.isNaN(num)) {throw new Error(`Configuration key ${key} is not a number`);}
+    return num;
+  }
+
+  private get nodeEnv() {
+    return process.env["NODE_ENV"];
+  }
+
+  isProduction() { return this.nodeEnv === "production"; }
+  isStaging() { return this.nodeEnv === "staging"; }
+  isSandbox() { return this.nodeEnv === "sandbox"; }
+  isDemo() { return this.nodeEnv === "demo"; }
+  isPreview() { return this.nodeEnv === "preview"; }
+  isTest() { return this.nodeEnv === "test"; }
+  isDevelopment() { return this.nodeEnv === "development"; }
+
+  useFake() {
+    return !this.isProduction() && !this.isStaging() && !this.isSandbox() && !this.isDemo();
+  }
+
+  getDotenvFileName() {
+    if (this.isTest()) {return ".env.test";}
+    if (process.env["CI"] === "true") {return ".env.ci";}
+    if (this.isProduction() || this.isStaging() || this.isPreview()) {return undefined;}
+    return `.env.${this.nodeEnv ?? "development"}`;
+  }
+
+  assertNodeEnv() {
+    if (!this.nodeEnv) {
+      throw new Error("System variable NODE_ENV should be defined before reading env file");
+    }
+  }
+}

package/src/core/infrastructure/config/config.service.ts

@@ -0,0 +1,25 @@
+export abstract class ConfigService {
+  abstract get(key: string): string | undefined;
+
+  abstract getUrl(key: string): string | undefined;
+
+  abstract getBoolean(key: string): boolean;
+
+  abstract getNumber(key: string): number | undefined;
+
+  abstract isProduction(): boolean;
+
+  abstract isStaging(): boolean;
+
+  abstract isSandbox(): boolean;
+
+  abstract isDemo(): boolean;
+
+  abstract useFake(): boolean;
+
+  abstract isPreview(): boolean;
+
+  abstract isTest(): boolean;
+
+  abstract isDevelopment(): boolean;
+}

package/src/core/infrastructure/config/index.ts

@@ -0,0 +1,2 @@
+export * from "./config.provider";
+export * from "./config.service";

package/src/core/infrastructure/messaging/fake/fake-messaging.service.ts

@@ -0,0 +1,17 @@
+import { MessagingService } from "../messaging.service";
+
+export class FakeMessagingService implements MessagingService {
+  private emittedMessages: Record<"pattern" | "payload", unknown>[] = [];
+
+  emit<TPayload>(pattern: string, payload: TPayload) {
+    this.emittedMessages.push({ pattern, payload });
+  }
+
+  getEmittedCount() {
+    return this.emittedMessages.length;
+  }
+
+  reset() {
+    this.emittedMessages = [];
+  }
+}

package/src/core/infrastructure/messaging/fake/fake-queue-manager.service.ts

@@ -0,0 +1,9 @@
+import { QueueManagerService } from "../queue-manager.service";
+import { QueueMessagingService } from "../queue-messaging.service";
+import { FakeQueueMessagingService } from "./fake-queue-messaging.service";
+
+export class FakeQueueManagerService implements QueueManagerService {
+  getMessagingService(): QueueMessagingService {
+    return new FakeQueueMessagingService();
+  }
+}

package/src/core/infrastructure/messaging/fake/fake-queue-messaging.service.ts

@@ -0,0 +1,9 @@
+import { QueueMessagingService } from "../queue-messaging.service";
+
+export class FakeQueueMessagingService implements QueueMessagingService {
+  private emittedMessages: Record<"pattern" | "payload", unknown>[] = [];
+
+  publish<TPayload>(pattern: string, payload: TPayload) {
+    this.emittedMessages.push({ pattern, payload });
+  }
+}

package/src/core/infrastructure/messaging/fake/index.ts

@@ -0,0 +1,3 @@
+export * from "./fake-messaging.service";
+export * from "./fake-queue-manager.service";
+export * from "./fake-queue-messaging.service";

package/src/core/infrastructure/messaging/index.ts

@@ -0,0 +1,6 @@
+export * from "./fake";
+export * from "./messaging.service";
+export * from "./queue-manager.service";
+export * from "./queue-messaging.service";
+export * from "./rabbitmq";
+export * from "./types";

package/src/core/infrastructure/messaging/messaging.service.ts

@@ -0,0 +1,3 @@
+export abstract class MessagingService {
+  abstract emit<TPayload>(pattern: string, payload: TPayload): void;
+}

package/src/core/infrastructure/messaging/queue-manager.service.ts

@@ -0,0 +1,6 @@
+import { QueueMessagingService } from "./queue-messaging.service";
+import { QueueName } from "./types";
+
+export abstract class QueueManagerService {
+  abstract getMessagingService(queueName: QueueName): QueueMessagingService;
+}

package/src/core/infrastructure/messaging/queue-messaging.service.ts

@@ -0,0 +1,3 @@
+export abstract class QueueMessagingService {
+  abstract publish<TPayload>(pattern: string, payload: TPayload): void;
+}

package/src/core/infrastructure/messaging/rabbitmq/index.ts

@@ -0,0 +1,2 @@
+export * from "./rabbit-messaging.service";
+export * from "./rabbit-queue-messaging.service";

package/src/core/infrastructure/messaging/rabbitmq/rabbit-messaging.service.ts

@@ -0,0 +1,11 @@
+import { ClientProxy } from "@nestjs/microservices";
+
+import { MessagingService } from "../messaging.service";
+
+export class RabbitMessagingService implements MessagingService {
+  constructor(private readonly eventBus: ClientProxy) {}
+
+  emit<TPayload>(pattern: string, payload: TPayload) {
+    this.eventBus.emit<void, TPayload>(pattern, payload);
+  }
+}

package/src/core/infrastructure/messaging/rabbitmq/rabbit-queue-messaging.service.ts

@@ -0,0 +1,11 @@
+import { ClientProxy } from "@nestjs/microservices";
+
+import { QueueMessagingService } from "../queue-messaging.service";
+
+export class RabbitQueueMessagingService implements QueueMessagingService {
+  constructor(private readonly clientProxy: ClientProxy) {}
+
+  publish<TPayload>(pattern: string, payload: TPayload) {
+    this.clientProxy.emit<void, TPayload>(pattern, payload);
+  }
+}

package/src/core/infrastructure/messaging/types.ts

@@ -0,0 +1,28 @@
+import { InjectionToken, ModuleMetadata, OptionalFactoryDependency } from "@nestjs/common";
+
+export enum QueueName {
+  COMMUNICATION = "COMMUNICATION",
+  HARBOR_FEEDBACK = "HARBOR_FEEDBACK",
+}
+
+export const QUEUE_NAME_RESOLVER = Symbol();
+export type QueueNameResolver = (queueName: QueueName) => string;
+
+export const CLIENT_PROXY_OPTIONS = Symbol("CLIENT_PROXY_OPTIONS");
+export type ClientProxyOptions = {
+  urls: string[] | Record<string, unknown>[];
+  queueOptions?: Record<string, unknown>;
+};
+
+export const QUEUE_CORE_OPTIONS_TOKEN = Symbol("QUEUE_CORE_OPTIONS_TOKEN");
+
+export interface QueueModuleOptions {
+  clientProxyOptions: ClientProxyOptions;
+  queueNameResolver?: QueueNameResolver;
+}
+
+export interface QueueModuleAsyncOptions extends Pick<ModuleMetadata, "imports"> {
+  inject: (InjectionToken | OptionalFactoryDependency)[];
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  useFactory: (...args: any[]) => Promise<QueueModuleOptions> | QueueModuleOptions;
+}

package/src/core/infrastructure/persistence/errors/index.ts

@@ -0,0 +1,2 @@
+export * from "./model-to-entity-conversion.error";
+export * from "./persistence.error";

package/src/core/infrastructure/persistence/errors/model-to-entity-conversion.error.ts

@@ -0,0 +1,9 @@
+import { PersistenceError } from "./persistence.error";
+
+export class ModelToEntityConversionError<Model> extends PersistenceError {
+  constructor(className: string, model: Model, cause: unknown) {
+    const message = cause instanceof Error ? cause.message : String(cause);
+    super(`ORM Model ${typeof model} cannot be converted to Entity: ${message}`, { "persistence-sql": { className } });
+    this.setDetails({ model });
+  }
+}

package/src/core/infrastructure/persistence/errors/persistence.error.ts

@@ -0,0 +1,8 @@
+import { ArchitectureLayerTrace, ArchitectureLevel } from "../../../types";
+import { DetailedError } from "../../../errors";
+
+export class PersistenceError extends DetailedError {
+  constructor(message: string, architectureTrace: ArchitectureLayerTrace, cause?: unknown) {
+    super(message, { [ArchitectureLevel.INFRASTRUCTURE]: { ...architectureTrace } }, cause);
+  }
+}

package/src/core/infrastructure/persistence/in-memory/fake.repository.ts

@@ -0,0 +1,79 @@
+/* eslint-disable @typescript-eslint/require-await */
+import _ from "lodash";
+
+import { ArchitectureLevel } from "../../../types";
+import { Entity, EntityProps } from "../../../domain/entities/entity";
+import { EntityNotFoundError } from "../../../errors";
+import { FindManyOptions, Repository } from "../../../application/persistence/repository";
+
+export class FakeRepository<DomainEntity extends Entity<EntityProps>> implements Repository<DomainEntity> {
+  protected store: Map<string, DomainEntity>;
+
+  constructor(
+    defaultEntities: DomainEntity[] = [],
+    protected error?: Error,
+  ) {
+    this.store = new Map(defaultEntities.map((e) => [e.id.toString(), e]));
+  }
+
+  async save(entity: DomainEntity): Promise<DomainEntity> {
+    this.checkError();
+    this.store.set(entity.id.toString(), entity);
+    return entity;
+  }
+
+  async saveAll(entities: DomainEntity[]): Promise<void> {
+    this.checkError();
+    for (const entity of entities) {await this.save(entity);}
+  }
+
+  async findOne(id: string): Promise<DomainEntity | null> {
+    return this.store.get(id) ?? null;
+  }
+
+  async findOneOrFail(id: string): Promise<DomainEntity> {
+    const entity = await this.findOne(id);
+    if (!entity) {
+      throw new EntityNotFoundError("FakeEntity", {
+        [ArchitectureLevel.INFRASTRUCTURE]: { "persistence-fake": { className: "FakeRepository" } },
+      });
+    }
+    return entity;
+  }
+
+  async findByIds(ids: string[]): Promise<DomainEntity[]> {
+    return this.toArray().filter((entity) => ids.includes(entity.id.toString()));
+  }
+
+  async delete(entity: DomainEntity): Promise<void> {
+    this.checkError();
+    this.store.delete(entity.id.toString());
+  }
+
+  async exists(id: string): Promise<boolean> {
+    this.checkError();
+    return this.store.has(id);
+  }
+
+  async count(options: FindManyOptions<DomainEntity>): Promise<number> {
+    this.checkError();
+    return _.filter(this.toArray(), options.filters).length;
+  }
+
+  clear(): void {
+    this.store.clear();
+    this.error = undefined;
+  }
+
+  setError(error: Error): void {
+    this.error = error;
+  }
+
+  protected checkError(): void {
+    if (this.error) {throw this.error;}
+  }
+
+  protected toArray(): DomainEntity[] {
+    return [...this.store.values()];
+  }
+}

package/src/core/infrastructure/persistence/in-memory/in-memory.query-builder.ts

@@ -0,0 +1,4 @@
+import { QueryBuilder } from "../../../application";
+import { Stub } from "../../../../testing/stubs/stub";
+
+export abstract class InMemoryQueryBuilder<TSelf = unknown> extends Stub<TSelf> implements QueryBuilder {}

package/src/core/infrastructure/persistence/in-memory/in-memory.repository.spec.ts

@@ -0,0 +1,50 @@
+import { describe, it, expect, beforeEach } from "@jest/globals";
+
+import { Entity, EntityProps } from "../../../domain/entities/entity";
+import { UniqueEntityId } from "../../../domain/entities/unique-entity-id";
+import { EntityNotFoundError } from "../../../errors";
+import { InMemoryRepository } from "./in-memory.repository";
+
+interface ItemProps extends EntityProps { name: string }
+class Item extends Entity<ItemProps> {}
+
+describe("InMemoryRepository", () => {
+  let repo: InMemoryRepository<Item>;
+
+  beforeEach(() => { repo = new InMemoryRepository<Item>(); });
+
+  it("should save and find an entity", async () => {
+    const item = new Item({ name: "a", id: new UniqueEntityId("1") });
+    await repo.save(item);
+    expect(await repo.findOne("1")).toBe(item);
+  });
+
+  it("should return null for missing entity", async () => {
+    expect(await repo.findOne("missing")).toBeNull();
+  });
+
+  it("should throw on findOneOrFail for missing entity", async () => {
+    await expect(repo.findOneOrFail("x")).rejects.toThrow(EntityNotFoundError);
+  });
+
+  it("should delete an entity", async () => {
+    const item = new Item({ name: "a", id: new UniqueEntityId("1") });
+    await repo.save(item);
+    await repo.delete(item);
+    expect(await repo.exists("1")).toBe(false);
+  });
+
+  it("should find entities by ids", async () => {
+    const a = new Item({ name: "a", id: new UniqueEntityId("1") });
+    const b = new Item({ name: "b", id: new UniqueEntityId("2") });
+    await repo.saveAll([a, b]);
+    const result = await repo.findByIds(["1"]);
+    expect(result).toEqual([a]);
+  });
+
+  it("should throw stored error on save", async () => {
+    repo.setError(new Error("boom"));
+    const item = new Item({ name: "a" });
+    await expect(repo.save(item)).rejects.toThrow("boom");
+  });
+});

package/src/core/infrastructure/persistence/in-memory/in-memory.repository.ts

@@ -0,0 +1,81 @@
+/* eslint-disable @typescript-eslint/require-await */
+import _ from "lodash";
+
+import { FindManyOptions, Repository } from "../../../application/persistence/repository";
+import { AggregateRoot, Entity, EntityProps } from "../../../domain";
+import { ArchitectureLevel } from "../../../types";
+import { EntityNotFoundError } from "../../../errors";
+
+export class InMemoryRepository<DomainEntity extends Entity<EntityProps> | AggregateRoot<EntityProps>>
+  implements Repository<DomainEntity>
+{
+  protected store: Map<string, DomainEntity>;
+
+  constructor(
+    defaultEntities: DomainEntity[] = [],
+    protected error?: Error,
+  ) {
+    this.store = new Map(defaultEntities.map((e) => [e.id.toString(), e]));
+  }
+
+  async save(entity: DomainEntity): Promise<DomainEntity> {
+    this.checkError();
+    this.store.set(entity.id.toString(), entity);
+    return entity;
+  }
+
+  async saveAll(entities: DomainEntity[]): Promise<void> {
+    this.checkError();
+    for (const entity of entities) {await this.save(entity);}
+  }
+
+  async findOne(id: string): Promise<DomainEntity | null> {
+    return this.store.get(id) ?? null;
+  }
+
+  async findOneOrFail(id: string): Promise<DomainEntity> {
+    const entity = await this.findOne(id);
+    if (!entity) {
+      throw new EntityNotFoundError("InMemoryEntity", {
+        [ArchitectureLevel.INFRASTRUCTURE]: { "persistence-fake": { className: "InMemoryRepository" } },
+      });
+    }
+    return entity;
+  }
+
+  async findByIds(ids: string[]): Promise<DomainEntity[]> {
+    return this.toArray().filter((entity) => ids.includes(entity.id.toString()));
+  }
+
+  async delete(entity: DomainEntity): Promise<void> {
+    this.checkError();
+    this.store.delete(entity.id.toString());
+  }
+
+  async exists(id: string): Promise<boolean> {
+    this.checkError();
+    return this.store.has(id);
+  }
+
+  async count(options: FindManyOptions<DomainEntity>): Promise<number> {
+    this.checkError();
+    return _.filter(this.toArray(), options.filters).length;
+  }
+
+  clear(): void {
+    this.store.clear();
+    this.error = undefined;
+  }
+
+  setError(error: Error): void {
+    this.error = error;
+  }
+
+  protected checkError(): void {
+    if (this.error) {throw this.error;}
+  }
+
+  protected toArray(): DomainEntity[] {
+    return [...this.store.values()];
+  }
+}

package/src/core/infrastructure/persistence/in-memory/index.ts

@@ -0,0 +1,3 @@
+export * from "./fake.repository";
+export * from "./in-memory.query-builder";
+export * from "./in-memory.repository";

package/src/core/infrastructure/persistence/index.ts

@@ -0,0 +1,4 @@
+export * from "./errors";
+export * from "./in-memory";
+export * from "./read-side";
+export * from "./write-side";

package/src/core/infrastructure/persistence/read-side/in-memory.query-builder.ts

@@ -0,0 +1,4 @@
+import { QueryBuilder } from "../../../application";
+import { Stub } from "../../../../testing/stub";
+
+export abstract class InMemoryQueryBuilder<TSelf = unknown> extends Stub<TSelf> implements QueryBuilder {}

package/src/core/infrastructure/persistence/read-side/index.ts

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

package/src/core/infrastructure/persistence/read-side/knex/index.ts

@@ -0,0 +1,2 @@
+export * from "./knex.query-builder";
+export * from "./knex-types.definition";

package/src/core/infrastructure/persistence/read-side/knex/knex-types.definition.ts

@@ -0,0 +1,13 @@
+type CamelToSnakeCase<S extends string> = S extends `${infer T}${infer U}`
+  ? `${T extends Capitalize<T> ? "_" : ""}${Lowercase<T>}${CamelToSnakeCase<U>}`
+  : S;
+
+export type knexInfer<T> = {
+  [K in keyof T as CamelToSnakeCase<Extract<K, string>>]: T[K] extends CallableFunction ? never : T[K];
+};
+
+export type knexTableAlias<Table, Alias extends string> = {
+  [K in keyof Table as `${Alias}.${string & CamelToSnakeCase<Extract<K, string>>}`]: Table[K] extends CallableFunction
+    ? never
+    : Table[K];
+};

package/src/core/infrastructure/persistence/read-side/knex/knex.query-builder.ts

@@ -0,0 +1,70 @@
+import { Knex } from "knex";
+
+import { QueryBuilder } from "../../../../application";
+import { ArchitectureLevel } from "../../../../types";
+import { EntityNotFoundError } from "../../../../errors";
+import { knexTableAlias } from "./knex-types.definition";
+
+export abstract class KnexQueryBuilder implements QueryBuilder {
+  constructor(private readonly knex: Knex) {}
+
+  private createDefaultQueryBuilder<TModel extends object, TResult = Partial<TModel>>(
+    tableName: string,
+  ): Knex.QueryBuilder<TModel, TResult> {
+    return this.knex.from<TModel, TResult>(tableName);
+  }
+
+  protected exists(tableName: string, id: string): Promise<boolean> {
+    return this.createDefaultQueryBuilder(tableName)
+      .where("id", id)
+      .first()
+      .then((result) => !!result);
+  }
+
+  protected findOne<TModel extends object, TResult = Partial<TModel>>(tableName: string, id: string): Promise<TResult | null> {
+    return this.createDefaultQueryBuilder<TModel, TResult>(tableName)
+      .select("*")
+      .where("id", id)
+      .first()
+      .then((result) => (result as TResult) || null);
+  }
+
+  protected findOneOrFail<TModel extends object, TResult = Partial<TModel>>(tableName: string, id: string): Promise<TResult> {
+    return this.createDefaultQueryBuilder<TModel, TResult>(tableName)
+      .select("*")
+      .where("id", id)
+      .first()
+      .then((result) => {
+        if (!result) {
+          throw new EntityNotFoundError(
+            tableName,
+            { [ArchitectureLevel.INFRASTRUCTURE]: { "persistence-sql": { className: KnexQueryBuilder.name } } },
+            { id },
+          );
+        }
+
+        return result as TResult;
+      });
+  }
+
+  protected findByIds<TModel extends object, TResult = Partial<TModel>>(tableName: string, ids: string[]): Promise<TResult[]> {
+    return this.createDefaultQueryBuilder<TModel, TResult>(tableName)
+      .whereIn("id", ids)
+      .then((result) => result as TResult[]);
+  }
+
+  protected count(tableName: string, options: Record<string, unknown>): Promise<number> {
+    return this.createDefaultQueryBuilder(tableName)
+      .count<Array<{ count: number }>>("*", { as: "count" })
+      .where(options)
+      .then(([{ count }]) => count);
+  }
+
+  get queryBuilder() {
+    return this.knex.queryBuilder();
+  }
+
+  dataSource<T, Alias extends string>(tableName: Alias) {
+    return this.knex<knexTableAlias<T, Alias>>(tableName);
+  }
+}