@rvoh/dream 2.38.0 → 2.40.0

package/README.md

@@ -171,39 +171,7 @@ await user.save()
 
 ### Specs
 
-Running specs is very easy, not much to explain here.
-
-```
-pnpm spec
-```
-
-We are using jest under the hood, and have a plugin enabled called `jest-plugin-context`, which allows us to branch specs out using the `context` function in place of `describe`, like so:
-
-```ts
-describe('Dream#pluck', () => {
-  let user1: User
-  let user2: User
-  beforeEach(async () => {
-    user1 = await User.create({ email: 'fred@frewd', password: 'howyadoin' })
-    user2 = await User.create({ email: 'how@yadoin', password: 'howyadoin' })
-  })
-
-  it('plucks the specified attributes and returns them as raw data', async () => {
-    const records = await User.pluck('id')
-    expect(records).toEqual([user1.id, user2.id])
-  })
-
-  context('with multiple fields', () => {
-    it('should return multi-dimensional array', async () => {
-      const records = await User.order('id').pluck('id', 'createdAt')
-      expect(records).toEqual([
-        [user1.id, user1.created_at],
-        [user2.id, user2.created_at],
-      ])
-    })
-  })
-})
-```
+See [CONTRIBUTING.md](CONTRIBUTING.md) for setting up the test databases and running the specs.
 
 ### Similarity matching
 
@@ -278,6 +246,6 @@ const pets = await user
 
 - **Ask them on [Stack Overflow](https://stackoverflow.com)**, using the `[dream]` tag.
 
-Dream is an open source library, so we encourage you to actively contribute. Visit our [Contributing](https://github.com/rvohealth/dream/CONTRIBUTING.md) guide to learn more about the processes we use for submitting pull requests or issues.
+Dream is an open source library, so we encourage you to actively contribute. Visit our [Contributing](CONTRIBUTING.md) guide to learn more about the processes we use for submitting pull requests or issues.
 
 Are you trying to report a possible security vulnerability? Visit our [Security Policy](https://github.com/rvohealth/dream/SECURITY.md) for guidelines about how to proceed.

package/dist/cjs/src/dream-app/index.js

@@ -19,7 +19,7 @@ import standardizeFullyQualifiedModelName from '../helpers/standardizeFullyQuali
 import expandStiClasses from '../helpers/sti/expandStiClasses.js';
 import inferSerializerFromDreamOrViewModel, { inferSerializersFromDreamClassOrViewModelClass, } from '../serializer/helpers/inferSerializerFromDreamOrViewModel.js';
 import isDreamSerializer from '../serializer/helpers/isDreamSerializer.js';
-import { nullFlattenedOpenapiKeys, nullFlattenedOpenapiKeysOfOtherVariants, nullFlattenedSerializerKeys, nullFlattenedSerializerKeysOfOtherVariants, } from '../serializer/helpers/nullFlattenedSerializerKeys.js';
+import { flattenedOpenapiVariants, nullFlattenedOpenapiKeys, nullFlattenedOpenapiKeysOfOtherVariants, nullFlattenedSerializerKeys, nullFlattenedSerializerKeysOfOtherVariants, } from '../serializer/helpers/nullFlattenedSerializerKeys.js';
 import serializerNameFromFullyQualifiedModelName from '../serializer/helpers/serializerNameFromFullyQualifiedModelName.js';
 import BaseClockTime from '../utils/datetime/BaseClockTime.js';
 import CalendarDate from '../utils/datetime/CalendarDate.js';
@@ -108,6 +108,7 @@ export default class DreamApp {
             nullFlattenedSerializerKeysOfOtherVariants,
             nullFlattenedOpenapiKeys,
             nullFlattenedOpenapiKeysOfOtherVariants,
+            flattenedOpenapiVariants,
             serializerNameFromFullyQualifiedModelName,
             autogeneratedFileDisclaimer,
         };
@@ -272,6 +273,28 @@ export default class DreamApp {
     get importExtension() {
         return this._importExtension;
     }
+    _importAliasPrefix = '@';
+    /**
+     * The prefix of the import aliases the CLI generators write: the `@` in
+     * `@models/User.js`, `@serializers/UserSerializer.js` and
+     * `@spec/factories/UserFactory.js`. Set with
+     * `dreamApp.set('importAliasPrefix', '#')` to have them write
+     * `#models/User.js` and so on, which Node resolves as subpath imports
+     * declared under `imports` in the app's package.json.
+     *
+     * Defaults to `@`. The default becomes `#` in Dream 3; an app that wants
+     * to keep `@` should set it explicitly with
+     * `dreamApp.set('importAliasPrefix', '@')`.
+     *
+     * Psychic's resource controller-spec generator still writes its
+     * `@spec/unit/helpers/authentication.js` import with a literal `@` until
+     * Psychic reads this setting (planned for 3.17.0), so a Psychic app should
+     * keep its `@spec` alias, or wait for that release, before switching to
+     * `#` only.
+     */
+    get importAliasPrefix() {
+        return this._importAliasPrefix;
+    }
     /**
      * if set to true, it will bypass deprecation checks that run
      * during the sync hook. Defaults to false, we only recommend
@@ -482,6 +505,9 @@ export default class DreamApp {
             case 'importExtension':
                 this._importExtension = options;
                 break;
+            case 'importAliasPrefix':
+                this._importAliasPrefix = options;
+                break;
             case 'logger':
                 this._logger = options;
                 break;
@@ -608,3 +634,7 @@ export const DreamAppAllowedPackageManagersEnumValues = ['pnpm', 'yarn', 'npm',
 // to style import suffixes. When integrating with other apps, this
 // suffix style can change, and may need to be configured.
 export const GeneratorImportStyles = ['.js', '.ts', 'none'];
+// GeneratorImportAliasPrefixes are used by CLI generators to determine the
+// prefix of the import aliases they write (`@models/User.js` vs
+// `#models/User.js`). The default is `@`; it becomes `#` in Dream 3.
+export const GeneratorImportAliasPrefixes = ['@', '#'];

package/dist/cjs/src/helpers/areEqual.js

@@ -28,7 +28,7 @@ function areEqualOrUndefined(a, b) {
     if (typeof a === 'boolean')
         return a === b;
     if (typeof a === 'number')
-        return a === b;
+        return a === b || (Number.isNaN(a) && Number.isNaN(b));
     if (typeof a === 'string')
         return a === b;
     if (a instanceof DateTime)
@@ -40,7 +40,7 @@ function areEqualOrUndefined(a, b) {
     if (a instanceof ClockTimeTz)
         return b instanceof ClockTimeTz && a.equals(b);
     if (Array.isArray(a))
-        return Array.isArray(b) && a.length === b.length && !a.find((value, index) => !areEqual(value, b[index]));
+        return Array.isArray(b) && a.length === b.length && a.every((value, index) => areEqual(value, b[index]));
     if (a instanceof Dream)
         return a.equals(b);
     return undefined;

package/dist/cjs/src/helpers/path/absoluteDreamPath.js

@@ -1,3 +1,4 @@
+import DreamApp from '../../dream-app/index.js';
 import addImportSuffix from '../cli/addImportSuffix.js';
 import pascalize from '../pascalize.js';
 export default function absoluteDreamPath(destinationDreamPathType, fullyQualifiedDestinationModelName) {
@@ -13,13 +14,14 @@ export default function absoluteDreamPath(destinationDreamPathType, fullyQualifi
     }
 }
 function rootPath(destinationDreamPathType) {
+    const prefix = DreamApp.getOrFail().importAliasPrefix;
     switch (destinationDreamPathType) {
         case 'models':
-            return '@models/';
+            return `${prefix}models/`;
         case 'serializers':
-            return '@serializers/';
+            return `${prefix}serializers/`;
         case 'factories':
-            return '@spec/factories/';
+            return `${prefix}spec/factories/`;
         default: {
             // protection so that if a new DreamPaths is ever added, this will throw a type error at build time
             const _never = destinationDreamPathType;

package/dist/cjs/src/serializer/DreamSerializer.js

@@ -10,11 +10,11 @@ import DreamSerializerBuilder from './builders/DreamSerializerBuilder.js';
  *
  * A serializer must not read its data while being built: what it declares may not
  * depend on its data. Dream and Psychic build it without data to read its shape (the
- * OpenAPI schema, and the null and other-variant keys of a flattened association or
- * `customAttribute` that uses it), so a serializer that reads its data while being
- * built throws when a flattened association or `customAttribute` that uses it is
- * rendered. Read the data inside a `customAttribute` callback, which runs only when
- * the serializer renders, not while it is built.
+ * OpenAPI schema, and the keys a flattened association or `customAttribute` that uses
+ * it renders as `null` where its value does not supply them), so a serializer that
+ * reads its data while being built throws when a flattened association or
+ * `customAttribute` that uses it is rendered. Read the data inside a `customAttribute`
+ * callback, which runs only when the serializer renders, not while it is built.
  *
  * @param dreamClass - The Dream model class the serializer renders
  * @param data - The Dream instance to render

package/dist/cjs/src/serializer/ObjectSerializer.js

@@ -10,11 +10,11 @@ import ObjectSerializerBuilder from './builders/ObjectSerializerBuilder.js';
  *
  * A serializer must not read its data while being built: what it declares may not
  * depend on its data. Dream and Psychic build it without data to read its shape (the
- * OpenAPI schema, and the null and other-variant keys of a flattened association or
- * `customAttribute` that uses it), so a serializer that reads its data while being
- * built throws when a flattened association or `customAttribute` that uses it is
- * rendered. Read the data inside a `customAttribute` callback, which runs only when
- * the serializer renders, not while it is built.
+ * OpenAPI schema, and the keys a flattened association or `customAttribute` that uses
+ * it renders as `null` where its value does not supply them), so a serializer that
+ * reads its data while being built throws when a flattened association or
+ * `customAttribute` that uses it is rendered. Read the data inside a `customAttribute`
+ * callback, which runs only when the serializer renders, not while it is built.
  *
  * @param data - The object to render
  * @param passthroughData - Data available to this serializer and passed down to the serializers

package/dist/cjs/src/serializer/SerializerRenderer.js

@@ -9,7 +9,7 @@ import { DateTime } from '../utils/datetime/DateTime.js';
 import DreamSerializerBuilder from './builders/DreamSerializerBuilder.js';
 import ObjectSerializerBuilder from './builders/ObjectSerializerBuilder.js';
 import inferSerializerFromDreamOrViewModel from './helpers/inferSerializerFromDreamOrViewModel.js';
-import { nullFlattenedOpenapiKeys, nullFlattenedOpenapiKeysForValue, nullFlattenedSerializerKeys, nullFlattenedSerializerKeysOfOtherVariants, } from './helpers/nullFlattenedSerializerKeys.js';
+import { nullFlattenedOpenapiKeys, nullFlattenedSerializerKeys, } from './helpers/nullFlattenedSerializerKeys.js';
 import { serializersForAssociatedClass } from './helpers/serializersForAssociatedClass.js';
 export default class SerializerRenderer {
     serializerBuilder;
@@ -79,29 +79,27 @@ export default class SerializerRenderer {
                         return accumulator;
                     if (attribute.options.flatten) {
                         const flattenOptions = { casing: this.renderOpts.casing, passthroughData };
-                        // a flattened customAttribute's keys are the parent's own keys, cased like them: a
-                        // callback that returns null or undefined, or a serializer built over null or undefined
-                        // data (which renders null), renders each key its openapi requires as null, as a null
-                        // flattened rendersOne does, and one that returns a value of one variant of its openapi
-                        // renders as null each key another variant requires that the rendered one does not
-                        // declare, and each key the rendered one requires that a returned plain object leaves out
+                        // a flattened customAttribute's keys are the parent's own keys, cased like them, and
+                        // always include each key any shape of its openapi requires: a callback that returns
+                        // null or undefined, or a serializer built over null or undefined data (which renders
+                        // null), renders each of them as null, as a null flattened rendersOne does, and a
+                        // present value renders its own keys over them, so a required key it leaves out is null
                         const valueIsSerializerBuilder = value instanceof DreamSerializerBuilder || value instanceof ObjectSerializerBuilder;
                         const valueRendersNull = value === null ||
                             value === undefined ||
                             (valueIsSerializerBuilder &&
                                 (value['data'] ?? null) === null);
+                        const nullRequiredKeys = nullFlattenedOpenapiKeys(attribute.options.openapi, flattenOptions);
                         if (valueRendersNull)
-                            return {
-                                ...accumulator,
-                                ...nullFlattenedOpenapiKeys(attribute.options.openapi, flattenOptions),
-                            };
+                            return { ...accumulator, ...nullRequiredKeys };
                         const renderedValue = applyRenderingOptionsToAttribute(null, value, attribute.name, {}, this.passthroughData, this.renderOpts);
                         return {
                             ...accumulator,
-                            ...nullFlattenedOpenapiKeysForValue(attribute.options.openapi, value, flattenOptions),
+                            ...nullRequiredKeys,
                             // a returned serializer renders its keys in the render's casing; a returned plain
-                            // object's top-level keys are cased here, its nested values left as returned
-                            ...(valueIsSerializerBuilder ? renderedValue : this.setCaseOfKeys(renderedValue)),
+                            // object's top-level keys are cased here, its nested values left as returned, and a
+                            // key it sets to undefined is skipped, so a required key renders null beneath it
+                            ...(valueIsSerializerBuilder ? renderedValue : this.setCaseOfDefinedKeys(renderedValue)),
                         };
                     }
                     else {
@@ -118,12 +116,6 @@ export default class SerializerRenderer {
                 case 'rendersOne': {
                     const outputAttributeName = this.setCase(attribute.options.as ?? attribute.name);
                     const associatedObject = data[attribute.name];
-                    if (!associatedObject && attribute.options.flatten) {
-                        return {
-                            ...accumulator,
-                            ...nullFlattenedSerializerKeys(serializersForAssociatedClass(data instanceof Dream ? data.constructor : null, attribute.name, attribute.options), { casing: this.renderOpts.casing, passthroughData }),
-                        };
-                    }
                     const serializer = associatedObject
                         ? serializerForAssociatedObject(associatedObject, attribute.options, renderTimeResolutionContext(attribute.options, 'rendersOne', attribute.name))
                         : null;
@@ -134,12 +126,11 @@ export default class SerializerRenderer {
                     if (attribute.options.flatten) {
                         return {
                             ...accumulator,
-                            // every payload carries the keys of every serializer the association may render with
-                            // (each STI child, each polymorphic target), so each key another one requires that the
-                            // rendered one does not declare renders as null
-                            ...(serializer
-                                ? nullFlattenedSerializerKeysOfOtherVariants(serializersForAssociatedClass(data instanceof Dream ? data.constructor : null, attribute.name, attribute.options), serializer, { casing: this.renderOpts.casing, passthroughData })
-                                : {}),
+                            // a flattened rendersOne always renders each key any serializer the association may
+                            // render with (each STI child, each polymorphic target) requires: as null when the
+                            // associated object is null, and beneath the rendered serializer's own keys when it is
+                            // present, so a required key the rendered serializer leaves out renders as null
+                            ...nullFlattenedSerializerKeys(serializersForAssociatedClass(data instanceof Dream ? data.constructor : null, attribute.name, attribute.options), { casing: this.renderOpts.casing, passthroughData }),
                             // passthrough data must be passed both into the serializer and render
                             // because, if the serializer does accept passthrough data, then passing it in is how
                             // it gets into the serializer, but if it does not accept passthrough data, and therefore
@@ -204,11 +195,13 @@ export default class SerializerRenderer {
         }, renderedAttributes);
         return renderedAttributes;
     }
-    setCaseOfKeys(value) {
+    setCaseOfDefinedKeys(value) {
         if (typeof value !== 'object' || value === null || Array.isArray(value))
             return value;
         return Object.keys(value).reduce((casedValue, key) => {
-            casedValue[this.setCase(key)] = value[key];
+            const keyValue = value[key];
+            if (keyValue !== undefined)
+                casedValue[this.setCase(key)] = keyValue;
             return casedValue;
         }, {});
     }

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

@@ -110,28 +110,29 @@ export default class DreamSerializerBuilder {
      *   - `openapi` - (required) OpenAPI schema definition for the computed value
      *   - `flatten` - When `true`, spreads the returned object's properties directly into the
      *     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` return, a serializer built over
-     *     `null` or `undefined` data, or an `undefined` return without `required: false` renders as
-     *     `null` each key the `openapi` requires: a key an object shape lists in its `required`
-     *     array, a key a `$serializer` or `$serializable` ref's serializer declares without
-     *     `required: false`, and each such key of an `allOf`, `anyOf` or `oneOf` member. Its
-     *     optional keys stay absent, and an `undefined` return with `required: false` adds no keys.
-     *     A returned plain object also renders as `null` each key its shape requires that it
-     *     leaves out, and its optional keys it leaves out stay absent. When the `openapi` is an
-     *     `anyOf` or `oneOf`, or a `$serializable` ref to an STI base, a present value also renders
-     *     as `null` each key another variant requires that the rendered one does not declare, so a
-     *     client sees the same keys whichever variant is rendered.
+     *     then describes the whole returned object, not each property: 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. Whatever the callback
+     *     returns, each key any shape of the `openapi` requires renders, as `null` wherever the
+     *     value does not supply it (a returned plain object's key set to `undefined` does not
+     *     supply it): a key an object shape lists in its `required` array, a key a `$serializer` or
+     *     `$serializable` ref's serializer declares without `required: false` (for an STI base,
+     *     any child's serializer), and each such key of any `allOf`, `anyOf` or `oneOf` member. So
+     *     a `null` return, a serializer built over `null` or `undefined` data, or an `undefined`
+     *     return without `required: false` renders each of them as `null`, and a present value
+     *     renders its own keys over them, so a key another shape requires renders as `null` even
+     *     when the value's own shape leaves it optional; the payload always includes the same
+     *     keys whichever shape the value takes and whether it is null. An optional key no shape
+     *     requires stays absent unless the value supplies it, and an `undefined` return with
+     *     `required: false` adds no keys.
      *     Every key it adds follows the render's casing like the parent's own keys: a returned
      *     plain object's top-level keys and the `openapi`'s `properties` keys are cased (so
      *     `casing: 'snake'` renders `phoneNumber` as `phone_number`, present or `null`), while
-     *     nested values render as returned. 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
+     *     nested values render as returned. Attributes render in declaration order, so a key the
+     *     returned object shares with another attribute takes the value of whichever is declared
+     *     later, and that value must match both the attribute's declaration and the `openapi`'s
      *   - `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
@@ -181,23 +182,29 @@ export default class DreamSerializerBuilder {
      *     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`, each key its serializer requires renders as `null`: an
-     *     attribute, delegatedAttribute or customAttribute declared without `required: false`, and
-     *     every non-flattened `rendersOne` and `rendersMany` (for a polymorphic `BelongsTo`, each
-     *     key the serializer of any of its target classes requires, and for an association to an
-     *     STI base, each key the serializer of any of its STI children requires), in the same order
-     *     (so an `id` declared before the `rendersOne` becomes `null`), while a key declared with
-     *     `required: false` stays absent. A flattened `customAttribute` in that serializer adds the
+     *     Each key its serializer requires always renders, as `null` wherever the association
+     *     does not supply it: an attribute, delegatedAttribute or customAttribute declared without
+     *     `required: false`, and every non-flattened `rendersOne` and `rendersMany` (for a
+     *     polymorphic `BelongsTo`, each key the serializer of any of its target classes requires,
+     *     and for an association to an STI base, each key the serializer of any of its STI children
+     *     requires), in the same order (so an `id` declared before the `rendersOne` becomes `null`
+     *     when the association is `null`). A flattened `customAttribute` in that serializer adds the
      *     keys its `openapi` requires: a key an object shape lists in its `required` array, a key a
      *     `$serializer` or `$serializable` ref's serializer declares without `required: false`, and
      *     each such key of an `allOf`, `anyOf` or `oneOf` member; a ref with `many: true` adds none,
-     *     and a flattened `customAttribute` declared with `required: false` adds none. Nothing in
-     *     that serializer is rendered, so its custom attribute callbacks do not run. When the
-     *     association to an STI base or polymorphic `BelongsTo` is present, each key another STI
-     *     child's or target's serializer requires that the held one's serializer does not declare
-     *     also renders as `null`, so a client sees the same keys whichever is held. 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
+     *     and a flattened `customAttribute` declared with `required: false` adds none. When the
+     *     association is `null`, each of these keys renders as `null` and nothing in its serializer
+     *     is rendered, so its custom attribute callbacks do not run. When it is present, the held
+     *     object's serializer renders its own keys over them, so a key another STI child's or
+     *     target's serializer requires renders as `null` where the held one's serializer does not
+     *     render it, including a key that serializer declares with `required: false`; the payload
+     *     always includes the same keys whichever is held and, for an association or a property
+     *     given a `serializer` or `viewModelClass` option, whether it is `null` (a `null` property
+     *     that is not an association and has neither option renders none of these keys, since no
+     *     serializer is known for it). A key declared with `required: false` that no serializer
+     *     requires stays absent unless it renders. The association's OpenAPI schema describes the
+     *     parent's payload too, so a shared key's value must match both the parent's declaration
+     *     and the association's, 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/builders/ObjectSerializerBuilder.js

@@ -146,28 +146,29 @@ export default class ObjectSerializerBuilder {
      *   - `openapi` - (required) OpenAPI schema definition for the computed value
      *   - `flatten` - When `true`, spreads the returned object's properties directly into the
      *     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` return, a serializer built over
-     *     `null` or `undefined` data, or an `undefined` return without `required: false` renders as
-     *     `null` each key the `openapi` requires: a key an object shape lists in its `required`
-     *     array, a key a `$serializer` or `$serializable` ref's serializer declares without
-     *     `required: false`, and each such key of an `allOf`, `anyOf` or `oneOf` member. Its
-     *     optional keys stay absent, and an `undefined` return with `required: false` adds no keys.
-     *     A returned plain object also renders as `null` each key its shape requires that it
-     *     leaves out, and its optional keys it leaves out stay absent. When the `openapi` is an
-     *     `anyOf` or `oneOf`, or a `$serializable` ref to an STI base, a present value also renders
-     *     as `null` each key another variant requires that the rendered one does not declare, so a
-     *     client sees the same keys whichever variant is rendered.
+     *     then describes the whole returned object, not each property: 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. Whatever the callback
+     *     returns, each key any shape of the `openapi` requires renders, as `null` wherever the
+     *     value does not supply it (a returned plain object's key set to `undefined` does not
+     *     supply it): a key an object shape lists in its `required` array, a key a `$serializer` or
+     *     `$serializable` ref's serializer declares without `required: false` (for an STI base,
+     *     any child's serializer), and each such key of any `allOf`, `anyOf` or `oneOf` member. So
+     *     a `null` return, a serializer built over `null` or `undefined` data, or an `undefined`
+     *     return without `required: false` renders each of them as `null`, and a present value
+     *     renders its own keys over them, so a key another shape requires renders as `null` even
+     *     when the value's own shape leaves it optional; the payload always includes the same
+     *     keys whichever shape the value takes and whether it is null. An optional key no shape
+     *     requires stays absent unless the value supplies it, and an `undefined` return with
+     *     `required: false` adds no keys.
      *     Every key it adds follows the render's casing like the parent's own keys: a returned
      *     plain object's top-level keys and the `openapi`'s `properties` keys are cased (so
      *     `casing: 'snake'` renders `phoneNumber` as `phone_number`, present or `null`), while
-     *     nested values render as returned. 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
+     *     nested values render as returned. Attributes render in declaration order, so a key the
+     *     returned object shares with another attribute takes the value of whichever is declared
+     *     later, and that value must match both the attribute's declaration and the `openapi`'s
      *   - `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
@@ -217,23 +218,27 @@ export default class ObjectSerializerBuilder {
      *     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`, each key its serializer requires renders as `null`: an
-     *     attribute, delegatedAttribute or customAttribute declared without `required: false`, and
-     *     every non-flattened `rendersOne` and `rendersMany` (for a polymorphic `BelongsTo`, each
-     *     key the serializer of any of its target classes requires, and for an association to an
-     *     STI base, each key the serializer of any of its STI children requires), in the same order
-     *     (so an `id` declared before the `rendersOne` becomes `null`), while a key declared with
-     *     `required: false` stays absent. A flattened `customAttribute` in that serializer adds the
+     *     Each key its serializer requires always renders, as `null` wherever the association
+     *     does not supply it: an attribute, delegatedAttribute or customAttribute declared without
+     *     `required: false`, and every non-flattened `rendersOne` and `rendersMany` (for a
+     *     polymorphic `BelongsTo`, each key the serializer of any of its target classes requires,
+     *     and for an association to an STI base, each key the serializer of any of its STI children
+     *     requires), in the same order (so an `id` declared before the `rendersOne` becomes `null`
+     *     when the association is `null`). A flattened `customAttribute` in that serializer adds the
      *     keys its `openapi` requires: a key an object shape lists in its `required` array, a key a
      *     `$serializer` or `$serializable` ref's serializer declares without `required: false`, and
      *     each such key of an `allOf`, `anyOf` or `oneOf` member; a ref with `many: true` adds none,
-     *     and a flattened `customAttribute` declared with `required: false` adds none. Nothing in
-     *     that serializer is rendered, so its custom attribute callbacks do not run. When the
-     *     association to an STI base or polymorphic `BelongsTo` is present, each key another STI
-     *     child's or target's serializer requires that the held one's serializer does not declare
-     *     also renders as `null`, so a client sees the same keys whichever is held. 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
+     *     and a flattened `customAttribute` declared with `required: false` adds none. When the
+     *     association is `null`, each of these keys renders as `null` and nothing in its serializer
+     *     is rendered, so its custom attribute callbacks do not run. When it is present, the held
+     *     object's serializer renders its own keys over them, so a key another STI child's or
+     *     target's serializer requires renders as `null` where the held one's serializer does not
+     *     render it, including a key that serializer declares with `required: false`; the payload
+     *     always includes the same keys whichever is held and whether the association is `null`. A
+     *     key declared with `required: false` that no serializer requires stays absent unless it
+     *     renders. The association's OpenAPI schema describes the parent's payload too, so a shared
+     *     key's value must match both the parent's declaration and the association's, 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