@rvoh/dream 2.34.0 → 2.36.0

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() { ... }

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

@@ -32,17 +32,17 @@ export type OpenapiSchemaBase =
   | 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
@@ -66,21 +66,40 @@ 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<{
@@ -108,15 +127,13 @@ 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
@@ -132,24 +149,23 @@ export type OpenapiSchemaObjectBase = CommonOpenapiSchemaObjectFields<{
     | OpenapiSchemaExpressionAnyOf
     | OpenapiSchemaExpressionAllOf
     | false
+  allOf?: never
 }>
 
-export type OpenapiSchemaObjectOneOf = CommonOpenapiSchemaObjectFields<{
-  oneOf?: OpenapiSchemaBody[]
-}>
-
-export type OpenapiSchemaObjectAnyOf = CommonOpenapiSchemaObjectFields<{
-  anyOf?: OpenapiSchemaBody[]
-}>
-
-export type OpenapiSchemaObjectAllOf = CommonOpenapiSchemaObjectFields<{
+/**
+ * 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 OpenapiSchemaObjectBaseShorthand = CommonOpenapiSchemaObjectFields<{
@@ -171,17 +187,15 @@ export type OpenapiSchemaObjectBaseShorthand = CommonOpenapiSchemaObjectFields<{
     | 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[]
 }>
 

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

@@ -2,7 +2,13 @@ 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'
@@ -32,7 +38,11 @@ export interface InternalAnyTypedSerializerCustomAttribute {
   type: 'customAttribute'
   name: string
   fn: (x?: any, y?: any) => any
-  options: Omit<NonAutomaticSerializerAttributeOptions, 'as'> & { flatten?: boolean }
+  options: {
+    openapi: CustomAttributeOpenapi
+    required?: false
+    flatten?: boolean
+  }
 }
 
 export interface InternalAnyRendersOneOrManyOpts {
@@ -143,6 +153,56 @@ export type NonAutomaticSerializerAttributeOptionsWithPossibleDecimalRenderOptio
     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 = (