@rvoh/dream 2.40.1 → 2.41.0

package/dist/cjs/src/Dream.js

@@ -20,6 +20,7 @@ import destroyDream from './dream/internal/destroyDream.js';
 import { destroyOptions, reallyDestroyOptions, undestroyOptions } from './dream/internal/destroyOptions.js';
 import ensureSTITypeFieldIsSet from './dream/internal/ensureSTITypeFieldIsSet.js';
 import findOrCreateBy from './dream/internal/findOrCreateBy.js';
+import findOrCreateLookupStatement from './dream/internal/findOrCreateLookupStatement.js';
 import mergeSerializerAssociationEdges from './dream/internal/mergeSerializerAssociationEdges.js';
 import printSerializerHierarchyLevel from './dream/internal/printSerializerHierarchyLevel.js';
 import reload from './dream/internal/reload.js';
@@ -1288,7 +1289,7 @@ export default class Dream {
         }
         catch (err) {
             if (pgErrorType(err) === UNIQUE_VIOLATION) {
-                const dreamModel = await this.findBy(this.extractAttributesFromUpdateableProperties(attributes));
+                const dreamModel = await this.findBy(findOrCreateLookupStatement(this, attributes));
                 if (!dreamModel)
                     throw new CreateOrFindByFailedToCreateAndFind(this);
                 return dreamModel;
@@ -1342,7 +1343,7 @@ export default class Dream {
         }
         catch (err) {
             if (pgErrorType(err) === UNIQUE_VIOLATION) {
-                const existingRecord = await this.findBy(this.extractAttributesFromUpdateableProperties(attributes));
+                const existingRecord = await this.findBy(findOrCreateLookupStatement(this, attributes));
                 if (!existingRecord)
                     throw new CreateOrUpdateByFailedToCreateAndUpdate(this);
                 const { with: attrs } = extraOpts;

package/dist/cjs/src/dream/internal/findOrCreateBy.js

@@ -1,7 +1,6 @@
+import findOrCreateLookupStatement from './findOrCreateLookupStatement.js';
 export default async function findOrCreateBy(dreamClass, txn = null, attributes, extraOpts = {}) {
-    const existingRecord = await dreamClass
-        .txn(txn)
-        .findBy(dreamClass['extractAttributesFromUpdateableProperties'](attributes));
+    const existingRecord = await dreamClass.txn(txn).findBy(findOrCreateLookupStatement(dreamClass, attributes));
     if (existingRecord)
         return existingRecord;
     const { createWith, skipHooks } = extraOpts;

package/dist/cjs/src/dream/internal/findOrCreateLookupStatement.js

@@ -0,0 +1,19 @@
+import isDatabaseArrayColumn from '../../helpers/db/types/isDatabaseArrayColumn.js';
+import ops from '../../ops/index.js';
+/**
+ * Builds the `findBy` statement that findOrCreateBy, createOrFindBy,
+ * updateOrCreateBy and createOrUpdateBy use to look up an existing record.
+ * Their attributes are both the lookup and the values to persist, so an array
+ * given for an array column is the whole array to store: the lookup compares
+ * it with `ops.equal`, matching only a record whose array equals it
+ * element-for-element, in order, instead of the `IN` a plain list means in a
+ * where clause. PostgreSQL defines no equality operator for `json`, so on a
+ * `json[]` column this lookup raises at the database, as `ops.equal` does.
+ */
+export default function findOrCreateLookupStatement(dreamClass, attributes) {
+    const lookup = dreamClass['extractAttributesFromUpdateableProperties'](attributes);
+    return Object.fromEntries(Object.entries(lookup).map(([column, value]) => [
+        column,
+        Array.isArray(value) && isDatabaseArrayColumn(dreamClass, column) ? ops.equal(value) : value,
+    ]));
+}

package/dist/cjs/src/dream/internal/updateOrCreateBy.js

@@ -1,8 +1,7 @@
+import findOrCreateLookupStatement from './findOrCreateLookupStatement.js';
 import saveDream from './saveDream.js';
 export default async function updateOrCreateBy(dreamClass, txn = null, attributes, extraOpts = {}) {
-    const existingRecord = await dreamClass
-        .txn(txn)
-        .findBy(dreamClass['extractAttributesFromUpdateableProperties'](attributes));
+    const existingRecord = await dreamClass.txn(txn).findBy(findOrCreateLookupStatement(dreamClass, attributes));
     const { with: attrs, skipHooks } = extraOpts;
     if (existingRecord) {
         existingRecord.assignAttributes(attrs ?? {});

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/helpers/db/normalizeDataForDb.js

@@ -38,11 +38,18 @@ function normalizedString(_val) {
     const normalizedValueArray = (alreadyAnArray ? _val : [_val]).map(val => typeof val === 'string' ? normalizeUnicode(val) : val);
     return alreadyAnArray ? normalizedValueArray : normalizedValueArray[0];
 }
+/**
+ * A value for a date or timestamp column (or an array of them) may be a single
+ * value, an array, or, as the `IN` operand against an array column, a list of
+ * whole arrays; every nested array is converted element by element.
+ */
 function dateTimeOrDateToSql(dateClass, _val) {
     const alreadyAnArray = Array.isArray(_val);
-    const normalizedValueArray = (alreadyAnArray ? _val : [_val]).map(val => {
+    const normalizedValueArray = (alreadyAnArray ? _val : [_val]).map((val) => {
         if (val === null || val === undefined)
             return val;
+        if (Array.isArray(val))
+            return dateTimeOrDateToSql(dateClass, val);
         if (val instanceof DateTime || val instanceof CalendarDate)
             return val.toSQL();
         try {
@@ -59,11 +66,18 @@ function dateTimeOrDateToSql(dateClass, _val) {
     });
     return alreadyAnArray ? normalizedValueArray : normalizedValueArray[0];
 }
+/**
+ * A value for a time column (or an array of them) may be a single value, an
+ * array, or, as the `IN` operand against an array column, a list of whole
+ * arrays; every nested array is converted element by element.
+ */
 function clockTimeOrClockTimeTzToSql(clockTimeClass, _val) {
     const alreadyAnArray = Array.isArray(_val);
-    const normalizedValueArray = (alreadyAnArray ? _val : [_val]).map(val => {
+    const normalizedValueArray = (alreadyAnArray ? _val : [_val]).map((val) => {
         if (val === null || val === undefined)
             return val;
+        if (Array.isArray(val))
+            return clockTimeOrClockTimeTzToSql(clockTimeClass, val);
         if (val instanceof BaseClockTime)
             return val.toSQL();
         try {

package/dist/cjs/src/ops/index.js

@@ -119,9 +119,13 @@ const ops = {
      *
      * **Array columns:** passing an array means literal array equality — the
      * whole array is bound as a single parameter, so the column must match
-     * element-for-element, in order. This is the opt-in counterpart to a bare
-     * array in a where clause (`Post.where({ tags: ['a', 'b'] })`), which means
-     * `IN`, and to `ops.any`, which tests for containment of a single element.
+     * element-for-element, in order. The plain value form of a where clause
+     * targets regular (scalar) columns, so comparing an array column against an
+     * array value goes through `ops`: a flat list against an array column
+     * (`Post.where({ tags: ['a', 'b'] })`) is a compile error. A list of whole
+     * arrays (`Post.where({ tags: [['a', 'b'], ['c']] })`) means `IN`, matching
+     * rows whose column equals any one of them, and `ops.any` tests for
+     * containment of a single element.
      * Element types are constrained by the column, so an enum array column
      * rejects a string that is not a member of its enum.
      *

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.js

@@ -20,6 +20,7 @@ import destroyDream from './dream/internal/destroyDream.js';
 import { destroyOptions, reallyDestroyOptions, undestroyOptions } from './dream/internal/destroyOptions.js';
 import ensureSTITypeFieldIsSet from './dream/internal/ensureSTITypeFieldIsSet.js';
 import findOrCreateBy from './dream/internal/findOrCreateBy.js';
+import findOrCreateLookupStatement from './dream/internal/findOrCreateLookupStatement.js';
 import mergeSerializerAssociationEdges from './dream/internal/mergeSerializerAssociationEdges.js';
 import printSerializerHierarchyLevel from './dream/internal/printSerializerHierarchyLevel.js';
 import reload from './dream/internal/reload.js';
@@ -1288,7 +1289,7 @@ export default class Dream {
         }
         catch (err) {
             if (pgErrorType(err) === UNIQUE_VIOLATION) {
-                const dreamModel = await this.findBy(this.extractAttributesFromUpdateableProperties(attributes));
+                const dreamModel = await this.findBy(findOrCreateLookupStatement(this, attributes));
                 if (!dreamModel)
                     throw new CreateOrFindByFailedToCreateAndFind(this);
                 return dreamModel;
@@ -1342,7 +1343,7 @@ export default class Dream {
         }
         catch (err) {
             if (pgErrorType(err) === UNIQUE_VIOLATION) {
-                const existingRecord = await this.findBy(this.extractAttributesFromUpdateableProperties(attributes));
+                const existingRecord = await this.findBy(findOrCreateLookupStatement(this, attributes));
                 if (!existingRecord)
                     throw new CreateOrUpdateByFailedToCreateAndUpdate(this);
                 const { with: attrs } = extraOpts;

package/dist/esm/src/dream/internal/findOrCreateBy.js

@@ -1,7 +1,6 @@
+import findOrCreateLookupStatement from './findOrCreateLookupStatement.js';
 export default async function findOrCreateBy(dreamClass, txn = null, attributes, extraOpts = {}) {
-    const existingRecord = await dreamClass
-        .txn(txn)
-        .findBy(dreamClass['extractAttributesFromUpdateableProperties'](attributes));
+    const existingRecord = await dreamClass.txn(txn).findBy(findOrCreateLookupStatement(dreamClass, attributes));
     if (existingRecord)
         return existingRecord;
     const { createWith, skipHooks } = extraOpts;

package/dist/esm/src/dream/internal/findOrCreateLookupStatement.js

@@ -0,0 +1,19 @@
+import isDatabaseArrayColumn from '../../helpers/db/types/isDatabaseArrayColumn.js';
+import ops from '../../ops/index.js';
+/**
+ * Builds the `findBy` statement that findOrCreateBy, createOrFindBy,
+ * updateOrCreateBy and createOrUpdateBy use to look up an existing record.
+ * Their attributes are both the lookup and the values to persist, so an array
+ * given for an array column is the whole array to store: the lookup compares
+ * it with `ops.equal`, matching only a record whose array equals it
+ * element-for-element, in order, instead of the `IN` a plain list means in a
+ * where clause. PostgreSQL defines no equality operator for `json`, so on a
+ * `json[]` column this lookup raises at the database, as `ops.equal` does.
+ */
+export default function findOrCreateLookupStatement(dreamClass, attributes) {
+    const lookup = dreamClass['extractAttributesFromUpdateableProperties'](attributes);
+    return Object.fromEntries(Object.entries(lookup).map(([column, value]) => [
+        column,
+        Array.isArray(value) && isDatabaseArrayColumn(dreamClass, column) ? ops.equal(value) : value,
+    ]));
+}

package/dist/esm/src/dream/internal/updateOrCreateBy.js

@@ -1,8 +1,7 @@
+import findOrCreateLookupStatement from './findOrCreateLookupStatement.js';
 import saveDream from './saveDream.js';
 export default async function updateOrCreateBy(dreamClass, txn = null, attributes, extraOpts = {}) {
-    const existingRecord = await dreamClass
-        .txn(txn)
-        .findBy(dreamClass['extractAttributesFromUpdateableProperties'](attributes));
+    const existingRecord = await dreamClass.txn(txn).findBy(findOrCreateLookupStatement(dreamClass, attributes));
     const { with: attrs, skipHooks } = extraOpts;
     if (existingRecord) {
         existingRecord.assignAttributes(attrs ?? {});

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/helpers/db/normalizeDataForDb.js

@@ -38,11 +38,18 @@ function normalizedString(_val) {
     const normalizedValueArray = (alreadyAnArray ? _val : [_val]).map(val => typeof val === 'string' ? normalizeUnicode(val) : val);
     return alreadyAnArray ? normalizedValueArray : normalizedValueArray[0];
 }
+/**
+ * A value for a date or timestamp column (or an array of them) may be a single
+ * value, an array, or, as the `IN` operand against an array column, a list of
+ * whole arrays; every nested array is converted element by element.
+ */
 function dateTimeOrDateToSql(dateClass, _val) {
     const alreadyAnArray = Array.isArray(_val);
-    const normalizedValueArray = (alreadyAnArray ? _val : [_val]).map(val => {
+    const normalizedValueArray = (alreadyAnArray ? _val : [_val]).map((val) => {
         if (val === null || val === undefined)
             return val;
+        if (Array.isArray(val))
+            return dateTimeOrDateToSql(dateClass, val);
         if (val instanceof DateTime || val instanceof CalendarDate)
             return val.toSQL();
         try {
@@ -59,11 +66,18 @@ function dateTimeOrDateToSql(dateClass, _val) {
     });
     return alreadyAnArray ? normalizedValueArray : normalizedValueArray[0];
 }
+/**
+ * A value for a time column (or an array of them) may be a single value, an
+ * array, or, as the `IN` operand against an array column, a list of whole
+ * arrays; every nested array is converted element by element.
+ */
 function clockTimeOrClockTimeTzToSql(clockTimeClass, _val) {
     const alreadyAnArray = Array.isArray(_val);
-    const normalizedValueArray = (alreadyAnArray ? _val : [_val]).map(val => {
+    const normalizedValueArray = (alreadyAnArray ? _val : [_val]).map((val) => {
         if (val === null || val === undefined)
             return val;
+        if (Array.isArray(val))
+            return clockTimeOrClockTimeTzToSql(clockTimeClass, val);
         if (val instanceof BaseClockTime)
             return val.toSQL();
         try {

package/dist/esm/src/ops/index.js

@@ -119,9 +119,13 @@ const ops = {
      *
      * **Array columns:** passing an array means literal array equality — the
      * whole array is bound as a single parameter, so the column must match
-     * element-for-element, in order. This is the opt-in counterpart to a bare
-     * array in a where clause (`Post.where({ tags: ['a', 'b'] })`), which means
-     * `IN`, and to `ops.any`, which tests for containment of a single element.
+     * element-for-element, in order. The plain value form of a where clause
+     * targets regular (scalar) columns, so comparing an array column against an
+     * array value goes through `ops`: a flat list against an array column
+     * (`Post.where({ tags: ['a', 'b'] })`) is a compile error. A list of whole
+     * arrays (`Post.where({ tags: [['a', 'b'], ['c']] })`) means `IN`, matching
+     * rows whose column equals any one of them, and `ops.any` tests for
+     * containment of a single element.
      * Element types are constrained by the column, so an enum array column
      * rejects a string that is not a member of its enum.
      *

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);