@rvoh/dream 1.9.4 → 1.10.0

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

@@ -5,11 +5,11 @@ const pluralize_esm_1 = require("pluralize-esm");
 const serializerGlobalNameFromFullyQualifiedModelName_js_1 = require("../../serializer/helpers/serializerGlobalNameFromFullyQualifiedModelName.js");
 const camelize_js_1 = require("../camelize.js");
 const globalClassNameFromFullyQualifiedModelName_js_1 = require("../globalClassNameFromFullyQualifiedModelName.js");
+const pascalize_js_1 = require("../pascalize.js");
 const relativeDreamPath_js_1 = require("../path/relativeDreamPath.js");
 const snakeify_js_1 = require("../snakeify.js");
 const standardizeFullyQualifiedModelName_js_1 = require("../standardizeFullyQualifiedModelName.js");
 const uniq_js_1 = require("../uniq.js");
-const pascalize_js_1 = require("../pascalize.js");
 function generateDreamContent({ fullyQualifiedModelName, columnsWithTypes, fullyQualifiedParentName, serializer, includeAdminSerializers, connectionName = 'default', }) {
     fullyQualifiedModelName = (0, standardizeFullyQualifiedModelName_js_1.default)(fullyQualifiedModelName);
     const modelClassName = (0, globalClassNameFromFullyQualifiedModelName_js_1.default)(fullyQualifiedModelName);
@@ -35,17 +35,19 @@ function generateDreamContent({ fullyQualifiedModelName, columnsWithTypes, fully
         const fullyQualifiedAssociatedModelName = (0, standardizeFullyQualifiedModelName_js_1.default)(attributeName);
         const associationModelName = (0, globalClassNameFromFullyQualifiedModelName_js_1.default)(fullyQualifiedAssociatedModelName);
         const associationImportStatement = importStatementForModel(fullyQualifiedModelName, fullyQualifiedAssociatedModelName);
-        const associationName = (0, camelize_js_1.default)(associationModelName);
         if (!attributeType)
             throw new Error(`must pass a column type for ${attributeName} (i.e. ${attributeName}:string)`);
         switch (attributeType) {
-            case 'belongs_to':
+            case 'belongs_to': {
                 modelImportStatements.push(associationImportStatement);
+                const associationName = (0, camelize_js_1.default)(fullyQualifiedAssociatedModelName.split('/').pop());
+                const associationForeignKey = `${associationName}Id`;
                 return `
-@deco.BelongsTo('${fullyQualifiedAssociatedModelName}'${descriptors.includes('optional') ? ', { optional: true }' : ''})
+@deco.BelongsTo('${fullyQualifiedAssociatedModelName}', { on: '${associationForeignKey}'${descriptors.includes('optional') ? ', optional: true' : ''} })
 public ${associationName}: ${associationModelName}${descriptors.includes('optional') ? ' | null' : ''}
-public ${associationName}Id: DreamColumn<${modelClassName}, '${associationName}Id'>
+public ${associationForeignKey}: DreamColumn<${modelClassName}, '${associationName}Id'>
 `;
+            }
             case 'has_one':
             case 'has_many':
                 return '';

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

@@ -32,6 +32,7 @@ function generateFactoryContent({ fullyQualifiedModelName, columnsWithTypes, })
             throw new Error(`Must pass a column type for ${attributeName} (i.e. ${attributeName}:string)`);
         switch (attributeType) {
             case 'belongs_to': {
+                const attributeVariable = (0, camelize_js_1.default)(attributeName.split('/').pop());
                 const fullyQualifiedAssociatedModelName = (0, standardizeFullyQualifiedModelName_js_1.default)(attributeName);
                 const associationModelName = (0, globalClassNameFromFullyQualifiedModelName_js_1.default)(fullyQualifiedAssociatedModelName);
                 const associationFactoryImportStatement = `import create${associationModelName} from '${(0, relativeDreamPath_js_1.default)('factories', 'factories', fullyQualifiedModelName, fullyQualifiedAssociatedModelName)}'`;

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

@@ -21,30 +21,20 @@ function generateMigrationContent({ connectionName = 'default', table, columnsWi
         // instead, we'll add a check constraint that uses the STI child class name
         const optional = userWantsThisOptional || !!stiChildClassName;
         const sqlAttributeType = getAttributeType(attributeType, descriptors);
-        let attributeName = (0, snakeify_js_1.default)(nonStandardAttributeName);
-        if (attributeName === undefined)
-            return acc;
         if (attributeType !== undefined && ['has_one', 'has_many'].includes(attributeType))
             return acc;
         if (attributeType === 'citext')
             requireCitextExtension = true;
-        if (stiChildClassName && !userWantsThisOptional) {
-            checkConstraints.push(`
-
-  await db.schema
-    .alterTable('${table}')
-    .addCheckConstraint(
-      '${table}_not_null_${attributeName}',
-      sql\`type != '${stiChildClassName}' OR ${attributeName} IS NOT NULL\`,
-    )
-    .execute()`);
-        }
+        if (nonStandardAttributeName === undefined)
+            return acc;
+        let attributeName = (0, snakeify_js_1.default)(nonStandardAttributeName);
         switch (attributeType) {
             case 'belongs_to':
                 columnDefs.push(generateBelongsToStr(connectionName, attributeName, {
                     primaryKeyType,
                     optional,
                 }));
+                attributeName = (0, snakeify_js_1.default)(nonStandardAttributeName.split('/').pop());
                 attributeName = associationNameToForeignKey(attributeName);
                 break;
             case 'enum':
@@ -78,7 +68,7 @@ function generateMigrationContent({ connectionName = 'default', table, columnsWi
                 break;
         }
         columnDrops.push(`.dropColumn('${attributeName}')`);
-        if (COLUMNS_TO_INDEX.includes(attributeName)) {
+        if (attributeType === 'belongs_to' || COLUMNS_TO_INDEX.includes(attributeName)) {
             const indexName = `${table}_${attributeName}`;
             indexDefs.push(`await db.schema
     .createIndex('${indexName}')
@@ -87,6 +77,17 @@ function generateMigrationContent({ connectionName = 'default', table, columnsWi
     .execute()`);
             indexDrops.push(`await db.schema.dropIndex('${indexName}').execute()`);
         }
+        if (stiChildClassName && !userWantsThisOptional) {
+            checkConstraints.push(`
+
+  await db.schema
+    .alterTable('${table}')
+    .addCheckConstraint(
+      '${table}_not_null_${attributeName}',
+      sql\`type != '${stiChildClassName}' OR ${attributeName} IS NOT NULL\`,
+    )
+    .execute()`);
+        }
         return acc;
     }, { columnDefs: [], columnDrops: [], indexDefs: [], indexDrops: [] });
     if (!table) {
@@ -256,7 +257,7 @@ function generateBelongsToStr(connectionName, associationName, { primaryKeyType,
     const dbDriverClass = Query_js_1.default.dbDriverClass(connectionName);
     const dataType = dbDriverClass.foreignKeyTypeFromPrimaryKey(primaryKeyType);
     const references = (0, pluralize_esm_1.default)(associationName.replace(/\//g, '_').replace(/_id$/, ''));
-    return `.addColumn('${associationNameToForeignKey(associationName)}', '${dataType}', col => col.references('${references}.id').onDelete('restrict')${optional ? '' : '.notNull()'})`;
+    return `.addColumn('${associationNameToForeignKey(associationName.split('/').pop())}', '${dataType}', col => col.references('${references}.id').onDelete('restrict')${optional ? '' : '.notNull()'})`;
 }
 function generateIdStr({ primaryKeyType }) {
     switch (primaryKeyType) {

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

@@ -54,7 +54,7 @@ function generateSerializerContent({ fullyQualifiedModelName, columnsWithTypes =
             return '';
         if (['belongs_to', 'has_one', 'has_many'].includes(type))
             return '';
-        return `\n    ${attribute(name, type, attr, stiBaseSerializer)}`;
+        return `\n    ${attribute(modelClassName, name, type, attr, stiBaseSerializer)}`;
     })
         .join('')}`;
     return `${dreamImport}${additionalImportsStr}${relatedModelImport}${additionalModelImports.join('')}
@@ -69,9 +69,9 @@ ${summarySerializer.replace(summarySerializerClassName, adminSummarySerializerCl
 ${defaultSerializer.replace(serializerClassName, adminSerializerClassName).replace(summarySerializerClassName, adminSummarySerializerClassName)}`}
 `;
 }
-function attribute(name, type, attr, stiBaseSerializer) {
+function attribute(modelClassName, name, type, attr, stiBaseSerializer) {
     if (name === 'type' && stiBaseSerializer) {
-        return `.attribute('type', { openapi: { type: 'string', enum: [StiChildClass.sanitizedName] } })`;
+        return `.attribute('type', { openapi: { type: 'string', enum: [(StiChildClass ?? ${modelClassName}).sanitizedName] } })`;
     }
     switch (type) {
         case 'json':

package/dist/cjs/src/helpers/comparisonKey.js

@@ -3,5 +3,20 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = comparisonKey;
 const Dream_js_1 = require("../Dream.js");
 function comparisonKey(val, toKey = undefined) {
-    return val instanceof Dream_js_1.default ? val.comparisonKey : toKey ? toKey(val) : val;
+    if (val instanceof Dream_js_1.default)
+        return val.comparisonKey;
+    if (toKey)
+        return toKey(val);
+    if (val === null)
+        return null;
+    if (val === undefined)
+        return undefined;
+    switch (typeof val) {
+        case 'number':
+        case 'string':
+        case 'bigint':
+            return val;
+        default:
+            return val.toString();
+    }
 }

package/dist/cjs/src/helpers/percent.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = percent;
+const round_js_1 = require("./round.js");
+function percent(numerator, denominator, precision) {
+    if (!numerator || !denominator)
+        return 0;
+    const percent = (numerator / denominator) * 100;
+    return precision ? (0, round_js_1.default)(percent, precision) : percent;
+}

package/dist/cjs/src/helpers/sort.js

@@ -17,8 +17,5 @@ const sortBy_js_1 = require("./sortBy.js");
  * ```
  */
 function sort(array) {
-    if (typeof array[0] === 'bigint') {
-        return (0, sortBy_js_1.default)(array, a => String(a));
-    }
     return (0, sortBy_js_1.default)(array, a => a);
 }

package/dist/cjs/src/helpers/sortBy.js

@@ -2,6 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.UnsupportedValueFromComparisonFunction = void 0;
 exports.default = sortBy;
+const CalendarDate_js_1 = require("./CalendarDate.js");
+const DateTime_js_1 = require("./DateTime.js");
 /**
  * Returns a copy of the array, sorted by the value returned by calling the function in the second argument on each element in the array
  * Returns a copy of the array sorted by the return value of the function passed as the second argument.
@@ -26,10 +28,17 @@ function sortBy(array, valueToCompare) {
     return arrayClone.sort((a, b) => {
         const aPrime = valueToCompare(a);
         const bPrime = valueToCompare(b);
-        if (typeof aPrime === 'string' && typeof bPrime === 'string')
-            return aPrime.localeCompare(bPrime);
         if (typeof aPrime === 'number' && typeof bPrime === 'number')
             return aPrime - bPrime;
+        if (typeof aPrime === 'bigint' && typeof bPrime === 'bigint')
+            return aPrime > bPrime ? 1 : aPrime < bPrime ? -1 : 0;
+        if (typeof aPrime === 'string' && typeof bPrime === 'string')
+            return aPrime.localeCompare(bPrime);
+        if (aPrime instanceof DateTime_js_1.DateTime && bPrime instanceof DateTime_js_1.DateTime)
+            return aPrime.valueOf() - bPrime.valueOf();
+        if ((aPrime instanceof DateTime_js_1.DateTime || aPrime instanceof CalendarDate_js_1.default) &&
+            (bPrime instanceof DateTime_js_1.DateTime || bPrime instanceof CalendarDate_js_1.default))
+            return (aPrime.toISO() ?? '').localeCompare(bPrime.toISO() ?? '');
         throw new UnsupportedValueFromComparisonFunction(aPrime, bPrime);
     });
 }

package/dist/cjs/src/helpers/uniq.js

@@ -4,13 +4,10 @@ exports.default = uniq;
 const comparisonKey_js_1 = require("./comparisonKey.js");
 function uniq(arr, toKey = undefined) {
     const map = arr.reduce((acc, val) => {
-        const baseKey = (0, comparisonKey_js_1.default)(val, toKey);
-        // Prefix with underscore to ensure that the values cannot be _interpreted_ as integers.
-        // If they can be interpreted as integers, then the keys are ordered not by the
-        // order in which they were added, but in ascending numerical order.
-        const key = typeof baseKey === 'string' ? baseKey : `_${baseKey}`;
-        acc[key] ||= val;
+        const key = (0, comparisonKey_js_1.default)(val, toKey);
+        if (!acc.has(key))
+            acc.set(key, val);
         return acc;
-    }, {});
-    return Object.values(map);
+    }, new Map());
+    return [...map.values()];
 }

package/dist/cjs/src/index.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.globalClassNameFromFullyQualifiedModelName = exports.Env = exports.DreamLogos = exports.DateTime = exports.compact = exports.cloneDeepSafe = exports.generateDream = exports.capitalize = exports.camelize = exports.CalendarDate = exports.Benchmark = exports.ValidationError = exports.MissingSerializersDefinition = exports.RecordNotFound = exports.GlobalNameNotSet = exports.NotNullViolation = exports.DataTypeColumnTypeMismatch = exports.DataIncompatibleWithDatabaseField = exports.ColumnOverflow = exports.CheckConstraintViolation = exports.CreateOrFindByFailedToCreateAndFind = exports.NonLoadedAssociation = exports.Encrypt = exports.PostgresQueryDriver = exports.KyselyQueryDriver = exports.QueryDriverBase = exports.Query = exports.DreamTransaction = exports.openapiShorthandPrimitiveTypes = exports.openapiPrimitiveTypes = exports.DreamConst = exports.Dream = exports.DreamAppAllowedPackageManagersEnumValues = exports.DreamApp = exports.lookupClassByGlobalName = exports.DreamImporter = exports.Decorators = exports.STI = exports.SoftDelete = exports.ReplicaSafe = exports.validateTable = exports.validateColumn = exports.DreamMigrationHelpers = exports.untypedDb = exports.pgErrorType = exports.dreamDbConnections = exports.closeAllDbConnections = exports.DreamCLI = exports.CliFileWriter = exports.DreamBin = void 0;
-exports.ObjectSerializerBuilder = exports.DreamSerializerBuilder = exports.ObjectSerializer = exports.DreamSerializer = exports.serializerNameFromFullyQualifiedModelName = exports.isDreamSerializer = exports.inferSerializersFromDreamClassOrViewModelClass = exports.inferSerializerFromDreamOrViewModel = exports.ops = exports.uniq = exports.uncapitalize = exports.expandStiClasses = exports.standardizeFullyQualifiedModelName = exports.sortObjectByValue = exports.sortObjectByKey = exports.sortBy = exports.sort = exports.snakeify = exports.round = exports.range = exports.Range = exports.sharedPathPrefix = exports.relativeDreamPath = exports.dreamPath = exports.pascalize = exports.normalizeUnicode = exports.loadRepl = exports.isEmpty = exports.intersection = exports.hyphenize = exports.groupBy = void 0;
+exports.ObjectSerializerBuilder = exports.DreamSerializerBuilder = exports.ObjectSerializer = exports.DreamSerializer = exports.serializerNameFromFullyQualifiedModelName = exports.isDreamSerializer = exports.inferSerializersFromDreamClassOrViewModelClass = exports.inferSerializerFromDreamOrViewModel = exports.ops = exports.uniq = exports.uncapitalize = exports.expandStiClasses = exports.standardizeFullyQualifiedModelName = exports.sortObjectByValue = exports.sortObjectByKey = exports.sortBy = exports.sort = exports.snakeify = exports.round = exports.range = exports.Range = exports.percent = exports.sharedPathPrefix = exports.relativeDreamPath = exports.dreamPath = exports.pascalize = exports.normalizeUnicode = exports.loadRepl = exports.isEmpty = exports.intersection = exports.hyphenize = exports.groupBy = void 0;
 var index_js_1 = require("./bin/index.js");
 Object.defineProperty(exports, "DreamBin", { enumerable: true, get: function () { return index_js_1.default; } });
 var CliFileWriter_js_1 = require("./cli/CliFileWriter.js");
@@ -118,6 +118,8 @@ var relativeDreamPath_js_1 = require("./helpers/path/relativeDreamPath.js");
 Object.defineProperty(exports, "relativeDreamPath", { enumerable: true, get: function () { return relativeDreamPath_js_1.default; } });
 var sharedPathPrefix_js_1 = require("./helpers/path/sharedPathPrefix.js");
 Object.defineProperty(exports, "sharedPathPrefix", { enumerable: true, get: function () { return sharedPathPrefix_js_1.default; } });
+var percent_js_1 = require("./helpers/percent.js");
+Object.defineProperty(exports, "percent", { enumerable: true, get: function () { return percent_js_1.default; } });
 var range_js_1 = require("./helpers/range.js");
 Object.defineProperty(exports, "Range", { enumerable: true, get: function () { return range_js_1.Range; } });
 Object.defineProperty(exports, "range", { enumerable: true, get: function () { return range_js_1.default; } });

package/dist/esm/src/Dream.js

@@ -41,6 +41,7 @@ import CreateOrUpdateByFailedToCreateAndUpdate from './errors/CreateOrUpdateByFa
 import GlobalNameNotSet from './errors/dream-app/GlobalNameNotSet.js';
 import DreamMissingRequiredOverride from './errors/DreamMissingRequiredOverride.js';
 import NonExistentScopeProvidedToResort from './errors/NonExistentScopeProvidedToResort.js';
+import RecordNotFound from './errors/RecordNotFound.js';
 import MissingSerializersDefinition from './errors/serializers/MissingSerializersDefinition.js';
 import CalendarDate from './helpers/CalendarDate.js';
 import cloneDeepSafe from './helpers/cloneDeepSafe.js';
@@ -3218,6 +3219,61 @@ export default class Dream {
     load(...args) {
         return new LoadBuilder(this).load(...args);
     }
+    /**
+     * If the association is already loaded on the instance, it returns the loaded value
+     * immediately without making a database query. If the association is not loaded,
+     * it performs a database query to fetch the association.
+     *
+     * If a query is performed, the association is set on the model so that future calls to
+     * access this association can access the already loaded value.
+     *
+     * ```ts
+     * // return the already loaded user if it exists or fetch it from the database otherwise
+     * const user = await post.associationOrFail('user')
+     * ```
+     *
+     * @param associationName - The name of the BelongsTo or HasOne association
+     * @returns The associated model instance or null
+     */
+    async association(associationName) {
+        if (!this.loaded(associationName)) {
+            const association = this.getAssociationMetadata(associationName);
+            if (association?.type === 'HasMany') {
+                this[associationName] = (await this.associationQuery(associationName).all());
+            }
+            else {
+                this[associationName] = (await this.associationQuery(associationName).first());
+            }
+        }
+        return this[associationName];
+    }
+    /**
+     * If the association is already loaded on the instance, it returns the loaded value
+     * immediately without making a database query. If the association is not loaded,
+     * it performs a database query to fetch the association.
+     *
+     * Unlike `association`, this method throws an exception if no associated
+     * record is found, guaranteeing a non-null result.
+     *
+     * If a query is performed, the association is set on the model so that future calls to
+     * access this association can access the already loaded value.
+     *
+     * ```ts
+     * // return the already loaded user if it exists or fetch it from the database otherwise,
+     * // throwing RecordNotFound either way if the associated model does not exist
+     * const user = await post.associationOrFail('user')
+     * ```
+     *
+     * @param associationName - The name of the BelongsTo or HasOne association
+     * @returns The associated model instance (never null)
+     * @throws RecordNotFound if no associated record exists
+     */
+    async associationOrFail(associationName) {
+        const response = await this.association(associationName);
+        if (this[associationName] === null)
+            throw new RecordNotFound(this['sanitizedConstructorName']);
+        return response;
+    }
     /**
      * Recursively loads all Dream associations referenced by `rendersOne` and `rendersMany`
      * in a DreamSerializer. This traverses the entire content tree of serializers to automatically
@@ -3278,8 +3334,8 @@ export default class Dream {
      * 4. the individual query becomes more complex the more associations are included
      * 5. associations loading associations loading associations could result in exponential amounts of data; in those cases, `.load(...).findEach(...)` avoids instantiating massive amounts of data at once
      *
-     * NOTE: {@link Dream.leftJoinPreload} is often a preferrable way of achieving the
-     * same goal.
+     * Note: Left join loading loads all data in a single SQL query but has trade-offs compared
+     * to regular preloading. See {@link Dream.leftJoinPreload} for details about limitations.
      *
      * ```ts
      * await user
@@ -3315,6 +3371,9 @@ export default class Dream {
      * This method analyzes the serializer (specified by `serializerKey` or 'default') and
      * automatically preloads all associations that will be needed during serialization.
      *
+     * Note: Left join loading loads all data in a single SQL query but has trade-offs compared
+     * to regular preloading. See {@link Dream.leftJoinPreload} for details about limitations.
+     *
      * ```ts
      * // Instead of manually specifying all associations:
      * await User.preload('posts', 'comments', 'replies').all()

package/dist/esm/src/bin/index.js

@@ -22,6 +22,12 @@ export default class DreamBin {
             await Query.dbDriverClass(connectionName).dbDrop(connectionName);
         }
     }
+    static async dbEnsureAllMigrationsHaveBeenRun() {
+        const dreamApp = DreamApp.getOrFail();
+        for (const connectionName of Object.keys(dreamApp.dbCredentials)) {
+            await Query.dbDriverClass(connectionName).ensureAllMigrationsHaveBeenRun(connectionName);
+        }
+    }
     static async dbMigrate() {
         const dreamApp = DreamApp.getOrFail();
         for (const connectionName of Object.keys(dreamApp.dbCredentials)) {

package/dist/esm/src/cli/index.js

@@ -32,7 +32,7 @@ ${INDENT}
 ${INDENT}    - decimal:
 ${INDENT}    - decimal[]:
 ${INDENT}        scale,precision is required, e.g.: volume:decimal:3,2 or volume:decimal:3,2:optional
-${INDENT}        
+${INDENT}
 ${INDENT}        leveraging arrays, add the "[]" suffix, e.g.: volume:decimal[]:3,2
 ${INDENT}
 ${INDENT}    - enum:
@@ -71,7 +71,7 @@ export default class DreamCLI {
             .description('sync introspects your database, updating your schema to reflect, and then syncs the new schema with the installed dream node module, allowing it provide your schema to the underlying kysely integration')
             .option('--schema-only')
             .action(async (options = {}) => {
-            await initializeDreamApp();
+            await initializeDreamApp({ bypassDreamIntegrityChecks: true });
             await DreamBin.sync(() => { }, options);
             process.exit();
         });
@@ -93,7 +93,7 @@ export default class DreamCLI {
             .option('--connection-name <connectionName>', 'the connection name you wish to use for your migration')
             .argument('[columnsWithTypes...]', columnsWithTypesDescriptionForMigration)
             .action(async (migrationName, columnsWithTypes, options) => {
-            await initializeDreamApp();
+            await initializeDreamApp({ bypassDreamIntegrityChecks: true });
             await DreamBin.generateMigration(migrationName, columnsWithTypes, options.connectionName || 'default');
             process.exit();
         });
@@ -109,7 +109,7 @@ export default class DreamCLI {
             .argument('<modelName>', 'the name of the model to create, e.g. Post or Settings/CommunicationPreferences')
             .argument('[columnsWithTypes...]', columnsWithTypesDescription)
             .action(async (modelName, columnsWithTypes, options) => {
-            await initializeDreamApp();
+            await initializeDreamApp({ bypassDreamIntegrityChecks: true });
             await DreamBin.generateDream(modelName, columnsWithTypes, options);
             process.exit();
         });
@@ -126,7 +126,7 @@ ${INDENT}    to extend the Room model in src/app/models/Room: Room
 ${INDENT}    to extend the Coach model in src/app/models/Health/Coach: Health/Coach`)
             .argument('[columnsWithTypes...]', columnsWithTypesDescription)
             .action(async (childModelName, extendsWord, parentModelName, columnsWithTypes, options) => {
-            await initializeDreamApp();
+            await initializeDreamApp({ bypassDreamIntegrityChecks: true });
             if (extendsWord !== 'extends')
                 throw new Error('Expecting: `<child-name> extends <parent-name> <columns-and-types>');
             await DreamBin.generateStiChild(childModelName, parentModelName, columnsWithTypes, options);
@@ -137,16 +137,24 @@ ${INDENT}    to extend the Coach model in src/app/models/Health/Coach: Health/Co
             .description('creates a new database, seeding from local .env or .env.test if NODE_ENV=test is set for env vars')
             .action(async () => {
             EnvInternal.setBoolean('BYPASS_DB_CONNECTIONS_DURING_INIT');
-            await initializeDreamApp({ bypassModelIntegrityCheck: true });
+            await initializeDreamApp({ bypassDreamIntegrityChecks: true });
             await DreamBin.dbCreate();
             process.exit();
         });
+        program
+            .command('db:integrity-check')
+            .description('db:integrity-check fails if migrations need to be run')
+            .action(async () => {
+            await initializeDreamApp({ bypassDreamIntegrityChecks: true });
+            await DreamBin.dbEnsureAllMigrationsHaveBeenRun();
+            process.exit();
+        });
         program
             .command('db:migrate')
             .description('db:migrate runs any outstanding database migrations')
             .option('--skip-sync', 'skips syncing local schema after running migrations')
             .action(async ({ skipSync }) => {
-            await initializeDreamApp({ bypassModelIntegrityCheck: true });
+            await initializeDreamApp({ bypassDreamIntegrityChecks: true });
             await DreamBin.dbMigrate();
             if (EnvInternal.isDevelopmentOrTest && !skipSync) {
                 await DreamBin.sync(onSync);
@@ -159,7 +167,7 @@ ${INDENT}    to extend the Coach model in src/app/models/Health/Coach: Health/Co
             .option('--steps <number>', 'number of steps back to travel', myParseInt, 1)
             .option('--skip-sync', 'skips syncing local schema after running migrations')
             .action(async ({ steps, skipSync }) => {
-            await initializeDreamApp({ bypassModelIntegrityCheck: true });
+            await initializeDreamApp({ bypassDreamIntegrityChecks: true });
             await DreamBin.dbRollback({ steps });
             if (EnvInternal.isDevelopmentOrTest && !skipSync) {
                 await DreamBin.sync(onSync);
@@ -171,7 +179,7 @@ ${INDENT}    to extend the Coach model in src/app/models/Health/Coach: Health/Co
             .description('drops the database, seeding from local .env or .env.test if NODE_ENV=test is set for env vars')
             .action(async () => {
             EnvInternal.setBoolean('BYPASS_DB_CONNECTIONS_DURING_INIT');
-            await initializeDreamApp({ bypassModelIntegrityCheck: true });
+            await initializeDreamApp({ bypassDreamIntegrityChecks: true });
             await DreamBin.dbDrop();
             process.exit();
         });
@@ -180,11 +188,11 @@ ${INDENT}    to extend the Coach model in src/app/models/Health/Coach: Health/Co
             .description('runs db:drop (safely), then db:create, db:migrate, and db:seed')
             .action(async () => {
             EnvInternal.setBoolean('BYPASS_DB_CONNECTIONS_DURING_INIT');
-            await initializeDreamApp({ bypassModelIntegrityCheck: true });
+            await initializeDreamApp({ bypassDreamIntegrityChecks: true });
             await DreamBin.dbDrop();
             await DreamBin.dbCreate();
             EnvInternal.unsetBoolean('BYPASS_DB_CONNECTIONS_DURING_INIT');
-            await initializeDreamApp({ bypassModelIntegrityCheck: true });
+            await initializeDreamApp({ bypassDreamIntegrityChecks: true });
             await DreamBin.dbMigrate();
             await DreamBin.sync(onSync);
             await seedDb();

package/dist/esm/src/db/migration-helpers/DreamMigrationHelpers.js

@@ -1,5 +1,24 @@
 import { sql } from 'kysely';
 export default class DreamMigrationHelpers {
+    /**
+     * Rename a table and its associated primary key sequence.
+     *
+     * This method renames both the table and its primary key sequence to keep them
+     * in sync. When PostgreSQL creates a table with a serial or bigserial primary key,
+     * it automatically creates a sequence named `{tablename}_id_seq`. If you only rename
+     * the table, the sequence keeps the old name, which can cause confusion and issues.
+     *
+     * This method is only suitable for tables that have a serial or bigserial primary
+     * key column named 'id'.
+     *
+     * @param db - The Kysely database object passed into the migration up/down function
+     * @param from - The current name of the table to rename
+     * @param to - The new name for the table
+     */
+    static async renameTable(db, from, to) {
+        await db.schema.alterTable(from).renameTo(to).execute();
+        await sql `ALTER SEQUENCE ${from}_id_seq RENAME TO ${to}_id_seq`.execute(db);
+    }
     /**
      * Unique indexes cannot be populated by the same value even within a transaction,
      * but deferrable unique constraints can.

package/dist/esm/src/decorators/field/association/BelongsTo.js

@@ -20,14 +20,14 @@ import { applyGetterAndSetter, associationPrimaryKeyAccessors, blankAssociations
  * }
  * ```
  *
- * @param opts.foreignKey - A custom column name to use for the foreign key.
+ * @param opts.on - A custom column name to use for joining associations on.
  * @param opts.optional - Whether or not this association is optional. Defaults to false.
  * @param opts.polymorphic - If true, this association will be treated as a polymorphic association.
  * @param opts.primaryKeyOverride - A custom column name to use for the primary key.
  * @param opts.withoutDefaultScopes - A list of default scopes to bypass when loading this association
  */
 export default function BelongsTo(globalAssociationNameOrNames, opts = {}) {
-    const { foreignKey, optional = false, polymorphic = false, primaryKeyOverride = null, withoutDefaultScopes, } = opts;
+    const { on: foreignKey, optional = false, polymorphic = false, primaryKeyOverride = null, withoutDefaultScopes, } = opts;
     return function (_, context) {
         const key = context.name;
         context.addInitializer(function () {

package/dist/esm/src/decorators/field/association/HasMany.js

@@ -20,7 +20,7 @@ import { applyGetterAndSetter, associationPrimaryKeyAccessors, blankAssociations
  *
  * @param opts.dependent - Can be either "destroy" or undefined. If "destroy", this record will be cascade deleted if the base model is destroyed.
  * @param opts.distinct - Can be a column name, or else a boolean. If a column name, a distinct clause will be applied to the column. If true, a distinct clause will be applied to the primary key.
- * @param opts.foreignKey - A custom column name to use for the foreign key.
+ * @param opts.on - A custom column name to use for joining associations on.
  * @param opts.and - An and-clause to be applied when this association is loaded
  * @param opts.andNot - A not and-clause to be applied when this association is loaded
  * @param opts.andAny - An andAny clause to be applied when this association is loaded
@@ -34,7 +34,7 @@ import { applyGetterAndSetter, associationPrimaryKeyAccessors, blankAssociations
  * @param opts.withoutDefaultScopes - A list of default scopes to bypass when loading this association
  */
 export default function HasMany(globalAssociationNameOrNames, opts = {}) {
-    const { dependent, distinct, foreignKey, and, andNot, andAny, order, polymorphic = false, primaryKeyOverride = null, selfAnd, selfAndNot, source, through, withoutDefaultScopes, } = opts;
+    const { dependent, distinct, on: foreignKey, and, andNot, andAny, order, polymorphic = false, primaryKeyOverride = null, selfAnd, selfAndNot, source, through, withoutDefaultScopes, } = opts;
     return function (_, context) {
         const key = context.name;
         context.addInitializer(function () {

package/dist/esm/src/decorators/field/association/HasOne.js

@@ -19,7 +19,7 @@ import { applyGetterAndSetter, associationPrimaryKeyAccessors, blankAssociations
  * ```
  *
  * @param opts.dependent - Can be either "destroy" or undefined. If "destroy", this record will be cascade deleted if the base model is destroyed.
- * @param opts.foreignKey - A custom column name to use for the foreign key.
+ * @param opts.on - A custom column name to use for joining associations on.
  * @param opts.and - An and-clause to be applied when this association is loaded
  * @param opts.andNot - A not and-clause to be applied when this association is loaded
  * @param opts.andAny - An andAny clause to be applied when this association is loaded
@@ -32,7 +32,7 @@ import { applyGetterAndSetter, associationPrimaryKeyAccessors, blankAssociations
  * @param opts.withoutDefaultScopes - A list of default scopes to bypass when loading this association
  */
 export default function HasOne(globalAssociationNameOrNames, opts = {}) {
-    const { dependent, foreignKey, and, andNot, andAny, polymorphic = false, primaryKeyOverride = null, selfAnd, selfAndNot, source, through, withoutDefaultScopes, } = opts;
+    const { dependent, on: foreignKey, and, andNot, andAny, polymorphic = false, primaryKeyOverride = null, selfAnd, selfAndNot, source, through, withoutDefaultScopes, } = opts;
     return function (_, context) {
         const key = context.name;
         context.addInitializer(function () {

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

@@ -1215,7 +1215,10 @@ export default class Query {
         const recordCount = await this.count();
         const pageSize = opts.pageSize || DreamApp.getOrFail().paginationPageSize;
         const pageCount = Math.ceil(recordCount / pageSize);
-        const results = await this
+        const query = this.orderStatements.length
+            ? this
+            : this.order({ [this.namespacedPrimaryKey]: 'asc' });
+        const results = await query
             .limit(pageSize)
             .offset((page - 1) * pageSize)
             .all();

package/dist/esm/src/dream/QueryDriver/Base.js

@@ -20,6 +20,12 @@ export default class QueryDriverBase {
         this.connectionOverride = query['originalOpts'].connection;
         this.innerJoinDreamClasses = Object.freeze(query['originalOpts'].innerJoinDreamClasses || []);
     }
+    // eslint-disable-next-line @typescript-eslint/require-await
+    static async ensureAllMigrationsHaveBeenRun(
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    connectionName) {
+        throw new Error('override ensureAllMigrationsHaveBeenRun in child class');
+    }
     /**
      * migrate the database. Must respond to the NODE_ENV value.
      */

package/dist/esm/src/dream/QueryDriver/Kysely.js

@@ -13,7 +13,7 @@ import { CliFileWriter } from '../../cli/CliFileWriter.js';
 import DreamCLI from '../../cli/index.js';
 import { CHECK_VIOLATION, COLUMN_OVERFLOW, INVALID_INPUT_SYNTAX, NOT_NULL_VIOLATION, pgErrorType, } from '../../db/errors.js';
 import syncDbTypesFiles from '../../db/helpers/syncDbTypesFiles.js';
-import _db from '../../db/index.js';
+import { default as _db } from '../../db/index.js';
 import associationToGetterSetterProp from '../../decorators/field/association/associationToGetterSetterProp.js';
 import PackageManager from '../../dream-app/helpers/PackageManager.js';
 import DreamApp from '../../dream-app/index.js';
@@ -64,6 +64,7 @@ import softDeleteDream from '../internal/softDeleteDream.js';
 import sqlResultToDreamInstance from '../internal/sqlResultToDreamInstance.js';
 import Query from '../Query.js';
 import QueryDriverBase from './Base.js';
+import checkForNeedToBeRunMigrations from './helpers/kysely/checkForNeedToBeRunMigrations.js';
 import runMigration from './helpers/kysely/runMigration.js';
 export default class KyselyQueryDriver extends QueryDriverBase {
     // ATTENTION FRED
@@ -100,6 +101,14 @@ export default class KyselyQueryDriver extends QueryDriverBase {
             }),
         });
     }
+    static async ensureAllMigrationsHaveBeenRun(connectionName) {
+        const migrationsNeedToBeRun = await checkForNeedToBeRunMigrations({
+            connectionName,
+            dialectProvider: this.dialectProvider(connectionName, 'primary'),
+        });
+        if (migrationsNeedToBeRun)
+            throw new Error(`Migrations need to be run on ${connectionName} database`);
+    }
     /**
      * migrate the database. Must respond to the NODE_ENV value.
      */
@@ -694,9 +703,8 @@ export default class KyselyQueryDriver extends QueryDriverBase {
         return orderByDirection(direction);
     }
     buildUpdate(attributes) {
-        let kyselyQuery = this.dbFor('update')
-            .updateTable(this.query['tableName'])
-            .set(attributes);
+        let kyselyQuery = this.dbFor('update').updateTable(this.query['tableName']);
+        kyselyQuery = kyselyQuery.set(attributes);
         kyselyQuery = this.conditionallyAttachSimilarityColumnsToUpdate(kyselyQuery);
         const results = this.attachLimitAndOrderStatementsToNonSelectQuery(kyselyQuery);
         return new this.constructor(results.clone).buildCommon(results.kyselyQuery);