@rvoh/dream 2.35.0 → 2.36.1

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

@@ -1,6 +1,6 @@
 import Dream from '../../Dream.js';
 import { DreamOrViewModelSerializerKey, DreamVirtualColumns, NonJsonDreamColumnNames, ViewModel, ViewModelClass } from '../../types/dream.js';
-import { AutomaticSerializerAttributeOptions, AutomaticSerializerAttributeOptionsForType, InternalAnyTypedSerializerAttribute, InternalAnyTypedSerializerCustomAttribute, InternalAnyTypedSerializerDelegatedAttribute, InternalAnyTypedSerializerRendersMany, InternalAnyTypedSerializerRendersOne, NonAutomaticSerializerAttributeOptionsWithPossibleDecimalRenderOption, SerializerAttributeOptionsForVirtualColumn, SerializerType } from '../../types/serializer.js';
+import { AutomaticSerializerAttributeOptions, AutomaticSerializerAttributeOptionsForType, CustomAttributeOptions, DelegatedAttributeOptionsArgs, InternalAnyTypedSerializerAttribute, InternalAnyTypedSerializerCustomAttribute, InternalAnyTypedSerializerDelegatedAttribute, InternalAnyTypedSerializerRendersMany, InternalAnyTypedSerializerRendersOne, NonAutomaticSerializerAttributeOptionsWithPossibleDecimalRenderOption, SerializerAttributeOptionsForVirtualColumn, SerializerType } from '../../types/serializer.js';
 import { SerializerRendererOpts } from '../SerializerRenderer.js';
 export type DreamPropertiesToExclude = keyof Dream | 'serializers';
 export default class DreamSerializerBuilder<DataTypeForOpenapi extends typeof Dream, MaybeNullDataType extends Dream | null, PassthroughDataType = any, DataType extends Exclude<MaybeNullDataType, null> = Exclude<MaybeNullDataType, null>> {
@@ -54,7 +54,7 @@ export default class DreamSerializerBuilder<DataTypeForOpenapi extends typeof Dr
      */
     attribute(name: NonJsonDreamColumnNames<DataType> & keyof DataType & 'type', options?: AutomaticSerializerAttributeOptionsForType): DreamSerializerBuilder<DataTypeForOpenapi, MaybeNullDataType, PassthroughDataType, DataType>;
     attribute(name: DreamVirtualColumns<DataType>[number], options?: SerializerAttributeOptionsForVirtualColumn): DreamSerializerBuilder<DataTypeForOpenapi, MaybeNullDataType, PassthroughDataType, DataType>;
-    attribute<MaybeAttributeName extends NonJsonDreamColumnNames<DataType> | (keyof DataType & string), AttributeName extends MaybeAttributeName extends NonJsonDreamColumnNames<DataType> ? never : Exclude<keyof DataType, DreamPropertiesToExclude> & string>(name: AttributeName, options: NonAutomaticSerializerAttributeOptionsWithPossibleDecimalRenderOption): DreamSerializerBuilder<DataTypeForOpenapi, MaybeNullDataType, PassthroughDataType, DataType>;
+    attribute<AttributeName extends Exclude<keyof DataType & string, NonJsonDreamColumnNames<DataType> | DreamPropertiesToExclude>>(name: AttributeName, options: NonAutomaticSerializerAttributeOptionsWithPossibleDecimalRenderOption): DreamSerializerBuilder<DataTypeForOpenapi, MaybeNullDataType, PassthroughDataType, DataType>;
     attribute<AttributeName extends NonJsonDreamColumnNames<DataType> & keyof DataType & string>(name: AttributeName, options?: AutomaticSerializerAttributeOptions): DreamSerializerBuilder<DataTypeForOpenapi, MaybeNullDataType, PassthroughDataType, DataType>;
     /**
      * Includes an attribute from a nested object in the serialized output.
@@ -65,9 +65,10 @@ export default class DreamSerializerBuilder<DataTypeForOpenapi extends typeof Dr
      *   2. `required: false` → omits the key entirely from the rendered output
      *   3. otherwise → renders `null`
      *
-     * When the target is a Dream model, OpenAPI types may be automatically inferred
-     * for standard database columns. For json/jsonb columns or non-Dream targets,
-     * the `openapi` option is required.
+     * When the target is a Dream model, a non-json column's OpenAPI shape is inferred
+     * from the column, so its `openapi` option takes only a `description`. json/jsonb
+     * columns and non-Dream targets have no shape to infer, so they require a full
+     * `openapi` shape.
      *
      * `optional` and `required` are not aliases — they encode different things and can
      * be used together:
@@ -91,12 +92,14 @@ export default class DreamSerializerBuilder<DataTypeForOpenapi extends typeof Dr
      *     a discriminator string when the association is actually missing produces a response
      *     indistinguishable from "association present with that type," which is misleading)
      *   - `openapi` - OpenAPI schema definition; required for non-Dream targets and json/jsonb
-     *     columns, optional for standard Dream columns (where types are inferred)
-     *   - `optional` - Set to `true` to mark the value as nullable in the OpenAPI schema
-     *     (wraps the type in `anyOf: [schema, { type: 'null' }]`). OpenAPI-only — the
-     *     key is still rendered (as `null`). For Dream models, this is auto-inferred
-     *     from optional BelongsTo associations. Use this when delegating through a
-     *     HasOne or other nullable association.
+     *     columns. On a non-json Dream column, whose shape is inferred, it takes only a
+     *     `description` (and, on the STI `type` column, a `type: 'string'` and `enum`)
+     *   - `optional` - Set to `true` to mark the value as nullable in the OpenAPI schema:
+     *     Psychic adds `null` to the rendered schema (e.g., `type: 'string'` becomes
+     *     `type: ['string', 'null']`, and a `$ref` becomes `anyOf: [{ $ref }, { type: 'null' }]`).
+     *     OpenAPI-only — the key is still rendered (as `null`). For Dream models, this is
+     *     auto-inferred from optional BelongsTo associations. Use this when delegating
+     *     through a HasOne or other nullable association.
      *   - `precision` - Round decimal values to the specified number of decimal places (0–9)
      *     during rendering; does not affect the OpenAPI shape (not available when delegating
      *     to a `'type'` STI discriminator column, which is always a string enum)
@@ -108,52 +111,45 @@ export default class DreamSerializerBuilder<DataTypeForOpenapi extends typeof Dr
      * @example
      * ```typescript
      * // Delegate to a Dream association's column (type inferred)
-     * .delegatedAttribute('currentLocalizedText', 'title', { openapi: 'string' })
+     * .delegatedAttribute('currentLocalizedText', 'title')
      *
      * // With default value for null target or attribute
-     * .delegatedAttribute('user', 'displayName', {
-     *   openapi: { type: 'string' },
-     *   default: 'Unknown User'
-     * })
+     * .delegatedAttribute('user', 'displayName', { default: 'Unknown User' })
      *
      * // Rename the output key
-     * .delegatedAttribute('profile', 'avatarUrl', {
-     *   openapi: 'string',
-     *   as: 'avatar'
+     * .delegatedAttribute('profile', 'avatarUrl', { as: 'avatar' })
+     *
+     * // A json/jsonb column has no shape to infer, so it declares one
+     * .delegatedAttribute('user', 'preferences', {
+     *   openapi: { type: 'object', properties: { theme: 'string' } }
      * })
      * ```
      */
-    delegatedAttribute<ProvidedModelType = undefined, ProvidedTargetName extends ProvidedModelType extends undefined ? undefined : Exclude<keyof ProvidedModelType, DreamPropertiesToExclude> = ProvidedModelType extends undefined ? undefined : Exclude<keyof ProvidedModelType, DreamPropertiesToExclude>, ActualDataType extends ProvidedModelType extends undefined ? InstanceType<DataTypeForOpenapi> : ProvidedModelType = ProvidedModelType extends undefined ? InstanceType<DataTypeForOpenapi> : ProvidedModelType, TargetName extends ProvidedTargetName extends undefined ? Exclude<keyof ActualDataType, DreamPropertiesToExclude> : ProvidedTargetName & keyof ActualDataType = ProvidedTargetName extends undefined ? Exclude<keyof ActualDataType, DreamPropertiesToExclude> : ProvidedTargetName & keyof ActualDataType, AssociatedModelType = Exclude<ActualDataType[TargetName], null>, TargetAttributeName extends AssociatedModelType extends object ? Exclude<keyof AssociatedModelType, DreamPropertiesToExclude> & string : never = AssociatedModelType extends object ? Exclude<keyof AssociatedModelType, DreamPropertiesToExclude> & string : never>(targetName: TargetName, name: TargetAttributeName, options?: AssociatedModelType extends Dream ? TargetAttributeName extends NonJsonDreamColumnNames<AssociatedModelType> & keyof AssociatedModelType & 'type' ? AutomaticSerializerAttributeOptionsForType & {
-        optional?: boolean;
-        required?: false;
-    } : TargetAttributeName extends DreamVirtualColumns<AssociatedModelType>[number] ? SerializerAttributeOptionsForVirtualColumn & {
-        optional?: boolean;
-    } : TargetAttributeName extends NonJsonDreamColumnNames<AssociatedModelType> & keyof AssociatedModelType & string ? (AutomaticSerializerAttributeOptions & {
-        optional?: boolean;
-    }) | (NonAutomaticSerializerAttributeOptionsWithPossibleDecimalRenderOption & {
-        optional?: boolean;
-    }) : NonAutomaticSerializerAttributeOptionsWithPossibleDecimalRenderOption & {
-        optional?: boolean;
-    } : NonAutomaticSerializerAttributeOptionsWithPossibleDecimalRenderOption & {
-        optional?: boolean;
-    }): this;
+    delegatedAttribute<ProvidedModelType = undefined, ProvidedTargetName extends ProvidedModelType extends undefined ? undefined : Exclude<keyof ProvidedModelType, DreamPropertiesToExclude> = ProvidedModelType extends undefined ? undefined : Exclude<keyof ProvidedModelType, DreamPropertiesToExclude>, ActualDataType extends ProvidedModelType extends undefined ? InstanceType<DataTypeForOpenapi> : ProvidedModelType = ProvidedModelType extends undefined ? InstanceType<DataTypeForOpenapi> : ProvidedModelType, TargetName extends ProvidedTargetName extends undefined ? Exclude<keyof ActualDataType, DreamPropertiesToExclude> : ProvidedTargetName & keyof ActualDataType = ProvidedTargetName extends undefined ? Exclude<keyof ActualDataType, DreamPropertiesToExclude> : ProvidedTargetName & keyof ActualDataType, AssociatedModelType = Exclude<ActualDataType[TargetName], null>, TargetAttributeName extends AssociatedModelType extends object ? Exclude<keyof AssociatedModelType, DreamPropertiesToExclude> & string : never = AssociatedModelType extends object ? Exclude<keyof AssociatedModelType, DreamPropertiesToExclude> & string : never>(targetName: TargetName, name: TargetAttributeName, ...options: DelegatedAttributeOptionsArgs<AssociatedModelType, TargetAttributeName>): 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.
      *
+     * The callback's return value renders as is, so any fallback or rounding belongs in the
+     * callback.
+     *
      * @param name - The attribute name for the computed value
      * @param fn - Callback function that returns the computed value
      * @param options - Configuration options:
      *   - `openapi` - (required) OpenAPI schema definition for the computed value
-     *   - `as` - Rename the attribute key in the serialized output and OpenAPI shape
-     *   - `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
-     *   - `precision` - Round decimal values to the specified number of decimal places (0–9)
-     *     during rendering; does not affect the OpenAPI shape
+     *     parent serialized output instead of nesting them under `name`. The `openapi` option
+     *     then describes the whole returned object, not each property, because Psychic adds it
+     *     to the parent's schema as an `allOf` branch: either an object schema with full
+     *     property bodies (`type: 'object'`, `properties`, and `required` listing the keys that
+     *     are always present), or `{ $serializer: SomeSerializer }` when the callback returns
+     *     what that serializer renders. A serializer ref with `many: true` does not type-check
+     *     here, since a list has no properties to spread. A `null` or `undefined` return adds no
+     *     keys. Attributes render in declaration order, so a key the returned object shares with
+     *     another attribute takes the value of whichever is declared later; under the `allOf`,
+     *     that value must match both schemas
      *   - `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
@@ -166,25 +162,21 @@ export default class DreamSerializerBuilder<DataTypeForOpenapi extends typeof Dr
      *   { openapi: { type: 'string' } }
      * )
      *
-     * // Flattened object properties
+     * // Flattened object properties: `openapi` describes the whole returned object
      * .customAttribute('coordinates', () => ({ lat: 40.7, lng: -74.0 }), {
      *   flatten: true,
      *   openapi: {
-     *     lat: { type: 'number' },
-     *     lng: { type: 'number' }
+     *     type: 'object',
+     *     required: ['lat', 'lng'],
+     *     properties: {
+     *       lat: { type: 'number' },
+     *       lng: { type: 'number' }
+     *     }
      *   }
      * })
-     *
-     * // With decimal precision
-     * .customAttribute('averageRating', () => calculateAverage(ratings), {
-     *   openapi: 'decimal',
-     *   precision: 2
-     * })
      * ```
      */
-    customAttribute(name: string, fn: () => unknown, options: NonAutomaticSerializerAttributeOptionsWithPossibleDecimalRenderOption & {
-        flatten?: boolean;
-    }): this;
+    customAttribute(name: string, fn: () => unknown, options: CustomAttributeOptions): this;
     /**
      * Includes a single associated object in the serialized output.
      *
@@ -195,9 +187,18 @@ export default class DreamSerializerBuilder<DataTypeForOpenapi extends typeof Dr
      * @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
+     *     the parent serialized output instead of nesting them under `name`. Attributes render in
+     *     declaration order, so when the parent and the association share a key (e.g., `id`),
+     *     whichever is declared later wins: the association's value replaces an attribute declared
+     *     before the `rendersOne`, and an attribute declared after it replaces the association's.
+     *     When the association is `null`, every key its serializer declares renders as `null`
+     *     (for a polymorphic `BelongsTo`, every key the serializer of any of its target classes
+     *     declares, and for an association to an STI base, every key the serializer of any of its
+     *     STI children declares), in the same order (so an `id` declared before the `rendersOne` becomes
+     *     `null`); nothing in that serializer is rendered, so its custom attribute callbacks do
+     *     not run, and a flattened `customAttribute` in it adds no keys. Psychic adds the association's OpenAPI
+     *     schema to the parent's as an `allOf` branch, so a shared key's value must match both
+     *     schemas, whichever declaration wins
      *   - `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
@@ -251,7 +252,10 @@ export default class DreamSerializerBuilder<DataTypeForOpenapi extends typeof Dr
         as?: string;
         /**
          * If `true`, the rendered association's attributes are merged directly into
-         * the parent object instead of being nested under the association key.
+         * the parent object instead of being nested under the association key. A key
+         * the parent shares with the association takes the value of whichever is
+         * declared later, and when the association is `null`, every key its serializer
+         * declares renders as `null`. See the `flatten` option of `rendersOne`.
          */
         flatten?: boolean;
         /**

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

@@ -1,6 +1,6 @@
 import Dream from '../../Dream.js';
 import { DreamOrViewModelSerializerKey, ViewModel, ViewModelClass } from '../../types/dream.js';
-import { InternalAnyTypedSerializerAttribute, InternalAnyTypedSerializerCustomAttribute, InternalAnyTypedSerializerDelegatedAttribute, InternalAnyTypedSerializerRendersMany, InternalAnyTypedSerializerRendersOne, NonAutomaticSerializerAttributeOptions, NonAutomaticSerializerAttributeOptionsWithPossibleDecimalRenderOption, SerializerType } from '../../types/serializer.js';
+import { CustomAttributeOptions, InternalAnyTypedSerializerAttribute, InternalAnyTypedSerializerCustomAttribute, InternalAnyTypedSerializerDelegatedAttribute, InternalAnyTypedSerializerRendersMany, InternalAnyTypedSerializerRendersOne, NonAutomaticSerializerAttributeOptionsWithPossibleDecimalRenderOption, SerializerType } from '../../types/serializer.js';
 import { SerializerRendererOpts } from '../SerializerRenderer.js';
 import { DreamPropertiesToExclude } from './DreamSerializerBuilder.js';
 export default class ObjectSerializerBuilder<MaybeNullDataType extends object | null, PassthroughDataType, DataType extends Exclude<MaybeNullDataType, null> = Exclude<MaybeNullDataType, null>> {
@@ -86,9 +86,10 @@ export default class ObjectSerializerBuilder<MaybeNullDataType extends object |
      *     (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
-     *   - `optional` - Set to `true` to mark the value as nullable in the OpenAPI schema
-     *     (wraps the type in `anyOf: [schema, { type: 'null' }]`). OpenAPI-only — the
-     *     key is still rendered (as `null`)
+     *   - `optional` - Set to `true` to mark the value as nullable in the OpenAPI schema:
+     *     Psychic adds `null` to the rendered schema (e.g., `type: 'string'` becomes
+     *     `type: ['string', 'null']`, and a `$ref` becomes `anyOf: [{ $ref }, { type: 'null' }]`).
+     *     OpenAPI-only — the key is still rendered (as `null`)
      *   - `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 omit the key from the rendered output when the
@@ -125,17 +126,23 @@ 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`.
+     * The callback's return value renders as is, so any fallback belongs in the callback.
      *
      * @param name - The attribute name for the computed value
      * @param fn - Callback function that returns the computed value
      * @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
+     *     parent serialized output instead of nesting them under `name`. The `openapi` option
+     *     then describes the whole returned object, not each property, because Psychic adds it
+     *     to the parent's schema as an `allOf` branch: either an object schema with full
+     *     property bodies (`type: 'object'`, `properties`, and `required` listing the keys that
+     *     are always present), or `{ $serializer: SomeSerializer }` when the callback returns
+     *     what that serializer renders. A serializer ref with `many: true` does not type-check
+     *     here, since a list has no properties to spread. A `null` or `undefined` return adds no
+     *     keys. Attributes render in declaration order, so a key the returned object shares with
+     *     another attribute takes the value of whichever is declared later; under the `allOf`,
+     *     that value must match both schemas
      *   - `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
@@ -148,19 +155,21 @@ export default class ObjectSerializerBuilder<MaybeNullDataType extends object |
      *   { openapi: { type: 'string' } }
      * )
      *
-     * // Flattened object properties
+     * // Flattened object properties: `openapi` describes the whole returned object
      * .customAttribute('coordinates', () => ({ lat: 40.7, lng: -74.0 }), {
      *   flatten: true,
      *   openapi: {
-     *     lat: { type: 'number' },
-     *     lng: { type: 'number' }
+     *     type: 'object',
+     *     required: ['lat', 'lng'],
+     *     properties: {
+     *       lat: { type: 'number' },
+     *       lng: { type: 'number' }
+     *     }
      *   }
      * })
      * ```
      */
-    customAttribute(name: string, fn: () => unknown, options: Omit<NonAutomaticSerializerAttributeOptions, 'as'> & {
-        flatten?: boolean;
-    }): this;
+    customAttribute(name: string, fn: () => unknown, options: CustomAttributeOptions): this;
     /**
      * Includes a single associated object in the serialized output.
      *
@@ -171,9 +180,18 @@ export default class ObjectSerializerBuilder<MaybeNullDataType extends object |
      * @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
+     *     the parent serialized output instead of nesting them under `name`. Attributes render in
+     *     declaration order, so when the parent and the association share a key (e.g., `id`),
+     *     whichever is declared later wins: the association's value replaces an attribute declared
+     *     before the `rendersOne`, and an attribute declared after it replaces the association's.
+     *     When the association is `null`, every key its serializer declares renders as `null`
+     *     (for a polymorphic `BelongsTo`, every key the serializer of any of its target classes
+     *     declares, and for an association to an STI base, every key the serializer of any of its
+     *     STI children declares), in the same order (so an `id` declared before the `rendersOne` becomes
+     *     `null`); nothing in that serializer is rendered, so its custom attribute callbacks do
+     *     not run, and a flattened `customAttribute` in it adds no keys. Psychic adds the association's OpenAPI
+     *     schema to the parent's as an `allOf` branch, so a shared key's value must match both
+     *     schemas, whichever declaration wins
      *   - `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
@@ -229,7 +247,10 @@ export default class ObjectSerializerBuilder<MaybeNullDataType extends object |
         as?: string;
         /**
          * If `true`, the rendered association's attributes are merged directly into
-         * the parent object instead of being nested under the association key.
+         * the parent object instead of being nested under the association key. A key
+         * the parent shares with the association takes the value of whichever is
+         * declared later, and when the association is `null`, every key its serializer
+         * declares renders as `null`. See the `flatten` option of `rendersOne`.
          */
         flatten?: boolean;
         /**

package/dist/types/src/serializer/helpers/serializersForAssociatedClass.d.ts

@@ -0,0 +1,17 @@
+import Dream from '../../Dream.js';
+import { DreamModelSerializerType, InternalAnyRendersOneOrManyOpts, SimpleObjectSerializerType } from '../../types/serializer.js';
+/**
+ * Only used when flatten: true, and the associated object is null, in which case there is no
+ * object to resolve a serializer from, but the renderer still needs the serializers whose keys it
+ * renders as null in the parent's payload.
+ *
+ * Resolves, in order, to the `serializer` option, the serializers of the `dreamClass` or
+ * `viewModelClass` option, or the serializers of each class `parentClass` declares the association
+ * to: the one class of most associations, or every target class of a polymorphic BelongsTo. A
+ * class that is an STI base contributes the serializer of every one of its children, since the
+ * association renders with whichever child it holds when present. The renderer renders the union
+ * of all their keys, each key once. Returns no serializers when none applies, e.g. a
+ * non-association property without a `serializer` option, so the flattened association adds no
+ * keys.
+ */
+export declare function serializersForAssociatedClass(parentClass: typeof Dream | null, associationName: string, options: InternalAnyRendersOneOrManyOpts): (DreamModelSerializerType | SimpleObjectSerializerType)[];

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

@@ -55,6 +55,12 @@ export interface AfterHookOpts<T extends Dream | null = null> {
      * Only run this hook if one of the specified columns was changed in the
      * most recent save operation.
      *
+     * On a create, a column counts when, just before the insert, it holds a
+     * value other than `undefined` (for an instance from `dup`, other than the
+     * copied value), whether the caller or a before hook assigned it; values
+     * the insert fills in, such as the primary key, timestamps, database
+     * defaults and `null` for a column nobody assigned, do not count.
+     *
      * ```ts
      * @deco.AfterUpdate({ ifChanged: ['email'] })
      * public sendEmailVerification() { ... }

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

@@ -5,15 +5,15 @@ import { DreamModelSerializerType, SimpleObjectSerializerType } from './serializ
 export type OpenapiSchemaBody = OpenapiSchemaBase | OpenapiSchemaPrimitiveGeneric | OpenapiSchemaExpressionAnyOf | OpenapiSchemaExpressionOneOf | OpenapiSchemaExpressionAllOf | OpenapiSchemaObject | OpenapiSchemaArray;
 export type OpenapiSchemaBodyShorthand = OpenapiSchemaBase | OpenapiSchemaShorthandPrimitiveGeneric | OpenapiSchemaShorthandExpressionAnyOf | OpenapiSchemaShorthandExpressionOneOf | OpenapiSchemaShorthandExpressionAllOf | OpenapiSchemaObjectShorthand | OpenapiSchemaArrayShorthand | OpenapiSchemaNull | OpenapiSchemaExpressionRefSchemaShorthand | OpenapiSchemaShorthandExpressionSerializerRef | OpenapiSchemaShorthandExpressionSerializableRef;
 export type OpenapiSchemaBase = OpenapiSchemaString | OpenapiSchemaInteger | OpenapiSchemaNumber | OpenapiSchemaNull | OpenapiSchemaExpressionRef;
-export type OpenapiSchemaShorthandExpressionAnyOf = {
+export type OpenapiSchemaShorthandExpressionAnyOf = OpenapiSchemaCombinatorFields<{
     anyOf: OpenapiSchemaBodyShorthand[];
-};
-export type OpenapiSchemaShorthandExpressionOneOf = {
+}>;
+export type OpenapiSchemaShorthandExpressionOneOf = OpenapiSchemaCombinatorFields<{
     oneOf: OpenapiSchemaBodyShorthand[];
-};
-export type OpenapiSchemaShorthandExpressionAllOf = {
+}>;
+export type OpenapiSchemaShorthandExpressionAllOf = OpenapiSchemaCombinatorFields<{
     allOf: OpenapiSchemaBodyShorthand[];
-};
+}>;
 export type OpenapiSchemaShorthandExpressionSerializerRef = {
     $serializer: DreamModelSerializerType | SimpleObjectSerializerType;
     many?: boolean;
@@ -32,18 +32,36 @@ export type OpenapiSchemaExpressionRef = {
 export type OpenapiSchemaExpressionRefSchemaShorthand = {
     $schema: string;
 };
-export type OpenapiSchemaExpressionAllOf = {
+export type OpenapiSchemaExpressionAllOf = OpenapiSchemaCombinatorFields<{
     allOf: OpenapiSchemaBody[];
-};
-export type OpenapiSchemaExpressionAnyOf = {
+}>;
+export type OpenapiSchemaExpressionAnyOf = OpenapiSchemaCombinatorFields<{
     anyOf: OpenapiSchemaBody[];
-};
-export type OpenapiSchemaExpressionOneOf = {
+}>;
+export type OpenapiSchemaExpressionOneOf = OpenapiSchemaCombinatorFields<{
     oneOf: OpenapiSchemaBody[];
-};
+}>;
+/**
+ * The fields of a schema that declares a `type`. `anyOf` and `oneOf` are not
+ * among them: they apply to every value, `null` included, so a nullable `type`
+ * beside one cannot admit `null`. A schema that may be null lists a
+ * `{ type: 'null' }` branch in its `anyOf` or `oneOf` instead.
+ */
 export type OpenapiSchemaCommonFields<T> = T & {
     description?: string;
     summary?: string;
+    anyOf?: never;
+    oneOf?: never;
+};
+/**
+ * The fields of a schema that is an `allOf`, `anyOf` or `oneOf`: the
+ * combinator and the fields that describe it, but no `type` (see
+ * `OpenapiSchemaCommonFields`).
+ */
+export type OpenapiSchemaCombinatorFields<T> = T & {
+    description?: string;
+    summary?: string;
+    type?: never;
 };
 export type OpenapiSchemaString = OpenapiSchemaCommonFields<{
     type: 'string' | ['string', 'null'] | ['null', 'string'];
@@ -67,38 +85,43 @@ export type OpenapiSchemaNumber = OpenapiSchemaCommonFields<{
 }>;
 export type OpenapiSchemaNull = {
     type: 'null';
+    anyOf?: never;
+    oneOf?: never;
 };
 export type OpenapiNumberFormats = 'decimal' | 'double';
-export type OpenapiSchemaObject = OpenapiSchemaObjectBase | OpenapiSchemaObjectOneOf | OpenapiSchemaObjectAnyOf | OpenapiSchemaObjectAllOf;
+export type OpenapiSchemaObject = OpenapiSchemaObjectBase | OpenapiSchemaObjectAllOf;
 export type OpenapiSchemaObjectBase = CommonOpenapiSchemaObjectFields<{
     minProperties?: number;
     maxProperties?: number;
     properties?: OpenapiSchemaProperties | OpenapiSchemaExpressionOneOf | OpenapiSchemaExpressionAnyOf | OpenapiSchemaExpressionAllOf;
     additionalProperties?: OpenapiSchemaObject | OpenapiSchemaExpressionOneOf | OpenapiSchemaExpressionAnyOf | OpenapiSchemaExpressionAllOf | false;
-}>;
-export type OpenapiSchemaObjectOneOf = CommonOpenapiSchemaObjectFields<{
-    oneOf?: OpenapiSchemaBody[];
-}>;
-export type OpenapiSchemaObjectAnyOf = CommonOpenapiSchemaObjectFields<{
-    anyOf?: OpenapiSchemaBody[];
-}>;
-export type OpenapiSchemaObjectAllOf = CommonOpenapiSchemaObjectFields<{
+    allOf?: never;
+}>;
+/**
+ * An object schema that is also an `allOf`. Its `type` cannot be nullable:
+ * `allOf` applies to every value, so `null` would have to match each of its
+ * object members. A schema that may be null is an `anyOf` or `oneOf` with a
+ * `{ type: 'null' }` branch.
+ */
+export type OpenapiSchemaObjectAllOf = OpenapiSchemaCommonFields<{
+    type: 'object';
+    required?: string[];
     allOf?: OpenapiSchemaBody[];
 }>;
-export type OpenapiSchemaObjectShorthand = OpenapiSchemaObjectBaseShorthand | OpenapiSchemaObjectOneOfShorthand | OpenapiSchemaObjectAnyOfShorthand | OpenapiSchemaObjectAllOfShorthand;
+export type OpenapiSchemaObjectShorthand = OpenapiSchemaObjectBaseShorthand | OpenapiSchemaObjectAllOfShorthand;
 export type OpenapiSchemaObjectBaseShorthand = CommonOpenapiSchemaObjectFields<{
     minProperties?: number;
     maxProperties?: number;
     properties?: OpenapiSchemaPropertiesShorthand | OpenapiSchemaShorthandExpressionOneOf | OpenapiSchemaShorthandExpressionAnyOf | OpenapiSchemaShorthandExpressionAllOf | OpenapiSchemaShorthandExpressionSerializerRef | OpenapiSchemaShorthandExpressionSerializableRef;
     additionalProperties?: OpenapiShorthandPrimitiveTypes | OpenapiSchemaBodyShorthand | OpenapiSchemaShorthandExpressionOneOf | OpenapiSchemaShorthandExpressionAnyOf | OpenapiSchemaShorthandExpressionAllOf | OpenapiSchemaShorthandExpressionSerializerRef | OpenapiSchemaShorthandExpressionSerializableRef | false;
+    allOf?: never;
 }>;
-export type OpenapiSchemaObjectOneOfShorthand = CommonOpenapiSchemaObjectFields<{
-    oneOf?: OpenapiSchemaBodyShorthand[];
-}>;
-export type OpenapiSchemaObjectAnyOfShorthand = CommonOpenapiSchemaObjectFields<{
-    anyOf?: OpenapiSchemaBodyShorthand[];
-}>;
-export type OpenapiSchemaObjectAllOfShorthand = CommonOpenapiSchemaObjectFields<{
+/**
+ * The shorthand form of `OpenapiSchemaObjectAllOf`.
+ */
+export type OpenapiSchemaObjectAllOfShorthand = OpenapiSchemaCommonFields<{
+    type: 'object';
+    required?: string[];
     allOf?: OpenapiSchemaBodyShorthand[];
 }>;
 export type CommonOpenapiSchemaObjectFields<T> = OpenapiSchemaCommonFields<T & {

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

@@ -2,7 +2,7 @@ import Dream from '../Dream.js';
 import { RoundingPrecision } from '../helpers/round.js';
 import DreamSerializerBuilder from '../serializer/builders/DreamSerializerBuilder.js';
 import ObjectSerializerBuilder from '../serializer/builders/ObjectSerializerBuilder.js';
-import { DreamSerializable, DreamSerializableArray, ViewModelClass } from './dream.js';
+import { DreamSerializable, DreamSerializableArray, DreamVirtualColumns, NonJsonDreamColumnNames, ViewModelClass } from './dream.js';
 import { OpenapiDescription, OpenapiSchemaBodyShorthand, OpenapiShorthandPrimitiveTypes } from './openapi.js';
 export type SerializerCasing = 'camel' | 'snake';
 export type DreamsOrSerializersOrViewModels = DreamSerializable | DreamSerializableArray;
@@ -28,7 +28,9 @@ export interface InternalAnyTypedSerializerCustomAttribute {
     type: 'customAttribute';
     name: string;
     fn: (x?: any, y?: any) => any;
-    options: Omit<NonAutomaticSerializerAttributeOptions, 'as'> & {
+    options: {
+        openapi: CustomAttributeOpenapi;
+        required?: false;
         flatten?: boolean;
     };
 }
@@ -119,6 +121,45 @@ export type NonAutomaticSerializerAttributeOptions = {
 export type NonAutomaticSerializerAttributeOptionsWithPossibleDecimalRenderOption = NonAutomaticSerializerAttributeOptions & {
     precision?: RoundingPrecision;
 };
+/**
+ * The options argument of `DreamSerializer#delegatedAttribute`. A Dream model's non-json
+ * column infers its OpenAPI shape, so its `openapi` takes only a description and the
+ * argument may be left out. A json/jsonb column or a non-Dream target has no shape to
+ * infer, so the argument is required and its `openapi` takes a full shape.
+ */
+export type DelegatedAttributeOptionsArgs<AssociatedModelType, TargetAttributeName> = DelegatedAttributeOptions<AssociatedModelType, TargetAttributeName> extends infer Options ? Partial<Options> extends Options ? [options?: Options] : [options: Options] : never;
+type DelegatedAttributeOptions<AssociatedModelType, TargetAttributeName> = AssociatedModelType extends Dream ? TargetAttributeName extends NonJsonDreamColumnNames<AssociatedModelType> & keyof AssociatedModelType & 'type' ? AutomaticSerializerAttributeOptionsForType & {
+    optional?: boolean;
+    required?: false;
+} : TargetAttributeName extends DreamVirtualColumns<AssociatedModelType>[number] ? SerializerAttributeOptionsForVirtualColumn & {
+    optional?: boolean;
+} : TargetAttributeName extends NonJsonDreamColumnNames<AssociatedModelType> & keyof AssociatedModelType & string ? AutomaticSerializerAttributeOptions & {
+    optional?: boolean;
+} : NonAutomaticSerializerAttributeOptionsWithPossibleDecimalRenderOption & {
+    optional?: boolean;
+} : NonAutomaticSerializerAttributeOptionsWithPossibleDecimalRenderOption & {
+    optional?: boolean;
+};
+type CustomAttributeOpenapi = OpenapiSchemaBodyShorthand | OpenapiShorthandPrimitiveTypes;
+/**
+ * The options of `customAttribute`. The callback's return value renders as is, so there is
+ * no `as`, `default` or `precision`. With `flatten: true`, `openapi` may be anything but a
+ * serializer ref with `many: true`: flattening spreads one object's properties into the
+ * parent, and a list has none to spread.
+ */
+export type CustomAttributeOptions = {
+    openapi: CustomAttributeOpenapi;
+    required?: false;
+    flatten?: false;
+} | {
+    openapi: OpenapiForFlattening<CustomAttributeOpenapi>;
+    required?: false;
+    flatten: true;
+};
+type OpenapiForFlattening<Openapi> = Openapi extends unknown ? 'many' extends keyof Openapi ? Omit<Openapi, 'many'> & {
+    many?: false;
+} : Openapi : never;
 export type DreamModelSerializerType = (data: any, passthroughData?: any) => DreamSerializerBuilder<any, any>;
 export type SimpleObjectSerializerType = (data: any, passthroughData?: any) => ObjectSerializerBuilder<any, any>;
 export type SerializerType = DreamModelSerializerType | SimpleObjectSerializerType;
+export {};

package/dist/types/src/types/types/lifecycle.ts

@@ -90,6 +90,12 @@ export interface AfterHookOpts<T extends Dream | null = null> {
    * Only run this hook if one of the specified columns was changed in the
    * most recent save operation.
    *
+   * On a create, a column counts when, just before the insert, it holds a
+   * value other than `undefined` (for an instance from `dup`, other than the
+   * copied value), whether the caller or a before hook assigned it; values
+   * the insert fills in, such as the primary key, timestamps, database
+   * defaults and `null` for a column nobody assigned, do not count.
+   *
    * ```ts
    * @deco.AfterUpdate({ ifChanged: ['email'] })
    * public sendEmailVerification() { ... }