@woltz/rich-domain 1.2.4 → 1.3.1

package/src/criteria.ts

@@ -27,7 +27,7 @@ export class Criteria<T = any> {
   private _filters: Filter<FieldPath<T>, any>[] = [];
   private _orders: Order[] = [];
   private _pagination: Pagination = { page: 1, limit: 20, offset: 0 };
-  private _search?: Search<T>;
+  private _search?: Search;
   private _adapter?: CriteriaAdapter<any, any>;
 
   private constructor() {}
@@ -155,11 +155,8 @@ export class Criteria<T = any> {
     return this.orderBy(field, "desc");
   }
 
-  search<K extends FieldPath<T>>(fields: K[], value: string): this {
-    this._search = {
-      fields: fields.map(this.resolveFieldPath),
-      value,
-    };
+  search(value: string): this {
+    this._search = value;
     return this;
   }
 
@@ -167,13 +164,8 @@ export class Criteria<T = any> {
     return !!this._search;
   }
 
-  getSearch() {
-    return this._search
-      ? {
-          fields: this._search.fields.map(this.resolveFieldPath),
-          value: this._search.value,
-        }
-      : undefined;
+  getSearch(): Search | undefined {
+    return this._search;
   }
 
   paginate(page: number, limit: number): this {
@@ -241,12 +233,7 @@ export class Criteria<T = any> {
       })),
     ];
     cloned._pagination = { ...this._pagination };
-    cloned._search = this._search
-      ? {
-          fields: this._search.fields.map(this.resolveFieldPath),
-          value: this._search.value,
-        }
-      : undefined;
+    cloned._search = this._search;
 
     if (this._adapter) {
       cloned.useAdapter(this._adapter);
@@ -268,12 +255,7 @@ export class Criteria<T = any> {
         direction: order.direction,
       })),
       pagination: this._pagination,
-      search: this._search
-        ? {
-            fields: this._search.fields.map(this.resolveFieldPath),
-            value: this._search.value,
-          }
-        : undefined,
+      search: this._search,
     };
   }
 
@@ -282,7 +264,7 @@ export class Criteria<T = any> {
       filters?: TypedFilter<T>[];
       orders?: TypedOrder<T>[];
       pagination?: Pagination;
-      search?: { fields: FieldPath<T>[]; value: string };
+      search?: Search;
     },
     adapter?: CriteriaAdapter<any, any>
   ): Criteria<T> {
@@ -307,11 +289,7 @@ export class Criteria<T = any> {
         })),
       ];
     if (obj.pagination) criteria._pagination = { ...obj.pagination };
-    if (obj.search)
-      criteria._search = {
-        ...obj.search,
-        fields: obj.search.fields.map(criteria.resolveFieldPath),
-      };
+    if (obj.search) criteria._search = obj.search;
 
     return criteria;
   }
@@ -337,10 +315,12 @@ export class Criteria<T = any> {
     return field;
   }
 
-  static fromQueryParams<T>(
-    query: Record<string, any>,
+  static fromQueryParams<T = any>(
+    query: Record<string, any> | undefined,
     adapter?: CriteriaAdapter<any, any>
   ): Criteria<T> {
+    if (!query) return Criteria.create<T>();
+
     const criteria = Criteria.create<T>();
 
     if (adapter) {
@@ -354,80 +334,95 @@ export class Criteria<T = any> {
       if (key === "limit") {
         continue;
       }
-      if (key === "sort") {
-        continue;
-      }
 
-      const [field, operatorWithQuantifier] = key.split(":");
+      if (key === "filters") {
+        const filters: Record<string, any> = criteria.parseFilterValue(value);
 
-      if (!operatorWithQuantifier || !field) continue;
+        for (let [filterKey, filterValue] of Object.entries(filters)) {
+          const [field, operatorWithQuantifier] = filterKey.split(":");
 
-      const [operatorRaw, quantifierRaw] = operatorWithQuantifier.split("@");
-      const operator = isOperator(operatorRaw) ? operatorRaw : null;
-      if (!operator) {
-        throw new InvalidCriteriaError(`Invalid filter operator`, operatorRaw);
-      }
+          if (!operatorWithQuantifier || !field) continue;
 
-      const validQuantifiers = ["some", "every", "none"];
-      const quantifier =
-        quantifierRaw && validQuantifiers.includes(quantifierRaw)
-          ? (quantifierRaw as CriteriaOptions["quantifier"])
-          : undefined;
-
-      if (quantifierRaw && !quantifier) {
-        throw new InvalidCriteriaError(
-          `Invalid quantifier. Valid values: ${validQuantifiers.join(", ")}`,
-          quantifierRaw
-        );
-      }
+          const [operatorRaw, quantifierRaw] =
+            operatorWithQuantifier.split("@");
+          const operator = isOperator(operatorRaw) ? operatorRaw : null;
+          if (!operator) {
+            throw new InvalidCriteriaError(
+              `Invalid filter operator`,
+              operatorRaw
+            );
+          }
 
-      const options: CriteriaOptions | undefined = quantifier
-        ? { quantifier }
-        : undefined;
+          const validQuantifiers = ["some", "every", "none"];
+          const quantifier =
+            quantifierRaw && validQuantifiers.includes(quantifierRaw)
+              ? (quantifierRaw as CriteriaOptions["quantifier"])
+              : undefined;
+
+          if (quantifierRaw && !quantifier) {
+            throw new InvalidCriteriaError(
+              `Invalid quantifier. Valid values: ${validQuantifiers.join(
+                ", "
+              )}`,
+              quantifierRaw
+            );
+          }
 
-      let parsedValue: any = value;
+          const options: CriteriaOptions | undefined = quantifier
+            ? { quantifier }
+            : undefined;
 
-      const resolvedField = criteria.resolveFieldPath(field as FieldPath<T>);
+          let parsedValue: any = filterValue;
 
-      if (operator === "between") {
-        parsedValue = value
-          .split(",")
-          .map((v: any) => parseQueryValue(v.trim()));
-        if (parsedValue.length === 2) {
-          criteria.where(
-            resolvedField,
-            "between" as OperatorsForType<PathValue<T, FieldPath<T>>>,
-            [parsedValue[0], parsedValue[1]] as [
-              PathValue<T, FieldPath<T>>,
-              PathValue<T, FieldPath<T>>
-            ],
-            options
+          const resolvedField = criteria.resolveFieldPath(
+            field as FieldPath<T>
           );
-        }
-        continue;
-      }
 
-      if (operator === "in" || operator === "notIn") {
-        parsedValue = value.split(",").map(parseQueryValue);
-        criteria.where(
-          field as any,
-          operator as OperatorsForType<PathValue<T, FieldPath<T>>>,
-          parsedValue,
-          options
-        );
-        continue;
-      }
+          if (operator === "between") {
+            parsedValue = criteria
+              .parseFilterValue(filterValue)
+              .map((v: any) => parseQueryValue(v.trim()));
+
+            if (parsedValue.length === 2) {
+              criteria.where(
+                resolvedField,
+                "between" as OperatorsForType<PathValue<T, FieldPath<T>>>,
+                [parsedValue[0], parsedValue[1]] as [
+                  PathValue<T, FieldPath<T>>,
+                  PathValue<T, FieldPath<T>>
+                ],
+                options
+              );
+            }
+            continue;
+          }
 
-      const parsedFinalValue = parseQueryValue(value);
+          if (operator === "in" || operator === "notIn") {
+            parsedValue = criteria
+              .parseFilterValue(filterValue)
+              .map(parseQueryValue);
+
+            criteria.where(
+              field as any,
+              operator as OperatorsForType<PathValue<T, FieldPath<T>>>,
+              parsedValue,
+              options
+            );
+            continue;
+          }
 
-      criteria.validateOperator(operator, parsedFinalValue);
+          const parsedFinalValue = parseQueryValue(filterValue);
 
-      criteria.where(
-        field as FieldPath<T>,
-        operator as OperatorsForType<PathValue<T, FieldPath<T>>>,
-        parsedFinalValue,
-        options
-      );
+          criteria.validateOperator(operator, parsedFinalValue);
+
+          criteria.where(
+            field as FieldPath<T>,
+            operator as OperatorsForType<PathValue<T, FieldPath<T>>>,
+            parsedFinalValue,
+            options
+          );
+        }
+      }
     }
 
     const page = query.page ? parseInt(query.page) : undefined;
@@ -437,24 +432,60 @@ export class Criteria<T = any> {
       criteria.paginate(page, limit);
     }
 
+    // 1. orderBy=["field:asc","field2:desc"]
     if (query.orderBy) {
-      const sortParts = query.orderBy.split(",");
-      sortParts.forEach((part: string) => {
-        const [field, direction] = part.split(":");
-        criteria.orderBy(
-          field as FieldPath<T>,
-          (direction as OrderDirection) || "asc"
-        );
-      });
+      const orderByValue = query.orderBy;
+
+      if (
+        typeof orderByValue === "string" &&
+        orderByValue.trim().startsWith("[")
+      ) {
+        try {
+          const orderArray = JSON.parse(orderByValue);
+          if (Array.isArray(orderArray)) {
+            orderArray.forEach((item: string) => {
+              const [field, direction] = item.split(":");
+              criteria.orderBy(
+                field as FieldPath<T>,
+                (direction as OrderDirection) || "asc"
+              );
+            });
+          }
+        } catch {
+          throw new InvalidCriteriaError(
+            "Invalid JSON array format for orderBy",
+            orderByValue
+          );
+        }
+      } else if (Array.isArray(orderByValue)) {
+        orderByValue.forEach((item: string) => {
+          const [field, direction] = item.split(":");
+          criteria.orderBy(
+            field as FieldPath<T>,
+            (direction as OrderDirection) || "asc"
+          );
+        });
+      }
+      // 2. orderBy="field:asc,field2:desc"
+      else if (typeof orderByValue === "string" && orderByValue.includes(":")) {
+        const sortParts = orderByValue.split(",");
+        sortParts.forEach((part: string) => {
+          const [field, direction] = part.split(":");
+          criteria.orderBy(
+            field as FieldPath<T>,
+            (direction as OrderDirection) || "asc"
+          );
+        });
+      }
+      // 3. orderBy="field" + orderDirection="asc"
+      else {
+        const direction = (query.orderDirection as OrderDirection) || "asc";
+        criteria.orderBy(orderByValue as FieldPath<T>, direction);
+      }
     }
 
-    if (query.search && query.searchFields) {
-      const fields = (query.searchFields as string)
-        .split(",")
-        .filter(Boolean) as FieldPath<T>[];
-
-      const resolvedFields = fields.map(criteria.resolveFieldPath);
-      criteria.search(resolvedFields, query.search as string);
+    if (query.search && typeof query.search === "string") {
+      criteria.search(query.search);
     }
 
     return criteria;
@@ -476,4 +507,15 @@ export class Criteria<T = any> {
       );
     }
   }
+
+  private parseFilterValue(value: any) {
+    if (typeof value === "string") {
+      try {
+        return JSON.parse(value);
+      } catch {
+        throw new InvalidCriteriaError(`Invalid filter value`, value);
+      }
+    }
+    return parseQueryValue(value);
+  }
 }

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,31 @@ 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;
   }
 
+  /**
+   * Gets all registered schemas.
+   */
+  getAllSchemas(): EntitySchema[] {
+    return Array.from(this.schemas.values());
+  }
+
+  /**
+   * 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 +286,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 +406,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 +429,77 @@ 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) {
+      return;
+    }
+
+    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/index.ts

@@ -11,7 +11,7 @@ export { ValueObject } from "./value-object";
 export { Mapper } from "./mapper";
 export { EntitySchemaRegistry } from "./entity-schema-registry";
 export { AggregateChanges } from "./aggregate-changes";
-export {
+export type {
   DomainEventHandler,
   EntityHooks,
   Filter,