@rvoh/dream 0.44.9 → 0.45.1

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;
@@ -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();
     }

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;
+}