@woltz/rich-domain 1.2.4 → 1.3.0

package/src/entity-schema-registry.ts

@@ -1,6 +1,47 @@
 import { Entity } from "./entity";
 import { ValueObject } from "./value-object";
 import { Id } from "./id";
+import { ConfigurationError } from "./exceptions";
+import { levenshteinDistance } from "./utils/helpers";
+
+/**
+ * Type of collection relationship.
+ * - 'owned': Parent owns the children (1:N). Delete parent = delete children.
+ * - 'reference': Parent references existing entities (N:N). Delete parent = unlink only.
+ */
+export type CollectionType = "owned" | "reference";
+
+/**
+ * Configuration for a collection (1:N or N:N relationship).
+ */
+export interface CollectionConfig {
+  /**
+   * Type of relationship.
+   * - 'owned': Children are created/deleted with the parent (default for 1:N)
+   * - 'reference': Only the link is created/removed (for N:N)
+   * @default 'owned'
+   */
+  type: CollectionType;
+
+  /**
+   * Target entity name (required for 'reference' type).
+   * @example 'Tag'
+   */
+  entity?: string;
+
+  /**
+   * Junction table configuration (optional, for ORMs that need it like Drizzle).
+   * Prisma handles this automatically, so it's optional.
+   */
+  junction?: {
+    /** Junction table name (e.g., 'post_tags', '_PostToTag') */
+    table: string;
+    /** FK field pointing to the source entity (e.g., 'post_id') */
+    sourceKey: string;
+    /** FK field pointing to the target entity (e.g., 'tag_id') */
+    targetKey: string;
+  };
+}
 
 /**
  * Mapping schema for a domain entity.
@@ -17,7 +58,7 @@ export interface EntitySchema {
    */
   fields?: Record<string, string>;
   /**
-   * FK configuration for parent relation.
+   * FK configuration for parent relation (1:N owned).
    */
   parentFk?: {
     /** Name of the FK field in the database (e.g., 'author_id') */
@@ -25,6 +66,18 @@ export interface EntitySchema {
     /** Name of the parent entity (e.g., 'User') */
     parentEntity: string;
   };
+  /**
+   * Collection configurations for this entity's relations.
+   * Key is the property name in the domain entity.
+   * @example
+   * ```typescript
+   * collections: {
+   *   comments: { type: 'owned' },
+   *   tags: { type: 'reference', entity: 'Tag' }
+   * }
+   * ```
+   */
+  collections?: Record<string, CollectionConfig>;
 }
 
 /**
@@ -50,11 +103,15 @@ export interface MappedEntityData {
  *     table: 'blog_posts',
  *     fields: { content: 'post_content' },
  *     parentFk: { field: 'author_id', parentEntity: 'User' },
+ *     collections: {
+ *       comments: { type: 'owned' },
+ *       tags: { type: 'reference', entity: 'Tag' }
+ *     }
  *   });
  *
  * const table = registry.getTable('Post'); // 'blog_posts'
- * const mapped = registry.mapFields('User', { email: 'test@test.com' });
- * // { user_email: 'test@test.com' }
+ * const tagConfig = registry.getCollectionConfig('Post', 'tags');
+ * // { type: 'reference', entity: 'Tag' }
  * ```
  */
 export class EntitySchemaRegistry {
@@ -93,14 +150,24 @@ export class EntitySchemaRegistry {
   getSchema(entity: string): EntitySchema {
     const schema = this.schemas.get(entity);
     if (!schema) {
-      throw new Error(
+      throw new ConfigurationError(
         `EntitySchemaRegistry: No schema registered for entity '${entity}'. ` +
-          `Available entities: ${Array.from(this.schemas.keys()).join(", ") || "none"}`
+          `Available entities: ${
+            Array.from(this.schemas.keys()).join(", ") || "none"
+          }`
       );
     }
     return schema;
   }
 
+  /**
+   * Tries to get the schema of an entity, returns null if not found.
+   * @param entity - Entity name.
+   */
+  tryGetSchema(entity: string): EntitySchema | null {
+    return this.schemas.get(entity) ?? null;
+  }
+
   /**
    * Checks if an entity is registered.
    * @param entity - Entity name.
@@ -212,6 +279,104 @@ export class EntitySchemaRegistry {
     return schema.parentFk?.field ?? null;
   }
 
+  /**
+   * Gets the collection configuration for a specific field.
+   *
+   * @param entity - Parent entity name (e.g., 'Post')
+   * @param fieldName - Collection field name (e.g., 'tags')
+   * @returns CollectionConfig or null if not configured
+   *
+   * @example
+   * ```typescript
+   * const config = registry.getCollectionConfig('Post', 'tags');
+   * if (config?.type === 'reference') {
+   *   // Handle N:N relation - use connect/disconnect
+   * } else {
+   *   // Handle 1:N relation - use create/delete
+   * }
+   * ```
+   */
+  getCollectionConfig(
+    entity: string,
+    fieldName: string
+  ): CollectionConfig | null {
+    const schema = this.tryGetSchema(entity);
+    if (!schema?.collections) return null;
+    return schema.collections[fieldName] ?? null;
+  }
+
+  /**
+   * Checks if a collection is a reference type (N:N).
+   *
+   * @param entity - Parent entity name
+   * @param fieldName - Collection field name
+   * @returns true if the collection is a reference (N:N), false otherwise
+   *
+   * @example
+   * ```typescript
+   * if (registry.isReferenceCollection('Post', 'tags')) {
+   *   // Use connect/disconnect instead of create/delete
+   * }
+   * ```
+   */
+  isReferenceCollection(entity: string, fieldName: string): boolean {
+    const config = this.getCollectionConfig(entity, fieldName);
+    return config?.type === "reference";
+  }
+
+  /**
+   * Checks if a collection is owned (1:N).
+   * Returns true if explicitly configured as 'owned' or if not configured at all.
+   *
+   * @param entity - Parent entity name
+   * @param fieldName - Collection field name
+   * @returns true if the collection is owned (1:N), false if reference
+   */
+  isOwnedCollection(entity: string, fieldName: string): boolean {
+    const config = this.getCollectionConfig(entity, fieldName);
+    // Default to owned if not configured
+    return config?.type !== "reference";
+  }
+
+  /**
+   * Gets all collections configured for an entity.
+   *
+   * @param entity - Entity name
+   * @returns Record of field names to collection configs, or empty object
+   */
+  getCollections(entity: string): Record<string, CollectionConfig> {
+    const schema = this.tryGetSchema(entity);
+    return schema?.collections ?? {};
+  }
+
+  /**
+   * Gets all reference (N:N) collections for an entity.
+   *
+   * @param entity - Entity name
+   * @returns Array of field names that are reference collections
+   */
+  getReferenceCollections(entity: string): string[] {
+    const collections = this.getCollections(entity);
+    return Object.entries(collections)
+      .filter(([_, config]) => config.type === "reference")
+      .map(([field]) => field);
+  }
+
+  /**
+   * Gets the junction table configuration for a reference collection.
+   *
+   * @param entity - Parent entity name
+   * @param fieldName - Collection field name
+   * @returns Junction config or null
+   */
+  getJunctionConfig(
+    entity: string,
+    fieldName: string
+  ): CollectionConfig["junction"] | null {
+    const config = this.getCollectionConfig(entity, fieldName);
+    return config?.junction ?? null;
+  }
+
   /**
    * Lists all registered entities.
    */
@@ -234,7 +399,12 @@ export class EntitySchemaRegistry {
     if (Array.isArray(value)) return true;
     if (value instanceof Entity) return true;
     if (value instanceof ValueObject) return true;
-    if (typeof value === 'object' && value.id && typeof value.id === 'object' && 'value' in value.id) {
+    if (
+      typeof value === "object" &&
+      value.id &&
+      typeof value.id === "object" &&
+      "value" in value.id
+    ) {
       return true;
     }
     return false;
@@ -252,4 +422,81 @@ export class EntitySchemaRegistry {
     }
     return value;
   }
+
+  /**
+   * Validates that a relation field exists in the entity's collections.
+   *
+   * @param entity - Parent entity name
+   * @param relationField - Relation field to validate
+   * @throws ConfigurationError if the field doesn't exist
+   *
+   */
+  public validateRelationField(entity: string, relationField: string): void {
+    const schema = this.tryGetSchema(entity);
+
+    const uuidPattern =
+      /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+    if (uuidPattern.test(entity)) {
+      throw new ConfigurationError(
+        `EntitySchemaRegistry: Received an ID '${entity}' instead of an entity name. ` +
+          `This usually means 'parentEntity' is not being set correctly in the ChangeTracker. ` +
+          `Check that addDelete/addCreate are receiving the entity NAME (e.g., 'Post'), not the ID.`
+      );
+    }
+
+    if (!schema) {
+      throw new ConfigurationError(
+        `EntitySchemaRegistry: Cannot validate relation '${relationField}' - ` +
+          `entity '${entity}' is not registered. ` +
+          `Available entities: ${
+            this.getRegisteredEntities().join(", ") || "none"
+          }`
+      );
+    }
+
+    const collections = schema.collections ?? {};
+    const availableCollections = Object.keys(collections);
+
+    if (availableCollections.length === 0) {
+      throw new ConfigurationError(
+        `EntitySchemaRegistry: Entity '${entity}' has no collections configured, ` +
+          `but received operation for relation '${relationField}'. ` +
+          `Did you forget to configure collections in the schema?`
+      );
+    }
+
+    if (!collections[relationField]) {
+      const suggestions = this.findSimilarNames(
+        relationField,
+        availableCollections
+      );
+      const suggestionText =
+        suggestions.length > 0
+          ? ` Did you mean: '${suggestions.join("' or '")}'?`
+          : "";
+
+      throw new ConfigurationError(
+        `EntitySchemaRegistry: Unknown relation '${relationField}' for entity '${entity}'. ` +
+          `Available collections: ${availableCollections.join(
+            ", "
+          )}.${suggestionText}`
+      );
+    }
+  }
+
+  private findSimilarNames(input: string, candidates: string[]): string[] {
+    return candidates
+      .map((candidate) => ({
+        name: candidate,
+        distance: levenshteinDistance(
+          input.toLowerCase(),
+          candidate.toLowerCase()
+        ),
+      }))
+      .filter(({ distance }) => distance <= 3)
+      .sort((a, b) => a.distance - b.distance)
+      .slice(0, 2)
+      .map(({ name }) => name);
+  }
 }

package/src/paginated-result.ts

@@ -4,10 +4,10 @@ import type { Pagination, PaginationMeta, Filter } from "./types";
 
 /**
  * Infers the JSON result type from T
- * - If T has toJson(), returns its return type
+ * - If T has toJSON(), returns its return type
  * - Otherwise returns T as-is
  */
-type InferJsonResult<T> = T extends { toJson(): infer R } ? R : T;
+type InferJsonResult<T> = T extends { toJSON(): infer R } ? R : T;
 
 /**
  * Type for the serialized result of PaginatedResult.toJSON()
@@ -58,18 +58,6 @@ export class PaginatedResult<T> {
     let result = [...items];
     let total = result.length;
 
-    const search = criteria.getSearch();
-    if (search) {
-      result = result.filter((item) => {
-        return search.fields.some((field) => {
-          return String(getNestedValue(item, field))
-            .toLowerCase()
-            .includes(search.value.trim().toLowerCase());
-        });
-      });
-      total = result.length;
-    }
-
     for (const filter of criteria.getFilters()) {
       result = result.filter((item) => applyFilter(item, filter));
       total = result.length;
@@ -89,25 +77,17 @@ export class PaginatedResult<T> {
     }
 
     const pagination = criteria.getPagination();
-    if (pagination && !criteria.hasSearch()) {
-      result = result.slice(
-        pagination.offset,
-        pagination.offset + pagination.limit
-      );
-      return PaginatedResult.create(result, pagination, total);
-    }
-
-    return PaginatedResult.create(
-      result,
-      { page: 1, limit: result.length, offset: 0 },
-      total
+    result = result.slice(
+      pagination.offset,
+      pagination.offset + pagination.limit
     );
+    return PaginatedResult.create(result, pagination, total);
   }
 
   /**
    * Converts the result to JSON, deeply serializing all entities/aggregates/value objects
-   * - Entities/Aggregates → calls toJson() recursively
-   * - Value Objects → calls toJson()
+   * - Entities/Aggregates → calls toJSON() recursively
+   * - Value Objects → calls toJSON()
    * - Id → converts to string
    * - Arrays → maps recursively
    * - Plain objects → serializes properties recursively
@@ -134,8 +114,8 @@ export class PaginatedResult<T> {
       return obj.map((item) => this.deepSerialize(item));
     }
 
-    if (obj && typeof obj.toJson === "function") {
-      return obj.toJson();
+    if (obj && typeof obj.toJSON === "function") {
+      return obj.toJSON();
     }
 
     if (typeof obj === "object") {

package/src/types/change-tracker.ts

@@ -9,6 +9,8 @@ export interface BaseOperation {
   entity: string;
   /** Depth in the aggregate tree (0 = root, 1 = direct children, etc.) */
   depth: number;
+  /** Name of the relation field in the parent entity (e.g., 'tags', 'comments') */
+  relationField?: string;
 }
 
 /**
@@ -46,6 +48,10 @@ export interface DeleteOperation<T = any> extends BaseOperation {
   id: string;
   /** Entity data (for reference) */
   data: T;
+  /** Parent entity name */
+  parentEntity?: string;
+  /** Parent ID */
+  parentId?: string;
 }
 
 /**
@@ -64,6 +70,10 @@ export interface BatchCreateItem<T = any> {
   data: T;
   /** Parent ID (for FK) */
   parentId?: string;
+  /** Parent entity name */
+  parentEntity?: string;
+  /** Relation field name */
+  relationField?: string;
 }
 
 /**
@@ -76,6 +86,16 @@ export interface BatchUpdateItem {
   changedFields: Record<string, any>;
 }
 
+/**
+ * Item for batch delete.
+ */
+export interface BatchDeleteItem {
+  /** Entity ID */
+  id: string;
+  /** Relation field name */
+  relationField?: string;
+}
+
 /**
  * Grouped and ordered operations for batch execution.
  */
@@ -87,6 +107,13 @@ export interface BatchOperations {
     entity: string;
     depth: number;
     ids: string[];
+    parentId?: string;
+    /** Relation field name (for determining owned vs reference) */
+    relationField?: string;
+    /** Parent entity name */
+    parentEntity?: string;
+    /** Individual items with their relation fields (when mixed) */
+    items?: BatchDeleteItem[];
   }>;
 
   /**
@@ -96,6 +123,10 @@ export interface BatchOperations {
     entity: string;
     depth: number;
     items: BatchCreateItem[];
+    /** Relation field name (for determining owned vs reference) */
+    relationField?: string;
+    /** Parent entity name */
+    parentEntity?: string;
   }>;
 
   /**

package/src/types/criteria.ts

@@ -129,10 +129,7 @@ export interface Pagination {
   offset: number;
 }
 
-export interface Search<T> {
-  fields: FieldPath<T>[];
-  value: string;
-}
+export type Search = string;
 
 export interface PaginationMeta {
   page: number;

package/src/types/domain.ts

@@ -14,12 +14,14 @@ export type EntityValidation<T> = DomainValidation<T>;
 export type VOValidation<T> = DomainValidation<T>;
 
 export interface VOHooks<T, E> {
+  onBeforeCreate?: (props: T) => void;
   onBeforeUpdate?: (entity: E, snapshot: T) => boolean;
   onCreate?: (entity: E) => void;
   rules?: (entity: E) => void;
 }
 
 export interface EntityHooks<T extends BaseProps, E> {
+  onBeforeCreate?: (props: T) => void;
   onBeforeUpdate?: (entity: E, snapshot: T) => boolean;
   onCreate?: (entity: E) => void;
   rules?: (entity: E) => void;

package/src/types/utils.ts

@@ -3,10 +3,10 @@ import { Id } from "../id";
 export type DeepJsonResult<T> = {
   [K in keyof T]: T[K] extends Id
     ? string
-    : T[K] extends { toJson(): infer U }
+    : T[K] extends { toJSON(): infer U }
     ? U
     : T[K] extends Array<infer U>
-    ? U extends { toJson(): infer V }
+    ? U extends { toJSON(): infer V }
       ? V[]
       : U extends Id
       ? string[]

package/src/utils/helpers.ts

@@ -4,3 +4,31 @@ export function parseQueryValue(value: string): any {
   if (!isNaN(Date.parse(value))) return new Date(value); // Date
   return value; // string
 }
+
+export function levenshteinDistance(a: string, b: string): number {
+  const matrix: number[][] = [];
+
+  for (let i = 0; i <= b.length; i++) {
+    matrix[i] = [i];
+  }
+
+  for (let j = 0; j <= a.length; j++) {
+    matrix[0][j] = j;
+  }
+
+  for (let i = 1; i <= b.length; i++) {
+    for (let j = 1; j <= a.length; j++) {
+      if (b.charAt(i - 1) === a.charAt(j - 1)) {
+        matrix[i][j] = matrix[i - 1][j - 1];
+      } else {
+        matrix[i][j] = Math.min(
+          matrix[i - 1][j - 1] + 1, // substitution
+          matrix[i][j - 1] + 1, // insertion
+          matrix[i - 1][j] + 1 // deletion
+        );
+      }
+    }
+  }
+
+  return matrix[b.length][a.length];
+}

package/src/value-object.ts

@@ -229,7 +229,7 @@ export abstract class ValueObject<T> {
     return this.domainEvents.length > 0;
   }
 
-  toJson(): T {
+  toJSON(): T {
     return { ...this.props };
   }
 

package/.versionrc.json

@@ -1,21 +0,0 @@
-{
-  "types": [
-    { "type": "feat", "section": "Features" },
-    { "type": "fix", "section": "Bug Fixes" },
-    { "type": "chore", "hidden": false, "section": "Chores" },
-    { "type": "docs", "hidden": false, "section": "Documentation" },
-    { "type": "style", "hidden": true },
-    { "type": "refactor", "section": "Refactoring" },
-    { "type": "perf", "section": "Performance Improvements" },
-    { "type": "test", "hidden": false, "section": "Tests" }
-  ],
-  "commitUrlFormat": "{{host}}/{{owner}}/{{repository}}/commit/{{hash}}",
-  "compareUrlFormat": "{{host}}/{{owner}}/{{repository}}/compare/{{previousTag}}...{{currentTag}}",
-  "issueUrlFormat": "{{host}}/{{owner}}/{{repository}}/issues/{{id}}",
-  "userUrlFormat": "{{host}}/{{user}}",
-  "releaseCommitMessageFormat": "chore(release): {{currentTag}}",
-  "issuePrefixes": ["#"],
-  "skip": {
-    "changelog": false
-  }
-}