@rvoh/dream 0.44.9 → 0.45.1

package/dist/esm/src/Dream.js

@@ -1,3 +1,4 @@
+import yoctocolors from 'yoctocolors';
 import { pgErrorType } from './db/errors.js';
 import db from './db/index.js';
 import associationToGetterSetterProp from './decorators/field/association/associationToGetterSetterProp.js';
@@ -45,7 +46,10 @@ import cloneDeepSafe from './helpers/cloneDeepSafe.js';
 import { DateTime } from './helpers/DateTime.js';
 import cachedTypeForAttribute from './helpers/db/cachedTypeForAttribute.js';
 import isJsonColumn from './helpers/db/types/isJsonColumn.js';
+import { indent } from './helpers/indent.js';
 import notEqual from './helpers/notEqual.js';
+import { inferSerializersFromDreamClassOrViewModelClass } from './serializer/helpers/inferSerializerFromDreamOrViewModel.js';
+import { serializerForAssociatedClass } from './serializer/helpers/serializerForAssociatedClass.js';
 export default class Dream {
     DB;
     /**
@@ -102,6 +106,46 @@ export default class Dream {
     get globalSchema() {
         throw new DreamMissingRequiredOverride(this.constructor, 'globalSchema');
     }
+    /**
+     * 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) {
+        return this.new() instanceof dreamClass;
+    }
     /**
      * Shadows #primaryKey, a getter which can be overwritten to customize the id field
      * for a given model.
@@ -421,6 +465,65 @@ export default class Dream {
     static setGlobalName(globalName) {
         this._globalName = globalName;
     }
+    static serializationMap(serializerKey) {
+        const key = serializerKey || 'default';
+        const serializer = inferSerializersFromDreamClassOrViewModelClass(this, key)[0] ?? null;
+        if (!serializer)
+            throw new Error(`unable to find serializer with key: ${key}`);
+        return this.recursiveSerializationMap(serializer);
+    }
+    static displaySerialization(serializerKey) {
+        const key = serializerKey || 'default';
+        const serializer = inferSerializersFromDreamClassOrViewModelClass(this, key)[0] ?? null;
+        if (!serializer)
+            throw new Error(`unable to find serializer with key: ${key}`);
+        console.log(yoctocolors.cyan(this.sanitizedName));
+        console.log(yoctocolors.gray(serializer.globalName));
+        return this.recursiveSerializationMap(serializer, {
+            forDisplay: true,
+        });
+    }
+    static recursiveSerializationMap(serializer, { forDisplay = false, forDisplayDepth = 0, } = {}) {
+        const serializerBuilder = serializer(undefined, undefined);
+        const serializerAssociations = serializerBuilder['attributes'].filter(attribute => ['rendersOne', 'rendersMany', 'delegatedAttribute'].includes(attribute.type));
+        return serializerAssociations.reduce((acc, serializerAssociation) => {
+            const serializerAssociationName = serializerAssociation.targetName ??
+                serializerAssociation.name;
+            const serializerAssociationType = serializerAssociation.type;
+            const association = this['getAssociationMetadata'](serializerAssociationName);
+            if (!association)
+                return acc;
+            const associatedClasses = association.modelCB();
+            const associatedClass = Array.isArray(associatedClasses) ? associatedClasses[0] : associatedClasses;
+            if (!associatedClass)
+                throw new Error(`No class defined on ${serializerAssociationName} association on ${this.sanitizedName}`);
+            const associationSerializer = serializerForAssociatedClass(this.prototype, serializerAssociationName, serializerAssociation.options);
+            if (!associationSerializer)
+                throw new Error(`No serializer found to render ${serializerAssociationName} on ${this.sanitizedName}`);
+            if (forDisplay && serializerAssociationType !== 'delegatedAttribute') {
+                const hierarchyLine = '└───';
+                const indentation = indent((hierarchyLine.length + 1) * forDisplayDepth, {
+                    tabWidth: 1,
+                });
+                const prefix = `${hierarchyLine} `;
+                const nestedAssociationDisplay = indentation + `${prefix}${serializerAssociationType} ${yoctocolors.cyan(serializerAssociationName)}`;
+                console.log(nestedAssociationDisplay);
+                console.log(yoctocolors.gray(indentation +
+                    indent(prefix.length, { tabWidth: 1 }) +
+                    associationSerializer.globalName));
+            }
+            acc[association.as] = {
+                parentDreamClass: this,
+                nestedSerializerInfo: serializerAssociation.type === 'delegatedAttribute'
+                    ? {}
+                    : associatedClass['recursiveSerializationMap'](associationSerializer, {
+                        forDisplay,
+                        forDisplayDepth: forDisplayDepth + 1,
+                    }),
+            };
+            return acc;
+        }, {});
+    }
     /**
      * Returns the column names for the given model
      *
@@ -622,12 +725,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 async paginate(opts) {
         return await this.query().paginate(opts);
@@ -695,7 +800,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 async create(attributes, { skipHooks } = {}) {
@@ -719,6 +825,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
      */
@@ -751,6 +858,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
@@ -771,6 +879,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
@@ -860,6 +969,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
      */
@@ -944,6 +1054,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
      */
@@ -971,10 +1082,10 @@ export default class Dream {
     }
     /**
      * 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.
@@ -1015,6 +1126,102 @@ export default class Dream {
     static preload(...args) {
         return this.query().preload(...args);
     }
+    /**
+     * 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.preloadFor('summary').all()
+     *
+     * // Add where conditions to specific associations during preloading:
+     * await User.preloadFor('default', (dreamClass, associationName) => {
+     *   if (dreamClass.typeof(Post) && associationName === 'comments') {
+     *     return { and: { published: true } }
+     *   }
+     * }).all()
+     *
+     * // Skip preloading specific associations to handle them manually:
+     * await User.preloadFor('summary', (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 serializerKey - The serializer key to use for determining which associations to preload.
+     * @param 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 preloadFor(serializerKey, modifierFn) {
+        return this.query().preloadFor(serializerKey, modifierFn);
+    }
+    /**
+     * 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.leftJoinPreloadFor('summary').all()
+     *
+     * // Add where conditions to specific associations during left join preloading:
+     * await User.leftJoinPreloadFor('detailed', (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.leftJoinPreloadFor('summary', (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 serializerKey - The serializer key to use for determining which associations to preload.
+     * @param 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 leftJoinPreloadFor(serializerKey, modifierFn) {
+        return this.query().leftJoinPreloadFor(serializerKey, modifierFn);
+    }
     /**
      * Returns a new Query instance with the provided
      * inner join statement attached
@@ -1211,7 +1418,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 async pluckEach(...args) {
@@ -1420,7 +1627,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(statements) {
@@ -1435,7 +1642,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(attributes) {
@@ -2375,7 +2582,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(columnName) {
@@ -2401,7 +2608,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(attribute) {
@@ -2838,7 +3045,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
@@ -2860,20 +3067,67 @@ export default class Dream {
     load(...args) {
         return new LoadBuilder(this).load(...args);
     }
+    /**
+     * Recursively loads 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.loadFor('summary').execute()
+     *
+     * // Add where conditions to specific associations during preloading:
+     * await user.loadFor('detailed', (dreamClass, associationName) => {
+     *   if (dreamClass.typeof(Post) && associationName === 'comments') {
+     *     return { and: { published: true } }
+     *   }
+     * })
+     *    .execute()
+     *
+     * // Skip preloading specific associations to handle them manually:
+     * await user
+     *   .loadFor('summary', (dreamClass, associationName) => {
+     *     if (dreamClass.typeof(User) && associationName === 'posts') {
+     *       return 'omit' // Handle posts preloading separately with custom logic
+     *     }
+     *   })
+     *     .load('posts', { and: { featured: true } }) // Custom preloading
+     *     .execute()
+     * ```
+     *
+     * @param serializerKey - The serializer key to use for determining which associations to preload.
+     * @param 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
+     */
+    loadFor(serializerKey, modifierFn) {
+        return new LoadBuilder(this)['loadFor'](serializerKey, modifierFn);
+    }
     /**
      * 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
@@ -2895,6 +3149,54 @@ export default class Dream {
     leftJoinLoad(...args) {
         return new LeftJoinLoadBuilder(this).leftJoinLoad(...args);
     }
+    /**
+     * Recursively loads 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.leftJoinLoadFor('summary').execute()
+     *
+     * // Add where conditions to specific associations during preloading:
+     * await user.leftJoinLoadFor('detailed', (dreamClass, associationName) => {
+     *   if (dreamClass.typeof(Post) && associationName === 'comments') {
+     *     return { and: { published: true } }
+     *   }
+     * })
+     *    .execute()
+     *
+     * // Skip preloading specific associations to handle them manually:
+     * await user
+     *   .loadFor('summary', (dreamClass, associationName) => {
+     *     if (dreamClass.typeof(User) && associationName === 'posts') {
+     *       return 'omit' // Handle posts preloading separately with custom logic
+     *     }
+     *   })
+     *     .load('posts', { and: { featured: true } }) // Custom preloading
+     *     .execute()
+     * ```
+     *
+     * @param serializerKey - The serializer key to use for determining which associations to preload.
+     * @param 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
+     */
+    leftJoinLoadFor(serializerKey, modifierFn) {
+        return new LeftJoinLoadBuilder(this)['leftJoinLoadFor'](serializerKey, modifierFn);
+    }
     /**
      * Returns true if the association specified has
      * been loaded on this instance
@@ -3007,7 +3309,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
      */
     async save({ skipHooks } = {}) {
@@ -3047,7 +3350,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
      */
     async update(attributes, { skipHooks } = {}) {
@@ -3074,7 +3378,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
      */
     async updateAttributes(attributes, { skipHooks } = {}) {
@@ -3107,7 +3412,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 {

package/dist/esm/src/cli/index.js

@@ -1,5 +1,6 @@
 import { InvalidArgumentError } from 'commander';
 import DreamBin from '../bin/index.js';
+import DreamApp from '../dream-app/index.js';
 import EnvInternal from '../helpers/EnvInternal.js';
 import sspawn from '../helpers/sspawn.js';
 import DreamCliLogger from './logger/DreamCliLogger.js';
@@ -139,6 +140,21 @@ export default class DreamCLI {
             await seedDb();
             process.exit();
         });
+        program
+            .command('inspect:serialization')
+            .alias('i:serialization')
+            .description('displays a serialization map to help understand the rendering logic for a particular model')
+            .argument('<globalName>', 'the global name of the model you want to look up')
+            .argument('[serializerKey]', 'the serializer key you wish to use')
+            .action(async (globalName, serializerKey) => {
+            await initializeDreamApp();
+            const dreamApp = DreamApp.getOrFail();
+            const modelClass = dreamApp.models[globalName];
+            if (!modelClass)
+                throw new Error(`failed to locate model by global name: ${globalName}`);
+            modelClass['displaySerialization'](serializerKey);
+            process.exit();
+        });
     }
     /*
      * the default spawn provided by node:child_process is incompatible

package/dist/esm/src/db/migration-helpers/DreamMigrationHelpers.js

@@ -9,8 +9,9 @@ export default class DreamMigrationHelpers {
      *
      * @param db - The Kysely database object passed into the migration up/down function
      * @param constraintName - The name of the constraint to create
-     * @param opts.table - The name of the table
-     * @param opts.columns[] - The names of the columns to include in the constraint
+     * @param options - Configuration options
+     * @param options.table - The name of the table
+     * @param options.columns - The names of the columns to include in the constraint
      *
      */
     static async addDeferrableUniqueConstraint(db, constraintName, { table, columns, }) {
@@ -28,9 +29,9 @@ export default class DreamMigrationHelpers {
      * Note that this always includes "IF NOT EXISTS", so is safe to re-run multiple times.
      *
      * @param db - The Kysely database object passed into the migration up/down function
-     * @param opt.enumName - The name of the enum to modify
-     * @param opt.value - The name of the value to add to the enum
-     *
+     * @param __namedParameters - The options for adding the enum value
+     * @param __namedParameters.enumName - The name of the enum to modify
+     * @param __namedParameters.value - The name of the value to add to the enum
      */
     static async addEnumValue(db, { enumName, value }) {
         await sql `ALTER TYPE ${sql.raw(enumName)} ADD VALUE IF NOT EXISTS '${sql.raw(value)}';`.execute(db);
@@ -48,8 +49,9 @@ export default class DreamMigrationHelpers {
      *
      * @param db - The Kysely database object passed into the migration up/down function
      * @param extensionName - The name of the database extension to add
-     * @param opt.ifNotExists - Only add the extension if it doesn't already exist
-     * @param opt.publicSchema - Create using the public schema
+     * @param options - Configuration options
+     * @param options.ifNotExists - Only add the extension if it doesn't already exist
+     * @param options.publicSchema - Create using the public schema
      *
      */
     static async createExtension(db, extensionName, { ifNotExists = true, publicSchema = true } = {}) {
@@ -64,8 +66,9 @@ export default class DreamMigrationHelpers {
      *
      * @param db - The Kysely database object passed into the migration up/down function
      * @param indexName - The name of the constraint to create
-     * @param opts.table - The name of the table
-     * @param opts.column - The name of the column to index
+     * @param options - Configuration options
+     * @param options.table - The name of the table
+     * @param options.column - The name of the column to index
      *
      */
     static async createGinIndex(db, indexName, { table, column }) {
@@ -80,7 +83,8 @@ export default class DreamMigrationHelpers {
      *
      * @param db - The Kysely database object passed into the migration up/down function
      * @param constraintName - The name of the constraint to create
-     * @param opts.table - The name of the table
+     * @param options - Configuration options
+     * @param options.table - The name of the table
      *
      */
     static async dropConstraint(db, constraintName, { table }) {
@@ -92,10 +96,10 @@ export default class DreamMigrationHelpers {
      * Drop a value from an enum and replace it (or optionally remove it from array columns)
      *
      * @param db - The Kysely database object passed into the migration up/down function
-     * @param opt.enumName - The name of the enum to modify
-     * @param opt.value - The name of the value to drop from the enum
-     * @param opt.replacements[] - Details about which table and column to change and which value to replace the dropped value with (or remove it if the column is an array)
-     *
+     * @param __namedParameters - The options for dropping the enum value
+     * @param __namedParameters.enumName - The name of the enum to modify
+     * @param __namedParameters.value - The name of the value to drop from the enum
+     * @param __namedParameters.replacements - Details about which table and column to change and which value to replace the dropped value with (or remove it if the column is an array)
      */
     static async dropEnumValue(db, { enumName, value, replacements }) {
         // temporarily set all table columns depending on this enum to an acceptable alternate type

package/dist/esm/src/decorators/Decorators.js

@@ -159,7 +159,8 @@ export default class Decorators {
      * }
      * ```
      *
-     * @param scope - The column, association, or combination there-of which you would like to restrict the incrementing logic to
+     * @param opts - Configuration options for the sortable decorator
+     * @param opts.scope - The column, association, or combination thereof which you would like to restrict the incrementing logic to. Can be a single column name, a single belongs-to association name, or an array of column/association names
      * @returns A Sortable decorator
      */
     Sortable(opts) {