@rvoh/dream 0.29.1

package/dist/esm/src/Dream.js

@@ -0,0 +1,2981 @@
+import { DateTime } from 'luxon';
+import { pgErrorType } from './db/errors.js';
+import db from './db/index.js';
+import associationToGetterSetterProp from './decorators/associations/associationToGetterSetterProp.js';
+import { blankAssociationsFactory, } from './decorators/associations/shared.js';
+import { blankHooksFactory } from './decorators/hooks/shared.js';
+import resortAllRecords from './decorators/sortable/helpers/resortAllRecords.js';
+import DreamClassTransactionBuilder from './dream/DreamClassTransactionBuilder.js';
+import DreamInstanceTransactionBuilder from './dream/DreamInstanceTransactionBuilder.js';
+import DreamTransaction from './dream/DreamTransaction.js';
+import associationQuery from './dream/internal/associations/associationQuery.js';
+import associationUpdateQuery from './dream/internal/associations/associationUpdateQuery.js';
+import createAssociation from './dream/internal/associations/createAssociation.js';
+import destroyAssociation from './dream/internal/associations/destroyAssociation.js';
+import undestroyAssociation from './dream/internal/associations/undestroyAssociation.js';
+import destroyDream from './dream/internal/destroyDream.js';
+import { destroyOptions, reallyDestroyOptions, undestroyOptions, } from './dream/internal/destroyOptions.js';
+import ensureSTITypeFieldIsSet from './dream/internal/ensureSTITypeFieldIsSet.js';
+import extractAssociationMetadataFromAssociationName from './dream/internal/extractAssociationMetadataFromAssociationName.js';
+import reload from './dream/internal/reload.js';
+import runValidations from './dream/internal/runValidations.js';
+import saveDream from './dream/internal/saveDream.js';
+import { DEFAULT_BYPASS_ALL_DEFAULT_SCOPES, DEFAULT_DEFAULT_SCOPES_TO_BYPASS, DEFAULT_SKIP_HOOKS, } from './dream/internal/scopeHelpers.js';
+import undestroyDream from './dream/internal/undestroyDream.js';
+import LeftJoinLoadBuilder from './dream/LeftJoinLoadBuilder.js';
+import LoadBuilder from './dream/LoadBuilder.js';
+import Query from './dream/Query.js';
+import CannotPassNullOrUndefinedToRequiredBelongsTo from './errors/associations/CannotPassNullOrUndefinedToRequiredBelongsTo.js';
+import CanOnlyPassBelongsToModelParam from './errors/associations/CanOnlyPassBelongsToModelParam.js';
+import NonLoadedAssociation from './errors/associations/NonLoadedAssociation.js';
+import CannotCallUndestroyOnANonSoftDeleteModel from './errors/CannotCallUndestroyOnANonSoftDeleteModel.js';
+import ConstructorOnlyForInternalUse from './errors/ConstructorOnlyForInternalUse.js';
+import CreateOrFindByFailedToCreateAndFind from './errors/CreateOrFindByFailedToCreateAndFind.js';
+import GlobalNameNotSet from './errors/dream-application/GlobalNameNotSet.js';
+import MissingSerializer from './errors/MissingSerializersDefinition.js';
+import MissingTable from './errors/MissingTable.js';
+import NonExistentScopeProvidedToResort from './errors/NonExistentScopeProvidedToResort.js';
+import CalendarDate from './helpers/CalendarDate.js';
+import cloneDeepSafe from './helpers/cloneDeepSafe.js';
+import cachedTypeForAttribute from './helpers/db/cachedTypeForAttribute.js';
+import isJsonColumn from './helpers/db/types/isJsonColumn.js';
+import inferSerializerFromDreamOrViewModel from './helpers/inferSerializerFromDreamOrViewModel.js';
+import { isString } from './helpers/typechecks.js';
+export default class Dream {
+    DB;
+    /**
+     * @internal
+     *
+     * This getter will throw an error when developers use .toEqual instead of
+     * useToMatchDreamModels or useToMatchDreamModel in a jest spec. This
+     * must be the first getter in the class in order for this to work, so don't move it.
+     *
+     */
+    get _useToMatchDreamModels() {
+        throw new Error(`
+      Hi there! It looks like you're trying to compare a Dream model in
+      a Jest expectation using \`toEqual\`. That won't work.
+      Instead, use \`toMatchDreamModel\` or \`toMatchDreamModels\`.
+
+      For example, instead of:
+
+        expect(balloons).toEqual([balloon])
+
+      write:
+
+        expect(balloons).toMatchDreamModels([balloon])
+    `);
+    }
+    /**
+     * @internal
+     *
+     * Modern Javascript sets all properties that do not have an explicit
+     * assignment within the constructor to undefined in an implicit constructor.
+     * Since the Dream constructor sets the value of properties of instances of
+     * classes that extend Dream (e.g. when passing attributes to #new or #create
+     * or when loading a model via one of the #find methods or #all), we need to
+     * prevent those properties from being set back to undefined. Since all
+     * properties corresponding to a database column get a setter, we achieve this
+     * protection by including a guard in the setters that returns if this
+     * property is set.
+     *
+     */
+    columnSetterGuardActivated = false;
+    /**
+     * @internal
+     *
+     * Certain features (e.g. passing a Dream instance to `create` so that it automatically destructures polymorphic type and primary key)
+     * need static access to things set up by decorators (e.g. associations). Stage 3 Decorators change the context that is available
+     * at decoration time such that the class of a property being decorated is only avilable during instance instantiation. In order
+     * to only apply static values once, on boot, `globallyInitializingDecorators` is set to true on Dream, and all Dream models are instantiated.
+     *
+     */
+    static globallyInitializingDecorators = false;
+    get schema() {
+        throw new Error('Must define schema getter in ApplicationModel');
+    }
+    get globalSchema() {
+        throw new Error('Must define schema getter in ApplicationModel');
+    }
+    /**
+     * Shadows #primaryKey, a getter which can be overwritten to customize the id field
+     * for a given model.
+     *
+     * @returns string
+     */
+    static get primaryKey() {
+        return this.prototype.primaryKey;
+    }
+    /**
+     * Shadows #table, a getter which can be overwritten to customize the table field
+     * for a given model.
+     *
+     * @returns string
+     */
+    static get table() {
+        return this.prototype.table;
+    }
+    /**
+     * A getter which can be overwritten to customize the automatic createdAt timestamp field
+     * for a given model.
+     *
+     * ```ts
+     *  class User extends ApplicationModel {
+     *    public get createdAtField() {
+     *       return 'createdAtTimestamp' as const
+     *    }
+     *  }
+     *
+     * const user = await User.first()
+     * user.createdAtTimestamp // returns the DateTime that this user was created
+     *
+     * @returns string
+     */
+    get createdAtField() {
+        return 'createdAt';
+    }
+    /**
+     * A getter which can be overwritten to customize the automatic updatedAt timestamp field
+     * for a given model.
+     *
+     * ```ts
+     *  class User extends ApplicationModel {
+     *    public get updatedAtField() {
+     *       return 'updatedAtTimestamp' as const
+     *    }
+     *  }
+     *
+     * const user = await User.first()
+     * user.updatedAtTimestamp // returns the DateTime that this user was updated
+     * ```
+     *
+     * @returns string
+     */
+    get updatedAtField() {
+        return 'updatedAt';
+    }
+    get deletedAtField() {
+        return 'deletedAt';
+    }
+    /**
+     * @internal
+     *
+     * Model storage for association metadata, set when using the association decorators like:
+     *   @Deco.HasOne
+     *   @Deco.HasMany
+     *   @Deco.BelongsTo
+     */
+    static associationMetadataByType = blankAssociationsFactory(this, {
+        freeze: true,
+    });
+    /**
+     * @internal
+     *
+     * Model storage for scope metadata, set when using the Scope decorator
+     * (this default assignment simply ensures that it is
+     * always an array rather than undefined,
+     * freezing ensures that we never modify the static array on the inherited Dream class)
+     */
+    static scopes = Object.freeze({
+        default: Object.freeze([]),
+        named: Object.freeze([]),
+    });
+    /**
+     * @internal
+     *
+     * Model storage for virtual attribute metadata, set on the inheriting class when
+     * using the Virtual decorator (this default assignment simply ensures that it is
+     * always an array rather than undefined,
+     * freezing ensures that we never modify the static array on the inherited Dream class)
+     */
+    static virtualAttributes = Object.freeze([]);
+    /**
+     * @internal
+     *
+     * Model storage for additional columns that may not be set via the new/create/update
+     * methods. Set on the inheriting class when using the Virtual decorator (this default
+     * assignment simply ensures that it is always an array rather than undefined)
+     */
+    static explicitUnsafeParamColumns = Object.freeze([]);
+    /**
+     * @internal
+     *
+     * Model storage for sortable metadata, set when using the Sortable decorator
+     *  (this default assignment simply ensures that it is always an array rather than undefined,
+     * freezing ensures that we never modify the static array on the inherited Dream class)
+     *
+     */
+    static sortableFields = Object.freeze([]);
+    /**
+     * @internal
+     *
+     * Model storage for STI metadata, set when using the STI decorator
+     */
+    static extendedBy = null;
+    /**
+     * @internal
+     *
+     * Model storage for STI metadata, set when using the STI decorator
+     *  (this default assignment simply ensures that it is always a valid object rather than undefined,
+     * freezing ensures that we never modify the static array on the inherited Dream class)
+     */
+    static sti = Object.freeze({
+        active: false,
+        baseClass: null,
+        value: null,
+    });
+    /**
+     * @internal
+     *
+     * Model storage for model hook metadata, set when using the following decorators:
+     *   BeforeCreate
+     *   BeforeUpdate
+     *   BeforeSave
+     *   BeforeDestroy
+     *   AfterCreate
+     *   AfterCreateCommit
+     *   AfterUpdate
+     *   AfterUpdateCommit
+     *   AfterSave
+     *   AfterSaveCommit
+     *   AfterDestroy
+     *   AfterDestroyCommit
+     */
+    static hooks = blankHooksFactory(this, { freeze: true });
+    /**
+     * @internal
+     *
+     * Model storage for validation metadata, set when using the Validates decorator
+     * (this default assignment simply ensures that it is always an array rather than undefined,
+     * freezing ensures that we never modify the static array on the inherited Dream class)
+     */
+    static validations = Object.freeze([]);
+    /**
+     * @internal
+     *
+     * Model storage for custom validation metadata, set when using the Validate decorator
+     * (this default assignment simply ensures that it is always an array rather than undefined,
+     * freezing ensures that we never modify the static array on the inherited Dream class)
+     *
+     */
+    static customValidations = Object.freeze([]);
+    /**
+     * @internal
+     *
+     * Model storage for replica-safe metadata, set when using the ReplicaSafe decorator
+     */
+    static replicaSafe = false;
+    /**
+     * @internal
+     *
+     * Model storage for soft-delete metadata, set when using the SoftDelete decorator
+     */
+    static softDelete = false;
+    /**
+     * @internal
+     *
+     * Provided to distinguish between Dream and other classes
+     *
+     * @returns true
+     */
+    static get isDream() {
+        return true;
+    }
+    /**
+     * @internal
+     *
+     * Returns true if this model class is the base class of other STI models
+     *
+     * @returns boolean
+     */
+    static get isSTIBase() {
+        return !!this.extendedBy?.length && !this.isSTIChild;
+    }
+    /**
+     * @internal
+     *
+     * Returns true if this model class a child class of a base STI model
+     *
+     * @returns boolean
+     */
+    static get isSTIChild() {
+        return !!this.sti?.active;
+    }
+    /**
+     * @internal
+     *
+     * Returns either the base STI class, or else this class
+     *
+     * @returns A dream class
+     */
+    static get stiBaseClassOrOwnClass() {
+        return this.sti.baseClass || this;
+    }
+    /**
+     * @internal
+     *
+     * Shadows .stiBaseClassOrOwnClass. Returns either the base STI class, or else this class
+     *
+     * @returns A dream class
+     */
+    get stiBaseClassOrOwnClass() {
+        return this.constructor.stiBaseClassOrOwnClass;
+    }
+    /**
+     * @internal
+     *
+     * Used by model hook decorators to apply a hook to a specific model.
+     *
+     * @param hookType - the type of hook you want to attach the provided statement to
+     * @param statement - the statement to couple to the provided hookType
+     * @returns void
+     */
+    static addHook(hookType, statement) {
+        const existingHook = this.hooks[hookType].find(hook => hook.method === statement.method);
+        if (existingHook)
+            return;
+        this.hooks[hookType] = [...this.hooks[hookType], statement];
+    }
+    /**
+     * @internal
+     *
+     * Returns a unique global name for the given model.
+     *
+     * @returns A string representing a unique key for this model
+     */
+    static get globalName() {
+        if (!this._globalName)
+            throw new GlobalNameNotSet(this);
+        return this._globalName;
+    }
+    static _globalName;
+    /**
+     * @internal
+     *
+     * Used by DreamApplication during the load process
+     * for models, services, and controllers to assign
+     * unique global names to each model based on the file
+     * name of that model.
+     */
+    static setGlobalName(globalName) {
+        this._globalName = globalName;
+    }
+    /**
+     * Returns the column names for the given model
+     *
+     * @returns The column names for the given model
+     */
+    static columns() {
+        if (this._columns)
+            return this._columns;
+        const columns = this.prototype.schema[this.table]?.columns;
+        this._columns = new Set(columns ? Object.keys(columns) : []);
+        return this._columns;
+    }
+    static _columns;
+    /**
+     * Returns the list of column names that are safe for
+     * casting automatically using `.paramsFor` within a
+     * psychic controller. It will return a subset of the
+     * `.columns` getter, but which filters out the following:
+     *   * createdAt
+     *   * updatedAt
+     *   * deletedAt
+     *   * type fields for STI models
+     *   * foreign key fields for belongs to associations (these should usually be verified before being set)
+     *   * type fields corresponding to polymorphic associations
+     *
+     * @returns A subset of columns for the given dream class
+     */
+    static paramSafeColumnsOrFallback() {
+        const defaultParams = this.defaultParamSafeColumns();
+        const userDefinedParams = this.prototype.paramSafeColumns;
+        if (Array.isArray(userDefinedParams)) {
+            return userDefinedParams.filter(param => defaultParams.includes(param));
+        }
+        return defaultParams;
+    }
+    static defaultParamSafeColumns() {
+        const columns = [...this.columns()].filter(column => {
+            if (this.prototype.primaryKey === column)
+                return false;
+            if (this.prototype.createdAtField === column)
+                return false;
+            if (this.prototype.updatedAtField === column)
+                return false;
+            if (this.prototype.deletedAtField === column)
+                return false;
+            if (this.explicitUnsafeParamColumns.includes(column))
+                return false;
+            if (this.isBelongsToAssociationForeignKey(column))
+                return false;
+            if (this.isBelongsToAssociationPolymorphicTypeField(column))
+                return false;
+            if (this.sti.active && column === 'type')
+                return false;
+            return true;
+        });
+        return [
+            ...new Set([...columns, ...this.virtualAttributes.map(attr => attr.property)]),
+        ];
+    }
+    /**
+     * @internal
+     *
+     * Returns true if the column is virtual (set using the Virtual decorator)
+     *
+     * @param columnName - the name of the property you are checking for
+     * @returns boolean
+     */
+    static isVirtualColumn(columnName) {
+        return this.prototype.isVirtualColumn(columnName);
+    }
+    /**
+     * @internal
+     *
+     * Locates an association's metadata by key
+     *
+     * ```ts
+     * Post.getAssociationMetadata('user')
+     * // {
+     * //    modelCB: [Function (anonymous)],
+     * //    type: 'BelongsTo',
+     * //    as: 'user',
+     * //    optional: false,
+     * //    polymorphic: false,
+     * //    primaryKeyOverride: null,
+     * //    primaryKey: [Function: primaryKey],
+     * //    primaryKeyValue: [Function: primaryKeyValue],
+     * //    foreignKey: [Function: foreignKey],
+     * //    foreignKeyTypeField: [Function: foreignKeyTypeField]
+     * //  }
+     * ```
+     *
+     * @param associationName - the name of the association you wish to retrieve metadata for
+     * @returns Association metadata for the requested association
+     */
+    static getAssociationMetadata(associationName) {
+        return this.associationMetadataMap()[extractAssociationMetadataFromAssociationName(associationName).name];
+    }
+    /**
+     * @internal
+     *
+     * Returns an array containing all of the associations for this dream class
+     *
+     * @returns An array containing all of the associations for this dream class
+     */
+    static associationMetadataMap() {
+        const allAssociations = [
+            ...this.associationMetadataByType.belongsTo,
+            ...this.associationMetadataByType.hasOne,
+            ...this.associationMetadataByType.hasMany,
+        ];
+        const map = {};
+        for (const association of allAssociations) {
+            map[association.as] = association;
+        }
+        return map;
+    }
+    /**
+     * @internal
+     *
+     * Returns all of the association names for this dream class
+     *
+     * @returns All of the association names for this dream class
+     */
+    static get associationNames() {
+        const allAssociations = [
+            ...this.associationMetadataByType.belongsTo,
+            ...this.associationMetadataByType.hasOne,
+            ...this.associationMetadataByType.hasMany,
+        ];
+        return allAssociations.map(association => {
+            return association.as;
+        });
+    }
+    /**
+     * Returns a query for this model which disregards default scopes
+     *
+     * @returns A query for this model which disregards default scopes
+     */
+    static removeAllDefaultScopes() {
+        return this.query().removeAllDefaultScopes();
+    }
+    /**
+     * Prevents a specific default scope from applying when
+     * the Query is executed
+     *
+     * @returns A new Query which will prevent a specific default scope from applying
+     */
+    static removeDefaultScope(scopeName) {
+        return this.query().removeDefaultScope(scopeName);
+    }
+    /**
+     * Retrieves an array containing all records corresponding to
+     * this model. Be careful using this, since it will attempt to
+     * pull every record into memory at once. For a large number
+     * of records, consider using `.findEach`, which will pull
+     * the records in batches.
+     *
+     * ```ts
+     * await User.all()
+     * ```
+     *
+     * @returns an array of dreams
+     */
+    static async all(options = {}) {
+        return await this.query().all(options);
+    }
+    /**
+     * Forces use of a database connection (e.g. 'primary') during the query.
+     *
+     * NOTE: all queries within a transaction always use the 'primary' replica, so
+     * explicitly setting connection within a transaction has no effect.
+     *
+     * @param connection - The connection you wish to access ('primary' or 'replica')
+     * @returns A Query with the requested connection
+     */
+    static connection(connection) {
+        return new Query(this.prototype, {
+            connection,
+        });
+    }
+    /**
+     * Retrieves the number of records corresponding
+     * to this model.
+     *
+     * @returns The number of records corresponding to this model
+     */
+    static async count() {
+        return await this.query().count();
+    }
+    /**
+     * Retrieves the max value of the specified column
+     * for this model's records.
+     *
+     * ```ts
+     * await User.max('id')
+     * // 99
+     * ```
+     *
+     * @param columnName - a column name on the model
+     * @returns the max value of the specified column for this model's records
+     */
+    static async max(columnName) {
+        return await this.query().max(columnName);
+    }
+    /**
+     * Retrieves the min value of the specified column
+     * for this model's records.
+     *
+     *
+     * ```ts
+     * await User.min('id')
+     * // 1
+     * ```
+     *
+     * @param columnName - a column name on the model
+     * @returns the min value of the specified column for this model's records
+     */
+    static async min(columnName) {
+        return await this.query().min(columnName);
+    }
+    /**
+     * Persists a new record, setting the provided attributes
+     *
+     * ```ts
+     * const user = await User.create({ email: 'how@yadoin' })
+     * await Post.create({ body: 'howdy', user })
+     * ```
+     *
+     * @param attributes - attributes or belongs to associations you wish to set on this model before persisting
+     * @returns A newly persisted dream instance
+     */
+    static async create(attributes) {
+        const dreamModel = this.new(attributes);
+        await dreamModel.save();
+        return dreamModel;
+    }
+    /**
+     * Attempt to create the model. If creation fails
+     * due to uniqueness constraint, then find the existing
+     * model.
+     *
+     * This is useful in situations where we want to avoid
+     * a race condition creating duplicate records.
+     *
+     * IMPORTANT: A unique index/uniqueness constraint must exist on
+     * at least one of the provided attributes
+     *
+     * ```ts
+     * const logEntry = await LogEntry.createOrFindBy({ externalId }, { createWith: params })
+     * ```
+     *
+     * @param attributes - The base attributes to persist, but also the attributes to use to find when create fails
+     * @param extraOpts.createWith - additional attributes to persist when creating, but not used for finding
+     * @returns A dream instance
+     */
+    static async createOrFindBy(attributes, extraOpts = {}) {
+        try {
+            const dreamModel = this.new({
+                ...attributes,
+                ...(extraOpts?.createWith || {}),
+            });
+            await dreamModel.save();
+            return dreamModel;
+        }
+        catch (err) {
+            if (pgErrorType(err) === 'UNIQUE_CONSTRAINT_VIOLATION') {
+                const dreamModel = await this.findBy(this.extractAttributesFromUpdateableProperties(attributes));
+                if (!dreamModel)
+                    throw new CreateOrFindByFailedToCreateAndFind(this);
+                return dreamModel;
+            }
+            throw err;
+        }
+    }
+    /**
+     * Returns a new query instance with the distinct query applied.
+     * If no columnName is provided, then distinct will apply to the
+     * primary key by default.
+     *
+     * ```ts
+     * await User.distinct('name').pluck('name')
+     * ```
+     *
+     * @param columnName - The column name you wish to apply the distinct clause to
+     * @returns A Query scoped to this Dream model with the distinct clause applied
+     */
+    static distinct(columnName) {
+        return this.query().distinct(columnName);
+    }
+    /**
+     * Finds a record for the corresponding model with the
+     * specified primary key. If not found, null
+     * is returned
+     *
+     * ```ts
+     * await User.query().find(123)
+     * // User{id: 123}
+     * ```
+     *
+     * @param primaryKey - The primaryKey of the record to look up
+     * @returns Either the found record, or else null
+     */
+    static async find(primaryKey) {
+        return await this.query().find(primaryKey);
+    }
+    /**
+     * Finds a record for the corresponding model with the
+     * specified primary key. If not found, an exception is raised.
+     *
+     * ```ts
+     * await User.query().findOrFail(123)
+     * // User{id: 123}
+     * ```
+     *
+     * @param primaryKey - The primaryKey of the record to look up
+     * @returns Either the found record, or else null
+     */
+    static async findOrFail(primaryKey) {
+        return await this.query().findOrFail(primaryKey);
+    }
+    /**
+     * Finds all records for the corresponding model in batches,
+     * and then calls the provided callback
+     * for each found record. Once all records
+     * have been passed for a given batch, the next set of
+     * records will be fetched and passed to your callback, until all
+     * records matching the corresponding model have been fetched.
+     *
+     * ```ts
+     * await User.findEach(user => {
+     *   console.log(user)
+     * })
+     * // User{email: 'hello@world'}
+     * // User{email: 'goodbye@world'}
+     * ```
+     *
+     * @param cb - The callback to call for each found record
+     * @param opts.batchSize - the batch size you wish to collect records in. If not provided, it will default to 1000
+     * @returns void
+     */
+    static async findEach(cb, opts) {
+        await this.query().findEach(cb, opts);
+    }
+    /**
+     * Returns a new instance of Query scoped to the given
+     * model class
+     *
+     * ```ts
+     * await User.query().all()
+     * // [User{id: 1}, User{id: 2}, ...]
+     * ```
+     *
+     * @returns A new Query instance scoped to this Dream class
+     *
+     */
+    static query() {
+        return new Query(this.prototype);
+    }
+    /**
+     * @internal
+     *
+     * Returns a new instance of Query scoped to the given
+     * Dream instance
+     *
+     * ```ts
+     * await user = User.first()
+     * await user.query()
+     * ```
+     *
+     * @returns A new Query instance scoped to this Dream instance
+     *
+     */
+    query() {
+        const dreamClass = this.constructor;
+        return dreamClass.where({ [this.primaryKey]: this.primaryKeyValue });
+    }
+    /**
+     * Finds the first record—ordered by primary key—matching
+     * the corresponding model and the specified where statement.
+     * If not found, null is returned.
+     *
+     * ```ts
+     * await User.findBy({ email: 'how@yadoin' })
+     * // User{email: 'how@yadoin'}
+     * ```
+     *
+     * @param whereStatement - The where statement used to locate the record
+     * @returns The first model found matching the whereStatement
+     */
+    static async findBy(whereStatement) {
+        return await this.query().findBy(whereStatement);
+    }
+    /**
+     * Finds the first record—ordered by primary key—matching
+     * the corresponding model and the specified where statement.
+     * If not found, an exception is raised.
+     *
+     * ```ts
+     * await User.findOrFailBy({ email: 'how@yadoin' })
+     * // User{email: 'how@yadoin'}
+     * ```
+     *
+     * @param whereStatement - The where statement used to locate the record
+     * @returns The first model found matching the whereStatement
+     */
+    static async findOrFailBy(whereStatement) {
+        return await this.query().findOrFailBy(whereStatement);
+    }
+    /**
+     * Attempt to find the model with the given attributes.
+     * If no record is found, then a new record is created.
+     *
+     * ```ts
+     * const user = await User.findOrCreateBy({ email }, { createWith: params })
+     * ```
+     *
+     * @param attributes - The base attributes for finding, but also the attributes to use when creating
+     * @param extraOpts.createWith - additional attributes to persist when creating, but not used for finding
+     * @returns A dream instance
+     */
+    static async findOrCreateBy(attributes, extraOpts = {}) {
+        const existingRecord = await this.findBy(this.extractAttributesFromUpdateableProperties(attributes));
+        if (existingRecord)
+            return existingRecord;
+        const dreamModel = this.new({
+            ...attributes,
+            ...(extraOpts?.createWith || {}),
+        });
+        await dreamModel.save();
+        return dreamModel;
+    }
+    /**
+     * Returns true if a record exists for the given
+     * model class
+     *
+     * ```ts
+     * await User.exists()
+     * // false
+     *
+     * await User.create({ email: 'how@yadoin' })
+     *
+     * await User.exists()
+     * // true
+     * ```
+     *
+     * @returns boolean
+     */
+    static async exists() {
+        return await this.query().exists();
+    }
+    /**
+     * Load each specified association using a single SQL query.
+     * See {@link #preload} for preloading in separate queries.
+     *
+     * Note: since leftJoinPreload loads via single query, it has
+     * some downsides and that may be avoided using {@link #preload}:
+     * 1. `limit` and `offset` will be automatically removed
+     * 2. `through` associations will bring additional namespaces into the query that can conflict with through associations from other associations, creating an invalid query
+     * 3. each nested association will result in an additional record which duplicates data from the outer record. E.g., given `.leftJoinPreload('a', 'b', 'c')`, if each `a` has 10 `b` and each `b` has 10 `c`, then for one `a`, 100 records will be returned, each of which has all of the columns of `a`. `.preload('a', 'b', 'c')` would perform three separate SQL queries, but the data for a single `a` would only be returned once.
+     * 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, `.preload(...).findEach(...)` avoids instantiating massive amounts of data at once
+     *
+     * ```ts
+     * const user = await User.leftJoinPreload('posts', 'comments', { visibilty: 'public' }, 'replies').first()
+     * console.log(user.posts[0].comments[0].replies)
+     * // [Reply{id: 1}, Reply{id: 2}]
+     * ```
+     *
+     * @param args - A chain of association names and where clauses
+     * @returns A query for this model with the include statement applied
+     */
+    static leftJoinPreload(...args) {
+        return this.query().leftJoinPreload(...args);
+    }
+    /**
+     * Applies preload statement to a Query scoped to this model.
+     * Upon instantiating records of this model type,
+     * specified associations will be preloaded.
+     *
+     * Preloading/loading/including is necessary prior to accessing associations
+     * on a Dream instance.
+     *
+     * Preload is useful for avoiding the N+1 query problem
+     *
+     * ```ts
+     * const user = await User.preload('posts', 'comments', { visibilty: 'public' }, 'replies').first()
+     * console.log(user.posts[0].comments[0].replies)
+     * // [Reply{id: 1}, Reply{id: 2}]
+     * ```
+     *
+     * @param args - A chain of association names and where clauses
+     * @returns A query for this model with the preload statement applied
+     */
+    static preload(...args) {
+        return this.query().preload(...args);
+    }
+    /**
+     * Returns a new Query instance with the provided
+     * inner join statement attached
+     *
+     * ```ts
+     * await User.innerJoin('posts').first()
+     * ```
+     *
+     * @param args - A chain of association names and where clauses
+     * @returns A Query for this model with the inner join clause applied
+     */
+    static innerJoin(...args) {
+        return this.query().innerJoin(...args);
+    }
+    /**
+     * Returns a new Query instance with the provided
+     * inner join statement attached
+     *
+     * ```ts
+     * await user.innerJoin('posts').first()
+     * ```
+     *
+     * @param args - A chain of association names and where clauses
+     * @returns A Query for this model with the inner join clause applied
+     */
+    innerJoin(...args) {
+        return this.query().innerJoin(...args);
+    }
+    /**
+     * Returns a new Query instance with the provided
+     * left join statement attached
+     *
+     * ```ts
+     * await User.leftJoin('posts').first()
+     * ```
+     *
+     * @param args - A chain of association names and where clauses
+     * @returns A Query for this model with the left join clause applied
+     */
+    static leftJoin(...args) {
+        return this.query().leftJoin(...args);
+    }
+    /**
+     * Returns a new Query instance with the provided
+     * left join statement attached
+     *
+     * ```ts
+     * await user.leftJoin('posts').first()
+     * ```
+     *
+     * @param args - A chain of association names and where clauses
+     * @returns A Query for this model with the left join clause applied
+     */
+    leftJoin(...args) {
+        return this.query().leftJoin(...args);
+    }
+    /**
+     * Returns the first record corresponding to the
+     * model, ordered by primary key.
+     *
+     * ```ts
+     * await User.first()
+     * // User{id: 1}
+     * ```
+     *
+     * @returns First record, or null if no record exists
+     */
+    static async first() {
+        return await this.query().first();
+    }
+    /**
+     * Returns the first record corresponding to the
+     * model, ordered by primary key. If no record is
+     * found, an exception is raised.
+     *
+     * ```ts
+     * await User.firstOrFail()
+     * // User{id: 1}
+     * ```
+     *
+     * @returns First record
+     */
+    static async firstOrFail() {
+        return await this.query().firstOrFail();
+    }
+    /**
+     * Returns the last record corresponding to the
+     * model, ordered by primary key.
+     *
+     * ```ts
+     * await User.last()
+     * // User{id: 99}
+     * ```
+     *
+     * @returns Last record, or null if no record exists
+     */
+    static async last() {
+        return await this.query().last();
+    }
+    /**
+     * Returns the last record corresponding to the
+     * model, ordered by primary key. If no record
+     * is found, an exception is raised.
+     *
+     * ```ts
+     * await User.lastOrFail()
+     * // User{id: 99}
+     * ```
+     *
+     * @returns Last record
+     */
+    static async lastOrFail() {
+        return await this.query().lastOrFail();
+    }
+    /**
+     * Returns a new Query instance, specifying a limit
+     *
+     * ```ts
+     * await User.limit(2).all()
+     * // [User{}, User{}]
+     * ```
+     *
+     * @returns A Query for this model with the limit clause applied
+     */
+    static limit(count) {
+        return this.query().limit(count);
+    }
+    /**
+     * Returns a new Query instance, specifying an offset
+     *
+     * ```ts
+     * await User.offset(2).order('id').limit(2).all()
+     * // [User{id: 3}, User{id: 4}]
+     * ```
+     *
+     * @returns A Query for this model with the offset clause applied
+     */
+    static offset(offset) {
+        return this.query().offset(offset);
+    }
+    /**
+     * Returns a new Query instance, attaching the provided
+     * order statement
+     *
+     * ```ts
+     * await User.order('id').all()
+     * // [User{id: 1}, User{id: 2}, ...]
+     * ```
+     *
+     * ```ts
+     * await User.order({ name: 'asc', id: 'desc' }).all()
+     * // [User{name: 'a', id: 99}, User{name: 'a', id: 97}, User{ name: 'b', id: 98 } ...]
+     * ```
+     *
+     * @param orderStatement - Either a string or an object specifying order. If a string, the order is implicitly ascending. If the orderStatement is an object, statements will be provided in the order of the keys set in the object
+     * @returns A query for this model with the order clause applied
+     */
+    static order(orderStatement) {
+        return this.query().order(orderStatement);
+    }
+    /**
+     * Plucks the provided fields from the corresponding model
+     *
+     * ```ts
+     * await User.pluck('id')
+     * // [1, 3, 2]
+     * ```
+     *
+     * If more than one column is requested, a multi-dimensional
+     * array is returned:
+     *
+     * ```ts
+     * await User.order('id').pluck('id', 'email')
+     * // [[1, 'a@a.com'], [2, 'b@b.com']]
+     * ```
+     *
+     * @param columnNames - The column or array of columns to pluck
+     * @returns An array of pluck results
+     */
+    static async pluck(...columnNames) {
+        return (await this.query().pluck(...columnNames));
+    }
+    /**
+     * Plucks the specified fields from the given dream class table
+     * in batches, passing each found columns into the
+     * provided callback function
+     *
+     * ```ts
+     * await User.order('id').pluckEach('id', (id) => {
+     *   console.log(id)
+     * })
+     * // 1
+     * // 2
+     * // 3
+     * ```
+     *
+     * @param fields - a list of fields to pluck, followed by a callback function to call for each set of found fields
+     * @returns void
+     */
+    static async pluckEach(...args) {
+        return await this.query().pluckEach(...args);
+    }
+    /**
+     * Used in conjunction with the Sortable decorator, `resort`
+     * takes a list of sortable fields, and for each one, finds and
+     * sorts each record in the DB matching the field based on the
+     * scope provided for each Sortable decorator found.
+     *
+     * Calling this method shouldn't be necessary, but if
+     * the contents of the database have shifted without firing the
+     * correct callback mechanisms at the application layer, calling
+     * `resort` will ensure that all sortable fields are set from 1..n
+     * with no gaps, accounting for the scopes specified in the
+     * corresponding Sortable decorator.
+     *
+     * ```ts
+     * class Post extends ApplicationModel {
+     *   @Sortable({ scope: ['user']})
+     *   public position: DreamColumn<User, 'position'>
+     * }
+     *
+     * await Post.all()
+     * // [Post{position: 1}, Post{position: 3}, Post{position: 5}]
+     *
+     * await Post.resort('position')
+     * await Post.all()
+     * // [Post{position: 1}, Post{position: 2}, Post{position: 3}]
+     * ```
+     *
+     * @param fields - A list of sortable fields to resort
+     * @returns void
+     *
+     */
+    static async resort(...fields) {
+        for (const field of fields) {
+            const sortableMetadata = this.sortableFields.find(conf => conf.positionField === field);
+            if (!sortableMetadata)
+                throw new NonExistentScopeProvidedToResort(fields, this);
+            await resortAllRecords(this, field, sortableMetadata.scope);
+        }
+    }
+    /**
+     * Returns a Query scoped to this model with
+     * the specified scope applied.
+     *
+     * ```ts
+     * class User extends ApplicationModel {
+     *   @Scope()
+     *   public visible(query: Query<User>) {
+     *     return query.where({ hidden: false })
+     *   }
+     * }
+     *
+     * await User.scope('visible').all()
+     * // [User{hidden: false}, User{hidden: false}]
+     * ```
+     *
+     * @param scopeName - The name of the scope
+     * @returns a Query scoped to this model with the specified scope applied
+     */
+    static scope(scopeName) {
+        return this[scopeName](this.query());
+    }
+    /**
+     * Returns the sql that would be executed by a Query
+     * scoped to this model.
+     *
+     * ```ts
+     * User.sql()
+     * // {
+     * //  query: {
+     * //    kind: 'SelectQueryNode',
+     * //    from: { kind: 'FromNode', froms: [Array] },
+     * //    selections: [ [Object] ],
+     * //    distinctOn: undefined,
+     * //    joins: undefined,
+     * //    groupBy: undefined,
+     * //    orderBy: undefined,
+     * //    where: { kind: 'WhereNode', where: [Object] },
+     * //    frontModifiers: undefined,
+     * //    endModifiers: undefined,
+     * //    limit: undefined,
+     * //    offset: undefined,
+     * //    with: undefined,
+     * //    having: undefined,
+     * //    explain: undefined,
+     * //    setOperations: undefined
+     * //  },
+     * //  sql: 'select "users".* from "users" where "users"."deleted_at" is null',
+     * //  parameters: []
+     * //}
+     * ```
+     *
+     * @returns An object representing the underlying sql statement
+     *
+     */
+    static sql() {
+        return this.query().sql();
+    }
+    /**
+     * Converts the given Dream class into a Kysely query, enabling
+     * you to build custom queries using the Kysely API
+     *
+     * ```ts
+     * await User.toKysely('select').where('email', '=', 'how@yadoin').execute()
+     * ```
+     *
+     * @param type - The type of Kysely query builder instance you would like to obtain
+     * @returns A Kysely query. Depending on the type passed, it will return either a SelectQueryBuilder, DeleteQueryBuilder, UpdateQueryBuilder, or an InsertQueryBuilder
+     */
+    static toKysely(type) {
+        switch (type) {
+            case 'select':
+                return this.query().dbFor('select').selectFrom(this.table);
+            case 'delete':
+                return this.query().dbFor('delete').deleteFrom(this.table);
+            case 'update':
+                return this.query().dbFor('update').updateTable(this.table);
+            case 'insert':
+                return this.query().dbFor('insert').insertInto(this.table);
+            default:
+                throw new Error('never');
+        }
+    }
+    /**
+     * Applies transaction to a new Query scoped
+     * to this model
+     *
+     * ```ts
+     * await ApplicationModel.transaction(async txn => {
+     *   await User.txn(txn).create({ email: 'how@yadoin' })
+     * })
+     * ```
+     *
+     * @param txn - A DreamTransaction instance (usually collected by calling `ApplicationModel.transaction`)
+     * @returns A Query scoped to this model with the transaction applied
+     */
+    static txn(txn) {
+        return new DreamClassTransactionBuilder(this.prototype, txn);
+    }
+    /**
+     * Builds a new DreamTransaction instance, provides
+     * the instance to the provided callback.
+     *
+     * ```ts
+     * await ApplicationModel.transaction(async txn => {
+     *   const user = await User.txn(txn).create({ email: 'how@yadoin' })
+     *   await Pet.txn(txn).create({ user })
+     * })
+     * ```
+     *
+     * @param callback - A callback function to call. The transaction provided to the callback can be passed to subsequent database calls within the transaction callback
+     * @returns void
+     */
+    static async transaction(callback) {
+        const dreamTransaction = new DreamTransaction();
+        let callbackResponse = undefined;
+        await db('primary')
+            .transaction()
+            .execute(async (kyselyTransaction) => {
+            dreamTransaction.kyselyTransaction = kyselyTransaction;
+            callbackResponse = (await callback(dreamTransaction));
+        });
+        await dreamTransaction.runAfterCommitHooks(dreamTransaction);
+        return callbackResponse;
+    }
+    /**
+     * Sends data through for use as passthrough data
+     * for the associations that require it.
+     *
+     * ```ts
+     * class Post {
+     *   @Deco.HasMany('LocalizedText')
+     *   public localizedTexts: LocalizedText[]
+     *
+     *   @Deco.HasOne('LocalizedText', {
+     *     where: { locale: DreamConst.passthrough },
+     *   })
+     *   public currentLocalizedText: LocalizedText
+     * }
+     *
+     * await User.passthrough({ locale: 'es-ES' })
+     *   .preload('posts', 'currentLocalizedText')
+     *   .first()
+     * ```
+     *
+     * @param passthroughWhereStatement - Where statement used for associations that require passthrough data
+     * @returns A Query for this model with the passthrough data
+     */
+    static passthrough(passthroughWhereStatement) {
+        return this.query().passthrough(passthroughWhereStatement);
+    }
+    /**
+     * Applies a where statement to a new Query instance
+     * scoped to this model
+     *
+     * ```ts
+     * await User.where({ email: 'how@yadoin' }).first()
+     * // User{email: 'how@yadoin'}
+     * ```
+     *
+     * @param whereStatement - Where statement to apply to the Query
+     * @returns A Query for this model with the where clause applied
+     */
+    static where(whereStatement) {
+        return this.query().where(whereStatement);
+    }
+    /**
+     * Applies "OR"'d where statements to a Query scoped
+     * to this model.
+     *
+     * ```ts
+     * await User.whereAny([{ email: 'how@yadoin' }, { name: 'fred' }]).first()
+     * // [User{email: 'how@yadoin'}, User{name: 'fred'}, User{name: 'fred'}]
+     * ```
+     *
+     * @param whereStatements - a list of where statements to `OR` together
+     * @returns A Query for this model with the whereAny clause applied
+     */
+    static whereAny(statements) {
+        return this.query().whereAny(statements);
+    }
+    /**
+     * Applies a whereNot statement to a new Query instance
+     * scoped to this model.
+     *
+     * ```ts
+     * await User.whereNot({ email: 'how@yadoin' }).first()
+     * // User{email: 'hello@world'}
+     * ```
+     *
+     * @param whereStatement - A where statement to negate and apply to the Query
+     * @returns A Query for this model with the whereNot clause applied
+     */
+    static whereNot(attributes) {
+        return this.query().whereNot(attributes);
+    }
+    /**
+     * @internal
+     *
+     * Given a column, checks to see if it is a foreign key
+     * belonging to a BelongsTo association
+     *
+     * ```ts
+     * Post.isBelongsToAssociationForeignKey('id')
+     * // false
+     * Post.isBelongsToAssociationForeignKey('userId')
+     * // true
+     * ```
+     *
+     * @param column - A column on this Dream class
+     * @returns A boolean
+     */
+    static isBelongsToAssociationForeignKey(column) {
+        return this.belongsToAssociationForeignKeys().includes(column);
+    }
+    /**
+     * @internal
+     *
+     * Given a column, checks to see if it is a belongs to
+     * polymorphic type field
+     *
+     * ```ts
+     * LocalizedText.isBelongsToAssociationPolymorphicTypeField('localizableId')
+     * // false
+     * LocalizedText.isBelongsToAssociationPolymorphicTypeField('localizableType')
+     * // true
+     * ```
+     *
+     * @param column - a column on this dream class
+     * @returns A boolean
+     */
+    static isBelongsToAssociationPolymorphicTypeField(column) {
+        return this.polymorphicTypeColumns().includes(column);
+    }
+    /**
+     * @internal
+     *
+     * Returns an array of column names that are belongs
+     * to foreign keys on this dream class
+     *
+     * ```ts
+     * Post.belongsToAssociationForeignKeys()
+     * // ['userId']
+     * ```
+     *
+     * @returns An array of column names that are belongs to foreign keys on this dream class
+     */
+    static belongsToAssociationForeignKeys() {
+        const associationMap = this.associationMetadataMap();
+        return this.belongsToAssociationNames().map(belongsToKey => associationMap[belongsToKey].foreignKey());
+    }
+    /**
+     * @internal
+     *
+     * Returns all polymorphic type columns
+     *
+     * ```ts
+     * LocalizedText.polymorphicTypeColumns()
+     * // ['localizableType']
+     * ```
+     *
+     * @returns An array of column names that are polymorphic type fields on the given dream class
+     */
+    static polymorphicTypeColumns() {
+        const associationMap = this.associationMetadataMap();
+        return this.belongsToAssociationNames()
+            .filter(key => associationMap[key].polymorphic)
+            .map(belongsToKey => associationMap[belongsToKey].foreignKeyTypeField());
+    }
+    /**
+     * @internal
+     *
+     * Returns a list of association names which
+     * correspond to belongs to associations
+     * on this model class.
+     *
+     * ```ts
+     * Post.belongsToAssociationNames()
+     * // ['user']
+     * ```
+     *
+     * @returns An array of belongs to association names
+     */
+    static belongsToAssociationNames() {
+        const associationMap = this.associationMetadataMap();
+        return Object.keys(associationMap).filter(key => associationMap[key].type === 'BelongsTo');
+    }
+    /**
+     * @internal
+     *
+     * Returns a list of association names which
+     * have `dependent: destroy` set
+     *
+     * ```ts
+     * Post.dependentDestroyAssociationNames()
+     * // ['user']
+     * ```
+     *
+     * @returns An array of HasOne/HasMany association names with `dependent: 'destroy'` defined
+     */
+    static dependentDestroyAssociationNames() {
+        const associationMap = this.associationMetadataMap();
+        return Object.keys(associationMap).filter(key => associationMap[key]
+            .dependent === 'destroy');
+    }
+    /**
+     * @internal
+     *
+     * Returns the metadata for the provided association
+     *
+     * ```ts
+     * new Post()['getAssociationMetadata']('user')
+     * // {
+     * //    modelCB: [Function (anonymous)],
+     * //    type: 'BelongsTo',
+     * //    as: 'user',
+     * //    optional: false,
+     * //    polymorphic: false,
+     * //    primaryKeyOverride: null,
+     * //    primaryKey: [Function: primaryKey],
+     * //    primaryKeyValue: [Function: primaryKeyValue],
+     * //    foreignKey: [Function: foreignKey],
+     * //    foreignKeyTypeField: [Function: foreignKeyTypeField]
+     * //  }
+     * ```
+     *
+     * @returns Association metadata
+     *
+     */
+    getAssociationMetadata(associationName) {
+        return this.constructor.getAssociationMetadata(associationName);
+    }
+    /**
+     * @internal
+     *
+     * Returns all association metadata for the given dream class
+     *
+     * ```ts
+     * new Post()['associationMetadataMap']()
+     * // {
+     * //     user: {
+     * //       modelCB: [Function (anonymous)],
+     * //       type: 'BelongsTo',
+     * //       as: 'user',
+     * //       optional: false,
+     * //       polymorphic: false,
+     * //       primaryKeyOverride: null,
+     * //       primaryKey: [Function: primaryKey],
+     * //       primaryKeyValue: [Function: primaryKeyValue],
+     * //       foreignKey: [Function: foreignKey],
+     * //       foreignKeyTypeField: [Function: foreignKeyTypeField]
+     * //     },
+     * //     ratings: {
+     * //       modelCB: [Function (anonymous)],
+     * //       type: 'HasMany',
+     * //       as: 'ratings',
+     * //       polymorphic: true,
+     * //       source: 'ratings',
+     * //       preloadThroughColumns: undefined,
+     * //       where: undefined,
+     * //       whereNot: undefined,
+     * //       selfWhere: undefined,
+     * //       selfWhereNot: undefined,
+     * //       primaryKeyOverride: null,
+     * //       primaryKey: [Function: primaryKey],
+     * //       primaryKeyValue: [Function: primaryKeyValue],
+     * //       through: undefined,
+     * //       distinct: undefined,
+     * //       order: undefined,
+     * //       foreignKey: [Function: foreignKey],
+     * //       foreignKeyTypeField: [Function: foreignKeyTypeField]
+     * //     },
+     * //     ...
+     * // }
+     * ```
+     *
+     * @returns association metadata
+     */
+    associationMetadataMap() {
+        return this.constructor.associationMetadataMap();
+    }
+    /**
+     * @internal
+     *
+     * returns all association data for the given dream class,
+     * organized by the type of association
+     *
+     * ```ts
+     * new Post().associationMetadataByType
+     * // {
+     * //   belongsTo: [
+     * //     {
+     * //       modelCB: [Function (anonymous)],
+     * //       type: 'BelongsTo',
+     * //       as: 'user',
+     * //       optional: false,
+     * //       polymorphic: false,
+     * //       primaryKeyOverride: null,
+     * //       primaryKey: [Function: primaryKey],
+     * //       primaryKeyValue: [Function: primaryKeyValue],
+     * //       foreignKey: [Function: foreignKey],
+     * //       foreignKeyTypeField: [Function: foreignKeyTypeField]
+     * //     },
+     * //   ],
+     * //   hasMany: [
+     * //   ],
+     * //   hasOne: []
+     * //   }
+     * // }
+     * ```
+     *
+     * @returns association metadata by type
+     *
+     */
+    get associationMetadataByType() {
+        return this.constructor.associationMetadataByType;
+    }
+    /**
+     * @internal
+     *
+     * Returns an array of association names for the
+     * given dream class
+     *
+     * ```ts
+     * new Post().associationNames
+     * // [ 'user', 'postVisibility', 'ratings', 'heartRatings' ]
+     * ```
+     *
+     * @returns association names array
+     */
+    get associationNames() {
+        return this.constructor.associationNames;
+    }
+    /**
+     * Returns true if any of the attributes on the instance
+     * have changed since it was last pulled from the database.
+     * It will also return true if the instance is not yet
+     * persisted.
+     *
+     * ```ts
+     * const post = Post.new({ body: 'howyadoin' })
+     * post.isDirty
+     * // true
+     *
+     * await post.save()
+     * post.isDirty
+     * // false
+     *
+     * post.body = 'groiyyyt'
+     * post.isDirty
+     * // true
+     * ```
+     *
+     * @returns A boolean
+     */
+    get isDirty() {
+        return !!Object.keys(this.dirtyAttributes()).length;
+    }
+    /**
+     * Returns true. This is useful for identifying
+     * dream instances from other objects
+     *
+     * @returns true
+     */
+    get isDreamInstance() {
+        return true;
+    }
+    /**
+     * Runs validation checks against all validations
+     * declared using the Validate and Validates decorators,
+     * and returns true if any of them fail.
+     *
+     * ```ts
+     * class User extends ApplicationModel {
+     *   @Validates('presence')
+     *   public email: DreamColumn<User, 'email'>
+     * }
+     * const user = User.new()
+     * user.isInvalid
+     * // true
+     *
+     * user.email = 'how@yadoin'
+     * user.isInvalid
+     * // false
+     * ```
+     *
+     * @returns A boolean
+     */
+    get isInvalid() {
+        return !this.isValid;
+    }
+    /**
+     * Returns true if the model has not been persisted
+     * to the database.
+     *
+     * ```ts
+     * const user = User.new({ email: 'howyadoin' })
+     * user.isNewRecord
+     * // true
+     *
+     * await user.save()
+     * user.isNewRecord
+     * // false
+     * ```
+     *
+     * @returns A boolean
+     */
+    get isNewRecord() {
+        return !this.isPersisted;
+    }
+    /**
+     * Runs validation checks against all validations
+     * declared using the Validate and Validates decorators.
+     * Returns true if none of the validations fail.
+     *
+     * NOTE: Any validations that fail will leave the errors
+     * field populated on your model instance.
+     *
+     * ```ts
+     * class User extends ApplicationModel {
+     *   @Validates('presence')
+     *   public email: DreamColumn<User, 'email'>
+     * }
+     *
+     * const user = User.new()
+     * user.isValid
+     * // false
+     *
+     * user.email = 'how@yadoin'
+     * user.isValid
+     * // true
+     * ```
+     *
+     * @returns A boolean
+     */
+    get isValid() {
+        this._errors = {};
+        runValidations(this);
+        return !Object.keys(this.errors).filter(key => !!this.errors[key].length).length;
+    }
+    /**
+     * The name of the primary key column on this model.
+     * NOTE: Must specify `as const` when defining a custom
+     * primary key.
+     *
+     * ```ts
+     * class User extends ApplicationModel {
+     *   public customIdField: DreamColumn<User, 'customIdField'>
+     *
+     *   public get primaryKey() {
+     *     return 'customIdField' as const
+     *   }
+     * }
+     * ```
+     *
+     * @returns The primary key column name
+     */
+    get primaryKey() {
+        return 'id';
+    }
+    /**
+     * Returns the value of the primary key
+     *
+     * @returns The value of the primary key field for this Dream instance
+     */
+    get primaryKeyValue() {
+        return this[this.primaryKey] || null;
+    }
+    /**
+     * This must be defined on every model, and it must point
+     * to a table in your database. In addition, you must
+     * return the value using the `as const` suffix, like so:
+     *
+     * ```ts
+     * class User extends ApplicationModel {
+     *   public get table() {
+     *     return 'users' as const
+     *   }
+     * }
+     * ```
+     *
+     * @returns The table name for this model
+     */
+    get table() {
+        throw new MissingTable(this.constructor);
+    }
+    /**
+     * @internal
+     *
+     * _errors is used to inform validation errors,
+     * and is built whenever validations are run on
+     * a dream instance.
+     */
+    _errors = {};
+    /**
+     * @internal
+     *
+     * Used for the changes api
+     */
+    frozenAttributes = {};
+    /**
+     * @internal
+     *
+     * Used for the changes api
+     */
+    originalAttributes = {};
+    /**
+     * @internal
+     *
+     * Used for the changes api
+     */
+    currentAttributes = {};
+    /**
+     * @internal
+     *
+     * Used for the changes api
+     */
+    attributesFromBeforeLastSave = {};
+    /**
+     * @internal
+     *
+     * Stores whether the record has been persisted or not
+     */
+    _isPersisted;
+    /**
+     * Returns true if the model has been persisted
+     * to the database.
+     *
+     * ```ts
+     * const user = User.new({ email: 'howyadoin' })
+     * user.isPersisted
+     * // false
+     *
+     * await user.save()
+     * user.isPersisted
+     * // true
+     * ```
+     *
+     * @returns A boolean
+     */
+    get isPersisted() {
+        return this._isPersisted || false;
+    }
+    set isPersisted(val) {
+        this._isPersisted = val;
+    }
+    /**
+     * Since typescript prevents constructor functions
+     * from absorbing type generics, we provide the `new`
+     * method to instantiate with type protection
+     *
+     * ```ts
+     * const user = User.new({ email: 'how@yadoin' })
+     * ```
+     *
+     * @returns A new (unpersisted) instance of the provided dream class
+     */
+    static new(opts, additionalOpts = {}) {
+        const dreamModel = new this(opts, {
+            ...additionalOpts,
+            _internalUseOnly: true,
+        });
+        dreamModel.finalizeConstruction();
+        return dreamModel;
+    }
+    /**
+     * @internal
+     *
+     * NOTE: avoid using the constructor function directly.
+     * Use the static `.new` or `.create` methods instead, which
+     * will provide type guarding for your attributes.
+     *
+     * Since typescript prevents constructor functions
+     * from absorbing type generics, we provide the `new`
+     * method to instantiate with type protection.
+     *
+     * ```ts
+     * const user = User.new({ email: 'how@yadoin' })
+     * ```
+     *
+     * @returns A new (unpersisted) instance of the provided dream class
+     */
+    constructor(opts, additionalOpts) {
+        if (!additionalOpts._internalUseOnly)
+            throw new ConstructorOnlyForInternalUse();
+        this.isPersisted = additionalOpts?.isPersisted || false;
+        this.defineAttributeAccessors();
+        if (opts) {
+            const marshalledOpts = this._setAttributes(opts, additionalOpts);
+            // if id is set, then we freeze attributes after setting them, so that
+            // any modifications afterwards will indicate updates.
+            if (this.isPersisted) {
+                this.freezeAttributes();
+                this.originalAttributes = { ...marshalledOpts };
+                this.attributesFromBeforeLastSave = { ...marshalledOpts };
+            }
+            else {
+                const columns = this.constructor.columns();
+                columns.forEach(column => {
+                    this.originalAttributes[column] = undefined;
+                    this.attributesFromBeforeLastSave[column] = undefined;
+                });
+            }
+        }
+        /**
+         *
+         * Modern Javascript sets all properties that do not have an explicit
+         * assignment within the constructor to undefined in an implicit constructor.
+         * Since the Dream constructor sets the value of properties of instances of
+         * classes that extend Dream (e.g. when passing attributes to #new or #create
+         * or when loading a model via one of the #find methods or #all), we need to
+         * prevent those properties from being set back to undefined. Since all
+         * properties corresponding to a database column get a setter, we achieve this
+         * protection by including a guard in the setters that returns if this
+         * property is set.
+         *
+         */
+        this.columnSetterGuardActivated = true;
+    }
+    /**
+     * @internal
+     *
+     * Used for determining which attributes to update
+     */
+    static extractAttributesFromUpdateableProperties(attributes, dreamInstance, { bypassUserDefinedSetters = false } = {}) {
+        const returnValues = {};
+        const setAttributeOnDreamInstance = (attr, value) => {
+            if (!dreamInstance)
+                return;
+            if (bypassUserDefinedSetters) {
+                dreamInstance.setAttribute(attr, value);
+            }
+            else {
+                dreamInstance.assignAttribute(attr, value);
+            }
+        };
+        Object.keys(attributes).forEach(attr => {
+            const associationMetaData = this.associationMetadataMap()[attr];
+            if (associationMetaData && associationMetaData.type !== 'BelongsTo') {
+                throw new CanOnlyPassBelongsToModelParam(this, associationMetaData);
+            }
+            else if (associationMetaData) {
+                const belongsToAssociationMetaData = associationMetaData;
+                const associatedObject = attributes[attr];
+                // if dream instance is passed, set the loaded association
+                if (dreamInstance && associatedObject !== undefined)
+                    dreamInstance[attr] = associatedObject;
+                if (!associationMetaData.optional && !associatedObject)
+                    throw new CannotPassNullOrUndefinedToRequiredBelongsTo(this, associationMetaData);
+                const foreignKey = belongsToAssociationMetaData.foreignKey();
+                const foreignKeyValue = belongsToAssociationMetaData.primaryKeyValue(associatedObject);
+                if (foreignKeyValue !== undefined) {
+                    returnValues[foreignKey] = foreignKeyValue;
+                    setAttributeOnDreamInstance(foreignKey, returnValues[foreignKey]);
+                    // Set the belongs-to association
+                    setAttributeOnDreamInstance(attr, attributes[attr]);
+                }
+                if (belongsToAssociationMetaData.polymorphic) {
+                    const foreignKeyTypeField = belongsToAssociationMetaData.foreignKeyTypeField();
+                    returnValues[foreignKeyTypeField] = associatedObject?.stiBaseClassOrOwnClass?.name;
+                    setAttributeOnDreamInstance(foreignKeyTypeField, returnValues[foreignKeyTypeField]);
+                }
+            }
+            else {
+                returnValues[attr] = attributes[attr];
+                setAttributeOnDreamInstance(attr, returnValues[attr]);
+            }
+        });
+        return returnValues;
+    }
+    /**
+     * @internal
+     *
+     * defines attribute setters and getters for every column
+     * set within your types/dream.ts file
+     */
+    defineAttributeAccessors() {
+        const dreamClass = this.constructor;
+        const columns = dreamClass.columns();
+        const dreamPrototype = Object.getPrototypeOf(this);
+        columns.forEach(column => {
+            // this ensures that the currentAttributes object will contain keys
+            // for each of the properties
+            if (this.currentAttributes[column] === undefined)
+                this.currentAttributes[column] = undefined;
+            if (!Object.getOwnPropertyDescriptor(dreamPrototype, column)?.set) {
+                if (isJsonColumn(this.constructor, column)) {
+                    // handle JSON columns
+                    Object.defineProperty(dreamPrototype, column, {
+                        get() {
+                            if ([undefined, null].includes(this.currentAttributes[column]))
+                                return this.currentAttributes[column];
+                            return JSON.parse(this.currentAttributes[column]);
+                        },
+                        set(val) {
+                            /**
+                             *
+                             * Modern Javascript sets all properties that do not have an explicit
+                             * assignment within the constructor to undefined in an implicit constructor.
+                             * Since the Dream constructor sets the value of properties of instances of
+                             * classes that extend Dream (e.g. when passing attributes to #new or #create
+                             * or when loading a model via one of the #find methods or #all), we need to
+                             * prevent those properties from being set back to undefined. Since all
+                             * properties corresponding to a database column get a setter, we achieve this
+                             * protection by including a guard in the setters that returns if this
+                             * property is set.
+                             *
+                             */
+                            if (this.columnSetterGuardActivated)
+                                return;
+                            this.currentAttributes[column] = isString(val) ? val : JSON.stringify(val);
+                        },
+                        configurable: true,
+                    });
+                }
+                else {
+                    // handle all other columns
+                    Object.defineProperty(dreamPrototype, column, {
+                        get() {
+                            return this.currentAttributes[column];
+                        },
+                        set(val) {
+                            /**
+                             *
+                             * Modern Javascript sets all properties that do not have an explicit
+                             * assignment within the constructor to undefined in an implicit constructor.
+                             * Since the Dream constructor sets the value of properties of instances of
+                             * classes that extend Dream (e.g. when passing attributes to #new or #create
+                             * or when loading a model via one of the #find methods or #all), we need to
+                             * prevent those properties from being set back to undefined. Since all
+                             * properties corresponding to a database column get a setter, we achieve this
+                             * protection by including a guard in the setters that returns if this
+                             * property is set.
+                             *
+                             */
+                            if (this.columnSetterGuardActivated)
+                                return;
+                            this.currentAttributes[column] = val;
+                        },
+                        configurable: true,
+                    });
+                }
+            }
+        });
+        ensureSTITypeFieldIsSet(this);
+    }
+    /**
+     * @internal
+     *
+     * Modern Javascript applies implicit accessors to instance properties that
+     * shadow prototype accessors applied by Dream. This method is called after
+     * every Dream model is initialized to delete the instance accessors so that
+     * the prototype accessors can be reached.
+     */
+    unshadowColumnPropertyPrototypeAccessors() {
+        ;
+        this.constructor.columns().forEach(column => delete this[column]);
+    }
+    finalizeConstruction() {
+        /**
+         *
+         * Modern Javascript sets all properties that do not have an explicit
+         * assignment within the constructor to undefined in an implicit constructor.
+         * Since the Dream constructor sets the value of properties of instances of
+         * classes that extend Dream (e.g. when passing attributes to #new or #create
+         * or when loading a model via one of the #find methods or #all), we need to
+         * prevent those properties from being set back to undefined. Since all
+         * properties corresponding to a database column get a setter, we achieve this
+         * protection by including a guard in the setters that returns if this
+         * property is set.
+         *
+         */
+        this.columnSetterGuardActivated = false;
+        /**
+         * Modern Javascript applies implicit accessors to instance properties
+         * that don't have an accessor explicitly defined in the class definition.
+         * The instance accessors shadow prototype accessors applied by Dream.
+         * This method is called after every Dream model is initialized to delete the
+         * instance accessors so that the prototype accessors can be reached.
+         */
+        this.unshadowColumnPropertyPrototypeAccessors();
+    }
+    /**
+     * Returns true if the columnName passed is marked by a
+     * Virtual attribute decorator
+     *
+     * @param columnName - A property on this model to check
+     * @returns A boolean
+     */
+    isVirtualColumn(columnName) {
+        return this.constructor.virtualAttributes
+            .map(attr => attr.property)
+            .includes(columnName);
+    }
+    /**
+     * Returns an object with column names for keys, and an
+     * array of strings representing validation errors for values.
+     *
+     * @returns An error object
+     */
+    get errors() {
+        return { ...this._errors };
+    }
+    /**
+     * Adds an error to the model. Any errors added to the model
+     * will cause the model to be invalid, and will prevent the
+     * model from saving.
+     *
+     * ```ts
+     *  class User extends ApplicationModel {
+     *    ...
+     *    @Validate()
+     *    public async validateName() {
+     *      if (typeof this.name === 'number')
+     *        this.addError('name', 'name cannot be a number')
+     *    }
+     *  }
+     * ```
+     *
+     * @returns void
+     */
+    addError(column, error) {
+        this._errors[column] ||= [];
+        this._errors[column].push(error);
+    }
+    /**
+     * Changes the attribute value for a single attribute,
+     * leveraging any custom-defined setters. If you would like to
+     * bypass custom-defined setters, use #setAttribute instead
+     *
+     * ```ts
+     *  const user = new User()
+     *  user.assignAttribute('email', 'sally@gmail.com')
+     * ```
+     */
+    assignAttribute(attr, val) {
+        const self = this;
+        self[attr] = val;
+    }
+    /**
+     * Changes the attribute value for a single attribute internally,
+     * bypassing any custom-defined setters. If you would like to set attributes
+     * without bypassing custom-defined setters, use #assignAttribute instead
+     *
+     * ```ts
+     *  const user = new User()
+     *  user.setAttribute('email', 'sally@gmail.com')
+     * ```
+     */
+    setAttribute(attr, val) {
+        const columns = this.constructor.columns();
+        const self = this;
+        if (columns.has(attr)) {
+            self.currentAttributes[attr] = isJsonColumn(this.constructor, attr)
+                ? isString(val)
+                    ? val
+                    : JSON.stringify(val)
+                : val;
+        }
+        else {
+            self.currentAttributes[attr] = val;
+        }
+    }
+    /**
+     * Returns the value for a columnName provided,
+     * bypassing the getters.
+     *
+     * ```ts
+     *  const user = User.new({ email: 'how@yadoin' })
+     *  user.getAttribute('email') // 'how@yadoin'
+     * ```
+     */
+    getAttribute(columnName) {
+        const columns = this.constructor.columns();
+        const self = this;
+        if (columns.has(columnName)) {
+            return self.currentAttributes[columnName];
+        }
+        else {
+            return self[columnName];
+        }
+    }
+    /**
+     * Returns an object containing all the columns
+     * on this dream class, as well as their values,
+     * bypassing getters.
+     *
+     * ```ts
+     *  const user = User.new({ email: 'how@yadoin' })
+     *  user.attributes()
+     *  // {
+     *  //   email: 'how@yadoin',
+     *  //   ...
+     *  // }
+     * ```
+     */
+    getAttributes() {
+        return { ...this.currentAttributes };
+    }
+    /**
+     * @internal
+     *
+     * Returns the db type stored within the database
+     */
+    static cachedTypeFor(attribute) {
+        return cachedTypeForAttribute(this, attribute);
+    }
+    /**
+     * Returns the attributes that have changed since
+     * being persisted to the database, with the values
+     * that were last persisted to the database.
+     *
+     * ```ts
+     *  const user = User.new({ email: 'original@email', password: 'howyadoin' })
+     *  await user.save()
+     *
+     *  user.email = 'new@email'
+     *  user.changedAttributes()
+     *  // { email: 'original@email' }
+     *
+     *  user.email = 'original@email'
+     *  user.changedAttributes()
+     *  // {}
+     * ```
+     *
+     * @returns An object containing changed attributes and their original values
+     */
+    changedAttributes() {
+        const obj = {};
+        Object.keys(this.dirtyAttributes()).forEach(column => {
+            ;
+            obj[column] = this.frozenAttributes[column];
+        });
+        return obj;
+    }
+    /**
+     * Returns an object containing the attributes that have
+     * changed since last persisting, along with their current
+     * and previously persisted values.
+     *
+     * ```ts
+     * const pet = Pet.new({ species: 'dog' })
+     * pet.changes()
+     * // {
+     * //   species: {
+     * //     was: undefined,
+     * //     now: 'dog',
+     * //   }
+     * // }
+     *
+     * await pet.save()
+     * pet.changes()
+     * // {
+     * //   species: {
+     * //     was: undefined,
+     * //     now: 'dog',
+     * //   }
+     * // }
+     *
+     * pet.species = 'cat'
+     * pet.species = 'frog'
+     * pet.changes()
+     * // {
+     * //   species: {
+     * //     was: 'dog',
+     * //     now: 'frog',
+     * //   }
+     * // }
+     *
+     * await pet.save()
+     * pet.changes()
+     * // {
+     * //   species: {
+     * //     was: 'dog',
+     * //     now: 'frog',
+     * //   }
+     * // }
+     * ```
+     *
+     * @returns An object containing changed attributes
+     */
+    changes() {
+        const obj = {};
+        this.constructor.columns().forEach(column => {
+            const was = this.previousValueForAttribute(column);
+            const now = this[column];
+            if (was !== now) {
+                ;
+                obj[column] = {
+                    was,
+                    now,
+                };
+            }
+        });
+        return obj;
+    }
+    /**
+     * Returns the value most recently persisted
+     * to the database.
+     *
+     * ```ts
+     * const pet = Pet.new({ species: 'cat' })
+     * pet.previousValueForAttribute('species')
+     * // undefined
+     *
+     * await pet.save()
+     * pet.previousValueForAttribute('species')
+     * // undefined
+     *
+     * pet.species = 'dog'
+     * pet.previousValueForAttribute('species')
+     * // 'cat'
+     *
+     * await pet.save()
+     * pet.previousValueForAttribute('species')
+     * // 'cat'
+     *
+     * await pet.update({ species: 'cat' })
+     * pet.previousValueForAttribute('species')
+     * // 'dog'
+     * ```
+     *
+     * @param columName - The column name you want the previous value for
+     * @returns Returns the previous value for an attribute
+     */
+    previousValueForAttribute(columnName) {
+        if (this.frozenAttributes[columnName] !== this[columnName])
+            return this.frozenAttributes[columnName];
+        return this.attributesFromBeforeLastSave[columnName];
+    }
+    /**
+     * Returns true if the columnName provided has
+     * changes that were persisted during the most
+     * recent save.
+     *
+     * @param columnName - the column name to check
+     * @returns A boolean
+     */
+    savedChangeToAttribute(columnName) {
+        const changes = this.changes();
+        const now = changes?.[columnName]?.now;
+        const was = changes?.[columnName]?.was;
+        return this.isPersisted && now !== was;
+    }
+    /**
+     * Returns true if the columnName provided has
+     * changes that have not yet been persisted.
+     *
+     * @param columnName - the column name to check
+     * @returns A boolean
+     */
+    willSaveChangeToAttribute(attribute) {
+        return this.attributeIsDirty(attribute);
+    }
+    /**
+     * Returns the column names for the given model
+     *
+     * @returns The column names for the given model
+     */
+    columns() {
+        return this.constructor.columns();
+    }
+    /**
+     * Returns an object containing the column names
+     * of columns that have changed since last persist,
+     * and their current values.
+     *
+     * ```ts
+     *  const user = User.new({ email: 'hello@world' })
+     *  user.dirtyAttributes()
+     *  // { email: 'hello@world' }
+     *
+     *  await user.save()
+     *
+     *  user.email = 'hello@world'
+     *  user.dirtyAttributes()
+     *  // {}
+     *
+     *  user.email = 'goodbye@world'
+     *  user.dirtyAttributes()
+     *  // { email: 'goodbye@world' }
+     *
+     *  user.email = 'hello@world'
+     *  user.dirtyAttributes()
+     *  // {}
+     * ```
+     *
+     * @returns An object containing the changed attributes
+     */
+    dirtyAttributes() {
+        const obj = {};
+        this.columns().forEach(column => {
+            // TODO: clean up types
+            if (this.attributeIsDirty(column))
+                obj[column] = this.getAttributes()[column];
+        });
+        return obj;
+    }
+    /**
+     * Returns true if an attribute has changes since last persist
+     *
+     * @returns A boolean
+     */
+    attributeIsDirty(attribute) {
+        const frozenValue = this.frozenAttributes[attribute];
+        const currentValue = this.getAttributes()[attribute];
+        if (this.isNewRecord)
+            return true;
+        if (frozenValue instanceof DateTime) {
+            return frozenValue.toMillis() !== this.unknownValueToMillis(currentValue);
+        }
+        else if (frozenValue instanceof CalendarDate) {
+            return frozenValue.toISO() !== this.unknownValueToDateString(currentValue);
+        }
+        else {
+            return frozenValue !== currentValue;
+        }
+    }
+    /**
+     * @internal
+     */
+    unknownValueToMillis(currentValue) {
+        if (!currentValue)
+            return;
+        if (isString(currentValue))
+            currentValue = DateTime.fromISO(currentValue);
+        if (currentValue instanceof CalendarDate)
+            currentValue = currentValue.toDateTime();
+        if (currentValue instanceof DateTime && currentValue.isValid)
+            return currentValue.toMillis();
+    }
+    /**
+     * @internal
+     */
+    unknownValueToDateString(currentValue) {
+        if (!currentValue)
+            return;
+        if (isString(currentValue))
+            currentValue = CalendarDate.fromISO(currentValue);
+        if (currentValue instanceof DateTime)
+            currentValue = CalendarDate.fromDateTime(currentValue);
+        if (currentValue instanceof CalendarDate && currentValue.isValid)
+            return currentValue.toISO();
+    }
+    /**
+     * Deletes the record represented by this instance
+     * from the database, calling any destroy
+     * hooks on this model.
+     *
+     * ```ts
+     * const user = await User.last()
+     * await user.destroy()
+     * ```
+     *
+     * @param options - Options for destroying the instance
+     * @param options.skipHooks - If true, skips applying model hooks during the destroy operation. Defaults to false
+     * @param options.cascade - If false, skips destroying associations marked `dependent: 'destroy'`. Defaults to true
+     * @param options.bypassAllDefaultScopes - If true, bypasses all default scopes when cascade destroying. Defaults to false
+     * @param options.defaultScopesToBypass - An array of default scope names to bypass when cascade destroying. Defaults to an empty array
+     * @returns The instance that was destroyed
+     */
+    async destroy(options = {}) {
+        return await destroyDream(this, null, destroyOptions(options));
+    }
+    /**
+     * Deletes the record represented by this instance
+     * from the database, calling any destroy
+     * hooks on this model.
+     *
+     * If the record being destroyed is using
+     * a SoftDelete decorator, the soft delete
+     * will be bypassed, causing the record
+     * to be permanently removed from the database.
+     *
+     * ```ts
+     * const user = await User.last()
+     * await user.reallyDestroy()
+     * ```
+     *
+     * @param options - Options for destroying the instance
+     * @param options.skipHooks - If true, skips applying model hooks during the destroy operation. Defaults to false
+     * @param options.cascade - If false, skips destroying associations marked `dependent: 'destroy'`. Defaults to true
+     * @param options.bypassAllDefaultScopes - If true, bypasses all default scopes when cascade destroying. Defaults to false
+     * @param options.defaultScopesToBypass - An array of default scope names to bypass when cascade destroying. Defaults to an empty array
+     * @returns The instance that was destroyed
+     */
+    async reallyDestroy(options = {}) {
+        return await destroyDream(this, null, reallyDestroyOptions(options));
+    }
+    /**
+     * Undestroys a SoftDelete model, unsetting
+     * the `deletedAt` field in the database.
+     *
+     * If the model is not a SoftDelete model,
+     * this will raise an exception.
+     *
+     * ```ts
+     * const user = await User.removeAllDefaultScopes().last()
+     * await user.undestroy()
+     * ```
+     *
+     * @param options - Options for undestroying the instance
+     * @param options.skipHooks - If true, skips applying model hooks during the undestroy operation. Defaults to false
+     * @param options.cascade - If false, skips undestroying associations marked `dependent: 'destroy'`. Defaults to true
+     * @param options.bypassAllDefaultScopes - If true, bypasses all default scopes when cascade undestroying. Defaults to false
+     * @param options.defaultScopesToBypass - An array of default scope names to bypass when cascade undestroying (soft delete is always bypassed). Defaults to an empty array
+     * @returns The undestroyed record
+     */
+    async undestroy(options = {}) {
+        const dreamClass = this.constructor;
+        if (!dreamClass['softDelete'])
+            throw new CannotCallUndestroyOnANonSoftDeleteModel(dreamClass);
+        await undestroyDream(this, null, undestroyOptions(options));
+        return this;
+    }
+    /**
+     * Returns true if the argument is the same Dream class
+     * with the same primary key value.
+     *
+     * NOTE: This does not compare attribute values other than
+     * the primary key.
+     *
+     * @returns A boolean
+     */
+    equals(other) {
+        return other?.constructor === this.constructor && other.primaryKeyValue === this.primaryKeyValue;
+    }
+    /**
+     * @internal
+     *
+     * Used for changes API
+     */
+    freezeAttributes() {
+        this.frozenAttributes = { ...this.getAttributes() };
+    }
+    /**
+     * Deep clones the model and its non-association attributes.
+     * Unsets primaryKey, created and updated fields.
+     *
+     * @returns Non-persisted, cloned Dream instance
+     */
+    dup() {
+        const clone = this.clone({ includeAssociations: false });
+        clone.isPersisted = false;
+        clone[clone.primaryKey] = undefined;
+        clone[clone.createdAtField] = undefined;
+        clone[clone.updatedAtField] = undefined;
+        const dreamClass = this.constructor;
+        dreamClass.sortableFields.forEach(data => {
+            ;
+            clone[data.positionField] = undefined;
+        });
+        clone.freezeAttributes();
+        clone.originalAttributes = { ...clone.getAttributes() };
+        clone.attributesFromBeforeLastSave = { ...clone.getAttributes() };
+        return clone;
+    }
+    /**
+     * Deep clones the model and it's attributes, but maintains references to
+     * loaded associations
+     */
+    clone({ includeAssociations = true } = {}) {
+        const self = this;
+        const clone = self.constructor.new({});
+        const associationDataKeys = Object.values(this.constructor.associationMetadataMap()).map(association => associationToGetterSetterProp(association));
+        Object.keys(this).forEach(property => {
+            if (!associationDataKeys.includes(property))
+                clone[property] = cloneDeepSafe(self[property]);
+        });
+        if (includeAssociations) {
+            associationDataKeys.forEach(associationDataKey => (clone[associationDataKey] = self[associationDataKey]));
+        }
+        return clone;
+    }
+    /**
+     * Creates an association for an instance. Automatically
+     * handles setting foreign key and, in the case of polymorphism,
+     * foreign key type.
+     *
+     * ```ts
+     * await user.createAssociation('posts', { body: 'hello world' })
+     * ```
+     *
+     * @param associationName - the name of the association to create
+     * @param attributes - the attributes with which to create the associated model
+     * @returns The created association
+     */
+    async createAssociation(associationName, attributes = {}) {
+        return createAssociation(this, null, associationName, attributes);
+    }
+    /**
+     * Destroys models associated with the current instance,
+     * deleting their corresponding records within the database.
+     *
+     * ```ts
+     * await user.destroyAssociation('posts', { body: 'hello world' })
+     * ```
+     *
+     * @param associationName - The name of the association to destroy
+     * @param options - Options for destroying the association
+     * @param options.on - Optional where statement to apply to query before destroying
+     * @param options.skipHooks - If true, skips applying model hooks during the destroy operation. Defaults to false
+     * @param options.cascade - If false, skips destroying associations marked `dependent: 'destroy'`. Defaults to true
+     * @param options.bypassAllDefaultScopes - If true, bypasses all default scopes when destroying the association. Defaults to false
+     * @param options.defaultScopesToBypass - An array of default scope names to bypass when destroying the association. Defaults to an empty array
+     * @returns The number of records deleted
+     */
+    async destroyAssociation(associationName, options) {
+        return await destroyAssociation(this, null, associationName, {
+            ...destroyOptions(options),
+            joinOnStatements: {
+                on: options?.on,
+                notOn: options?.notOn,
+                onAny: options?.onAny,
+            },
+        });
+    }
+    /**
+     * Destroys models associated with the current instance,
+     * deleting their corresponding records within the database.
+     *
+     * If the record, or else any of its associations
+     * which are marked cascade: "destroy", are using
+     * the SoftDelete decorator, it will be bypassed,
+     * causing those records to be deleted from the database.
+     *
+     * ```ts
+     * await user.reallyDestroyAssociation('posts', { body: 'hello world' })
+     * ```
+     *
+     * @param associationName - The name of the association to destroy
+     * @param options - Options for destroying the association
+     * @param options.on - Optional where statement to apply to query before destroying
+     * @param options.skipHooks - If true, skips applying model hooks during the destroy operation. Defaults to false
+     * @param options.cascade - If true, cascades the destroy operation to associations marked with `dependent: 'destroy'`. Defaults to true
+     * @param options.bypassAllDefaultScopes - If true, bypasses all default scopes when destroying the association. Defaults to false
+     * @param options.defaultScopesToBypass - An array of default scope names to bypass when destroying the association. Defaults to an empty array
+     * @returns The number of records deleted
+     */
+    async reallyDestroyAssociation(associationName, options) {
+        return await destroyAssociation(this, null, associationName, {
+            ...reallyDestroyOptions(options),
+            joinOnStatements: {
+                on: options?.on,
+                notOn: options?.notOn,
+                onAny: options?.onAny,
+            },
+        });
+    }
+    /**
+     * Undestroys a SoftDelete association.
+     * If cascade: true is passed, any child
+     * associations that have been soft deleted
+     * will also be undeleted.
+     *
+     * ```ts
+     * await user.undestroyAssociation('posts', { body: 'hello world' })
+     * ```
+     *
+     * @param associationName - The name of the association to undestroy
+     * @param options - Options for undestroying the association
+     * @param options.on - Optional where statement to apply to query before undestroying
+     * @param options.skipHooks - If true, skips applying model hooks during the undestroy operation. Defaults to false
+     * @param options.cascade - If false, skips undestroying associations marked `dependent: 'destroy'`. Defaults to true
+     * @param options.bypassAllDefaultScopes - If true, bypasses all default scopes when undestroying the association. Defaults to false
+     * @param options.defaultScopesToBypass - An array of default scope names to bypass when undestroying the association. Defaults to an empty array
+     * @returns The number of records undestroyed
+     */
+    async undestroyAssociation(associationName, options) {
+        return await undestroyAssociation(this, null, associationName, {
+            ...undestroyOptions(options),
+            joinOnStatements: {
+                on: options?.on,
+                notOn: options?.notOn,
+                onAny: options?.onAny,
+            },
+        });
+    }
+    /**
+     * Returns a Query instance for the specified
+     * association on the current instance.
+     *
+     * ```ts
+     * await user.associationQuery('posts').all()
+     * // only user posts returned
+     * ```
+     *
+     * @returns A Query scoped to the specified association on the current instance
+     *
+     */
+    associationQuery(associationName, joinOnStatements) {
+        return associationQuery(this, null, associationName, {
+            joinOnStatements: joinOnStatements,
+            bypassAllDefaultScopes: DEFAULT_BYPASS_ALL_DEFAULT_SCOPES,
+            defaultScopesToBypass: DEFAULT_DEFAULT_SCOPES_TO_BYPASS,
+        });
+    }
+    /**
+     * Updates all records matching the association with
+     * the provided attributes. If a where statement is passed,
+     * The on statement will be applied to the query
+     * before updating.
+     *
+     * ```ts
+     * await user.createAssociation('posts', { body: 'hello world' })
+     * await user.createAssociation('posts', { body: 'howyadoin' })
+     * await user.updateAssociation('posts', { body: 'goodbye world' }, { on: { body: 'hello world' }})
+     * // 1
+     * ```
+     *
+     * @param associationName - The name of the association to update
+     * @param attributes - The attributes to update on the association
+     * @param options - Options for updating the association
+     * @param options.on - Optional on statement to apply to query before updating
+     * @param options.skipHooks - If true, skips applying model hooks during the update operation. Defaults to false
+     * @param options.bypassAllDefaultScopes - If true, bypasses all default scopes when updating the association. Defaults to false
+     * @param options.defaultScopesToBypass - An array of default scope names to bypass when updating the association. Defaults to an empty array
+     * @returns The number of updated records
+     */
+    async updateAssociation(associationName, attributes, updateAssociationOptions) {
+        return associationUpdateQuery(this, null, associationName, {
+            joinOnStatements: {
+                on: updateAssociationOptions?.on,
+                notOn: updateAssociationOptions?.notOn,
+                onAny: updateAssociationOptions?.onAny,
+            },
+            bypassAllDefaultScopes: updateAssociationOptions?.bypassAllDefaultScopes ?? DEFAULT_BYPASS_ALL_DEFAULT_SCOPES,
+            defaultScopesToBypass: updateAssociationOptions?.defaultScopesToBypass ?? DEFAULT_DEFAULT_SCOPES_TO_BYPASS,
+        }).update(attributes, { skipHooks: updateAssociationOptions?.skipHooks ?? DEFAULT_SKIP_HOOKS });
+    }
+    ///////////////////
+    // end: updateAssociation
+    ///////////////////
+    /**
+     * Sends data through for use as passthrough data
+     * for the associations that require it.
+     *
+     * ```ts
+     * class Post {
+     *   @Deco.HasMany('LocalizedText')
+     *   public localizedTexts: LocalizedText[]
+     *
+     *   @Deco.HasOne('LocalizedText', {
+     *     where: { locale: DreamConst.passthrough },
+     *   })
+     *   public currentLocalizedText: LocalizedText
+     * }
+     *
+     * await User.passthrough({ locale: 'es-ES' })
+     *   .preload('posts', 'currentLocalizedText')
+     *   .first()
+     * ```
+     *
+     * @param passthroughWhereStatement - where statement used for associations that require passthrough data
+     * @returns A cloned Query with the passthrough data
+     */
+    passthrough(passthroughWhereStatement) {
+        return new LoadBuilder(this).passthrough(passthroughWhereStatement);
+    }
+    /**
+     * Loads the requested associations upon execution
+     *
+     * NOTE: {@link #preload} is often a preferrable way of achieving the
+     * same goal.
+     *
+     * ```ts
+     * await user
+     *  .load('posts', { body: ops.ilike('%hello world%') }, 'comments', 'replies')
+     *  .load('images')
+     *  .execute()
+     *
+     * user.posts[0].comments[0].replies[0]
+     * // Reply{}
+     *
+     * user.images[0]
+     * // Image{}
+     * ```
+     *
+     * @param args - A list of associations (and optional where clauses) to load
+     * @returns A chainable LoadBuilder instance
+     */
+    load(...args) {
+        return new LoadBuilder(this).load(...args);
+    }
+    /**
+     * Load each specified association using a single SQL query.
+     * See {@link #load} for loading in separate queries.
+     *
+     * Note: since leftJoinPreload loads via single query, it has
+     * some downsides and that may be avoided using {@link #load}:
+     * 1. `limit` and `offset` will be automatically removed
+     * 2. `through` associations will bring additional namespaces into the query that can conflict with through associations from other associations, creating an invalid query
+     * 3. each nested association will result in an additional record which duplicates data from the outer record. E.g., given `.leftJoinPreload('a', 'b', 'c')`, if each `a` has 10 `b` and each `b` has 10 `c`, then for one `a`, 100 records will be returned, each of which has all of the columns of `a`. `.load('a', 'b', 'c')` would perform three separate SQL queries, but the data for a single `a` would only be returned once.
+     * 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
+     * Loads the requested associations upon execution
+     *
+     * NOTE: {@link #leftJoinPreload} is often a preferrable way of achieving the
+     * same goal.
+     *
+     * ```ts
+     * await user
+     *  .leftJoinLoad('posts', { body: ops.ilike('%hello world%') }, 'comments', 'replies')
+     *  .leftJoinLoad('images')
+     *  .execute()
+     *
+     * user.posts[0].comments[0].replies[0]
+     * // Reply{}
+     *
+     * user.images[0]
+     * // Image{}
+     * ```
+     *
+     * @param args - A list of associations (and optional where clauses) to load
+     * @returns A chainable LeftJoinLoadBuilder instance
+     */
+    leftJoinLoad(...args) {
+        return new LeftJoinLoadBuilder(this).leftJoinLoad(...args);
+    }
+    /**
+     * Returns true if the association specified has
+     * been loaded on this instance
+     *
+     * Since accessing associations that haven't been
+     * loaded/preloaded will raise an exception, `loaded`
+     * is useful for conditionally loading from the database
+     * in contexts where an association may not yet be loaded.
+     *
+     * ```ts
+     * user.loaded('posts')
+     * // false
+     *
+     * user = await user.load('posts').execute()
+     * user.loaded('posts')
+     * // true
+     * ```
+     *
+     * @param associationName - the association name you wish to check the loading of
+     * @returns A boolean
+     */
+    loaded(associationName) {
+        try {
+            ;
+            this[associationName];
+            return true;
+        }
+        catch (error) {
+            if (error.constructor !== NonLoadedAssociation)
+                throw error;
+            return false;
+        }
+    }
+    /**
+     * Reloads an instance, refreshing all it's attribute values
+     * to those in the database.
+     *
+     * NOTE: this does not refresh associations
+     *
+     * ```ts
+     * await user.reload()
+     * ```
+     *
+     * @returns void
+     */
+    async reload() {
+        await reload(this);
+    }
+    /**
+     * Serializes an instance. You can specify a serializer key,
+     * or else the default will be used
+     *
+     * ```ts
+     * // uses the default serializer provided in the model's `serializers` getter
+     * await user.serialize()
+     *
+     * // uses the summary serializer provided in the model's `serializers` getter
+     * await user.serialize({ serializerKey: 'summary' })
+     * ```
+     *
+     * @param args.casing - Which casing to use when serializing (camel or snake, default camel)
+     * @param args.serializerKey - The key to use when referencing the object returned by the `serializers` getter on the given model instance (defaults to "default")
+     * @returns A serialized representation of the model
+     */
+    serialize({ casing = null, serializerKey } = {}) {
+        const serializerClass = inferSerializerFromDreamOrViewModel(this, serializerKey?.toString());
+        if (!serializerClass)
+            throw new MissingSerializer(this.constructor);
+        const serializer = new serializerClass(this);
+        if (casing)
+            serializer.casing(casing);
+        return serializer.render();
+    }
+    /**
+     * Takes the attributes passed in and sets their values,
+     * leveraging any custom setters defined for these attributes.
+     *
+     * NOTE:
+     * To bypass custom-defined setters, use `#setAttributes` instead.
+     *
+     * ```ts
+     *  const user = new User()
+     *  user.assignAttributes({ email: 'my@email', password: 'my password' })
+     * ```
+     */
+    assignAttributes(attributes) {
+        return this._setAttributes(attributes, { bypassUserDefinedSetters: false });
+    }
+    /**
+     * Takes the attributes passed in and sets their values internally,
+     * bypassing any custom setters defined for these attributes.
+     *
+     * NOTE:
+     * To leverage custom-defined setters, use `#assignAttributes` instead.
+     *
+     * ```ts
+     *  const user = new User()
+     *  user.setAttributes({ email: 'my@email', password: 'my password' })
+     * ```
+     */
+    setAttributes(attributes) {
+        return this._setAttributes(attributes, { bypassUserDefinedSetters: true });
+    }
+    _setAttributes(attributes, additionalOpts = {}) {
+        const dreamClass = this.constructor;
+        const marshalledOpts = dreamClass.extractAttributesFromUpdateableProperties(attributes, this, additionalOpts);
+        return marshalledOpts;
+    }
+    /**
+     * Saves the state of the current instance to the
+     * database. For new instances (that have not been
+     * persisted), `save` and `create` model hooks will be called.
+     * For instances that have already been persisted,
+     * the `save` and `update` model hooks will be called.
+     *
+     * Upon saving a new instance, the primary key, timestamp
+     * fields (if defined), and `type` (if STI) will be set on
+     * the model.
+     *
+     * Upon updating an instance, the update timestamp (if defined)
+     * will be updated on the model.
+     *
+     * ```ts
+     * const user = User.new({ email: 'how@yadoin' })
+     * user.name = 'fred'
+     * await user.save()
+     *
+     * user.email // 'how@yadoin'
+     * user.name // 'fred'
+     * user.id // 1
+     * user.createdAt // A DateTime object
+     * user.updatedAt // A DateTime object
+     *
+     * // If User were STI:
+     * user.type // 'User'
+     * ```
+     *
+     * @param opts.skipHooks - if true, will skip applying model hooks. Defaults to false
+     * @returns void
+     */
+    async save({ skipHooks } = {}) {
+        await saveDream(this, null, { skipHooks });
+    }
+    /**
+     * Applies transaction to a new Query instance
+     *
+     * ```ts
+     * await ApplicationModel.transaction(async txn => {
+     *   const user = await User.txn(txn).create({ email: 'how@yadoin' })
+     *   await Pet.txn(txn).create({ user })
+     * })
+     * ```
+     *
+     * @param txn - A DreamTransaction instance (collected by calling `ApplicationModel.transaction`)
+     * @returns A Query scoped to this model with the transaction applied
+     */
+    txn(txn) {
+        return new DreamInstanceTransactionBuilder(this, txn);
+    }
+    /**
+     * Applies all attribute changes passed to the Dream
+     * instance, leveraging any custom-defined setters,
+     * and then saves the Dream instance. Can be called
+     * on an unpersisted Dream instance.
+     *
+     * See {@link Dream.save | save} for details on
+     * the side effects of saving.
+     *
+     * NOTE:
+     * To bypass custom-defined setters, use {@link Dream.updateAttributes | updateAttributes} instead.
+     *
+     * ```ts
+     *  const user = await User.create({ email: 'saly@gmail.com' })
+     *  await user.update({ email: 'sally@gmail.com' })
+     * ```
+     *
+     * @param attributes - the attributes to set on the model
+     * @param opts.skipHooks - if true, will skip applying model hooks. Defaults to false
+     * @returns void
+     */
+    async update(attributes, { skipHooks } = {}) {
+        // use #assignAttributes to leverage any custom-defined setters
+        this.assignAttributes(attributes);
+        await this.save({ skipHooks });
+    }
+    /**
+     * Applies all attribute changes passed to the dream,
+     * bypassing any custom-defined setters,
+     * and then saves the dream instance. Does not bypass
+     * model hooks.
+     *
+     * See {@link Dream.save | save} for details on
+     * the side effects of saving.
+     *
+     * NOTE:
+     * To update the values without bypassing any custom-defined
+     * setters, use {@link Dream.update | update} instead.
+     *
+     * ```ts
+     * const user = await User.create({ email: 'saly@gmail.com' })
+     * await user.updateAttributes({ email: 'sally@gmail.com' })
+     * ```
+     *
+     * @param attributes - The attributes to update on this instance
+     * @param opts.skipHooks - if true, will skip applying model hooks. Defaults to false
+     * @returns - void
+     */
+    async updateAttributes(attributes, { skipHooks } = {}) {
+        // use #setAttributes to bypass any custom-defined setters
+        this.setAttributes(attributes);
+        await this.save({ skipHooks });
+    }
+    /**
+     * Flags a dream model so that it does not
+     * actually destroy when in a destroy phase.
+     * This is usually used for a soft-delete
+     * pattern
+     *
+     * ```ts
+     * class User extends ApplicationModel {
+     *   @Deco.BeforeDestroy()
+     *   public softDelete() {
+     *     await this.update({ deletedAt: DateTime.now() })
+     *     this.preventDeletion()
+     *   }
+     * }
+     * ```
+     *
+     * @returns void
+     */
+    preventDeletion() {
+        this._preventDeletion = true;
+    }
+    /**
+     * Flags a dream model so that it allows
+     * deletion once again.
+     *
+     * Undoes {@link Dream.(preventDeletion:instance) | preventDeletion}
+     *
+     * ```ts
+     * class User extends ApplicationModel {
+     *   @Deco.BeforeDestroy()
+     *   public async softDelete() {
+     *     await this.update({ deletedAt: DateTime.now() })
+     *     this.preventDeletion()
+     *   }
+     *
+     *   @Deco.BeforeDestroy()
+     *   public async undoSoftDelete() {
+     *     await this.update({ deletedAt: null })
+     *     this.unpreventDeletion()
+     *   }
+     * }
+     * ```
+     *
+     * @returns void
+     */
+    unpreventDeletion() {
+        this._preventDeletion = false;
+        return this;
+    }
+    _preventDeletion = false;
+}