@rvoh/dream 2.34.0 → 2.36.0

package/dist/cjs/src/serializer/builders/ObjectSerializerBuilder.js

@@ -92,9 +92,10 @@ export default class ObjectSerializerBuilder {
      *     (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
@@ -137,17 +138,23 @@ export default class ObjectSerializerBuilder {
      * 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
@@ -160,12 +167,16 @@ export default class ObjectSerializerBuilder {
      *   { 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' }
+     *     }
      *   }
      * })
      * ```
@@ -189,9 +200,18 @@ export default class ObjectSerializerBuilder {
      * @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

package/dist/cjs/src/serializer/helpers/serializersForAssociatedClass.js

@@ -0,0 +1,43 @@
+import uniq from '../../helpers/uniq.js';
+import { inferSerializersFromDreamClassOrViewModelClass } from './inferSerializerFromDreamOrViewModel.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 function serializersForAssociatedClass(parentClass, associationName, options) {
+    if (options.serializer)
+        return [options.serializer];
+    const optionClass = options.dreamClass ?? options.viewModelClass;
+    let associatedClasses;
+    if (optionClass) {
+        associatedClasses = [optionClass];
+    }
+    else {
+        const association = parentClass?.['getAssociationMetadata'](associationName);
+        if (!association)
+            return [];
+        const modelClassOrClasses = association.modelCB();
+        associatedClasses = Array.isArray(modelClassOrClasses) ? modelClassOrClasses : [modelClassOrClasses];
+    }
+    // Every serializer of every class: one for a plain class, and one per child (sorted by
+    // sanitizedName) for an STI base, so the parent JSON carries the flattened keys of every child
+    // as nulls, as it carries those of every target class of a polymorphic BelongsTo. Several classes
+    // may resolve to the same serializer; the renderer walks each serializer once either way.
+    // (rendersMany never reaches here and does not accept `flatten`.)
+    return uniq(associatedClasses.flatMap(associatedClass => inferSerializersFromDreamClassOrViewModelClass(associatedClass, options.serializerKey, {
+        // Reached only from SerializerRenderer's rendersOne branch, so the edge type is fixed. No
+        // declaring serializer: the renderer holds the rendered attribute, not the serializer that
+        // declared it.
+        edge: { type: 'rendersOne', associationName },
+    })));
+}