@rvoh/dream 0.40.4 → 0.40.6

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

@@ -1,6 +1,6 @@
 export default class LoadBuilder {
-    dream;
     dreamTransaction;
+    dream;
     query;
     /**
      * An intermediate class on the way to executing a load
@@ -12,7 +12,8 @@ export default class LoadBuilder {
      * await user.load('settings').execute()
      * ```
      */
-    constructor(dream, txn) {
+    constructor(dream, dreamTransaction) {
+        this.dreamTransaction = dreamTransaction;
         this.dream = dream['clone']();
         // Load queries start from the table corresponding to an instance
         // of a Dream. However, the Dream may have default scopes that would
@@ -21,7 +22,6 @@ export default class LoadBuilder {
         // to other associations (thus the use of `removeAllDefaultScopesExceptOnAssociations`
         // instead of `removeAllDefaultScopes`).
         this.query = this.dream.query()['removeAllDefaultScopesExceptOnAssociations']();
-        this.dreamTransaction = txn;
     }
     passthrough(passthroughWhereStatement) {
         this.query = this.query.passthrough(passthroughWhereStatement);

package/dist/esm/src/dream/internal/associations/createAssociation.js

@@ -30,12 +30,7 @@ export default async function createAssociation(dream, txn = null, associationNa
             if (hasAssociation.polymorphic) {
                 modifiedOpts[hasAssociation.foreignKeyTypeField()] = dream['stiBaseClassOrOwnClassName'];
             }
-            if (txn) {
-                hasresult = await associationClass.txn(txn).create(modifiedOpts);
-            }
-            else {
-                hasresult = await associationClass.create(modifiedOpts);
-            }
+            hasresult = await associationClass.txn(txn).create(modifiedOpts);
             return hasresult;
         case 'BelongsTo':
             belongstoFn = async (txn) => {

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

@@ -37,7 +37,7 @@ async function destroyDreamWithTransaction(dream, txn, options) {
     }
     await maybeDestroyDream(dream, txn, reallyDestroy);
     if (!skipHooks) {
-        await runHooksFor('afterDestroy', dream, true, null, txn || undefined);
+        await runHooksFor('afterDestroy', dream, true, null, txn);
         await runHooksFor('afterDestroyCommit', dream, true, null, txn);
     }
     if (shouldSoftDelete(dream, reallyDestroy)) {

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

@@ -0,0 +1,13 @@
+export default async function findOrCreateBy(dreamClass, txn = null, attributes, extraOpts = {}) {
+    const existingRecord = await dreamClass
+        .txn(txn)
+        .findBy(dreamClass['extractAttributesFromUpdateableProperties'](attributes));
+    if (existingRecord)
+        return existingRecord;
+    const dreamModel = dreamClass.new({
+        ...attributes,
+        ...(extraOpts?.createWith || {}),
+    });
+    await dreamModel.txn(txn).save();
+    return dreamModel;
+}

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

@@ -35,7 +35,7 @@ export default async function runHooksFor(key, dream, alreadyPersisted, beforeSa
                         if (txn)
                             txn.addCommitHook(hook, dream);
                         else
-                            await runHook(hook, dream);
+                            await runHook(hook, dream, null);
                     }
                     break;
                 case 'afterSave':
@@ -50,7 +50,7 @@ export default async function runHooksFor(key, dream, alreadyPersisted, beforeSa
                         if (txn)
                             txn.addCommitHook(hook, dream);
                         else
-                            await runHook(hook, dream);
+                            await runHook(hook, dream, null);
                     }
                     break;
                 case 'afterUpdate':
@@ -63,7 +63,7 @@ export default async function runHooksFor(key, dream, alreadyPersisted, beforeSa
                         if (txn)
                             txn.addCommitHook(hook, dream);
                         else
-                            await runHook(hook, dream);
+                            await runHook(hook, dream, null);
                     }
                     break;
                 default:
@@ -79,7 +79,7 @@ export default async function runHooksFor(key, dream, alreadyPersisted, beforeSa
                     if (txn)
                         txn.addCommitHook(hook, dream);
                     else
-                        await runHook(hook, dream);
+                        await runHook(hook, dream, null);
                     break;
                 default:
                     await runHook(hook, dream, txn);

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

@@ -6,7 +6,7 @@ import sqlAttributes from '../../helpers/sqlAttributes.js';
 import executeDatabaseQuery from './executeDatabaseQuery.js';
 import runHooksFor from './runHooksFor.js';
 export default async function saveDream(dream, txn = null, { skipHooks = false } = {}) {
-    const db = txn?.kyselyTransaction || _db('primary');
+    const db = txn?.kyselyTransaction ?? _db('primary');
     const alreadyPersisted = dream.isPersisted;
     if (!skipHooks) {
         if (alreadyPersisted)

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

@@ -0,0 +1,15 @@
+import saveDream from './saveDream.js';
+export default async function updateOrCreateBy(dreamClass, txn = null, attributes, extraOpts = {}) {
+    const existingRecord = await dreamClass
+        .txn(txn)
+        .findBy(dreamClass['extractAttributesFromUpdateableProperties'](attributes));
+    const { with: attrs, skipHooks } = extraOpts;
+    if (existingRecord) {
+        existingRecord.assignAttributes(attrs ?? {});
+        return await saveDream(existingRecord, txn, skipHooks ? { skipHooks } : undefined);
+    }
+    return await dreamClass.txn(txn).create({
+        ...attributes,
+        ...(extraOpts?.with || {}),
+    }, skipHooks ? { skipHooks } : undefined);
+}

package/dist/esm/src/errors/CreateOrUpdateByFailedToCreateAndUpdate.js

@@ -0,0 +1,15 @@
+export default class CreateOrUpdateByFailedToCreateAndUpdate extends Error {
+    dreamClass;
+    constructor(dreamClass) {
+        super();
+        this.dreamClass = dreamClass;
+    }
+    get message() {
+        return `
+Failed to create instance of ${this.dreamClass.sanitizedName} and no matching model exists to update.
+
+The likely cause is that one of the \`with\` fields violates
+a uniqueness constraint.
+    `;
+    }
+}

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

@@ -11,7 +11,7 @@ import LoadBuilder from './dream/LoadBuilder.js';
 import Query from './dream/Query.js';
 import { AssociationStatementsMap, PassthroughOnClause, WhereStatement } from './types/associations/shared.js';
 import { AssociationTableNames, DbConnectionType } from './types/db.js';
-import { AllDefaultScopeNames, AssociationNameToDream, AttributeKeys, DefaultOrNamedScopeName, DreamAssociationNames, DreamAssociationNamesWithoutRequiredOnClauses, DreamAttributes, DreamColumnNames, DreamParamSafeColumnNames, DreamSerializeOptions, IdType, JoinAndStatements, NextPreloadArgumentType, OrderDir, PassthroughColumnNames, PluckEachArgs, PrimaryKeyForFind, TableColumnNames, UpdateableAssociationProperties, UpdateableProperties, UpdateablePropertiesForClass } from './types/dream.js';
+import { AllDefaultScopeNames, AssociationNameToDream, AttributeKeys, CreateOrFindByExtraOpts, DefaultOrNamedScopeName, DreamAssociationNames, DreamAssociationNamesWithoutRequiredOnClauses, DreamAttributes, DreamColumnNames, DreamParamSafeColumnNames, DreamSerializeOptions, IdType, JoinAndStatements, NextPreloadArgumentType, OrderDir, PassthroughColumnNames, PluckEachArgs, PrimaryKeyForFind, TableColumnNames, UpdateableAssociationProperties, UpdateableProperties, UpdateablePropertiesForClass, UpdateOrCreateByExtraOpts } from './types/dream.js';
 import { HookStatement, HookStatementMap } from './types/lifecycle.js';
 import { BaseModelColumnTypes, DefaultQueryTypeOptions, FindEachOpts, QueryWithJoinedAssociationsType, QueryWithJoinedAssociationsTypeAndNoPreload } from './types/query.js';
 import { ValidationStatement, ValidationType } from './types/validation.js';
@@ -487,9 +487,12 @@ export default class Dream {
      * ```
      *
      * @param attributes - attributes or belongs to associations you wish to set on this model before persisting
+     * @param opts.skipHooks - if true, will skip applying model hooks. Defaults to false
      * @returns A newly persisted dream instance
      */
-    static create<T extends typeof Dream>(this: T, attributes?: UpdateablePropertiesForClass<T>): Promise<InstanceType<T>>;
+    static create<T extends typeof Dream>(this: T, attributes?: UpdateablePropertiesForClass<T>, { skipHooks }?: {
+        skipHooks?: boolean;
+    }): Promise<InstanceType<T>>;
     /**
      * Attempt to create the model. If creation fails
      * due to uniqueness constraint, then find the existing
@@ -509,7 +512,40 @@ export default class Dream {
      * @param extraOpts.createWith - additional attributes to persist when creating, but not used for finding
      * @returns A dream instance
      */
-    static createOrFindBy<T extends typeof Dream>(this: T, attributes: UpdateablePropertiesForClass<T>, extraOpts?: CreateOrFindByExtraOps<T>): Promise<InstanceType<T>>;
+    static createOrFindBy<T extends typeof Dream>(this: T, attributes: UpdateablePropertiesForClass<T>, extraOpts?: CreateOrFindByExtraOpts<T>): Promise<InstanceType<T>>;
+    /**
+     * Attempt to update the model with the given attributes.
+     * If no record is found, then a new record is created.
+     * All lifecycle hooks are run for whichever action is taken.
+     *
+     * ```ts
+     * const user = await User.updateOrCreateBy({ email }, { with: { name: 'Alice' })
+     * ```
+     *
+     * @param attributes - The base attributes for finding which record to update, also used when creating
+     * @param extraOpts.with - additional attributes to persist when updating and creating, but not used for finding
+     * @param extraOpts.skipHooks - if true, will skip applying model hooks. Defaults to false
+     * @returns A dream instance
+     */
+    static updateOrCreateBy<T extends typeof Dream>(this: T, attributes: UpdateablePropertiesForClass<T>, extraOpts?: UpdateOrCreateByExtraOpts<T>): Promise<InstanceType<T>>;
+    /**
+     * Attempt to create the model with the given attributes.
+     * If creation fails due to uniqueness constraint, then find and update
+     * the existing model. All lifecycle hooks are run for whichever
+     * action is taken.
+     *
+     * 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
+     *
+     * @param attributes - The base attributes for finding which record to update, also used when creating
+     * @param extraOpts.with - additional attributes to persist when updating and creating, but not used for finding
+     * @param extraOpts.skipHooks - if true, will skip applying model hooks. Defaults to false
+     * @returns A dream instance
+     */
+    static createOrUpdateBy<T extends typeof Dream>(this: T, attributes: UpdateablePropertiesForClass<T>, extraOpts?: UpdateOrCreateByExtraOpts<T>): Promise<InstanceType<T>>;
     /**
      * Returns a new query instance with the distinct query applied.
      * If no columnName is provided, then distinct will apply to the
@@ -649,7 +685,7 @@ export default class Dream {
      * @param extraOpts.createWith - additional attributes to persist when creating, but not used for finding
      * @returns A dream instance
      */
-    static findOrCreateBy<T extends typeof Dream>(this: T, attributes: UpdateablePropertiesForClass<T>, extraOpts?: CreateOrFindByExtraOps<T>): Promise<InstanceType<T>>;
+    static findOrCreateBy<T extends typeof Dream>(this: T, attributes: UpdateablePropertiesForClass<T>, extraOpts?: CreateOrFindByExtraOpts<T>): Promise<InstanceType<T>>;
     /**
      * Returns true if a record exists for the given
      * model class
@@ -1029,7 +1065,7 @@ export default class Dream {
      * @param txn - A DreamTransaction instance (usually collected by calling `ApplicationModel.transaction`)
      * @returns A Query scoped to this model with the transaction applied
      */
-    static txn<T extends typeof Dream, I extends InstanceType<T>>(this: T, txn: DreamTransaction<I>): DreamClassTransactionBuilder<I>;
+    static txn<T extends typeof Dream, I extends InstanceType<T>>(this: T, txn: DreamTransaction<I> | null): DreamClassTransactionBuilder<T, I>;
     /**
      * Builds a new DreamTransaction instance, provides
      * the instance to the provided callback.
@@ -2164,7 +2200,7 @@ export default class Dream {
      * @param txn - A DreamTransaction instance (collected by calling `ApplicationModel.transaction`)
      * @returns A Query scoped to this model with the transaction applied
      */
-    txn<I extends Dream>(this: I, txn: DreamTransaction<Dream>): DreamInstanceTransactionBuilder<I>;
+    txn<I extends Dream>(this: I, txn: DreamTransaction<Dream> | null): DreamInstanceTransactionBuilder<I>;
     /**
      * Applies all attribute changes passed to the Dream
      * instance, leveraging any custom-defined setters,
@@ -2260,6 +2296,3 @@ export default class Dream {
     unpreventDeletion(): this;
     private _preventDeletion;
 }
-export interface CreateOrFindByExtraOps<T extends typeof Dream> {
-    createWith?: WhereStatement<InstanceType<T>['DB'], InstanceType<T>['schema'], InstanceType<T>['table']> | UpdateablePropertiesForClass<T>;
-}

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

@@ -1,22 +1,23 @@
-import { SelectArg, SelectExpression, Updateable } from 'kysely';
+import { SelectArg, SelectExpression } from 'kysely';
 import Dream from '../Dream.js';
 import { PassthroughOnClause, WhereStatement } from '../types/associations/shared.js';
 import { AssociationTableNames } from '../types/db.js';
-import { DefaultScopeName, DreamColumnNames, OrderDir, PassthroughColumnNames, PluckEachArgs, PrimaryKeyForFind, TableColumnNames, UpdateableProperties } from '../types/dream.js';
+import { CreateOrFindByExtraOpts, DefaultScopeName, DreamColumnNames, OrderDir, PassthroughColumnNames, PluckEachArgs, PrimaryKeyForFind, TableColumnNames, UpdateableProperties, UpdateablePropertiesForClass, UpdateOrCreateByExtraOpts } from '../types/dream.js';
 import { BaseModelColumnTypes, FindEachOpts, QueryWithJoinedAssociationsType, QueryWithJoinedAssociationsTypeAndNoPreload } from '../types/query.js';
 import { JoinedAssociation, JoinedAssociationsTypeFromAssociations, VariadicJoinsArgs, VariadicLeftJoinLoadArgs, VariadicLoadArgs } from '../types/variadic.js';
 import DreamTransaction from './DreamTransaction.js';
 import Query from './Query.js';
-export default class DreamClassTransactionBuilder<DreamInstance extends Dream> {
+export default class DreamClassTransactionBuilder<DreamClass extends typeof Dream, DreamInstance extends Dream> {
+    private dreamClass;
+    private dreamTransaction;
     dreamInstance: DreamInstance;
-    dreamTransaction: DreamTransaction<Dream>;
     /**
      * Constructs a new DreamClassTransactionBuilder.
      *
      * @param dreamInstance - The Dream instance to build the transaction for
      * @param txn - The DreamTransaction instance
      */
-    constructor(dreamInstance: DreamInstance, dreamTransaction: DreamTransaction<Dream>);
+    constructor(dreamClass: DreamClass, dreamTransaction: DreamTransaction<Dream> | null);
     /**
      * Retrieves an array containing all records corresponding to
      * this model. Be careful using this, since it will attempt to
@@ -33,7 +34,7 @@ export default class DreamClassTransactionBuilder<DreamInstance extends Dream> {
      * @param options.columns - Columns to select
      * @returns An array of dreams
      */
-    all<I extends DreamClassTransactionBuilder<DreamInstance>>(this: I, options?: {
+    all<I extends DreamClassTransactionBuilder<DreamClass, DreamInstance>>(this: I, options?: {
         columns?: DreamColumnNames<DreamInstance>[];
     }): Promise<DreamInstance[]>;
     /**
@@ -42,7 +43,7 @@ export default class DreamClassTransactionBuilder<DreamInstance extends Dream> {
      *
      * @returns The number of records corresponding to this model
      */
-    count<I extends DreamClassTransactionBuilder<DreamInstance>>(this: I): Promise<number>;
+    count<I extends DreamClassTransactionBuilder<DreamClass, DreamInstance>>(this: I): Promise<number>;
     /**
      * Returns a new Query instance, specifying a limit
      *
@@ -56,7 +57,7 @@ export default class DreamClassTransactionBuilder<DreamInstance extends Dream> {
      * @param limit - The number of records to limit the query to
      * @returns A Query for this model with the limit clause applied
      */
-    limit<I extends DreamClassTransactionBuilder<DreamInstance>>(this: I, limit: number | null): Query<DreamInstance>;
+    limit<I extends DreamClassTransactionBuilder<DreamClass, DreamInstance>>(this: I, limit: number | null): Query<DreamInstance>;
     /**
      * Returns a new Query instance, specifying an offset
      *
@@ -70,7 +71,7 @@ export default class DreamClassTransactionBuilder<DreamInstance extends Dream> {
      * @param offset - The number of records to offset the query by
      * @returns A Query for this model with the offset clause applied
      */
-    offset<I extends DreamClassTransactionBuilder<DreamInstance>>(this: I, offset: number | null): Query<DreamInstance>;
+    offset<I extends DreamClassTransactionBuilder<DreamClass, DreamInstance>>(this: I, offset: number | null): Query<DreamInstance>;
     /**
      * Retrieves the max value of the specified column
      * for this model's records.
@@ -85,7 +86,7 @@ export default class DreamClassTransactionBuilder<DreamInstance extends Dream> {
      * @param columnName - A column name on the model
      * @returns The max value of the specified column for this model's records
      */
-    max<I extends DreamClassTransactionBuilder<DreamInstance>, T extends DreamColumnNames<DreamInstance>>(this: I, columnName: T): Promise<DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]][T & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]]]["coercedType" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]][T & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]]]]>;
+    max<I extends DreamClassTransactionBuilder<DreamClass, DreamInstance>, T extends DreamColumnNames<DreamInstance>>(this: I, columnName: T): Promise<DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]][T & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]]]["coercedType" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]][T & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]]]]>;
     /**
      * Retrieves the min value of the specified column
      * for this model's records.
@@ -100,7 +101,7 @@ export default class DreamClassTransactionBuilder<DreamInstance extends Dream> {
      * @param columnName - A column name on the model
      * @returns The min value of the specified column for this model's records
      */
-    min<I extends DreamClassTransactionBuilder<DreamInstance>, T extends DreamColumnNames<DreamInstance>>(this: I, columnName: T): Promise<DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]][T & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]]]["coercedType" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]][T & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]]]]>;
+    min<I extends DreamClassTransactionBuilder<DreamClass, DreamInstance>, T extends DreamColumnNames<DreamInstance>>(this: I, columnName: T): Promise<DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]][T & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]]]["coercedType" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]][T & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]]]]>;
     /**
      * Persists a new record, setting the provided attributes
      *
@@ -114,7 +115,9 @@ export default class DreamClassTransactionBuilder<DreamInstance extends Dream> {
      * @param attributes - Attributes or belongs to associations you wish to set on this model before persisting
      * @returns A newly persisted dream instance
      */
-    create<I extends DreamClassTransactionBuilder<DreamInstance>>(this: I, attributes?: UpdateableProperties<DreamInstance>): Promise<DreamInstance>;
+    create<I extends DreamClassTransactionBuilder<DreamClass, DreamInstance>>(this: I, attributes?: UpdateableProperties<DreamInstance>, { skipHooks }?: {
+        skipHooks?: boolean;
+    }): Promise<DreamInstance>;
     /**
      * Finds a record for the corresponding model with the
      * specified primary key. If not found, null is returned.
@@ -129,7 +132,7 @@ export default class DreamClassTransactionBuilder<DreamInstance extends Dream> {
      * @param primaryKey - The primary key of the record to look up
      * @returns Either the found record, or else null
      */
-    find<I extends DreamClassTransactionBuilder<DreamInstance>>(this: I, primaryKey: PrimaryKeyForFind<DreamInstance>): Promise<DreamInstance | null>;
+    find<I extends DreamClassTransactionBuilder<DreamClass, DreamInstance>>(this: I, primaryKey: PrimaryKeyForFind<DreamInstance>): Promise<DreamInstance | null>;
     /**
      * Finds a record for the corresponding model with the
      * specified primary key. If not found, an exception is raised.
@@ -144,7 +147,7 @@ export default class DreamClassTransactionBuilder<DreamInstance extends Dream> {
      * @param primaryKey - The primary key of the record to look up
      * @returns The found record
      */
-    findOrFail<I extends DreamClassTransactionBuilder<DreamInstance>>(this: I, primaryKey: PrimaryKeyForFind<DreamInstance>): Promise<DreamInstance>;
+    findOrFail<I extends DreamClassTransactionBuilder<DreamClass, DreamInstance>>(this: I, primaryKey: PrimaryKeyForFind<DreamInstance>): Promise<DreamInstance>;
     /**
      * Finds the first record—ordered by primary key—matching
      * the corresponding model and the specified where statement.
@@ -160,7 +163,7 @@ export default class DreamClassTransactionBuilder<DreamInstance extends Dream> {
      * @param attributes - The where statement used to locate the record
      * @returns Either the first model found matching the whereStatement, or else null
      */
-    findBy<I extends DreamClassTransactionBuilder<DreamInstance>, DB extends DreamInstance['DB']>(this: I, attributes: Updateable<DB[DreamInstance['table']]>): Promise<DreamInstance | null>;
+    findBy<I extends DreamClassTransactionBuilder<DreamClass, DreamInstance>>(this: I, attributes: WhereStatement<DreamInstance['DB'], DreamInstance['schema'], DreamInstance['table']>): Promise<DreamInstance | null>;
     /**
      * Finds the first record—ordered by primary key—matching
      * the corresponding model and the specified where statement.
@@ -176,7 +179,39 @@ export default class DreamClassTransactionBuilder<DreamInstance extends Dream> {
      * @param whereStatement - The where statement used to locate the record
      * @returns The first model found matching the whereStatement
      */
-    findOrFailBy<I extends DreamClassTransactionBuilder<DreamInstance>>(this: I, whereStatement: WhereStatement<DreamInstance['DB'], DreamInstance['schema'], DreamInstance['table']>): Promise<DreamInstance>;
+    findOrFailBy<I extends DreamClassTransactionBuilder<DreamClass, DreamInstance>>(this: I, whereStatement: WhereStatement<DreamInstance['DB'], DreamInstance['schema'], DreamInstance['table']>): Promise<DreamInstance>;
+    /**
+     * Attempt to find the model with the given attributes.
+     * If no record is found, then a new record is created.
+     *
+     * ```ts
+     * await ApplicationModel.transaction(async txn => {
+     *   await User.txn(txn).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
+     */
+    findOrCreateBy<I extends DreamClassTransactionBuilder<DreamClass, DreamInstance>>(this: I, attributes: UpdateablePropertiesForClass<DreamClass>, extraOpts?: CreateOrFindByExtraOpts<DreamClass>): Promise<InstanceType<DreamClass>>;
+    /**
+     * Attempt to update the model with the given attributes.
+     * If no record is found, then a new record is created.
+     * All lifecycle hooks are run for whichever action is taken.
+     *
+     * ```ts
+     * await ApplicationModel.transaction(async txn => {
+     *   await User.txn(txn).updateOrCreateBy({ email }, { with: { name: 'Alice' })
+     * })
+     * ```
+     *
+     * @param attributes - The base attributes for finding, but also the attributes to use when creating
+     * @param extraOpts.with - additional attributes to persist when updating and creating, but not used for finding
+     * @param extraOpts.skipHooks - if true, will skip applying model hooks. Defaults to false
+     * @returns A dream instance
+     */
+    updateOrCreateBy<I extends DreamClassTransactionBuilder<DreamClass, DreamInstance>>(this: I, attributes: UpdateablePropertiesForClass<DreamClass>, extraOpts?: UpdateOrCreateByExtraOpts<DreamClass>): Promise<InstanceType<DreamClass>>;
     /**
      * Finds all records for the corresponding model in batches,
      * and then calls the provided callback for each found record.
@@ -198,7 +233,7 @@ export default class DreamClassTransactionBuilder<DreamInstance extends Dream> {
      * @param options.batchSize - The batch size you wish to collect records in. If not provided, it will default to 1000
      * @returns void
      */
-    findEach<I extends DreamClassTransactionBuilder<DreamInstance>>(this: I, cb: (instance: DreamInstance) => void | Promise<void>, options?: FindEachOpts): Promise<void>;
+    findEach<I extends DreamClassTransactionBuilder<DreamClass, DreamInstance>>(this: I, cb: (instance: DreamInstance) => void | Promise<void>, options?: FindEachOpts): Promise<void>;
     /**
      * Returns the first record corresponding to the
      * model, ordered by primary key.
@@ -212,7 +247,7 @@ export default class DreamClassTransactionBuilder<DreamInstance extends Dream> {
      *
      * @returns First record, or null if no record exists
      */
-    first<I extends DreamClassTransactionBuilder<DreamInstance>>(this: I): Promise<DreamInstance | null>;
+    first<I extends DreamClassTransactionBuilder<DreamClass, DreamInstance>>(this: I): Promise<DreamInstance | null>;
     /**
      * Returns the first record corresponding to the
      * model, ordered by primary key. If no record
@@ -227,7 +262,7 @@ export default class DreamClassTransactionBuilder<DreamInstance extends Dream> {
      *
      * @returns First record
      */
-    firstOrFail<I extends DreamClassTransactionBuilder<DreamInstance>>(this: I): Promise<DreamInstance>;
+    firstOrFail<I extends DreamClassTransactionBuilder<DreamClass, DreamInstance>>(this: I): Promise<DreamInstance>;
     /**
      * Returns true if a record exists for the given
      * model class.
@@ -246,7 +281,7 @@ export default class DreamClassTransactionBuilder<DreamInstance extends Dream> {
      *
      * @returns boolean
      */
-    exists<I extends DreamClassTransactionBuilder<DreamInstance>>(this: I): Promise<boolean>;
+    exists<I extends DreamClassTransactionBuilder<DreamClass, DreamInstance>>(this: I): Promise<boolean>;
     /**
      * Load each specified association using a single SQL query.
      * See {@link #preload} for preloading in separate queries.
@@ -268,7 +303,7 @@ export default class DreamClassTransactionBuilder<DreamInstance extends Dream> {
      * @param args - A chain of association names and where clauses
      * @returns A query for this model with the include statement applied
      */
-    leftJoinPreload<I extends DreamClassTransactionBuilder<DreamInstance>, DB extends DreamInstance['DB'], TableName extends DreamInstance['table'], Schema extends DreamInstance['schema'], const Arr extends readonly unknown[], const LastArg extends VariadicLeftJoinLoadArgs<DB, Schema, TableName, Arr>, const JoinedAssociationsCandidate = JoinedAssociationsTypeFromAssociations<DB, Schema, TableName, [
+    leftJoinPreload<I extends DreamClassTransactionBuilder<DreamClass, DreamInstance>, DB extends DreamInstance['DB'], TableName extends DreamInstance['table'], Schema extends DreamInstance['schema'], const Arr extends readonly unknown[], const LastArg extends VariadicLeftJoinLoadArgs<DB, Schema, TableName, Arr>, const JoinedAssociationsCandidate = JoinedAssociationsTypeFromAssociations<DB, Schema, TableName, [
         ...Arr,
         LastArg
     ]>, const JoinedAssociations extends readonly JoinedAssociation[] = JoinedAssociationsCandidate extends readonly JoinedAssociation[] ? JoinedAssociationsCandidate : never, RetQuery = QueryWithJoinedAssociationsTypeAndNoPreload<Query<DreamInstance>, JoinedAssociations>>(this: I, ...args: [...Arr, LastArg]): RetQuery;
@@ -293,7 +328,7 @@ export default class DreamClassTransactionBuilder<DreamInstance extends Dream> {
      * @param args - A chain of association names and where clauses
      * @returns A query for this model with the preload statement applied
      */
-    preload<I extends DreamClassTransactionBuilder<DreamInstance>, DB extends DreamInstance['DB'], TableName extends DreamInstance['table'], Schema extends DreamInstance['schema'], const Arr extends readonly unknown[]>(this: I, ...args: [...Arr, VariadicLoadArgs<DB, Schema, TableName, Arr>]): Query<DreamInstance, Readonly<{
+    preload<I extends DreamClassTransactionBuilder<DreamClass, DreamInstance>, DB extends DreamInstance['DB'], TableName extends DreamInstance['table'], Schema extends DreamInstance['schema'], const Arr extends readonly unknown[]>(this: I, ...args: [...Arr, VariadicLoadArgs<DB, Schema, TableName, Arr>]): Query<DreamInstance, Readonly<{
         joinedAssociations: readonly [];
         rootTableName: DreamInstance["table"];
         rootTableAlias: DreamInstance extends Dream ? DreamInstance["table"] : DreamInstance;
@@ -313,7 +348,7 @@ export default class DreamClassTransactionBuilder<DreamInstance extends Dream> {
      * @param args - A chain of association names and where clauses
      * @returns A Query for this model with the inner join clause applied
      */
-    innerJoin<I extends DreamClassTransactionBuilder<DreamInstance>, DB extends DreamInstance['DB'], TableName extends DreamInstance['table'], Schema extends DreamInstance['schema'], const Arr extends readonly unknown[], const LastArg extends VariadicJoinsArgs<DB, Schema, TableName, Arr>, const JoinedAssociationsCandidate = JoinedAssociationsTypeFromAssociations<DB, Schema, TableName, [
+    innerJoin<I extends DreamClassTransactionBuilder<DreamClass, DreamInstance>, DB extends DreamInstance['DB'], TableName extends DreamInstance['table'], Schema extends DreamInstance['schema'], const Arr extends readonly unknown[], const LastArg extends VariadicJoinsArgs<DB, Schema, TableName, Arr>, const JoinedAssociationsCandidate = JoinedAssociationsTypeFromAssociations<DB, Schema, TableName, [
         ...Arr,
         LastArg
     ]>, const JoinedAssociations extends readonly JoinedAssociation[] = JoinedAssociationsCandidate extends readonly JoinedAssociation[] ? JoinedAssociationsCandidate : never, RetQuery = QueryWithJoinedAssociationsType<Query<DreamInstance>, JoinedAssociations>>(this: I, ...args: [...Arr, LastArg]): RetQuery;
@@ -330,7 +365,7 @@ export default class DreamClassTransactionBuilder<DreamInstance extends Dream> {
      * @param args - A chain of association names and where clauses
      * @returns A Query for this model with the left join clause applied
      */
-    leftJoin<I extends DreamClassTransactionBuilder<DreamInstance>, DB extends DreamInstance['DB'], TableName extends DreamInstance['table'], Schema extends DreamInstance['schema'], const Arr extends readonly unknown[], const LastArg extends VariadicJoinsArgs<DB, Schema, TableName, Arr>, const JoinedAssociationsCandidate = JoinedAssociationsTypeFromAssociations<DB, Schema, TableName, [
+    leftJoin<I extends DreamClassTransactionBuilder<DreamClass, DreamInstance>, DB extends DreamInstance['DB'], TableName extends DreamInstance['table'], Schema extends DreamInstance['schema'], const Arr extends readonly unknown[], const LastArg extends VariadicJoinsArgs<DB, Schema, TableName, Arr>, const JoinedAssociationsCandidate = JoinedAssociationsTypeFromAssociations<DB, Schema, TableName, [
         ...Arr,
         LastArg
     ]>, const JoinedAssociations extends readonly JoinedAssociation[] = JoinedAssociationsCandidate extends readonly JoinedAssociation[] ? JoinedAssociationsCandidate : never, RetQuery = QueryWithJoinedAssociationsType<Query<DreamInstance>, JoinedAssociations>>(this: I, ...args: [...Arr, LastArg]): RetQuery;
@@ -346,20 +381,20 @@ export default class DreamClassTransactionBuilder<DreamInstance extends Dream> {
      *
      * @returns A new Query instance
      */
-    queryInstance<I extends DreamClassTransactionBuilder<DreamInstance>>(this: I): Query<DreamInstance>;
+    queryInstance<I extends DreamClassTransactionBuilder<DreamClass, DreamInstance>>(this: I): Query<DreamInstance>;
     /**
      * Returns a query for this model which disregards default scopes
      *
      * @returns A query for this model which disregards default scopes
      */
-    removeAllDefaultScopes<I extends DreamClassTransactionBuilder<DreamInstance>>(this: I): Query<DreamInstance>;
+    removeAllDefaultScopes<I extends DreamClassTransactionBuilder<DreamClass, DreamInstance>>(this: I): Query<DreamInstance>;
     /**
      * 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
      */
-    removeDefaultScope<I extends DreamClassTransactionBuilder<DreamInstance>>(this: I, scopeName: DefaultScopeName<DreamInstance>): Query<DreamInstance>;
+    removeDefaultScope<I extends DreamClassTransactionBuilder<DreamClass, DreamInstance>>(this: I, scopeName: DefaultScopeName<DreamInstance>): Query<DreamInstance>;
     /**
      * Returns the last record corresponding to the
      * model, ordered by primary key.
@@ -373,7 +408,7 @@ export default class DreamClassTransactionBuilder<DreamInstance extends Dream> {
      *
      * @returns Last record, or null if no record exists
      */
-    last<I extends DreamClassTransactionBuilder<DreamInstance>>(this: I): Promise<DreamInstance | null>;
+    last<I extends DreamClassTransactionBuilder<DreamClass, DreamInstance>>(this: I): Promise<DreamInstance | null>;
     /**
      * Returns the last record corresponding to the
      * model, ordered by primary key. If no record
@@ -388,7 +423,7 @@ export default class DreamClassTransactionBuilder<DreamInstance extends Dream> {
      *
      * @returns Last record
      */
-    lastOrFail<I extends DreamClassTransactionBuilder<DreamInstance>>(this: I): Promise<DreamInstance>;
+    lastOrFail<I extends DreamClassTransactionBuilder<DreamClass, DreamInstance>>(this: I): Promise<DreamInstance>;
     /**
      * Returns a new Kysely SelectQueryBuilder instance to be used
      * in a sub Query
@@ -405,7 +440,7 @@ export default class DreamClassTransactionBuilder<DreamInstance extends Dream> {
      * @param selection - the column to use for your nested Query
      * @returns A Kysely SelectQueryBuilder instance
      */
-    nestedSelect<I extends DreamClassTransactionBuilder<DreamInstance>, DB extends DreamInstance['DB'], SE extends SelectExpression<DB, DreamInstance['table']>>(this: I, selection: SelectArg<DB, DreamInstance['table'], SE>): import("kysely").SelectQueryBuilder<any, any, any>;
+    nestedSelect<I extends DreamClassTransactionBuilder<DreamClass, DreamInstance>, DB extends DreamInstance['DB'], SE extends SelectExpression<DB, DreamInstance['table']>>(this: I, selection: SelectArg<DB, DreamInstance['table'], SE>): import("kysely").SelectQueryBuilder<any, any, any>;
     /**
      * Returns a new Query instance, attaching the provided
      * order statement
@@ -427,7 +462,7 @@ export default class DreamClassTransactionBuilder<DreamInstance extends Dream> {
      * @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
      */
-    order<I extends DreamClassTransactionBuilder<DreamInstance>>(this: I, arg: DreamColumnNames<DreamInstance> | Partial<Record<DreamColumnNames<DreamInstance>, OrderDir>> | null): Query<DreamInstance, Readonly<{
+    order<I extends DreamClassTransactionBuilder<DreamClass, DreamInstance>>(this: I, arg: DreamColumnNames<DreamInstance> | Partial<Record<DreamColumnNames<DreamInstance>, OrderDir>> | null): Query<DreamInstance, Readonly<{
         joinedAssociations: Readonly<[]>;
         rootTableName: DreamInstance["table"];
         rootTableAlias: DreamInstance extends Dream ? DreamInstance["table"] : DreamInstance;
@@ -457,7 +492,7 @@ export default class DreamClassTransactionBuilder<DreamInstance extends Dream> {
      * @param columnNames - The column or array of columns to pluck
      * @returns An array of pluck results
      */
-    pluck<I extends DreamClassTransactionBuilder<DreamInstance>, ColumnNames extends TableColumnNames<DreamInstance['DB'], DreamInstance['table']>[], ReturnValue extends ColumnNames['length'] extends 1 ? BaseModelColumnTypes<ColumnNames, DreamInstance>[0][] : BaseModelColumnTypes<ColumnNames, DreamInstance>[]>(this: I, ...columnNames: ColumnNames): Promise<ReturnValue>;
+    pluck<I extends DreamClassTransactionBuilder<DreamClass, DreamInstance>, ColumnNames extends TableColumnNames<DreamInstance['DB'], DreamInstance['table']>[], ReturnValue extends ColumnNames['length'] extends 1 ? BaseModelColumnTypes<ColumnNames, DreamInstance>[0][] : BaseModelColumnTypes<ColumnNames, DreamInstance>[]>(this: I, ...columnNames: ColumnNames): Promise<ReturnValue>;
     /**
      * Plucks the specified fields from the given dream class table
      * in batches, passing each found columns into the provided callback function.
@@ -476,7 +511,7 @@ export default class DreamClassTransactionBuilder<DreamInstance extends Dream> {
      * @param fields - A list of fields to pluck, followed by a callback function to call for each set of found fields
      * @returns void
      */
-    pluckEach<I extends DreamClassTransactionBuilder<DreamInstance>, ColumnName extends keyof UpdateableProperties<DreamInstance>, ColumnNames extends ColumnName[], CbArgTypes extends BaseModelColumnTypes<ColumnNames, DreamInstance>>(this: I, ...args: PluckEachArgs<ColumnNames, CbArgTypes>): Promise<void>;
+    pluckEach<I extends DreamClassTransactionBuilder<DreamClass, DreamInstance>, ColumnName extends keyof UpdateableProperties<DreamInstance>, ColumnNames extends ColumnName[], CbArgTypes extends BaseModelColumnTypes<ColumnNames, DreamInstance>>(this: I, ...args: PluckEachArgs<ColumnNames, CbArgTypes>): Promise<void>;
     /**
      * Sends data through for use as passthrough data
      * for the associations that require it.
@@ -502,7 +537,7 @@ export default class DreamClassTransactionBuilder<DreamInstance extends Dream> {
      * @param passthroughWhereStatement - Where statement used for associations that require passthrough data
      * @returns A Query for this model with the passthrough data
      */
-    passthrough<I extends DreamClassTransactionBuilder<DreamInstance>, PassthroughColumns extends PassthroughColumnNames<DreamInstance>>(this: I, passthroughWhereStatement: PassthroughOnClause<PassthroughColumns>): Query<DreamInstance>;
+    passthrough<I extends DreamClassTransactionBuilder<DreamClass, DreamInstance>, PassthroughColumns extends PassthroughColumnNames<DreamInstance>>(this: I, passthroughWhereStatement: PassthroughOnClause<PassthroughColumns>): Query<DreamInstance>;
     /**
      * Applies a where statement to a new Query instance
      * scoped to this model.
@@ -517,7 +552,7 @@ export default class DreamClassTransactionBuilder<DreamInstance extends Dream> {
      * @param whereStatement - Where statement to apply to the Query
      * @returns A Query for this model with the where clause applied
      */
-    where<I extends DreamClassTransactionBuilder<DreamInstance>, DB extends DreamInstance['DB'], Schema extends DreamInstance['schema'], TableName extends AssociationTableNames<DB, Schema> & keyof DB = I['dreamInstance']['table'] & keyof DB>(this: I, whereStatement: WhereStatement<DB, Schema, TableName>): Query<DreamInstance>;
+    where<I extends DreamClassTransactionBuilder<DreamClass, DreamInstance>, DB extends DreamInstance['DB'], Schema extends DreamInstance['schema'], TableName extends AssociationTableNames<DB, Schema> & keyof DB = I['dreamInstance']['table'] & keyof DB>(this: I, whereStatement: WhereStatement<DB, Schema, TableName>): Query<DreamInstance>;
     /**
      * Applies "OR"'d where statements to a Query scoped
      * to this model.
@@ -532,7 +567,7 @@ export default class DreamClassTransactionBuilder<DreamInstance extends Dream> {
      * @param whereStatements - An array of where statements to `OR` together
      * @returns A Query for this model with the whereAny clause applied
      */
-    whereAny<I extends DreamClassTransactionBuilder<DreamInstance>, DB extends DreamInstance['DB'], Schema extends DreamInstance['schema'], TableName extends AssociationTableNames<DB, Schema> & keyof DB = I['dreamInstance']['table'] & keyof DB>(this: I, whereStatements: WhereStatement<DB, Schema, TableName>[]): Query<DreamInstance>;
+    whereAny<I extends DreamClassTransactionBuilder<DreamClass, DreamInstance>, DB extends DreamInstance['DB'], Schema extends DreamInstance['schema'], TableName extends AssociationTableNames<DB, Schema> & keyof DB = I['dreamInstance']['table'] & keyof DB>(this: I, whereStatements: WhereStatement<DB, Schema, TableName>[]): Query<DreamInstance>;
     /**
      * Applies a whereNot statement to a new Query instance
      * scoped to this model.
@@ -547,5 +582,5 @@ export default class DreamClassTransactionBuilder<DreamInstance extends Dream> {
      * @param whereStatement - A where statement to negate and apply to the Query
      * @returns A Query for this model with the whereNot clause applied
      */
-    whereNot<I extends DreamClassTransactionBuilder<DreamInstance>, DB extends DreamInstance['DB'], Schema extends DreamInstance['schema'], TableName extends AssociationTableNames<DB, Schema> & keyof DB = I['dreamInstance']['table'] & keyof DB>(this: I, whereStatement: WhereStatement<DB, Schema, TableName>): Query<DreamInstance>;
+    whereNot<I extends DreamClassTransactionBuilder<DreamClass, DreamInstance>, DB extends DreamInstance['DB'], Schema extends DreamInstance['schema'], TableName extends AssociationTableNames<DB, Schema> & keyof DB = I['dreamInstance']['table'] & keyof DB>(this: I, whereStatement: WhereStatement<DB, Schema, TableName>): Query<DreamInstance>;
 }

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

@@ -8,15 +8,15 @@ import LeftJoinLoadBuilder from './LeftJoinLoadBuilder.js';
 import LoadBuilder from './LoadBuilder.js';
 import Query from './Query.js';
 export default class DreamInstanceTransactionBuilder<DreamInstance extends Dream> {
-    dreamInstance: DreamInstance;
-    dreamTransaction: DreamTransaction<Dream>;
+    private dreamInstance;
+    private dreamTransaction;
     /**
      * Constructs a new DreamInstanceTransactionBuilder.
      *
      * @param dreamInstance - The Dream instance to build the transaction for
      * @param txn - The DreamTransaction instance
      */
-    constructor(dreamInstance: DreamInstance, txn: DreamTransaction<Dream>);
+    constructor(dreamInstance: DreamInstance, dreamTransaction: DreamTransaction<Dream> | null);
     /**
      * Loads the requested associations upon execution
      *