@rvoh/dream 2.33.0 → 2.35.0

package/README.md

@@ -1,4 +1,4 @@
-Dream is a typescript-driven, esm-first ORM built on top of [kysely](http://kysely.dev). It is built to operate within the [Psychic web framework](https://psychicframework.com/docs/intro), but can be brought into other projects and used without the encapsulating framework (though this is theoretical, and we do not encourage it at this time). It is actively being developed to support production-grade applications in use within the [RVOHealth organization](https://www.rvohealth.com), who has kindly sponsored the continued development of this ORM, as well as the Psychic web framework as a whole.
+Dream is a typescript-driven, esm-first ORM built on top of [kysely](http://kysely.dev). It supports Node.js 24 and newer, with Node.js 26 as the primary development and CI runtime. It is built to operate within the [Psychic web framework](https://psychicframework.com/docs/intro), but can be brought into other projects and used without the encapsulating framework (though this is theoretical, and we do not encourage it at this time). It is actively being developed to support production-grade applications in use within the [RVOHealth organization](https://www.rvohealth.com), who has kindly sponsored the continued development of this ORM, as well as the Psychic web framework as a whole.
 
 Documentation: [https://psychicframework.com/docs/intro](https://psychicframework.com/docs/intro)
 Psychic web framework github: [https://github.com/rvohealth/psychic](https://github.com/rvohealth/psychic)

package/dist/cjs/src/Dream.js

@@ -2302,8 +2302,8 @@ export default class Dream {
     /**
      * Returns true if any of the attributes on the instance
      * have changed since it was last pulled from the database.
-     * It will also return true if the instance is not yet
-     * persisted.
+     * On an unpersisted instance, it returns true when at least
+     * one column has a value other than `undefined`.
      *
      * ```ts
      * const post = Post.new({ body: 'howyadoin' })
@@ -2946,6 +2946,9 @@ export default class Dream {
      * being persisted to the database, with the values
      * that were last persisted to the database.
      *
+     * On a record that has not been persisted, only columns
+     * with values other than `undefined` count as changed.
+     *
      * ```ts
      *  const user = User.new({ email: 'original@email', password: 'howyadoin' })
      *  await user.save()
@@ -3077,6 +3080,10 @@ export default class Dream {
      * Returns true if the columnName provided has
      * changes that have not yet been persisted.
      *
+     * On a record that has not been persisted, this returns
+     * true only for a column with a value other than `undefined`.
+     * An explicit `null` counts as a change.
+     *
      * @param attribute - the column name to check
      * @returns A boolean
      */
@@ -3096,6 +3103,10 @@ export default class Dream {
      * of columns that have changed since last persist,
      * and their current values.
      *
+     * On a record that has not been persisted, the object
+     * contains only columns with values other than `undefined`.
+     * An explicit `null` is included.
+     *
      * ```ts
      *  const user = User.new({ email: 'hello@world' })
      *  user.dirtyAttributes()
@@ -3133,7 +3144,7 @@ export default class Dream {
      */
     attributeIsDirty(attribute) {
         if (this.isNewRecord)
-            return true;
+            return this.getAttribute(attribute) !== undefined;
         return !areEqual(this.frozenAttributes[attribute], this.getAttribute(attribute));
     }
     /**

package/dist/cjs/src/decorators/Decorators.js

@@ -491,6 +491,11 @@ export default class Decorators {
      * }
      * ```
      *
+     * The decorated method is called with no argument, once the
+     * transaction has committed, so declaring a parameter on it is a
+     * compile error. A subclass override of the method that is not itself
+     * decorated is not checked; it is still called with no argument.
+     *
      * @returns The AfterCreateCommit decorator
      */
     AfterCreateCommit(opts) {
@@ -526,6 +531,11 @@ export default class Decorators {
      * }
      * ```
      *
+     * The decorated method is called with no argument, once the
+     * transaction has committed, so declaring a parameter on it is a
+     * compile error. A subclass override of the method that is not itself
+     * decorated is not checked; it is still called with no argument.
+     *
      * @returns The AfterSaveCommit decorator
      *
      */
@@ -562,6 +572,11 @@ export default class Decorators {
      * }
      * ```
      *
+     * The decorated method is called with no argument, once the
+     * transaction has committed, so declaring a parameter on it is a
+     * compile error. A subclass override of the method that is not itself
+     * decorated is not checked; it is still called with no argument.
+     *
      * @returns The AfterUpdateCommit decorator
      *
      */
@@ -598,6 +613,11 @@ export default class Decorators {
      * }
      * ```
      *
+     * The decorated method is called with no argument, once the
+     * transaction has committed, so declaring a parameter on it is a
+     * compile error. A subclass override of the method that is not itself
+     * decorated is not checked; it is still called with no argument.
+     *
      * @returns The AfterDestroyCommit decorator
      *
      */

package/dist/cjs/src/decorators/field/lifecycle/AfterCreateCommit.js

@@ -7,6 +7,10 @@ import { blankHooksFactory } from './shared.js';
  * a transaction, the method will be run after the save
  * is complete.
  *
+ * The method is called with no argument: the transaction has already
+ * committed, so there is none to hand it. Decorating a method that
+ * declares a parameter is a compile error (see {@link CommitHookDecorator}).
+ *
  * class User extends ApplicationModel {
  *   @deco.AfterCreateCommit()
  *   public doSomething() {

package/dist/cjs/src/decorators/field/lifecycle/AfterDestroyCommit.js

@@ -7,6 +7,10 @@ import { blankHooksFactory } from './shared.js';
  * a transaction, the method will be run after the save
  * is complete.
  *
+ * The method is called with no argument: the transaction has already
+ * committed, so there is none to hand it. Decorating a method that
+ * declares a parameter is a compile error (see {@link CommitHookDecorator}).
+ *
  * class User extends ApplicationModel {
  *   @deco.AfterDestroyCommit()
  *   public doSomething() {

package/dist/cjs/src/decorators/field/lifecycle/AfterSaveCommit.js

@@ -7,6 +7,10 @@ import { blankHooksFactory } from './shared.js';
  * a transaction, the method will be run after the save
  * is complete.
  *
+ * The method is called with no argument: the transaction has already
+ * committed, so there is none to hand it. Decorating a method that
+ * declares a parameter is a compile error (see {@link CommitHookDecorator}).
+ *
  * class User extends ApplicationModel {
  *   @deco.AfterSaveCommit()
  *   public doSomething() {

package/dist/cjs/src/decorators/field/lifecycle/AfterUpdateCommit.js

@@ -7,6 +7,10 @@ import { blankHooksFactory } from './shared.js';
  * a transaction, the method will be run after the save
  * is complete.
  *
+ * The method is called with no argument: the transaction has already
+ * committed, so there is none to hand it. Decorating a method that
+ * declares a parameter is a compile error (see {@link CommitHookDecorator}).
+ *
  * class User extends ApplicationModel {
  *   @deco.AfterUpdateCommit()
  *   public doSomething() {

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

@@ -1,4 +1,4 @@
-import { runHook } from './internal/runHooksFor.js';
+import { runCommitHook } from './internal/runHooksFor.js';
 // though this class is called `DreamTransaction`, it is not itself
 // a transaction class, as much as a collector for various callbacks
 // that must be run after the underlying transaction is commited (i.e.
@@ -6,6 +6,10 @@ import { runHook } from './internal/runHooksFor.js';
 export default class DreamTransaction {
     _kyselyTransaction;
     commitHooks = [];
+    // Set when the query driver starts the commit hooks, which it does only once
+    // the transaction has committed. `withConcurrentWriterRetry` reads it to
+    // never run a committed operation again.
+    committed = false;
     get kyselyTransaction() {
         return this._kyselyTransaction;
     }
@@ -15,9 +19,16 @@ export default class DreamTransaction {
     addCommitHook(hookStatement, dreamInstance) {
         this.commitHooks.push({ dreamInstance, hookStatement });
     }
-    async runAfterCommitHooks(txn) {
+    /**
+     * Runs the commit hooks queued during the transaction, in the order they
+     * were queued. A query driver calls this once the transaction has
+     * committed. Each hook is called with no argument, since the transaction
+     * it would otherwise receive can no longer run queries.
+     */
+    async runAfterCommitHooks() {
+        this.committed = true;
         for (const hook of this.commitHooks) {
-            await runHook(hook.hookStatement, hook.dreamInstance, txn);
+            await runCommitHook(hook.hookStatement, hook.dreamInstance);
         }
     }
 }

package/dist/cjs/src/dream/QueryDriver/Kysely.js

@@ -351,7 +351,7 @@ export default class KyselyQueryDriver extends QueryDriverBase {
             dreamTransaction.kyselyTransaction = kyselyTransaction;
             callbackResponse = (await callback(dreamTransaction));
         });
-        await dreamTransaction.runAfterCommitHooks(dreamTransaction);
+        await dreamTransaction.runAfterCommitHooks();
         return callbackResponse;
     }
     /**

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

@@ -35,7 +35,7 @@ export default async function runHooksFor(key, dream, alreadyPersisted, beforeSa
                         if (txn)
                             txn.addCommitHook(hook, dream);
                         else
-                            await runHook(hook, dream, null);
+                            await runCommitHook(hook, dream);
                     }
                     break;
                 case 'afterSave':
@@ -50,7 +50,7 @@ export default async function runHooksFor(key, dream, alreadyPersisted, beforeSa
                         if (txn)
                             txn.addCommitHook(hook, dream);
                         else
-                            await runHook(hook, dream, null);
+                            await runCommitHook(hook, dream);
                     }
                     break;
                 case 'afterUpdate':
@@ -63,7 +63,7 @@ export default async function runHooksFor(key, dream, alreadyPersisted, beforeSa
                         if (txn)
                             txn.addCommitHook(hook, dream);
                         else
-                            await runHook(hook, dream, null);
+                            await runCommitHook(hook, dream);
                     }
                     break;
                 default:
@@ -79,7 +79,7 @@ export default async function runHooksFor(key, dream, alreadyPersisted, beforeSa
                     if (txn)
                         txn.addCommitHook(hook, dream);
                     else
-                        await runHook(hook, dream, null);
+                        await runCommitHook(hook, dream);
                     break;
                 default:
                     await runHook(hook, dream, txn);
@@ -88,6 +88,18 @@ export default async function runHooksFor(key, dream, alreadyPersisted, beforeSa
     }
 }
 export async function runHook(statement, dream, txn) {
+    assertHookMethodExists(statement, dream);
+    await dream[statement.method](txn);
+}
+/**
+ * Commit hooks run after the transaction has committed, so they are called
+ * with no argument.
+ */
+export async function runCommitHook(statement, dream) {
+    assertHookMethodExists(statement, dream);
+    await dream[statement.method]();
+}
+function assertHookMethodExists(statement, dream) {
     if (typeof dream[statement.method] !== 'function') {
         throw new Error(`
 Attempting to run ${statement.method} as part of the ${statement.type}
@@ -96,7 +108,6 @@ Dream model hook sequence, but we encountered a method that does not exist.
 Please make sure "${statement.method}" is defined on ${dream['sanitizedConstructorName']}
 `);
     }
-    await dream[statement.method](txn);
 }
 function shouldRunBeforeCreateHook(dream, statement) {
     let shouldRun = false;

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

@@ -22,7 +22,8 @@ export const MAX_CONCURRENT_WRITER_ATTEMPTS = 3;
  * rows mid-statement as well. Either way the database has undone the whole
  * transaction, nothing has committed and no commit hook has run, so running
  * the operation again reads the rows as the other writer left them. The last
- * attempt's error is the adapter's own.
+ * attempt's error is the adapter's own. An error raised after COMMIT, such as a
+ * commit hook's, is never retried.
  *
  * A unique violation raised by a statement inside the callback is not a
  * collision but a write that violates a constraint outright, and is not
@@ -46,15 +47,19 @@ export const MAX_CONCURRENT_WRITER_ATTEMPTS = 3;
 export default async function withConcurrentWriterRetry(dreamClass, callback) {
     const queryDriverClass = DreamApp.getOrFail().dbConnectionQueryDriverClass(dreamClass.prototype.connectionName);
     for (let attempt = 1;; attempt++) {
+        let attemptTransaction = null;
         let callbackResolved = false;
         try {
             return await dreamClass.transaction(async (txn) => {
+                attemptTransaction = txn;
                 const result = await callback(txn);
                 callbackResolved = true;
                 return result;
             });
         }
         catch (error) {
+            if (attemptTransaction?.['committed'])
+                throw error;
             const undoneByConcurrentWriter = queryDriverClass.isDeadlock(error) ||
                 (callbackResolved && queryDriverClass.isUniqueConstraintViolation(error));
             if (!undoneByConcurrentWriter || attempt === MAX_CONCURRENT_WRITER_ATTEMPTS)

package/dist/esm/src/Dream.js

@@ -2302,8 +2302,8 @@ export default class Dream {
     /**
      * Returns true if any of the attributes on the instance
      * have changed since it was last pulled from the database.
-     * It will also return true if the instance is not yet
-     * persisted.
+     * On an unpersisted instance, it returns true when at least
+     * one column has a value other than `undefined`.
      *
      * ```ts
      * const post = Post.new({ body: 'howyadoin' })
@@ -2946,6 +2946,9 @@ export default class Dream {
      * being persisted to the database, with the values
      * that were last persisted to the database.
      *
+     * On a record that has not been persisted, only columns
+     * with values other than `undefined` count as changed.
+     *
      * ```ts
      *  const user = User.new({ email: 'original@email', password: 'howyadoin' })
      *  await user.save()
@@ -3077,6 +3080,10 @@ export default class Dream {
      * Returns true if the columnName provided has
      * changes that have not yet been persisted.
      *
+     * On a record that has not been persisted, this returns
+     * true only for a column with a value other than `undefined`.
+     * An explicit `null` counts as a change.
+     *
      * @param attribute - the column name to check
      * @returns A boolean
      */
@@ -3096,6 +3103,10 @@ export default class Dream {
      * of columns that have changed since last persist,
      * and their current values.
      *
+     * On a record that has not been persisted, the object
+     * contains only columns with values other than `undefined`.
+     * An explicit `null` is included.
+     *
      * ```ts
      *  const user = User.new({ email: 'hello@world' })
      *  user.dirtyAttributes()
@@ -3133,7 +3144,7 @@ export default class Dream {
      */
     attributeIsDirty(attribute) {
         if (this.isNewRecord)
-            return true;
+            return this.getAttribute(attribute) !== undefined;
         return !areEqual(this.frozenAttributes[attribute], this.getAttribute(attribute));
     }
     /**

package/dist/esm/src/decorators/Decorators.js

@@ -491,6 +491,11 @@ export default class Decorators {
      * }
      * ```
      *
+     * The decorated method is called with no argument, once the
+     * transaction has committed, so declaring a parameter on it is a
+     * compile error. A subclass override of the method that is not itself
+     * decorated is not checked; it is still called with no argument.
+     *
      * @returns The AfterCreateCommit decorator
      */
     AfterCreateCommit(opts) {
@@ -526,6 +531,11 @@ export default class Decorators {
      * }
      * ```
      *
+     * The decorated method is called with no argument, once the
+     * transaction has committed, so declaring a parameter on it is a
+     * compile error. A subclass override of the method that is not itself
+     * decorated is not checked; it is still called with no argument.
+     *
      * @returns The AfterSaveCommit decorator
      *
      */
@@ -562,6 +572,11 @@ export default class Decorators {
      * }
      * ```
      *
+     * The decorated method is called with no argument, once the
+     * transaction has committed, so declaring a parameter on it is a
+     * compile error. A subclass override of the method that is not itself
+     * decorated is not checked; it is still called with no argument.
+     *
      * @returns The AfterUpdateCommit decorator
      *
      */
@@ -598,6 +613,11 @@ export default class Decorators {
      * }
      * ```
      *
+     * The decorated method is called with no argument, once the
+     * transaction has committed, so declaring a parameter on it is a
+     * compile error. A subclass override of the method that is not itself
+     * decorated is not checked; it is still called with no argument.
+     *
      * @returns The AfterDestroyCommit decorator
      *
      */

package/dist/esm/src/decorators/field/lifecycle/AfterCreateCommit.js

@@ -7,6 +7,10 @@ import { blankHooksFactory } from './shared.js';
  * a transaction, the method will be run after the save
  * is complete.
  *
+ * The method is called with no argument: the transaction has already
+ * committed, so there is none to hand it. Decorating a method that
+ * declares a parameter is a compile error (see {@link CommitHookDecorator}).
+ *
  * class User extends ApplicationModel {
  *   @deco.AfterCreateCommit()
  *   public doSomething() {

package/dist/esm/src/decorators/field/lifecycle/AfterDestroyCommit.js

@@ -7,6 +7,10 @@ import { blankHooksFactory } from './shared.js';
  * a transaction, the method will be run after the save
  * is complete.
  *
+ * The method is called with no argument: the transaction has already
+ * committed, so there is none to hand it. Decorating a method that
+ * declares a parameter is a compile error (see {@link CommitHookDecorator}).
+ *
  * class User extends ApplicationModel {
  *   @deco.AfterDestroyCommit()
  *   public doSomething() {

package/dist/esm/src/decorators/field/lifecycle/AfterSaveCommit.js

@@ -7,6 +7,10 @@ import { blankHooksFactory } from './shared.js';
  * a transaction, the method will be run after the save
  * is complete.
  *
+ * The method is called with no argument: the transaction has already
+ * committed, so there is none to hand it. Decorating a method that
+ * declares a parameter is a compile error (see {@link CommitHookDecorator}).
+ *
  * class User extends ApplicationModel {
  *   @deco.AfterSaveCommit()
  *   public doSomething() {

package/dist/esm/src/decorators/field/lifecycle/AfterUpdateCommit.js

@@ -7,6 +7,10 @@ import { blankHooksFactory } from './shared.js';
  * a transaction, the method will be run after the save
  * is complete.
  *
+ * The method is called with no argument: the transaction has already
+ * committed, so there is none to hand it. Decorating a method that
+ * declares a parameter is a compile error (see {@link CommitHookDecorator}).
+ *
  * class User extends ApplicationModel {
  *   @deco.AfterUpdateCommit()
  *   public doSomething() {

package/dist/esm/src/dream/DreamTransaction.js

@@ -1,4 +1,4 @@
-import { runHook } from './internal/runHooksFor.js';
+import { runCommitHook } from './internal/runHooksFor.js';
 // though this class is called `DreamTransaction`, it is not itself
 // a transaction class, as much as a collector for various callbacks
 // that must be run after the underlying transaction is commited (i.e.
@@ -6,6 +6,10 @@ import { runHook } from './internal/runHooksFor.js';
 export default class DreamTransaction {
     _kyselyTransaction;
     commitHooks = [];
+    // Set when the query driver starts the commit hooks, which it does only once
+    // the transaction has committed. `withConcurrentWriterRetry` reads it to
+    // never run a committed operation again.
+    committed = false;
     get kyselyTransaction() {
         return this._kyselyTransaction;
     }
@@ -15,9 +19,16 @@ export default class DreamTransaction {
     addCommitHook(hookStatement, dreamInstance) {
         this.commitHooks.push({ dreamInstance, hookStatement });
     }
-    async runAfterCommitHooks(txn) {
+    /**
+     * Runs the commit hooks queued during the transaction, in the order they
+     * were queued. A query driver calls this once the transaction has
+     * committed. Each hook is called with no argument, since the transaction
+     * it would otherwise receive can no longer run queries.
+     */
+    async runAfterCommitHooks() {
+        this.committed = true;
         for (const hook of this.commitHooks) {
-            await runHook(hook.hookStatement, hook.dreamInstance, txn);
+            await runCommitHook(hook.hookStatement, hook.dreamInstance);
         }
     }
 }

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

@@ -351,7 +351,7 @@ export default class KyselyQueryDriver extends QueryDriverBase {
             dreamTransaction.kyselyTransaction = kyselyTransaction;
             callbackResponse = (await callback(dreamTransaction));
         });
-        await dreamTransaction.runAfterCommitHooks(dreamTransaction);
+        await dreamTransaction.runAfterCommitHooks();
         return callbackResponse;
     }
     /**

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

@@ -35,7 +35,7 @@ export default async function runHooksFor(key, dream, alreadyPersisted, beforeSa
                         if (txn)
                             txn.addCommitHook(hook, dream);
                         else
-                            await runHook(hook, dream, null);
+                            await runCommitHook(hook, dream);
                     }
                     break;
                 case 'afterSave':
@@ -50,7 +50,7 @@ export default async function runHooksFor(key, dream, alreadyPersisted, beforeSa
                         if (txn)
                             txn.addCommitHook(hook, dream);
                         else
-                            await runHook(hook, dream, null);
+                            await runCommitHook(hook, dream);
                     }
                     break;
                 case 'afterUpdate':
@@ -63,7 +63,7 @@ export default async function runHooksFor(key, dream, alreadyPersisted, beforeSa
                         if (txn)
                             txn.addCommitHook(hook, dream);
                         else
-                            await runHook(hook, dream, null);
+                            await runCommitHook(hook, dream);
                     }
                     break;
                 default:
@@ -79,7 +79,7 @@ export default async function runHooksFor(key, dream, alreadyPersisted, beforeSa
                     if (txn)
                         txn.addCommitHook(hook, dream);
                     else
-                        await runHook(hook, dream, null);
+                        await runCommitHook(hook, dream);
                     break;
                 default:
                     await runHook(hook, dream, txn);
@@ -88,6 +88,18 @@ export default async function runHooksFor(key, dream, alreadyPersisted, beforeSa
     }
 }
 export async function runHook(statement, dream, txn) {
+    assertHookMethodExists(statement, dream);
+    await dream[statement.method](txn);
+}
+/**
+ * Commit hooks run after the transaction has committed, so they are called
+ * with no argument.
+ */
+export async function runCommitHook(statement, dream) {
+    assertHookMethodExists(statement, dream);
+    await dream[statement.method]();
+}
+function assertHookMethodExists(statement, dream) {
     if (typeof dream[statement.method] !== 'function') {
         throw new Error(`
 Attempting to run ${statement.method} as part of the ${statement.type}
@@ -96,7 +108,6 @@ Dream model hook sequence, but we encountered a method that does not exist.
 Please make sure "${statement.method}" is defined on ${dream['sanitizedConstructorName']}
 `);
     }
-    await dream[statement.method](txn);
 }
 function shouldRunBeforeCreateHook(dream, statement) {
     let shouldRun = false;

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

@@ -22,7 +22,8 @@ export const MAX_CONCURRENT_WRITER_ATTEMPTS = 3;
  * rows mid-statement as well. Either way the database has undone the whole
  * transaction, nothing has committed and no commit hook has run, so running
  * the operation again reads the rows as the other writer left them. The last
- * attempt's error is the adapter's own.
+ * attempt's error is the adapter's own. An error raised after COMMIT, such as a
+ * commit hook's, is never retried.
  *
  * A unique violation raised by a statement inside the callback is not a
  * collision but a write that violates a constraint outright, and is not
@@ -46,15 +47,19 @@ export const MAX_CONCURRENT_WRITER_ATTEMPTS = 3;
 export default async function withConcurrentWriterRetry(dreamClass, callback) {
     const queryDriverClass = DreamApp.getOrFail().dbConnectionQueryDriverClass(dreamClass.prototype.connectionName);
     for (let attempt = 1;; attempt++) {
+        let attemptTransaction = null;
         let callbackResolved = false;
         try {
             return await dreamClass.transaction(async (txn) => {
+                attemptTransaction = txn;
                 const result = await callback(txn);
                 callbackResolved = true;
                 return result;
             });
         }
         catch (error) {
+            if (attemptTransaction?.['committed'])
+                throw error;
             const undoneByConcurrentWriter = queryDriverClass.isDeadlock(error) ||
                 (callbackResolved && queryDriverClass.isUniqueConstraintViolation(error));
             if (!undoneByConcurrentWriter || attempt === MAX_CONCURRENT_WRITER_ATTEMPTS)

package/dist/types/src/Dream.d.ts

@@ -1900,8 +1900,8 @@ export default class Dream {
     /**
      * Returns true if any of the attributes on the instance
      * have changed since it was last pulled from the database.
-     * It will also return true if the instance is not yet
-     * persisted.
+     * On an unpersisted instance, it returns true when at least
+     * one column has a value other than `undefined`.
      *
      * ```ts
      * const post = Post.new({ body: 'howyadoin' })
@@ -2312,6 +2312,9 @@ export default class Dream {
      * being persisted to the database, with the values
      * that were last persisted to the database.
      *
+     * On a record that has not been persisted, only columns
+     * with values other than `undefined` count as changed.
+     *
      * ```ts
      *  const user = User.new({ email: 'original@email', password: 'howyadoin' })
      *  await user.save()
@@ -2421,6 +2424,10 @@ export default class Dream {
      * Returns true if the columnName provided has
      * changes that have not yet been persisted.
      *
+     * On a record that has not been persisted, this returns
+     * true only for a column with a value other than `undefined`.
+     * An explicit `null` counts as a change.
+     *
      * @param attribute - the column name to check
      * @returns A boolean
      */
@@ -2436,6 +2443,10 @@ export default class Dream {
      * of columns that have changed since last persist,
      * and their current values.
      *
+     * On a record that has not been persisted, the object
+     * contains only columns with values other than `undefined`.
+     * An explicit `null` is included.
+     *
      * ```ts
      *  const user = User.new({ email: 'hello@world' })
      *  user.dirtyAttributes()