@woltz/rich-domain 0.2.1 → 1.0.0

package/src/id.ts

@@ -1,4 +1,4 @@
-import { randomUUID } from 'crypto';
+import { randomUUID } from "crypto";
 // ============================================================================
 // Id Class - Smart Identity Management
 // ============================================================================
@@ -14,11 +14,11 @@ export class Id {
    * @example
    * // New entity (generates UUID)
    * const newId = new Id();
-   * newId.isNew // true
+   * newuser.isNew() // true
    *
    * // Existing entity (uses provided ID)
    * const existingId = new Id("550e8400-e29b-41d4-a716-446655440000");
-   * existingId.isNew // false
+   * existinguser.isNew() // false
    */
   constructor(value?: string) {
     if (value !== undefined) {
@@ -42,7 +42,7 @@ export class Id {
   /**
    * Check if this ID represents a new entity
    */
-  get isNew(): boolean {
+  public isNew(): boolean {
     return this._isNew;
   }
 

package/src/index.ts

@@ -7,6 +7,7 @@ export { Id } from "./id";
 export { BaseEntity } from "./base-entity";
 export { Entity, Aggregate } from "./entity";
 export { ValueObject } from "./value-object";
+export { Mapper } from "./mapper";
 
 export * from "./validation-error";
 
@@ -15,14 +16,12 @@ export * from "./domain-event";
 
 export * from "./domain-event-bus";
 
-// Criteria & Repository
+// Criteria
 export * from "./criteria";
 export * from "./paginated-result";
 
 // Repository
 export * from "./repository";
-// Backward compatibility - re-export InMemoryRepository at top level
-export { InMemoryRepository } from "./repository";
 
 // Types
 export * from "./types";

package/src/mapper.ts

@@ -0,0 +1,3 @@
+export abstract class Mapper<Input, Output> {
+  public abstract build(input: Input, ...args: unknown[]): Output;
+}

package/src/paginated-result.ts

@@ -1,7 +1,3 @@
-// ============================================================================
-// PaginatedResult - Container for paginated data with deep serialization
-// ============================================================================
-
 import { Id } from "./id";
 import type { Criteria } from "./criteria";
 import type { Pagination, PaginationMeta, Filter } from "./types";
@@ -66,10 +62,7 @@ export class PaginatedResult<T> {
   /**
    * Applies criteria to an in-memory array (useful for testing)
    */
-  static fromArray<T>(
-    items: T[],
-    criteria: Criteria<T>
-  ): PaginatedResult<T> {
+  static fromArray<T>(items: T[], criteria: Criteria<T>): PaginatedResult<T> {
     let result = [...items];
 
     // Apply filters

package/src/repository/base-repository.ts

@@ -2,12 +2,10 @@
 // Base Repository - Abstract implementation with common logic
 // ============================================================================
 
-import type { Id } from "../id";
 import type { Aggregate } from "../entity";
 import type { Criteria } from "../criteria";
 import { PaginatedResult } from "../paginated-result";
-import type { IRepository } from "../types";
-import type { IMapper } from "./mapper";
+import { Mapper } from "../mapper";
 
 /**
  * Abstract base repository
@@ -33,120 +31,34 @@ import type { IMapper } from "./mapper";
  * }
  * ```
  */
-export abstract class BaseRepository<
-  TDomain extends Aggregate<any>,
-  TPersistence = any
-> implements IRepository<TDomain>
-{
-  constructor(protected readonly mapper: IMapper<TDomain, TPersistence>) {}
 
-  // ============================================================================
-  // Abstract methods - Must be implemented by subclasses
-  // ============================================================================
-
-  /**
-   * Insert new record in database
-   */
-  protected abstract insertOne(data: TPersistence): Promise<TPersistence>;
-
-  /**
-   * Update existing record in database
-   */
-  protected abstract updateOne(
-    id: string,
-    data: TPersistence
-  ): Promise<TPersistence>;
-
-  /**
-   * Delete record from database
-   */
-  protected abstract deleteOne(id: string): Promise<void>;
-
-  /**
-   * Find record by ID in database
-   */
-  protected abstract findOneById(id: string): Promise<TDomain | null>;
-
-  /**
-   * Find all records in database (no filtering)
-   */
-  protected abstract findMany(): Promise<TDomain[]>;
-
-  /**
-   * Apply criteria to query (filtering, ordering, pagination)
-   * Returns [data, total]
-   */
-  protected abstract applyCriteria(
-    criteria: Criteria<TDomain>
-  ): Promise<PaginatedResult<TDomain>>;
-
-  /**
-   * Count records matching criteria
-   */
-  protected abstract countByCriteria(
-    criteria?: Criteria<TDomain>
-  ): Promise<number>;
-
-  /**
-   * Check if record exists by ID
-   */
-  protected abstract existsById(id: string): Promise<boolean>;
-
-  // ============================================================================
-  // Public API - Implemented using abstract methods
-  // ============================================================================
-
-  async findById(id: Id): Promise<TDomain | null> {
-    const domain = await this.findOneById(id.value);
-    if (!domain) return null;
-    return domain;
-  }
-
-  async find(criteria: Criteria<TDomain>): Promise<PaginatedResult<TDomain>> {
-    return await this.applyCriteria(criteria);
-  }
-
-  async findAll(criteria?: Criteria<TDomain>): Promise<TDomain[]> {
-    if (criteria) {
-      const result = await this.find(criteria);
-      return result.data;
-    }
-
-    const domains = await this.findMany();
-    return domains;
-  }
-
-  async findOne(criteria: Criteria<TDomain>): Promise<TDomain | null> {
-    // Limit to 1 result
-    const limitedCriteria = criteria.clone().limit(1);
-    const result = await this.find(limitedCriteria);
-
-    return result.data.length > 0 ? result.data[0] : null;
-  }
-
-  async save(aggregate: TDomain): Promise<void> {
-    const persistence = this.mapper.toPersistence(aggregate);
-
-    if (aggregate.isNew) {
-      await this.insertOne(persistence);
-    } else {
-      await this.updateOne(aggregate.id.value, persistence);
-    }
-  }
-
-  async delete(aggregate: TDomain): Promise<void> {
-    await this.deleteOne(aggregate.id.value);
-  }
+export abstract class ReadRepository<Agg extends Aggregate<any>> {
+  abstract find(criteria: Criteria<Agg>): Promise<PaginatedResult<Agg>>;
+  abstract findById(id: string): Promise<Agg | null>;
+  abstract count(criteria: Criteria<Agg>): Promise<number>;
+  abstract exists(id: string): Promise<boolean>;
+}
 
-  async deleteById(id: Id): Promise<void> {
-    await this.deleteOne(id.value);
-  }
+export abstract class WriteRepository<Agg extends Aggregate<any>> {
+  abstract create(entity: Agg): Promise<void>;
+  abstract update(entity: Agg): Promise<void>;
+  abstract delete(entity: Agg): Promise<void>;
+}
 
-  async exists(id: Id): Promise<boolean> {
-    return this.existsById(id.value);
-  }
+export abstract class WriteAndRead<Agg extends Aggregate<any>> {
+  abstract find(criteria: Criteria<Agg>): Promise<PaginatedResult<Agg>>;
+  abstract findById(id: string): Promise<Agg | null>;
+  abstract create(entity: Agg): Promise<void>;
+  abstract update(entity: Agg): Promise<void>;
+  abstract delete(entity: Agg): Promise<void>;
+  abstract count(criteria: Criteria<Agg>): Promise<number>;
+  abstract exists(id: string): Promise<boolean>;
+}
 
-  async count(criteria?: Criteria<TDomain>): Promise<number> {
-    return this.countByCriteria(criteria);
-  }
+export abstract class Repository<
+  TDomain extends Aggregate<any>
+> extends WriteAndRead<TDomain> {
+  protected abstract readonly mapperToDomain: Mapper<unknown, TDomain>;
+  protected abstract readonly mapperToPersistence: Mapper<TDomain, unknown>;
+  abstract get model(): any;
 }

package/src/repository/in-memory-repository.ts

@@ -2,11 +2,11 @@
 // In-Memory Repository - Perfect for testing
 // ============================================================================
 
-import type { Id } from "../id";
 import type { Aggregate } from "../entity";
 import type { Criteria } from "../criteria";
 import { PaginatedResult } from "../paginated-result";
-import type { IRepository } from "../types";
+import { Repository } from "./base-repository";
+import { Mapper } from "../mapper";
 
 /**
  * In-memory repository implementation
@@ -23,13 +23,25 @@ import type { IRepository } from "../types";
  * );
  * ```
  */
-export class InMemoryRepository<TDomain extends Aggregate<any>>
-  implements IRepository<TDomain>
-{
+export class InMemoryRepository<
+  TDomain extends Aggregate<any>
+> extends Repository<TDomain> {
   protected items: Map<string, TDomain> = new Map();
 
-  async findById(id: Id): Promise<TDomain | null> {
-    return this.items.get(id.value) || null;
+  constructor(
+    protected readonly mapperToDomain: Mapper<unknown, TDomain>,
+    protected readonly mapperToPersistence: Mapper<TDomain, unknown>
+  ) {
+    super();
+  }
+
+  get model(): any {
+    // your database table name
+    return "inMemory";
+  }
+
+  async findById(id: string): Promise<TDomain | null> {
+    return this.items.get(id) || null;
   }
 
   async find(criteria: Criteria<TDomain>): Promise<PaginatedResult<TDomain>> {
@@ -51,13 +63,17 @@ export class InMemoryRepository<TDomain extends Aggregate<any>>
     return result.data.length > 0 ? result.data[0] : null;
   }
 
-  async save(aggregate: TDomain): Promise<void> {
+  async create(aggregate: TDomain): Promise<void> {
     this.items.set(aggregate.id.value, aggregate);
   }
 
-  async saveMany(aggregates: TDomain[]): Promise<void> {
+  async update(entity: TDomain): Promise<void> {
+    this.items.set(entity.id.value, entity);
+  }
+
+  async createMany(aggregates: TDomain[]): Promise<void> {
     for (const aggregate of aggregates) {
-      await this.save(aggregate);
+      await this.create(aggregate);
     }
   }
 
@@ -65,12 +81,8 @@ export class InMemoryRepository<TDomain extends Aggregate<any>>
     this.items.delete(aggregate.id.value);
   }
 
-  async deleteById(id: Id): Promise<void> {
-    this.items.delete(id.value);
-  }
-
-  async exists(id: Id): Promise<boolean> {
-    return this.items.has(id.value);
+  async exists(id: string): Promise<boolean> {
+    return this.items.has(id);
   }
 
   async count(criteria?: Criteria<TDomain>): Promise<number> {

package/src/repository/index.ts

@@ -3,11 +3,10 @@
 // ============================================================================
 
 // Mapper
-export { BaseMapper } from "./mapper";
-export type { IMapper } from "./mapper";
+export { Mapper } from "../mapper";
 
 // Base implementations
-export { BaseRepository } from "./base-repository";
+export * from "./base-repository";
 export { InMemoryRepository } from "./in-memory-repository";
 
 // Unit of Work
@@ -16,40 +15,3 @@ export {
   BaseTransactionContext,
   InMemoryUnitOfWork,
 } from "./unit-of-work";
-
-/**
- * QUICK START:
- *
- * 1. For Testing:
- * ```ts
- * import { InMemoryRepository } from 'rich-domain';
- *
- * const userRepo = new InMemoryRepository<User>();
- * await userRepo.save(user);
- * const found = await userRepo.findById(user.id);
- * ```
- *
- * 2. For Production (Prisma, TypeORM, etc):
- * - Extend BaseRepository
- * - Implement abstract methods
- * - Create a Mapper
- * - See examples/ folder for reference
- *
- * 3. With Criteria:
- * ```ts
- * const result = await userRepo.find(
- *   Criteria.create<User>()
- *     .whereEquals('status', 'active')
- *     .orderByDesc('createdAt')
- *     .paginate(1, 10)
- * );
- * ```
- *
- * 4. With Unit of Work:
- * ```ts
- * await uow.transaction(async (ctx) => {
- *   const userRepo = uow.getRepository(UserRepository);
- *   await userRepo.save(user);
- * });
- * ```
- */

package/src/types/criteria.ts

@@ -1,6 +1,6 @@
 import { Primitive } from "./utils";
 
-export const FilterOperator = [
+export const FILTER_OPERATORS = [
   "equals",
   "notEquals",
   "greaterThan",
@@ -36,7 +36,7 @@ export type PathValue<
   ? T[P]
   : never;
 
-export type FilterOperator = (typeof FilterOperator)[number];
+export type FilterOperator = (typeof FILTER_OPERATORS)[number];
 
 export interface Filter<TField = string, TValue = unknown> {
   field: TField;

package/src/types/index.ts

@@ -3,5 +3,4 @@ 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/unit-of-work.ts

@@ -1,5 +1,5 @@
 import { Aggregate } from "../entity";
-import { IRepository } from "./repository";
+import { Repository } from "../repository/base-repository";
 
 /**
  * Transaction context for Unit of Work
@@ -41,6 +41,6 @@ export interface IUnitOfWork {
    * Get repository within transaction context
    */
   getRepository<TDomain extends Aggregate<any>>(
-    repository: new (...args: any[]) => IRepository<TDomain>
-  ): IRepository<TDomain>;
+    repository: new (...args: any[]) => Repository<TDomain>
+  ): Repository<TDomain>;
 }

package/tests/entity-validation.test.ts

@@ -134,7 +134,7 @@ describe("Rich Domain with Standard Schema Validation", () => {
       expect(user.name).toBe("John Doe");
       expect(user.email).toBe("john@example.com");
       expect(user.age).toBe(25);
-      expect(user.isNew).toBe(true);
+      expect(user.isNew()).toBe(true);
     });
 
     it("should throw on invalid email", () => {

package/tests/history-tracker.spec.ts

@@ -4,28 +4,68 @@ import { Post, User, Address, Comment } from "./utils";
 describe("History Tracker Tests", () => {
   describe("Simple Property Changes", () => {
     it("should track simple property changes", (done) => {
-      const post = new Post({
+      const user = new User({
         id: new Id("1"),
-        title: "First Post",
-        content: "Hello World",
-        likes: 0,
+        name: "John Doe",
+        email: "john@example.com",
+        posts: [
+          new Post({
+            id: new Id("1"),
+            title: "First Post",
+            content: "Hello World",
+            likes: 0,
+          }),
+        ],
+        address: new Address({
+          street: "Main St",
+          city: "NYC",
+          zipCode: "10001",
+        }),
+        comments: [],
       });
 
-      let changeCount = 0;
+      user.changeEmail("new@example.com");
+      user.name = "New Name";
+      user.addPost(
+        new Post({
+          id: new Id("2"),
+          title: "Second Post",
+          content: "Hello World 2",
+          likes: 0,
+        })
+      );
 
-      post.subscribe({
-        title: {
-          onChange: ({ previous, current, path }) => {
-            changeCount++;
-            expect(previous).toBe("First Post");
-            expect(current).toBe("Updated Title");
-            expect(path).toBe("title");
-            done();
+      function dispatch(entity: User) {
+        entity.subscribe({
+          email: {
+            onChange: ({ previous, current, path }) => {
+              expect(previous).toBe("john@example.com");
+              expect(current).toBe("new@example.com");
+              expect(path).toBe("email");
+            },
           },
-        },
-      });
-
-      post.title = "Updated Title";
+          posts: {
+            onChange: ({ toCreate, toUpdate, toDelete }) => {
+              expect(toCreate).toHaveLength(1);
+              expect(toUpdate).toHaveLength(1);
+              expect(toDelete).toHaveLength(0);
+            },
+          },
+          name: {
+            onChange: ({ previous, current, path }) => {
+              expect(previous).toBe("John Doe");
+              expect(current).toBe("New Name");
+              expect(path).toBe("name");
+            },
+          },
+        });
+      }
+      user.posts[0].title = "Updated Title";
+      dispatch(user);
+
+      setTimeout(() => {
+        done();
+      }, 100);
     });
 
     it("should track multiple property changes", () => {