@invariant--labs/foundation 1.1.2 → 1.1.5

package/jest.config.js

@@ -1,49 +0,0 @@
-const sharedConfig = {
-  roots: ["<rootDir>/src"],
-  moduleDirectories: ["node_modules"],
-  testPathIgnorePatterns: ["./node_modules/"],
-  testEnvironment: "node",
-  transform: {
-    "^.+\\.(t|j)sx?$": [
-      "@swc/jest",
-      {
-        jsc: {
-          parser: {
-            syntax: "typescript",
-            decorators: true,
-          },
-          transform: {
-            legacyDecorator: true,
-            decoratorMetadata: true,
-          },
-          target: "es2022",
-        },
-        module: {
-          type: "commonjs",
-        },
-      },
-    ],
-  },
-  transformIgnorePatterns: ["/node_modules/(?!(jose|uuid)/)"],
-  moduleNameMapper: {
-    "^src/(.*)$": "<rootDir>/src/$1",
-  },
-  maxWorkers: "25%",
-  moduleFileExtensions: ["ts", "js", "json"],
-  restoreMocks: true,
-  workerIdleMemoryLimit: "1024MB",
-};
-
-module.exports = {
-  displayName: "foundation",
-  coverageDirectory: "./coverage",
-  ...sharedConfig,
-  projects: [
-    {
-      displayName: "foundation-spec",
-      ...sharedConfig,
-      testMatch: ["**/*.spec.ts"],
-      workerIdleMemoryLimit: "512MB",
-    },
-  ],
-};

package/src/core/application/index.ts

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

package/src/core/application/persistence/query-builder.ts

@@ -1,2 +0,0 @@
-// eslint-disable-next-line @typescript-eslint/no-empty-object-type
-export interface QueryBuilder {}

package/src/core/application/persistence/read-projection.ts

@@ -1,2 +0,0 @@
-// eslint-disable-next-line @typescript-eslint/no-empty-object-type
-export interface ReadProjection {}

package/src/core/application/persistence/repository.ts

@@ -1,23 +0,0 @@
-import { AggregateRoot, Entity, EntityProps } from "../../domain";
-
-export abstract class Repository<DomainEntity extends Entity<EntityProps> | AggregateRoot<EntityProps>> {
-  abstract count(options: FindManyOptions<DomainEntity>): Promise<number>;
-  abstract exists(id: string): Promise<boolean>;
-  abstract findOne(id: string): Promise<DomainEntity | null>;
-  abstract findOneOrFail(id: string): Promise<DomainEntity>;
-  abstract findByIds(ids: string[]): Promise<DomainEntity[]>;
-  abstract save(entity: DomainEntity): Promise<DomainEntity>;
-  abstract saveAll(entities: DomainEntity[]): Promise<void>;
-}
-
-export interface FindOptions<T> {
-  filters?: { [P in keyof T]?: T[P] };
-  order?: { [P in keyof T]?: "ASC" | "DESC" };
-}
-
-export interface FindManyOptions<T> extends FindOptions<T> {
-  skip?: number;
-  limit?: number;
-}
-
-export type Predicate<T> = (item: T) => boolean;

package/src/core/domain/entities/aggregate-root.ts

@@ -1,34 +0,0 @@
-import { EventPublisher, AggregateRoot as NestAggregateRoot } from "@nestjs/cqrs";
-
-import { DomainEvent } from "../events/domain-event";
-import { EntityProps } from "./entity";
-import { UniqueEntityId } from "./unique-entity-id";
-
-export abstract class AggregateRoot<Props extends EntityProps = EntityProps> extends NestAggregateRoot<DomainEvent> {
-  public readonly _id: UniqueEntityId;
-
-  constructor(protected props: Props) {
-    super();
-    this._id = props.id ?? new UniqueEntityId();
-    this.props.id = this._id;
-  }
-
-  get id(): UniqueEntityId {
-    return this._id;
-  }
-
-  public equals(object?: AggregateRoot<Props>): boolean {
-    if (object == null) {return false;}
-    if (this === object) {return true;}
-    if (!(object instanceof AggregateRoot)) {return false;}
-    return this._id.equals(object._id);
-  }
-
-  public mergeContext(eventPublisher: EventPublisher) {
-    eventPublisher.mergeObjectContext(this);
-  }
-
-  public getProps() {
-    return { ...this.props, id: this._id };
-  }
-}

package/src/core/domain/entities/entity.spec.ts

@@ -1,43 +0,0 @@
-import { describe, it, expect } from "@jest/globals";
-
-import { Entity, EntityProps } from "./entity";
-import { UniqueEntityId } from "./unique-entity-id";
-
-interface TestProps extends EntityProps {
-  name: string;
-}
-
-class TestEntity extends Entity<TestProps> {}
-
-describe("Entity", () => {
-  it("should generate an id when none is provided", () => {
-    const entity = new TestEntity({ name: "test" });
-    expect(entity.id).toBeDefined();
-    expect(entity.id.toValue()).toBeTruthy();
-  });
-
-  it("should use the provided id", () => {
-    const id = new UniqueEntityId("custom-id");
-    const entity = new TestEntity({ name: "test", id });
-    expect(entity.id.toValue()).toBe("custom-id");
-  });
-
-  it("should be equal to another entity with the same id", () => {
-    const id = new UniqueEntityId("same");
-    const a = new TestEntity({ name: "a", id });
-    const b = new TestEntity({ name: "b", id });
-    expect(a.equals(b)).toBe(true);
-  });
-
-  it("should not be equal to an entity with a different id", () => {
-    const a = new TestEntity({ name: "a", id: new UniqueEntityId("1") });
-    const b = new TestEntity({ name: "b", id: new UniqueEntityId("2") });
-    expect(a.equals(b)).toBe(false);
-  });
-
-  it("should not be equal to null or undefined", () => {
-    const entity = new TestEntity({ name: "a" });
-    expect(entity.equals(undefined)).toBe(false);
-    expect(entity.equals(null as unknown as TestEntity)).toBe(false);
-  });
-});

package/src/core/domain/entities/entity.ts

@@ -1,29 +0,0 @@
-import { UniqueEntityId } from "./unique-entity-id";
-
-export type EntityProps = {
-  id?: UniqueEntityId;
-};
-
-export abstract class Entity<Props extends EntityProps = EntityProps> {
-  public readonly _id: UniqueEntityId;
-
-  constructor(protected props: Props) {
-    this._id = props.id ?? new UniqueEntityId();
-    this.props.id = this._id;
-  }
-
-  get id(): UniqueEntityId {
-    return this._id;
-  }
-
-  public equals(object?: Entity<Props>): boolean {
-    if (object == null) {return false;}
-    if (this === object) {return true;}
-    if (!(object instanceof Entity)) {return false;}
-    return this._id.equals(object._id);
-  }
-
-  public getProps() {
-    return { ...this.props, id: this._id };
-  }
-}

package/src/core/domain/entities/identifier.spec.ts

@@ -1,34 +0,0 @@
-import { describe, it, expect } from "@jest/globals";
-
-import { Identifier } from "./identifier";
-
-class TestId extends Identifier<string> {}
-
-describe("Identifier", () => {
-  it("should store and return its value", () => {
-    const id = new TestId("abc");
-    expect(id.toValue()).toBe("abc");
-  });
-
-  it("should convert to string", () => {
-    const id = new TestId("abc");
-    expect(id.toString()).toBe("abc");
-  });
-
-  it("should be equal to another with same value", () => {
-    const id1 = new TestId("abc");
-    const id2 = new TestId("abc");
-    expect(id1.equals(id2)).toBe(true);
-  });
-
-  it("should not be equal to another with different value", () => {
-    const id1 = new TestId("abc");
-    const id2 = new TestId("xyz");
-    expect(id1.equals(id2)).toBe(false);
-  });
-
-  it("should not be equal to undefined", () => {
-    const id = new TestId("abc");
-    expect(id.equals(undefined)).toBe(false);
-  });
-});

package/src/core/domain/entities/identifier.ts

@@ -1,16 +0,0 @@
-export class Identifier<T> {
-  constructor(private readonly value: T) {}
-
-  equals(id?: Identifier<T>): boolean {
-    if (!(id instanceof this.constructor)) {return false;}
-    return id.toValue() === this.value;
-  }
-
-  toString() {
-    return String(this.value);
-  }
-
-  toValue(): T {
-    return this.value;
-  }
-}

package/src/core/domain/entities/unique-entity-id.ts

@@ -1,9 +0,0 @@
-import { v4 as uuid } from "uuid";
-
-import { Identifier } from "./identifier";
-
-export class UniqueEntityId extends Identifier<string | number> {
-  constructor(id?: string | number) {
-    super(id ?? uuid());
-  }
-}

package/src/core/domain/events/domain-event.ts

@@ -1,7 +0,0 @@
-import { IEvent } from "@nestjs/cqrs";
-
-import { UniqueEntityId } from "../entities/unique-entity-id";
-
-export class DomainEvent implements IEvent {
-  constructor(public readonly id: UniqueEntityId = new UniqueEntityId()) {}
-}

package/src/core/domain/events/index.ts

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

package/src/core/domain/value-objects/range.ts

@@ -1,4 +0,0 @@
-export type Range<T> = {
-  start: T;
-  end: T;
-};

package/src/core/domain/value-objects/value-object.spec.ts

@@ -1,45 +0,0 @@
-import { describe, it, expect } from "@jest/globals";
-
-import { ValueObject } from "./value-object";
-
-interface MoneyProps {
-  amount: number;
-  currency: string;
-}
-
-class Money extends ValueObject<MoneyProps> {
-  validate() {
-    if (this.props.amount < 0) {throw new Error("negative");}
-  }
-}
-
-describe("ValueObject", () => {
-  it("should freeze props on construction", () => {
-    const money = new Money({ amount: 10, currency: "EUR" });
-    expect(() => {
-      money.getProps().amount = 99;
-    }).toThrow();
-  });
-
-  it("should be equal when props match", () => {
-    const a = new Money({ amount: 10, currency: "EUR" });
-    const b = new Money({ amount: 10, currency: "EUR" });
-    expect(a.equals(b)).toBe(true);
-  });
-
-  it("should not be equal when props differ", () => {
-    const a = new Money({ amount: 10, currency: "EUR" });
-    const b = new Money({ amount: 20, currency: "EUR" });
-    expect(a.equals(b)).toBe(false);
-  });
-
-  it("should not be equal to undefined", () => {
-    const money = new Money({ amount: 10, currency: "EUR" });
-    expect(money.equals(undefined)).toBe(false);
-  });
-
-  it("should expose props via getProps", () => {
-    const money = new Money({ amount: 5, currency: "USD" });
-    expect(money.getProps()).toEqual({ amount: 5, currency: "USD" });
-  });
-});

package/src/core/domain/value-objects/value-object.ts

@@ -1,17 +0,0 @@
-import { shallowEqual } from "shallow-equal-object";
-
-export abstract class ValueObject<Props extends object = object> {
-  constructor(protected props: Props) {
-    this.props = Object.freeze(props);
-  }
-
-  public equals(vo?: ValueObject<Props>): boolean {
-    return !!vo?.props && shallowEqual(this.props, vo.props);
-  }
-
-  getProps(): Props {
-    return this.props;
-  }
-
-  abstract validate(): void;
-}

package/src/core/errors/command-failure.error.spec.ts

@@ -1,30 +0,0 @@
-import { describe, it, expect } from "@jest/globals";
-
-import { ArchitectureLevel } from "../types";
-import { CommandFailureError } from "./command-failure.error";
-
-describe("CommandFailureError", () => {
-  it("should store message and layer with command className", () => {
-    const error = new CommandFailureError("failed", "CreateUserHandler");
-    expect(error.message).toBe("failed");
-    expect(error.layer()).toEqual({
-      [ArchitectureLevel.APPLICATION]: { command: { className: "CreateUserHandler" } },
-    });
-  });
-
-  it("should store details", () => {
-    const error = new CommandFailureError("fail", "X", { key: "val" });
-    expect(error.details()).toEqual({ key: "val" });
-  });
-
-  it("should preserve the cause", () => {
-    const cause = new Error("root");
-    const error = new CommandFailureError("fail", "X", {}, cause);
-    expect(error.cause).toBe(cause);
-  });
-
-  it("should be an instance of Error", () => {
-    const error = new CommandFailureError("fail", "X");
-    expect(error).toBeInstanceOf(Error);
-  });
-});

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

@@ -1,9 +0,0 @@
-import { ArchitectureLevel } from "../types";
-import { DetailedError } from "./detailed.error";
-
-export class CommandFailureError extends DetailedError {
-  constructor(message: string, className: string, details: Record<string, unknown> = {}, cause?: unknown) {
-    super(message, { [ArchitectureLevel.APPLICATION]: { command: { className } } }, cause);
-    this.setDetails(details);
-  }
-}

package/src/core/errors/command-filter.error.ts

@@ -1,3 +0,0 @@
-import { CommandFailureError } from "./command-failure.error";
-
-export class CommandFilterError extends CommandFailureError {}

package/src/core/errors/detailed.error.ts

@@ -1,25 +0,0 @@
-import { CustomError } from "ts-custom-error";
-
-import { ArchitectureLayer } from "../types";
-
-export abstract class DetailedError extends CustomError {
-  private detailsObject: Record<string, unknown> = {};
-  private readonly layerObject: ArchitectureLayer;
-
-  constructor(message: string, layer: ArchitectureLayer, cause?: unknown) {
-    super(message, { cause });
-    this.layerObject = layer;
-  }
-
-  layer(): ArchitectureLayer {
-    return this.layerObject;
-  }
-
-  details(): Record<string, unknown> {
-    return this.detailsObject;
-  }
-
-  protected setDetails(details: Record<string, unknown>): void {
-    this.detailsObject = details;
-  }
-}

package/src/core/errors/domain.error.spec.ts

@@ -1,27 +0,0 @@
-import { describe, it, expect } from "@jest/globals";
-
-import { ArchitectureLevel } from "../types";
-import { DomainError } from "./domain.error";
-
-describe("DomainError", () => {
-  it("should wrap trace under DOMAIN layer", () => {
-    const trace = { entity: { className: "Invoice" } };
-    const error = new DomainError("invalid", trace);
-    expect(error.layer()).toEqual({
-      [ArchitectureLevel.DOMAIN]: { entity: { className: "Invoice" } },
-    });
-  });
-
-  it("should store details", () => {
-    const trace = { entity: { className: "X" } };
-    const error = new DomainError("bad", trace, { field: "email" });
-    expect(error.details()).toEqual({ field: "email" });
-  });
-
-  it("should preserve the cause", () => {
-    const cause = new Error("original");
-    const trace = { entity: { className: "X" } };
-    const error = new DomainError("bad", trace, {}, cause);
-    expect(error.cause).toBe(cause);
-  });
-});

package/src/core/errors/domain.error.ts

@@ -1,9 +0,0 @@
-import { ArchitectureLayerTrace, ArchitectureLevel } from "../types";
-import { DetailedError } from "./detailed.error";
-
-export class DomainError extends DetailedError {
-  constructor(message: string, trace: ArchitectureLayerTrace, details: Record<string, unknown> = {}, cause?: unknown) {
-    super(message, { [ArchitectureLevel.DOMAIN]: { ...trace } }, cause);
-    this.setDetails(details);
-  }
-}

package/src/core/errors/entity-not-found.error.spec.ts

@@ -1,32 +0,0 @@
-import { describe, it, expect } from "@jest/globals";
-
-import { ArchitectureLevel } from "../types";
-import { EntityNotFoundError } from "./entity-not-found.error";
-
-describe("EntityNotFoundError", () => {
-  it("should include entity name in message", () => {
-    const layer = { [ArchitectureLevel.DOMAIN]: { entity: { className: "User" } } };
-    const error = new EntityNotFoundError("User", layer);
-    expect(error.message).toContain("User");
-    expect(error.message).toContain("cannot be retrieved");
-  });
-
-  it("should store the architecture layer", () => {
-    const layer = { [ArchitectureLevel.DOMAIN]: { entity: { className: "Order" } } };
-    const error = new EntityNotFoundError("Order", layer);
-    expect(error.layer()).toEqual(layer);
-  });
-
-  it("should store details when provided", () => {
-    const layer = { [ArchitectureLevel.DOMAIN]: { entity: { className: "X" } } };
-    const error = new EntityNotFoundError("X", layer, undefined, { id: "123" });
-    expect(error.details()).toEqual({ id: "123" });
-  });
-
-  it("should preserve the cause", () => {
-    const cause = new Error("db down");
-    const layer = { [ArchitectureLevel.DOMAIN]: { entity: { className: "X" } } };
-    const error = new EntityNotFoundError("X", layer, cause);
-    expect(error.cause).toBe(cause);
-  });
-});

package/src/core/errors/entity-not-found.error.ts

@@ -1,9 +0,0 @@
-import { ArchitectureLayer } from "../types";
-import { DetailedError } from "./detailed.error";
-
-export class EntityNotFoundError extends DetailedError {
-  constructor(entityName: string, layer: ArchitectureLayer, cause?: unknown, details: Record<string, unknown> = {}) {
-    super(`${entityName} cannot be retrieved`, layer, cause);
-    this.setDetails(details);
-  }
-}

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

@@ -1,27 +0,0 @@
-import { describe, it, expect } from "@jest/globals";
-
-import { ArchitectureLevel } from "../types";
-import { FakeImplementationError } from "./fake-implementation.error";
-
-describe("FakeImplementationError", () => {
-  it("should include class and method in message", () => {
-    const error = new FakeImplementationError("UserRepo", "findOne");
-    expect(error.message).toContain("UserRepo");
-    expect(error.message).toContain("fake");
-    expect(error.message).toContain("findOne");
-  });
-
-  it("should set layer to INFRASTRUCTURE", () => {
-    const error = new FakeImplementationError("UserRepo", "save");
-    expect(error.layer()).toEqual({
-      [ArchitectureLevel.INFRASTRUCTURE]: {
-        "persistence-fake": { className: "UserRepo" },
-      },
-    });
-  });
-
-  it("should be an instance of Error", () => {
-    const error = new FakeImplementationError("X", "y");
-    expect(error).toBeInstanceOf(Error);
-  });
-});

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

@@ -1,15 +0,0 @@
-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/query-failure.error.ts

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

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

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

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

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