@rvoh/dream 2.38.0 → 2.40.0

package/dist/esm/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

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

@@ -1,17 +1,20 @@
 import snakeify from '../../helpers/snakeify.js';
 import DreamSerializerBuilder from '../builders/DreamSerializerBuilder.js';
-import ObjectSerializerBuilder from '../builders/ObjectSerializerBuilder.js';
 import { inferSerializersFromDreamClassOrViewModelClass } from './inferSerializerFromDreamOrViewModel.js';
 import { serializersForAssociatedClass } from './serializersForAssociatedClass.js';
 /**
- * The keys a flattened `rendersOne` adds to the parent's payload when its associated object is
- * null, returned as an object with each key set to `null`, ready to spread into the parent's
- * payload (`Object.keys` of it for the key names alone): each key one of `serializers` requires.
- * As a property read on an empty object is `undefined`, a null value carries no key it may omit:
- * an attribute, delegatedAttribute or customAttribute declared with `required: false` adds no key.
- * Every key is cased per `casing`, as the renderer cases it. There are several serializers when
- * the association is a polymorphic BelongsTo, one for each target class, or when the associated
- * class is an STI base, one for each child, and their required keys are unioned.
+ * The keys a flattened `rendersOne` always adds to the parent's payload, returned as an object
+ * with each key set to `null`, ready to spread into the parent's payload (`Object.keys` of it for
+ * the key names alone): each key one of `serializers` requires. When the associated object is
+ * null, these are the keys it renders; when it is present, the rendered serializer's own keys
+ * render over them, so each of these it leaves out stays `null` and the payload always includes
+ * these keys, whichever serializer renders and whether the object is null. As a property read on
+ * an empty object is `undefined`, a null value carries no key it may omit: an attribute,
+ * delegatedAttribute or customAttribute declared with `required: false` adds no key unless another
+ * of `serializers` requires it. Every key is cased per `casing`, as the renderer cases it. There
+ * are several serializers when the association is a polymorphic BelongsTo, one for each target
+ * class, or when the associated class is an STI base, one for each child, and their required keys
+ * are unioned.
  *
  * Each serializer is built with `undefined` data to read its declarations, as Psychic's OpenAPI
  * generation and `preloadFor` build it, and nothing is rendered: no attribute callback runs and
@@ -34,85 +37,58 @@ export function nullFlattenedSerializerKeys(serializers, options = {}) {
     return nullRequiredKeys(walkSerializers(serializers, newWalk(options)));
 }
 /**
- * The keys a flattened `customAttribute` with this `openapi` adds to the parent's payload when
+ * The keys a flattened `customAttribute` with this `openapi` always adds to the parent's payload,
+ * each set to `null`: each key any shape of `openapi` requires, walked as
+ * `nullFlattenedSerializerKeys` walks a flattened `customAttribute` and cased per `casing`. When
  * its callback returns null (or `undefined` without `required: false`), or a serializer built over
- * null data, each set to `null`: each key `openapi` requires, walked as `nullFlattenedSerializerKeys`
- * walks a flattened `customAttribute` and cased per `casing`.
+ * null data, these are the keys it renders; when it returns any other value, that value's own keys
+ * render over them, so each of these the value leaves out, or a returned plain object sets to
+ * `undefined`, stays `null`. With `required: false`, a callback that returns `undefined` adds none
+ * of them.
  */
 export function nullFlattenedOpenapiKeys(openapi, options = {}) {
     return nullRequiredKeys(walkOpenapi(openapi, newWalk(options)));
 }
 /**
- * The keys a present flattened `rendersOne` adds to the parent's payload, each set to `null`,
- * beside what `renderedSerializer` renders: each key one of `serializers` (every serializer the
- * association may render with) requires that `renderedSerializer` does not declare at all. A key
- * `renderedSerializer` declares is its own to render or, when `required: false`, to omit.
+ * The keys only the other variants of a flattened `rendersOne` contribute to its payload, each set
+ * to `null`: each key one of `serializers` (every serializer the association may render with)
+ * requires that `renderedSerializer` does not declare at all. A key `renderedSerializer` declares
+ * is left out even when it declares it with `required: false` and another serializer requires it;
+ * the renderer fills that key with `null` too, since it renders every key
+ * `nullFlattenedSerializerKeys` returns beneath the rendered serializer's own keys.
  */
 export function nullFlattenedSerializerKeysOfOtherVariants(serializers, renderedSerializer, options = {}) {
     return nullKeysRequiredByOthers(walkSerializers(serializers, newWalk(options)), Object.keys(walkSerializers([renderedSerializer], newWalk(options))));
 }
 /**
- * The keys a flattened `customAttribute` with this `openapi` adds to the parent's payload, each
- * set to `null`, when it renders `renderedVariant`: each key a variant of `openapi` requires that
+ * The keys only the other variants of a flattened `customAttribute` with this `openapi` contribute
+ * to its payload, each set to `null`: each key a variant of `openapi` requires that
  * `renderedVariant` does not declare. `renderedVariant` is any `openapi` shorthand: one member of
  * an `anyOf` or `oneOf`, or `{ $serializer: childSerializer }` for one child of a `$serializable`
  * ref to an STI base. A key requires its value when an object shape's `required` array lists it,
  * whether the shape's own `properties` declare it or a member of its `allOf`, `anyOf` or `oneOf`
- * does, or when a serializer declares it without `required: false`.
+ * does, or when a serializer declares it without `required: false`. A key `renderedVariant`
+ * declares is left out even when it is optional there and another variant requires it; the
+ * renderer fills that key with `null` too, since it renders every key `nullFlattenedOpenapiKeys`
+ * returns beneath the value's own keys.
  */
 export function nullFlattenedOpenapiKeysOfOtherVariants(openapi, renderedVariant, options = {}) {
     return nullKeysRequiredByOthers(walkOpenapi(openapi, newWalk(options)), Object.keys(walkOpenapi(renderedVariant, newWalk(options))));
 }
 /**
- * The keys a flattened `customAttribute` with this `openapi` adds to the parent's payload, each
- * set to `null`, beside the non-null `value` its callback returned, from which the rendered
- * variant is read. A serializer's declarations are the rendered variant, so a `$serializable` ref
- * to an STI base adds the keys of every other child, as `nullFlattenedOpenapiKeysOfOtherVariants`
- * reads them; the serializer renders each of its own keys. A plain object renders only the keys
- * it has, so it adds each key the rendered variant requires that the object leaves out as well as
- * each key another variant requires that the rendered one does not declare. An `openapi` with one
- * variant is the rendered one. Of several variants (the members of an `anyOf` or `oneOf`, or one
- * `$serializer` per child of a `$serializable` ref to an STI base, a member with several variants
- * of its own contributing each of them, and an `allOf` beside an `anyOf` or `oneOf` joining each
- * of its variants), the rendered one is the variant that declares every key the object has; when
- * several do, the first of them whose required keys the object all has, and when none is found,
- * the object adds each key any variant requires. The object's top-level keys render cased per
- * `casing`, so they are compared cased, and a key it has is never added.
+ * Lists the single shapes a value of a flattened `customAttribute` with this `openapi` may take,
+ * which a consumer can union into one description of the flattened payload: a `$serializer` ref to
+ * each serializer a `$serializable` ref resolves to (one per child for an STI base), or the members
+ * of an `anyOf` or `oneOf` (an `anyOf`'s members listed before a sibling `oneOf`'s, not paired with
+ * them), each member that itself has several shapes (a nested `anyOf` or `oneOf`, or a
+ * `$serializable` ref to an STI base) contributing those shapes in its place. An `allOf` beside
+ * the `anyOf` or `oneOf` describes every value, so each shape is that `allOf` with the shape added
+ * to its members. Anything else (a single shape, a ref with `many: true`, or a primitive) has no
+ * variants and returns an empty list. Each shape may be passed back as the `renderedVariant` of
+ * `nullFlattenedOpenapiKeysOfOtherVariants`. The renderer does not read a value's shape from this
+ * list: whatever shape the value takes, it renders every key `nullFlattenedOpenapiKeys` returns.
  */
-export function nullFlattenedOpenapiKeysForValue(openapi, value, options = {}) {
-    if (value instanceof DreamSerializerBuilder || value instanceof ObjectSerializerBuilder)
-        return nullKeysRequiredByOthers(walkOpenapi(openapi, newWalk(options)), Object.keys(walkSerializerBuilder(value, newWalk(options))));
-    if (typeof value !== 'object' || value === null)
-        return {};
-    const { casing } = newWalk(options);
-    const valueKeys = Object.keys(value).map(key => setCase(key, casing));
-    const variants = openapiVariants(openapi);
-    const candidates = variants
-        .map(variant => ({ variant, requirements: walkOpenapi(variant, newWalk(options)) }))
-        .filter(({ requirements }) => valueKeys.every(key => Object.prototype.hasOwnProperty.call(requirements, key)));
-    const renderedVariant = variants.length < 2
-        ? openapi
-        : candidates.length === 1
-            ? candidates[0].variant
-            : candidates.find(({ requirements }) => Object.keys(requirements).every(key => !requirements[key] || valueKeys.includes(key)))?.variant;
-    const requiredKeys = renderedVariant
-        ? {
-            ...nullFlattenedOpenapiKeysOfOtherVariants(openapi, renderedVariant, options),
-            ...nullFlattenedOpenapiKeys(renderedVariant, options),
-        }
-        : nullFlattenedOpenapiKeys(openapi, options);
-    valueKeys.forEach(key => delete requiredKeys[key]);
-    return requiredKeys;
-}
-/**
- * The shapes a value of `openapi` may take, each one a variant a plain object may render: a
- * `$serializer` ref to each serializer a `$serializable` ref resolves to, or the members of an
- * `anyOf` or `oneOf`, each member that itself has several variants (a nested `anyOf` or `oneOf`,
- * or a `$serializable` ref to an STI base) contributing those variants in its place. An `allOf`
- * beside the `anyOf` or `oneOf` describes every value, so each variant is that `allOf` with the
- * variant added to its members.
- */
-function openapiVariants(openapi) {
+export function flattenedOpenapiVariants(openapi) {
     if (typeof openapi !== 'object' || Array.isArray(openapi))
         return [];
     if ('$serializable' in openapi)
@@ -123,7 +99,7 @@ function openapiVariants(openapi) {
         ...(('anyOf' in openapi && openapi.anyOf) || []),
         ...(('oneOf' in openapi && openapi.oneOf) || []),
     ].flatMap(member => {
-        const memberVariants = openapiVariants(member);
+        const memberVariants = flattenedOpenapiVariants(member);
         return memberVariants.length > 1 ? memberVariants : [member];
     });
     const sharedMembers = ('allOf' in openapi && openapi.allOf) || [];

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

@@ -1,9 +1,10 @@
 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.
+ * Used by every flattened rendersOne render, whether the associated object is present or null: it
+ * lists every serializer the association may render with, whose required keys the renderer renders
+ * as null in the parent's payload, beneath the present object's own keys or alone when the object
+ * is null, where there is no object to resolve a serializer from.
  *
  * 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

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

@@ -14,7 +14,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 { DbConnectionType, LegacyCompatiblePrimaryKeyType } from '../types/db.js';
 import { DreamModelSerializerType, SimpleObjectSerializerType } from '../types/serializer.js';
@@ -72,6 +72,7 @@ export default class DreamApp {
         nullFlattenedSerializerKeysOfOtherVariants: typeof nullFlattenedSerializerKeysOfOtherVariants;
         nullFlattenedOpenapiKeys: typeof nullFlattenedOpenapiKeys;
         nullFlattenedOpenapiKeysOfOtherVariants: typeof nullFlattenedOpenapiKeysOfOtherVariants;
+        flattenedOpenapiVariants: typeof flattenedOpenapiVariants;
         serializerNameFromFullyQualifiedModelName: typeof serializerNameFromFullyQualifiedModelName;
         autogeneratedFileDisclaimer: typeof autogeneratedFileDisclaimer;
     };
@@ -159,6 +160,26 @@ export default class DreamApp {
     get packageManager(): "pnpm" | "yarn" | "npm" | "bun" | "deno";
     private _importExtension;
     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
+     * `#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(): "@" | "#";
     /**
      * if set to true, it will bypass deprecation checks that run
      * during the sync hook. Defaults to false, we only recommend
@@ -242,7 +263,7 @@ export default class DreamApp {
     private requireTestDatabaseClaimSupport;
     load<RT extends 'models' | 'serializers'>(resourceType: RT, resourcePath: string, importCb: (path: string) => Promise<any>): Promise<void>;
     plugin(cb: (app: DreamApp) => void | Promise<void>): void;
-    set<ApplyOpt extends DreamAppSetOption>(applyOption: ApplyOpt, options: ApplyOpt extends 'bypassDeprecationChecks' ? boolean : ApplyOpt extends 'db' ? DreamDbCredentialOptions | string : ApplyOpt extends 'encryption' ? DreamAppEncryptionOptions : ApplyOpt extends 'primaryKeyType' ? LegacyCompatiblePrimaryKeyType : ApplyOpt extends 'importExtension' ? GeneratorImportStyle : ApplyOpt extends 'logger' ? DreamLogger : ApplyOpt extends 'projectRoot' ? string : ApplyOpt extends 'inflections' ? () => void | Promise<void> : ApplyOpt extends 'packageManager' ? DreamAppAllowedPackageManagersEnum : ApplyOpt extends 'paths' ? DreamDirectoryPaths : ApplyOpt extends 'parallelTests' ? number : ApplyOpt extends 'unicodeNormalization' ? UnicodeNormalizationForm : ApplyOpt extends 'paginationPageSize' ? number : ApplyOpt extends 'paginationMaxPageSize' ? number : ApplyOpt extends 'sortableScopeLockTimeout' ? number : never, secondaryOptions?: ApplyOpt extends 'db' ? DreamDbCredentialOptions : never): void;
+    set<ApplyOpt extends DreamAppSetOption>(applyOption: ApplyOpt, options: ApplyOpt extends 'bypassDeprecationChecks' ? boolean : ApplyOpt extends 'db' ? DreamDbCredentialOptions | string : ApplyOpt extends 'encryption' ? DreamAppEncryptionOptions : ApplyOpt extends 'primaryKeyType' ? LegacyCompatiblePrimaryKeyType : ApplyOpt extends 'importExtension' ? GeneratorImportStyle : ApplyOpt extends 'importAliasPrefix' ? GeneratorImportAliasPrefix : ApplyOpt extends 'logger' ? DreamLogger : ApplyOpt extends 'projectRoot' ? string : ApplyOpt extends 'inflections' ? () => void | Promise<void> : ApplyOpt extends 'packageManager' ? DreamAppAllowedPackageManagersEnum : ApplyOpt extends 'paths' ? DreamDirectoryPaths : ApplyOpt extends 'parallelTests' ? number : ApplyOpt extends 'unicodeNormalization' ? UnicodeNormalizationForm : ApplyOpt extends 'paginationPageSize' ? number : ApplyOpt extends 'paginationMaxPageSize' ? number : ApplyOpt extends 'sortableScopeLockTimeout' ? number : never, secondaryOptions?: ApplyOpt extends 'db' ? DreamDbCredentialOptions : never): void;
     /**
      * Registers a callback for an app-level event. Callbacks for the same
      * event run in the order they were registered.
@@ -289,7 +310,7 @@ export interface DreamAppOpts {
     serializerCasing?: DreamSerializerCasing;
     parallelTests: number | undefined;
 }
-export type DreamAppSetOption = 'bypassDeprecationChecks' | 'db' | 'encryption' | 'inflections' | 'importExtension' | 'logger' | 'paths' | 'primaryKeyType' | 'projectRoot' | 'serializerCasing' | 'parallelTests' | 'unicodeNormalization' | 'paginationPageSize' | 'paginationMaxPageSize' | 'sortableScopeLockTimeout' | 'packageManager';
+export type DreamAppSetOption = 'bypassDeprecationChecks' | 'db' | 'encryption' | 'inflections' | 'importExtension' | 'importAliasPrefix' | 'logger' | 'paths' | 'primaryKeyType' | 'projectRoot' | 'serializerCasing' | 'parallelTests' | 'unicodeNormalization' | 'paginationPageSize' | 'paginationMaxPageSize' | 'sortableScopeLockTimeout' | 'packageManager';
 export interface DreamDirectoryPaths {
     models?: string;
     serializers?: string;
@@ -447,4 +468,6 @@ export declare const DreamAppAllowedPackageManagersEnumValues: readonly ["pnpm",
 export type DreamAppAllowedPackageManagersEnum = (typeof DreamAppAllowedPackageManagersEnumValues)[number];
 export declare const GeneratorImportStyles: readonly [".js", ".ts", "none"];
 export type GeneratorImportStyle = (typeof GeneratorImportStyles)[number];
+export declare const GeneratorImportAliasPrefixes: readonly ["@", "#"];
+export type GeneratorImportAliasPrefix = (typeof GeneratorImportAliasPrefixes)[number];
 export {};

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

@@ -11,11 +11,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/types/src/serializer/ObjectSerializer.d.ts

@@ -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/types/src/serializer/SerializerRenderer.d.ts

@@ -10,6 +10,6 @@ export default class SerializerRenderer {
     private renderOpts;
     constructor(serializerBuilder: DreamSerializerBuilder<any, any> | ObjectSerializerBuilder<any, any> | null | undefined, passthroughData?: object, { casing }?: SerializerRendererOpts);
     render(): Record<string, any> | null;
-    private setCaseOfKeys;
+    private setCaseOfDefinedKeys;
     private setCase;
 }

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

@@ -141,28 +141,29 @@ export default class DreamSerializerBuilder<DataTypeForOpenapi extends typeof Dr
      *   - `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
@@ -204,23 +205,29 @@ export default class DreamSerializerBuilder<DataTypeForOpenapi extends typeof Dr
      *     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
@@ -276,8 +283,9 @@ export default class DreamSerializerBuilder<DataTypeForOpenapi extends typeof Dr
          * If `true`, the rendered association's attributes are merged directly into
          * 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`, each key its serializer
-         * requires renders as `null`. See the `flatten` option of `rendersOne`.
+         * declared later, and each key its serializer requires renders, as `null`
+         * wherever the association does not supply it. See the `flatten` option of
+         * `rendersOne`.
          */
         flatten?: boolean;
         /**