@rvoh/dream 2.34.0 → 2.36.0

package/dist/cjs/src/dream/DreamInstanceTransactionBuilder.js

@@ -3,6 +3,7 @@ import CannotCreateAssociationOnUnpersistedDream from '../errors/associations/Ca
 import CannotDestroyAssociationOnUnpersistedDream from '../errors/associations/CannotDestroyAssociationOnUnpersistedDream.js';
 import CannotUpdateAssociationOnUnpersistedDream from '../errors/associations/CannotUpdateAssociationOnUnpersistedDream.js';
 import RecordNotFound from '../errors/RecordNotFound.js';
+import assertRecognizedAssociationConditionKeys, { DESTROY_ASSOCIATION_OPTION_KEYS, UPDATE_ASSOCIATION_OPTION_KEYS, } from './internal/associations/assertRecognizedAssociationConditionKeys.js';
 import associationQuery from './internal/associations/associationQuery.js';
 import associationUpdateQuery from './internal/associations/associationUpdateQuery.js';
 import createAssociation from './internal/associations/createAssociation.js';
@@ -33,26 +34,29 @@ export default class DreamInstanceTransactionBuilder {
     /**
      * Loads the requested associations upon execution
      *
+     * **IMPORTANT:** `load().execute()` returns a **new clone** of the model with the
+     * associations loaded. It does NOT modify the original instance.
+     *
      * NOTE: {@link Dream#preload} is often a preferrable way of achieving the
      * same goal.
      *
      * ```ts
      * await ApplicationModel.transaction(async txn => {
-     *   await user
+     *   const loadedUser = await user
      *    .txn(txn)
-     *    .load('posts', { body: ops.ilike('%hello world%') }, 'comments', 'replies')
+     *    .load('posts', { and: { body: ops.ilike('%hello world%') } }, 'comments', 'replies')
      *    .load('images')
      *    .execute()
      *
-     *   user.posts[0].comments[0].replies[0]
+     *   loadedUser.posts[0].comments[0].replies[0]
      *   // Reply{}
      *
-     *   user.images[0]
+     *   loadedUser.images[0]
      *   // Image{}
      * })
      * ```
      *
-     * @param args - A list of associations (and optional where clauses) to load
+     * @param args - A chain of association names and and/andNot/andAny clauses
      * @returns A chainable LoadBuilder instance
      */
     load(...args) {
@@ -112,32 +116,34 @@ export default class DreamInstanceTransactionBuilder {
      * Load each specified association using a single SQL query.
      * See {@link #load} for loading in separate queries.
      *
-     * Note: since leftJoinPreload loads via single query, it has
-     * some downsides and that may be avoided using {@link #load}:
+     * **IMPORTANT:** Like `load()`, `leftJoinLoad().execute()` returns a **new clone** of the
+     * model with associations loaded. It does NOT modify the original instance.
+     *
+     * Note: since leftJoinLoad loads via single query, it has
+     * some downsides that may be avoided using {@link #load}:
      * 1. `limit` and `offset` will be automatically removed
      * 2. `through` associations will bring additional namespaces into the query that can conflict with through associations from other associations, creating an invalid query
-     * 3. each nested association will result in an additional record which duplicates data from the outer record. E.g., given `.leftJoinPreload('a', 'b', 'c')`, if each `a` has 10 `b` and each `b` has 10 `c`, then for one `a`, 100 records will be returned, each of which has all of the columns of `a`. `.load('a', 'b', 'c')` would perform three separate SQL queries, but the data for a single `a` would only be returned once.
+     * 3. each nested association will result in an additional record which duplicates data from the outer record. E.g., given `.leftJoinLoad('a', 'b', 'c')`, if each `a` has 10 `b` and each `b` has 10 `c`, then for one `a`, 100 records will be returned, each of which has all of the columns of `a`. `.load('a', 'b', 'c')` would perform three separate SQL queries, but the data for a single `a` would only be returned once.
      * 4. the individual query becomes more complex the more associations are included
      * 5. associations loading associations loading associations could result in exponential amounts of data; in those cases, `.load(...).findEach(...)` avoids instantiating massive amounts of data at once
-     * Loads the requested associations upon execution
-     *
-     * NOTE: {@link Dream#leftJoinPreload} is often a preferrable way of achieving the
-     * same goal.
      *
      * ```ts
-     * await user.txn(txn)
-     *  .leftJoinLoad('posts', { body: ops.ilike('%hello world%') }, 'comments', 'replies')
-     *  .leftJoinLoad('images')
-     *  .execute()
+     * await ApplicationModel.transaction(async txn => {
+     *   const loadedUser = await user
+     *    .txn(txn)
+     *    .leftJoinLoad('posts', { and: { body: ops.ilike('%hello world%') } }, 'comments', 'replies')
+     *    .leftJoinLoad('images')
+     *    .execute()
      *
-     * user.posts[0].comments[0].replies[0]
-     * // Reply{}
+     *   loadedUser.posts[0].comments[0].replies[0]
+     *   // Reply{}
      *
-     * user.images[0]
-     * // Image{}
+     *   loadedUser.images[0]
+     *   // Image{}
+     * })
      * ```
      *
-     * @param args - A list of associations (and optional where clauses) to load
+     * @param args - A chain of association names and and/andNot/andAny clauses
      * @returns A chainable LeftJoinLoadBuilder instance
      */
     leftJoinLoad(...args) {
@@ -153,7 +159,7 @@ export default class DreamInstanceTransactionBuilder {
      * })
      * ```
      *
-     * @param args - A chain of association names and where clauses
+     * @param args - A chain of association names and and/andNot/andAny clauses
      * @returns A Query for this model with the inner join clause applied
      */
     innerJoin(...args) {
@@ -169,7 +175,7 @@ export default class DreamInstanceTransactionBuilder {
      * })
      * ```
      *
-     * @param args - A chain of association names and where clauses
+     * @param args - A chain of association names and and/andNot/andAny clauses
      * @returns A Query for this model with the left join clause applied
      */
     leftJoin(...args) {
@@ -252,6 +258,12 @@ export default class DreamInstanceTransactionBuilder {
      * See {@link Dream.save | save} for details on
      * the side effects of saving.
      *
+     * A column whose value is still `undefined` after setters run is
+     * skipped, not written (see {@link Dream.save | save}), with two
+     * `@Encrypted` exceptions: `undefined` for an encrypted property (e.g.
+     * `secret`) is encrypted to `null`, so it clears the column, and
+     * `undefined` for its backing column (e.g. `encryptedSecret`) throws.
+     *
      * NOTE:
      * To bypass custom-defined setters, use {@link Dream.updateAttributes | updateAttributes} instead.
      *
@@ -279,6 +291,18 @@ export default class DreamInstanceTransactionBuilder {
      * See {@link Dream.save | save} for details on
      * the side effects of saving.
      *
+     * An encrypted property (e.g. `secret`) is still encrypted. Its
+     * `@Encrypted` backing column (e.g. `encryptedSecret`) accepts only
+     * ciphertext that decrypts with this app's column encryption keys, or
+     * `null`; anything else throws before anything is saved (see
+     * {@link Dream.setAttribute | setAttribute}).
+     *
+     * A column whose value is still `undefined` after setters run is
+     * skipped, not written (see {@link Dream.save | save}), with two
+     * `@Encrypted` exceptions: `undefined` for an encrypted property (e.g.
+     * `secret`) is encrypted to `null`, so it clears the column, and
+     * `undefined` for its backing column (e.g. `encryptedSecret`) throws.
+     *
      * NOTE:
      * To update the values without bypassing any custom-defined
      * setters, use {@link Dream.update | update} instead.
@@ -329,6 +353,10 @@ export default class DreamInstanceTransactionBuilder {
      * Upon updating an instance, the update timestamp (if defined)
      * will be updated on the model.
      *
+     * A column whose value is `undefined` is skipped, not written: a new
+     * record gets the column's database default, and a persisted record
+     * keeps the value stored for it. Set a column to `null` to clear it.
+     *
      * ```ts
      * const user = User.new({ email: 'how@yadoin' })
      *
@@ -386,8 +414,8 @@ export default class DreamInstanceTransactionBuilder {
     }
     /**
      * Updates all records matching the association with
-     * the provided attributes. If a where statement is passed,
-     * The where statement will be applied to the query
+     * the provided attributes. If an and, andNot or andAny
+     * statement is passed, it will be applied to the query
      * before updating.
      *
      * ```ts
@@ -402,13 +430,16 @@ export default class DreamInstanceTransactionBuilder {
      * @param associationName - The name of the association to update
      * @param attributes - The attributes to update on the association
      * @param updateAssociationOptions - Options for updating the association
-     * @param updateAssociationOptions.where - Optional where statement to apply to query before updating
+     * @param updateAssociationOptions.and - Optional and statement to apply to query before updating
+     * @param updateAssociationOptions.andNot - Optional andNot statement to apply to query before updating
+     * @param updateAssociationOptions.andAny - Optional andAny statement to apply to query before updating
      * @param updateAssociationOptions.bypassAllDefaultScopes - If true, bypasses user-removable default scopes when updating the association; an STI child's reserved discriminator remains enforced, including when associations are loaded. Defaults to false
      * @param updateAssociationOptions.defaultScopesToBypass - An array of default scope names to bypass when updating the association. Defaults to an empty array
      * @param updateAssociationOptions.skipHooks - If true, skips applying model hooks during the update operation. Defaults to false
      * @returns The number of updated records
      */
     async updateAssociation(associationName, attributes, updateAssociationOptions) {
+        assertRecognizedAssociationConditionKeys(updateAssociationOptions, UPDATE_ASSOCIATION_OPTION_KEYS, associationName, 'updateAssociation');
         if (this.dreamInstance.isNewRecord)
             throw new CannotUpdateAssociationOnUnpersistedDream(this.dreamInstance, associationName);
         return await associationUpdateQuery(this.dreamInstance, this.dreamTransaction, associationName, {
@@ -465,6 +496,7 @@ export default class DreamInstanceTransactionBuilder {
      * @returns The number of records deleted
      */
     async destroyAssociation(associationName, options) {
+        assertRecognizedAssociationConditionKeys(options, DESTROY_ASSOCIATION_OPTION_KEYS, associationName, 'destroyAssociation');
         if (this.dreamInstance.isNewRecord)
             throw new CannotDestroyAssociationOnUnpersistedDream(this.dreamInstance, associationName);
         return await destroyAssociation(this.dreamInstance, this.dreamTransaction, associationName, {
@@ -503,6 +535,7 @@ export default class DreamInstanceTransactionBuilder {
      * @returns The number of records deleted
      */
     async reallyDestroyAssociation(associationName, options) {
+        assertRecognizedAssociationConditionKeys(options, DESTROY_ASSOCIATION_OPTION_KEYS, associationName, 'reallyDestroyAssociation');
         if (this.dreamInstance.isNewRecord)
             throw new CannotDestroyAssociationOnUnpersistedDream(this.dreamInstance, associationName);
         return await destroyAssociation(this.dreamInstance, this.dreamTransaction, associationName, {
@@ -521,7 +554,9 @@ export default class DreamInstanceTransactionBuilder {
      * will also be undeleted.
      *
      * ```ts
-     * await user.undestroyAssociation('posts', { and: { body: 'hello world' } })
+     * await ApplicationModel.transaction(async txn => {
+     *   await user.txn(txn).undestroyAssociation('posts', { and: { body: 'hello world' } })
+     * })
      * ```
      *
      * @param associationName - The name of the association to undestroy
@@ -536,6 +571,7 @@ export default class DreamInstanceTransactionBuilder {
      * @returns The number of records undestroyed
      */
     async undestroyAssociation(associationName, options) {
+        assertRecognizedAssociationConditionKeys(options, DESTROY_ASSOCIATION_OPTION_KEYS, associationName, 'undestroyAssociation');
         return await undestroyAssociation(this.dreamInstance, this.dreamTransaction, associationName, {
             ...undestroyOptions(options),
             joinAndStatements: {

package/dist/cjs/src/dream/LeftJoinLoadBuilder.js

@@ -28,13 +28,13 @@ export default class LeftJoinLoadBuilder {
         return this;
     }
     /**
-     * Attaches a load statement to the load builder
+     * Attaches a leftJoinLoad statement to the load builder
      *
      * ```ts
      * const user = await User.firstOrFail()
      * await user
-     *   .load('settings')
-     *   .load('posts', 'comments', 'replies', ['image', 'localizedText'])
+     *   .leftJoinLoad('settings')
+     *   .leftJoinLoad('posts', 'comments', 'replies', ['image', 'localizedText'])
      *   .execute()
      * ```
      */

package/dist/cjs/src/dream/LoadBuilder.js

@@ -93,7 +93,7 @@ export default class LoadBuilder {
      *   .execute()
      * ```
      *
-     * @param args - A list of associations (and optional where clauses) to load
+     * @param args - A chain of association names and and/andNot/andAny clauses to load
      * @returns A chainable LoadBuilder instance
      */
     load(...args) {