@rvoh/dream 1.9.4 → 1.10.0

package/dist/esm/src/dream/QueryDriver/helpers/kysely/checkForNeedToBeRunMigrations.js

@@ -0,0 +1,24 @@
+import { FileMigrationProvider, Migrator } from 'kysely';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { closeAllConnectionsForConnectionName } from '../../../../db/DreamDbConnection.js';
+import db from '../../../../db/index.js';
+import migrationFolderPath from './migrationFolderPath.js';
+export default async function checkForNeedToBeRunMigrations({ connectionName, dialectProvider, }) {
+    const migrationFolder = migrationFolderPath(connectionName);
+    // Ensure the migration folder exists
+    await fs.mkdir(migrationFolder, { recursive: true });
+    const kyselyDb = db(connectionName, 'primary', dialectProvider);
+    const migrator = new Migrator({
+        db: kyselyDb,
+        allowUnorderedMigrations: true,
+        provider: new FileMigrationProvider({
+            fs,
+            path,
+            migrationFolder,
+        }),
+    });
+    const result = (await migrator.getMigrations()).some(migrationInfo => !migrationInfo.executedAt);
+    await closeAllConnectionsForConnectionName(connectionName);
+    return result;
+}

package/dist/esm/src/dream/QueryDriver/helpers/kysely/migrationFolderPath.js

@@ -0,0 +1,8 @@
+import * as path from 'node:path';
+import DreamApp from '../../../../dream-app/index.js';
+export default function migrationFolderPath(connectionName) {
+    const dreamApp = DreamApp.getOrFail();
+    return connectionName === 'default'
+        ? path.join(dreamApp.projectRoot, dreamApp.paths.db, 'migrations')
+        : path.join(dreamApp.projectRoot, dreamApp.paths.db, 'migrations', connectionName);
+}

package/dist/esm/src/dream/QueryDriver/helpers/kysely/runMigration.js

@@ -1,16 +1,14 @@
 import { FileMigrationProvider, Migrator } from 'kysely';
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
+import DreamCLI from '../../../../cli/index.js';
 import colorize from '../../../../cli/logger/loggable/colorize.js';
 import { closeAllConnectionsForConnectionName, closeAllDbConnections, } from '../../../../db/DreamDbConnection.js';
 import db from '../../../../db/index.js';
 import DreamApp from '../../../../dream-app/index.js';
-import DreamCLI from '../../../../cli/index.js';
+import migrationFolderPath from './migrationFolderPath.js';
 export default async function runMigration({ connectionName, mode = 'migrate', dialectProvider, }) {
-    const dreamApp = DreamApp.getOrFail();
-    const migrationFolder = connectionName === 'default'
-        ? path.join(dreamApp.projectRoot, dreamApp.paths.db, 'migrations')
-        : path.join(dreamApp.projectRoot, dreamApp.paths.db, 'migrations', connectionName);
+    const migrationFolder = migrationFolderPath(connectionName);
     // Ensure the migration folder exists
     await fs.mkdir(migrationFolder, { recursive: true });
     const kyselyDb = db(connectionName, 'primary', dialectProvider);

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

@@ -1,11 +1,10 @@
-import { sql } from 'kysely';
 export default function orderByDirection(dir) {
     switch (dir) {
         case 'asc':
         case null:
-            return sql `asc nulls first`;
+            return (obj) => obj.asc().nullsFirst();
         case 'desc':
-            return sql `desc nulls last`;
+            return (obj) => obj.desc().nullsLast();
         default: {
             // protection so that if a new OrderDir is ever added, this will throw a type error at build time
             const _never = dir;

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

@@ -49,8 +49,8 @@ async function undestroyDreamWithTransaction(dream, txn, options) {
  * deleting by one of the beforeDestroy model hooks
  */
 async function doUndestroyDream(dream, txn) {
-    let query = txn.kyselyTransaction
-        .updateTable(dream.table)
+    const updateStatement = txn.kyselyTransaction.updateTable(dream.table);
+    let query = updateStatement
         .where(dream['_primaryKey'], '=', dream.primaryKeyValue())
         .set({ [dream['_deletedAtField']]: null });
     const dreamClass = dream.constructor;

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

@@ -1,6 +1,7 @@
 import * as util from 'node:util';
 import validateTable from '../db/validators/validateTable.js';
 import Query from '../dream/Query.js';
+import PostgresQueryDriver from '../dream/QueryDriver/Postgres.js';
 import Encrypt from '../encrypt/index.js';
 import DreamAppInitMissingCallToLoadModels from '../errors/dream-app/DreamAppInitMissingCallToLoadModels.js';
 import DreamAppInitMissingMissingProjectRoot from '../errors/dream-app/DreamAppInitMissingMissingProjectRoot.js';
@@ -10,7 +11,6 @@ import EnvInternal from '../helpers/EnvInternal.js';
 import { cacheDreamApp, getCachedDreamAppOrFail } from './cache.js';
 import importModels, { getModelsOrFail } from './helpers/importers/importModels.js';
 import importSerializers, { getSerializersOrFail, setCachedSerializers, } from './helpers/importers/importSerializers.js';
-import PostgresQueryDriver from '../dream/QueryDriver/Postgres.js';
 // this needs to be done top-level to ensure proper configuration
 Settings.defaultZone = 'UTC';
 export default class DreamApp {
@@ -40,7 +40,7 @@ export default class DreamApp {
             await plugin(dreamApp);
         }
         dreamApp.validateAppBuildIntegrity({
-            bypassModelIntegrityCheck: opts.bypassModelIntegrityCheck || false,
+            bypassDreamIntegrityChecks: opts.bypassDreamIntegrityChecks || false,
         });
         return dreamApp;
     }
@@ -51,14 +51,14 @@ export default class DreamApp {
      * that would render it in an invalid state
      *
      */
-    validateAppBuildIntegrity({ bypassModelIntegrityCheck }) {
+    validateAppBuildIntegrity({ bypassDreamIntegrityChecks }) {
         if (!this.projectRoot)
             throw new DreamAppInitMissingMissingProjectRoot();
         if (!this.loadedModels)
             throw new DreamAppInitMissingCallToLoadModels();
         if (this.encryption?.columns?.current)
             DreamApp.checkKey('columns', this.encryption.columns.current.key, this.encryption.columns.current.algorithm);
-        if (!bypassModelIntegrityCheck)
+        if (!bypassDreamIntegrityChecks)
             this.validateApplicationModels();
     }
     /**

package/dist/esm/src/errors/associations/InvalidComputedForeignKey.js

@@ -13,11 +13,10 @@ export class InvalidComputedForeignKey extends Error {
     }
     get message() {
         return `
-Add an explicit foreignKey declaration to this association declaration:
+Add an explicit \`on\` declaration to this association definition:
   Dream class: ${this.dreamClass.sanitizedName}
   Association: ${this.partialAssociation.as}
-Dream tried ${this.computedForeignKey} automatically, but it isn't a column in table ${this.table}.
-    `;
+Dream tried ${this.computedForeignKey} automatically, but it isn't a column in table ${this.table}.`;
     }
 }
 export class ExplicitForeignKeyRequired extends Error {
@@ -47,7 +46,7 @@ export function checkForeignKey(explicitForeignKey, computedForeignKey, dreamCla
         table = dreamClass.table;
     else
         table = modelCBtoSingleDreamClass(dreamClass, partialAssociation).table;
-    const tableColumns = Object.keys(dreamClass.prototype.schema[table]?.columns);
+    const tableColumns = Object.keys(dreamClass.prototype.schema[table]?.columns ?? {});
     const validForeignKey = tableColumns.includes(computedForeignKey);
     if (validForeignKey)
         return;

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

@@ -5,6 +5,7 @@ import dbTypesFilenameForConnection from '../../db/helpers/dbTypesFilenameForCon
 import DreamApp from '../../dream-app/index.js';
 import { DreamConst } from '../../dream/constants.js';
 import Query from '../../dream/Query.js';
+import { ExplicitForeignKeyRequired, InvalidComputedForeignKey, } from '../../errors/associations/InvalidComputedForeignKey.js';
 import FailedToIdentifyAssociation from '../../errors/schema-builder/FailedToIdentifyAssociation.js';
 import camelize from '../camelize.js';
 import compact from '../compact.js';
@@ -263,33 +264,39 @@ may need to update the table getter in the corresponding Dream.
                     this.hasForeignKeyError = true;
                     // console.error(err)
                 }
-                tableAssociationData[associationName] ||= {
-                    tables: [],
-                    type: associationMetaData.type,
-                    polymorphic: associationMetaData.polymorphic,
-                    foreignKey,
-                    foreignKeyTypeColumn: associationMetaData.polymorphic
-                        ? associationMetaData?.foreignKeyTypeField?.() || null
-                        : null,
-                    optional,
-                    where,
-                };
-                if (foreignKey)
-                    tableAssociationData[associationName]['foreignKey'] = foreignKey;
-                if (Array.isArray(dreamClassOrClasses)) {
-                    const tables = dreamClassOrClasses.map(dreamClass => dreamClass.table);
+                try {
+                    tableAssociationData[associationName] ||= {
+                        tables: [],
+                        type: associationMetaData.type,
+                        polymorphic: associationMetaData.polymorphic,
+                        foreignKey,
+                        foreignKeyTypeColumn: associationMetaData.polymorphic
+                            ? associationMetaData?.foreignKeyTypeField?.() || null
+                            : null,
+                        optional,
+                        where,
+                    };
+                    if (foreignKey)
+                        tableAssociationData[associationName]['foreignKey'] = foreignKey;
+                    if (Array.isArray(dreamClassOrClasses)) {
+                        const tables = dreamClassOrClasses.map(dreamClass => dreamClass.table);
+                        tableAssociationData[associationName].tables = [
+                            ...tableAssociationData[associationName].tables,
+                            ...tables,
+                        ];
+                    }
+                    else {
+                        tableAssociationData[associationName].tables.push(dreamClassOrClasses.table);
+                    }
+                    // guarantee unique
                     tableAssociationData[associationName].tables = [
-                        ...tableAssociationData[associationName].tables,
-                        ...tables,
+                        ...new Set(tableAssociationData[associationName].tables),
                     ];
                 }
-                else {
-                    tableAssociationData[associationName].tables.push(dreamClassOrClasses.table);
+                catch (error) {
+                    if (!(error instanceof ExplicitForeignKeyRequired || error instanceof InvalidComputedForeignKey))
+                        throw error;
                 }
-                // guarantee unique
-                tableAssociationData[associationName].tables = [
-                    ...new Set(tableAssociationData[associationName].tables),
-                ];
             }
         }
         return Object.keys(tableAssociationData)

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

@@ -2,11 +2,11 @@ import pluralize from 'pluralize-esm';
 import serializerGlobalNameFromFullyQualifiedModelName from '../../serializer/helpers/serializerGlobalNameFromFullyQualifiedModelName.js';
 import camelize from '../camelize.js';
 import globalClassNameFromFullyQualifiedModelName from '../globalClassNameFromFullyQualifiedModelName.js';
+import pascalize from '../pascalize.js';
 import relativeDreamPath from '../path/relativeDreamPath.js';
 import snakeify from '../snakeify.js';
 import standardizeFullyQualifiedModelName from '../standardizeFullyQualifiedModelName.js';
 import uniq from '../uniq.js';
-import pascalize from '../pascalize.js';
 export default function generateDreamContent({ fullyQualifiedModelName, columnsWithTypes, fullyQualifiedParentName, serializer, includeAdminSerializers, connectionName = 'default', }) {
     fullyQualifiedModelName = standardizeFullyQualifiedModelName(fullyQualifiedModelName);
     const modelClassName = globalClassNameFromFullyQualifiedModelName(fullyQualifiedModelName);
@@ -32,17 +32,19 @@ export default function generateDreamContent({ fullyQualifiedModelName, columnsW
         const fullyQualifiedAssociatedModelName = standardizeFullyQualifiedModelName(attributeName);
         const associationModelName = globalClassNameFromFullyQualifiedModelName(fullyQualifiedAssociatedModelName);
         const associationImportStatement = importStatementForModel(fullyQualifiedModelName, fullyQualifiedAssociatedModelName);
-        const associationName = camelize(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 = camelize(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/esm/src/helpers/cli/generateFactoryContent.js

@@ -29,6 +29,7 @@ export default function generateFactoryContent({ fullyQualifiedModelName, column
             throw new Error(`Must pass a column type for ${attributeName} (i.e. ${attributeName}:string)`);
         switch (attributeType) {
             case 'belongs_to': {
+                const attributeVariable = camelize(attributeName.split('/').pop());
                 const fullyQualifiedAssociatedModelName = standardizeFullyQualifiedModelName(attributeName);
                 const associationModelName = globalClassNameFromFullyQualifiedModelName(fullyQualifiedAssociatedModelName);
                 const associationFactoryImportStatement = `import create${associationModelName} from '${relativeDreamPath('factories', 'factories', fullyQualifiedModelName, fullyQualifiedAssociatedModelName)}'`;

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

@@ -17,30 +17,20 @@ export default function generateMigrationContent({ connectionName = 'default', t
         // 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 = snakeify(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 = snakeify(nonStandardAttributeName);
         switch (attributeType) {
             case 'belongs_to':
                 columnDefs.push(generateBelongsToStr(connectionName, attributeName, {
                     primaryKeyType,
                     optional,
                 }));
+                attributeName = snakeify(nonStandardAttributeName.split('/').pop());
                 attributeName = associationNameToForeignKey(attributeName);
                 break;
             case 'enum':
@@ -74,7 +64,7 @@ export default function generateMigrationContent({ connectionName = 'default', t
                 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}')
@@ -83,6 +73,17 @@ export default function generateMigrationContent({ connectionName = 'default', t
     .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) {
@@ -252,7 +253,7 @@ function generateBelongsToStr(connectionName, associationName, { primaryKeyType,
     const dbDriverClass = Query.dbDriverClass(connectionName);
     const dataType = dbDriverClass.foreignKeyTypeFromPrimaryKey(primaryKeyType);
     const references = pluralize(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/esm/src/helpers/cli/generateSerializerContent.js

@@ -51,7 +51,7 @@ export default function generateSerializerContent({ fullyQualifiedModelName, col
             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('')}
@@ -66,9 +66,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/esm/src/helpers/comparisonKey.js

@@ -1,4 +1,19 @@
 import Dream from '../Dream.js';
 export default function comparisonKey(val, toKey = undefined) {
-    return val instanceof Dream ? val.comparisonKey : toKey ? toKey(val) : val;
+    if (val instanceof Dream)
+        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/esm/src/helpers/percent.js

@@ -0,0 +1,7 @@
+import round from './round.js';
+export default function percent(numerator, denominator, precision) {
+    if (!numerator || !denominator)
+        return 0;
+    const percent = (numerator / denominator) * 100;
+    return precision ? round(percent, precision) : percent;
+}

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

@@ -14,8 +14,5 @@ import sortBy from './sortBy.js';
  * ```
  */
 export default function sort(array) {
-    if (typeof array[0] === 'bigint') {
-        return sortBy(array, a => String(a));
-    }
     return sortBy(array, a => a);
 }

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

@@ -1,3 +1,5 @@
+import CalendarDate from './CalendarDate.js';
+import { DateTime } from './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.
@@ -22,10 +24,17 @@ export default 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 && bPrime instanceof DateTime)
+            return aPrime.valueOf() - bPrime.valueOf();
+        if ((aPrime instanceof DateTime || aPrime instanceof CalendarDate) &&
+            (bPrime instanceof DateTime || bPrime instanceof CalendarDate))
+            return (aPrime.toISO() ?? '').localeCompare(bPrime.toISO() ?? '');
         throw new UnsupportedValueFromComparisonFunction(aPrime, bPrime);
     });
 }

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

@@ -1,13 +1,10 @@
 import comparisonKey from './comparisonKey.js';
 export default function uniq(arr, toKey = undefined) {
     const map = arr.reduce((acc, val) => {
-        const baseKey = comparisonKey(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 = comparisonKey(val, toKey);
+        if (!acc.has(key))
+            acc.set(key, val);
         return acc;
-    }, {});
-    return Object.values(map);
+    }, new Map());
+    return [...map.values()];
 }

package/dist/esm/src/index.js

@@ -54,6 +54,7 @@ export { default as pascalize } from './helpers/pascalize.js';
 export { default as dreamPath } from './helpers/path/dreamPath.js';
 export { default as relativeDreamPath } from './helpers/path/relativeDreamPath.js';
 export { default as sharedPathPrefix } from './helpers/path/sharedPathPrefix.js';
+export { default as percent } from './helpers/percent.js';
 export { Range, default as range } from './helpers/range.js';
 export { default as round } from './helpers/round.js';
 export { default as snakeify } from './helpers/snakeify.js';

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

@@ -8,7 +8,7 @@ import LoadBuilder from './dream/LoadBuilder.js';
 import Query from './dream/Query.js';
 import { PassthroughOnClause, WhereStatement } from './types/associations/shared.js';
 import { AssociationTableNames, DbConnectionType } from './types/db.js';
-import { AllDefaultScopeNames, AssociationNameToDream, AttributeKeys, CreateOrFindByExtraOpts, DefaultOrNamedScopeName, DreamAssociationNames, DreamAssociationNamesWithoutRequiredOnClauses, DreamAttributes, DreamColumnNames, DreamParamSafeColumnNames, DreamPrimaryKeyType, DreamSerializerKey, GlobalModelNames, GlobalSerializerName, JoinAndStatements, NextPreloadArgumentType, OrderDir, PassthroughColumnNames, PluckEachArgs, PrimaryKeyForFind, TableColumnNames, UpdateableAssociationProperties, UpdateableProperties, UpdateablePropertiesForClass, UpdateOrCreateByExtraOpts } from './types/dream.js';
+import { AllDefaultScopeNames, AssociationNameToDream, AttributeKeys, CreateOrFindByExtraOpts, DefaultOrNamedScopeName, DreamAssociationNames, DreamAssociationNamesWithoutRequiredOnClauses, DreamAttributes, DreamBelongsToAssociationNames, DreamColumnNames, DreamHasManyAssociationNames, DreamHasOneAssociationNames, DreamModelAssociationNames, DreamParamSafeColumnNames, DreamPrimaryKeyType, DreamSerializerKey, GlobalModelNames, GlobalSerializerName, JoinAndStatements, OrderDir, PassthroughColumnNames, PluckEachArgs, PrimaryKeyForFind, TableColumnNames, UpdateableAssociationProperties, UpdateableProperties, UpdateablePropertiesForClass, UpdateOrCreateByExtraOpts } from './types/dream.js';
 import { BaseModelColumnTypes, DefaultQueryTypeOptions, FindEachOpts, LoadForModifierFn, PaginatedDreamQueryOptions, PaginatedDreamQueryResult, QueryWithJoinedAssociationsType, QueryWithJoinedAssociationsTypeAndNoPreload } from './types/query.js';
 import { DreamModelSerializerType, SimpleObjectSerializerType } from './types/serializer.js';
 import { ValidationType } from './types/validation.js';
@@ -2343,6 +2343,45 @@ export default class Dream {
      * @returns A chainable LoadBuilder instance
      */
     load<I extends Dream, DB extends I['DB'], TableName extends I['table'], Schema extends I['schema'], const Arr extends readonly unknown[]>(this: I, ...args: [...Arr, VariadicLoadArgs<DB, Schema, TableName, Arr>]): LoadBuilder<I>;
+    /**
+     * 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
+     */
+    association<I extends Dream, AssociationName extends DreamBelongsToAssociationNames<I> | DreamHasOneAssociationNames<I> | DreamHasManyAssociationNames<I>, ReturnType extends AssociationName extends DreamHasManyAssociationNames<I> ? AssociationNameToDream<I, AssociationName>[] : AssociationNameToDream<I, AssociationName> | null>(this: I, associationName: AssociationName): Promise<ReturnType>;
+    /**
+     * 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
+     */
+    associationOrFail<I extends Dream, AssociationName extends DreamBelongsToAssociationNames<I> | DreamHasOneAssociationNames<I> | DreamHasManyAssociationNames<I>, ReturnType extends AssociationName extends DreamHasManyAssociationNames<I> ? AssociationNameToDream<I, AssociationName>[] : AssociationNameToDream<I, AssociationName>>(this: I, associationName: AssociationName): Promise<ReturnType>;
     /**
      * Recursively loads all Dream associations referenced by `rendersOne` and `rendersMany`
      * in a DreamSerializer. This traverses the entire content tree of serializers to automatically
@@ -2401,8 +2440,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
@@ -2436,6 +2475,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()
@@ -2488,7 +2530,7 @@ export default class Dream {
      * @param associationName - the association name you wish to check the loading of
      * @returns A boolean
      */
-    loaded<I extends Dream, TableName extends I['table'], Schema extends I['schema'], AssociationName extends NextPreloadArgumentType<Schema, TableName>>(this: I, associationName: AssociationName): boolean;
+    loaded<I extends Dream, TableName extends I['table'], Schema extends I['schema'], AssociationName extends DreamModelAssociationNames<Schema, TableName>>(this: I, associationName: AssociationName): boolean;
     /**
      * Reloads an instance, refreshing all it's attribute values
      * to those in the database.

package/dist/types/src/bin/index.d.ts

@@ -4,6 +4,7 @@ export default class DreamBin {
     }): Promise<void>;
     static dbCreate(): Promise<void>;
     static dbDrop(): Promise<void>;
+    static dbEnsureAllMigrationsHaveBeenRun(): Promise<void>;
     static dbMigrate(): Promise<void>;
     static dbRollback(opts: {
         steps: number;

package/dist/types/src/db/migration-helpers/DreamMigrationHelpers.d.ts

@@ -1,5 +1,21 @@
 import { Kysely } 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 renameTable(db: Kysely<any>, from: string, to: string): Promise<void>;
     /**
      * Unique indexes cannot be populated by the same value even within a transaction,
      * but deferrable unique constraints can.

package/dist/types/src/decorators/field/sortable/helpers/setPosition.d.ts

@@ -12,5 +12,5 @@ export default function setPosition({ position, previousPosition, dream, positio
     scope: string | string[] | undefined;
     txn: DreamTransaction<any> | undefined;
 }): Promise<void>;
-export declare function applySortableScopesToQuery<QB extends UpdateQueryBuilder<any, string, string, any> | SelectQueryBuilder<any, any, any>>(dream: Dream, kyselyQuery: QB, whereValueCB: (column: string) => any, scope?: string | string[]): QB;
+export declare function applySortableScopesToQuery<QB extends UpdateQueryBuilder<any, any, any, any> | SelectQueryBuilder<any, any, any>>(dream: Dream, kyselyQuery: QB, whereValueCB: (column: string) => any, scope?: string | string[]): QB;
 export declare function getPostgresQueryDriver(connectionName: string): typeof PostgresQueryDriver;

package/dist/types/src/dream/QueryDriver/Base.d.ts

@@ -20,6 +20,7 @@ export default class QueryDriverBase<DreamInstance extends Dream> {
      */
     protected readonly innerJoinDreamClasses: readonly (typeof Dream)[];
     constructor(query: Query<DreamInstance, any>);
+    static ensureAllMigrationsHaveBeenRun(connectionName: string): Promise<void>;
     /**
      * migrate the database. Must respond to the NODE_ENV value.
      */

package/dist/types/src/dream/QueryDriver/Kysely.d.ts

@@ -1,4 +1,4 @@
-import { DeleteQueryBuilder, Kysely, Transaction as KyselyTransaction, SelectQueryBuilder, UpdateQueryBuilder } from 'kysely';
+import { DeleteQueryBuilder, Kysely, Transaction as KyselyTransaction, OrderByItemBuilder, SelectQueryBuilder, UpdateQueryBuilder } from 'kysely';
 import { DialectProviderCb } from '../../db/DreamDbConnection.js';
 import Dream from '../../Dream.js';
 import { SchemaBuilderInformationSchemaRow } from '../../helpers/cli/SchemaBuilder.js';
@@ -13,6 +13,7 @@ export default class KyselyQueryDriver<DreamInstance extends Dream> extends Quer
     dbFor(sqlCommandType: SqlCommandType): Kysely<DreamInstance['DB']> | KyselyTransaction<DreamInstance['DB']>;
     static dbFor<I extends Dream>(connectionName: string, dbConnectionType: DbConnectionType, dreamTransaction?: DreamTransaction<I> | null): Kysely<I['DB']> | KyselyTransaction<I['DB']>;
     static dialectProvider(connectionName: string, dbConnectionType: DbConnectionType): DialectProviderCb;
+    static ensureAllMigrationsHaveBeenRun(connectionName: string): Promise<void>;
     /**
      * migrate the database. Must respond to the NODE_ENV value.
      */
@@ -266,7 +267,7 @@ export default class KyselyQueryDriver<DreamInstance extends Dream> extends Quer
     }>;
     private buildDelete;
     private buildSelect;
-    orderByDirection(direction: OrderDir | null): import("kysely").RawBuilder<unknown>;
+    orderByDirection(direction: OrderDir | null): (obj: OrderByItemBuilder) => OrderByItemBuilder;
     private buildUpdate;
     /**
      * @internal

package/dist/types/src/dream/QueryDriver/helpers/kysely/checkForNeedToBeRunMigrations.d.ts

@@ -0,0 +1,9 @@
+import { DialectProviderCb } from '../../../../db/DreamDbConnection.js';
+type MigrationModes = 'migrate' | 'rollback';
+interface MigrationOpts {
+    connectionName: string;
+    dialectProvider: DialectProviderCb;
+    mode?: MigrationModes;
+}
+export default function checkForNeedToBeRunMigrations({ connectionName, dialectProvider, }: MigrationOpts): Promise<boolean>;
+export {};

package/dist/types/src/dream/QueryDriver/helpers/kysely/migrationFolderPath.d.ts

@@ -0,0 +1 @@
+export default function migrationFolderPath(connectionName: string): string;