@rvoh/dream 0.29.1

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

@@ -0,0 +1,316 @@
+import Dream from '../Dream.js';
+import DreamTransaction from './DreamTransaction.js';
+import { DestroyOptions } from './internal/destroyOptions.js';
+import LeftJoinLoadBuilder from './LeftJoinLoadBuilder.js';
+import LoadBuilder from './LoadBuilder.js';
+import Query, { DefaultQueryTypeOptions, QueryWithJoinedAssociationsType } from './Query.js';
+import { AllDefaultScopeNames, AssociationNameToDream, DreamAssociationNames, DreamAssociationNamesWithoutRequiredOnClauses, DreamAttributes, JoinedAssociation, JoinedAssociationsTypeFromAssociations, JoinOnStatements, RequiredOnClauseKeys, UpdateableAssociationProperties, UpdateableProperties, VariadicJoinsArgs, VariadicLeftJoinLoadArgs, VariadicLoadArgs } from './types.js';
+export default class DreamInstanceTransactionBuilder<DreamInstance extends Dream> {
+    dreamInstance: DreamInstance;
+    dreamTransaction: DreamTransaction<Dream>;
+    /**
+     * 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>);
+    /**
+     * 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<I extends DreamInstanceTransactionBuilder<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>]): LoadBuilder<DreamInstance>;
+    /**
+     * 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<I extends DreamInstanceTransactionBuilder<DreamInstance>, DB extends DreamInstance['DB'], TableName extends DreamInstance['table'], Schema extends DreamInstance['schema'], const Arr extends readonly unknown[]>(this: I, ...args: [...Arr, VariadicLeftJoinLoadArgs<DB, Schema, TableName, Arr>]): LeftJoinLoadBuilder<DreamInstance>;
+    /**
+     * 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<I extends DreamInstanceTransactionBuilder<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;
+    /**
+     * 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<I extends DreamInstanceTransactionBuilder<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;
+    /**
+     * 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
+     */
+    destroy<I extends DreamInstanceTransactionBuilder<DreamInstance>>(this: I, options?: DestroyOptions<DreamInstance>): Promise<DreamInstance>;
+    /**
+     * 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
+     */
+    reallyDestroy<I extends DreamInstanceTransactionBuilder<DreamInstance>>(this: I, options?: DestroyOptions<DreamInstance>): Promise<DreamInstance>;
+    /**
+     * 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
+     */
+    undestroy<I extends DreamInstanceTransactionBuilder<DreamInstance>>(this: I, options?: DestroyOptions<DreamInstance>): Promise<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
+     */
+    update<I extends DreamInstanceTransactionBuilder<DreamInstance>>(this: I, attributes: UpdateableProperties<DreamInstance>, { skipHooks }?: {
+        skipHooks?: boolean;
+    }): Promise<void>;
+    /**
+     * 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
+     */
+    updateAttributes<I extends DreamInstanceTransactionBuilder<DreamInstance>>(this: I, attributes: UpdateableProperties<DreamInstance>, { skipHooks }?: {
+        skipHooks?: boolean;
+    }): Promise<void>;
+    /**
+     * 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
+     */
+    reload<I extends DreamInstanceTransactionBuilder<DreamInstance>>(this: I): Promise<void>;
+    /**
+     * 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
+     */
+    save<I extends DreamInstanceTransactionBuilder<DreamInstance>>(this: I, { skipHooks }?: {
+        skipHooks?: boolean;
+    }): Promise<void>;
+    associationQuery<I extends DreamInstanceTransactionBuilder<DreamInstance>, DB extends DreamInstance['DB'], TableName extends DreamInstance['table'], Schema extends DreamInstance['schema'], AssociationName extends DreamAssociationNames<DreamInstance>, RequiredOnClauseKeysForThisAssociation extends RequiredOnClauseKeys<Schema, TableName, AssociationName>, AssociationDream extends AssociationNameToDream<DreamInstance, AssociationName>, AssociationTableName extends AssociationDream['table']>(this: I, associationName: AssociationName, joinOnStatements: JoinOnStatements<DB, Schema, AssociationTableName, RequiredOnClauseKeysForThisAssociation>): Query<AssociationDream, DefaultQueryTypeOptions<AssociationDream, AssociationName & string>>;
+    associationQuery<I extends DreamInstanceTransactionBuilder<DreamInstance>, DB extends DreamInstance['DB'], Schema extends DreamInstance['schema'], AssociationName extends DreamAssociationNamesWithoutRequiredOnClauses<DreamInstance>, AssociationDream extends AssociationNameToDream<DreamInstance, AssociationName>, AssociationTableName extends AssociationDream['table']>(this: I, associationName: AssociationName, joinOnStatements?: JoinOnStatements<DB, Schema, AssociationTableName, null>): Query<AssociationDream, DefaultQueryTypeOptions<AssociationDream, AssociationName & string>>;
+    updateAssociation<I extends DreamInstanceTransactionBuilder<DreamInstance>, DB extends DreamInstance['DB'], TableName extends DreamInstance['table'], Schema extends DreamInstance['schema'], AssociationName extends DreamAssociationNames<DreamInstance>, RequiredOnClauseKeysForThisAssociation extends RequiredOnClauseKeys<Schema, TableName, AssociationName>, AssociationDream extends AssociationNameToDream<DreamInstance, AssociationName>, AssociationTableName extends AssociationDream['table']>(this: I, associationName: AssociationName, attributes: Partial<DreamAttributes<AssociationNameToDream<DreamInstance, AssociationName>>>, updateAssociationOptions: {
+        bypassAllDefaultScopes?: boolean;
+        defaultScopesToBypass?: AllDefaultScopeNames<DreamInstance>[];
+        skipHooks?: boolean;
+    } & JoinOnStatements<DB, Schema, AssociationTableName, RequiredOnClauseKeysForThisAssociation>): Promise<number>;
+    updateAssociation<I extends DreamInstanceTransactionBuilder<DreamInstance>, DB extends DreamInstance['DB'], Schema extends DreamInstance['schema'], AssociationName extends DreamAssociationNamesWithoutRequiredOnClauses<DreamInstance>, AssociationDream extends AssociationNameToDream<DreamInstance, AssociationName>, AssociationTableName extends AssociationDream['table']>(this: I, associationName: AssociationName, attributes: Partial<DreamAttributes<AssociationNameToDream<DreamInstance, AssociationName>>>, updateAssociationOptions?: {
+        bypassAllDefaultScopes?: boolean;
+        defaultScopesToBypass?: AllDefaultScopeNames<DreamInstance>[];
+        skipHooks?: boolean;
+    } & JoinOnStatements<DB, Schema, AssociationTableName, null>): Promise<number>;
+    /**
+     * 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
+     */
+    createAssociation<I extends DreamInstanceTransactionBuilder<DreamInstance>, AssociationName extends DreamAssociationNames<DreamInstance>, PossibleArrayAssociationType = DreamInstance[AssociationName & keyof DreamInstance], AssociationType = PossibleArrayAssociationType extends (infer ElementType)[] ? ElementType : PossibleArrayAssociationType, RestrictedAssociationType extends AssociationType extends Dream ? AssociationType : never = AssociationType extends Dream ? AssociationType : never>(this: I, associationName: AssociationName, opts?: UpdateableAssociationProperties<DreamInstance, RestrictedAssociationType>): Promise<NonNullable<AssociationType>>;
+    destroyAssociation<I extends DreamInstanceTransactionBuilder<DreamInstance>, DB extends DreamInstance['DB'], TableName extends DreamInstance['table'], Schema extends DreamInstance['schema'], AssociationName extends DreamAssociationNames<DreamInstance>, RequiredOnClauseKeysForThisAssociation extends RequiredOnClauseKeys<Schema, TableName, AssociationName>, AssociationDream extends AssociationNameToDream<DreamInstance, AssociationName>, AssociationTableName extends AssociationDream['table']>(this: I, associationName: AssociationName, options: DestroyOptions<DreamInstance> & JoinOnStatements<DB, Schema, AssociationTableName, RequiredOnClauseKeysForThisAssociation>): Promise<number>;
+    destroyAssociation<I extends DreamInstanceTransactionBuilder<DreamInstance>, DB extends DreamInstance['DB'], Schema extends DreamInstance['schema'], AssociationName extends DreamAssociationNamesWithoutRequiredOnClauses<DreamInstance>, AssociationDream extends AssociationNameToDream<DreamInstance, AssociationName>, AssociationTableName extends AssociationDream['table']>(this: I, associationName: AssociationName, options?: DestroyOptions<DreamInstance> & JoinOnStatements<DB, Schema, AssociationTableName, null>): Promise<number>;
+    reallyDestroyAssociation<I extends DreamInstanceTransactionBuilder<DreamInstance>, DB extends DreamInstance['DB'], TableName extends DreamInstance['table'], Schema extends DreamInstance['schema'], AssociationName extends DreamAssociationNames<DreamInstance>, RequiredOnClauseKeysForThisAssociation extends RequiredOnClauseKeys<Schema, TableName, AssociationName>, AssociationDream extends AssociationNameToDream<DreamInstance, AssociationName>, AssociationTableName extends AssociationDream['table']>(this: I, associationName: AssociationName, options: DestroyOptions<DreamInstance> & JoinOnStatements<DB, Schema, AssociationTableName, RequiredOnClauseKeysForThisAssociation>): Promise<number>;
+    reallyDestroyAssociation<I extends DreamInstanceTransactionBuilder<DreamInstance>, DB extends DreamInstance['DB'], Schema extends DreamInstance['schema'], AssociationName extends DreamAssociationNamesWithoutRequiredOnClauses<DreamInstance>, AssociationDream extends AssociationNameToDream<DreamInstance, AssociationName>, AssociationTableName extends AssociationDream['table']>(this: I, associationName: AssociationName, options?: DestroyOptions<DreamInstance> & JoinOnStatements<DB, Schema, AssociationTableName, null>): Promise<number>;
+    undestroyAssociation<I extends DreamInstanceTransactionBuilder<DreamInstance>, DB extends DreamInstance['DB'], TableName extends DreamInstance['table'], Schema extends DreamInstance['schema'], AssociationName extends DreamAssociationNames<DreamInstance>, RequiredOnClauseKeysForThisAssociation extends RequiredOnClauseKeys<Schema, TableName, AssociationName>, AssociationDream extends AssociationNameToDream<DreamInstance, AssociationName>, AssociationTableName extends AssociationDream['table']>(this: I, associationName: AssociationName, options: DestroyOptions<DreamInstance> & JoinOnStatements<DB, Schema, AssociationTableName, RequiredOnClauseKeysForThisAssociation>): Promise<number>;
+    undestroyAssociation<I extends DreamInstanceTransactionBuilder<DreamInstance>, DB extends DreamInstance['DB'], Schema extends DreamInstance['schema'], AssociationName extends DreamAssociationNamesWithoutRequiredOnClauses<DreamInstance>, AssociationDream extends AssociationNameToDream<DreamInstance, AssociationName>, AssociationTableName extends AssociationDream['table']>(this: I, associationName: AssociationName, options?: DestroyOptions<DreamInstance> & JoinOnStatements<DB, Schema, AssociationTableName, null>): Promise<number>;
+    /**
+     * @internal
+     *
+     * returns a query instance, scoped to the current
+     * dream instance with primary key where statement
+     * automatically applied.
+     */
+    private queryInstance;
+}

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

@@ -0,0 +1,15 @@
+import { Transaction } from 'kysely';
+import { HookStatement } from '../decorators/hooks/shared.js';
+import Dream from '../Dream.js';
+export interface TransactionCommitHookStatement {
+    hookStatement: HookStatement;
+    dreamInstance: Dream;
+}
+export default class DreamTransaction<T extends Dream, DB extends T['DB'] = T['DB']> {
+    private _kyselyTransaction;
+    private commitHooks;
+    get kyselyTransaction(): Transaction<DB>;
+    set kyselyTransaction(txn: Transaction<DB>);
+    addCommitHook(hookStatement: HookStatement, dreamInstance: Dream): void;
+    runAfterCommitHooks(txn: DreamTransaction<any>): Promise<void>;
+}

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

@@ -0,0 +1,48 @@
+import { PassthroughOnClause } from '../decorators/associations/shared.js';
+import Dream from '../Dream.js';
+import DreamTransaction from './DreamTransaction.js';
+import { PassthroughColumnNames, VariadicLeftJoinLoadArgs } from './types.js';
+export default class LeftJoinLoadBuilder<DreamInstance extends Dream> {
+    private dream;
+    private dreamTransaction;
+    private 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: Dream, txn?: DreamTransaction<any>);
+    passthrough<I extends LeftJoinLoadBuilder<DreamInstance>, PassthroughColumns extends PassthroughColumnNames<DreamInstance>>(this: I, passthroughWhereStatement: PassthroughOnClause<PassthroughColumns>): I;
+    /**
+     * 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<I extends LeftJoinLoadBuilder<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>>(this: I, ...args: [...Arr, LastArg]): I;
+    /**
+     * 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()
+     * ```
+     */
+    execute(): Promise<DreamInstance>;
+    private associationToPreloadedDreamsAndWhatTheyPointTo;
+}

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

@@ -0,0 +1,47 @@
+import { PassthroughOnClause } from '../decorators/associations/shared.js';
+import Dream from '../Dream.js';
+import DreamTransaction from './DreamTransaction.js';
+import { PassthroughColumnNames, VariadicLoadArgs } from './types.js';
+export default class LoadBuilder<DreamInstance extends Dream> {
+    private dream;
+    private dreamTransaction;
+    private 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: Dream, txn?: DreamTransaction<any>);
+    passthrough<I extends LoadBuilder<DreamInstance>, PassthroughColumns extends PassthroughColumnNames<DreamInstance>>(this: I, passthroughWhereStatement: PassthroughOnClause<PassthroughColumns>): I;
+    /**
+     * 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<I extends LoadBuilder<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>]): I;
+    /**
+     * 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()
+     * ```
+     */
+    execute(): Promise<DreamInstance>;
+}