@invariant--labs/foundation 1.1.2

package/jest.config.js

@@ -0,0 +1,49 @@
+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/package.json

@@ -0,0 +1,99 @@
+{
+  "name": "@invariant--labs/foundation",
+  "version": "1.1.2",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "license": "MIT",
+  "scripts": {
+    "clean": "rimraf ./dist",
+    "build": "nest build",
+    "lint": "eslint src/",
+    "lint:types": "tsc --project ./tsconfig.json --noEmit",
+    "test": "NODE_ENV=test jest",
+    "test:spec": "yarn test --selectProjects=foundation-spec",
+    "test:integration": "echo 'integration tests not implemented'",
+    "test:e2e": "echo 'e2e tests not implemented'",
+    "prerelease": "yarn clean && yarn lint && yarn lint:types && yarn test",
+    "release": "yarn prerelease && yarn build && npm publish --access public"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "@jest/globals": "^30.2.0",
+    "@nestjs/axios": "^4.0.1",
+    "@nestjs/platform-express": "^11.1.12",
+    "@nestjs/schematics": "^11.0.9",
+    "@nestjs/testing": "^11.1.12",
+    "@swc/core": "^1.11.29",
+    "@swc/jest": "^0.2.39",
+    "@types/base-64": "^1.0.2",
+    "@types/cls-hooked": "^4.3.9",
+    "@types/dotenv-safe": "^9.1.0",
+    "@types/express": "^5.0.6",
+    "@types/jest": "^30.0.0",
+    "@types/lodash": "^4.17.23",
+    "@types/luxon": "^3.7.1",
+    "@types/mime-types": "^3.0.1",
+    "@types/multer": "^2.0.0",
+    "@types/node": "^25.0.9",
+    "@types/passport": "^1.0.17",
+    "@types/supertest": "^6.0.3",
+    "@types/utf8": "^3.0.3",
+    "@types/uuid": "^11.0.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-no-only-tests": "^3.3.0",
+    "globals": "^17.0.0",
+    "jest": "^30.2.0",
+    "jest-util": "^30.2.0",
+    "rimraf": "^6.1.2",
+    "supertest": "^7.1.0",
+    "terser": "^5.46.0",
+    "tslib": "^2.8.1",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.53.1"
+  },
+  "dependencies": {
+    "@nestjs/cli": "^11.0.16",
+    "@nestjs/common": "^11.1.12",
+    "@nestjs/core": "^11.1.12",
+    "@nestjs/cqrs": "^11.0.3",
+    "@nestjs/graphql": "^13.2.3",
+    "@nestjs/microservices": "^11.1.12",
+    "@nestjs/passport": "^11.0.5",
+    "@nestjs/swagger": "^11.2.5",
+    "@sentry/nestjs": "^10.35.0",
+    "@vercel/style-guide": "^6.0.0",
+    "amqp-connection-manager": "^5.0.0",
+    "amqplib": "^0.10.9",
+    "axios": "^1.13.2",
+    "base-64": "^1.0.0",
+    "class-transformer": "^0.5.1",
+    "class-validator": "^0.14.3",
+    "cls-hooked": "^4.2.2",
+    "dayjs": "^1.11.19",
+    "dotenv": "^17.2.3",
+    "dotenv-safe": "^9.1.0",
+    "eslint": "^9.39.2",
+    "express-basic-auth": "^1.2.1",
+    "fast-xml-parser": "^5.3.3",
+    "graphql": "^16.12.0",
+    "knex": "^3.1.0",
+    "lodash": "^4.17.21",
+    "luxon": "^3.7.2",
+    "mime-types": "^3.0.2",
+    "passport": "^0.7.0",
+    "passport-headerapikey": "^1.2.2",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.2",
+    "shallow-equal-object": "^1.1.1",
+    "slugify": "^1.6.6",
+    "tiny-invariant": "^1.3.3",
+    "ts-custom-error": "^3.3.1",
+    "typeorm": "^0.3.28",
+    "utf8": "^3.0.0",
+    "uuid": "^13.0.0"
+  },
+  "volta": {
+    "node": "24.4.0",
+    "yarn": "4.7.0"
+  }
+}

package/src/core/application/index.ts

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

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

@@ -0,0 +1,3 @@
+export * from "./query-builder";
+export * from "./read-projection";
+export * from "./repository";

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

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,16 @@
+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/index.ts

@@ -0,0 +1,5 @@
+export * from "./aggregate-root";
+export * from "./entity";
+export * from "./identifier";
+export * from "./projection";
+export * from "./unique-entity-id";

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

@@ -0,0 +1,7 @@
+import { AggregateRoot } from "./aggregate-root";
+import { UniqueEntityId } from "./unique-entity-id";
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+export interface Projection<T extends Partial<AggregateRoot>> {
+  id: UniqueEntityId;
+}

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

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

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

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

package/src/core/domain/index.ts

@@ -0,0 +1,3 @@
+export * from "./entities";
+export * from "./events";
+export * from "./value-objects";

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

@@ -0,0 +1,2 @@
+export * from "./range";
+export * from "./value-object";

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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