@rvoh/dream 2.36.1 → 2.38.0

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

@@ -1,4 +1,27 @@
 import DreamSerializerBuilder from './builders/DreamSerializerBuilder.js';
+/**
+ * Builds a serializer for a Dream model. A serializer is a function that takes the
+ * data to render and declares the keys to render it with:
+ *
+ * ```typescript
+ * export const UserSerializer = (user: User) =>
+ *   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 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.
+ *
+ * @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
+ * @returns The serializer builder for method chaining
+ */
 export default function DreamSerializer(dreamClass, data, passthroughData) {
     return new DreamSerializerBuilder(dreamClass, data, passthroughData);
 }

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

@@ -1,4 +1,26 @@
 import ObjectSerializerBuilder from './builders/ObjectSerializerBuilder.js';
+/**
+ * Builds a serializer for a plain object or view model. A serializer is a function
+ * that takes the data to render and declares the keys to render it with:
+ *
+ * ```typescript
+ * export const AddressSerializer = (address: Address) =>
+ *   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 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.
+ *
+ * @param data - The object to render
+ * @param passthroughData - Data available to this serializer and passed down to the serializers
+ *   it renders
+ * @returns The serializer builder for method chaining
+ */
 export default function ObjectSerializer(data, passthroughData) {
     return new ObjectSerializerBuilder(data, passthroughData);
 }

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

@@ -9,6 +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 { serializersForAssociatedClass } from './helpers/serializersForAssociatedClass.js';
 export default class SerializerRenderer {
     serializerBuilder;
@@ -77,9 +78,30 @@ export default class SerializerRenderer {
                     if (value === undefined && attribute.options?.required === false)
                         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
+                        const valueIsSerializerBuilder = value instanceof DreamSerializerBuilder || value instanceof ObjectSerializerBuilder;
+                        const valueRendersNull = value === null ||
+                            value === undefined ||
+                            (valueIsSerializerBuilder &&
+                                (value['data'] ?? null) === null);
+                        if (valueRendersNull)
+                            return {
+                                ...accumulator,
+                                ...nullFlattenedOpenapiKeys(attribute.options.openapi, flattenOptions),
+                            };
+                        const renderedValue = applyRenderingOptionsToAttribute(null, value, attribute.name, {}, this.passthroughData, this.renderOpts);
                         return {
                             ...accumulator,
-                            ...applyRenderingOptionsToAttribute(null, value, attribute.name, {}, this.passthroughData, this.renderOpts),
+                            ...nullFlattenedOpenapiKeysForValue(attribute.options.openapi, value, flattenOptions),
+                            // 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)),
                         };
                     }
                     else {
@@ -99,7 +121,7 @@ export default class SerializerRenderer {
                     if (!associatedObject && attribute.options.flatten) {
                         return {
                             ...accumulator,
-                            ...this.nullFlattenedAttributes(serializersForAssociatedClass(data instanceof Dream ? data.constructor : null, attribute.name, attribute.options), passthroughData),
+                            ...nullFlattenedSerializerKeys(serializersForAssociatedClass(data instanceof Dream ? data.constructor : null, attribute.name, attribute.options), { casing: this.renderOpts.casing, passthroughData }),
                         };
                     }
                     const serializer = associatedObject
@@ -112,6 +134,12 @@ 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 })
+                                : {}),
                             // 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
@@ -176,58 +204,12 @@ export default class SerializerRenderer {
         }, renderedAttributes);
         return renderedAttributes;
     }
-    /**
-     * The keys a flattened `rendersOne` adds to the parent's payload when its associated object is
-     * null: each key any of `serializers` declares, set to `null`. 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 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
-     * no association of the missing object is read. A flattened `rendersOne` it declares adds its
-     * own serializers' keys the same way. A flattened `customAttribute` adds none, since only its
-     * callback knows its keys.
-     */
-    nullFlattenedAttributes(serializers, passthroughData, serializersBeingFlattened = new Set()) {
-        return serializers.reduce((flattenedKeys, serializer) => {
-            // a serializer reached again, e.g. one that flattens itself directly or through others, or
-            // one that two polymorphic targets or two STI children both flatten, adds no keys the first
-            // walk through it did not
-            if (serializersBeingFlattened.has(serializer))
-                return flattenedKeys;
-            serializersBeingFlattened.add(serializer);
-            const serializerBuilder = serializer(undefined, passthroughData);
-            const dreamClass = serializerBuilder instanceof DreamSerializerBuilder
-                ? serializerBuilder['$typeForOpenapi']
-                : null;
-            return serializerBuilder['attributes'].reduce((keys, attribute) => {
-                const attributeType = attribute.type;
-                switch (attributeType) {
-                    case 'attribute':
-                    case 'delegatedAttribute':
-                    case 'rendersMany':
-                        keys[this.setCase(attribute.options?.as ?? attribute.name)] = null;
-                        return keys;
-                    case 'customAttribute':
-                        if (!attribute.options.flatten)
-                            keys[this.setCase(attribute.name)] = null;
-                        return keys;
-                    case 'rendersOne':
-                        if (!attribute.options.flatten) {
-                            keys[this.setCase(attribute.options.as ?? attribute.name)] = null;
-                            return keys;
-                        }
-                        return {
-                            ...keys,
-                            ...this.nullFlattenedAttributes(serializersForAssociatedClass(dreamClass, attribute.name, attribute.options), passthroughData, serializersBeingFlattened),
-                        };
-                    default: {
-                        // protection so that if a new ValidationType is ever added, this will throw a type error at build time
-                        const _never = attributeType;
-                        throw new Error(`Unhandled serializer attribute type: ${_never}`);
-                    }
-                }
-            }, flattenedKeys);
+    setCaseOfKeys(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];
+            return casedValue;
         }, {});
     }
     setCase(attr) {

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

@@ -115,8 +115,21 @@ export default class DreamSerializerBuilder {
      *     property bodies (`type: 'object'`, `properties`, and `required` listing the keys that
      *     are always present), or `{ $serializer: SomeSerializer }` when the callback returns
      *     what that serializer renders. A serializer ref with `many: true` does not type-check
-     *     here, since a list has no properties to spread. A `null` or `undefined` return adds no
-     *     keys. Attributes render in declaration order, so a key the returned object shares with
+     *     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.
+     *     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
      *   - `required` - Set to `false` to mark the attribute as optional in the OpenAPI schema;
@@ -168,14 +181,23 @@ 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`, every key its serializer declares renders as `null`
-     *     (for a polymorphic `BelongsTo`, every key the serializer of any of its target classes
-     *     declares, and for an association to an STI base, every key the serializer of any of its
-     *     STI children declares), in the same order (so an `id` declared before the `rendersOne` becomes
-     *     `null`); nothing in that serializer is rendered, so its custom attribute callbacks do
-     *     not run, and a flattened `customAttribute` in it adds no keys. Psychic adds the association's OpenAPI
-     *     schema to the parent's as an `allOf` branch, so a shared key's value must match both
-     *     schemas, whichever declaration wins
+     *     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
+     *     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
      *   - `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

@@ -151,8 +151,21 @@ export default class ObjectSerializerBuilder {
      *     property bodies (`type: 'object'`, `properties`, and `required` listing the keys that
      *     are always present), or `{ $serializer: SomeSerializer }` when the callback returns
      *     what that serializer renders. A serializer ref with `many: true` does not type-check
-     *     here, since a list has no properties to spread. A `null` or `undefined` return adds no
-     *     keys. Attributes render in declaration order, so a key the returned object shares with
+     *     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.
+     *     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
      *   - `required` - Set to `false` to mark the attribute as optional in the OpenAPI schema;
@@ -204,14 +217,23 @@ 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`, every key its serializer declares renders as `null`
-     *     (for a polymorphic `BelongsTo`, every key the serializer of any of its target classes
-     *     declares, and for an association to an STI base, every key the serializer of any of its
-     *     STI children declares), in the same order (so an `id` declared before the `rendersOne` becomes
-     *     `null`); nothing in that serializer is rendered, so its custom attribute callbacks do
-     *     not run, and a flattened `customAttribute` in it adds no keys. Psychic adds the association's OpenAPI
-     *     schema to the parent's as an `allOf` branch, so a shared key's value must match both
-     *     schemas, whichever declaration wins
+     *     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
+     *     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
      *   - `optional` - When `true`, allows the association to be null/missing without causing
      *     an `OpenapiResponseValidationFailure` during Psychic controller unit specs. By default,
      *     `rendersOne` expects the association to be present (mirroring the `optional` option on

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

@@ -0,0 +1,257 @@
+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.
+ *
+ * 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
+ * no association of the missing object is read. A non-flattened `rendersOne` or a `rendersMany`
+ * always adds its key. A flattened `rendersOne` it declares adds its own serializers' required keys
+ * the same way. A flattened `customAttribute` adds the keys its `openapi` requires: each key of
+ * its `properties` that the shape's `required` array lists, the required keys of the serializer a
+ * `$serializer` ref names or of every serializer a `$serializable` ref resolves to (one per child
+ * for an STI base), walked the same way, and the union of the keys every member of an `allOf`,
+ * `anyOf` or `oneOf` requires, with each key an object shape's own `required` array lists beside
+ * its members; one declared with `required: false` adds none. A ref with `many: true` adds none,
+ * since a list has no keys to spread. A serializer reached again within its own walk, as when one
+ * 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.
+ */
+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
+ * 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`.
+ */
+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.
+ */
+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
+ * `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`.
+ */
+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.
+ */
+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) {
+    if (typeof openapi !== 'object' || Array.isArray(openapi))
+        return [];
+    if ('$serializable' in openapi)
+        return openapi.many
+            ? []
+            : inferSerializersFromDreamClassOrViewModelClass(openapi.$serializable, openapi.$serializableSerializerKey ?? openapi.key).map(serializer => ({ $serializer: serializer }));
+    const variants = [
+        ...(('anyOf' in openapi && openapi.anyOf) || []),
+        ...(('oneOf' in openapi && openapi.oneOf) || []),
+    ].flatMap(member => {
+        const memberVariants = openapiVariants(member);
+        return memberVariants.length > 1 ? memberVariants : [member];
+    });
+    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 nullRequiredKeys(requirements) {
+    return Object.keys(requirements).reduce((keys, key) => {
+        if (requirements[key])
+            keys[key] = null;
+        return keys;
+    }, {});
+}
+function nullKeysRequiredByOthers(requirements, renderedKeys) {
+    return Object.keys(requirements).reduce((keys, key) => {
+        if (requirements[key] && !renderedKeys.includes(key))
+            keys[key] = null;
+        return keys;
+    }, {});
+}
+/**
+ * A key is required when any of its declarations requires it.
+ */
+function mergeRequirements(requirements, other) {
+    Object.keys(other).forEach(key => {
+        requirements[key] = (requirements[key] ?? false) || other[key];
+    });
+    return requirements;
+}
+function walkSerializers(serializers, walk) {
+    return serializers.reduce((flattenedKeys, serializer) => {
+        // a serializer that flattens itself, directly or through others, adds no keys its walk in
+        // progress does not; one reached again along another path is walked again, since a path that
+        // requires its keys must not lose them to an earlier path that left them optional
+        if (walk.serializersBeingFlattened.has(serializer))
+            return flattenedKeys;
+        walk.serializersBeingFlattened.add(serializer);
+        const serializerBuilder = serializer(undefined, walk.passthroughData);
+        const serializerKeys = walkSerializerBuilder(serializerBuilder, walk);
+        walk.serializersBeingFlattened.delete(serializer);
+        return mergeRequirements(flattenedKeys, serializerKeys);
+    }, {});
+}
+function walkSerializerBuilder(serializerBuilder, walk) {
+    const dreamClass = serializerBuilder instanceof DreamSerializerBuilder
+        ? serializerBuilder['$typeForOpenapi']
+        : null;
+    return serializerBuilder['attributes'].reduce((keys, attribute) => {
+        const attributeType = attribute.type;
+        switch (attributeType) {
+            case 'attribute':
+            case 'delegatedAttribute':
+                return mergeRequirements(keys, {
+                    [setCase(attribute.options?.as ?? attribute.name, walk.casing)]: attribute.options?.required !== false,
+                });
+            case 'rendersMany':
+                return mergeRequirements(keys, {
+                    [setCase(attribute.options?.as ?? attribute.name, walk.casing)]: true,
+                });
+            case 'customAttribute': {
+                if (!attribute.options.flatten)
+                    return mergeRequirements(keys, {
+                        [setCase(attribute.name, walk.casing)]: attribute.options.required !== false,
+                    });
+                const flattenedKeys = walkOpenapi(attribute.options.openapi, walk);
+                // a callback that may return undefined with `required: false` adds none of its keys
+                if (attribute.options.required === false)
+                    Object.keys(flattenedKeys).forEach(key => (flattenedKeys[key] = false));
+                return mergeRequirements(keys, flattenedKeys);
+            }
+            case 'rendersOne':
+                if (!attribute.options.flatten)
+                    return mergeRequirements(keys, {
+                        [setCase(attribute.options.as ?? attribute.name, walk.casing)]: true,
+                    });
+                return mergeRequirements(keys, walkSerializers(serializersForAssociatedClass(dreamClass, attribute.name, attribute.options), walk));
+            default: {
+                // protection so that if a new ValidationType is ever added, this will throw a type error at build time
+                const _never = attributeType;
+                throw new Error(`Unhandled serializer attribute type: ${_never}`);
+            }
+        }
+    }, {});
+}
+function walkOpenapi(openapi, walk) {
+    if (typeof openapi !== 'object' || Array.isArray(openapi))
+        return {};
+    if ('$serializer' in openapi) {
+        if (openapi.many)
+            return {};
+        return walkSerializers([openapi.$serializer], walk);
+    }
+    if ('$serializable' in openapi) {
+        if (openapi.many)
+            return {};
+        return walkSerializers(inferSerializersFromDreamClassOrViewModelClass(openapi.$serializable, openapi.$serializableSerializerKey ?? openapi.key), walk);
+    }
+    const keys = Object.keys(('properties' in openapi && openapi.properties) || {}).reduce((propertyKeys, key) => {
+        propertyKeys[setCase(key, walk.casing)] = false;
+        return propertyKeys;
+    }, {});
+    const members = [
+        ...(('allOf' in openapi && openapi.allOf) || []),
+        ...(('anyOf' in openapi && openapi.anyOf) || []),
+        ...(('oneOf' in openapi && openapi.oneOf) || []),
+    ];
+    const shapeKeys = members.reduce((keys, member) => mergeRequirements(keys, walkOpenapi(member, walk)), keys);
+    // the shape's own `required` array requires a key its `properties` declare or a member declares
+    const requiredKeys = ('required' in openapi && openapi.required) || [];
+    requiredKeys.forEach(key => {
+        const casedKey = setCase(key, walk.casing);
+        if (Object.prototype.hasOwnProperty.call(shapeKeys, casedKey))
+            shapeKeys[casedKey] = true;
+    });
+    return shapeKeys;
+}
+function setCase(attr, casing) {
+    switch (casing) {
+        case 'camel':
+            return attr;
+        case 'snake':
+            return snakeify(attr);
+        default: {
+            // protection so that if a new Casing is ever added, this will throw a type error at build time
+            const _never = casing;
+            throw new Error(`Unhandled Casing: ${_never}`);
+        }
+    }
+}

package/dist/esm/src/db/dataTypes.js

@@ -1,11 +1,3 @@
-export default function dataTypes() {
-    // In the future, when we support multiple db drivers,
-    // this will need to be updated
-    return postgresDatatypes;
-}
-export function isPrimitiveDataType(type) {
-    return dataTypes().includes(type.replace(/\[\]$/, ''));
-}
 export const postgresDatatypes = [
     'bigint',
     'bigserial',

package/dist/esm/src/dream/QueryDriver/Base.js

@@ -91,14 +91,12 @@ export default class QueryDriverBase {
      * comlpex to override. You will need to do the following
      * when overriding this method:
      *
-     * 1. introspect the db and use it to generate a db.ts file in the
-     *    same shape as the existing one. Currently, the process for generating
-     *    this file is extremely complex and messy, and will be difficult
-     *    to achieve.
+     * 1. generate a types/db.ts file in the same shape as the existing one.
+     *    KyselyQueryDriver does this with the ASTDbTypesBuilder, which writes
+     *    it from {@link introspectDatabase}.
      * 2. generate a types/dream.ts file in the same shape as the existing
-     *    one. This is normally done using the ASTSchemaBuilder
-     *    but this will likely need to be overridden to tailor to your custom
-     *    database engine.
+     *    one. KyselyQueryDriver does this with the ASTSchemaBuilder, which
+     *    also reads the connection through {@link introspectDatabase}.
      */
     // eslint-disable-next-line @typescript-eslint/require-await
     static async sync(connectionName, _, 
@@ -292,15 +290,20 @@ export default class QueryDriverBase {
     keys) {
         throw new Error('override acquireAdvisoryTransactionLocks in child class');
     }
+    /**
+     * Reads the tables, columns and enums of the connection's database, from
+     * which `sync` writes the connection's `types/db.ts` and `types/dream.ts`.
+     * It returns every table the connection can read, sorted by schema and
+     * name; `sync` applies `tableIncludePattern` and `tableExcludePattern`
+     * itself.
+     *
+     * @param connectionName - the connection to read
+     */
     // eslint-disable-next-line @typescript-eslint/require-await
-    static async getColumnData(
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    connectionName, 
+    static async introspectDatabase(
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    tableName, 
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    allTableAssociationData) {
-        throw new Error('implement getColumnData in child class');
+    connectionName) {
+        throw new Error('implement introspectDatabase in child class');
     }
     /**
      * @internal
@@ -695,16 +698,6 @@ export default class QueryDriverBase {
     reallyDestroy) {
         throw new Error('implement destroyDream in child class');
     }
-    static get syncDialect() {
-        return 'postgres';
-    }
-    /** @internal Resolve the credential used by the database type generator. */
-    static codegenPassword(password) {
-        if (typeof password === 'function') {
-            throw new Error('This database adapter does not support a password provider for type generation');
-        }
-        return Promise.resolve(password);
-    }
     /**
      * Returns the sql that would be executed by this Query
      *