bigal 15.3.0 → 15.4.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+# [15.4.0](https://github.com/bigalorm/bigal/compare/v15.3.0...v15.4.0) (2026-01-08)
+
+### Features
+
+- Add withCount() for efficient pagination with total count ([#266](https://github.com/bigalorm/bigal/issues/266)) ([233221e](https://github.com/bigalorm/bigal/commit/233221e7902af8ca3a4b24d1f60f0857bcd7803f))
+
 # [15.3.0](https://github.com/bigalorm/bigal/compare/v15.2.0...v15.3.0) (2026-01-08)
 
 ### Features

package/README.md

@@ -325,14 +325,109 @@ const item = await ProductRepository.find({
 });
 ```
 
-#### Example of an OR statement
+#### String matching operators
+
+BigAl provides four string matching operators. All use case-insensitive matching (PostgreSQL `ILIKE`) and accept arrays for OR matching.
+
+| Operator     | Description                                   | SQL Pattern |
+| ------------ | --------------------------------------------- | ----------- |
+| `like`       | Raw ILIKE pattern with your own `%` wildcards | As provided |
+| `contains`   | Substring match anywhere in the string        | `%value%`   |
+| `startsWith` | Matches strings starting with the value       | `value%`    |
+| `endsWith`   | Matches strings ending with the value         | `%value`    |
 
 ```ts
+const items = await ProductRepository.find().where({
+  name: { contains: 'widget' },
+});
+// SQL: SELECT ... FROM product WHERE name ILIKE '%widget%'
+
+const items = await ProductRepository.find().where({
+  name: { startsWith: 'Pro' },
+});
+// SQL: SELECT ... FROM product WHERE name ILIKE 'Pro%'
+
+const items = await ProductRepository.find().where({
+  name: { endsWith: 'ter' },
+});
+// SQL: SELECT ... FROM product WHERE name ILIKE '%ter'
+
+const items = await ProductRepository.find().where({
+  name: { like: 'Pro%Widget%' },
+});
+// SQL: SELECT ... FROM product WHERE name ILIKE 'Pro%Widget%'
+
+// Arrays create OR conditions
 const items = await PersonRepository.find().where({
-  firstName: {
-    like: ['walter', 'Jess%'],
-  },
+  firstName: { like: ['walter', 'Jess%'] },
+});
+// SQL: SELECT ... FROM person WHERE (first_name ILIKE 'walter' OR first_name ILIKE 'Jess%')
+```
+
+#### Comparison operators
+
+For number and date fields, use comparison operators:
+
+| Operator | Description              |
+| -------- | ------------------------ |
+| `<`      | Less than                |
+| `<=`     | Less than or equal to    |
+| `>`      | Greater than             |
+| `>=`     | Greater than or equal to |
+
+```ts
+const items = await ProductRepository.find().where({
+  price: { '>=': 100 },
+});
+// SQL: SELECT ... FROM product WHERE price >= $1
+
+// Multiple operators on same field create AND
+const items = await ProductRepository.find().where({
+  createdAt: { '>=': startDate, '<': endDate },
+});
+// SQL: SELECT ... FROM product WHERE created_at >= $1 AND created_at < $2
+```
+
+#### Array values (OR conditions)
+
+When you pass an array of values, BigAl creates an OR condition:
+
+```ts
+const items = await PersonRepository.find().where({
+  age: [22, 23, 24],
+});
+// SQL: SELECT ... FROM person WHERE age IN ($1, $2, $3)
+
+const items = await ProductRepository.find().where({
+  name: { startsWith: ['Pro', 'Pre'] },
+});
+// SQL: SELECT ... FROM product WHERE (name ILIKE 'Pro%' OR name ILIKE 'Pre%')
+```
+
+#### Negation operator (`!`)
+
+Use `!` to negate any condition:
+
+```ts
+const items = await ProductRepository.find().where({
+  status: { '!': 'discontinued' },
+});
+// SQL: SELECT ... FROM product WHERE status <> $1
+
+const items = await ProductRepository.find().where({
+  status: { '!': ['discontinued', 'archived'] },
+});
+// SQL: SELECT ... FROM product WHERE status NOT IN ($1, $2)
+
+const items = await ProductRepository.find().where({
+  name: { '!': { startsWith: 'Test' } },
 });
+// SQL: SELECT ... FROM product WHERE name NOT ILIKE 'Test%'
+
+const items = await ProductRepository.find().where({
+  deletedAt: { '!': null },
+});
+// SQL: SELECT ... FROM product WHERE deleted_at IS NOT NULL
 ```
 
 #### Example of an AND statement
@@ -392,22 +487,28 @@ Equivalent to:
 select * from person where ((first_name = $1) OR (last_name = $2)) AND ((first_name = $3) OR (last_name = $4))
 ```
 
-#### Fetch multiple objects and perform a db sort before returning result
+#### Sorting results
+
+Use `.sort()` to order results. Two syntax options are available:
+
+**String syntax** - Use `asc` or `desc` (comma-separated for multiple columns):
 
 ```ts
-const items = await PersonRepository.find()
-  .where({
-    firstName: {
-      like: 'walter',
-    },
-    lastName: {
-      like: 'white',
-    },
-  })
-  .sort({
-    age: 1,
-    occupation: -1,
-  });
+const items = await PersonRepository.find().where({ lastName: 'Smith' }).sort('age asc');
+// SQL: SELECT ... FROM person WHERE last_name = $1 ORDER BY age ASC
+
+const items = await PersonRepository.find().where({ lastName: 'Smith' }).sort('age asc, createdAt desc');
+// SQL: SELECT ... FROM person WHERE last_name = $1 ORDER BY age ASC, created_at DESC
+```
+
+**Object syntax** - Use `1` for ascending, `-1` for descending:
+
+```ts
+const items = await PersonRepository.find().where({ lastName: 'Smith' }).sort({ age: 1 });
+// SQL: SELECT ... FROM person WHERE last_name = $1 ORDER BY age ASC
+
+const items = await PersonRepository.find().where({ lastName: 'Smith' }).sort({ age: 1, createdAt: -1 });
+// SQL: SELECT ... FROM person WHERE last_name = $1 ORDER BY age ASC, created_at DESC
 ```
 
 #### Limit number results returned
@@ -460,6 +561,34 @@ const items = await FooRepository.find()
   .paginate(page, pageSize);
 ```
 
+#### Page results with total count using `withCount`
+
+Use `.withCount()` to get both paginated results and the total count of matching records in a single query. This uses PostgreSQL's `COUNT(*) OVER()` window function for efficient execution.
+
+```ts
+const { results, totalCount } = await ProductRepository.find()
+  .where({
+    store: storeId,
+  })
+  .sort('name')
+  .limit(10)
+  .skip(20)
+  .withCount();
+
+// results: Product[] (10 items from offset 20)
+// totalCount: number (total matching products, ignoring LIMIT/OFFSET)
+```
+
+This is useful for building paginated UIs where you need to display total pages:
+
+```ts
+const page = 3;
+const pageSize = 25;
+const { results, totalCount } = await ProductRepository.find().where({ isActive: true }).paginate({ page, limit: pageSize }).withCount();
+
+const totalPages = Math.ceil(totalCount / pageSize);
+```
+
 #### Join related tables
 
 Use `join()` for INNER JOIN or `leftJoin()` for LEFT JOIN to filter or sort by related table columns in a single query.

package/dist/index.cjs

@@ -445,13 +445,17 @@ function getSelectQueryAndParams({
   sorts,
   skip,
   limit,
-  joins
+  joins,
+  includeCount
 }) {
   let query = "SELECT ";
   query += getColumnsToSelect({
     model,
     select
   });
+  if (includeCount) {
+    query += ',count(*) OVER() AS "__total_count__"';
+  }
   query += ` FROM ${model.qualifiedTableName}`;
   const params = [];
   if (joins?.length) {
@@ -901,7 +905,7 @@ function buildJoinClauses({
     if (alias !== relatedModel.tableName) {
       joinSql += ` AS "${alias}"`;
     }
-    joinSql += ` ON ${model.qualifiedTableName}."${column.name}" = "${alias}"."${relatedPrimaryKey.name}"`;
+    joinSql += ` ON ${model.qualifiedTableName}."${column.name}"="${alias}"."${relatedPrimaryKey.name}"`;
     if (join.on) {
       for (const [propertyName, value] of Object.entries(join.on)) {
         const onColumn = relatedModel.columnsByPropertyName[propertyName];
@@ -2145,6 +2149,7 @@ ${stack ?? ""}`;
     const populates = [];
     const sorts = sort ? this._convertSortsToOrderBy(sort) : [];
     const joins = [];
+    let includeCount = false;
     const modelInstance = this;
     return {
       /**
@@ -2255,6 +2260,10 @@ ${stack ?? ""}`;
         const safePage = Math.max(page, 1);
         return this.skip(safePage * paginateLimit - paginateLimit).limit(paginateLimit);
       },
+      withCount() {
+        includeCount = true;
+        return this;
+      },
       async then(resolve, reject) {
         try {
           if (typeof where === "string") {
@@ -2268,14 +2277,29 @@ ${stack ?? ""}`;
             sorts,
             skip: skip ?? 0,
             limit: limit ?? 0,
-            joins
+            joins,
+            includeCount
           });
           const pool = poolOverride ?? modelInstance._readonlyPool;
           const results = await pool.query(query, params);
-          const entities = modelInstance._buildInstances(results.rows);
+          let totalCount = 0;
+          if (includeCount && results.rows.length > 0 && results.rows[0]?.__total_count__ !== void 0) {
+            totalCount = Number(results.rows[0].__total_count__);
+          }
+          const rows = includeCount ? results.rows.map((row) => {
+            const { __total_count__, ...rest } = row;
+            return rest;
+          }) : results.rows;
+          const entities = modelInstance._buildInstances(rows);
           if (populates.length) {
             await modelInstance.populateFields(entities, populates);
           }
+          if (includeCount) {
+            return await resolve({
+              results: entities,
+              totalCount
+            });
+          }
           return await resolve(entities);
         } catch (ex) {
           const typedException = ex;

package/dist/index.d.cts

@@ -569,6 +569,22 @@ interface PaginateOptions {
     page: number;
 }
 
+interface FindWithCountResult<TReturn> {
+    results: TReturn[];
+    totalCount: number;
+}
+interface FindQueryWithCount<T extends Entity, TReturn, TJoins extends JoinInfo = never> extends PromiseLike<FindWithCountResult<TReturn>> {
+    select<TKeys extends string & keyof T>(keys: TKeys[]): FindQueryWithCount<T, Pick<T, TKeys>, TJoins>;
+    where(args: JoinedWhereQuery<T, TJoins>): FindQueryWithCount<T, TReturn, TJoins>;
+    populate<TProperty extends string & keyof PickByValueType<T, Entity> & keyof T, TPopulateType extends GetValueType<T[TProperty], Entity>, TPopulateSelectKeys extends string & keyof TPopulateType>(propertyName: TProperty, options?: PopulateArgs<TPopulateType, TPopulateSelectKeys>): FindQueryWithCount<T, Omit<TReturn, TProperty> & Populated<T, TProperty, TPopulateType, TPopulateSelectKeys>, TJoins>;
+    join<TProperty extends ModelRelationshipKeys<T>, TAlias extends string = TProperty>(propertyName: TProperty, alias?: TAlias): FindQueryWithCount<T, TReturn, JoinInfo<TProperty, TAlias, GetValueType<T[TProperty], Entity>> | TJoins>;
+    leftJoin<TProperty extends ModelRelationshipKeys<T>, TAlias extends string = TProperty>(propertyName: TProperty, alias?: TAlias, on?: WhereQuery<GetValueType<T[TProperty], Entity>>): FindQueryWithCount<T, TReturn, JoinInfo<TProperty, TAlias, GetValueType<T[TProperty], Entity>> | TJoins>;
+    sort(value?: JoinedSort<T, TJoins>): FindQueryWithCount<T, TReturn, TJoins>;
+    limit(value: number): FindQueryWithCount<T, TReturn, TJoins>;
+    skip(value: number): FindQueryWithCount<T, TReturn, TJoins>;
+    paginate(options: PaginateOptions): FindQueryWithCount<T, TReturn, TJoins>;
+}
+
 interface FindResult<T extends Entity, TReturn, TJoins extends JoinInfo = never> extends PromiseLike<TReturn[]> {
     select<TKeys extends string & keyof T>(keys: TKeys[]): FindResult<T, Pick<T, TKeys>, TJoins>;
     where(args: JoinedWhereQuery<T, TJoins>): FindResult<T, TReturn, TJoins>;
@@ -579,6 +595,7 @@ interface FindResult<T extends Entity, TReturn, TJoins extends JoinInfo = never>
     limit(value: number): FindResult<T, TReturn, TJoins>;
     skip(value: number): FindResult<T, TReturn, TJoins>;
     paginate(options: PaginateOptions): FindResult<T, TReturn, TJoins>;
+    withCount(): FindQueryWithCount<T, TReturn, TJoins>;
     UNSAFE_withOriginalFieldType<TProperty extends string & keyof PickByValueType<T, Entity> & keyof T>(propertyName: TProperty): FindResult<T, Omit<TReturn, TProperty> & Pick<T, TProperty>, TJoins>;
 }
 
@@ -1029,4 +1046,4 @@ interface InitializeOptions extends IConnection {
 declare function initialize({ models, pool, readonlyPool, connections, expose }: InitializeOptions): Record<string, IReadonlyRepository<Entity> | IRepository<Entity>>;
 
 export { ColumnBaseMetadata, ColumnCollectionMetadata, ColumnModelMetadata, ColumnTypeMetadata, Entity, ModelMetadata, QueryError, ReadonlyRepository, Repository, ScalarSubquery, SubqueryBuilder, column, createDateColumn, getMetadataStorage, initialize, primaryColumn, subquery, table, updateDateColumn, versionColumn };
-export type { ClassLike, ColumnBaseMetadataOptions, ColumnCollectionMetadataOptions, ColumnMetadata, ColumnModelMetadataOptions, ColumnModifierMetadata, ColumnTypeMetadataOptions, Comparer, CountResult, CreateUpdateOptions, CreateUpdateParams, DeleteOptions, DestroyResult, DoNotReturnRecords, EntityFieldValue, EntityPrimitiveOrId, EntityStatic, ExcludeEntityCollections, ExcludeFunctions, FindArgs, FindOneArgs, FindOneResult, FindResult, GetValueType, IConnection, IReadonlyRepository, IRepository, IRepositoryOptions, IncludeFunctions, InitializeOptions, IsValueOfType, JoinDefinition, JoinInfo, JoinType, JoinedSort, JoinedWhereQuery, LiteralValues, ModelMetadataOptions, ModelRelationshipKeys, MultipleSortString, NegatableConstraint, NotEntity, NotEntityBrand, NumberOrDateConstraint, NumberOrDateConstraintWithSubquery, OmitEntityCollections, OmitFunctions, OrderBy, PaginateOptions, PickAsType, PickByValueType, PickFunctions, PoolLike, PoolQueryResult, PopulateArgs, Populated, QueryResult, QueryResultOptionalPopulated, QueryResultPopulated, QueryResultRow, ReturnSelect$1 as ReturnSelect, ScalarSubqueryConstraint, Sort, SortObject, SortObjectValue, SortString, StringConstraint, SubqueryBuilderLike, SubqueryInConstraint, WhereClauseValue, WhereQuery, WhereQueryStatement };
+export type { ClassLike, ColumnBaseMetadataOptions, ColumnCollectionMetadataOptions, ColumnMetadata, ColumnModelMetadataOptions, ColumnModifierMetadata, ColumnTypeMetadataOptions, Comparer, CountResult, CreateUpdateOptions, CreateUpdateParams, DeleteOptions, DestroyResult, DoNotReturnRecords, EntityFieldValue, EntityPrimitiveOrId, EntityStatic, ExcludeEntityCollections, ExcludeFunctions, FindArgs, FindOneArgs, FindOneResult, FindQueryWithCount, FindResult, FindWithCountResult, GetValueType, IConnection, IReadonlyRepository, IRepository, IRepositoryOptions, IncludeFunctions, InitializeOptions, IsValueOfType, JoinDefinition, JoinInfo, JoinType, JoinedSort, JoinedWhereQuery, LiteralValues, ModelMetadataOptions, ModelRelationshipKeys, MultipleSortString, NegatableConstraint, NotEntity, NotEntityBrand, NumberOrDateConstraint, NumberOrDateConstraintWithSubquery, OmitEntityCollections, OmitFunctions, OrderBy, PaginateOptions, PickAsType, PickByValueType, PickFunctions, PoolLike, PoolQueryResult, PopulateArgs, Populated, QueryResult, QueryResultOptionalPopulated, QueryResultPopulated, QueryResultRow, ReturnSelect$1 as ReturnSelect, ScalarSubqueryConstraint, Sort, SortObject, SortObjectValue, SortString, StringConstraint, SubqueryBuilderLike, SubqueryInConstraint, WhereClauseValue, WhereQuery, WhereQueryStatement };

package/dist/index.d.mts

@@ -569,6 +569,22 @@ interface PaginateOptions {
     page: number;
 }
 
+interface FindWithCountResult<TReturn> {
+    results: TReturn[];
+    totalCount: number;
+}
+interface FindQueryWithCount<T extends Entity, TReturn, TJoins extends JoinInfo = never> extends PromiseLike<FindWithCountResult<TReturn>> {
+    select<TKeys extends string & keyof T>(keys: TKeys[]): FindQueryWithCount<T, Pick<T, TKeys>, TJoins>;
+    where(args: JoinedWhereQuery<T, TJoins>): FindQueryWithCount<T, TReturn, TJoins>;
+    populate<TProperty extends string & keyof PickByValueType<T, Entity> & keyof T, TPopulateType extends GetValueType<T[TProperty], Entity>, TPopulateSelectKeys extends string & keyof TPopulateType>(propertyName: TProperty, options?: PopulateArgs<TPopulateType, TPopulateSelectKeys>): FindQueryWithCount<T, Omit<TReturn, TProperty> & Populated<T, TProperty, TPopulateType, TPopulateSelectKeys>, TJoins>;
+    join<TProperty extends ModelRelationshipKeys<T>, TAlias extends string = TProperty>(propertyName: TProperty, alias?: TAlias): FindQueryWithCount<T, TReturn, JoinInfo<TProperty, TAlias, GetValueType<T[TProperty], Entity>> | TJoins>;
+    leftJoin<TProperty extends ModelRelationshipKeys<T>, TAlias extends string = TProperty>(propertyName: TProperty, alias?: TAlias, on?: WhereQuery<GetValueType<T[TProperty], Entity>>): FindQueryWithCount<T, TReturn, JoinInfo<TProperty, TAlias, GetValueType<T[TProperty], Entity>> | TJoins>;
+    sort(value?: JoinedSort<T, TJoins>): FindQueryWithCount<T, TReturn, TJoins>;
+    limit(value: number): FindQueryWithCount<T, TReturn, TJoins>;
+    skip(value: number): FindQueryWithCount<T, TReturn, TJoins>;
+    paginate(options: PaginateOptions): FindQueryWithCount<T, TReturn, TJoins>;
+}
+
 interface FindResult<T extends Entity, TReturn, TJoins extends JoinInfo = never> extends PromiseLike<TReturn[]> {
     select<TKeys extends string & keyof T>(keys: TKeys[]): FindResult<T, Pick<T, TKeys>, TJoins>;
     where(args: JoinedWhereQuery<T, TJoins>): FindResult<T, TReturn, TJoins>;
@@ -579,6 +595,7 @@ interface FindResult<T extends Entity, TReturn, TJoins extends JoinInfo = never>
     limit(value: number): FindResult<T, TReturn, TJoins>;
     skip(value: number): FindResult<T, TReturn, TJoins>;
     paginate(options: PaginateOptions): FindResult<T, TReturn, TJoins>;
+    withCount(): FindQueryWithCount<T, TReturn, TJoins>;
     UNSAFE_withOriginalFieldType<TProperty extends string & keyof PickByValueType<T, Entity> & keyof T>(propertyName: TProperty): FindResult<T, Omit<TReturn, TProperty> & Pick<T, TProperty>, TJoins>;
 }
 
@@ -1029,4 +1046,4 @@ interface InitializeOptions extends IConnection {
 declare function initialize({ models, pool, readonlyPool, connections, expose }: InitializeOptions): Record<string, IReadonlyRepository<Entity> | IRepository<Entity>>;
 
 export { ColumnBaseMetadata, ColumnCollectionMetadata, ColumnModelMetadata, ColumnTypeMetadata, Entity, ModelMetadata, QueryError, ReadonlyRepository, Repository, ScalarSubquery, SubqueryBuilder, column, createDateColumn, getMetadataStorage, initialize, primaryColumn, subquery, table, updateDateColumn, versionColumn };
-export type { ClassLike, ColumnBaseMetadataOptions, ColumnCollectionMetadataOptions, ColumnMetadata, ColumnModelMetadataOptions, ColumnModifierMetadata, ColumnTypeMetadataOptions, Comparer, CountResult, CreateUpdateOptions, CreateUpdateParams, DeleteOptions, DestroyResult, DoNotReturnRecords, EntityFieldValue, EntityPrimitiveOrId, EntityStatic, ExcludeEntityCollections, ExcludeFunctions, FindArgs, FindOneArgs, FindOneResult, FindResult, GetValueType, IConnection, IReadonlyRepository, IRepository, IRepositoryOptions, IncludeFunctions, InitializeOptions, IsValueOfType, JoinDefinition, JoinInfo, JoinType, JoinedSort, JoinedWhereQuery, LiteralValues, ModelMetadataOptions, ModelRelationshipKeys, MultipleSortString, NegatableConstraint, NotEntity, NotEntityBrand, NumberOrDateConstraint, NumberOrDateConstraintWithSubquery, OmitEntityCollections, OmitFunctions, OrderBy, PaginateOptions, PickAsType, PickByValueType, PickFunctions, PoolLike, PoolQueryResult, PopulateArgs, Populated, QueryResult, QueryResultOptionalPopulated, QueryResultPopulated, QueryResultRow, ReturnSelect$1 as ReturnSelect, ScalarSubqueryConstraint, Sort, SortObject, SortObjectValue, SortString, StringConstraint, SubqueryBuilderLike, SubqueryInConstraint, WhereClauseValue, WhereQuery, WhereQueryStatement };
+export type { ClassLike, ColumnBaseMetadataOptions, ColumnCollectionMetadataOptions, ColumnMetadata, ColumnModelMetadataOptions, ColumnModifierMetadata, ColumnTypeMetadataOptions, Comparer, CountResult, CreateUpdateOptions, CreateUpdateParams, DeleteOptions, DestroyResult, DoNotReturnRecords, EntityFieldValue, EntityPrimitiveOrId, EntityStatic, ExcludeEntityCollections, ExcludeFunctions, FindArgs, FindOneArgs, FindOneResult, FindQueryWithCount, FindResult, FindWithCountResult, GetValueType, IConnection, IReadonlyRepository, IRepository, IRepositoryOptions, IncludeFunctions, InitializeOptions, IsValueOfType, JoinDefinition, JoinInfo, JoinType, JoinedSort, JoinedWhereQuery, LiteralValues, ModelMetadataOptions, ModelRelationshipKeys, MultipleSortString, NegatableConstraint, NotEntity, NotEntityBrand, NumberOrDateConstraint, NumberOrDateConstraintWithSubquery, OmitEntityCollections, OmitFunctions, OrderBy, PaginateOptions, PickAsType, PickByValueType, PickFunctions, PoolLike, PoolQueryResult, PopulateArgs, Populated, QueryResult, QueryResultOptionalPopulated, QueryResultPopulated, QueryResultRow, ReturnSelect$1 as ReturnSelect, ScalarSubqueryConstraint, Sort, SortObject, SortObjectValue, SortString, StringConstraint, SubqueryBuilderLike, SubqueryInConstraint, WhereClauseValue, WhereQuery, WhereQueryStatement };

package/dist/index.d.ts

@@ -569,6 +569,22 @@ interface PaginateOptions {
     page: number;
 }
 
+interface FindWithCountResult<TReturn> {
+    results: TReturn[];
+    totalCount: number;
+}
+interface FindQueryWithCount<T extends Entity, TReturn, TJoins extends JoinInfo = never> extends PromiseLike<FindWithCountResult<TReturn>> {
+    select<TKeys extends string & keyof T>(keys: TKeys[]): FindQueryWithCount<T, Pick<T, TKeys>, TJoins>;
+    where(args: JoinedWhereQuery<T, TJoins>): FindQueryWithCount<T, TReturn, TJoins>;
+    populate<TProperty extends string & keyof PickByValueType<T, Entity> & keyof T, TPopulateType extends GetValueType<T[TProperty], Entity>, TPopulateSelectKeys extends string & keyof TPopulateType>(propertyName: TProperty, options?: PopulateArgs<TPopulateType, TPopulateSelectKeys>): FindQueryWithCount<T, Omit<TReturn, TProperty> & Populated<T, TProperty, TPopulateType, TPopulateSelectKeys>, TJoins>;
+    join<TProperty extends ModelRelationshipKeys<T>, TAlias extends string = TProperty>(propertyName: TProperty, alias?: TAlias): FindQueryWithCount<T, TReturn, JoinInfo<TProperty, TAlias, GetValueType<T[TProperty], Entity>> | TJoins>;
+    leftJoin<TProperty extends ModelRelationshipKeys<T>, TAlias extends string = TProperty>(propertyName: TProperty, alias?: TAlias, on?: WhereQuery<GetValueType<T[TProperty], Entity>>): FindQueryWithCount<T, TReturn, JoinInfo<TProperty, TAlias, GetValueType<T[TProperty], Entity>> | TJoins>;
+    sort(value?: JoinedSort<T, TJoins>): FindQueryWithCount<T, TReturn, TJoins>;
+    limit(value: number): FindQueryWithCount<T, TReturn, TJoins>;
+    skip(value: number): FindQueryWithCount<T, TReturn, TJoins>;
+    paginate(options: PaginateOptions): FindQueryWithCount<T, TReturn, TJoins>;
+}
+
 interface FindResult<T extends Entity, TReturn, TJoins extends JoinInfo = never> extends PromiseLike<TReturn[]> {
     select<TKeys extends string & keyof T>(keys: TKeys[]): FindResult<T, Pick<T, TKeys>, TJoins>;
     where(args: JoinedWhereQuery<T, TJoins>): FindResult<T, TReturn, TJoins>;
@@ -579,6 +595,7 @@ interface FindResult<T extends Entity, TReturn, TJoins extends JoinInfo = never>
     limit(value: number): FindResult<T, TReturn, TJoins>;
     skip(value: number): FindResult<T, TReturn, TJoins>;
     paginate(options: PaginateOptions): FindResult<T, TReturn, TJoins>;
+    withCount(): FindQueryWithCount<T, TReturn, TJoins>;
     UNSAFE_withOriginalFieldType<TProperty extends string & keyof PickByValueType<T, Entity> & keyof T>(propertyName: TProperty): FindResult<T, Omit<TReturn, TProperty> & Pick<T, TProperty>, TJoins>;
 }
 
@@ -1029,4 +1046,4 @@ interface InitializeOptions extends IConnection {
 declare function initialize({ models, pool, readonlyPool, connections, expose }: InitializeOptions): Record<string, IReadonlyRepository<Entity> | IRepository<Entity>>;
 
 export { ColumnBaseMetadata, ColumnCollectionMetadata, ColumnModelMetadata, ColumnTypeMetadata, Entity, ModelMetadata, QueryError, ReadonlyRepository, Repository, ScalarSubquery, SubqueryBuilder, column, createDateColumn, getMetadataStorage, initialize, primaryColumn, subquery, table, updateDateColumn, versionColumn };
-export type { ClassLike, ColumnBaseMetadataOptions, ColumnCollectionMetadataOptions, ColumnMetadata, ColumnModelMetadataOptions, ColumnModifierMetadata, ColumnTypeMetadataOptions, Comparer, CountResult, CreateUpdateOptions, CreateUpdateParams, DeleteOptions, DestroyResult, DoNotReturnRecords, EntityFieldValue, EntityPrimitiveOrId, EntityStatic, ExcludeEntityCollections, ExcludeFunctions, FindArgs, FindOneArgs, FindOneResult, FindResult, GetValueType, IConnection, IReadonlyRepository, IRepository, IRepositoryOptions, IncludeFunctions, InitializeOptions, IsValueOfType, JoinDefinition, JoinInfo, JoinType, JoinedSort, JoinedWhereQuery, LiteralValues, ModelMetadataOptions, ModelRelationshipKeys, MultipleSortString, NegatableConstraint, NotEntity, NotEntityBrand, NumberOrDateConstraint, NumberOrDateConstraintWithSubquery, OmitEntityCollections, OmitFunctions, OrderBy, PaginateOptions, PickAsType, PickByValueType, PickFunctions, PoolLike, PoolQueryResult, PopulateArgs, Populated, QueryResult, QueryResultOptionalPopulated, QueryResultPopulated, QueryResultRow, ReturnSelect$1 as ReturnSelect, ScalarSubqueryConstraint, Sort, SortObject, SortObjectValue, SortString, StringConstraint, SubqueryBuilderLike, SubqueryInConstraint, WhereClauseValue, WhereQuery, WhereQueryStatement };
+export type { ClassLike, ColumnBaseMetadataOptions, ColumnCollectionMetadataOptions, ColumnMetadata, ColumnModelMetadataOptions, ColumnModifierMetadata, ColumnTypeMetadataOptions, Comparer, CountResult, CreateUpdateOptions, CreateUpdateParams, DeleteOptions, DestroyResult, DoNotReturnRecords, EntityFieldValue, EntityPrimitiveOrId, EntityStatic, ExcludeEntityCollections, ExcludeFunctions, FindArgs, FindOneArgs, FindOneResult, FindQueryWithCount, FindResult, FindWithCountResult, GetValueType, IConnection, IReadonlyRepository, IRepository, IRepositoryOptions, IncludeFunctions, InitializeOptions, IsValueOfType, JoinDefinition, JoinInfo, JoinType, JoinedSort, JoinedWhereQuery, LiteralValues, ModelMetadataOptions, ModelRelationshipKeys, MultipleSortString, NegatableConstraint, NotEntity, NotEntityBrand, NumberOrDateConstraint, NumberOrDateConstraintWithSubquery, OmitEntityCollections, OmitFunctions, OrderBy, PaginateOptions, PickAsType, PickByValueType, PickFunctions, PoolLike, PoolQueryResult, PopulateArgs, Populated, QueryResult, QueryResultOptionalPopulated, QueryResultPopulated, QueryResultRow, ReturnSelect$1 as ReturnSelect, ScalarSubqueryConstraint, Sort, SortObject, SortObjectValue, SortString, StringConstraint, SubqueryBuilderLike, SubqueryInConstraint, WhereClauseValue, WhereQuery, WhereQueryStatement };

package/dist/index.mjs

@@ -443,13 +443,17 @@ function getSelectQueryAndParams({
   sorts,
   skip,
   limit,
-  joins
+  joins,
+  includeCount
 }) {
   let query = "SELECT ";
   query += getColumnsToSelect({
     model,
     select
   });
+  if (includeCount) {
+    query += ',count(*) OVER() AS "__total_count__"';
+  }
   query += ` FROM ${model.qualifiedTableName}`;
   const params = [];
   if (joins?.length) {
@@ -899,7 +903,7 @@ function buildJoinClauses({
     if (alias !== relatedModel.tableName) {
       joinSql += ` AS "${alias}"`;
     }
-    joinSql += ` ON ${model.qualifiedTableName}."${column.name}" = "${alias}"."${relatedPrimaryKey.name}"`;
+    joinSql += ` ON ${model.qualifiedTableName}."${column.name}"="${alias}"."${relatedPrimaryKey.name}"`;
     if (join.on) {
       for (const [propertyName, value] of Object.entries(join.on)) {
         const onColumn = relatedModel.columnsByPropertyName[propertyName];
@@ -2143,6 +2147,7 @@ ${stack ?? ""}`;
     const populates = [];
     const sorts = sort ? this._convertSortsToOrderBy(sort) : [];
     const joins = [];
+    let includeCount = false;
     const modelInstance = this;
     return {
       /**
@@ -2253,6 +2258,10 @@ ${stack ?? ""}`;
         const safePage = Math.max(page, 1);
         return this.skip(safePage * paginateLimit - paginateLimit).limit(paginateLimit);
       },
+      withCount() {
+        includeCount = true;
+        return this;
+      },
       async then(resolve, reject) {
         try {
           if (typeof where === "string") {
@@ -2266,14 +2275,29 @@ ${stack ?? ""}`;
             sorts,
             skip: skip ?? 0,
             limit: limit ?? 0,
-            joins
+            joins,
+            includeCount
           });
           const pool = poolOverride ?? modelInstance._readonlyPool;
           const results = await pool.query(query, params);
-          const entities = modelInstance._buildInstances(results.rows);
+          let totalCount = 0;
+          if (includeCount && results.rows.length > 0 && results.rows[0]?.__total_count__ !== void 0) {
+            totalCount = Number(results.rows[0].__total_count__);
+          }
+          const rows = includeCount ? results.rows.map((row) => {
+            const { __total_count__, ...rest } = row;
+            return rest;
+          }) : results.rows;
+          const entities = modelInstance._buildInstances(rows);
           if (populates.length) {
             await modelInstance.populateFields(entities, populates);
           }
+          if (includeCount) {
+            return await resolve({
+              results: entities,
+              totalCount
+            });
+          }
           return await resolve(entities);
         } catch (ex) {
           const typedException = ex;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bigal",
-  "version": "15.3.0",
+  "version": "15.4.0",
   "description": "A fast and lightweight orm for postgres and node.js, written in typescript.",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",