@woltz/rich-domain 1.1.0 → 1.2.1

package/src/id.ts

@@ -2,42 +2,33 @@
 // Id Class - Smart Identity Management
 // ============================================================================
 
-function randomUUID(): string {
-  // If we are in the browser, use the browser's crypto API
-  // @ts-expect-error - window.crypto is not defined in the browser
-  if (typeof window !== "undefined" && window.crypto) {
-    // @ts-expect-error - window.crypto is not defined in the browser
-    return window.crypto.randomUUID();
-  }
-  // If we are in the server, use the crypto library
-  // eslint-disable-next-line @typescript-eslint/no-require-imports
-  const crypto = require("crypto");
-
-  return crypto.randomUUID();
-}
+import UUID from "./crypto";
 
 export class Id {
   private readonly _value: string;
   private readonly _isNew: boolean;
 
+
   /**
    * Create a new Id
    * @param value - Optional existing ID value. If not provided, generates a new UUID.
-   *
-   * @example
-   * // New entity (generates UUID)
-   * const newId = new Id();
-   * newuser.isNew() // true
-   *
-   * // Existing entity (uses provided ID)
-   * const existingId = new Id("550e8400-e29b-41d4-a716-446655440000");
-   * existinguser.isNew() // false
-   */
-  constructor(value?: string) {
+  *
+  * @example
+  * // New entity (generates UUID)
+  * const newId = new Id();
+  * newuser.isNew() // true
+  *
+  * // Existing entity (uses provided ID)
+  * const existingId = new Id("550e8400-e29b-41d4-a716-446655440000");
+  * existinguser.isNew() // false
+  */
+  constructor(value: string, isNew?: boolean);
+  constructor(value?: string);
+  constructor(value?: string, isNew?: boolean) {
     if (value !== undefined) {
       // ID was provided - this is an existing entity
       this._value = value;
-      this._isNew = false;
+      this._isNew = isNew ?? false;
     } else {
       // No ID provided - generate new one, this is a new entity
       this._value = this.generateUUID();
@@ -88,7 +79,7 @@ export class Id {
    */
   private generateUUID(): string {
     // Simple UUID v4 implementation
-    return randomUUID();
+    return UUID();
   }
 
   /**

package/src/index.ts

@@ -7,6 +7,7 @@ export { Id } from "./id";
 export { Entity, Aggregate } from "./entity";
 export { ValueObject } from "./value-object";
 export { Mapper } from "./mapper";
+export { EntitySchemaRegistry } from "./entity-schema-registry";
 
 export * from "./validation-error";
 
@@ -46,6 +47,11 @@ export {
   Search,
   FilterValueFor,
   PathValue,
+  OperatorsForType,
+  DateOperators,
+  NumberOperators,
+  StringOperators,
+  BooleanOperators,
+  ArrayOperators,
+  CriteriaOptions,
 } from "./types";
-
-// Internal (for advanced usage)

package/src/mapper.ts

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

package/src/paginated-result.ts

@@ -64,12 +64,6 @@ export class PaginatedResult<T> {
    */
   static fromArray<T>(items: T[], criteria: Criteria<T>): PaginatedResult<T> {
     let result = [...items];
-
-    // Apply filters
-    for (const filter of criteria.getFilters()) {
-      result = result.filter((item) => applyFilter(item, filter));
-    }
-
     let total = result.length;
 
     const search = criteria.getSearch();
@@ -78,10 +72,15 @@ export class PaginatedResult<T> {
         return search.fields.some((field) => {
           return String(getNestedValue(item, field))
             .toLowerCase()
-            .includes(search.value.toLowerCase());
+            .includes(search.value.trim().toLowerCase());
         });
       });
+      total = result.length;
+    }
 
+    // Apply filters
+    for (const filter of criteria.getFilters()) {
+      result = result.filter((item) => applyFilter(item, filter));
       total = result.length;
     }
 
@@ -101,7 +100,7 @@ export class PaginatedResult<T> {
 
     // Apply pagination
     const pagination = criteria.getPagination();
-    if (pagination) {
+    if (pagination && !criteria.hasSearch()) {
       result = result.slice(
         pagination.offset,
         pagination.offset + pagination.limit

package/src/repository/base-repository.ts

@@ -1,57 +1,26 @@
-// ============================================================================
-// Base Repository - Abstract implementation with common logic
-// ============================================================================
-
 import type { Aggregate } from "../entity";
 import type { Criteria } from "../criteria";
 import { PaginatedResult } from "../paginated-result";
 import { Mapper } from "../mapper";
 
-/**
- * Abstract base repository
- * Implements common logic, delegates persistence to subclasses
- *
- * @example
- * ```ts
- * class UserRepository extends BaseRepository<User, PrismaUser> {
- *   constructor(prisma: PrismaClient) {
- *     super(new UserMapper());
- *     this.prisma = prisma;
- *   }
- *
- *   protected async insertOne(data: PrismaUser): Promise<PrismaUser> {
- *     return this.prisma.user.create({ data });
- *   }
- *
- *   protected async updateOne(id: string, data: PrismaUser): Promise<PrismaUser> {
- *     return this.prisma.user.update({ where: { id }, data });
- *   }
- *
- *   // ... implement other abstract methods
- * }
- * ```
- */
-
 export abstract class ReadRepository<Agg extends Aggregate<any>> {
-  abstract find(criteria: Criteria<Agg>): Promise<PaginatedResult<Agg>>;
+  abstract find(criteria?: Criteria<Agg>): Promise<PaginatedResult<Agg>>;
   abstract findById(id: string): Promise<Agg | null>;
-  abstract count(criteria: Criteria<Agg>): Promise<number>;
+  abstract count(criteria?: Criteria<Agg>): Promise<number>;
   abstract exists(id: string): Promise<boolean>;
 }
 
 export abstract class WriteRepository<Agg extends Aggregate<any>> {
-  abstract create(entity: Agg): Promise<void>;
-  abstract update(entity: Agg): Promise<void>;
+  abstract save(entity: Agg): Promise<void>;
   abstract delete(entity: Agg): Promise<void>;
 }
 
 export abstract class WriteAndRead<Agg extends Aggregate<any>> {
-  abstract find(criteria: Criteria<Agg>): Promise<PaginatedResult<Agg>>;
+  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 save(entity: Agg): Promise<void>;
   abstract delete(entity: Agg): Promise<void>;
-  abstract count(criteria: Criteria<Agg>): Promise<number>;
+  abstract count(criteria?: Criteria<Agg>): Promise<number>;
   abstract exists(id: string): Promise<boolean>;
 }
 

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

@@ -7,31 +7,6 @@ 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;

package/src/types/change-tracker.ts

@@ -0,0 +1,221 @@
+import { Entity } from "../entity";
+import { ValueObject } from "../value-object";
+
+/**
+ * Base operation with common information.
+ */
+export interface BaseOperation {
+  /** Entity name in the domain (e.g., 'User', 'Post', 'Comment') */
+  entity: string;
+  /** Depth in the aggregate tree (0 = root, 1 = direct children, etc.) */
+  depth: number;
+}
+
+/**
+ * Create operation.
+ */
+export interface CreateOperation<T = any> extends BaseOperation {
+  type: "create";
+  /** Entity data to be created */
+  data: T;
+  /** Parent ID (for FK) */
+  parentId?: string;
+  /** Parent entity name */
+  parentEntity?: string;
+}
+
+/**
+ * Update operation.
+ */
+export interface UpdateOperation<T = any> extends BaseOperation {
+  type: "update";
+  /** Entity ID */
+  id: string;
+  /** Current entity instance */
+  data: T;
+  /** Only fields that have changed */
+  changedFields: Record<string, any>;
+}
+
+/**
+ * Delete operation.
+ */
+export interface DeleteOperation<T = any> extends BaseOperation {
+  type: "delete";
+  /** Entity ID to be deleted */
+  id: string;
+  /** Entity data (for reference) */
+  data: T;
+}
+
+/**
+ * Union of all possible operations.
+ */
+export type Operation<T = any> =
+  | CreateOperation<T>
+  | UpdateOperation<T>
+  | DeleteOperation<T>;
+
+/**
+ * Item for batch creation.
+ */
+export interface BatchCreateItem<T = any> {
+  /** Entity data */
+  data: T;
+  /** Parent ID (for FK) */
+  parentId?: string;
+}
+
+/**
+ * Item for batch update.
+ */
+export interface BatchUpdateItem {
+  /** Entity ID */
+  id: string;
+  /** Fields that have changed */
+  changedFields: Record<string, any>;
+}
+
+/**
+ * Grouped and ordered operations for batch execution.
+ */
+export interface BatchOperations {
+  /**
+   * Deletes grouped by entity, ordered by depth descending (leaf → root).
+   */
+  deletes: Array<{
+    entity: string;
+    depth: number;
+    ids: string[];
+  }>;
+
+  /**
+   * Creates grouped by entity, ordered by depth ascending (root → leaf).
+   */
+  creates: Array<{
+    entity: string;
+    depth: number;
+    items: BatchCreateItem[];
+  }>;
+
+  /**
+   * Updates grouped by entity.
+   */
+  updates: Array<{
+    entity: string;
+    items: BatchUpdateItem[];
+  }>;
+}
+
+/**
+ * Changes detected in a collection (1:N).
+ */
+export interface CollectionChanges<T = any> {
+  /** Created items */
+  created: T[];
+  /** Updated items with their changes */
+  updated: Array<{
+    entity: T;
+    changes: Record<string, { from: any; to: any }>;
+  }>;
+  /** Deleted items */
+  deleted: T[];
+}
+
+/**
+ * Possible states for a 1:1 relationship.
+ */
+export type EntityChangeState =
+  | "created"    // null → Entity
+  | "updated"    // Entity(id:1) → Entity(id:1) with changes
+  | "deleted"    // Entity → null
+  | "replaced"   // Entity(id:1) → Entity(id:2)
+  | "unchanged"; // No changes
+
+/**
+ * Change in a 1:1 entity relationship.
+ */
+export interface EntityChange<T = any> {
+  /** State of the change */
+  state: EntityChangeState;
+  /** Current entity (null if deleted) */
+  current: T | null;
+  /** Previous entity (null if created) */
+  previous: T | null;
+  /** Field changes (if state === 'updated') */
+  changes?: Record<string, { from: any; to: any }>;
+}
+
+/**
+ * Change in a primitive field.
+ */
+export interface FieldChange<T = any> {
+  from: T;
+  to: T;
+}
+
+/**
+ * Extracts the props type from an Entity or ValueObject.
+ */
+export type ExtractProps<T> = T extends Entity<infer P>
+  ? P
+  : T extends ValueObject<infer P>
+  ? P
+  : never;
+
+/**
+ * Keys of primitive properties (not Entity, ValueObject or Array).
+ */
+export type PrimitiveKeys<T> = {
+  [K in keyof T]: T[K] extends
+    | Entity<any>
+    | ValueObject<any>
+    | Array<any>
+    | undefined
+    ? never
+    : K;
+}[keyof T];
+
+/**
+ * Keys of collections (arrays).
+ */
+export type CollectionKeys<T> = {
+  [K in keyof T]: T[K] extends Array<any> ? K : never;
+}[keyof T];
+
+/**
+ * Keys of single entities (1:1).
+ */
+export type SingleEntityKeys<T> = {
+  [K in keyof T]: T[K] extends Entity<any> | ValueObject<any> | null | undefined
+    ? T[K] extends Array<any>
+      ? never
+      : K
+    : never;
+}[keyof T];
+
+/**
+ * Change history entry.
+ */
+export interface HistoryEntry {
+  path: string;
+  previousValue: any;
+  currentValue: any;
+  timestamp: number;
+}
+
+/**
+ * Metadata from a tracked entity/VO.
+ */
+export interface TrackedEntityMetadata {
+  /** Entity name */
+  entityName: string;
+  /** Depth in the tree */
+  depth: number;
+  /** Parent ID */
+  parentId?: string;
+  /** Parent entity name */
+  parentEntity?: string;
+  /** Path in the object (e.g., 'posts[0].comments[1]') */
+  path: string;
+}

package/src/types/criteria.ts

@@ -17,12 +17,65 @@ export const FILTER_OPERATORS = [
   "isNotNull",
 ] as const;
 
+export type FilterOperator = (typeof FILTER_OPERATORS)[number];
+
+export type StringOperators =
+  | "equals"
+  | "notEquals"
+  | "contains"
+  | "startsWith"
+  | "endsWith"
+  | "in"
+  | "notIn"
+  | "isNull"
+  | "isNotNull";
+
+export type NumberOperators =
+  | "equals"
+  | "notEquals"
+  | "greaterThan"
+  | "greaterThanOrEqual"
+  | "lessThan"
+  | "lessThanOrEqual"
+  | "in"
+  | "notIn"
+  | "between"
+  | "isNull"
+  | "isNotNull";
+
+export type DateOperators =
+  | "equals"
+  | "notEquals"
+  | "greaterThan"
+  | "greaterThanOrEqual"
+  | "lessThan"
+  | "lessThanOrEqual"
+  | "in"
+  | "notIn"
+  | "between"
+  | "isNull"
+  | "isNotNull";
+
+export type BooleanOperators = "equals" | "notEquals" | "isNull" | "isNotNull";
+
+export type ArrayOperators = "in" | "notIn" | "isNull" | "isNotNull";
+
+export type OperatorsForType<T> = T extends string
+  ? StringOperators
+  : T extends number
+  ? NumberOperators
+  : T extends Date
+  ? DateOperators
+  : T extends boolean
+  ? BooleanOperators
+  : T extends Array<any>
+  ? ArrayOperators
+  : FilterOperator;
+
 export type FilterValueFor<T> =
-  | T // equals, notEquals
-  | (T extends number | Date
-      ? [T, T] // between
-      : never)
-  | T[] // in, notIn
+  | T
+  | (T extends number | Date ? [T, T] : never)
+  | T[]
   | null;
 
 export type PathValue<
@@ -30,24 +83,34 @@ export type PathValue<
   P extends string
 > = P extends `${infer K}.${infer Rest}`
   ? K extends keyof T
-    ? PathValue<T[K], Rest>
+    ? T[K] extends Array<infer U>
+      ? PathValue<U, Rest>
+      : PathValue<T[K], Rest>
     : never
   : P extends keyof T
   ? T[P]
   : never;
 
-export type FilterOperator = (typeof FILTER_OPERATORS)[number];
-
 export interface Filter<TField = string, TValue = unknown> {
   field: TField;
-  operator: FilterOperator;
+  operator: unknown extends TValue ? FilterOperator : OperatorsForType<TValue>;
   value: TValue;
+  options?: CriteriaOptions;
 }
 
 export type TypedFilter<T> = {
-  [K in FieldPath<T>]: Filter<K, FilterValueFor<PathValue<T, K>>>;
+  [K in FieldPath<T>]: {
+    field: K;
+    operator: OperatorsForType<NonNullable<PathValue<T, K>>>;
+    value: FilterValueFor<NonNullable<PathValue<T, K>>>;
+    options?: CriteriaOptions;
+  };
 }[FieldPath<T>];
 
+export type CriteriaAdapter<Input, Output> = {
+  [K in FieldPath<Input>]?: FieldPath<Output>;
+};
+
 export type OrderDirection = "asc" | "desc";
 
 export interface Order {
@@ -55,6 +118,11 @@ export interface Order {
   direction: OrderDirection;
 }
 
+export type TypedOrder<T> = {
+  field: FieldPath<T>;
+  direction: OrderDirection;
+};
+
 export interface Pagination {
   page: number;
   limit: number;
@@ -75,10 +143,20 @@ export interface PaginationMeta {
   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];
+export interface CriteriaOptions {
+  quantifier?: "some" | "every" | "none";
+}
+
+type ExcludeBuiltInKeys<T> = Exclude<keyof T, keyof any[] | number | symbol>;
+
+export type FieldPath<T> = T extends Primitive
+  ? never
+  : {
+      [K in ExcludeBuiltInKeys<T> & string]: NonNullable<T[K]> extends Primitive
+        ? K
+        : NonNullable<T[K]> extends Array<infer U>
+        ? U extends Primitive
+          ? K
+          : K | `${K}.${FieldPath<U>}`
+        : `${K}.${FieldPath<NonNullable<T[K]>>}`;
+    }[ExcludeBuiltInKeys<T> & string];

package/src/types/history-tracker.ts

@@ -1,3 +1,4 @@
+import { TrackedEntityMetadata } from "./change-tracker";
 import { BaseProps } from "./domain";
 import { IsArray, NonUndefined, UnwrapArray } from "./utils";
 
@@ -7,6 +8,18 @@ export interface ChangeEvent<T> {
   path: string;
 }
 
+export interface TrackedItem {
+  entity: any;
+  metadata: TrackedEntityMetadata;
+  originalState: any;
+}
+
+export interface ArrayState {
+  cloned: any[];
+  original: any[];
+  metadata: TrackedEntityMetadata;
+}
+
 export interface ArrayChangeEvent<T> {
   toCreate: T[];
   toUpdate: T[];

package/src/types/utils.ts

@@ -14,16 +14,7 @@ export type DeepJsonResult<T> = {
     : 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;