@rvoh/dream 2.1.4-alpha.3 → 2.2.0

package/dist/cjs/src/Dream.js

@@ -926,11 +926,15 @@ export default class Dream {
         return await this.query().paginate(opts);
     }
     /**
-     * Fast paginates the results of your query using cursor-based pagination,
+     * @deprecated Use {@link cursorPaginate} instead.
+     *
+     * Paginates the results of your query using cursor-based pagination,
      * accepting a pageSize and cursor argument. This method
      * provides better performance for large datasets by using cursor-based
      * pagination instead of offset-based pagination.
      *
+     * Default order is ascending primary key.
+     *
      * ```ts
      * // First page (using undefined to start from beginning)
      * const firstPage = await User.scrollPaginate({ pageSize: 100, cursor: undefined })
@@ -947,7 +951,7 @@ export default class Dream {
      * })
      * ```
      *
-     * @param opts - Fast pagination options
+     * @param opts - scroll pagination options
      * @param opts.pageSize - the number of results per page
      * @param opts.cursor - identifier of where to start the next page; use undefined to start from the beginning
      * @returns A fast pagination result object containing:
@@ -957,6 +961,40 @@ export default class Dream {
     static async scrollPaginate(opts) {
         return await this.query().scrollPaginate(opts);
     }
+    /**
+     * Paginates the results of your query using cursor-based pagination,
+     * accepting a pageSize and cursor argument. This method
+     * provides better performance for large datasets by using cursor-based
+     * pagination instead of offset-based pagination.
+     *
+     * Default order is descending primary key.
+     *
+     * ```ts
+     * // First page (using undefined to start from beginning)
+     * const firstPage = await User.cursorPaginate({ pageSize: 100, cursor: undefined })
+     * firstPage.results
+     * // [ { User{id: 777}, User{id: 776}, ...}]
+     *
+     * firstPage.cursor
+     * // "100" (or null if no more pages)
+     *
+     * // Next page using cursor from previous result
+     * const nextPage = await User.cursorPaginate({
+     *   pageSize: 100,
+     *   cursor: firstPage.cursor
+     * })
+     * ```
+     *
+     * @param opts - cursor pagination options
+     * @param opts.pageSize - the number of results per page
+     * @param opts.cursor - identifier of where to start the next page; use undefined to start from the beginning
+     * @returns A fast pagination result object containing:
+     * - `cursor` - identifier for the next page, or null if no more pages
+     * - `results` - An array of records for the current page
+     */
+    static async cursorPaginate(opts) {
+        return await this.query().cursorPaginate(opts);
+    }
     /**
      * Forces use of a database connection (e.g. 'primary') during the query.
      *

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

@@ -1225,7 +1225,7 @@ export default class Query {
         const pageCount = Math.ceil(recordCount / pageSize);
         const query = this.orderStatements.length
             ? this
-            : this.order({ [this.namespacedPrimaryKey]: 'asc' });
+            : this.order({ [this.namespacedPrimaryKey]: 'desc' });
         const results = await query
             .limit(pageSize)
             .offset(((page - 1) * pageSize))
@@ -1238,11 +1238,17 @@ export default class Query {
         };
     }
     /**
-     * Fast paginates the results of your query using cursor-based pagination,
+     * @deprecated Use {@link cursorPaginate} instead.
+     *
+     * Paginates the results of your query using cursor-based pagination,
      * accepting a pageSize and cursor argument. This method
      * provides better performance for large datasets by using cursor-based
      * pagination instead of offset-based pagination.
      *
+     * Default order is ascending primary key. If an order has already been
+     * set on the query, and it includes the primary key (e.g.: `id: 'asc'`),
+     * then the implicit primary key ordering will be omitted.
+     *
      * ```ts
      * // First page (using undefined to start from beginning)
      * const firstPage = await User.order('email').scrollPaginate({ pageSize: 100, cursor: undefined })
@@ -1259,13 +1265,53 @@ export default class Query {
      * })
      * ```
      *
-     * @param opts - Fast pagination options
+     * @param opts - scroll pagination options
      * @param opts.pageSize - the number of results per page (optional)
      * @param opts.cursor - identifier of where to start the next page; undefined to start from the beginning; null when no more pages
      * @returns results.cursor - identifier for the next page, or null if no more pages
      * @returns results.results - An array of records for the current page
      */
     async scrollPaginate(opts) {
+        const orderIncludesPrimaryKey = this.orderStatements.some(orderStatement => orderStatement.column === this.dreamClass.primaryKey ||
+            orderStatement.column === this.namespacedPrimaryKey);
+        const query = orderIncludesPrimaryKey
+            ? this
+            : this.order({ [this.namespacedPrimaryKey]: 'asc' });
+        return await query.cursorPaginate(opts);
+    }
+    /**
+     * Paginates the results of your query using cursor-based pagination,
+     * accepting a pageSize and cursor argument. This method
+     * provides better performance for large datasets by using cursor-based
+     * pagination instead of offset-based pagination.
+     *
+     * Default order is descending primary key. If an order has already been
+     * set on the query, and it includes the primary key (e.g.: `id: 'asc'`),
+     * then the implicit primary key ordering will be omitted.
+     *
+     * ```ts
+     * // First page (using undefined to start from beginning)
+     * const firstPage = await User.order('email').cursorPaginate({ pageSize: 100, cursor: undefined })
+     * firstPage.results
+     * // [ { User{id: 777}, User{id: 776}, ...}]
+     *
+     * firstPage.cursor
+     * // "100" (or null if no more pages)
+     *
+     * // Next page using cursor from previous result
+     * const nextPage = await User.order('email').cursorPaginate({
+     *   pageSize: 100,
+     *   cursor: firstPage.cursor
+     * })
+     * ```
+     *
+     * @param opts - cursor pagination options
+     * @param opts.pageSize - the number of results per page (optional)
+     * @param opts.cursor - identifier of where to start the next page; undefined to start from the beginning; null when no more pages
+     * @returns results.cursor - identifier for the next page, or null if no more pages
+     * @returns results.results - An array of records for the current page
+     */
+    async cursorPaginate(opts) {
         const options = opts;
         const pageSize = Math.max(0, options.pageSize ?? 0) || DreamApp.getOrFail().paginationPageSize;
         if (options === null)
@@ -1280,53 +1326,97 @@ export default class Query {
             orderStatement.column === this.namespacedPrimaryKey);
         let query = orderIncludesPrimaryKey
             ? this
-            : this.order({ [this.namespacedPrimaryKey]: 'asc' });
+            : this.order({ [this.namespacedPrimaryKey]: 'desc' });
         if (options.cursor) {
             const orderStatements = query.orderStatements;
-            /**
-             * if there is only one ordering, then that is the primary key (either added above or in the original),
-             * so we don't need to pluck values, and all we need is the primary key that we already have in the cursor
-             */
-            const endOfPreviousPageComparisonValues = orderStatements.length === 1
-                ? [options.cursor]
-                : (await query
+            if (orderStatements.length === 1) {
+                /**
+                 * Since we add a primary key above if it wasn't already included, we know
+                 * that if there is only one order statement, then it must be ordering on
+                 * the primary key
+                 */
+                const orderStatement = orderStatements[0];
+                switch (orderStatement.direction) {
+                    case 'asc':
+                        query = query.where({
+                            [orderStatement.column]: ops.greaterThan(options.cursor),
+                        });
+                        break;
+                    case 'desc':
+                        query = query.where({
+                            [orderStatement.column]: ops.lessThan(options.cursor),
+                        });
+                        break;
+                }
+            }
+            else {
+                const endOfPreviousPageComparisonValues = (await query
                     .removeDefaultScopeExceptOnAssociations(SOFT_DELETE_SCOPE_NAME)
                     .where({ [this.namespacedPrimaryKey]: options.cursor })
                     .limit(1)
                     .order(null)
-                    .pluck(...orderStatements.map(orderStatement => orderStatement.column)))[0] || [];
-            endOfPreviousPageComparisonValues.forEach((valueToCompare, index) => {
-                const orderStatement = orderStatements[index];
-                if (orderStatement.column === this.dreamClass.primaryKey ||
-                    orderStatement.column === this.namespacedPrimaryKey) {
-                    switch (orderStatement.direction) {
-                        case 'asc':
-                            query = query.where({
-                                [orderStatement.column]: ops.greaterThan(valueToCompare),
-                            });
-                            break;
-                        case 'desc':
-                            query = query.where({
-                                [orderStatement.column]: ops.lessThan(valueToCompare),
-                            });
-                            break;
-                    }
-                }
-                else {
-                    switch (orderStatement.direction) {
-                        case 'asc':
-                            query = query.where({
-                                [orderStatement.column]: ops.greaterThanOrEqualTo(valueToCompare),
-                            });
-                            break;
-                        case 'desc':
-                            query = query.where({
-                                [orderStatement.column]: ops.lessThanOrEqualTo(valueToCompare),
-                            });
-                            break;
+                    .pluck(...orderStatements.map(orderStatement => orderStatement.column)))[0];
+                if (endOfPreviousPageComparisonValues) {
+                    const whereAnyMaybeEqualArray = [];
+                    for (let index = 0; index < endOfPreviousPageComparisonValues.length; index++) {
+                        /**
+                         * This nested loop enables us to give priority to the left-most order clause,
+                         * then the left-most and next left-most, etc., replicating what ordering on
+                         * multiple clauses does:
+                         *
+                         *  const results = await Pet.query()
+                         *    .leftJoin('user')
+                         *    // The primary key is implicitly added if not explicitly present, so these two
+                         *    // order clauses appear in the query with an additional primary key clause.
+                         *    // This supports pagination when the earlier order clauses match multiple records.
+                         *    .order({ 'pets.name': 'asc', 'user.id': 'asc' })
+                         *    .cursorPaginate({ pageSize: 2, cursor: undefined })
+                         *
+                         * Results in:
+                         *
+                         * SELECT
+                         * 	"pets".*
+                         * FROM
+                         * 	"pets"
+                         * 	LEFT JOIN "users" AS "user" ON "pets"."user_id" = "user"."id"
+                         * 		AND "user"."deleted_at" IS NULL
+                         * WHERE ("pets"."deleted_at" IS NULL
+                         * 	AND (
+                         *    "pets"."name" > $1
+                         * 		OR (
+                         *    "pets"."name" = $2 AND "user"."id" > $3
+                         * 		) OR (
+                         *    "pets"."name" = $4 AND "user"."id" = $5 AND "pets"."id" < $6
+                         *   )))
+                         * ORDER BY
+                         * 	"pets"."name" ASC nulls FIRST,
+                         * 	"user"."id" ASC nulls FIRST,
+                         * 	"pets"."id" DESC nulls LAST
+                         * LIMIT $7
+                         */
+                        const whereAnyMaybeEqual = {};
+                        whereAnyMaybeEqualArray.push(whereAnyMaybeEqual);
+                        for (let nestedIndex = 0; nestedIndex <= index; nestedIndex++) {
+                            const valueToCompare = endOfPreviousPageComparisonValues[nestedIndex];
+                            const orderStatement = orderStatements[nestedIndex];
+                            if (nestedIndex < index) {
+                                whereAnyMaybeEqual[orderStatement.column] = valueToCompare;
+                            }
+                            else if (nestedIndex === index) {
+                                switch (orderStatement.direction) {
+                                    case 'asc':
+                                        whereAnyMaybeEqual[orderStatement.column] = ops.greaterThan(valueToCompare);
+                                        break;
+                                    case 'desc':
+                                        whereAnyMaybeEqual[orderStatement.column] = ops.lessThan(valueToCompare);
+                                        break;
+                                }
+                            }
+                        }
                     }
+                    query = query.whereAny(whereAnyMaybeEqualArray);
                 }
-            });
+            }
         }
         const results = await query.limit(pageSize).all();
         return {

package/dist/cjs/src/helpers/cli/generateMigrationContent.js

@@ -295,12 +295,18 @@ function generateIdStr({ primaryKeyType }) {
         .defaultTo(sql\`uuidv7()\`),
     )`;
         case 'uuid4':
-        case 'uuid':
             return `\
 .addColumn('id', 'uuid', col =>
       col
         .primaryKey()
         .defaultTo(sql\`gen_random_uuid()\`),
+    )`;
+        case 'uuid':
+            return `\
+.addColumn('id', 'uuid', col =>
+      col
+        .primaryKey()
+        .defaultTo(sql\`uuid_generate_v4()\`),
     )`;
         default:
             return `.addColumn('id', '${primaryKeyType}', col => col.primaryKey())`;

package/dist/esm/src/Dream.js

@@ -926,11 +926,15 @@ export default class Dream {
         return await this.query().paginate(opts);
     }
     /**
-     * Fast paginates the results of your query using cursor-based pagination,
+     * @deprecated Use {@link cursorPaginate} instead.
+     *
+     * Paginates the results of your query using cursor-based pagination,
      * accepting a pageSize and cursor argument. This method
      * provides better performance for large datasets by using cursor-based
      * pagination instead of offset-based pagination.
      *
+     * Default order is ascending primary key.
+     *
      * ```ts
      * // First page (using undefined to start from beginning)
      * const firstPage = await User.scrollPaginate({ pageSize: 100, cursor: undefined })
@@ -947,7 +951,7 @@ export default class Dream {
      * })
      * ```
      *
-     * @param opts - Fast pagination options
+     * @param opts - scroll pagination options
      * @param opts.pageSize - the number of results per page
      * @param opts.cursor - identifier of where to start the next page; use undefined to start from the beginning
      * @returns A fast pagination result object containing:
@@ -957,6 +961,40 @@ export default class Dream {
     static async scrollPaginate(opts) {
         return await this.query().scrollPaginate(opts);
     }
+    /**
+     * Paginates the results of your query using cursor-based pagination,
+     * accepting a pageSize and cursor argument. This method
+     * provides better performance for large datasets by using cursor-based
+     * pagination instead of offset-based pagination.
+     *
+     * Default order is descending primary key.
+     *
+     * ```ts
+     * // First page (using undefined to start from beginning)
+     * const firstPage = await User.cursorPaginate({ pageSize: 100, cursor: undefined })
+     * firstPage.results
+     * // [ { User{id: 777}, User{id: 776}, ...}]
+     *
+     * firstPage.cursor
+     * // "100" (or null if no more pages)
+     *
+     * // Next page using cursor from previous result
+     * const nextPage = await User.cursorPaginate({
+     *   pageSize: 100,
+     *   cursor: firstPage.cursor
+     * })
+     * ```
+     *
+     * @param opts - cursor pagination options
+     * @param opts.pageSize - the number of results per page
+     * @param opts.cursor - identifier of where to start the next page; use undefined to start from the beginning
+     * @returns A fast pagination result object containing:
+     * - `cursor` - identifier for the next page, or null if no more pages
+     * - `results` - An array of records for the current page
+     */
+    static async cursorPaginate(opts) {
+        return await this.query().cursorPaginate(opts);
+    }
     /**
      * Forces use of a database connection (e.g. 'primary') during the query.
      *

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

@@ -1225,7 +1225,7 @@ export default class Query {
         const pageCount = Math.ceil(recordCount / pageSize);
         const query = this.orderStatements.length
             ? this
-            : this.order({ [this.namespacedPrimaryKey]: 'asc' });
+            : this.order({ [this.namespacedPrimaryKey]: 'desc' });
         const results = await query
             .limit(pageSize)
             .offset(((page - 1) * pageSize))
@@ -1238,11 +1238,17 @@ export default class Query {
         };
     }
     /**
-     * Fast paginates the results of your query using cursor-based pagination,
+     * @deprecated Use {@link cursorPaginate} instead.
+     *
+     * Paginates the results of your query using cursor-based pagination,
      * accepting a pageSize and cursor argument. This method
      * provides better performance for large datasets by using cursor-based
      * pagination instead of offset-based pagination.
      *
+     * Default order is ascending primary key. If an order has already been
+     * set on the query, and it includes the primary key (e.g.: `id: 'asc'`),
+     * then the implicit primary key ordering will be omitted.
+     *
      * ```ts
      * // First page (using undefined to start from beginning)
      * const firstPage = await User.order('email').scrollPaginate({ pageSize: 100, cursor: undefined })
@@ -1259,13 +1265,53 @@ export default class Query {
      * })
      * ```
      *
-     * @param opts - Fast pagination options
+     * @param opts - scroll pagination options
      * @param opts.pageSize - the number of results per page (optional)
      * @param opts.cursor - identifier of where to start the next page; undefined to start from the beginning; null when no more pages
      * @returns results.cursor - identifier for the next page, or null if no more pages
      * @returns results.results - An array of records for the current page
      */
     async scrollPaginate(opts) {
+        const orderIncludesPrimaryKey = this.orderStatements.some(orderStatement => orderStatement.column === this.dreamClass.primaryKey ||
+            orderStatement.column === this.namespacedPrimaryKey);
+        const query = orderIncludesPrimaryKey
+            ? this
+            : this.order({ [this.namespacedPrimaryKey]: 'asc' });
+        return await query.cursorPaginate(opts);
+    }
+    /**
+     * Paginates the results of your query using cursor-based pagination,
+     * accepting a pageSize and cursor argument. This method
+     * provides better performance for large datasets by using cursor-based
+     * pagination instead of offset-based pagination.
+     *
+     * Default order is descending primary key. If an order has already been
+     * set on the query, and it includes the primary key (e.g.: `id: 'asc'`),
+     * then the implicit primary key ordering will be omitted.
+     *
+     * ```ts
+     * // First page (using undefined to start from beginning)
+     * const firstPage = await User.order('email').cursorPaginate({ pageSize: 100, cursor: undefined })
+     * firstPage.results
+     * // [ { User{id: 777}, User{id: 776}, ...}]
+     *
+     * firstPage.cursor
+     * // "100" (or null if no more pages)
+     *
+     * // Next page using cursor from previous result
+     * const nextPage = await User.order('email').cursorPaginate({
+     *   pageSize: 100,
+     *   cursor: firstPage.cursor
+     * })
+     * ```
+     *
+     * @param opts - cursor pagination options
+     * @param opts.pageSize - the number of results per page (optional)
+     * @param opts.cursor - identifier of where to start the next page; undefined to start from the beginning; null when no more pages
+     * @returns results.cursor - identifier for the next page, or null if no more pages
+     * @returns results.results - An array of records for the current page
+     */
+    async cursorPaginate(opts) {
         const options = opts;
         const pageSize = Math.max(0, options.pageSize ?? 0) || DreamApp.getOrFail().paginationPageSize;
         if (options === null)
@@ -1280,53 +1326,97 @@ export default class Query {
             orderStatement.column === this.namespacedPrimaryKey);
         let query = orderIncludesPrimaryKey
             ? this
-            : this.order({ [this.namespacedPrimaryKey]: 'asc' });
+            : this.order({ [this.namespacedPrimaryKey]: 'desc' });
         if (options.cursor) {
             const orderStatements = query.orderStatements;
-            /**
-             * if there is only one ordering, then that is the primary key (either added above or in the original),
-             * so we don't need to pluck values, and all we need is the primary key that we already have in the cursor
-             */
-            const endOfPreviousPageComparisonValues = orderStatements.length === 1
-                ? [options.cursor]
-                : (await query
+            if (orderStatements.length === 1) {
+                /**
+                 * Since we add a primary key above if it wasn't already included, we know
+                 * that if there is only one order statement, then it must be ordering on
+                 * the primary key
+                 */
+                const orderStatement = orderStatements[0];
+                switch (orderStatement.direction) {
+                    case 'asc':
+                        query = query.where({
+                            [orderStatement.column]: ops.greaterThan(options.cursor),
+                        });
+                        break;
+                    case 'desc':
+                        query = query.where({
+                            [orderStatement.column]: ops.lessThan(options.cursor),
+                        });
+                        break;
+                }
+            }
+            else {
+                const endOfPreviousPageComparisonValues = (await query
                     .removeDefaultScopeExceptOnAssociations(SOFT_DELETE_SCOPE_NAME)
                     .where({ [this.namespacedPrimaryKey]: options.cursor })
                     .limit(1)
                     .order(null)
-                    .pluck(...orderStatements.map(orderStatement => orderStatement.column)))[0] || [];
-            endOfPreviousPageComparisonValues.forEach((valueToCompare, index) => {
-                const orderStatement = orderStatements[index];
-                if (orderStatement.column === this.dreamClass.primaryKey ||
-                    orderStatement.column === this.namespacedPrimaryKey) {
-                    switch (orderStatement.direction) {
-                        case 'asc':
-                            query = query.where({
-                                [orderStatement.column]: ops.greaterThan(valueToCompare),
-                            });
-                            break;
-                        case 'desc':
-                            query = query.where({
-                                [orderStatement.column]: ops.lessThan(valueToCompare),
-                            });
-                            break;
-                    }
-                }
-                else {
-                    switch (orderStatement.direction) {
-                        case 'asc':
-                            query = query.where({
-                                [orderStatement.column]: ops.greaterThanOrEqualTo(valueToCompare),
-                            });
-                            break;
-                        case 'desc':
-                            query = query.where({
-                                [orderStatement.column]: ops.lessThanOrEqualTo(valueToCompare),
-                            });
-                            break;
+                    .pluck(...orderStatements.map(orderStatement => orderStatement.column)))[0];
+                if (endOfPreviousPageComparisonValues) {
+                    const whereAnyMaybeEqualArray = [];
+                    for (let index = 0; index < endOfPreviousPageComparisonValues.length; index++) {
+                        /**
+                         * This nested loop enables us to give priority to the left-most order clause,
+                         * then the left-most and next left-most, etc., replicating what ordering on
+                         * multiple clauses does:
+                         *
+                         *  const results = await Pet.query()
+                         *    .leftJoin('user')
+                         *    // The primary key is implicitly added if not explicitly present, so these two
+                         *    // order clauses appear in the query with an additional primary key clause.
+                         *    // This supports pagination when the earlier order clauses match multiple records.
+                         *    .order({ 'pets.name': 'asc', 'user.id': 'asc' })
+                         *    .cursorPaginate({ pageSize: 2, cursor: undefined })
+                         *
+                         * Results in:
+                         *
+                         * SELECT
+                         * 	"pets".*
+                         * FROM
+                         * 	"pets"
+                         * 	LEFT JOIN "users" AS "user" ON "pets"."user_id" = "user"."id"
+                         * 		AND "user"."deleted_at" IS NULL
+                         * WHERE ("pets"."deleted_at" IS NULL
+                         * 	AND (
+                         *    "pets"."name" > $1
+                         * 		OR (
+                         *    "pets"."name" = $2 AND "user"."id" > $3
+                         * 		) OR (
+                         *    "pets"."name" = $4 AND "user"."id" = $5 AND "pets"."id" < $6
+                         *   )))
+                         * ORDER BY
+                         * 	"pets"."name" ASC nulls FIRST,
+                         * 	"user"."id" ASC nulls FIRST,
+                         * 	"pets"."id" DESC nulls LAST
+                         * LIMIT $7
+                         */
+                        const whereAnyMaybeEqual = {};
+                        whereAnyMaybeEqualArray.push(whereAnyMaybeEqual);
+                        for (let nestedIndex = 0; nestedIndex <= index; nestedIndex++) {
+                            const valueToCompare = endOfPreviousPageComparisonValues[nestedIndex];
+                            const orderStatement = orderStatements[nestedIndex];
+                            if (nestedIndex < index) {
+                                whereAnyMaybeEqual[orderStatement.column] = valueToCompare;
+                            }
+                            else if (nestedIndex === index) {
+                                switch (orderStatement.direction) {
+                                    case 'asc':
+                                        whereAnyMaybeEqual[orderStatement.column] = ops.greaterThan(valueToCompare);
+                                        break;
+                                    case 'desc':
+                                        whereAnyMaybeEqual[orderStatement.column] = ops.lessThan(valueToCompare);
+                                        break;
+                                }
+                            }
+                        }
                     }
+                    query = query.whereAny(whereAnyMaybeEqualArray);
                 }
-            });
+            }
         }
         const results = await query.limit(pageSize).all();
         return {

package/dist/esm/src/helpers/cli/generateMigrationContent.js

@@ -295,12 +295,18 @@ function generateIdStr({ primaryKeyType }) {
         .defaultTo(sql\`uuidv7()\`),
     )`;
         case 'uuid4':
-        case 'uuid':
             return `\
 .addColumn('id', 'uuid', col =>
       col
         .primaryKey()
         .defaultTo(sql\`gen_random_uuid()\`),
+    )`;
+        case 'uuid':
+            return `\
+.addColumn('id', 'uuid', col =>
+      col
+        .primaryKey()
+        .defaultTo(sql\`uuid_generate_v4()\`),
     )`;
         default:
             return `.addColumn('id', '${primaryKeyType}', col => col.primaryKey())`;