@nulledexp/translatable-criteria 1.1.0 → 2.0.0

package/README.md

@@ -3,7 +3,8 @@
 [![NPM Version](https://img.shields.io/npm/v/@nulledexp/translatable-criteria.svg)](https://www.npmjs.com/package/@nulledexp/translatable-criteria)
 ![NPM Downloads](https://img.shields.io/npm/dw/%40nulledexp%2Ftranslatable-criteria)
 [![Development Stage](https://img.shields.io/badge/Development-Active%20Development-green)]()
-[![Documentation](https://img.shields.io/badge/Documentation-EN/ES-blue)](./src/docs/introduction/en.md)
+[![Documentation](https://img.shields.io/badge/Documentation-EN-blue)](./src/docs/introduction/en.md)
+[![Documentation](https://img.shields.io/badge/Documentation-ES-blue)](./src/docs/introduction/es.md)
 [![CI](https://github.com/Techscq/translatable-criteria/actions/workflows/ci.yml/badge.svg)](https://github.com/Techscq/translatable-criteria/actions/workflows/ci.yml)
 
 A TypeScript library for building data-source agnostic, translatable query criteria. Define complex filtering, ordering, and join logic in a structured, type-safe way, then translate it to your specific data source using custom translators.
@@ -16,84 +17,88 @@ npm install @nulledexp/translatable-criteria
 
 ## Overview
 
-This library simplifies the construction of complex data queries by providing a consistent and abstract way to define filtering, ordering, field selection, pagination (offset and cursor-based), and relationship (joins) configurations. The core concept revolves around the `Criteria` object hierarchy, which allows developers to define sophisticated query specifications in a data source-agnostic manner. These `Criteria` objects can then be processed by a `CriteriaTranslator` (using the Visitor pattern) to generate queries for various data sources.
+This library simplifies the construction of complex data queries by providing a consistent and abstract way to define filtering, ordering, field selection, pagination (offset and cursor-based), and relationship (joins) configurations. The core concept revolves around the `Criteria` object hierarchy, which allows developers to define sophisticated query specifications in a data source-agnostic manner, now with enhanced schema validation (including `identifier_field`) and richer context for translators (like `parent_identifier`). These `Criteria` objects can then be processed by a `CriteriaTranslator` to generate queries for various data sources.
 
 ## Key Features
 
-- **Enhanced Type-Safety:** Construct queries with a fluent, strongly-typed interface, benefiting from compile-time and runtime validation of field names, aliases, and join parameters based on your schemas.
-- **Powerful Filtering:** Define intricate filtering logic with multiple operators (including for JSON and arrays) and grouping. Filter groups are automatically normalized for consistency.
-- **Flexible Join System:** Support for various join types (inner, left, full outer) and pivot table configurations, with validation of join parameters according to the relation type.
-- **Default Join Field Selection:** When a join is added, if `setSelect()` is not explicitly called on the `JoinCriteria`, all fields from the joined schema will be automatically included in the main `SELECT` clause. This can be overridden by using `setSelect()` on the specific `JoinCriteria`.
-- **Field Selection:** Specify exactly which fields to retrieve using `setSelect()`. Use `resetSelect()` to select all fields (which is also the default behavior).
+- **Enhanced Type-Safety:** Construct queries with a fluent, strongly-typed interface, benefiting from compile-time and runtime validation of field names (including `identifier_field`), aliases, and join parameters based on your schemas.
+- **Powerful Filtering:** Define intricate filtering logic with multiple operators (including for JSON, arrays, sets, ranges, and regex) and grouping. Filter groups are automatically normalized for consistency.
+- **Flexible Join System:** Support for various join types (inner, left, full outer) and pivot table configurations. Join parameters now include `parent_identifier` to provide richer context to translators for relationship inference (e.g., for `one_to_one`).
+- **Granular Null-Value Sorting:** Explicitly control whether `NULL` values appear first or last in your ordered results.
+- **Filter-Only Joins:** Improve query performance by creating joins solely for filtering, without including their fields in the final `SELECT` statement.
+- **Field Selection & `identifier_field`:** Specify exactly which fields to retrieve using `setSelect()`. The `identifier_field` of an entity is automatically included when `setSelect()` is used. Use `resetSelect()` to select all fields (default behavior).
 - **Pagination:** Supports both offset-based (`setTake()`, `setSkip()`) and cursor-based (`setCursor()`) pagination.
-- **Visitor Pattern for Translation:** Criteria objects implement an `accept` method, allowing for clean and extensible translation logic via the Visitor pattern.
 - **Data Source Agnostic:** Design criteria independently of the underlying data source.
 - **Translator-Based Architecture:** The core library defines criteria; actual translation is handled by separate translator packages that implement the `CriteriaTranslator` interface.
 - **Full TypeScript Support:** Benefit from compile-time validation and autocompletion.
 
 ## Core Concepts
 
-The library is built upon a few fundamental concepts. For detailed explanations, please refer to our Core Concepts Documentation.
+The library is built upon a few fundamental concepts. For detailed explanations, please refer to our documentation guides.
 
-- **`Criteria` Hierarchy:** Abstract base for query specifications (`RootCriteria`, `InnerJoinCriteria`, etc.). Learn more.
-- **`CriteriaFactory`:** Recommended utility for creating `Criteria` instances (e.g., `CriteriaFactory.GetCriteria(...)`, `CriteriaFactory.GetInnerJoinCriteria(...)`). Learn more.
-- **Schemas (`CriteriaSchema` & `GetTypedCriteriaSchema`):** Define your data entities' structure for type-safe criteria construction. Learn more.
-- **`CriteriaTranslator`:** Abstract class for converting `Criteria` objects into specific data source queries using the Visitor pattern. Learn more.
+- [**`Criteria` Hierarchy:**](./src/docs/core-concepts/en.md#criteria-hierarchy) Abstract base for query specifications (`RootCriteria`, `InnerJoinCriteria`, etc.).
+- [**`CriteriaFactory`:**](./src/docs/core-concepts/en.md#criteriafactory) Recommended utility for creating `Criteria` instances.
+- [**Schemas (`CriteriaSchema` & `GetTypedCriteriaSchema`):**](./src/docs/guides/schema-definitions/en.md) Define your data entities' structure for type-safe criteria construction.
+- [**`CriteriaTranslator`:**](./src/docs/guides/developing-translators/en.md) Abstract class responsible for converting `Criteria` objects into specific data source queries.
 
 ## Usage Example (Core Library)
 
-This package provides the tools to define your query criteria.
+This package provides the tools to define your query criteria. The core philosophy is to define relationship logic **once** in the schema, and then simply reference it when building criteria.
 
 ### 1. Define Schemas
 
+First, define your entity schemas using `GetTypedCriteriaSchema`. This is where you declare how entities are related by defining `local_field`, `relation_field`, etc.
+
 ```typescript
 import { GetTypedCriteriaSchema } from '@nulledexp/translatable-criteria';
 
 export const UserSchema = GetTypedCriteriaSchema({
-  source_name: 'user',
-  alias: ['users', 'user', 'publisher'],
-  fields: ['uuid', 'email', 'username', 'created_at'],
-  joins: [
-    { alias: 'posts', join_relation_type: 'one_to_many' },
-    // other joins like 'permissions', 'addresses' can be defined here
+  source_name: 'users',
+  alias: 'u',
+  fields: ['id', 'username', 'email', 'age', 'isActive', 'createdAt'],
+  identifier_field: 'id',
+  relations: [
+    {
+      relation_alias: 'posts',
+      target_source_name: 'posts',
+      relation_type: 'one_to_many',
+      local_field: 'id',
+      relation_field: 'userId',
+    },
   ],
 });
-export type UserSchema = typeof UserSchema;
 
 export const PostSchema = GetTypedCriteriaSchema({
-  source_name: 'post',
-  alias: ['posts', 'post'],
-  fields: [
-    'uuid',
-    'title',
-    'body',
-    'user_uuid',
-    'created_at',
-    'categories', // Example: for array filters
-    'metadata', // Example: for JSON filters
-  ],
-  joins: [
-    { alias: 'comments', join_relation_type: 'one_to_many' },
-    { alias: 'publisher', join_relation_type: 'many_to_one' },
+  source_name: 'posts',
+  alias: 'p',
+  fields: ['id', 'title', 'content', 'userId', 'createdAt'],
+  identifier_field: 'id',
+  relations: [
+    {
+      relation_alias: 'user',
+      target_source_name: 'users',
+      relation_type: 'many_to_one',
+      local_field: 'userId',
+      relation_field: 'id',
+    },
   ],
 });
-export type PostSchema = typeof PostSchema;
-
-// Define other schemas (PermissionSchema, PostCommentSchema, AddressSchema) as needed for your application.
-// See the full documentation for more examples.
 ```
 
-### 2. Create Criteria
+### 2. Create a Simple Criteria
+
+Use `CriteriaFactory` to create a `Criteria` object and apply filters or ordering.
 
 ```typescript
 import {
   CriteriaFactory,
   FilterOperator,
+  OrderDirection,
 } from '@nulledexp/translatable-criteria';
-import { UserSchema } from './path/to/your/criteria/schemas'; // Adjust path
+import { UserSchema } from './path/to/your/schemas'; // Adjust path
 
 // Create Criteria for the User entity
-const userCriteria = CriteriaFactory.GetCriteria(UserSchema, 'users');
+const userCriteria = CriteriaFactory.GetCriteria(UserSchema);
 
 // Example: Add a simple filter
 userCriteria.where({
@@ -103,17 +108,45 @@ userCriteria.where({
 });
 
 // Example: Add ordering
-userCriteria.orderBy('created_at', 'DESC');
+userCriteria.orderBy('createdAt', OrderDirection.DESC);
 
 // The 'userCriteria' object is now ready to be passed to a translator.
 ```
 
+### 3. Create Criteria with a Join
+
+To add a join, simply call the `.join()` method with the `relation_alias` you defined in the schema. The library automatically uses the configuration you provided, eliminating the need for manual join parameters.
+
+```typescript
+import {
+  CriteriaFactory,
+  FilterOperator,
+} from '@nulledexp/translatable-criteria';
+import { PostSchema, UserSchema } from './path/to/your/schemas'; // Adjust path
+
+// Find posts from active users
+const postCriteria = CriteriaFactory.GetCriteria(PostSchema);
+
+const activeUserJoin = CriteriaFactory.GetInnerJoinCriteria(UserSchema).where({
+  field: 'isActive',
+  operator: FilterOperator.EQUALS,
+  value: true,
+});
+
+// The join is now declarative. Just provide the relation alias.
+postCriteria.join('user', activeUserJoin);
+
+// The 'postCriteria' object is now ready to be passed to a translator.
+```
+
+---
+
 ## Available Translators
 
-To interact with a database, you'll need a translator package.
+To interact with a database, you'll need a translator package. You can either build your own following our Criteria Translator Development Guide or use one from the community.
 
 - **`@nulledexp/typeorm-mysql-criteria-translator`**:
-  A translator for generating TypeORM `SelectQueryBuilder` instances for MySQL.
+  - A translator for generating TypeORM `SelectQueryBuilder` instances for MySQL.
   - **Author:** Nelson Cabrera
   - **Installation**:
 
@@ -121,58 +154,25 @@ To interact with a database, you'll need a translator package.
   npm install @nulledexp/typeorm-mysql-criteria-translator
 ```
 
-- **Usage (basic)**:
-
-```typescript
-import {
-  CriteriaFactory,
-  FilterOperator,
-} from '@nulledexp/translatable-criteria';
-import { TypeOrmMysqlTranslator } from '@nulledexp/typeorm-mysql-criteria-translator'; // Using new suggested name
-import { UserSchema } from './path/to/your/criteria/schemas'; // Your Criteria Schema
-// import { YourTypeOrmUserEntity } from './path/to/your/typeorm/entities'; // Your actual TypeORM entity
-// import { DbDatasource } from './path-to-your-datasource-config'; // Your initialized TypeORM DataSource instance
-
-// 1. Define your Criteria using @nulledexp/translatable-criteria
-const criteria = CriteriaFactory.GetCriteria(UserSchema, 'users') // 'users' is an alias from UserSchema
-  .where({
-    field: 'username', // Field from UserSchema
-    operator: FilterOperator.EQUALS,
-    value: 'testuser',
-  })
-  .setTake(10);
-
-// 2. Use the translator with your TypeORM QueryBuilder
-// (Conceptual - assuming DbDatasource and YourTypeOrmUserEntity are set up)
-
-// const queryBuilder = DbDatasource.getRepository(YourTypeOrmUserEntity)
-//   .createQueryBuilder(criteria.alias); // Alias must match root criteria alias
-
-// const translator = new TypeOrmMysqlTranslator<YourTypeOrmUserEntity>();
-// translator.translate(criteria, queryBuilder);
-
-// Now queryBuilder is populated with the translated criteria
-// console.log(queryBuilder.getSql(), queryBuilder.getParameters());
-// const results = await queryBuilder.getMany();
-```
+- **Usage:**
 
-- **Note:** This translator has been tested with integration tests. Please review its implementation at its repository (replace with actual repo link if different) to ensure it meets your specific project needs and production requirements. Contributions and bug reports are welcome!
+  - See the TypeORM Translator Usage Guide for detailed instructions.
 
 - **(More translators coming soon or can be created by the community)**
 
-### Developing Custom Translators
-
-You can create your own translators by extending the abstract `CriteriaTranslator` class. See the Developing Custom Translators Guide for details.
+**Important Note for Translator Developers:** Translators should be updated to handle the new `parent_identifier` in join parameters (especially for inferring `one_to_one` relationships) and to support the new filter operators. Refer to the Developing Custom Translators Guide for details.
 
 ## Type Safety Features
 
 - Compile-time validation of field names within criteria based on schemas.
+- Validation of `identifier_field` definition within schemas.
 - Type-checked join configurations ensuring compatibility between schemas.
 - Autocomplete support for schema fields and defined join aliases.
 - Validation of alias usage in `Criteria` constructors.
 - Robust validation of join parameters based on `join_relation_type`.
 - Validation for selected fields, cursor fields, take/skip values.
 - Strictly typed filter values based on the `FilterOperator` used.
+- Inclusion of `parent_identifier` in resolved join parameters for translator use.
 
 ## Roadmap (Core Library)
 
@@ -182,9 +182,13 @@ You can create your own translators by extending the abstract `CriteriaTranslato
 - [x] Implement `LIMIT` and `OFFSET` (take/skip) for pagination.
 - [x] Implement `PivotJoin` for many-to-many relationships.
 - [x] Strictly typed filter values based on operator.
-- [x] New filter operators (JSON, Array, Set).
-- [x] Enhanced documentation with detailed examples for translator development.
+- [x] New filter operators (JSON, Array, Set, Range, Regex, ILIKE).
 - [x] `OuterJoinCriteria` support in the core logic.
+- [x] Introduce `identifier_field` in schemas and `parent_identifier` in join parameters.
+- [x] Enforce stricter schema validation at type level.
+- [x] Implement `NULLS FIRST/LAST` ordering.
+- [x] Implement filter-only joins (`withSelect`).
+- [x] Enhanced documentation with detailed examples for translator development.
 - [ ] Explore utility functions to simplify translator development.
 - [ ] Explore utility functions to simplify schema development.
 - [ ] Add more comprehensive unit test coverage for criteria construction and edge cases.

package/dist/criteria/criteria-factory.d.ts

@@ -1,8 +1,9 @@
 import { RootCriteria } from './root.criteria.js';
-import type { CriteriaSchema, SelectedAliasOf } from './types/schema.types.js';
+import type { CriteriaSchema } from './types/schema.types.js';
 import { InnerJoinCriteria } from './join/inner.join-criteria.js';
 import { LeftJoinCriteria } from './join/left.join-criteria.js';
 import { OuterJoinCriteria } from './join/outer.join-criteria.js';
+import type { ValidSchema } from './criteria.js';
 /**
  * Provides static methods for creating instances of different types of `Criteria`.
  * This simplifies the creation of `Criteria` objects and ensures they are instantiated
@@ -22,7 +23,7 @@ export declare class CriteriaFactory {
      *
      * const userCriteria = CriteriaFactory.GetCriteria(UserSchema, 'users');
      */
-    static GetCriteria<CSchema extends CriteriaSchema, Alias extends SelectedAliasOf<CSchema>>(schema: CSchema, alias: Alias): RootCriteria<CSchema, Alias>;
+    static GetCriteria<CSchema extends CriteriaSchema>(schema: ValidSchema<CSchema>): RootCriteria<CSchema>;
     /**
      * Creates an instance of `InnerJoinCriteria`. Used to define an `INNER JOIN` in a query.
      * @template CSchema - The type of the `CriteriaSchema` for the entity to be joined.
@@ -37,7 +38,7 @@ export declare class CriteriaFactory {
      * const postJoinCriteria = CriteriaFactory.GetInnerJoinCriteria(PostSchema, 'posts');
      * // postJoinCriteria can then be used in the .join() method of another Criteria
      */
-    static GetInnerJoinCriteria<CSchema extends CriteriaSchema, Alias extends SelectedAliasOf<CSchema>>(schema: CSchema, alias: Alias): InnerJoinCriteria<CSchema, Alias>;
+    static GetInnerJoinCriteria<CSchema extends CriteriaSchema>(schema: ValidSchema<CSchema>): InnerJoinCriteria<CSchema>;
     /**
      * Creates an instance of `LeftJoinCriteria`. Used to define a `LEFT JOIN` in a query.
      * @template CSchema - The type of the `CriteriaSchema` for the entity to be joined.
@@ -51,7 +52,7 @@ export declare class CriteriaFactory {
      *
      * const commentJoinCriteria = CriteriaFactory.GetLeftJoinCriteria(CommentSchema, 'comments');
      */
-    static GetLeftJoinCriteria<CSchema extends CriteriaSchema, Alias extends SelectedAliasOf<CSchema>>(schema: CSchema, alias: Alias): LeftJoinCriteria<CSchema, Alias>;
+    static GetLeftJoinCriteria<CSchema extends CriteriaSchema>(schema: ValidSchema<CSchema>): LeftJoinCriteria<CSchema>;
     /**
      * Creates an instance of `OuterJoinCriteria`. Used to define a `FULL OUTER JOIN` in a query.
      * @template CSchema - The type of the `CriteriaSchema` for the entity to be joined.
@@ -65,6 +66,6 @@ export declare class CriteriaFactory {
      *
      * const profileJoinCriteria = CriteriaFactory.GetOuterJoinCriteria(ProfileSchema, 'profiles');
      */
-    static GetOuterJoinCriteria<CSchema extends CriteriaSchema, Alias extends SelectedAliasOf<CSchema>>(schema: CSchema, alias: Alias): OuterJoinCriteria<CSchema, Alias>;
+    static GetOuterJoinCriteria<CSchema extends CriteriaSchema>(schema: ValidSchema<CSchema>): OuterJoinCriteria<CSchema>;
 }
 //# sourceMappingURL=criteria-factory.d.ts.map

package/dist/criteria/criteria-factory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"criteria-factory.d.ts","sourceRoot":"","sources":["../../src/criteria/criteria-factory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC/E,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAElE;;;;GAIG;AACH,qBAAa,eAAe;IAC1B;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,WAAW,CAChB,OAAO,SAAS,cAAc,EAC9B,KAAK,SAAS,eAAe,CAAC,OAAO,CAAC,EACtC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,GAAG,YAAY,CAAC,OAAO,EAAE,KAAK,CAAC;IAI9D;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,oBAAoB,CACzB,OAAO,SAAS,cAAc,EAC9B,KAAK,SAAS,eAAe,CAAC,OAAO,CAAC,EACtC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,GAAG,iBAAiB,CAAC,OAAO,EAAE,KAAK,CAAC;IAInE;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,mBAAmB,CACxB,OAAO,SAAS,cAAc,EAC9B,KAAK,SAAS,eAAe,CAAC,OAAO,CAAC,EACtC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,GAAG,gBAAgB,CAAC,OAAO,EAAE,KAAK,CAAC;IAIlE;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,oBAAoB,CACzB,OAAO,SAAS,cAAc,EAC9B,KAAK,SAAS,eAAe,CAAC,OAAO,CAAC,EACtC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,GAAG,iBAAiB,CAAC,OAAO,EAAE,KAAK,CAAC;CAGpE"}
+{"version":3,"file":"criteria-factory.d.ts","sourceRoot":"","sources":["../../src/criteria/criteria-factory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD;;;;GAIG;AACH,qBAAa,eAAe;IAC1B;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,WAAW,CAAC,OAAO,SAAS,cAAc,EAC/C,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,GAC3B,YAAY,CAAC,OAAO,CAAC;IAIxB;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,oBAAoB,CAAC,OAAO,SAAS,cAAc,EACxD,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,GAC3B,iBAAiB,CAAC,OAAO,CAAC;IAI7B;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,mBAAmB,CAAC,OAAO,SAAS,cAAc,EACvD,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,GAC3B,gBAAgB,CAAC,OAAO,CAAC;IAI5B;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,oBAAoB,CAAC,OAAO,SAAS,cAAc,EACxD,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,GAC3B,iBAAiB,CAAC,OAAO,CAAC;CAG9B"}

package/dist/criteria/criteria-factory.js

@@ -21,8 +21,8 @@ export class CriteriaFactory {
      *
      * const userCriteria = CriteriaFactory.GetCriteria(UserSchema, 'users');
      */
-    static GetCriteria(schema, alias) {
-        return new RootCriteria(schema, alias);
+    static GetCriteria(schema) {
+        return new RootCriteria(schema);
     }
     /**
      * Creates an instance of `InnerJoinCriteria`. Used to define an `INNER JOIN` in a query.
@@ -38,8 +38,8 @@ export class CriteriaFactory {
      * const postJoinCriteria = CriteriaFactory.GetInnerJoinCriteria(PostSchema, 'posts');
      * // postJoinCriteria can then be used in the .join() method of another Criteria
      */
-    static GetInnerJoinCriteria(schema, alias) {
-        return new InnerJoinCriteria(schema, alias);
+    static GetInnerJoinCriteria(schema) {
+        return new InnerJoinCriteria(schema);
     }
     /**
      * Creates an instance of `LeftJoinCriteria`. Used to define a `LEFT JOIN` in a query.
@@ -54,8 +54,8 @@ export class CriteriaFactory {
      *
      * const commentJoinCriteria = CriteriaFactory.GetLeftJoinCriteria(CommentSchema, 'comments');
      */
-    static GetLeftJoinCriteria(schema, alias) {
-        return new LeftJoinCriteria(schema, alias);
+    static GetLeftJoinCriteria(schema) {
+        return new LeftJoinCriteria(schema);
     }
     /**
      * Creates an instance of `OuterJoinCriteria`. Used to define a `FULL OUTER JOIN` in a query.
@@ -70,8 +70,8 @@ export class CriteriaFactory {
      *
      * const profileJoinCriteria = CriteriaFactory.GetOuterJoinCriteria(ProfileSchema, 'profiles');
      */
-    static GetOuterJoinCriteria(schema, alias) {
-        return new OuterJoinCriteria(schema, alias);
+    static GetOuterJoinCriteria(schema) {
+        return new OuterJoinCriteria(schema);
     }
 }
 //# sourceMappingURL=criteria-factory.js.map

package/dist/criteria/criteria-factory.js.map

@@ -1 +1 @@
-{"version":3,"file":"criteria-factory.js","sourceRoot":"","sources":["../../src/criteria/criteria-factory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAElE;;;;GAIG;AACH,MAAM,OAAO,eAAe;IAC1B;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,WAAW,CAGhB,MAAe,EAAE,KAAY;QAC7B,OAAO,IAAI,YAAY,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACzC,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,oBAAoB,CAGzB,MAAe,EAAE,KAAY;QAC7B,OAAO,IAAI,iBAAiB,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAC9C,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,mBAAmB,CAGxB,MAAe,EAAE,KAAY;QAC7B,OAAO,IAAI,gBAAgB,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAC7C,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,oBAAoB,CAGzB,MAAe,EAAE,KAAY;QAC7B,OAAO,IAAI,iBAAiB,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAC9C,CAAC;CACF"}
+{"version":3,"file":"criteria-factory.js","sourceRoot":"","sources":["../../src/criteria/criteria-factory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAGlE;;;;GAIG;AACH,MAAM,OAAO,eAAe;IAC1B;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,WAAW,CAChB,MAA4B;QAE5B,OAAO,IAAI,YAAY,CAAC,MAAM,CAAC,CAAC;IAClC,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,oBAAoB,CACzB,MAA4B;QAE5B,OAAO,IAAI,iBAAiB,CAAC,MAAM,CAAC,CAAC;IACvC,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,mBAAmB,CACxB,MAA4B;QAE5B,OAAO,IAAI,gBAAgB,CAAC,MAAM,CAAC,CAAC;IACtC,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,oBAAoB,CACzB,MAA4B;QAE5B,OAAO,IAAI,iBAAiB,CAAC,MAAM,CAAC,CAAC;IACvC,CAAC;CACF"}

package/dist/criteria/criteria-join-manager.js.map

@@ -1 +1 @@
-{"version":3,"file":"criteria-join-manager.js","sourceRoot":"","sources":["../../src/criteria/criteria-join-manager.ts"],"names":[],"mappings":"AAQA,MAAM,OAAO,mBAAmB;IAGtB,MAAM,GAA4C,IAAI,GAAG,EAAE,CAAC;IAEpE,OAAO,CACL,cAA2C,EAC3C,aAEqD;QAErD,MAAM,WAAW,GAA+B;YAC9C,UAAU,EAAE,aAAa;YACzB,QAAQ,EAAE,cAAc;SACzB,CAAC;QAEF,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,cAAc,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC;IACrD,CAAC;IAED,QAAQ;QACN,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IAC1C,CAAC;CACF"}
+{"version":3,"file":"criteria-join-manager.js","sourceRoot":"","sources":["../../src/criteria/criteria-join-manager.ts"],"names":[],"mappings":"AAQA,MAAM,OAAO,mBAAmB;IAGtB,MAAM,GAA4C,IAAI,GAAG,EAAE,CAAC;IAEpE,OAAO,CACL,cAA2C,EAC3C,aAEqD;QAErD,MAAM,WAAW,GAA+B;YAC9C,UAAU,EAAE,aAAa;YACzB,QAAQ,EAAE,cAAiD;SAC5D,CAAC;QAEF,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,cAAc,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC;IACrD,CAAC;IAED,QAAQ;QACN,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IAC1C,CAAC;CACF"}

package/dist/criteria/criteria.d.ts

@@ -1,36 +1,137 @@
-import type { CriteriaSchema, FieldOfSchema, SelectedAliasOf } from './types/schema.types.js';
+import type { CriteriaSchema, FieldOfSchema } from './types/schema.types.js';
 import { Cursor } from './cursor.js';
 import { Order, OrderDirection } from './order/order.js';
 import type { FilterPrimitive } from './filter/types/filter-primitive.types.js';
 import type { ICriteriaBase } from './types/criteria.interface.js';
-import type { JoinCriteriaParameterType, JoinParameterType, SpecificMatchingJoinConfig } from './types/join-utility.types.js';
+import type { JoinCriteriaType, StoredJoinDetails } from './types/join-utility.types.js';
 import { FilterOperator } from './types/operator.types.js';
-export declare abstract class Criteria<TSchema extends CriteriaSchema, CurrentAlias extends SelectedAliasOf<TSchema> = SelectedAliasOf<TSchema>> implements ICriteriaBase<TSchema, CurrentAlias> {
-    protected readonly schema: TSchema;
-    protected _alias: CurrentAlias;
+import type { FilterGroup } from './filter/filter-group.js';
+export type ValidSchema<CSchema extends CriteriaSchema> = CSchema['identifier_field'] extends CSchema['fields'][number] ? CSchema : `Schema identifier_field '${CSchema['identifier_field']}' must be one of the schema's defined fields. Schema: ${CSchema['source_name']}`;
+/**
+ * Abstract base class for constructing query criteria.
+ * It provides a fluent API for defining filters, joins, selections, ordering, and pagination.
+ * Concrete criteria types (e.g., RootCriteria, JoinCriteria) will extend this class.
+ *
+ * @template TSchema - The schema definition for the entity this criteria operates on.
+ */
+export declare abstract class Criteria<const TSchema extends CriteriaSchema> implements ICriteriaBase<TSchema> {
     private readonly _filterManager;
     private readonly _joinManager;
     private readonly _source_name;
     private _take;
+    /**
+     * Stores the set of fields explicitly selected by the user.
+     * This is used when `_selectAll` is false.
+     * @protected
+     */
     protected _select: Set<FieldOfSchema<TSchema>>;
     private _selectAll;
+    /**
+     * Stores the cursor configuration for pagination, if set.
+     * @protected
+     */
     protected _cursor: Cursor<FieldOfSchema<TSchema>, FilterOperator.GREATER_THAN | FilterOperator.LESS_THAN> | undefined;
-    constructor(schema: TSchema, _alias: CurrentAlias);
-    get select(): FieldOfSchema<TSchema>[];
-    abstract resetCriteria(): ICriteriaBase<TSchema, CurrentAlias>;
+    protected readonly _schema: TSchema;
+    /**
+     * Initializes a new instance of the Criteria class.
+     * @param {ValidSchema<TSchema>} schema - The schema definition for the entity.
+     * @throws {Error} If the schema's identifier_field is not one of its defined fields.
+     * @protected
+     */
+    constructor(schema: ValidSchema<TSchema>);
+    get schema(): TSchema;
+    /**
+     * Gets the metadata associated with the root schema of this criteria.
+     * @returns {TSchema['metadata']} The metadata object from the schema, which can be undefined.
+     * @remarks This is intended primarily for use by translators.
+     */
+    get schemaMetadata(): TSchema['metadata'];
+    /**
+     * Gets the name of the identifier field for the current schema.
+     * @returns {FieldOfSchema<TSchema>} The name of the identifier field.
+     */
+    get identifierField(): FieldOfSchema<TSchema>;
+    /**
+     * Gets the currently selected fields.
+     * If `_selectAll` is true (default or after `resetSelect()`), it returns all fields from the schema.
+     * If `_selectAll` is false (after `setSelect()`), it returns the fields explicitly set by the user,
+     * plus the schema's `identifier_field` (which is added implicitly by `setSelect`).
+     * @returns {Array<FieldOfSchema<TSchema>>} An array of selected field names.
+     */
+    get select(): Array<FieldOfSchema<TSchema>>;
+    /**
+     * Resets the selection to include all fields from the schema.
+     * Later calls to `get select()` will return all schema fields
+     * until `setSelect()` is called again.
+     * @returns {this} The current criteria instance for chaining.
+     */
     resetSelect(): this;
+    /**
+     * Indicates whether all fields are currently configured to be selected.
+     * @returns {boolean} True if all fields are selected, false if specific fields are selected.
+     */
     get selectAll(): boolean;
+    /**
+     * Specifies which fields to select for the entity.
+     * Calling this method sets `selectAll` to false.
+     * The schema's `identifier_field` will always be included in the selection
+     * if it's not already present in `selectFields`.
+     * If `selectFields` is empty, only the `identifier_field` will be selected.
+     * @param {Array<FieldOfSchema<TSchema>>} selectFields - An array of field names to select.
+     * @returns {this} The current criteria instance for chaining.
+     * @throws {Error} If any of the specified fields are not defined in the schema.
+     */
     setSelect(selectFields: Array<FieldOfSchema<TSchema>>): this;
+    /**
+     * Gets the maximum number of records to return (LIMIT).
+     * @returns {number} The take value.
+     */
     get take(): number;
     private _skip;
+    /**
+     * Gets the number of records to skip (OFFSET).
+     * @returns {number} The skip value.
+     */
     get skip(): number;
     private _orders;
+    /**
+     * Gets the current ordering rules applied to this criteria.
+     * @returns {ReadonlyArray<Order<FieldOfSchema<TSchema>>>} A readonly array of order objects.
+     */
     get orders(): ReadonlyArray<Order<FieldOfSchema<TSchema>>>;
-    get joins(): import("./types/join-utility.types.js").StoredJoinDetails<TSchema>[];
-    get rootFilterGroup(): import("./index.js").FilterGroup<string>;
-    get sourceName(): TSchema["source_name"];
-    get alias(): CurrentAlias;
+    /**
+     * Gets the configured join details for this criteria.
+     * @returns {ReadonlyArray<StoredJoinDetails<TSchema>>} A readonly array of join configurations.
+     */
+    get joins(): ReadonlyArray<StoredJoinDetails<TSchema>>;
+    /**
+     * Gets the root filter group for this criteria, which holds all filter conditions.
+     * @returns {FilterGroup} The root filter group.
+     */
+    get rootFilterGroup(): FilterGroup;
+    /**
+     * Gets the source name (e.g., table name) for the entity of this criteria.
+     * @returns {TSchema['source_name']} The source name string.
+     */
+    get sourceName(): TSchema['source_name'];
+    /**
+     * Gets the alias used for the entity of this criteria.
+     * @returns {CurrentAlias} The alias string.
+     */
+    get alias(): TSchema['alias'];
+    /**
+     * Sets the maximum number of records to return (LIMIT).
+     * @param {number} amount - The number of records to take. Must be non-negative.
+     * @returns {this} The current criteria instance for chaining.
+     * @throws {Error} If the amount is negative.
+     */
     setTake(amount: number): this;
+    /**
+     * Sets the number of records to skip before starting to return records (OFFSET).
+     * @param {number} amount - The number of records to skip. Must be non-negative.
+     * @returns {this} The current criteria instance for chaining.
+     * @throws {Error} If the amount is negative.
+     */
     setSkip(amount: number): this;
     /**
      * Asserts that a given field name is defined within the current criteria's schema.
@@ -41,19 +142,89 @@ export declare abstract class Criteria<TSchema extends CriteriaSchema, CurrentAl
      * @param {FieldOfSchema<TSchema>} field - The field name to validate.
      * @throws {Error} If the field is not defined in the schema.
      */
-    protected assetFieldOnSchema(field: FieldOfSchema<TSchema>): void;
-    orderBy(field: FieldOfSchema<TSchema>, direction: OrderDirection): this;
+    protected assetFieldOnSchema(field: TSchema['fields'][number]): void;
+    /**
+     * Adds an ordering rule to the criteria.
+     * Multiple calls will append new ordering rules.
+     * @param {FieldOfSchema<TSchema>} field - The field to order by.
+     * @param {OrderDirection} direction - The direction of the ordering (ASC or DESC).
+     * @param {boolean} [nullFirst=false] - If true, null values will be ordered first.
+     * @returns {this} The current criteria instance for chaining.
+     * @throws {Error} If the specified field is not defined in the schema.
+     */
+    orderBy(field: FieldOfSchema<TSchema>, direction: OrderDirection, nullFirst?: boolean): this;
+    /**
+     * Initializes the filter criteria with a single filter primitive.
+     * This replaces any existing filters in the root filter group.
+     * @template Operator - The specific filter operator type.
+     * @param {FilterPrimitive<FieldOfSchema<TSchema>, Operator>} filterPrimitive - The filter to apply.
+     * @returns {this} The current criteria instance for chaining.
+     * @throws {Error} If the specified field in filterPrimitive is not defined in the schema.
+     */
     where<Operator extends FilterOperator>(filterPrimitive: FilterPrimitive<FieldOfSchema<TSchema>, Operator>): this;
+    /**
+     * Adds a filter primitive to the current filter group using an AND logical operator.
+     * Requires `where()` to have been called first to initialize the filter group.
+     * @template Operator - The specific filter operator type.
+     * @param {FilterPrimitive<FieldOfSchema<TSchema>, Operator>} filterPrimitive - The filter to add.
+     * @returns {this} The current criteria instance for chaining.
+     * @throws {Error} If the specified field in filterPrimitive is not defined in the schema.
+     * @throws {Error} If `where()` has not been called first.
+     */
     andWhere<Operator extends FilterOperator>(filterPrimitive: FilterPrimitive<FieldOfSchema<TSchema>, Operator>): this;
+    /**
+     * Adds a filter primitive to the current filter group using an OR logical operator.
+     * Requires `where()` to have been called first to initialize the filter group.
+     * @template Operator - The specific filter operator type.
+     * @param {FilterPrimitive<FieldOfSchema<TSchema>, Operator>} filterPrimitive - The filter to add.
+     * @returns {this} The current criteria instance for chaining.
+     * @throws {Error} If the specified field in filterPrimitive is not defined in the schema.
+     * @throws {Error} If `where()` has not been called first.
+     */
     orWhere<Operator extends FilterOperator>(filterPrimitive: FilterPrimitive<FieldOfSchema<TSchema>, Operator>): this;
-    join<TJoinSchema extends CriteriaSchema, TJoinedCriteriaAlias extends SelectedAliasOf<TJoinSchema>, TMatchingJoinConfig extends SpecificMatchingJoinConfig<TSchema, TJoinedCriteriaAlias>>(criteriaToJoin: JoinCriteriaParameterType<TSchema, TJoinSchema, TJoinedCriteriaAlias, TMatchingJoinConfig>, joinParameter: JoinParameterType<TSchema, TJoinSchema, TMatchingJoinConfig>): this;
-    private assertIsValidJoinOptions;
+    /**
+     * Adds a join to another criteria. This method is fully type-safe.
+     * The `joinAlias` argument provides autocompletion for all valid relation aliases defined in the schema.
+     * The `criteriaToJoin` argument is then validated to ensure its `source_name` matches the one
+     * configured for the chosen `joinAlias`, providing clear, compile-time error messages if they mismatch.
+     *
+     * @template TJoinSchema - The schema of the entity to join.
+     * @template SpecificRelationAlias - The literal type of the relation alias being used for the join.
+     * @param {SpecificRelationAlias} joinAlias - The specific alias defined in the parent schema's `relations` array for
+     *   this relation.
+     * @param {JoinCriteriaType<TSchema, TJoinSchema, SpecificRelationAlias>} criteriaToJoin - The criteria instance
+     *   representing the entity to join (e.g., `InnerJoinCriteria`).
+     * @param {boolean} [withSelect=true] - If true (default), the joined entity's fields will be included in the final
+     *   selection. If false, the join will only be used for filtering and its fields will not be selected.
+     * @returns {this} The current criteria instance for chaining.
+     */
+    join<const TJoinSchema extends CriteriaSchema, const SpecificRelationAlias extends TSchema['relations'][number]['relation_alias']>(joinAlias: SpecificRelationAlias, criteriaToJoin: JoinCriteriaType<TSchema, TJoinSchema, SpecificRelationAlias>, withSelect?: boolean): this;
+    /**
+     * Gets the current cursor configuration, if set.
+     * @returns {Cursor<FieldOfSchema<TSchema>, FilterOperator.GREATER_THAN | FilterOperator.LESS_THAN> | undefined}
+     * The cursor object or undefined.
+     */
     get cursor(): Cursor<FieldOfSchema<TSchema>, FilterOperator.GREATER_THAN | FilterOperator.LESS_THAN> | undefined;
+    /**
+     * Sets the cursor for pagination.
+     * @template Operator - The specific comparison operator for the cursor.
+     * @param {readonly [Omit<FilterPrimitive<FieldOfSchema<TSchema>, Operator>, 'operator'>] | readonly
+     *   [Omit<FilterPrimitive<FieldOfSchema<TSchema>, Operator>, 'operator'>,
+     *   Omit<FilterPrimitive<FieldOfSchema<TSchema>, Operator>, 'operator'>]} filterPrimitives - An array of one or two
+     *   filter primitives defining the cursor's fields and values.
+     * @param {Operator} operator - The comparison operator (GREATER_THAN or LESS_THAN).
+     * @param {OrderDirection} order - The primary order direction for pagination.
+     * @returns {this} The current criteria instance for chaining.
+     * @throws {Error} If filterPrimitives does not contain exactly 1 or 2 elements.
+     * @throws {Error} If any cursor field is not defined in the schema.
+     * @throws {Error} If any cursor value is undefined (null is allowed, per Cursor constructor).
+     * @throws {Error} If two cursor fields are provided and they are identical (per Cursor constructor).
+     */
     setCursor<Operator extends FilterOperator.GREATER_THAN | FilterOperator.LESS_THAN>(filterPrimitives: readonly [
         Omit<FilterPrimitive<FieldOfSchema<TSchema>, Operator>, 'operator'>
     ] | readonly [
         Omit<FilterPrimitive<FieldOfSchema<TSchema>, Operator>, 'operator'>,
         Omit<FilterPrimitive<FieldOfSchema<TSchema>, Operator>, 'operator'>
-    ], operator: Operator, order: OrderDirection): ICriteriaBase<TSchema, CurrentAlias>;
+    ], operator: Operator, order: OrderDirection): this;
 }
 //# sourceMappingURL=criteria.d.ts.map