@cullet/erp-core 1.0.0

package/src/core/result/outcome.ts

@@ -0,0 +1,158 @@
+// core/domain/outcome.ts
+
+import { InvariantViolationException } from "../exceptions/invariant-violation-exception";
+
+/**
+ * Outcome — Business decision abstraction.
+ *
+ * Represents the semantic result of a domain decision, policy evaluation,
+ * or business rule. NOT for technical success/failure — use Result for that.
+ *
+ * Mental model:
+ *   "What was the business decision?"
+ *   NOT "Did the operation succeed?"
+ *
+ * The status axis represents valid business outcomes (APPROVED, REJECTED,
+ * ALLOW, DENY, NO_OP, etc.), never technical Ok/Err.
+ *
+ * @typeParam S - Union of valid status literals for this outcome
+ * @typeParam D - Shape of the decision data carried by this outcome
+ */
+export class Outcome<S extends string, D = undefined> {
+  readonly status: S;
+  readonly data: D;
+  readonly reason: string | undefined;
+  readonly metadata: Readonly<Record<string, unknown>>;
+
+  private constructor(
+    status: S,
+    data: D,
+    reason: string | undefined,
+    metadata: Readonly<Record<string, unknown>>,
+  ) {
+    this.status = status;
+    this.data = data;
+    this.reason = reason;
+    this.metadata = metadata;
+    Object.freeze(this);
+  }
+
+  // ─── Generic factory ────────────────────────────────────────────────
+
+  static of<S extends string, D = undefined>(
+    status: S,
+    data: D,
+    reason?: string,
+    metadata?: Record<string, unknown>,
+  ): Outcome<S, D> {
+    return new Outcome(status, data, reason, Object.freeze({ ...metadata }));
+  }
+
+  // ─── Convenience factories for common business statuses ─────────────
+
+  static approved<D = undefined>(
+    data: D,
+    reason?: string,
+  ): Outcome<"APPROVED", D> {
+    return new Outcome("APPROVED", data, reason, Object.freeze({}));
+  }
+
+  static rejected<D = undefined>(
+    data: D,
+    reason: string,
+  ): Outcome<"REJECTED", D> {
+    return new Outcome("REJECTED", data, reason, Object.freeze({}));
+  }
+
+  static noOp<D = undefined>(data: D, reason?: string): Outcome<"NO_OP", D> {
+    return new Outcome("NO_OP", data, reason, Object.freeze({}));
+  }
+
+  static deferred<D = undefined>(
+    data: D,
+    reason: string,
+  ): Outcome<"DEFERRED", D> {
+    return new Outcome("DEFERRED", data, reason, Object.freeze({}));
+  }
+
+  static requiresReview<D = undefined>(
+    data: D,
+    reason: string,
+  ): Outcome<"REQUIRES_REVIEW", D> {
+    return new Outcome("REQUIRES_REVIEW", data, reason, Object.freeze({}));
+  }
+
+  // ─── Type narrowing ────────────────────────────────────────────────
+
+  /**
+   * Narrows this Outcome to a specific status.
+   *
+   * @example
+   * if (outcome.is('DENY')) {
+   *   outcome.data.violations // TS knows status is 'DENY'
+   * }
+   */
+  is<T extends S>(status: T): this is Outcome<T, D> {
+    return (this.status as string) === status;
+  }
+
+  // ─── Exhaustive match ──────────────────────────────────────────────
+
+  /**
+   * Exhaustive pattern match over all possible statuses.
+   * TypeScript enforces that every status has a handler.
+   *
+   * @example
+   * outcome.match({
+   *   ALLOW: (o) => handleAllow(o.data),
+   *   DENY:  (o) => handleDeny(o.data.violations),
+   * })
+   */
+  match<THandlers extends { [K in S]: (outcome: Outcome<K, D>) => unknown }>(
+    handlers: THandlers,
+  ): ReturnType<THandlers[S]> {
+    const handler = (
+      handlers as Partial<Record<string, (o: unknown) => unknown>>
+    )[this.status];
+
+    if (typeof handler !== "function") {
+      const availableStatuses = Object.keys(handlers);
+      throw new InvariantViolationException(
+        `Outcome.match is missing a handler for runtime status "${this.status}". Available handlers: ${availableStatuses.join(", ") || "(none)"}`,
+      );
+    }
+
+    return handler(this) as ReturnType<THandlers[S]>;
+  }
+
+  // ─── Derived copies ────────────────────────────────────────────────
+
+  withMetadata(extra: Record<string, unknown>): Outcome<S, D> {
+    return new Outcome(
+      this.status,
+      this.data,
+      this.reason,
+      Object.freeze({ ...this.metadata, ...extra }),
+    );
+  }
+
+  withReason(reason: string): Outcome<S, D> {
+    return new Outcome(this.status, this.data, reason, this.metadata);
+  }
+
+  // ─── Debug ─────────────────────────────────────────────────────────
+
+  toString(): string {
+    const parts: string[] = [this.status];
+    if (this.reason) parts.push(`reason="${this.reason}"`);
+    return `Outcome(${parts.join(", ")})`;
+  }
+}
+
+/** Common business outcome statuses. Extend per domain as needed. */
+export type CommonOutcomeStatus =
+  | "APPROVED"
+  | "REJECTED"
+  | "NO_OP"
+  | "DEFERRED"
+  | "REQUIRES_REVIEW";

package/src/core/result/result.ts

@@ -0,0 +1,153 @@
+/**
+ * Represents the outcome of an operation that may succeed or fail.
+ * Useful for avoiding excessive exceptions and making error flows explicit.
+ */
+export abstract class Result<T, E> {
+  protected constructor() {
+    // prevent direct instantiation
+  }
+
+  /**
+   * Creates a success result containing a value.
+   */
+  static ok<T>(value: T): Result<T, never> {
+    return new Ok(value);
+  }
+
+  /**
+   * Creates an error result containing an error object.
+   */
+  static err<E>(error: E): Result<never, E> {
+    return new Err(error);
+  }
+
+  /**
+   * Returns true when this is a success result.
+   */
+  abstract isOk(): this is Ok<T>;
+
+  /**
+   * Returns true when this is an error result.
+   */
+  abstract isErr(): this is Err<E>;
+
+  /**
+   * Runs a handler based on the result state (similar to pattern matching).
+   */
+  abstract match<R>(handlers: { ok: (value: T) => R; err: (error: E) => R }): R;
+
+  /**
+   * Returns the value when this is success, or null when this is an error.
+   */
+  getOrNull(): T | null {
+    return this.match({
+      ok: (value) => value,
+      err: () => null,
+    });
+  }
+
+  /**
+   * Returns the error when this is a failure, or null when this is a success.
+   */
+  errorOrNull(): E | null {
+    return this.match({
+      ok: () => null,
+      err: (error) => error,
+    });
+  }
+
+  /**
+   * Returns the value when this is a success, or throws the error when this is a failure.
+   */
+  getOrThrow(): T {
+    return this.match({
+      ok: (value) => value,
+      err: (error) => {
+        throw error instanceof Error ? error : new Error(String(error));
+      },
+    });
+  }
+
+  /**
+   * Transforms the success value using the provided function. Keeps the error when this is a failure.
+   */
+  map<R>(transform: (value: T) => R): Result<R, E> {
+    return this.match<Result<R, E>>({
+      ok: (value) => Result.ok(transform(value)),
+      // TS does not "see" variance here; the cast is intentional and safe:
+      // Err carries no T, so it can be widened to Result<R, E> safely.
+      err: (error) => Result.err(error) as unknown as Result<R, E>,
+    });
+  }
+
+  /**
+   * Transforms the error using the provided function. Keeps the value when this is a success.
+   */
+  mapError<F>(transform: (error: E) => F): Result<T, F> {
+    return this.match<Result<T, F>>({
+      // Ok carries no E, so it can be widened to Result<T, F>.
+      ok: (value) => Result.ok(value) as unknown as Result<T, F>,
+      err: (error) => Result.err(transform(error)),
+    });
+  }
+
+  /**
+   * Chains another operation that returns a Result when this result is a success.
+   */
+  flatMap<R>(transform: (value: T) => Result<R, E>): Result<R, E> {
+    return this.match<Result<R, E>>({
+      ok: (value) => transform(value),
+      err: (error) => Result.err(error) as unknown as Result<R, E>,
+    });
+  }
+}
+
+/**
+ * Success variant of Result.
+ */
+export class Ok<T> extends Result<T, never> {
+  public readonly value: T;
+
+  constructor(value: T) {
+    super();
+    this.value = value;
+    Object.freeze(this);
+  }
+
+  isOk(): this is Ok<T> {
+    return true;
+  }
+
+  isErr(): this is Err<never> {
+    return false;
+  }
+
+  match<R>(handlers: { ok: (value: T) => R; err: (error: never) => R }): R {
+    return handlers.ok(this.value);
+  }
+}
+
+/**
+ * Error variant of Result.
+ */
+export class Err<E> extends Result<never, E> {
+  public readonly error: E;
+
+  constructor(error: E) {
+    super();
+    this.error = error;
+    Object.freeze(this);
+  }
+
+  isOk(): this is Ok<never> {
+    return false;
+  }
+
+  isErr(): this is Err<E> {
+    return true;
+  }
+
+  match<R>(handlers: { ok: (value: never) => R; err: (error: E) => R }): R {
+    return handlers.err(this.error);
+  }
+}

package/src/core/shared/aggregate-version.ts

@@ -0,0 +1,11 @@
+import { InvariantViolationException } from "../exceptions/invariant-violation-exception";
+
+function assertValidAggregateVersion(aggregateVersion: number): void {
+  if (!Number.isInteger(aggregateVersion) || aggregateVersion < 0) {
+    throw new InvariantViolationException(
+      `aggregateVersion must be a non-negative integer. Received: ${aggregateVersion}`,
+    );
+  }
+}
+
+export { assertValidAggregateVersion };

package/src/core/shared/hashing.ts

@@ -0,0 +1,38 @@
+import { createHash } from "node:crypto";
+
+function sha256Hex(value: string): string {
+  return createHash("sha256").update(value, "utf8").digest("hex");
+}
+
+function sortKeysDeep(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map((item) => sortKeysDeep(item));
+  }
+
+  if (value instanceof Date) {
+    return value;
+  }
+
+  if (value && typeof value === "object") {
+    const record = value as Record<string, unknown>;
+    const ordered = Object.create(null) as Record<string, unknown>;
+
+    for (const key of Object.keys(record).sort()) {
+      ordered[key] = sortKeysDeep(record[key]);
+    }
+
+    return ordered;
+  }
+
+  return value;
+}
+
+function stableStringify(value: unknown): string {
+  return JSON.stringify(sortKeysDeep(value));
+}
+
+function payloadHash(value: unknown): string {
+  return sha256Hex(stableStringify(value));
+}
+
+export { payloadHash, sha256Hex, stableStringify };

package/src/core/shared/immutable.ts

@@ -0,0 +1,46 @@
+type PrimitiveValue =
+  | bigint
+  | boolean
+  | null
+  | number
+  | string
+  | symbol
+  | undefined;
+
+type DeepReadonly<T> = T extends PrimitiveValue | Date
+  ? T
+  : T extends readonly (infer TItem)[]
+    ? readonly DeepReadonly<TItem>[]
+    : { readonly [TKey in keyof T]: DeepReadonly<T[TKey]> };
+
+function deepFreeze<T>(value: T): T {
+  if (typeof value !== "object" || value === null || value instanceof Date) {
+    return value;
+  }
+
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      deepFreeze(item);
+    }
+
+    return Object.freeze(value);
+  }
+
+  const objectValue = value as Record<PropertyKey, object | PrimitiveValue>;
+
+  for (const propertyKey of Reflect.ownKeys(objectValue)) {
+    deepFreeze(objectValue[propertyKey]);
+  }
+
+  return Object.freeze(value);
+}
+
+function makeImmutable<T>(value: T): DeepReadonly<T> {
+  if (typeof value !== "object" || value === null) {
+    return value as DeepReadonly<T>;
+  }
+
+  return deepFreeze(structuredClone(value)) as DeepReadonly<T>;
+}
+
+export { deepFreeze, makeImmutable, type DeepReadonly };

package/src/core/shared/temporal-guards.ts

@@ -0,0 +1,22 @@
+import { InvariantViolationException } from "../exceptions/invariant-violation-exception";
+
+function isValidDate(value: unknown): value is Date {
+  return value instanceof Date && !Number.isNaN(value.getTime());
+}
+
+function cloneDate(date: Date): Date {
+  return new Date(date.getTime());
+}
+
+function assertValidDate(
+  fieldName: string,
+  value: unknown,
+): asserts value is Date {
+  if (!isValidDate(value)) {
+    throw new InvariantViolationException(
+      `${fieldName} must be a valid Date instance`,
+    );
+  }
+}
+
+export { assertValidDate, cloneDate, isValidDate };

package/src/core/versioning/domain-event-contracts.ts

@@ -0,0 +1,73 @@
+import { UseCase } from "../application/use-case";
+import { Entity } from "../domain/entity";
+import { ValueObject } from "../domain/value-object";
+import { assertValidAggregateVersion } from "../shared/aggregate-version";
+import { type ContractVersion } from "./version";
+
+interface DomainEventContractSelection {
+  readonly entity?: boolean;
+  readonly valueObject?: boolean;
+  readonly useCase?: boolean;
+}
+
+interface DomainEventContractVersions {
+  readonly entity_contract?: ContractVersion;
+  readonly value_object_contract?: ContractVersion;
+  readonly use_case_contract?: ContractVersion;
+}
+
+interface CreateDomainEventEnvelopeInput<TPayload> {
+  readonly aggregateVersion: number;
+  readonly payload: TPayload;
+  readonly contracts: DomainEventContractSelection;
+}
+
+interface DomainEventEnvelope<TPayload> extends DomainEventContractVersions {
+  readonly aggregate_version: number;
+  readonly payload: TPayload;
+}
+
+function buildDomainEventContractVersions(
+  selection: DomainEventContractSelection,
+): DomainEventContractVersions {
+  const contractVersions: {
+    entity_contract?: ContractVersion;
+    value_object_contract?: ContractVersion;
+    use_case_contract?: ContractVersion;
+  } = {};
+
+  if (selection.entity) {
+    contractVersions.entity_contract = Entity.CONTRACT_VERSION;
+  }
+
+  if (selection.valueObject) {
+    contractVersions.value_object_contract = ValueObject.CONTRACT_VERSION;
+  }
+
+  if (selection.useCase) {
+    contractVersions.use_case_contract = UseCase.CONTRACT_VERSION;
+  }
+
+  return Object.freeze(contractVersions);
+}
+
+function createDomainEventEnvelope<TPayload>(
+  input: CreateDomainEventEnvelopeInput<TPayload>,
+): DomainEventEnvelope<TPayload> {
+  assertValidAggregateVersion(input.aggregateVersion);
+
+  return Object.freeze({
+    aggregate_version: input.aggregateVersion,
+    payload: input.payload,
+    ...buildDomainEventContractVersions(input.contracts),
+  });
+}
+
+export {
+  buildDomainEventContractVersions,
+  createDomainEventEnvelope,
+  type CreateDomainEventEnvelopeInput,
+  type DomainEventContractSelection,
+  type DomainEventContractVersions,
+  type DomainEventEnvelope,
+};

package/src/core/versioning/version.ts

@@ -0,0 +1,34 @@
+type ContractVersion = `${number}.${number}`;
+
+type VersionedTarget = {
+  readonly prototype: object;
+};
+
+const CONTRACT_VERSION_PROPERTY = "CONTRACT_VERSION" as const;
+const CONTRACT_VERSION_PATTERN = /^\d+\.\d+$/;
+
+function version<const TVersion extends ContractVersion>(
+  contractVersion: TVersion,
+) {
+  if (!CONTRACT_VERSION_PATTERN.test(contractVersion)) {
+    throw new TypeError(
+      `Invalid contract version "${contractVersion}". Expected MAJOR.MINOR.`,
+    );
+  }
+
+  return (target: VersionedTarget): void => {
+    Object.defineProperty(target, CONTRACT_VERSION_PROPERTY, {
+      value: contractVersion,
+      writable: false,
+      configurable: false,
+      enumerable: false,
+    });
+  };
+}
+
+export {
+  CONTRACT_VERSION_PROPERTY,
+  type ContractVersion,
+  version,
+  type VersionedTarget,
+};

package/src/errors/index.ts

@@ -0,0 +1 @@
+export * from "../core/errors/index.js";

package/src/examples/rulesets/entity/order-creation-rules-v1.ts

@@ -0,0 +1,31 @@
+import { DomainException } from "../../../core/domain/rulesets/entity-ruleset.contracts";
+import { type OrderCreationData, type OrderCreationRuleset } from "./order";
+
+class OrderCreationValidationError extends DomainException {}
+
+class OrderCreationRulesV1 implements OrderCreationRuleset {
+  readonly id = "order-creation@1.0" as const;
+  readonly description = "Order creation rules — version 1.0";
+
+  validate(data: OrderCreationData): void {
+    if (!data.customerId) {
+      throw new OrderCreationValidationError("customerId is required.");
+    }
+
+    if (!data.items || data.items.length === 0) {
+      throw new OrderCreationValidationError(
+        "The order must contain at least one item.",
+      );
+    }
+
+    for (const item of data.items) {
+      if (item.quantity <= 0) {
+        throw new OrderCreationValidationError(
+          `Item "${item.sku}" quantity must be greater than zero. Received: ${item.quantity}.`,
+        );
+      }
+    }
+  }
+}
+
+export { OrderCreationRulesV1 };

package/src/examples/rulesets/entity/order-invariants-v1.ts

@@ -0,0 +1,48 @@
+import {
+  DomainException,
+  type RulesetId,
+} from "../../../core/domain/rulesets/entity-ruleset.contracts";
+import {
+  type Order,
+  type OrderInvariantRuleset,
+  type OrderItem,
+} from "./order";
+
+class OrderInvariantError extends DomainException {}
+
+class OrderInvariantsV1 implements OrderInvariantRuleset {
+  readonly id: RulesetId = "order-invariants@1.0";
+  readonly description: string = "Order invariants — version 1.0";
+
+  assertCanAddItem(order: Order, _item: OrderItem): void {
+    if (order.status !== "open") {
+      throw new OrderInvariantError(
+        `Cannot add an item to an order with status "${order.status}". The order must be open.`,
+      );
+    }
+  }
+
+  assertCanCancel(order: Order): void {
+    if (order.status === "delivered") {
+      throw new OrderInvariantError(
+        "Cannot cancel an order that has already been delivered.",
+      );
+    }
+  }
+
+  assertCanCheckout(order: Order): void {
+    if (order.items.length === 0) {
+      throw new OrderInvariantError("Cannot check out an order with no items.");
+    }
+  }
+
+  assertCanMarkAsDelivered(order: Order): void {
+    if (order.status !== "shipped") {
+      throw new OrderInvariantError(
+        `Cannot mark as delivered an order with status "${order.status}". The order must be shipped.`,
+      );
+    }
+  }
+}
+
+export { OrderInvariantsV1 };

package/src/examples/rulesets/entity/order-invariants-v2.ts

@@ -0,0 +1,28 @@
+import {
+  DomainException,
+  type RulesetId,
+} from "../../../core/domain/rulesets/entity-ruleset.contracts";
+import { type Order } from "./order";
+import { OrderInvariantsV1 } from "./order-invariants-v1";
+
+class OrderCancellationWindowError extends DomainException {}
+
+const FORTY_EIGHT_HOURS_MS = 48 * 60 * 60 * 1000;
+
+class OrderInvariantsV2 extends OrderInvariantsV1 {
+  override readonly id: RulesetId = "order-invariants@2.0";
+  override readonly description = "Order invariants — version 2.0";
+
+  override assertCanCancel(order: Order): void {
+    super.assertCanCancel(order);
+
+    const ageMs = Date.now() - order.createdAt.getTime();
+    if (ageMs > FORTY_EIGHT_HOURS_MS) {
+      throw new OrderCancellationWindowError(
+        "Cannot cancel an order created more than 48 hours ago.",
+      );
+    }
+  }
+}
+
+export { OrderInvariantsV2 };