@rvoh/dream 0.44.8 → 0.45.0

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

@@ -11,11 +11,13 @@ import CannotPaginateWithLimit from '../errors/pagination/CannotPaginateWithLimi
 import CannotPaginateWithOffset from '../errors/pagination/CannotPaginateWithOffset.js';
 import RecordNotFound from '../errors/RecordNotFound.js';
 import cloneDeepSafe from '../helpers/cloneDeepSafe.js';
+import compact from '../helpers/compact.js';
 import isObject from '../helpers/isObject.js';
 import namespaceColumn from '../helpers/namespaceColumn.js';
 import protectAgainstPollutingAssignment from '../helpers/protectAgainstPollutingAssignment.js';
 import ops from '../ops/index.js';
 import computedPaginatePage from './internal/computedPaginatePage.js';
+import extractNestedPaths from './internal/extractNestedPaths.js';
 import PostgresQueryDriver from './QueryDriver/Postgres.js';
 export default class Query {
     /**
@@ -396,8 +398,8 @@ export default class Query {
      * ```
      *
      * @param cb - The callback to call for each found record
-     * @param options - Options for destroying the instance
-     * @param options.batchSize - The batch size you wish to collect records in. If not provided, it will default to 1000
+     * @param __namedParameters - Options for batch processing
+     * @param __namedParameters.batchSize - The batch size you wish to collect records in. If not provided, it will default to 1000
      * @returns void
      */
     async findEach(cb, { batchSize = Query.BATCH_SIZES.FIND_EACH } = {}) {
@@ -421,10 +423,10 @@ export default class Query {
     }
     /**
      * Load each specified association using a single SQL query.
-     * See {@link #preload} for preloading in separate queries.
+     * See {@link Query.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 Query.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.
@@ -452,7 +454,7 @@ export default class Query {
     }
     /**
      * Load each specified association using a separate SQL query.
-     * See {@link #leftJoinPreload} for preloading in a single query.
+     * See {@link Query.leftJoinPreload} for preloading in a single query.
      *
      * ```ts
      * const user = await User.query().preload('posts', 'comments', { visibilty: 'public' }, 'replies').first()
@@ -469,6 +471,141 @@ export default class Query {
         this.fleshOutJoinStatements([], preloadStatements, preloadOnStatements, null, [...args]);
         return this.clone({ preloadStatements, preloadOnStatements: preloadOnStatements });
     }
+    /**
+     * 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
+     */
+    preloadForSerialization({ serializerKey, modifierFn, } = {}) {
+        const preloadArgs = extractNestedPaths(this.dreamClass['serializationMap'](serializerKey));
+        let query = this;
+        preloadArgs.forEach(dreamClassAndAssociationNameTupleArray => {
+            query = query.preload(...this.convertDreamClassAndAssociationNameTupleArrayToPreloadArgs(dreamClassAndAssociationNameTupleArray, modifierFn));
+        });
+        return query;
+    }
+    /**
+     * 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
+     */
+    leftJoinPreloadForSerialization({ serializerKey, modifierFn, } = {}) {
+        const preloadArgs = extractNestedPaths(this.dreamClass['serializationMap'](serializerKey));
+        let query = this;
+        const counter = { count: 0 };
+        preloadArgs.forEach(dreamClassAndAssociationNameTupleArray => {
+            query = query.leftJoinPreload(...this.convertDreamClassAndAssociationNameTupleArrayToPreloadArgs(dreamClassAndAssociationNameTupleArray, modifierFn, counter));
+        });
+        return query;
+    }
+    convertDreamClassAndAssociationNameTupleArrayToPreloadArgs(dreamClassAndAssociationNameTupleArray, modifierFn, counter) {
+        return compact(dreamClassAndAssociationNameTupleArray.flatMap(dreamClassAndAssociationNameTuple => {
+            const associationName = dreamClassAndAssociationNameTuple[1];
+            const aliasedAssociationName = counter
+                ? `${dreamClassAndAssociationNameTuple[1]} as drsz${counter.count++}`
+                : dreamClassAndAssociationNameTuple[1];
+            if (!modifierFn)
+                return aliasedAssociationName;
+            const modifier = modifierFn(dreamClassAndAssociationNameTuple[0], associationName);
+            if (modifier === 'omit')
+                return undefined;
+            return [aliasedAssociationName, modifier];
+        }));
+    }
     /**
      * Returns a new Query instance, with the provided
      * joins statement attached
@@ -783,7 +920,7 @@ export default class Query {
      * // [User{name: 'a', id: 99}, User{name: 'a', id: 97}, User{ name: 'b', id: 98 } ...]
      * ```
      *
-     * @param orderStatement - Either a string or an object specifying order. If a string, the order is implicitly ascending. If the orderStatement is an object, statements will be provided in the order of the keys set in the object
+     * @param arg - Either a string or an object specifying order. If a string, the order is implicitly ascending. If the orderStatement is an object, statements will be provided in the order of the keys set in the object
      * @returns A cloned Query with the order clause applied
      */
     order(arg) {
@@ -885,7 +1022,7 @@ export default class Query {
      * })
      * ```
      *
-     * @param txn - A DreamTransaction instance (usually collected by calling `ApplicationModel.transaction`)
+     * @param dreamTransaction - A DreamTransaction instance (usually collected by calling `ApplicationModel.transaction`)
      * @returns A cloned Query with the transaction applied
      *
      */
@@ -1082,6 +1219,7 @@ export default class Query {
      * // 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
@@ -1245,11 +1383,11 @@ export default class Query {
      * // 12
      * ```
      *
-     * @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
+     * @param __namedParameters - Options for destroying the instance
+     * @param __namedParameters.skipHooks - If true, skips applying model hooks during the destroy operation. Defaults to false
+     * @param __namedParameters.cascade - If false, skips destroying associations marked `dependent: 'destroy'`. Defaults to true
+     * @param __namedParameters.bypassAllDefaultScopes - If true, bypasses all default scopes when cascade destroying. Defaults to false
+     * @param __namedParameters.defaultScopesToBypass - An array of default scope names to bypass when cascade destroying. Defaults to an empty array
      * @returns The number of records that were removed
      */
     async destroy({ skipHooks, cascade, } = {}) {
@@ -1285,18 +1423,18 @@ export default class Query {
      * were destroyed.
      *
      * To destroy without bypassing the SoftDelete
-     * decorator, use {@link Query.(destroy:instance) | destroy} instead.
+     * decorator, use {@link Query.destroy} instead.
      *
      * ```ts
      * await User.where({ email: ops.ilike('%burpcollaborator%') }).reallyDestroy()
      * // 12
      * ```
      *
-     * @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
+     * @param __namedParameters - Options for destroying the instance
+     * @param __namedParameters.skipHooks - If true, skips applying model hooks during the destroy operation. Defaults to false
+     * @param __namedParameters.cascade - If false, skips destroying associations marked `dependent: 'destroy'`. Defaults to true
+     * @param __namedParameters.bypassAllDefaultScopes - If true, bypasses all default scopes when cascade destroying. Defaults to false
+     * @param __namedParameters.defaultScopesToBypass - An array of default scope names to bypass when cascade destroying. Defaults to an empty array
      * @returns The number of records that were removed
      */
     async reallyDestroy({ skipHooks, cascade, } = {}) {
@@ -1314,11 +1452,11 @@ export default class Query {
      * // 12
      * ```
      *
-     * @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
+     * @param __namedParameters - Options for undestroying the instance
+     * @param __namedParameters.skipHooks - If true, skips applying model hooks during the undestroy operation. Defaults to false
+     * @param __namedParameters.cascade - If false, skips undestroying associations marked `dependent: 'destroy'`. Defaults to true
+     * @param __namedParameters.bypassAllDefaultScopes - If true, bypasses all default scopes when cascade undestroying. Defaults to false
+     * @param __namedParameters.defaultScopesToBypass - An array of default scope names to bypass when cascade undestroying (soft delete is always bypassed). Defaults to an empty array
      * @returns The number of records that were removed
      */
     async undestroy({ cascade, skipHooks, } = {}) {
@@ -1346,7 +1484,7 @@ export default class Query {
      * though cascading may still happen at the database level.
      *
      * To apply model hooks and association dependent destroy,
-     * use {@link Query.(destroy:instance) | destroy} instead.
+     * use {@link Query.destroy} instead.
      *
      * ```ts
      * await User.where({ email: ops.ilike('%burpcollaborator%').delete() })

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

@@ -0,0 +1,34 @@
+/**
+ * Turns RecursiveSerializerInfo into an array of arrays of tuples,
+ * each tuple including a Dream class and an association name
+ *
+ * E.g., returns the following:
+ * ```ts
+ * [
+ *   [[Post, 'a'], [Pet, 'b']],
+ *   [[Post, 'a'], [Balloon, 'd'], [BalloonLine, 'e']]
+ * ]
+ * ```
+ */
+export default function extractNestedPaths(obj) {
+    const paths = [];
+    function traverse(current, currentPath) {
+        const associationNames = Object.keys(current);
+        if (associationNames.length === 0) {
+            paths.push([...currentPath]);
+            return;
+        }
+        for (const associationName of associationNames) {
+            const serializerInfo = current[associationName];
+            if (serializerInfo === undefined)
+                throw new Error('shouldn’t be undefined');
+            const dreamClass = serializerInfo.parentDreamClass;
+            const nestedSerializerInfo = serializerInfo.nestedSerializerInfo;
+            const tuple = [dreamClass, associationName];
+            const newPath = [...currentPath, tuple];
+            traverse(nestedSerializerInfo, newPath);
+        }
+    }
+    traverse(obj, []);
+    return paths;
+}

package/dist/esm/src/helpers/indent.js

@@ -0,0 +1,15 @@
+export function indent(number, { tabWidth = 2 } = {}) {
+    let spacesString = '';
+    const indentationUnit = indentationUnitString(tabWidth);
+    for (let i = 0; i < number; i++) {
+        spacesString += indentationUnit;
+    }
+    return spacesString;
+}
+function indentationUnitString(number) {
+    let spacesString = '';
+    for (let i = 0; i < number; i++) {
+        spacesString += ' ';
+    }
+    return spacesString;
+}

package/dist/esm/src/serializer/SerializerRenderer.js

@@ -6,7 +6,8 @@ import round from '../helpers/round.js';
 import snakeify from '../helpers/snakeify.js';
 import DreamSerializerBuilder from './builders/DreamSerializerBuilder.js';
 import ObjectSerializerBuilder from './builders/ObjectSerializerBuilder.js';
-import inferSerializerFromDreamOrViewModel, { inferSerializersFromDreamClassOrViewModelClass, } from './helpers/inferSerializerFromDreamOrViewModel.js';
+import inferSerializerFromDreamOrViewModel from './helpers/inferSerializerFromDreamOrViewModel.js';
+import { serializerForAssociatedClass } from './helpers/serializerForAssociatedClass.js';
 export default class SerializerRenderer {
     serializerBuilder;
     passthroughData;
@@ -51,7 +52,7 @@ export default class SerializerRenderer {
                 case 'delegatedAttribute': {
                     const outputAttributeName = this.setCase(attribute.options?.as ?? attribute.name);
                     const target = data[attribute.targetName];
-                    const value = target[attribute.name] ?? attribute.options?.default;
+                    const value = target?.[attribute.name] ?? attribute.options?.default;
                     accumulator[outputAttributeName] = applyRenderingOptionsToAttribute(value, attribute.options, this.passthroughData, this.renderOpts);
                     return accumulator;
                 }
@@ -201,19 +202,3 @@ function serializerForAssociatedObject(associatedObject, options) {
         return options.serializer;
     return inferSerializerFromDreamOrViewModel(associatedObject, options.serializerKey);
 }
-/**
- * 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
- */
-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/esm/src/serializer/builders/DreamSerializerBuilder.js

@@ -20,15 +20,74 @@ export default class DreamSerializerBuilder {
         });
         return this;
     }
+    /**
+     * Includes an attribute from a nested object in the serialized output.
+     *
+     * Serializes an attribute from a target object. 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 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('user', 'displayName', {
+     *   openapi: { type: 'string' },
+     *   default: 'Unknown 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('initials', () =>
+     *   `${user.firstName?.[0]}${user.lastName?.[0]}`.toUpperCase(),
+     *   { openapi: { type: 'string' } }
+     * )
+     *
+     * // Flattened object properties
+     * .customAttribute('metadata', () => ({ age: 30, city: 'NYC' }), {
+     *   flatten: true,
+     *   openapi: {
+     *     age: { type: 'integer' },
+     *     city: { type: 'string' }
+     *   }
+     * })
+     * ```
+     *
+     * See: {@link https://your-docs-url.com/docs/serializers/attributes | Serializer Attributes Documentation}
+     */
     customAttribute(name, fn, options) {
         this.attributes.push({
             type: 'customAttribute',
@@ -38,22 +97,99 @@ export default class DreamSerializerBuilder {
         });
         return this;
     }
+    /**
+     * Includes a single associated object in the serialized output.
+     *
+     * When rendering a Dream association, the OpenAPI shape is automatically
+     * inferred from that associated Dream's serializer.
+     *
+     * @param name - The association property name
+     * @param options - Configuration options for serialization and schema definition
+     * @returns The serializer builder for method chaining
+     *
+     * @example
+     * ```typescript
+     * // DreamSerializer with inference
+     * .rendersOne('user') // Infers from Dream association
+     *
+     * // With specific serializer
+     * .rendersOne('user', { serializerKey: 'summary' })
+     *
+     * // ObjectSerializer (explicit configuration required)
+     * .rendersOne('owner', UserSerializer, {
+     *   openapi: { $ref: '#/components/schemas/User' }
+     * })
+     * ```
+     *
+     * 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.
+     *
+     * When rendering a Dream association, the OpenAPI shape is automatically
+     * inferred from that associated Dream's serializer.
+     *
+     * @param name - The association property name (should be an array)
+     * @param options - Configuration options for serialization and schema definition
+     * @returns The serializer builder for method chaining
+     *
+     * @example
+     * ```typescript
+     * // DreamSerializer with inference
+     * .rendersMany('posts') // Infers from Dream association
+     *
+     * // With specific serializer
+     * .rendersMany('posts', { serializerKey: 'summary' })
+     *
+     * // ObjectSerializer (explicit configuration required)
+     * .rendersMany('articles', ArticleSerializer, {
+     *   openapi: {
+     *     type: 'array',
+     *     items: { $ref: '#/components/schemas/Article' }
+     *   }
+     * })
+     * ```
+     *
+     * 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 = UserSerializer(user).render()
+     * // Returns: { id: 1, email: 'user@example.com', ... }
+     *
+     * // With passthrough data
+     * const result = UserSerializer(user).render({ currentUserId: 123 })
+     * ```
+     *
+     * See: {@link https://your-docs-url.com/docs/serializers/render | Serializer Rendering Documentation}
+     */
     render(passthrough = {}, opts = {}) {
         return new SerializerRenderer(this, passthrough, opts).render();
     }