@woltz/rich-domain 0.2.1

package/src/repository/unit-of-work.ts

@@ -0,0 +1,148 @@
+// ============================================================================
+// Unit of Work - Simple transaction management
+// ============================================================================
+
+import type { IUnitOfWork, TransactionContext } from "../types";
+
+/**
+ * Abstract Unit of Work
+ * Provides transaction management across multiple repositories
+ *
+ * @example
+ * ```ts
+ * // Using transaction helper (recommended)
+ * await uow.transaction(async (ctx) => {
+ *   const userRepo = uow.getRepository(UserRepository);
+ *   const orderRepo = uow.getRepository(OrderRepository);
+ *
+ *   await userRepo.save(user);
+ *   await orderRepo.save(order);
+ *
+ *   // Auto-commits on success, rolls back on error
+ * });
+ *
+ * // Manual control
+ * const ctx = await uow.begin();
+ * try {
+ *   await userRepo.save(user);
+ *   await orderRepo.save(order);
+ *   await ctx.commit();
+ * } catch (error) {
+ *   await ctx.rollback();
+ *   throw error;
+ * }
+ * ```
+ */
+export abstract class UnitOfWork implements IUnitOfWork {
+  protected currentContext: TransactionContext | null = null;
+  protected repositoryCache: Map<string, any> = new Map();
+
+  abstract begin(): Promise<TransactionContext>;
+
+  /**
+   * Execute work within a transaction
+   * Auto-commits on success, rolls back on error
+   */
+  async transaction<T>(
+    work: (ctx: TransactionContext) => Promise<T>
+  ): Promise<T> {
+    const ctx = await this.begin();
+
+    try {
+      const result = await work(ctx);
+      await ctx.commit();
+      return result;
+    } catch (error) {
+      if (ctx.isActive()) {
+        await ctx.rollback();
+      }
+      throw error;
+    } finally {
+      this.currentContext = null;
+      this.repositoryCache.clear();
+    }
+  }
+
+  /**
+   * Get repository instance (cached per transaction)
+   */
+  getRepository<TRepo>(
+    RepositoryClass: new (...args: any[]) => TRepo
+  ): TRepo {
+    const key = RepositoryClass.name;
+
+    if (this.repositoryCache.has(key)) {
+      return this.repositoryCache.get(key);
+    }
+
+    const repo = this.createRepository(RepositoryClass);
+    this.repositoryCache.set(key, repo);
+    return repo;
+  }
+
+  /**
+   * Create repository instance - implement in subclass
+   */
+  protected abstract createRepository<TRepo>(
+    RepositoryClass: new (...args: any[]) => TRepo
+  ): TRepo;
+}
+
+/**
+ * Base Transaction Context
+ */
+export abstract class BaseTransactionContext implements TransactionContext {
+  protected _isActive = true;
+
+  abstract commit(): Promise<void>;
+  abstract rollback(): Promise<void>;
+
+  isActive(): boolean {
+    return this._isActive;
+  }
+
+  protected markInactive(): void {
+    this._isActive = false;
+  }
+}
+
+/**
+ * In-Memory Unit of Work (for testing)
+ */
+export class InMemoryUnitOfWork extends UnitOfWork {
+  private committed = false;
+  private rolledBack = false;
+
+  async begin(): Promise<TransactionContext> {
+    this.currentContext = new InMemoryTransactionContext();
+    this.committed = false;
+    this.rolledBack = false;
+    return this.currentContext;
+  }
+
+  protected createRepository<TRepo>(
+    RepositoryClass: new (...args: any[]) => TRepo
+  ): TRepo {
+    // For in-memory, just create a new instance
+    // In real implementation, pass transaction client
+    return new RepositoryClass();
+  }
+
+  isCommitted(): boolean {
+    return this.committed;
+  }
+
+  isRolledBack(): boolean {
+    return this.rolledBack;
+  }
+}
+
+class InMemoryTransactionContext extends BaseTransactionContext {
+  async commit(): Promise<void> {
+    this.markInactive();
+  }
+
+  async rollback(): Promise<void> {
+    this.markInactive();
+  }
+}

package/src/types/criteria.ts

@@ -0,0 +1,79 @@
+import { Primitive } from "./utils";
+
+export const FilterOperator = [
+  "equals",
+  "notEquals",
+  "greaterThan",
+  "greaterThanOrEqual",
+  "lessThan",
+  "lessThanOrEqual",
+  "contains",
+  "startsWith",
+  "endsWith",
+  "in",
+  "notIn",
+  "between",
+  "isNull",
+  "isNotNull",
+] as const;
+
+export type FilterValueFor<T> =
+  | T // equals, notEquals
+  | (T extends number | Date
+      ? [T, T] // between
+      : never)
+  | T[] // in, notIn
+  | null;
+
+export type PathValue<
+  T,
+  P extends string
+> = P extends `${infer K}.${infer Rest}`
+  ? K extends keyof T
+    ? PathValue<T[K], Rest>
+    : never
+  : P extends keyof T
+  ? T[P]
+  : never;
+
+export type FilterOperator = (typeof FilterOperator)[number];
+
+export interface Filter<TField = string, TValue = unknown> {
+  field: TField;
+  operator: FilterOperator;
+  value: TValue;
+}
+
+export type TypedFilter<T> = {
+  [K in FieldPath<T>]: Filter<K, FilterValueFor<PathValue<T, K>>>;
+}[FieldPath<T>];
+
+export type OrderDirection = "asc" | "desc";
+
+export interface Order {
+  field: string;
+  direction: OrderDirection;
+}
+
+export interface Pagination {
+  page: number;
+  limit: number;
+  offset: number;
+}
+
+export interface PaginationMeta {
+  page: number;
+  limit: number;
+  total: number;
+  totalPages: number;
+  hasNext: boolean;
+  hasPrevious: boolean;
+}
+
+export type FieldPath<T> = {
+  [K in keyof T & string]: T[K] extends Primitive
+    ? K
+    : T[K] extends Array<infer U>
+    ? K | `${K}.${FieldPath<U>}`
+    : K | `${K}.${FieldPath<T[K]>}`;
+}[keyof T & string];

package/src/types/domain.ts

@@ -0,0 +1,37 @@
+import { StandardSchema, ValidationConfig } from "..";
+import { Id } from "../id";
+
+export type EntityId = string | number;
+
+export interface BaseProps {
+  id: Id;
+}
+
+interface DomainValidation<T> {
+  schema: StandardSchema<T>;
+  config?: ValidationConfig;
+}
+
+export type EntityValidation<T> = DomainValidation<T>;
+export type VOValidation<T> = DomainValidation<T>;
+
+
+export interface VOHooks<T, E> {
+  onBeforeUpdate?: (entity: E, snapshot: T) => boolean;
+  onCreate?: (entity: E) => void;
+  rules?: (entity: E) => void;
+  defaultValues?: Partial<T>;
+}
+
+// Specialized hooks for entities (with BaseProps)
+export interface EntityHooks<T extends BaseProps, E> {
+  onBeforeUpdate?: (entity: E, snapshot: T) => boolean;
+  onCreate?: (entity: E) => void;
+  rules?: (entity: E) => void;
+}
+
+export interface EntityConstructor<T extends BaseProps, E> {
+  new (props: T): E;
+  validation?: DomainValidation<T>;
+  hooks?: EntityHooks<T, E>;
+}

package/src/types/history-tracker.ts

@@ -0,0 +1,45 @@
+import { BaseProps } from "..";
+import { IsArray, NonUndefined, UnwrapArray } from "./utils";
+
+export interface ChangeEvent<T> {
+  previous: T | undefined;
+  current: T;
+  path: string;
+}
+
+export interface ArrayChangeEvent<T> {
+  toCreate: T[];
+  toUpdate: T[];
+  toDelete: T[];
+  path: string;
+}
+
+export type PropertySubscriber<T> = (event: ChangeEvent<T>) => void;
+export type ArraySubscriber<T> = (event: ArrayChangeEvent<T>) => void;
+
+export interface PropertySubscription<T> {
+  onChange: PropertySubscriber<T>;
+}
+
+export interface ArraySubscription<T> {
+  onChange: ArraySubscriber<T>;
+}
+
+export type SubscriptionConfig<T extends BaseProps> = {
+  [K in keyof T]?: IsArray<NonUndefined<T[K]>> extends true
+    ? ArraySubscription<UnwrapArray<NonUndefined<T[K]>>>
+    : PropertySubscription<NonUndefined<T[K]>>;
+};
+
+export interface ValidationConfig {
+  onCreate?: boolean;
+  onUpdate?: boolean;
+  throwOnError?: boolean;
+}
+
+export interface HistoryEntry {
+  path: string;
+  previousValue: any;
+  currentValue: any;
+  timestamp: number;
+}

package/src/types/index.ts

@@ -0,0 +1,7 @@
+export * from "./criteria";
+export * from "./domain";
+export * from "./history-tracker";
+export * from "./standard-schema";
+export * from "./utils";
+export * from "./repository";
+export * from "./unit-of-work";

package/src/types/repository.ts

@@ -0,0 +1,51 @@
+import { Criteria } from "../criteria";
+import { Aggregate } from "../entity";
+import { Id } from "../id";
+import { PaginatedResult } from "../paginated-result";
+
+export interface IRepository<TDomain extends Aggregate<any>> {
+  /**
+   * Find by ID
+   */
+  findById(id: Id): Promise<TDomain | null>;
+
+  /**
+   * Find using criteria (filtering, ordering, pagination)
+   */
+  find(criteria: Criteria<TDomain>): Promise<PaginatedResult<TDomain>>;
+
+  /**
+   * Find all (with optional criteria)
+   */
+  findAll(criteria?: Criteria<TDomain>): Promise<TDomain[]>;
+
+  /**
+   * Find one (first matching criteria)
+   */
+  findOne(criteria: Criteria<TDomain>): Promise<TDomain | null>;
+
+  /**
+   * Save (insert or update based on aggregate.isNew)
+   */
+  save(aggregate: TDomain): Promise<void>;
+
+  /**
+   * Delete aggregate
+   */
+  delete(aggregate: TDomain): Promise<void>;
+
+  /**
+   * Delete by ID
+   */
+  deleteById(id: Id): Promise<void>;
+
+  /**
+   * Check if exists
+   */
+  exists(id: Id): Promise<boolean>;
+
+  /**
+   * Count matching criteria
+   */
+  count(criteria?: Criteria<TDomain>): Promise<number>;
+}

package/src/types/standard-schema.ts

@@ -0,0 +1,19 @@
+export interface StandardSchemaIssue {
+  message: string;
+  path?: ReadonlyArray<unknown>;
+}
+
+export interface StandardSchemaResult<T> {
+  value?: T;
+  issues?: ReadonlyArray<StandardSchemaIssue>;
+}
+
+export interface StandardSchemaProps<T> {
+  validate: (
+    value: unknown
+  ) => StandardSchemaResult<T> | Promise<StandardSchemaResult<T>>;
+}
+
+export interface StandardSchema<T = unknown> {
+  "~standard": StandardSchemaProps<T>;
+}

package/src/types/unit-of-work.ts

@@ -0,0 +1,46 @@
+import { Aggregate } from "../entity";
+import { IRepository } from "./repository";
+
+/**
+ * Transaction context for Unit of Work
+ */
+export interface TransactionContext {
+  /**
+   * Commit all changes
+   */
+  commit(): Promise<void>;
+
+  /**
+   * Rollback all changes
+   */
+  rollback(): Promise<void>;
+
+  /**
+   * Check if transaction is active
+   */
+  isActive(): boolean;
+}
+
+/**
+ * Unit of Work interface
+ * Manages transactions across multiple repositories
+ */
+export interface IUnitOfWork {
+  /**
+   * Start a new transaction
+   */
+  begin(): Promise<TransactionContext>;
+
+  /**
+   * Execute work within a transaction
+   * Auto-commits on success, rolls back on error
+   */
+  transaction<T>(work: (ctx: TransactionContext) => Promise<T>): Promise<T>;
+
+  /**
+   * Get repository within transaction context
+   */
+  getRepository<TDomain extends Aggregate<any>>(
+    repository: new (...args: any[]) => IRepository<TDomain>
+  ): IRepository<TDomain>;
+}

package/src/types/utils.ts

@@ -0,0 +1,29 @@
+import { Id } from "../id";
+
+export type DeepJsonResult<T> = {
+  [K in keyof T]: T[K] extends Id
+    ? string
+    : T[K] extends { toJson(): infer U }
+    ? U
+    : T[K] extends Array<infer U>
+    ? U extends { toJson(): infer V }
+      ? V[]
+      : U extends Id
+      ? string[]
+      : U[]
+    : T[K];
+};
+
+export type DeepKeyOf<T, K extends keyof T = keyof T> = K extends string
+  ? T[K] extends Primitive
+    ? K
+    : T[K] extends object
+    ? `${K}` | `${K}.${DeepKeyOf<T[K]>}`
+    : never
+  : never;
+
+export type Primitive = string | number | boolean | Date | null | undefined;
+
+export type UnwrapArray<T> = T extends Array<infer U> ? U : never;
+export type IsArray<T> = T extends Array<any> ? true : false;
+export type NonUndefined<T> = T extends undefined ? never : T;

package/src/validation-error.ts

@@ -0,0 +1,97 @@
+// ============================================================================
+// Validation Error - Domain Validation Errors
+// ============================================================================
+
+export interface ValidationIssue {
+  path: string[];
+  message: string;
+}
+
+export class ValidationError extends Error {
+  public readonly issues: ValidationIssue[];
+  public readonly __isValidationError = true; // Brand for identification
+
+  constructor(issues: ValidationIssue[], message?: string) {
+    const errorMessage =
+      message || `Validation failed: ${issues.map(i => i.message).join(', ')}`;
+    super(errorMessage);
+    this.name = 'ValidationError';
+    this.issues = issues;
+
+    // Maintain proper stack trace
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, ValidationError);
+    }
+  }
+
+  /**
+   * Check if an error is a ValidationError (works across module boundaries)
+   */
+  static isValidationError(error: unknown): error is ValidationError {
+    if (error instanceof ValidationError) {
+      return true;
+    }
+    // Check by duck typing for cross-module compatibility
+    return (
+      error instanceof Error &&
+      error.name === 'ValidationError' &&
+      'issues' in error &&
+      Array.isArray((error as any).issues)
+    );
+  }
+
+  /**
+   * Get all error messages as a simple array
+   */
+  getMessages(): string[] {
+    return this.issues.map(i => i.message);
+  }
+
+  /**
+   * Get errors for a specific field path
+   */
+  getErrorsForPath(path: string): ValidationIssue[] {
+    return this.issues.filter(i => i.path.join('.') === path);
+  }
+
+  /**
+   * Check if a specific path has errors
+   */
+  hasErrorsForPath(path: string): boolean {
+    return this.getErrorsForPath(path).length > 0;
+  }
+
+  /**
+   * Convert to a plain object for serialization
+   */
+  toJSON(): { name: string; message: string; issues: ValidationIssue[] } {
+    return {
+      name: this.name,
+      message: this.message,
+      issues: this.issues,
+    };
+  }
+}
+
+/**
+ * Helper to create a single validation issue
+ */
+export function createValidationIssue(
+  path: string | string[],
+  message: string
+): ValidationIssue {
+  return {
+    path: Array.isArray(path) ? path : path.split('.'),
+    message,
+  };
+}
+
+/**
+ * Helper to throw a validation error with a single issue
+ */
+export function throwValidationError(
+  path: string | string[],
+  message: string
+): never {
+  throw new ValidationError([createValidationIssue(path, message)]);
+}