@rvoh/dream 2.40.1 → 2.40.2

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

@@ -270,6 +270,16 @@ export default class DreamApp {
         return this._packageManager;
     }
     _importExtension = '.js';
+    /**
+     * The import suffix the CLI generators write: `.js`, `.ts` or `none`.
+     *
+     * In a Psychic app, set it in conf/app.ts with
+     * `psy.set('importExtension', …)`. Psychic forwards it here, and a different
+     * value set in conf/dream.ts throws at boot. In a Dream-only app, set it in
+     * conf/dream.ts with `dreamApp.set('importExtension', …)`.
+     *
+     * Defaults to `.js`.
+     */
     get importExtension() {
         return this._importExtension;
     }
@@ -277,20 +287,17 @@ export default class DreamApp {
     /**
      * 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
+     * `@spec/factories/UserFactory.js`. Set it to `#` 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', '@')`.
+     * In a Psychic app, set it in conf/app.ts with
+     * `psy.set('importAliasPrefix', '#')`. Psychic forwards it here, and a
+     * different value set in conf/dream.ts throws at boot. In a Dream-only app,
+     * set it in conf/dream.ts 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.
+     * Defaults to `@`. The default becomes `#` in Dream 3; an app that wants
+     * to keep `@` should set it to `@` explicitly.
      */
     get importAliasPrefix() {
         return this._importAliasPrefix;

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

@@ -8,18 +8,24 @@ import DreamSerializerBuilder from './builders/DreamSerializerBuilder.js';
  *   DreamSerializer(User, user).attribute('email').rendersMany('posts')
  * ```
  *
- * 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 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.
+ * A serializer must not read its data or its passthrough data while being built: what it
+ * declares (which keys, under which names, and which associations it renders) may not
+ * depend on either. Dream and Psychic build it without data to read its shape (the OpenAPI
+ * schema, the associations `preloadFor` loads, and the keys a flattened association or
+ * `customAttribute` that uses it renders as `null` where its value does not supply them),
+ * and without passthrough data when registering it, preloading and generating OpenAPI. A
+ * serializer that reads its data while being built throws when a flattened association or
+ * `customAttribute` that uses it is rendered; one that reads its passthrough data is never
+ * registered, or renders keys and associations its OpenAPI schema and `preloadFor` do not
+ * describe. Read either inside a `customAttribute` callback, which runs only when the
+ * serializer renders, not while it is built, and hand passthrough data on to the
+ * serializers it renders.
  *
  * @param dreamClass - The Dream model class the serializer renders
  * @param data - The Dream instance to render
- * @param passthroughData - Data available to this serializer and passed down to the serializers
- *   it renders
+ * @param passthroughData - Data available to this serializer's callbacks when it renders,
+ *   and passed down to the serializers it renders. It must not decide what the serializer
+ *   declares.
  * @returns The serializer builder for method chaining
  */
 export default function DreamSerializer(dreamClass, data, passthroughData) {

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

@@ -8,17 +8,23 @@ import ObjectSerializerBuilder from './builders/ObjectSerializerBuilder.js';
  *   ObjectSerializer(address).attribute('city', { openapi: 'string' })
  * ```
  *
- * 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 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.
+ * A serializer must not read its data or its passthrough data while being built: what it
+ * declares (which keys, under which names, and which associations it renders) may not
+ * depend on either. Dream and Psychic build it without data to read its shape (the OpenAPI
+ * schema, the associations `preloadFor` loads, and the keys a flattened association or
+ * `customAttribute` that uses it renders as `null` where its value does not supply them),
+ * and without passthrough data when registering it, preloading and generating OpenAPI. A
+ * serializer that reads its data while being built throws when a flattened association or
+ * `customAttribute` that uses it is rendered; one that reads its passthrough data is never
+ * registered, or renders keys and associations its OpenAPI schema and `preloadFor` do not
+ * describe. Read either inside a `customAttribute` callback, which runs only when the
+ * serializer renders, not while it is built, and hand passthrough data on to the
+ * serializers it renders.
  *
  * @param data - The object to render
- * @param passthroughData - Data available to this serializer and passed down to the serializers
- *   it renders
+ * @param passthroughData - Data available to this serializer's callbacks when it renders,
+ *   and passed down to the serializers it renders. It must not decide what the serializer
+ *   declares.
  * @returns The serializer builder for method chaining
  */
 export default function ObjectSerializer(data, passthroughData) {

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

@@ -78,7 +78,7 @@ export default class SerializerRenderer {
                     if (value === undefined && attribute.options?.required === false)
                         return accumulator;
                     if (attribute.options.flatten) {
-                        const flattenOptions = { casing: this.renderOpts.casing, passthroughData };
+                        const flattenOptions = { casing: this.renderOpts.casing };
                         // 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
@@ -130,7 +130,7 @@ export default class SerializerRenderer {
                             // 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 }),
+                            ...nullFlattenedSerializerKeys(serializersForAssociatedClass(data instanceof Dream ? data.constructor : null, attribute.name, attribute.options), { casing: this.renderOpts.casing }),
                             // 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

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

@@ -30,8 +30,9 @@ import { serializersForAssociatedClass } from './serializersForAssociatedClass.j
  * flattens itself, adds nothing, so the walk always terminates; one reached again along another
  * path is walked again, so each path adds its keys and their requirements.
  *
- * `passthroughData` is handed to each serializer as it is built, as when rendering; outside a
- * render it may be left out.
+ * Each serializer is built with empty passthrough data, as Psychic's OpenAPI generation builds it,
+ * so the keys are the same whatever passthrough data a render carries: what a serializer declares
+ * must not depend on its passthrough data.
  */
 export function nullFlattenedSerializerKeys(serializers, options = {}) {
     return nullRequiredKeys(walkSerializers(serializers, newWalk(options)));
@@ -105,8 +106,8 @@ export function flattenedOpenapiVariants(openapi) {
     const sharedMembers = ('allOf' in openapi && openapi.allOf) || [];
     return sharedMembers.length ? variants.map(variant => ({ allOf: [...sharedMembers, variant] })) : variants;
 }
-function newWalk({ casing = 'camel', passthroughData = {}, }) {
-    return { casing, passthroughData, serializersBeingFlattened: new Set() };
+function newWalk({ casing = 'camel' }) {
+    return { casing, serializersBeingFlattened: new Set() };
 }
 function nullRequiredKeys(requirements) {
     return Object.keys(requirements).reduce((keys, key) => {
@@ -139,7 +140,7 @@ function walkSerializers(serializers, walk) {
         if (walk.serializersBeingFlattened.has(serializer))
             return flattenedKeys;
         walk.serializersBeingFlattened.add(serializer);
-        const serializerBuilder = serializer(undefined, walk.passthroughData);
+        const serializerBuilder = serializer(undefined, {});
         const serializerKeys = walkSerializerBuilder(serializerBuilder, walk);
         walk.serializersBeingFlattened.delete(serializer);
         return mergeRequirements(flattenedKeys, serializerKeys);

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

@@ -270,6 +270,16 @@ export default class DreamApp {
         return this._packageManager;
     }
     _importExtension = '.js';
+    /**
+     * The import suffix the CLI generators write: `.js`, `.ts` or `none`.
+     *
+     * In a Psychic app, set it in conf/app.ts with
+     * `psy.set('importExtension', …)`. Psychic forwards it here, and a different
+     * value set in conf/dream.ts throws at boot. In a Dream-only app, set it in
+     * conf/dream.ts with `dreamApp.set('importExtension', …)`.
+     *
+     * Defaults to `.js`.
+     */
     get importExtension() {
         return this._importExtension;
     }
@@ -277,20 +287,17 @@ export default class DreamApp {
     /**
      * 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
+     * `@spec/factories/UserFactory.js`. Set it to `#` 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', '@')`.
+     * In a Psychic app, set it in conf/app.ts with
+     * `psy.set('importAliasPrefix', '#')`. Psychic forwards it here, and a
+     * different value set in conf/dream.ts throws at boot. In a Dream-only app,
+     * set it in conf/dream.ts 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.
+     * Defaults to `@`. The default becomes `#` in Dream 3; an app that wants
+     * to keep `@` should set it to `@` explicitly.
      */
     get importAliasPrefix() {
         return this._importAliasPrefix;

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

@@ -8,18 +8,24 @@ import DreamSerializerBuilder from './builders/DreamSerializerBuilder.js';
  *   DreamSerializer(User, user).attribute('email').rendersMany('posts')
  * ```
  *
- * 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 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.
+ * A serializer must not read its data or its passthrough data while being built: what it
+ * declares (which keys, under which names, and which associations it renders) may not
+ * depend on either. Dream and Psychic build it without data to read its shape (the OpenAPI
+ * schema, the associations `preloadFor` loads, and the keys a flattened association or
+ * `customAttribute` that uses it renders as `null` where its value does not supply them),
+ * and without passthrough data when registering it, preloading and generating OpenAPI. A
+ * serializer that reads its data while being built throws when a flattened association or
+ * `customAttribute` that uses it is rendered; one that reads its passthrough data is never
+ * registered, or renders keys and associations its OpenAPI schema and `preloadFor` do not
+ * describe. Read either inside a `customAttribute` callback, which runs only when the
+ * serializer renders, not while it is built, and hand passthrough data on to the
+ * serializers it renders.
  *
  * @param dreamClass - The Dream model class the serializer renders
  * @param data - The Dream instance to render
- * @param passthroughData - Data available to this serializer and passed down to the serializers
- *   it renders
+ * @param passthroughData - Data available to this serializer's callbacks when it renders,
+ *   and passed down to the serializers it renders. It must not decide what the serializer
+ *   declares.
  * @returns The serializer builder for method chaining
  */
 export default function DreamSerializer(dreamClass, data, passthroughData) {

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

@@ -8,17 +8,23 @@ import ObjectSerializerBuilder from './builders/ObjectSerializerBuilder.js';
  *   ObjectSerializer(address).attribute('city', { openapi: 'string' })
  * ```
  *
- * 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 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.
+ * A serializer must not read its data or its passthrough data while being built: what it
+ * declares (which keys, under which names, and which associations it renders) may not
+ * depend on either. Dream and Psychic build it without data to read its shape (the OpenAPI
+ * schema, the associations `preloadFor` loads, and the keys a flattened association or
+ * `customAttribute` that uses it renders as `null` where its value does not supply them),
+ * and without passthrough data when registering it, preloading and generating OpenAPI. A
+ * serializer that reads its data while being built throws when a flattened association or
+ * `customAttribute` that uses it is rendered; one that reads its passthrough data is never
+ * registered, or renders keys and associations its OpenAPI schema and `preloadFor` do not
+ * describe. Read either inside a `customAttribute` callback, which runs only when the
+ * serializer renders, not while it is built, and hand passthrough data on to the
+ * serializers it renders.
  *
  * @param data - The object to render
- * @param passthroughData - Data available to this serializer and passed down to the serializers
- *   it renders
+ * @param passthroughData - Data available to this serializer's callbacks when it renders,
+ *   and passed down to the serializers it renders. It must not decide what the serializer
+ *   declares.
  * @returns The serializer builder for method chaining
  */
 export default function ObjectSerializer(data, passthroughData) {

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

@@ -78,7 +78,7 @@ export default class SerializerRenderer {
                     if (value === undefined && attribute.options?.required === false)
                         return accumulator;
                     if (attribute.options.flatten) {
-                        const flattenOptions = { casing: this.renderOpts.casing, passthroughData };
+                        const flattenOptions = { casing: this.renderOpts.casing };
                         // 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
@@ -130,7 +130,7 @@ export default class SerializerRenderer {
                             // 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 }),
+                            ...nullFlattenedSerializerKeys(serializersForAssociatedClass(data instanceof Dream ? data.constructor : null, attribute.name, attribute.options), { casing: this.renderOpts.casing }),
                             // 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

package/dist/esm/src/serializer/helpers/nullFlattenedSerializerKeys.js

@@ -30,8 +30,9 @@ import { serializersForAssociatedClass } from './serializersForAssociatedClass.j
  * flattens itself, adds nothing, so the walk always terminates; one reached again along another
  * path is walked again, so each path adds its keys and their requirements.
  *
- * `passthroughData` is handed to each serializer as it is built, as when rendering; outside a
- * render it may be left out.
+ * Each serializer is built with empty passthrough data, as Psychic's OpenAPI generation builds it,
+ * so the keys are the same whatever passthrough data a render carries: what a serializer declares
+ * must not depend on its passthrough data.
  */
 export function nullFlattenedSerializerKeys(serializers, options = {}) {
     return nullRequiredKeys(walkSerializers(serializers, newWalk(options)));
@@ -105,8 +106,8 @@ export function flattenedOpenapiVariants(openapi) {
     const sharedMembers = ('allOf' in openapi && openapi.allOf) || [];
     return sharedMembers.length ? variants.map(variant => ({ allOf: [...sharedMembers, variant] })) : variants;
 }
-function newWalk({ casing = 'camel', passthroughData = {}, }) {
-    return { casing, passthroughData, serializersBeingFlattened: new Set() };
+function newWalk({ casing = 'camel' }) {
+    return { casing, serializersBeingFlattened: new Set() };
 }
 function nullRequiredKeys(requirements) {
     return Object.keys(requirements).reduce((keys, key) => {
@@ -139,7 +140,7 @@ function walkSerializers(serializers, walk) {
         if (walk.serializersBeingFlattened.has(serializer))
             return flattenedKeys;
         walk.serializersBeingFlattened.add(serializer);
-        const serializerBuilder = serializer(undefined, walk.passthroughData);
+        const serializerBuilder = serializer(undefined, {});
         const serializerKeys = walkSerializerBuilder(serializerBuilder, walk);
         walk.serializersBeingFlattened.delete(serializer);
         return mergeRequirements(flattenedKeys, serializerKeys);

package/dist/types/src/dream-app/index.d.ts

@@ -159,25 +159,32 @@ export default class DreamApp {
     private _packageManager;
     get packageManager(): "pnpm" | "yarn" | "npm" | "bun" | "deno";
     private _importExtension;
+    /**
+     * The import suffix the CLI generators write: `.js`, `.ts` or `none`.
+     *
+     * In a Psychic app, set it in conf/app.ts with
+     * `psy.set('importExtension', …)`. Psychic forwards it here, and a different
+     * value set in conf/dream.ts throws at boot. In a Dream-only app, set it in
+     * conf/dream.ts with `dreamApp.set('importExtension', …)`.
+     *
+     * Defaults to `.js`.
+     */
     get importExtension(): ".js" | ".ts" | "none";
     private _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
+     * `@spec/factories/UserFactory.js`. Set it to `#` 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.
      *
+     * In a Psychic app, set it in conf/app.ts with
+     * `psy.set('importAliasPrefix', '#')`. Psychic forwards it here, and a
+     * different value set in conf/dream.ts throws at boot. In a Dream-only app,
+     * set it in conf/dream.ts with `dreamApp.set('importAliasPrefix', '#')`.
+     *
      * 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.
+     * to keep `@` should set it to `@` explicitly.
      */
     get importAliasPrefix(): "@" | "#";
     /**

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

@@ -9,18 +9,24 @@ import DreamSerializerBuilder from './builders/DreamSerializerBuilder.js';
  *   DreamSerializer(User, user).attribute('email').rendersMany('posts')
  * ```
  *
- * 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 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.
+ * A serializer must not read its data or its passthrough data while being built: what it
+ * declares (which keys, under which names, and which associations it renders) may not
+ * depend on either. Dream and Psychic build it without data to read its shape (the OpenAPI
+ * schema, the associations `preloadFor` loads, and the keys a flattened association or
+ * `customAttribute` that uses it renders as `null` where its value does not supply them),
+ * and without passthrough data when registering it, preloading and generating OpenAPI. A
+ * serializer that reads its data while being built throws when a flattened association or
+ * `customAttribute` that uses it is rendered; one that reads its passthrough data is never
+ * registered, or renders keys and associations its OpenAPI schema and `preloadFor` do not
+ * describe. Read either inside a `customAttribute` callback, which runs only when the
+ * serializer renders, not while it is built, and hand passthrough data on to the
+ * serializers it renders.
  *
  * @param dreamClass - The Dream model class the serializer renders
  * @param data - The Dream instance to render
- * @param passthroughData - Data available to this serializer and passed down to the serializers
- *   it renders
+ * @param passthroughData - Data available to this serializer's callbacks when it renders,
+ *   and passed down to the serializers it renders. It must not decide what the serializer
+ *   declares.
  * @returns The serializer builder for method chaining
  */
 export default function DreamSerializer<DreamClass extends typeof Dream, DataType extends Dream | null, PassthroughDataType extends object | undefined = undefined>(dreamClass: DreamClass, data: DataType, passthroughData?: PassthroughDataType): DreamSerializerBuilder<DreamClass, DataType, PassthroughDataType, Exclude<DataType, null>>;

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

@@ -8,17 +8,23 @@ import ObjectSerializerBuilder from './builders/ObjectSerializerBuilder.js';
  *   ObjectSerializer(address).attribute('city', { openapi: 'string' })
  * ```
  *
- * 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 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.
+ * A serializer must not read its data or its passthrough data while being built: what it
+ * declares (which keys, under which names, and which associations it renders) may not
+ * depend on either. Dream and Psychic build it without data to read its shape (the OpenAPI
+ * schema, the associations `preloadFor` loads, and the keys a flattened association or
+ * `customAttribute` that uses it renders as `null` where its value does not supply them),
+ * and without passthrough data when registering it, preloading and generating OpenAPI. A
+ * serializer that reads its data while being built throws when a flattened association or
+ * `customAttribute` that uses it is rendered; one that reads its passthrough data is never
+ * registered, or renders keys and associations its OpenAPI schema and `preloadFor` do not
+ * describe. Read either inside a `customAttribute` callback, which runs only when the
+ * serializer renders, not while it is built, and hand passthrough data on to the
+ * serializers it renders.
  *
  * @param data - The object to render
- * @param passthroughData - Data available to this serializer and passed down to the serializers
- *   it renders
+ * @param passthroughData - Data available to this serializer's callbacks when it renders,
+ *   and passed down to the serializers it renders. It must not decide what the serializer
+ *   declares.
  * @returns The serializer builder for method chaining
  */
 export default function ObjectSerializer<DataType extends object | null, PassthroughDataType extends object | undefined = undefined>(data: DataType, passthroughData?: PassthroughDataType): ObjectSerializerBuilder<DataType, PassthroughDataType, Exclude<DataType, null>>;

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

@@ -2,7 +2,6 @@ import { OpenapiSchemaBodyShorthand, OpenapiShorthandPrimitiveTypes } from '../.
 import { DreamModelSerializerType, SerializerCasing, SimpleObjectSerializerType } from '../../types/serializer.js';
 export interface NullFlattenedSerializerKeysOptions {
     casing?: SerializerCasing;
-    passthroughData?: object;
 }
 /**
  * The keys a flattened `rendersOne` always adds to the parent's payload, returned as an object
@@ -32,8 +31,9 @@ export interface NullFlattenedSerializerKeysOptions {
  * flattens itself, adds nothing, so the walk always terminates; one reached again along another
  * path is walked again, so each path adds its keys and their requirements.
  *
- * `passthroughData` is handed to each serializer as it is built, as when rendering; outside a
- * render it may be left out.
+ * Each serializer is built with empty passthrough data, as Psychic's OpenAPI generation builds it,
+ * so the keys are the same whatever passthrough data a render carries: what a serializer declares
+ * must not depend on its passthrough data.
  */
 export declare function nullFlattenedSerializerKeys(serializers: (DreamModelSerializerType | SimpleObjectSerializerType)[], options?: NullFlattenedSerializerKeysOptions): Record<string, null>;
 /**