@rvoh/dream 0.29.1

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

@@ -0,0 +1,477 @@
+import associationQuery from './internal/associations/associationQuery.js';
+import associationUpdateQuery from './internal/associations/associationUpdateQuery.js';
+import createAssociation from './internal/associations/createAssociation.js';
+import destroyAssociation from './internal/associations/destroyAssociation.js';
+import undestroyAssociation from './internal/associations/undestroyAssociation.js';
+import destroyDream from './internal/destroyDream.js';
+import { destroyOptions, reallyDestroyOptions, undestroyOptions, } from './internal/destroyOptions.js';
+import reload from './internal/reload.js';
+import saveDream from './internal/saveDream.js';
+import { DEFAULT_BYPASS_ALL_DEFAULT_SCOPES, DEFAULT_DEFAULT_SCOPES_TO_BYPASS, DEFAULT_SKIP_HOOKS, } from './internal/scopeHelpers.js';
+import undestroyDream from './internal/undestroyDream.js';
+import LeftJoinLoadBuilder from './LeftJoinLoadBuilder.js';
+import LoadBuilder from './LoadBuilder.js';
+export default class DreamInstanceTransactionBuilder {
+    dreamInstance;
+    dreamTransaction;
+    /**
+     * Constructs a new DreamInstanceTransactionBuilder.
+     *
+     * @param dreamInstance - The Dream instance to build the transaction for
+     * @param txn - The DreamTransaction instance
+     */
+    constructor(dreamInstance, txn) {
+        this.dreamInstance = dreamInstance;
+        this.dreamTransaction = txn;
+    }
+    /**
+     * Loads the requested associations upon execution
+     *
+     * NOTE: {@link Dream#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.dreamInstance, this.dreamTransaction).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 Dream#leftJoinPreload} is often a preferrable way of achieving the
+     * same goal.
+     *
+     * ```ts
+     * await user.txn(txn)
+     *  .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.dreamInstance, this.dreamTransaction).leftJoinLoad(...args);
+    }
+    /**
+     * Returns a new Query instance with the provided
+     * inner join statement attached
+     *
+     * ```ts
+     * await ApplicationModel.transaction(async txn => {
+     *   await user.txn(txn).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.queryInstance().innerJoin(...args);
+    }
+    /**
+     * Returns a new Query instance with the provided
+     * left join statement attached
+     *
+     * ```ts
+     * await ApplicationModel.transaction(async txn => {
+     *   await user.txn(txn).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.queryInstance().leftJoin(...args);
+    }
+    /**
+     * Deletes the record represented by this instance
+     * from the database, calling any destroy
+     * hooks on this model.
+     *
+     * ```ts
+     * const user = await User.last()
+     * await ApplicationModel.transaction(async txn => {
+     *   await user.txn(txn).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.dreamInstance, this.dreamTransaction, destroyOptions(options));
+    }
+    /**
+     * Deletes the record represented by this instance
+     * from the database, calling any destroy
+     * hooks on this model.
+     *
+     * ```ts
+     * const user = await User.last()
+     * await ApplicationModel.transaction(async txn => {
+     *   await user.txn(txn).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.dreamInstance, this.dreamTransaction, 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.txn(txn).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 instance
+     */
+    async undestroy(options = {}) {
+        await undestroyDream(this.dreamInstance, this.dreamTransaction, undestroyOptions(options));
+        await this.reload();
+        return this.dreamInstance;
+    }
+    /**
+     * 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 ApplicationModel.transaction(async txn => {
+     *    await user.txn(txn).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 } = {}) {
+        this.dreamInstance.assignAttributes(attributes);
+        await saveDream(this.dreamInstance, this.dreamTransaction, { 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 ApplicationModel.transaction(async txn => {
+     *    await user.txn(txn).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 } = {}) {
+        this.dreamInstance.setAttributes(attributes);
+        await saveDream(this.dreamInstance, this.dreamTransaction, { skipHooks });
+    }
+    /**
+     * Reloads an instance, refreshing all it's attribute values
+     * to those in the database.
+     *
+     * NOTE: this does not refresh associations
+     *
+     * ```ts
+     * await ApplicationModel.transaction(async txn => {
+     *   await user.txn(txn).reload()
+     * })
+     * ```
+     *
+     * @returns void
+     */
+    async reload() {
+        await reload(this.dreamInstance, this.dreamTransaction);
+    }
+    /**
+     * 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' })
+     *
+     * await ApplicationModel.transaction(async txn => {
+     *   user.name = 'fred'
+     *   await user.txn(txn).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.dreamInstance, this.dreamTransaction, { skipHooks });
+    }
+    /**
+     * Returns a Query instance for the specified
+     * association on the current instance.
+     *
+     * ```ts
+     * await ApplicationModel.transaction(async txn => {
+     *   await user.txn(txn).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.dreamInstance, this.dreamTransaction, 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 where statement will be applied to the query
+     * before updating.
+     *
+     * ```ts
+     * await ApplicationModel.transaction(async txn => {
+     *   await user.txn(txn).createAssociation('posts', { body: 'hello world' })
+     *   await user.txn(txn).createAssociation('posts', { body: 'howyadoin' })
+     *   await user.txn(txn).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 updateAssociationOptions - Options for updating the association
+     * @param updateAssociationOptions.where - Optional where statement to apply to query before updating
+     * @param updateAssociationOptions.bypassAllDefaultScopes - If true, bypasses all default scopes when updating the association. Defaults to false
+     * @param updateAssociationOptions.defaultScopesToBypass - An array of default scope names to bypass when updating the association. Defaults to an empty array
+     * @param updateAssociationOptions.skipHooks - If true, skips applying model hooks during the update operation. Defaults to false
+     * @returns The number of updated records
+     */
+    async updateAssociation(associationName, attributes, updateAssociationOptions) {
+        return await associationUpdateQuery(this.dreamInstance, this.dreamTransaction, 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 });
+    }
+    /**
+     * Creates an association for an instance. Automatically
+     * handles setting foreign key and, in the case of polymorphism,
+     * foreign key type.
+     *
+     * ```ts
+     * await ApplicationModel.transaction(async txn => {
+     *   await user.txn(txn).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, opts = {}) {
+        return await createAssociation(this.dreamInstance, this.dreamTransaction, associationName, opts);
+    }
+    /**
+     * Destroys models associated with the current instance,
+     * deleting their corresponding records within the database.
+     *
+     * ```ts
+     * await ApplicationModel.transaction(async txn => {
+     *   await user.txn(txn).destroyAssociation('posts', { on: { 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.dreamInstance, this.dreamTransaction, 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 ApplicationModel.transaction(async txn => {
+     *   await user.txn(txn).reallyDestroyAssociation('posts', { on: { 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.dreamInstance, this.dreamTransaction, 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', { on: { 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.dreamInstance, this.dreamTransaction, associationName, {
+            ...undestroyOptions(options),
+            joinOnStatements: {
+                on: options?.on,
+                notOn: options?.notOn,
+                onAny: options?.onAny,
+            },
+        });
+    }
+    ///////////////////
+    // end: undestroyAssociation
+    ///////////////////
+    /**
+     * @internal
+     *
+     * returns a query instance, scoped to the current
+     * dream instance with primary key where statement
+     * automatically applied.
+     */
+    queryInstance() {
+        const dreamClass = this.dreamInstance.constructor;
+        const id = this.dreamInstance.primaryKeyValue;
+        return dreamClass.txn(this.dreamTransaction).where({ [this.dreamInstance.primaryKey]: id });
+    }
+}

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

@@ -0,0 +1,23 @@
+import { runHook } from './internal/runHooksFor.js';
+// though this class is called `DreamTransaction`, it is not itself
+// a transaction class, as much as a collector for various callbacks
+// that must be run after the underlying transaction is commited (i.e.
+// AfterCreateCommit, AfterUpdateCommit, etc...).
+export default class DreamTransaction {
+    _kyselyTransaction;
+    commitHooks = [];
+    get kyselyTransaction() {
+        return this._kyselyTransaction;
+    }
+    set kyselyTransaction(txn) {
+        this._kyselyTransaction = txn;
+    }
+    addCommitHook(hookStatement, dreamInstance) {
+        this.commitHooks.push({ dreamInstance, hookStatement });
+    }
+    async runAfterCommitHooks(txn) {
+        for (const hook of this.commitHooks) {
+            await runHook(hook.hookStatement, hook.dreamInstance, txn);
+        }
+    }
+}

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

@@ -0,0 +1,74 @@
+export default class LeftJoinLoadBuilder {
+    dream;
+    dreamTransaction;
+    query;
+    /**
+     * An intermediate class on the way to executing a load
+     * query. this can be accessed on an instance of a dream
+     * model by using the `#load` method:
+     *
+     * ```ts
+     * const user = await User.firstOrFail()
+     * await user.load('settings').execute()
+     * ```
+     */
+    constructor(dream, txn) {
+        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
+        // preclude finding that instance, so the Query that forms the base of
+        // a load must be unscoped, but that unscoping should not carry through
+        // 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);
+        return this;
+    }
+    /**
+     * Attaches a load statement to the load builder
+     *
+     * ```ts
+     * const user = await User.firstOrFail()
+     * await user
+     *   .load('settings')
+     *   .load('posts', 'comments', 'replies', ['image', 'localizedText'])
+     *   .execute()
+     * ```
+     */
+    leftJoinLoad(...args) {
+        this.query = this.query.leftJoinPreload(...args);
+        return this;
+    }
+    /**
+     * executes a load builder query, binding
+     * all associations to their respective model
+     * instances.
+     *
+     * ```ts
+     * const user = await User.firstOrFail()
+     * await user
+     *   .load('settings')
+     *   .load('posts', 'comments', 'replies', ['image', 'localizedText'])
+     *   .execute()
+     * ```
+     */
+    async execute() {
+        if (this.dreamTransaction) {
+            this.query = this.query.txn(this.dreamTransaction);
+        }
+        const dreamWithLoadedAssociations = await this.query.firstOrFail();
+        Object.keys(this.query['leftJoinStatements']).forEach(associationName => {
+            this.query['hydrateAssociation']([this.dream], this.dream['getAssociationMetadata'](associationName), this.associationToPreloadedDreamsAndWhatTheyPointTo({
+                pointsToPrimaryKey: this.dream.primaryKeyValue,
+                associatedModels: dreamWithLoadedAssociations[associationName],
+            }));
+        });
+        return this.dream;
+    }
+    associationToPreloadedDreamsAndWhatTheyPointTo({ pointsToPrimaryKey, associatedModels, }) {
+        return [associatedModels].flat().map(dream => ({ dream, pointsToPrimaryKey }));
+    }
+}

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

@@ -0,0 +1,65 @@
+export default class LoadBuilder {
+    dream;
+    dreamTransaction;
+    query;
+    /**
+     * An intermediate class on the way to executing a load
+     * query. this can be accessed on an instance of a dream
+     * model by using the `#load` method:
+     *
+     * ```ts
+     * const user = await User.firstOrFail()
+     * await user.load('settings').execute()
+     * ```
+     */
+    constructor(dream, txn) {
+        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
+        // preclude finding that instance, so the Query that forms the base of
+        // a load must be unscoped, but that unscoping should not carry through
+        // 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);
+        return this;
+    }
+    /**
+     * Attaches a load statement to the load builder
+     *
+     * ```ts
+     * const user = await User.firstOrFail()
+     * await user
+     *   .load('settings')
+     *   .load('posts', 'comments', 'replies', ['image', 'localizedText'])
+     *   .execute()
+     * ```
+     */
+    load(...args) {
+        this.query = this.query.preload(...args);
+        return this;
+    }
+    /**
+     * executes a load builder query, binding
+     * all associations to their respective model
+     * instances.
+     *
+     * ```ts
+     * const user = await User.firstOrFail()
+     * await user
+     *   .load('settings')
+     *   .load('posts', 'comments', 'replies', ['image', 'localizedText'])
+     *   .execute()
+     * ```
+     */
+    async execute() {
+        if (this.dreamTransaction) {
+            this.query = this.query.txn(this.dreamTransaction);
+        }
+        await this.query['hydratePreload'](this.dream);
+        return this.dream;
+    }
+}