@rvoh/dream 0.42.2 → 0.42.3

package/README.md

@@ -1,4 +1,4 @@
-> ATTENTION: we are currently in the process of releasing this code to the world, as of the afternoon of March 10th, 2025. This notice will be removed, and the version of this repo will be bumped to 1.0.0, once all of the repos have been migrated to the new spaces and we can verify that it is all working. This is anticipated to take 1 day.
+> ATTENTION: we are currently in the process of releasing this code to the world, as of the afternoon of May 21st, 2025. This notice will be removed, and the version of this repo will be bumped to 1.0.0, once all of the repos have been migrated to the new spaces and we can verify that it is all working. This should happen sometime in the next month.
 
 Dream is a typescript-driven, esm-first ORM built on top of [kysely](http://kysely.dev). It is built to operate within the [Psychic web framework](https://psychic-docs.netlify.app), but can be brought into other projects and used without the encapsulating framework (though this is theoretical, and we do not encourage it at this time). It is actively being developed to support production-grade applications in use within the [RVOHealth organization](https://www.rvohealth.com), who has kindly sponsored the continued development of this ORM, as well as the Psychic web framework as a whole.
 

package/dist/cjs/src/Dream.js

@@ -596,6 +596,36 @@ class Dream {
     static async all(options = {}) {
         return await this.query().all(options);
     }
+    /**
+     * Paginates the results of your query, accepting a pageSize and page argument,
+     * which it uses to segment your query into pages, leveraging limit and offset
+     * to deliver your query to you in pages.
+     *
+     * ```ts
+     * const paginated = await User.paginate({ pageSize: 100, page: 2 })
+     * paginated.results
+     * // [ { User{id: 101}, User{id: 102}, ...}]
+     *
+     * paginated.recordCount
+     * // 350
+     *
+     * paginated.pageCount
+     * // 4
+     *
+     * paginated.currentPage
+     * // 2
+     * ```
+     *
+     * @param opts.page - the page number that you want to fetch results for
+     * @param opts.pageSize - the number of results per page (optional)
+     * @returns results.recordCount - A number representing the total number of records matching your query
+     * @returns results.pageCount - The number of pages needed to encapsulate all the matching records
+     * @returns results.currentPage - The current page (same as what is provided in the paginate args)
+     * @returns results.results - An array of records matching the current record
+     */
+    static async paginate(opts) {
+        return await this.query().paginate(opts);
+    }
     /**
      * Forces use of a database connection (e.g. 'primary') during the query.
      *

package/dist/cjs/src/dream/DreamClassTransactionBuilder.js

@@ -38,6 +38,38 @@ class DreamClassTransactionBuilder {
     async all(options = {}) {
         return this.queryInstance().all(options);
     }
+    /**
+     * Paginates the results of your query, accepting a pageSize and page argument,
+     * which it uses to segment your query into pages, leveraging limit and offset
+     * to deliver your query to you in pages.
+     *
+     * ```ts
+     * await ApplicationModel.transaction(async txn => {
+     *   const paginated = await User.txn(txn).paginate({ pageSize: 100, page: 2 })
+     *   paginated.results
+     *   // [ { User{id: 101}, User{id: 102}, ...}]
+     *
+     *   paginated.recordCount
+     *   // 350
+     *
+     *   paginated.pageCount
+     *   // 4
+     *
+     *   paginated.currentPage
+     *   // 2
+     * })
+     * ```
+     *
+     * @param opts.page - the page number that you want to fetch results for
+     * @param opts.pageSize - the number of results per page (optional)
+     * @returns results.recordCount - A number representing the total number of records matching your query
+     * @returns results.pageCount - The number of pages needed to encapsulate all the matching records
+     * @returns results.currentPage - The current page (same as what is provided in the paginate args)
+     * @returns results.results - An array of records matching the current record
+     */
+    async paginate(opts) {
+        return await this.queryInstance().paginate(opts);
+    }
     /**
      * Retrieves the number of records corresponding
      * to this model.

package/dist/cjs/src/dream/Query.js

@@ -47,6 +47,10 @@ const orderByDirection_js_1 = require("./internal/orderByDirection.js");
 const shouldBypassDefaultScope_js_1 = require("./internal/shouldBypassDefaultScope.js");
 const SimilarityBuilder_js_1 = require("./internal/similarity/SimilarityBuilder.js");
 const sqlResultToDreamInstance_js_1 = require("./internal/sqlResultToDreamInstance.js");
+const index_js_2 = require("../dream-app/index.js");
+const CannotPaginateWithLimit_js_1 = require("../errors/pagination/CannotPaginateWithLimit.js");
+const CannotPaginateWithOffset_js_1 = require("../errors/pagination/CannotPaginateWithOffset.js");
+const computedPaginatePage_js_1 = require("./internal/computedPaginatePage.js");
 class Query extends ConnectedToDB_js_1.default {
     /**
      * @internal
@@ -1414,6 +1418,52 @@ class Query extends ConnectedToDB_js_1.default {
         await this.applyPreload(this.preloadStatements, this.preloadOnStatements, theAll);
         return theAll;
     }
+    /**
+     * Paginates the results of your query, accepting a pageSize and page argument,
+     * which it uses to segment your query into pages, leveraging limit and offset
+     * to deliver your query to you in pages.
+     *
+     * ```ts
+     * const paginated = await User.order('email').paginate({ pageSize: 100, page: 2 })
+     * paginated.results
+     * // [ { User{id: 101}, User{id: 102}, ...}]
+     *
+     * paginated.recordCount
+     * // 350
+     *
+     * paginated.pageCount
+     * // 4
+     *
+     * paginated.currentPage
+     * // 2
+     * ```
+     *
+     * @param opts.page - the page number that you want to fetch results for
+     * @param opts.pageSize - the number of results per page (optional)
+     * @returns results.recordCount - A number representing the total number of records matching your query
+     * @returns results.pageCount - The number of pages needed to encapsulate all the matching records
+     * @returns results.currentPage - The current page (same as what is provided in the paginate args)
+     * @returns results.results - An array of records matching the current record
+     */
+    async paginate(opts) {
+        if (this.limitStatement)
+            throw new CannotPaginateWithLimit_js_1.default();
+        if (this.offsetStatement)
+            throw new CannotPaginateWithOffset_js_1.default();
+        const page = (0, computedPaginatePage_js_1.default)(opts.page);
+        const recordCount = await this.count();
+        const pageSize = opts.pageSize || index_js_2.default.getOrFail().paginationPageSize;
+        const pageCount = Math.ceil(recordCount / pageSize);
+        const results = await this.limit(pageSize)
+            .offset((page - 1) * pageSize)
+            .all();
+        return {
+            recordCount,
+            pageCount,
+            currentPage: page,
+            results,
+        };
+    }
     /**
      * Forces use of a database connection (e.g. 'primary') during the query.
      *

package/dist/cjs/src/dream/internal/computedPaginatePage.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = computedPaginatePage;
+function computedPaginatePage(page) {
+    if (page === null)
+        return 1;
+    if (page === undefined)
+        return 1;
+    return page <= 1 ? 1 : Math.floor(page);
+}

package/dist/cjs/src/dream-app/index.js

@@ -179,6 +179,10 @@ Try setting it to something valid, like:
     get unicodeNormalization() {
         return this._unicodeNormalization;
     }
+    _paginationPageSize = 25;
+    get paginationPageSize() {
+        return this._paginationPageSize;
+    }
     _primaryKeyType = 'bigserial';
     get primaryKeyType() {
         return this._primaryKeyType;
@@ -310,6 +314,9 @@ Try setting it to something valid, like:
             case 'unicodeNormalization':
                 this._unicodeNormalization = options;
                 break;
+            case 'paginationPageSize':
+                this._paginationPageSize = options;
+                break;
             default:
                 throw new Error(`Unhandled applyOption encountered in Dreamconf: ${applyOption}`);
         }

package/dist/cjs/src/errors/pagination/CannotPaginateWithLimit.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+class CannotPaginateWithLimit extends Error {
+    get message() {
+        return `\
+Cannot call paginate on a query which has a limit applied.
+
+Limit statements are automatically generated by the paginate method,
+and adding custom limits interferes with paginate's ability to provide
+a total count.
+
+fix:
+  remove the limit statement from your query
+`;
+    }
+}
+exports.default = CannotPaginateWithLimit;

package/dist/cjs/src/errors/pagination/CannotPaginateWithOffset.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+class CannotPaginateWithOffset extends Error {
+    get message() {
+        return `\
+Cannot call paginate on a query which has an offset applied.
+
+Offset statements are automatically generated by the paginate method,
+and adding custom offsets interferes with paginate's ability to provide
+a total count.
+
+fix:
+  remove the offset statement from your query
+`;
+    }
+}
+exports.default = CannotPaginateWithOffset;

package/dist/esm/src/Dream.js

@@ -594,6 +594,36 @@ export default class Dream {
     static async all(options = {}) {
         return await this.query().all(options);
     }
+    /**
+     * Paginates the results of your query, accepting a pageSize and page argument,
+     * which it uses to segment your query into pages, leveraging limit and offset
+     * to deliver your query to you in pages.
+     *
+     * ```ts
+     * const paginated = await User.paginate({ pageSize: 100, page: 2 })
+     * paginated.results
+     * // [ { User{id: 101}, User{id: 102}, ...}]
+     *
+     * paginated.recordCount
+     * // 350
+     *
+     * paginated.pageCount
+     * // 4
+     *
+     * paginated.currentPage
+     * // 2
+     * ```
+     *
+     * @param opts.page - the page number that you want to fetch results for
+     * @param opts.pageSize - the number of results per page (optional)
+     * @returns results.recordCount - A number representing the total number of records matching your query
+     * @returns results.pageCount - The number of pages needed to encapsulate all the matching records
+     * @returns results.currentPage - The current page (same as what is provided in the paginate args)
+     * @returns results.results - An array of records matching the current record
+     */
+    static async paginate(opts) {
+        return await this.query().paginate(opts);
+    }
     /**
      * Forces use of a database connection (e.g. 'primary') during the query.
      *

package/dist/esm/src/dream/DreamClassTransactionBuilder.js

@@ -36,6 +36,38 @@ export default class DreamClassTransactionBuilder {
     async all(options = {}) {
         return this.queryInstance().all(options);
     }
+    /**
+     * Paginates the results of your query, accepting a pageSize and page argument,
+     * which it uses to segment your query into pages, leveraging limit and offset
+     * to deliver your query to you in pages.
+     *
+     * ```ts
+     * await ApplicationModel.transaction(async txn => {
+     *   const paginated = await User.txn(txn).paginate({ pageSize: 100, page: 2 })
+     *   paginated.results
+     *   // [ { User{id: 101}, User{id: 102}, ...}]
+     *
+     *   paginated.recordCount
+     *   // 350
+     *
+     *   paginated.pageCount
+     *   // 4
+     *
+     *   paginated.currentPage
+     *   // 2
+     * })
+     * ```
+     *
+     * @param opts.page - the page number that you want to fetch results for
+     * @param opts.pageSize - the number of results per page (optional)
+     * @returns results.recordCount - A number representing the total number of records matching your query
+     * @returns results.pageCount - The number of pages needed to encapsulate all the matching records
+     * @returns results.currentPage - The current page (same as what is provided in the paginate args)
+     * @returns results.results - An array of records matching the current record
+     */
+    async paginate(opts) {
+        return await this.queryInstance().paginate(opts);
+    }
     /**
      * Retrieves the number of records corresponding
      * to this model.

package/dist/esm/src/dream/Query.js

@@ -45,6 +45,10 @@ import orderByDirection from './internal/orderByDirection.js';
 import shouldBypassDefaultScope from './internal/shouldBypassDefaultScope.js';
 import SimilarityBuilder from './internal/similarity/SimilarityBuilder.js';
 import sqlResultToDreamInstance from './internal/sqlResultToDreamInstance.js';
+import DreamApp from '../dream-app/index.js';
+import CannotPaginateWithLimit from '../errors/pagination/CannotPaginateWithLimit.js';
+import CannotPaginateWithOffset from '../errors/pagination/CannotPaginateWithOffset.js';
+import computedPaginatePage from './internal/computedPaginatePage.js';
 export default class Query extends ConnectedToDB {
     /**
      * @internal
@@ -1412,6 +1416,52 @@ export default class Query extends ConnectedToDB {
         await this.applyPreload(this.preloadStatements, this.preloadOnStatements, theAll);
         return theAll;
     }
+    /**
+     * Paginates the results of your query, accepting a pageSize and page argument,
+     * which it uses to segment your query into pages, leveraging limit and offset
+     * to deliver your query to you in pages.
+     *
+     * ```ts
+     * const paginated = await User.order('email').paginate({ pageSize: 100, page: 2 })
+     * paginated.results
+     * // [ { User{id: 101}, User{id: 102}, ...}]
+     *
+     * paginated.recordCount
+     * // 350
+     *
+     * paginated.pageCount
+     * // 4
+     *
+     * paginated.currentPage
+     * // 2
+     * ```
+     *
+     * @param opts.page - the page number that you want to fetch results for
+     * @param opts.pageSize - the number of results per page (optional)
+     * @returns results.recordCount - A number representing the total number of records matching your query
+     * @returns results.pageCount - The number of pages needed to encapsulate all the matching records
+     * @returns results.currentPage - The current page (same as what is provided in the paginate args)
+     * @returns results.results - An array of records matching the current record
+     */
+    async paginate(opts) {
+        if (this.limitStatement)
+            throw new CannotPaginateWithLimit();
+        if (this.offsetStatement)
+            throw new CannotPaginateWithOffset();
+        const page = computedPaginatePage(opts.page);
+        const recordCount = await this.count();
+        const pageSize = opts.pageSize || DreamApp.getOrFail().paginationPageSize;
+        const pageCount = Math.ceil(recordCount / pageSize);
+        const results = await this.limit(pageSize)
+            .offset((page - 1) * pageSize)
+            .all();
+        return {
+            recordCount,
+            pageCount,
+            currentPage: page,
+            results,
+        };
+    }
     /**
      * Forces use of a database connection (e.g. 'primary') during the query.
      *

package/dist/esm/src/dream/internal/computedPaginatePage.js

@@ -0,0 +1,7 @@
+export default function computedPaginatePage(page) {
+    if (page === null)
+        return 1;
+    if (page === undefined)
+        return 1;
+    return page <= 1 ? 1 : Math.floor(page);
+}

package/dist/esm/src/dream-app/index.js

@@ -177,6 +177,10 @@ Try setting it to something valid, like:
     get unicodeNormalization() {
         return this._unicodeNormalization;
     }
+    _paginationPageSize = 25;
+    get paginationPageSize() {
+        return this._paginationPageSize;
+    }
     _primaryKeyType = 'bigserial';
     get primaryKeyType() {
         return this._primaryKeyType;
@@ -308,6 +312,9 @@ Try setting it to something valid, like:
             case 'unicodeNormalization':
                 this._unicodeNormalization = options;
                 break;
+            case 'paginationPageSize':
+                this._paginationPageSize = options;
+                break;
             default:
                 throw new Error(`Unhandled applyOption encountered in Dreamconf: ${applyOption}`);
         }

package/dist/esm/src/errors/pagination/CannotPaginateWithLimit.js

@@ -0,0 +1,14 @@
+export default class CannotPaginateWithLimit extends Error {
+    get message() {
+        return `\
+Cannot call paginate on a query which has a limit applied.
+
+Limit statements are automatically generated by the paginate method,
+and adding custom limits interferes with paginate's ability to provide
+a total count.
+
+fix:
+  remove the limit statement from your query
+`;
+    }
+}

package/dist/esm/src/errors/pagination/CannotPaginateWithOffset.js

@@ -0,0 +1,14 @@
+export default class CannotPaginateWithOffset extends Error {
+    get message() {
+        return `\
+Cannot call paginate on a query which has an offset applied.
+
+Offset statements are automatically generated by the paginate method,
+and adding custom offsets interferes with paginate's ability to provide
+a total count.
+
+fix:
+  remove the offset statement from your query
+`;
+    }
+}

package/dist/types/src/Dream.d.ts

@@ -13,7 +13,7 @@ import { AssociationStatementsMap, PassthroughOnClause, WhereStatement } from '.
 import { AssociationTableNames, DbConnectionType } from './types/db.js';
 import { AllDefaultScopeNames, AssociationNameToDream, AttributeKeys, CreateOrFindByExtraOpts, DefaultOrNamedScopeName, DreamAssociationNames, DreamAssociationNamesWithoutRequiredOnClauses, DreamAttributes, DreamColumnNames, DreamParamSafeColumnNames, DreamSerializeOptions, IdType, JoinAndStatements, NextPreloadArgumentType, OrderDir, PassthroughColumnNames, PluckEachArgs, PrimaryKeyForFind, TableColumnNames, UpdateableAssociationProperties, UpdateableProperties, UpdateablePropertiesForClass, UpdateOrCreateByExtraOpts } from './types/dream.js';
 import { HookStatement, HookStatementMap } from './types/lifecycle.js';
-import { BaseModelColumnTypes, DefaultQueryTypeOptions, FindEachOpts, QueryWithJoinedAssociationsType, QueryWithJoinedAssociationsTypeAndNoPreload } from './types/query.js';
+import { BaseModelColumnTypes, DefaultQueryTypeOptions, FindEachOpts, PaginatedDreamQueryOptions, PaginatedDreamQueryResult, QueryWithJoinedAssociationsType, QueryWithJoinedAssociationsTypeAndNoPreload } from './types/query.js';
 import { ValidationStatement, ValidationType } from './types/validation.js';
 import { JoinedAssociation, JoinedAssociationsTypeFromAssociations, RequiredOnClauseKeys, VariadicJoinsArgs, VariadicLeftJoinLoadArgs, VariadicLoadArgs } from './types/variadic.js';
 export default class Dream {
@@ -434,6 +434,34 @@ export default class Dream {
     static all<T extends typeof Dream>(this: T, options?: {
         columns?: DreamColumnNames<InstanceType<T>>[];
     }): Promise<InstanceType<T>[]>;
+    /**
+     * Paginates the results of your query, accepting a pageSize and page argument,
+     * which it uses to segment your query into pages, leveraging limit and offset
+     * to deliver your query to you in pages.
+     *
+     * ```ts
+     * const paginated = await User.paginate({ pageSize: 100, page: 2 })
+     * paginated.results
+     * // [ { User{id: 101}, User{id: 102}, ...}]
+     *
+     * paginated.recordCount
+     * // 350
+     *
+     * paginated.pageCount
+     * // 4
+     *
+     * paginated.currentPage
+     * // 2
+     * ```
+     *
+     * @param opts.page - the page number that you want to fetch results for
+     * @param opts.pageSize - the number of results per page (optional)
+     * @returns results.recordCount - A number representing the total number of records matching your query
+     * @returns results.pageCount - The number of pages needed to encapsulate all the matching records
+     * @returns results.currentPage - The current page (same as what is provided in the paginate args)
+     * @returns results.results - An array of records matching the current record
+     */
+    static paginate<T extends typeof Dream>(this: T, opts: PaginatedDreamQueryOptions): Promise<PaginatedDreamQueryResult<InstanceType<T>>>;
     /**
      * Forces use of a database connection (e.g. 'primary') during the query.
      *

package/dist/types/src/dream/DreamClassTransactionBuilder.d.ts

@@ -3,7 +3,7 @@ import Dream from '../Dream.js';
 import { PassthroughOnClause, WhereStatement } from '../types/associations/shared.js';
 import { AssociationTableNames } from '../types/db.js';
 import { CreateOrFindByExtraOpts, DefaultScopeName, DreamColumnNames, OrderDir, PassthroughColumnNames, PluckEachArgs, PrimaryKeyForFind, TableColumnNames, UpdateableProperties, UpdateablePropertiesForClass, UpdateOrCreateByExtraOpts } from '../types/dream.js';
-import { BaseModelColumnTypes, FindEachOpts, QueryWithJoinedAssociationsType, QueryWithJoinedAssociationsTypeAndNoPreload } from '../types/query.js';
+import { BaseModelColumnTypes, FindEachOpts, PaginatedDreamQueryOptions, PaginatedDreamQueryResult, QueryWithJoinedAssociationsType, QueryWithJoinedAssociationsTypeAndNoPreload } from '../types/query.js';
 import { JoinedAssociation, JoinedAssociationsTypeFromAssociations, VariadicJoinsArgs, VariadicLeftJoinLoadArgs, VariadicLoadArgs } from '../types/variadic.js';
 import DreamTransaction from './DreamTransaction.js';
 import Query from './Query.js';
@@ -37,6 +37,36 @@ export default class DreamClassTransactionBuilder<DreamClass extends typeof Drea
     all<I extends DreamClassTransactionBuilder<DreamClass, DreamInstance>>(this: I, options?: {
         columns?: DreamColumnNames<DreamInstance>[];
     }): Promise<DreamInstance[]>;
+    /**
+     * Paginates the results of your query, accepting a pageSize and page argument,
+     * which it uses to segment your query into pages, leveraging limit and offset
+     * to deliver your query to you in pages.
+     *
+     * ```ts
+     * await ApplicationModel.transaction(async txn => {
+     *   const paginated = await User.txn(txn).paginate({ pageSize: 100, page: 2 })
+     *   paginated.results
+     *   // [ { User{id: 101}, User{id: 102}, ...}]
+     *
+     *   paginated.recordCount
+     *   // 350
+     *
+     *   paginated.pageCount
+     *   // 4
+     *
+     *   paginated.currentPage
+     *   // 2
+     * })
+     * ```
+     *
+     * @param opts.page - the page number that you want to fetch results for
+     * @param opts.pageSize - the number of results per page (optional)
+     * @returns results.recordCount - A number representing the total number of records matching your query
+     * @returns results.pageCount - The number of pages needed to encapsulate all the matching records
+     * @returns results.currentPage - The current page (same as what is provided in the paginate args)
+     * @returns results.results - An array of records matching the current record
+     */
+    paginate<I extends DreamClassTransactionBuilder<DreamClass, DreamInstance>>(this: I, opts: PaginatedDreamQueryOptions): Promise<PaginatedDreamQueryResult<DreamInstance>>;
     /**
      * Retrieves the number of records corresponding
      * to this model.

package/dist/types/src/dream/Query.d.ts

@@ -4,7 +4,7 @@ import Dream from '../Dream.js';
 import { ColumnNamesAccountingForJoinedAssociations, LimitStatement, OffsetStatement, OrderQueryStatement, PassthroughOnClause, WhereStatement, WhereStatementForJoinedAssociation } from '../types/associations/shared.js';
 import { DbConnectionType } from '../types/db.js';
 import { AllDefaultScopeNames, DefaultScopeName, DreamColumnNames, DreamTableSchema, OrderDir, PassthroughColumnNames, PluckEachArgs, PrimaryKeyForFind, RelaxedJoinAndStatement, RelaxedJoinStatement, RelaxedPreloadOnStatement, RelaxedPreloadStatement, TableColumnNames, TableOrAssociationName } from '../types/dream.js';
-import { DefaultQueryTypeOptions, ExtendQueryType, NamespacedOrBaseModelColumnTypes, QueryToKyselyDBType, QueryToKyselyTableNamesType } from '../types/query.js';
+import { DefaultQueryTypeOptions, ExtendQueryType, NamespacedOrBaseModelColumnTypes, PaginatedDreamQueryOptions, PaginatedDreamQueryResult, QueryToKyselyDBType, QueryToKyselyTableNamesType } from '../types/query.js';
 import { JoinedAssociation, JoinedAssociationsTypeFromAssociations, QueryTypeOptions, VariadicJoinsArgs, VariadicLeftJoinLoadArgs, VariadicLoadArgs } from '../types/variadic.js';
 import DreamTransaction from './DreamTransaction.js';
 export default class Query<DreamInstance extends Dream, QueryTypeOpts extends Readonly<QueryTypeOptions> = DefaultQueryTypeOptions<DreamInstance>> extends ConnectedToDB<DreamInstance> {
@@ -774,6 +774,34 @@ export default class Query<DreamInstance extends Dream, QueryTypeOpts extends Re
     all(options?: {
         columns?: DreamColumnNames<DreamInstance>[];
     }): Promise<DreamInstance[]>;
+    /**
+     * Paginates the results of your query, accepting a pageSize and page argument,
+     * which it uses to segment your query into pages, leveraging limit and offset
+     * to deliver your query to you in pages.
+     *
+     * ```ts
+     * const paginated = await User.order('email').paginate({ pageSize: 100, page: 2 })
+     * paginated.results
+     * // [ { User{id: 101}, User{id: 102}, ...}]
+     *
+     * paginated.recordCount
+     * // 350
+     *
+     * paginated.pageCount
+     * // 4
+     *
+     * paginated.currentPage
+     * // 2
+     * ```
+     *
+     * @param opts.page - the page number that you want to fetch results for
+     * @param opts.pageSize - the number of results per page (optional)
+     * @returns results.recordCount - A number representing the total number of records matching your query
+     * @returns results.pageCount - The number of pages needed to encapsulate all the matching records
+     * @returns results.currentPage - The current page (same as what is provided in the paginate args)
+     * @returns results.results - An array of records matching the current record
+     */
+    paginate(opts: PaginatedDreamQueryOptions): Promise<PaginatedDreamQueryResult<DreamInstance>>;
     /**
      * Forces use of a database connection (e.g. 'primary') during the query.
      *

package/dist/types/src/dream/internal/computedPaginatePage.d.ts

@@ -0,0 +1 @@
+export default function computedPaginatePage(page: number | undefined | null): number;

package/dist/types/src/dream-app/index.d.ts

@@ -64,6 +64,8 @@ export default class DreamApp {
     get parallelTests(): number | undefined;
     private _unicodeNormalization;
     get unicodeNormalization(): UnicodeNormalizationForm;
+    private _paginationPageSize;
+    get paginationPageSize(): number;
     private _primaryKeyType;
     get primaryKeyType(): "bigint" | "integer" | "bigserial" | "uuid";
     private _projectRoot;
@@ -88,7 +90,7 @@ export default class DreamApp {
     get parallelDatabasesEnabled(): boolean;
     load<RT extends 'models' | 'serializers'>(resourceType: RT, resourcePath: string, importCb: (path: string) => Promise<any>): Promise<void>;
     plugin(cb: (app: DreamApp) => void | Promise<void>): void;
-    set<ApplyOpt extends DreamAppSetOption>(applyOption: ApplyOpt, options: ApplyOpt extends 'db' ? DreamDbCredentialOptions : ApplyOpt extends 'encryption' ? DreamAppEncryptionOptions : ApplyOpt extends 'primaryKeyType' ? (typeof primaryKeyTypes)[number] : ApplyOpt extends 'logger' ? DreamLogger : ApplyOpt extends 'projectRoot' ? string : ApplyOpt extends 'inflections' ? () => void | Promise<void> : ApplyOpt extends 'paths' ? DreamDirectoryPaths : ApplyOpt extends 'parallelTests' ? number : ApplyOpt extends 'unicodeNormalization' ? UnicodeNormalizationForm : never): void;
+    set<ApplyOpt extends DreamAppSetOption>(applyOption: ApplyOpt, options: ApplyOpt extends 'db' ? DreamDbCredentialOptions : ApplyOpt extends 'encryption' ? DreamAppEncryptionOptions : ApplyOpt extends 'primaryKeyType' ? (typeof primaryKeyTypes)[number] : ApplyOpt extends 'logger' ? DreamLogger : ApplyOpt extends 'projectRoot' ? string : ApplyOpt extends 'inflections' ? () => void | Promise<void> : ApplyOpt extends 'paths' ? DreamDirectoryPaths : ApplyOpt extends 'parallelTests' ? number : ApplyOpt extends 'unicodeNormalization' ? UnicodeNormalizationForm : ApplyOpt extends 'paginationPageSize' ? number : never): void;
     on<T extends DreamHookEventType>(hookEventType: T, cb: T extends 'db:log' ? (event: KyselyLogEvent) => void : T extends 'repl:start' ? (context: Context) => void | Promise<void> : never): void;
 }
 export type DreamHookEventType = 'db:log' | 'repl:start';
@@ -101,7 +103,7 @@ export interface DreamAppOpts {
     serializerCasing?: DreamSerializerCasing;
     parallelTests: number | undefined;
 }
-export type DreamAppSetOption = 'db' | 'encryption' | 'inflections' | 'logger' | 'paths' | 'primaryKeyType' | 'projectRoot' | 'serializerCasing' | 'parallelTests' | 'unicodeNormalization';
+export type DreamAppSetOption = 'db' | 'encryption' | 'inflections' | 'logger' | 'paths' | 'primaryKeyType' | 'projectRoot' | 'serializerCasing' | 'parallelTests' | 'unicodeNormalization' | 'paginationPageSize';
 export interface DreamDirectoryPaths {
     models?: string;
     serializers?: string;

package/dist/types/src/errors/pagination/CannotPaginateWithLimit.d.ts

@@ -0,0 +1,3 @@
+export default class CannotPaginateWithLimit extends Error {
+    get message(): string;
+}

package/dist/types/src/errors/pagination/CannotPaginateWithOffset.d.ts

@@ -0,0 +1,3 @@
+export default class CannotPaginateWithOffset extends Error {
+    get message(): string;
+}

package/dist/types/src/types/query.d.ts

@@ -54,4 +54,32 @@ export type QueryToKyselyAliasMap<Q extends Query<any, any>, DreamInstance exten
         alias: Key;
     }>['table']]>;
 } : null> = AliasToDbMaps;
+export interface PaginatedDreamQueryOptions {
+    /**
+     * the number of records you would like to be returned in each page
+     */
+    pageSize?: number;
+    /**
+     * the current page
+     */
+    page: number | null | undefined;
+}
+export interface PaginatedDreamQueryResult<T extends Dream> {
+    /**
+     * the total number of records in the DB matching the query
+     */
+    recordCount: number;
+    /**
+     * The number of pages that are needed to encapsulate these results
+     */
+    pageCount: number;
+    /**
+     * The current page
+     */
+    currentPage: number;
+    /**
+     * The results for the current page
+     */
+    results: T[];
+}
 export {};