@rvoh/dream 2.5.6 → 2.5.8

package/dist/types/src/serializer/builders/ObjectSerializerBuilder.d.ts

@@ -14,7 +14,15 @@ export default class ObjectSerializerBuilder<MaybeNullDataType extends object |
      * 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
+     * @param options - Configuration options:
+     *   - `openapi` - (required) OpenAPI schema definition for the attribute
+     *   - `as` - Rename the attribute key in the serialized output and OpenAPI shape
+     *   - `default` - Value to use when the attribute is undefined
+     *   - `precision` - Round decimal values to the specified number of decimal places (0–9)
+     *     during rendering; does not affect the OpenAPI shape
+     *   - `required` - Set to `false` to mark the attribute as optional in the OpenAPI schema;
+     *     when omitted, attributes are required by default, meaning `undefined` values will
+     *     serialize as `null`
      * @returns The serializer builder for method chaining
      *
      * @example
@@ -35,21 +43,40 @@ export default class ObjectSerializerBuilder<MaybeNullDataType extends object |
      *   openapi: { type: 'string' },
      *   as: 'userEmail'
      * })
-     * ```
      *
-     * See: {@link https://your-docs-url.com/docs/serializers/attributes | Serializer Attributes Documentation}
+     * // Round decimal to 2 places
+     * .attribute('price', {
+     *   openapi: 'decimal',
+     *   precision: 2
+     * })
+     *
+     * // Mark as optional in OpenAPI (omitted from response when undefined)
+     * .attribute('nickname', {
+     *   openapi: 'string',
+     *   required: false
+     * })
+     * ```
      */
     attribute<AttributeName extends keyof DataType & string>(name: AttributeName, options: NonAutomaticSerializerAttributeOptionsWithPossibleDecimalRenderOption): 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.
+     * Accesses `targetName.name` on the data object. 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
+     * @param options - Configuration options:
+     *   - `openapi` - (required) OpenAPI schema definition for the attribute
+     *   - `as` - Rename the attribute key in the serialized output and OpenAPI shape
+     *     (e.g., delegating `'profile', 'avatarUrl'` with `as: 'avatar'` outputs the value
+     *     under `avatar`)
+     *   - `default` - Value to use when the target object or its attribute is null/undefined
+     *   - `precision` - Round decimal values to the specified number of decimal places (0–9)
+     *     during rendering; does not affect the OpenAPI shape
+     *   - `required` - Set to `false` to mark the attribute as optional in the OpenAPI schema;
+     *     when omitted, attributes are required by default
      * @returns The serializer builder for method chaining
      *
      * @example
@@ -64,9 +91,13 @@ export default class ObjectSerializerBuilder<MaybeNullDataType extends object |
      *   openapi: { type: 'string' },
      *   default: 'Anonymous User'
      * })
-     * ```
      *
-     * See: {@link https://your-docs-url.com/docs/serializers/attributes | Serializer Attributes Documentation}
+     * // Rename the output key
+     * .delegatedAttribute('profile', 'avatarUrl', {
+     *   openapi: 'string',
+     *   as: 'avatar'
+     * })
+     * ```
      */
     delegatedAttribute<ProvidedModelType = undefined, ProvidedAttributeName extends ProvidedModelType extends undefined ? undefined : Exclude<keyof ProvidedModelType, keyof Dream> = ProvidedModelType extends undefined ? undefined : Exclude<keyof ProvidedModelType, keyof Dream>, ActualDataType extends ProvidedModelType extends undefined ? DataType : ProvidedModelType = ProvidedModelType extends undefined ? DataType : ProvidedModelType, TargetName extends ProvidedAttributeName extends undefined ? Exclude<keyof ActualDataType, keyof Dream> : ProvidedAttributeName & keyof ActualDataType = ProvidedAttributeName extends undefined ? Exclude<keyof ActualDataType, keyof Dream> : ProvidedAttributeName & keyof ActualDataType, TargetObject extends ActualDataType[TargetName] = ActualDataType[TargetName], AttributeName extends TargetObject extends object ? Exclude<keyof TargetObject, keyof Dream> & string : never = TargetObject extends object ? Exclude<keyof TargetObject, keyof Dream> & string : never>(targetName: TargetName, name: AttributeName, options: NonAutomaticSerializerAttributeOptionsWithPossibleDecimalRenderOption): this;
     /**
@@ -75,9 +106,19 @@ export default class ObjectSerializerBuilder<MaybeNullDataType extends object |
      * Executes a callback function to generate a custom attribute value.
      * The `openapi` option is always required since the return type cannot be inferred.
      *
+     * Unlike DreamSerializerBuilder's `customAttribute`, this version does not support `as`
+     * or `precision`.
+     *
      * @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
+     * @param options - Configuration options:
+     *   - `openapi` - (required) OpenAPI schema definition for the computed value
+     *   - `default` - Value to use when the callback returns undefined
+     *   - `flatten` - When `true`, spreads the returned object's properties directly into the
+     *     parent serialized output instead of nesting them under `name`; the `openapi` option
+     *     should then define each flattened property individually
+     *   - `required` - Set to `false` to mark the attribute as optional in the OpenAPI schema;
+     *     when omitted, attributes are required by default
      * @returns The serializer builder for method chaining
      *
      * @example
@@ -97,8 +138,6 @@ export default class ObjectSerializerBuilder<MaybeNullDataType extends object |
      *   }
      * })
      * ```
-     *
-     * See: {@link https://your-docs-url.com/docs/serializers/attributes | Serializer Attributes Documentation}
      */
     customAttribute(name: string, fn: () => unknown, options: Omit<NonAutomaticSerializerAttributeOptions, 'as'> & {
         flatten?: boolean;
@@ -110,25 +149,47 @@ export default class ObjectSerializerBuilder<MaybeNullDataType extends object |
      * 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
+     * @param options - Configuration options:
+     *   - `as` - Rename the association key in the serialized output
+     *   - `flatten` - When `true`, spreads the rendered association's attributes directly into
+     *     the parent serialized output instead of nesting them under `name`. Be aware of
+     *     attribute shadowing: if the parent and flattened association share attribute names
+     *     (e.g., `id`), the flattened association's values overwrite the parent's
+     *   - `optional` - When `true`, allows the association to be null/missing without causing
+     *     an `OpenapiResponseValidationFailure` during Psychic controller unit specs. By default,
+     *     `rendersOne` expects the association to be present (mirroring the `optional` option on
+     *     `@deco.BelongsTo`). Set this to `true` when the association is genuinely nullable
+     *
+     *   For Dream associations:
+     *   - `dreamClass` - The Dream model class, enabling serializer inference; when specified,
+     *     `serializerKey` may also be provided to select a specific registered serializer
+     *   - `serializer` - Provide an explicit serializer function
+     *
+     *   For ViewModel associations:
+     *   - `viewModelClass` + optional `serializerKey`
+     *   - `serializer`
+     *
+     *   For non-Dream/non-ViewModel associations:
+     *   - `serializer` is required
      * @returns The serializer builder for method chaining
      *
      * @example
      * ```typescript
      * // With explicit serializer function
-     * .rendersOne('owner', UserSerializer, {
-     *   openapi: { $ref: '#/components/schemas/User' }
-     * })
+     * .rendersOne('owner', { serializer: CustomOwnerSerializer })
      *
-     * // With Dream class reference
+     * // With Dream class reference and serializer key
      * .rendersOne('creator', {
      *   dreamClass: User,
-     *   serializerKey: 'summary',
-     *   openapi: { $ref: '#/components/schemas/UserSummary' }
+     *   serializerKey: 'summary'
      * })
-     * ```
      *
-     * See: {@link https://your-docs-url.com/docs/serializers/associations | Serializer Associations Documentation}
+     * // Allow null association
+     * .rendersOne('approver', { serializer: UserSerializer, optional: true })
+     *
+     * // Flatten into parent object
+     * .rendersOne('profile', { serializer: ProfileSerializer, flatten: true })
+     * ```
      */
     rendersOne<ProvidedModelType = undefined, ProvidedAttributeName extends ProvidedModelType extends undefined ? undefined : keyof ProvidedModelType = ProvidedModelType extends undefined ? undefined : keyof ProvidedModelType, ActualDataType extends ProvidedModelType extends undefined ? DataType : ProvidedModelType = ProvidedModelType extends undefined ? DataType : ProvidedModelType, AttributeName extends ProvidedAttributeName extends undefined ? keyof ActualDataType : ProvidedAttributeName & keyof ActualDataType = ProvidedAttributeName extends undefined ? keyof ActualDataType : ProvidedAttributeName & keyof ActualDataType, AssociatedModelType = Exclude<ActualDataType[AttributeName], null>, SerializerOptions = AssociatedModelType extends Dream ? {
         dreamClass: typeof Dream;
@@ -143,8 +204,20 @@ export default class ObjectSerializerBuilder<MaybeNullDataType extends object |
     } : {
         serializer: SerializerType;
     }>(name: AttributeName, options: {
+        /**
+         * Rename the association key in the serialized output.
+         */
         as?: string;
+        /**
+         * If `true`, the rendered association's attributes are merged directly into
+         * the parent object instead of being nested under the association key.
+         */
         flatten?: boolean;
+        /**
+         * If `true`, the association is treated as nullable in the OpenAPI spec,
+         * allowing `null` when the association doesn't resolve. Set this for
+         * associations that may not exist.
+         */
         optional?: boolean;
     } & SerializerOptions): this;
     /**
@@ -153,32 +226,43 @@ export default class ObjectSerializerBuilder<MaybeNullDataType extends object |
      * 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
+     * @param name - The association property name (should resolve to an array)
+     * @param options - Configuration options:
+     *   - `as` - Rename the association key in the serialized output
+     *
+     *   For Dream associations:
+     *   - `dreamClass` - The Dream model class, enabling serializer inference; when specified,
+     *     `serializerKey` may also be provided to select a specific registered serializer
+     *   - `serializer` - Provide an explicit serializer function
+     *
+     *   For ViewModel associations:
+     *   - `viewModelClass` + optional `serializerKey`
+     *   - `serializer`
+     *
+     *   For non-Dream/non-ViewModel associations:
+     *   - `serializer` is required
      * @returns The serializer builder for method chaining
      *
      * @example
      * ```typescript
      * // With explicit serializer function
-     * .rendersMany('articles', ArticleSerializer, {
-     *   openapi: {
-     *     type: 'array',
-     *     items: { $ref: '#/components/schemas/Article' }
-     *   }
+     * .rendersMany('articles', { serializer: ArticleSerializer })
+     *
+     * // With Dream class reference and serializer key
+     * .rendersMany('posts', {
+     *   dreamClass: Post,
+     *   serializerKey: 'summary'
      * })
      *
      * // With ViewModel class reference
      * .rendersMany('comments', {
      *   viewModelClass: CommentViewModel,
-     *   serializer: CommentViewModelSerializer,
-     *   openapi: {
-     *     type: 'array',
-     *     items: { $ref: '#/components/schemas/Comment' }
-     *   }
+     *   serializer: CommentViewModelSerializer
      * })
-     * ```
      *
-     * See: {@link https://your-docs-url.com/docs/serializers/associations | Serializer Associations Documentation}
+     * // Rename output key
+     * .rendersMany('articles', { serializer: ArticleSerializer, as: 'posts' })
+     * ```
      */
     rendersMany<ProvidedModelType = undefined, ProvidedAttributeName extends ProvidedModelType extends undefined ? undefined : Exclude<keyof ProvidedModelType, keyof Dream> = ProvidedModelType extends undefined ? undefined : Exclude<keyof ProvidedModelType, keyof Dream>, ActualDataType extends ProvidedModelType extends undefined ? DataType : ProvidedModelType = ProvidedModelType extends undefined ? DataType : ProvidedModelType, AttributeName extends ProvidedAttributeName extends undefined ? Exclude<keyof ActualDataType, keyof Dream> : ProvidedAttributeName & keyof ActualDataType = ProvidedAttributeName extends undefined ? Exclude<keyof ActualDataType, keyof Dream> : ProvidedAttributeName & keyof ActualDataType, AssociatedModelType = ActualDataType[AttributeName] extends (Dream | ViewModel)[] ? ActualDataType[AttributeName] extends (infer U)[] ? U : object : object, SerializerOptions = AssociatedModelType extends Dream ? {
         dreamClass: typeof Dream;
@@ -198,13 +282,13 @@ export default class ObjectSerializerBuilder<MaybeNullDataType extends object |
     /**
      * 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.
+     * Processes all defined attributes, custom attributes, delegated attributes,
+     * and associations to produce the final serialized object.
      *
      * @param passthrough - Additional data to pass through to nested serializers
+     *   (e.g., locale, current user context)
      * @param opts - Rendering options for customizing the serialization process
-     * @returns The serialized object
+     * @returns The serialized object, suitable for JSON responses
      *
      * @example
      * ```typescript
@@ -214,8 +298,6 @@ export default class ObjectSerializerBuilder<MaybeNullDataType extends object |
      * // 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?: any, opts?: SerializerRendererOpts): Record<string, any> | null;
 }

package/dist/types/src/types/associations/belongsTo.d.ts

@@ -19,15 +19,49 @@ export interface BelongsToStatement<BaseInstance extends Dream, DB, Schema, Tabl
     withoutDefaultScopes?: DefaultScopeName<BaseInstance>[];
 }
 export interface NonPolymorphicBelongsToOptions<BaseInstance extends Dream, AssociationGlobalNameOrNames extends GlobalModelNames<BaseInstance> | readonly GlobalModelNames<BaseInstance>[], AssociationGlobalName = AssociationGlobalNameOrNames extends Readonly<any[]> ? AssociationGlobalNameOrNames[0] & string : AssociationGlobalNameOrNames & string, AssociationTableName extends AssociationTableNames<BaseInstance['DB'], BaseInstance['schema']> & keyof BaseInstance['DB'] = TableNameForGlobalModelName<BaseInstance, AssociationGlobalName & GlobalModelNames<BaseInstance>> & AssociationTableNames<BaseInstance['DB'], BaseInstance['schema']> & keyof BaseInstance['DB']> {
+    /**
+     * A custom column name on this model to use as the foreign key for this association,
+     * overriding the default convention-based foreign key.
+     */
     on?: DreamColumnNames<BaseInstance>;
+    /**
+     * A custom column on the associated model to use as the primary key for this association,
+     * instead of the default primary key (e.g., `'uuid'` instead of `'id'`).
+     */
     primaryKeyOverride?: TableColumnNames<BaseInstance['DB'], AssociationTableName> | null;
+    /**
+     * Whether or not this association is optional. Defaults to `false`.
+     * When `false`, a validation is added requiring the foreign key to be present.
+     */
     optional?: boolean;
+    /**
+     * A list of default scopes to bypass when loading this association.
+     */
     withoutDefaultScopes?: DefaultScopeNameForTable<BaseInstance['schema'], AssociationTableName>[];
 }
 export interface PolymorphicBelongsToOptions<BaseInstance extends Dream, AssociationGlobalNameOrNames extends GlobalModelNames<BaseInstance> | readonly GlobalModelNames<BaseInstance>[], AssociationGlobalName = AssociationGlobalNameOrNames extends Readonly<any[]> ? AssociationGlobalNameOrNames[0] & string : AssociationGlobalNameOrNames & string, AssociationTableName extends AssociationTableNames<BaseInstance['DB'], BaseInstance['schema']> & keyof BaseInstance['DB'] = TableNameForGlobalModelName<BaseInstance, AssociationGlobalName & GlobalModelNames<BaseInstance>> & AssociationTableNames<BaseInstance['DB'], BaseInstance['schema']> & keyof BaseInstance['DB']> {
+    /**
+     * A custom column name on this model to use as the foreign key for this association.
+     * Required for polymorphic BelongsTo associations.
+     */
     on: DreamColumnNames<BaseInstance>;
+    /**
+     * A custom column on the associated model to use as the primary key for this association,
+     * instead of the default primary key (e.g., `'uuid'` instead of `'id'`).
+     */
     primaryKeyOverride?: TableColumnNames<BaseInstance['DB'], AssociationTableName> | null;
+    /**
+     * Whether or not this association is optional. Defaults to `false`.
+     * When `false`, a validation is added requiring the foreign key to be present.
+     */
     optional?: boolean;
+    /**
+     * Marks this as a polymorphic association, where the foreign key and a type column
+     * together identify the associated record across multiple tables.
+     */
     polymorphic: boolean;
+    /**
+     * A list of default scopes to bypass when loading this association.
+     */
     withoutDefaultScopes?: DefaultScopeNameForTable<BaseInstance['schema'], AssociationTableName>[];
 }

package/dist/types/src/types/associations/belongsTo.ts

@@ -49,9 +49,27 @@ export interface NonPolymorphicBelongsToOptions<
     AssociationTableNames<BaseInstance['DB'], BaseInstance['schema']> &
     keyof BaseInstance['DB'],
 > {
+  /**
+   * A custom column name on this model to use as the foreign key for this association,
+   * overriding the default convention-based foreign key.
+   */
   on?: DreamColumnNames<BaseInstance>
+
+  /**
+   * A custom column on the associated model to use as the primary key for this association,
+   * instead of the default primary key (e.g., `'uuid'` instead of `'id'`).
+   */
   primaryKeyOverride?: TableColumnNames<BaseInstance['DB'], AssociationTableName> | null
+
+  /**
+   * Whether or not this association is optional. Defaults to `false`.
+   * When `false`, a validation is added requiring the foreign key to be present.
+   */
   optional?: boolean
+
+  /**
+   * A list of default scopes to bypass when loading this association.
+   */
   withoutDefaultScopes?: DefaultScopeNameForTable<BaseInstance['schema'], AssociationTableName>[]
 }
 
@@ -71,9 +89,32 @@ export interface PolymorphicBelongsToOptions<
     AssociationTableNames<BaseInstance['DB'], BaseInstance['schema']> &
     keyof BaseInstance['DB'],
 > {
+  /**
+   * A custom column name on this model to use as the foreign key for this association.
+   * Required for polymorphic BelongsTo associations.
+   */
   on: DreamColumnNames<BaseInstance>
+
+  /**
+   * A custom column on the associated model to use as the primary key for this association,
+   * instead of the default primary key (e.g., `'uuid'` instead of `'id'`).
+   */
   primaryKeyOverride?: TableColumnNames<BaseInstance['DB'], AssociationTableName> | null
+
+  /**
+   * Whether or not this association is optional. Defaults to `false`.
+   * When `false`, a validation is added requiring the foreign key to be present.
+   */
   optional?: boolean
+
+  /**
+   * Marks this as a polymorphic association, where the foreign key and a type column
+   * together identify the associated record across multiple tables.
+   */
   polymorphic: boolean
+
+  /**
+   * A list of default scopes to bypass when loading this association.
+   */
   withoutDefaultScopes?: DefaultScopeNameForTable<BaseInstance['schema'], AssociationTableName>[]
 }

package/dist/types/src/types/associations/hasMany.d.ts

@@ -7,7 +7,25 @@ export type HasManyStatement<BaseInstance extends Dream, DB, Schema, ForeignTabl
     order?: OrderStatement<DB, Schema, ForeignTableName>;
 };
 interface HasManyOnlyOptions<BaseInstance extends Dream, AssociationGlobalNameOrNames extends GlobalModelNames<BaseInstance> | readonly GlobalModelNames<BaseInstance>[], AssociationGlobalName = AssociationGlobalNameOrNames extends any[] ? AssociationGlobalNameOrNames[0] & string : AssociationGlobalNameOrNames & string, AssociationTableName = TableNameForGlobalModelName<BaseInstance, AssociationGlobalName & GlobalModelNames<BaseInstance>>> {
+    /**
+     * Applies a DISTINCT clause to this association. If a column name is provided, the distinct
+     * clause is applied to that column. If `true`, the distinct clause is applied to the primary key.
+     *
+     * ```ts
+     * @deco.HasMany('Collar', { distinct: 'tagName' })
+     * public uniqueCollars: Collar[]
+     * ```
+     */
     distinct?: TableColumnNames<BaseInstance['DB'], AssociationTableName & AssociationTableNames<BaseInstance['DB'], BaseInstance['schema']> & keyof BaseInstance['DB']> | boolean;
+    /**
+     * A custom order to apply when loading this association. Can be a single order statement
+     * or an array of order statements.
+     *
+     * ```ts
+     * @deco.HasMany('Post', { order: { createdAt: 'desc' } })
+     * public recentPosts: Post[]
+     * ```
+     */
     order?: OrderStatement<BaseInstance['DB'], BaseInstance['schema'], AssociationTableName & AssociationTableNames<BaseInstance['DB'], BaseInstance['schema']> & keyof BaseInstance['DB']> | OrderStatement<BaseInstance['DB'], BaseInstance['schema'], AssociationTableName & AssociationTableNames<BaseInstance['DB'], BaseInstance['schema']> & keyof BaseInstance['DB']>[];
 }
 export type HasManyOptions<BaseInstance extends Dream, AssociationGlobalName extends keyof GlobalModelNameTableMap<BaseInstance>, ThroughAssociationName extends keyof BaseInstance['schema'][BaseInstance['table']]['associations']> = HasOptions<BaseInstance, AssociationGlobalName, ThroughAssociationName> & HasManyOnlyOptions<BaseInstance, AssociationGlobalName>;

package/dist/types/src/types/associations/hasMany.ts

@@ -36,6 +36,15 @@ interface HasManyOnlyOptions<
     AssociationGlobalName & GlobalModelNames<BaseInstance>
   >,
 > {
+  /**
+   * Applies a DISTINCT clause to this association. If a column name is provided, the distinct
+   * clause is applied to that column. If `true`, the distinct clause is applied to the primary key.
+   *
+   * ```ts
+   * @deco.HasMany('Collar', { distinct: 'tagName' })
+   * public uniqueCollars: Collar[]
+   * ```
+   */
   distinct?:
     | TableColumnNames<
         BaseInstance['DB'],
@@ -45,6 +54,15 @@ interface HasManyOnlyOptions<
       >
     | boolean
 
+  /**
+   * A custom order to apply when loading this association. Can be a single order statement
+   * or an array of order statements.
+   *
+   * ```ts
+   * @deco.HasMany('Post', { order: { createdAt: 'desc' } })
+   * public recentPosts: Post[]
+   * ```
+   */
   order?:
     | OrderStatement<
         BaseInstance['DB'],

package/dist/types/src/types/associations/shared.d.ts

@@ -75,17 +75,88 @@ export interface HasStatement<BaseInstance extends Dream, DB, Schema, ForeignTab
     withoutDefaultScopes?: DefaultScopeName<BaseInstance>[];
 }
 interface HasOptionsBase<BaseInstance extends Dream, AssociationGlobalName extends keyof GlobalModelNameTableMap<BaseInstance>, ThroughAssociationName extends keyof BaseInstance['schema'][BaseInstance['table']]['associations'], ForeignTableName extends BaseInstance['schema'][BaseInstance['table']]['associations'][ThroughAssociationName]['tables'][number] = BaseInstance['schema'][BaseInstance['table']]['associations'][ThroughAssociationName]['tables'][number], AssociationTableName = TableNameForGlobalModelName<BaseInstance, AssociationGlobalName & keyof GlobalModelNameTableMap<BaseInstance>>> {
+    /**
+     * If `'destroy'`, associated records will be cascade-deleted when the base model is destroyed.
+     */
     dependent?: DependentOptions;
+    /**
+     * A custom column on the associated model to use as the foreign key for this association,
+     * overriding the default convention-based foreign key.
+     */
     on?: TableColumnNames<BaseInstance['DB'], AssociationTableName & keyof BaseInstance['DB']>;
+    /**
+     * A where clause applied whenever this association is loaded, scoping the association
+     * to only records matching the given conditions.
+     *
+     * ```ts
+     * @deco.HasMany('Collar', { and: { lost: false } })
+     * public currentCollars: Collar[]
+     * ```
+     */
     and?: OnStatementForAssociationDefinition<BaseInstance['DB'], BaseInstance['schema'], AssociationTableName & AssociationTableNames<BaseInstance['DB'], BaseInstance['schema']> & keyof BaseInstance['DB']>;
+    /**
+     * A negated where clause applied whenever this association is loaded, excluding
+     * records matching the given conditions.
+     *
+     * ```ts
+     * @deco.HasOne('Collar', { andNot: { lost: true } })
+     * public notLostCollar: Collar
+     * ```
+     */
     andNot?: InternalWhereStatement<BaseInstance, BaseInstance['DB'], BaseInstance['schema'], AssociationTableName & AssociationTableNames<BaseInstance['DB'], BaseInstance['schema']> & keyof BaseInstance['DB']>;
+    /**
+     * An array of where clauses combined with OR logic, applied whenever this association
+     * is loaded. At least one of the clauses must match.
+     *
+     * ```ts
+     * @deco.HasMany('Balloon', { andAny: [{ color: 'red' }, { color: 'blue' }] })
+     * public redOrBlueBalloons: Balloon[]
+     * ```
+     */
     andAny?: InternalWhereStatement<BaseInstance, BaseInstance['DB'], BaseInstance['schema'], AssociationTableName & AssociationTableNames<BaseInstance['DB'], BaseInstance['schema']> & keyof BaseInstance['DB']>[];
+    /**
+     * Marks this as a polymorphic association, where the foreign key and a type column
+     * together identify the associated record across multiple tables.
+     */
     polymorphic?: boolean;
+    /**
+     * A custom column on this model to use as the primary key for this association,
+     * instead of the default primary key (e.g., `'uuid'` instead of `'id'`).
+     */
     primaryKeyOverride?: DreamColumnNames<BaseInstance> | null;
+    /**
+     * Adds a join condition between a column on the associated model and a column on this model,
+     * so the association is scoped by matching column values across both models.
+     *
+     * ```ts
+     * @deco.HasMany('Post', { selfAnd: { species: 'targetSpecies' } })
+     * public postsMatchingSpecies: Post[]
+     * ```
+     */
     selfAnd?: SelfOnStatement<BaseInstance, BaseInstance['DB'], BaseInstance['schema'], AssociationTableName & AssociationTableNames<BaseInstance['DB'], BaseInstance['schema']> & keyof BaseInstance['DB']>;
+    /**
+     * Adds a negated join condition between a column on the associated model and a column
+     * on this model, excluding records where the columns match.
+     */
     selfAndNot?: SelfOnStatement<BaseInstance, BaseInstance['DB'], BaseInstance['schema'], AssociationTableName & AssociationTableNames<BaseInstance['DB'], BaseInstance['schema']> & keyof BaseInstance['DB']>;
+    /**
+     * Used in conjunction with `through` to specify which association on the intermediate model
+     * should be used to reach the target model.
+     */
     source?: keyof BaseInstance['schema'][ForeignTableName]['associations'];
+    /**
+     * Loads this association through an intermediate association, similar to a SQL join
+     * through a join table.
+     *
+     * ```ts
+     * @deco.HasMany('Rating', { through: 'posts' })
+     * public ratings: Rating[]
+     * ```
+     */
     through?: ThroughAssociationName;
+    /**
+     * A list of default scopes to bypass when loading this association.
+     */
     withoutDefaultScopes?: DefaultScopeNameForTable<BaseInstance['schema'], AssociationTableName & keyof BaseInstance['DB']>[];
 }
 export type PolymorphicOption = 'polymorphic';

package/dist/types/src/types/associations/shared.ts

@@ -399,9 +399,26 @@ interface HasOptionsBase<
     AssociationGlobalName & keyof GlobalModelNameTableMap<BaseInstance>
   >,
 > {
+  /**
+   * If `'destroy'`, associated records will be cascade-deleted when the base model is destroyed.
+   */
   dependent?: DependentOptions
+
+  /**
+   * A custom column on the associated model to use as the foreign key for this association,
+   * overriding the default convention-based foreign key.
+   */
   on?: TableColumnNames<BaseInstance['DB'], AssociationTableName & keyof BaseInstance['DB']>
 
+  /**
+   * A where clause applied whenever this association is loaded, scoping the association
+   * to only records matching the given conditions.
+   *
+   * ```ts
+   * @deco.HasMany('Collar', { and: { lost: false } })
+   * public currentCollars: Collar[]
+   * ```
+   */
   and?: OnStatementForAssociationDefinition<
     BaseInstance['DB'],
     BaseInstance['schema'],
@@ -410,6 +427,15 @@ interface HasOptionsBase<
       keyof BaseInstance['DB']
   >
 
+  /**
+   * A negated where clause applied whenever this association is loaded, excluding
+   * records matching the given conditions.
+   *
+   * ```ts
+   * @deco.HasOne('Collar', { andNot: { lost: true } })
+   * public notLostCollar: Collar
+   * ```
+   */
   andNot?: InternalWhereStatement<
     BaseInstance,
     BaseInstance['DB'],
@@ -419,6 +445,15 @@ interface HasOptionsBase<
       keyof BaseInstance['DB']
   >
 
+  /**
+   * An array of where clauses combined with OR logic, applied whenever this association
+   * is loaded. At least one of the clauses must match.
+   *
+   * ```ts
+   * @deco.HasMany('Balloon', { andAny: [{ color: 'red' }, { color: 'blue' }] })
+   * public redOrBlueBalloons: Balloon[]
+   * ```
+   */
   andAny?: InternalWhereStatement<
     BaseInstance,
     BaseInstance['DB'],
@@ -428,9 +463,27 @@ interface HasOptionsBase<
       keyof BaseInstance['DB']
   >[]
 
+  /**
+   * Marks this as a polymorphic association, where the foreign key and a type column
+   * together identify the associated record across multiple tables.
+   */
   polymorphic?: boolean
+
+  /**
+   * A custom column on this model to use as the primary key for this association,
+   * instead of the default primary key (e.g., `'uuid'` instead of `'id'`).
+   */
   primaryKeyOverride?: DreamColumnNames<BaseInstance> | null
 
+  /**
+   * Adds a join condition between a column on the associated model and a column on this model,
+   * so the association is scoped by matching column values across both models.
+   *
+   * ```ts
+   * @deco.HasMany('Post', { selfAnd: { species: 'targetSpecies' } })
+   * public postsMatchingSpecies: Post[]
+   * ```
+   */
   selfAnd?: SelfOnStatement<
     BaseInstance,
     BaseInstance['DB'],
@@ -440,6 +493,10 @@ interface HasOptionsBase<
       keyof BaseInstance['DB']
   >
 
+  /**
+   * Adds a negated join condition between a column on the associated model and a column
+   * on this model, excluding records where the columns match.
+   */
   selfAndNot?: SelfOnStatement<
     BaseInstance,
     BaseInstance['DB'],
@@ -449,9 +506,26 @@ interface HasOptionsBase<
       keyof BaseInstance['DB']
   >
 
+  /**
+   * Used in conjunction with `through` to specify which association on the intermediate model
+   * should be used to reach the target model.
+   */
   source?: keyof BaseInstance['schema'][ForeignTableName]['associations']
+
+  /**
+   * Loads this association through an intermediate association, similar to a SQL join
+   * through a join table.
+   *
+   * ```ts
+   * @deco.HasMany('Rating', { through: 'posts' })
+   * public ratings: Rating[]
+   * ```
+   */
   through?: ThroughAssociationName
 
+  /**
+   * A list of default scopes to bypass when loading this association.
+   */
   withoutDefaultScopes?: DefaultScopeNameForTable<
     BaseInstance['schema'],
     AssociationTableName & keyof BaseInstance['DB']