@rvoh/dream 0.44.8 → 0.45.0

package/dist/esm/src/serializer/builders/ObjectSerializerBuilder.js

@@ -10,6 +10,38 @@ export default class ObjectSerializerBuilder {
         this.data = data;
         this.passthroughData = passthroughData;
     }
+    /**
+     * Includes an attribute from the data object in the serialized output.
+     *
+     * For ObjectSerializer, the `openapi` option is always required since type
+     * inference is not available for plain objects or ViewModels.
+     *
+     * @param name - The attribute name from the data object
+     * @param options - Configuration options including required OpenAPI schema, default value, and output customization
+     * @returns The serializer builder for method chaining
+     *
+     * @example
+     * ```typescript
+     * // Required OpenAPI schema
+     * .attribute('email', {
+     *   openapi: { type: 'string', format: 'email' }
+     * })
+     *
+     * // With default value
+     * .attribute('status', {
+     *   openapi: { type: 'string' },
+     *   default: 'active'
+     * })
+     *
+     * // Rename output key
+     * .attribute('email', {
+     *   openapi: { type: 'string' },
+     *   as: 'userEmail'
+     * })
+     * ```
+     *
+     * See: {@link https://your-docs-url.com/docs/serializers/attributes | Serializer Attributes Documentation}
+     */
     attribute(name, options) {
         this.attributes.push({
             type: 'attribute',
@@ -18,15 +50,74 @@ export default class ObjectSerializerBuilder {
         });
         return this;
     }
+    /**
+     * Includes an attribute from a nested object in the serialized output.
+     *
+     * Pulls up an attribute from a target object property. The `openapi` option
+     * is always required. If the target object or the delegated attribute
+     * is null/undefined, the `default` option value will be used if provided.
+     *
+     * @param targetName - The property name containing the target object
+     * @param name - The attribute name within the target object
+     * @param options - Configuration options including required OpenAPI schema, default value, and output customization
+     * @returns The serializer builder for method chaining
+     *
+     * @example
+     * ```typescript
+     * // Delegate to user.email
+     * .delegatedAttribute('user', 'email', {
+     *   openapi: { type: 'string', format: 'email' }
+     * })
+     *
+     * // With default value for null target or attribute
+     * .delegatedAttribute('profile', 'displayName', {
+     *   openapi: { type: 'string' },
+     *   default: 'Anonymous User'
+     * })
+     * ```
+     *
+     * See: {@link https://your-docs-url.com/docs/serializers/attributes | Serializer Attributes Documentation}
+     */
     delegatedAttribute(targetName, name, options) {
         this.attributes.push({
             type: 'delegatedAttribute',
-            targetName,
+            targetName: targetName,
             name: name,
             options: options ?? {},
         });
         return this;
     }
+    /**
+     * Includes a computed value in the serialized output.
+     *
+     * Executes a callback function to generate a custom attribute value.
+     * The `openapi` option is always required since the return type cannot be inferred.
+     *
+     * @param name - The attribute name for the computed value
+     * @param fn - Callback function that returns the computed value
+     * @param options - Configuration options including required OpenAPI schema and optional flattening
+     * @returns The serializer builder for method chaining
+     *
+     * @example
+     * ```typescript
+     * // Simple computed value
+     * .customAttribute('fullName', () =>
+     *   `${user.firstName} ${user.lastName}`,
+     *   { openapi: { type: 'string' } }
+     * )
+     *
+     * // Flattened object properties
+     * .customAttribute('coordinates', () => ({ lat: 40.7, lng: -74.0 }), {
+     *   flatten: true,
+     *   openapi: {
+     *     lat: { type: 'number' },
+     *     lng: { type: 'number' }
+     *   }
+     * })
+     * ```
+     *
+     * See: {@link https://your-docs-url.com/docs/serializers/attributes | Serializer Attributes Documentation}
+     */
     customAttribute(name, fn, options) {
         this.attributes.push({
             type: 'customAttribute',
@@ -36,22 +127,104 @@ export default class ObjectSerializerBuilder {
         });
         return this;
     }
+    /**
+     * Includes a single associated object in the serialized output.
+     *
+     * For ObjectSerializer, explicit serializer configuration is always required
+     * since association schemas cannot be inferred from plain objects.
+     *
+     * @param name - The association property name
+     * @param options - Configuration options including required serializer and OpenAPI schema
+     * @returns The serializer builder for method chaining
+     *
+     * @example
+     * ```typescript
+     * // With explicit serializer function
+     * .rendersOne('owner', UserSerializer, {
+     *   openapi: { $ref: '#/components/schemas/User' }
+     * })
+     *
+     * // With Dream class reference
+     * .rendersOne('creator', {
+     *   dreamClass: User,
+     *   serializerKey: 'summary',
+     *   openapi: { $ref: '#/components/schemas/UserSummary' }
+     * })
+     * ```
+     *
+     * See: {@link https://your-docs-url.com/docs/serializers/associations | Serializer Associations Documentation}
+     */
     rendersOne(name, options) {
         this.attributes.push({
             type: 'rendersOne',
-            name,
+            name: name,
             options: options ?? {},
         });
         return this;
     }
+    /**
+     * Includes an array of associated objects in the serialized output.
+     *
+     * For ObjectSerializer, explicit serializer configuration is always required
+     * since association schemas cannot be inferred from plain objects.
+     *
+     * @param name - The association property name (should be an array)
+     * @param options - Configuration options including required serializer and OpenAPI schema
+     * @returns The serializer builder for method chaining
+     *
+     * @example
+     * ```typescript
+     * // With explicit serializer function
+     * .rendersMany('articles', ArticleSerializer, {
+     *   openapi: {
+     *     type: 'array',
+     *     items: { $ref: '#/components/schemas/Article' }
+     *   }
+     * })
+     *
+     * // With ViewModel class reference
+     * .rendersMany('comments', {
+     *   viewModelClass: CommentViewModel,
+     *   serializer: CommentViewModelSerializer,
+     *   openapi: {
+     *     type: 'array',
+     *     items: { $ref: '#/components/schemas/Comment' }
+     *   }
+     * })
+     * ```
+     *
+     * See: {@link https://your-docs-url.com/docs/serializers/associations | Serializer Associations Documentation}
+     */
     rendersMany(name, options) {
         this.attributes.push({
             type: 'rendersMany',
-            name,
+            name: name,
             options: options ?? {},
         });
         return this;
     }
+    /**
+     * Executes the serializer and returns the serialized output.
+     *
+     * This method processes all defined attributes, custom attributes, delegated attributes,
+     * and associations to produce the final serialized object. The result is suitable for
+     * JSON.stringify() and API responses.
+     *
+     * @param passthrough - Additional data to pass through to nested serializers
+     * @param opts - Rendering options for customizing the serialization process
+     * @returns The serialized object
+     *
+     * @example
+     * ```typescript
+     * const result = UserViewModelSerializer(userVm).render()
+     * // Returns: { id: '123', email: 'user@example.com', ... }
+     *
+     * // With passthrough data for nested serializers
+     * const result = UserViewModelSerializer(userVm).render({ currentUserId: '456' })
+     * ```
+     *
+     * See: {@link https://your-docs-url.com/docs/serializers/render | Serializer Rendering Documentation}
+     */
     render(passthrough = {}, opts = {}) {
         return new SerializerRenderer(this, passthrough, opts).render();
     }

package/dist/esm/src/serializer/helpers/serializerForAssociatedClass.js

@@ -0,0 +1,17 @@
+import { inferSerializersFromDreamClassOrViewModelClass } from './inferSerializerFromDreamOrViewModel.js';
+/**
+ * Only used when flatten: true, and the associated model is null, in which case,
+ * we need something to determine the keys that will be flattened into the
+ * rendering serializer
+ */
+export function serializerForAssociatedClass(object, associationName, options) {
+    if (options.serializer)
+        return options.serializer;
+    if (!object.isDreamInstance)
+        return null;
+    const dream = object;
+    const association = dream['getAssociationMetadata'](associationName);
+    const associatedClasses = association.modelCB();
+    const associatedClass = Array.isArray(associatedClasses) ? associatedClasses[0] : associatedClasses;
+    return inferSerializersFromDreamClassOrViewModelClass(associatedClass, options.serializerKey)[0] ?? null;
+}

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

@@ -6,14 +6,16 @@ import DreamClassTransactionBuilder from './dream/DreamClassTransactionBuilder.j
 import DreamInstanceTransactionBuilder from './dream/DreamInstanceTransactionBuilder.js';
 import DreamTransaction from './dream/DreamTransaction.js';
 import { DestroyOptions } from './dream/internal/destroyOptions.js';
+import { RecursiveSerializerInfo } from './dream/internal/extractNestedPaths.js';
 import LeftJoinLoadBuilder from './dream/LeftJoinLoadBuilder.js';
 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, CreateOrFindByExtraOpts, DefaultOrNamedScopeName, DreamAssociationNames, DreamAssociationNamesWithoutRequiredOnClauses, DreamAttributes, DreamColumnNames, DreamParamSafeColumnNames, IdType, JoinAndStatements, NextPreloadArgumentType, OrderDir, PassthroughColumnNames, PluckEachArgs, PrimaryKeyForFind, TableColumnNames, UpdateableAssociationProperties, UpdateableProperties, UpdateablePropertiesForClass, UpdateOrCreateByExtraOpts } from './types/dream.js';
+import { AllDefaultScopeNames, AssociationNameToDream, AttributeKeys, CreateOrFindByExtraOpts, DefaultOrNamedScopeName, DreamAssociationNames, DreamAssociationNamesWithoutRequiredOnClauses, DreamAttributes, DreamColumnNames, DreamParamSafeColumnNames, DreamSerializerKey, 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, PaginatedDreamQueryOptions, PaginatedDreamQueryResult, QueryWithJoinedAssociationsType, QueryWithJoinedAssociationsTypeAndNoPreload } from './types/query.js';
+import { DreamModelSerializerType, SimpleObjectSerializerType } from './types/serializer.js';
 import { ValidationStatement, ValidationType } from './types/validation.js';
 import { JoinedAssociation, JoinedAssociationsTypeFromAssociations, RequiredOnClauseKeys, VariadicJoinsArgs, VariadicLeftJoinLoadArgs, VariadicLoadArgs } from './types/variadic.js';
 export default class Dream {
@@ -54,6 +56,44 @@ export default class Dream {
     private static globallyInitializingDecorators;
     get schema(): any;
     get globalSchema(): any;
+    /**
+     * Determines if the provided Dream class is the same as or a subclass of this Dream class.
+     * This method is particularly useful for runtime type checking and works with STI (Single Table Inheritance) classes.
+     *
+     * For regular Dream classes, this checks if the provided class is exactly the same class.
+     * For STI classes, this checks inheritance relationships - a child STI class will return true
+     * when compared against its parent class.
+     *
+     * ```ts
+     * // Regular class comparison
+     * User.typeof(User)    // true
+     * User.typeof(Pet)     // false
+     *
+     * // STI inheritance checking
+     * class Balloon extends ApplicationModel {
+     *   // base STI class
+     * }
+     *
+     * class Mylar extends Balloon {
+     *   // STI child class
+     * }
+     *
+     * Balloon.typeof(Balloon) // true
+     * Balloon.typeof(Mylar)   // false
+     * Mylar.typeof(Balloon)   // true (child recognizes parent)
+     * Mylar.typeof(Mylar)     // true
+     *
+     * // Runtime type checking with variables
+     * const dreamClass: typeof Dream = getRandomDreamClass()
+     * if (dreamClass.typeof(Pet)) {
+     *   // dreamClass is Pet or a subclass of Pet
+     * }
+     * ```
+     *
+     * @param dreamClass - The Dream class to compare against this class
+     * @returns `true` if the provided class is the same as this class or if this class is a subclass of the provided class (STI inheritance), `false` otherwise
+     */
+    static typeof(dreamClass: typeof Dream): boolean;
     /**
      * Shadows #primaryKey, a getter which can be overwritten to customize the id field
      * for a given model.
@@ -332,6 +372,12 @@ export default class Dream {
      * name of that model.
      */
     private static setGlobalName;
+    protected static serializationMap<T extends typeof Dream, I extends InstanceType<T>, SerializerKey extends DreamSerializerKey<I>>(this: T, serializerKey?: SerializerKey): RecursiveSerializerInfo;
+    protected static displaySerialization<T extends typeof Dream, I extends InstanceType<T>, SerializerKey extends DreamSerializerKey<I>>(this: T, serializerKey?: SerializerKey): RecursiveSerializerInfo;
+    protected static recursiveSerializationMap(serializer: DreamModelSerializerType | SimpleObjectSerializerType, { forDisplay, forDisplayDepth, }?: {
+        forDisplay?: boolean;
+        forDisplayDepth?: number;
+    }): RecursiveSerializerInfo;
     /**
      * Returns the column names for the given model
      *
@@ -463,12 +509,14 @@ export default class Dream {
      * // 2
      * ```
      *
+     * @param opts - Pagination options
      * @param opts.page - the page number that you want to fetch results for
      * @param opts.pageSize - the number of results per page (optional)
-     * @returns results.recordCount - A number representing the total number of records matching your query
-     * @returns results.pageCount - The number of pages needed to encapsulate all the matching records
-     * @returns results.currentPage - The current page (same as what is provided in the paginate args)
-     * @returns results.results - An array of records matching the current record
+     * @returns A paginated result object containing:
+     * - `recordCount` - A number representing the total number of records matching your query
+     * - `pageCount` - The number of pages needed to encapsulate all the matching records
+     * - `currentPage` - The current page (same as what is provided in the paginate args)
+     * - `results` - An array of records matching the current record
      */
     static paginate<T extends typeof Dream>(this: T, opts: PaginatedDreamQueryOptions): Promise<PaginatedDreamQueryResult<InstanceType<T>>>;
     /**
@@ -524,7 +572,8 @@ 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
+     * @param __namedParameters - optional parameters
+     * @param __namedParameters.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>, { skipHooks }?: {
@@ -546,6 +595,7 @@ export default class Dream {
      * ```
      *
      * @param attributes - The base attributes to persist, but also the attributes to use to find when create fails
+     * @param extraOpts - Additional options
      * @param extraOpts.createWith - additional attributes to persist when creating, but not used for finding
      * @returns A dream instance
      */
@@ -560,6 +610,7 @@ export default class Dream {
      * ```
      *
      * @param attributes - The base attributes for finding which record to update, also used when creating
+     * @param extraOpts - Additional options
      * @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
@@ -578,6 +629,7 @@ export default class Dream {
      * at least one of the provided attributes
      *
      * @param attributes - The base attributes for finding which record to update, also used when creating
+     * @param extraOpts - Additional options
      * @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
@@ -649,6 +701,7 @@ export default class Dream {
      * ```
      *
      * @param cb - The callback to call for each found record
+     * @param opts - Optional parameters for batch processing
      * @param opts.batchSize - the batch size you wish to collect records in. If not provided, it will default to 1000
      * @returns void
      */
@@ -722,6 +775,7 @@ export default class Dream {
      * ```
      *
      * @param attributes - The base attributes for finding, but also the attributes to use when creating
+     * @param extraOpts - Additional options
      * @param extraOpts.createWith - additional attributes to persist when creating, but not used for finding
      * @returns A dream instance
      */
@@ -745,10 +799,10 @@ export default class Dream {
     static exists<T extends typeof Dream>(this: T): Promise<boolean>;
     /**
      * Load each specified association using a single SQL query.
-     * See {@link #preload} for preloading in separate queries.
+     * See {@link Dream.preload} for preloading in separate queries.
      *
      * Note: since leftJoinPreload loads via single query, it has
-     * some downsides and that may be avoided using {@link #preload}:
+     * some downsides and that may be avoided using {@link Dream.preload}:
      * 1. `limit` and `offset` will be automatically removed
      * 2. `through` associations will bring additional namespaces into the query that can conflict with through associations from other associations, creating an invalid query
      * 3. each nested association will result in an additional record which duplicates data from the outer record. E.g., given `.leftJoinPreload('a', 'b', 'c')`, if each `a` has 10 `b` and each `b` has 10 `c`, then for one `a`, 100 records will be returned, each of which has all of the columns of `a`. `.preload('a', 'b', 'c')` would perform three separate SQL queries, but the data for a single `a` would only be returned once.
@@ -797,6 +851,144 @@ export default class Dream {
         allowOffset: true;
         allowPaginate: true;
     }>>;
+    /**
+     * Recursively preloads all Dream associations referenced by `rendersOne` and `rendersMany`
+     * in a DreamSerializer. This traverses the entire content tree of serializers to automatically
+     * load all necessary associations, eliminating N+1 query problems and removing the need to
+     * manually remember which associations to preload for serialization.
+     *
+     * This method decouples data loading code from data rendering code by having the serializer
+     * (rendering code) inform the query (loading code) about which associations are needed.
+     * As serializers evolve over time - adding new `rendersOne` and `rendersMany` calls or
+     * modifying existing ones - the loading code automatically adapts without requiring
+     * corresponding modifications to preload statements.
+     *
+     * This method analyzes the serializer (specified by `serializerKey` or 'default') and
+     * automatically preloads all associations that will be needed during serialization.
+     *
+     * ```ts
+     * // Instead of manually specifying all associations:
+     * await User.preload('posts', 'comments', 'replies').all()
+     *
+     * // Automatically preload everything needed for serialization:
+     * await User.preloadForSerialization({ serializerKey: 'summary' }).all()
+     *
+     * // Add where conditions to specific associations during preloading:
+     * await User.preloadForSerialization({
+     *   serializerKey: 'detailed',
+     *   modifierFn: (dreamClass, associationName) => {
+     *     if (dreamClass.typeof(Post) && associationName === 'comments') {
+     *       return { and: { published: true } }
+     *     }
+     *   }
+     * }).all()
+     *
+     * // Skip preloading specific associations to handle them manually:
+     * await User.preloadForSerialization({
+     *   serializerKey: 'summary',
+     *   modifierFn: (dreamClass, associationName) => {
+     *     if (dreamClass.typeof(User) && associationName === 'posts') {
+     *       return 'omit' // Handle posts preloading separately with custom logic
+     *     }
+     *   }
+     * })
+     * .preload('posts', { and: { featured: true } }) // Custom preloading
+     * .all()
+     * ```
+     *
+     * @param opts - Configuration options for serialization preloading
+     * @param opts.serializerKey - The serializer key to use for determining which associations to preload. Defaults to 'default'
+     * @param opts.modifierFn - Optional callback function to modify or omit specific associations during preloading. Called for each association with the Dream class and association name. Return an object with `and`, `andAny`, or `andNot` properties to add where conditions, return 'omit' to skip preloading that association (useful when you want to handle it manually), or return undefined to use default preloading
+     * @returns A Query with all serialization associations preloaded
+     */
+    static preloadForSerialization<T extends typeof Dream, I extends InstanceType<T>, SerializerKey extends DreamSerializerKey<I>>(this: T, opts?: {
+        serializerKey?: SerializerKey;
+        modifierFn?: <DreamClass extends typeof Dream, const AssociationName extends DreamAssociationNames<InstanceType<DreamClass>>>(dreamClass: DreamClass, associationName: AssociationName) => {
+            and?: object;
+            andAny?: object;
+            andNot?: object;
+        } | 'omit' | undefined;
+    }): Query<InstanceType<T>, Readonly<{
+        joinedAssociations: readonly [];
+        rootTableName: InstanceType<T>["table"];
+        rootTableAlias: InstanceType<T> extends infer T_1 ? T_1 extends InstanceType<T> ? T_1 extends Dream ? T_1["table"] : T_1 : never : never;
+        allowPreload: true;
+        allowLeftJoinPreload: false;
+        allowLimit: true;
+        allowOffset: true;
+        allowPaginate: true;
+    }>>;
+    /**
+     * Recursively preloads all Dream associations referenced by `rendersOne` and `rendersMany`
+     * in a DreamSerializer using left join preloading. This traverses the entire content tree
+     * of serializers to automatically load all necessary associations in a single query,
+     * eliminating N+1 query problems and removing the need to manually remember which
+     * associations to preload for serialization.
+     *
+     * This method decouples data loading code from data rendering code by having the serializer
+     * (rendering code) inform the query (loading code) about which associations are needed.
+     * As serializers evolve over time - adding new `rendersOne` and `rendersMany` calls or
+     * modifying existing ones - the loading code automatically adapts without requiring
+     * corresponding modifications to left join preload statements.
+     *
+     * This method analyzes the serializer (specified by `serializerKey` or 'default') and
+     * automatically left join preloads all associations that will be needed during serialization.
+     *
+     * Note: Left join preloading loads all data in a single SQL query but has trade-offs compared
+     * to regular preloading. See {@link Dream.leftJoinPreload} for details about limitations.
+     *
+     * ```ts
+     * // Instead of manually specifying all associations:
+     * await User.leftJoinPreload('posts', 'comments', 'replies').all()
+     *
+     * // Automatically left join preload everything needed for serialization:
+     * await User.leftJoinPreloadForSerialization({ serializerKey: 'summary' }).all()
+     *
+     * // Add where conditions to specific associations during left join preloading:
+     * await User.leftJoinPreloadForSerialization({
+     *   serializerKey: 'detailed',
+     *   modifierFn: (dreamClass, associationName) => {
+     *     if (dreamClass.typeof(Post) && associationName === 'comments') {
+     *       return { and: { published: true } }
+     *     }
+     *   }
+     * }).all()
+     *
+     * // Skip left join preloading specific associations to handle them manually:
+     * await User.leftJoinPreloadForSerialization({
+     *   serializerKey: 'summary',
+     *   modifierFn: (dreamClass, associationName) => {
+     *     if (dreamClass.typeof(User) && associationName === 'posts') {
+     *       return 'omit' // Handle posts preloading separately with custom logic
+     *     }
+     *   }
+     * })
+     * .preload('posts', { and: { featured: true } }) // Custom preloading instead
+     * .all()
+     * ```
+     *
+     * @param opts - Configuration options for serialization preloading
+     * @param opts.serializerKey - The serializer key to use for determining which associations to preload. Defaults to 'default'
+     * @param opts.modifierFn - Optional callback function to modify or omit specific associations during preloading. Called for each association with the Dream class and association name. Return an object with `and`, `andAny`, or `andNot` properties to add where conditions, return 'omit' to skip preloading that association (useful when you want to handle it manually), or return undefined to use default preloading
+     * @returns A Query with all serialization associations left join preloaded
+     */
+    static leftJoinPreloadForSerialization<T extends typeof Dream, I extends InstanceType<T>, SerializerKey extends DreamSerializerKey<I>>(this: T, opts?: {
+        serializerKey?: SerializerKey;
+        modifierFn?: <DreamClass extends typeof Dream, const AssociationName extends DreamAssociationNames<InstanceType<DreamClass>>>(dreamClass: DreamClass, associationName: AssociationName) => {
+            and?: object;
+            andAny?: object;
+            andNot?: object;
+        } | 'omit' | undefined;
+    }): Query<InstanceType<T>, Readonly<{
+        joinedAssociations: readonly [];
+        rootTableName: InstanceType<T>["table"];
+        rootTableAlias: InstanceType<T> extends infer T_1 ? T_1 extends InstanceType<T> ? T_1 extends Dream ? T_1["table"] : T_1 : never : never;
+        allowPreload: false;
+        allowLeftJoinPreload: true;
+        allowLimit: false;
+        allowOffset: false;
+        allowPaginate: false;
+    }>>;
     /**
      * Returns a new Query instance with the provided
      * inner join statement attached
@@ -999,7 +1191,7 @@ export default class Dream {
      * // 3
      * ```
      *
-     * @param fields - a list of fields to pluck, followed by a callback function to call for each set of found fields
+     * @param args - a list of fields to pluck, followed by a callback function to call for each set of found fields
      * @returns void
      */
     static pluckEach<T extends typeof Dream, I extends InstanceType<T>, ColumnNames extends TableColumnNames<I['DB'], I['table']>[], CbArgTypes extends BaseModelColumnTypes<ColumnNames, I>>(this: T, ...args: PluckEachArgs<ColumnNames, CbArgTypes>): Promise<void>;
@@ -1176,7 +1368,7 @@ export default class Dream {
      * // [User{email: 'how@yadoin'}, User{name: 'fred'}, User{name: 'fred'}]
      * ```
      *
-     * @param whereStatements - a list of where statements to `OR` together
+     * @param statements - a list of where statements to `OR` together
      * @returns A Query for this model with the whereAny clause applied
      */
     static whereAny<T extends typeof Dream, I extends InstanceType<T>, DB extends I['DB'], Schema extends I['schema'], TableName extends AssociationTableNames<DB, Schema> & keyof DB = InstanceType<T>['table']>(this: T, statements: WhereStatement<DB, Schema, TableName>[]): Query<InstanceType<T>>;
@@ -1189,7 +1381,7 @@ export default class Dream {
      * // User{email: 'hello@world'}
      * ```
      *
-     * @param whereStatement - A where statement to negate and apply to the Query
+     * @param attributes - A where statement to negate and apply to the Query
      * @returns A Query for this model with the whereNot clause applied
      */
     static whereNot<T extends typeof Dream, I extends InstanceType<T>, DB extends I['DB'], Schema extends I['schema'], TableName extends AssociationTableNames<DB, Schema> & keyof DB = InstanceType<T>['table']>(this: T, attributes: WhereStatement<DB, Schema, TableName>): Query<InstanceType<T>>;
@@ -1850,7 +2042,7 @@ export default class Dream {
      * // 'dog'
      * ```
      *
-     * @param columName - The column name you want the previous value for
+     * @param columnName - The column name you want the previous value for
      * @returns Returns the previous value for an attribute
      */
     previousValueForAttribute<I extends Dream, DB extends I['DB'], TableName extends I['table'], Table extends DB[TableName], ColumnName extends DreamColumnNames<I>>(this: I, columnName: ColumnName): Updateable<Table>[ColumnName];
@@ -1867,7 +2059,7 @@ export default class Dream {
      * Returns true if the columnName provided has
      * changes that have not yet been persisted.
      *
-     * @param columnName - the column name to check
+     * @param attribute - the column name to check
      * @returns A boolean
      */
     willSaveChangeToAttribute<I extends Dream>(this: I, attribute: DreamColumnNames<I>): boolean;
@@ -2068,7 +2260,7 @@ export default class Dream {
     /**
      * Loads the requested associations upon execution
      *
-     * NOTE: {@link #preload} is often a preferrable way of achieving the
+     * NOTE: {@link Dream.preload} is often a preferrable way of achieving the
      * same goal.
      *
      * ```ts
@@ -2090,18 +2282,17 @@ export default class Dream {
     load<I extends Dream, DB extends I['DB'], TableName extends I['table'], Schema extends I['schema'], const Arr extends readonly unknown[]>(this: I, ...args: [...Arr, VariadicLoadArgs<DB, Schema, TableName, Arr>]): LoadBuilder<I>;
     /**
      * Load each specified association using a single SQL query.
-     * See {@link #load} for loading in separate queries.
+     * See {@link Dream.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}:
+     * Note: since leftJoinLoad loads via single query, it has
+     * some downsides and that may be avoided using {@link Dream.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.
+     * 3. each nested association will result in an additional record which duplicates data from the outer record. E.g., given `.leftJoinLoad('a', 'b', 'c')`, if each `a` has 10 `b` and each `b` has 10 `c`, then for one `a`, 100 records will be returned, each of which has all of the columns of `a`. `.load('a', 'b', 'c')` would perform three separate SQL queries, but the data for a single `a` would only be returned once.
      * 4. the individual query becomes more complex the more associations are included
      * 5. associations loading associations loading associations could result in exponential amounts of data; in those cases, `.load(...).findEach(...)` avoids instantiating massive amounts of data at once
-     * Loads the requested associations upon execution
      *
-     * NOTE: {@link #leftJoinPreload} is often a preferrable way of achieving the
+     * NOTE: {@link Dream.leftJoinPreload} is often a preferrable way of achieving the
      * same goal.
      *
      * ```ts
@@ -2220,7 +2411,8 @@ export default class Dream {
      * user.type // 'User'
      * ```
      *
-     * @param opts.skipHooks - if true, will skip applying model hooks. Defaults to false
+     * @param __namedParameters - optional parameters
+     * @param __namedParameters.skipHooks - if true, will skip applying model hooks. Defaults to false
      * @returns void
      */
     save<I extends Dream>(this: I, { skipHooks }?: {
@@ -2258,7 +2450,8 @@ export default class Dream {
      * ```
      *
      * @param attributes - the attributes to set on the model
-     * @param opts.skipHooks - if true, will skip applying model hooks. Defaults to false
+     * @param __namedParameters - optional parameters
+     * @param __namedParameters.skipHooks - if true, will skip applying model hooks. Defaults to false
      * @returns void
      */
     update<I extends Dream>(this: I, attributes: UpdateableProperties<I>, { skipHooks }?: {
@@ -2283,7 +2476,8 @@ export default class Dream {
      * ```
      *
      * @param attributes - The attributes to update on this instance
-     * @param opts.skipHooks - if true, will skip applying model hooks. Defaults to false
+     * @param __namedParameters - optional parameters
+     * @param __namedParameters.skipHooks - if true, will skip applying model hooks. Defaults to false
      * @returns - void
      */
     updateAttributes<I extends Dream>(this: I, attributes: UpdateableProperties<I>, { skipHooks }?: {
@@ -2312,7 +2506,7 @@ export default class Dream {
      * Flags a dream model so that it allows
      * deletion once again.
      *
-     * Undoes {@link Dream.(preventDeletion:instance) | preventDeletion}
+     * Undoes {@link Dream.preventDeletion}
      *
      * ```ts
      * class User extends ApplicationModel {