@rvoh/dream 2.32.0 → 2.34.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

@@ -2946,6 +2946,10 @@ 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, every
+     * column counts as changed: the object has a key
+     * for every column.
+     *
      * ```ts
      *  const user = User.new({ email: 'original@email', password: 'howyadoin' })
      *  await user.save()
@@ -3077,6 +3081,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, every
+     * column counts as changed, so this returns true
+     * for every column, whether or not it was assigned.
+     *
      * @param attribute - the column name to check
      * @returns A boolean
      */
@@ -3096,10 +3104,15 @@ export default class Dream {
      * of columns that have changed since last persist,
      * and their current values.
      *
+     * On a record that has not been persisted, every
+     * column counts as changed: the object has a key
+     * for every column, including those never assigned,
+     * whose value is `undefined`.
+     *
      * ```ts
      *  const user = User.new({ email: 'hello@world' })
      *  user.dirtyAttributes()
-     *  // { email: 'hello@world' }
+     *  // { id: undefined, email: 'hello@world', name: undefined, ...every other column: undefined }
      *
      *  await user.save()
      *

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

@@ -508,10 +508,10 @@ ${INDENT}Examples: User, Place, Room/Bedroom, Settings/CommunicationPreferences`
      * (package.json scripts, CLI argv, scaffold templates) — never from
      * runtime request input or any other untrusted external source.
      *
-     * Argv-form is the safe choice for any caller that interpolates a
-     * config value, path, or credential: a database password containing
-     * `$` or backticks is passed literally to the child rather than
-     * interpreted by a shell.
+     * Argv-form passes config values and paths literally to the child,
+     * without interpreting shell metacharacters. Credentials belong in
+     * the child's environment, since argv is visible in process listings
+     * and in the refused-spawn error.
      *
      * ## Layered defense
      *

package/dist/cjs/src/db/helpers/syncDbTypesFiles.js

@@ -13,16 +13,14 @@ export default async function syncDbTypesFiles(connectionName) {
     const dbFilename = dbTypesFilenameForConnection(connectionName);
     const dbSyncFilePath = path.join(dreamPath('types'), dbFilename);
     const absoluteDbSyncPath = path.join(dreamApp.projectRoot, dbSyncFilePath);
+    const password = await driverClass.codegenPassword(dbConf.password);
     await CliFileWriter.cache(absoluteDbSyncPath);
     const lowLevelDbOpts = dreamApp.dbCredentialsFor(connectionName);
-    // Argv form (R-015): the connection URL embeds the DB password, and passwords
-    // may legitimately contain shell meta-characters (`$`, backticks, spaces, etc.).
-    // DreamCLI.spawn always uses shell:false, so each arg is passed literally to
-    // the child rather than parsed by a shell — credentials are preserved and any
-    // future mutable source can't open a command-injection surface.
-    const userinfo = `${dbConf.user}${dbConf.password ? `:${dbConf.password}` : ''}`;
+    // Pass the URL only in the child's environment. A URL in argv exposes the
+    // password in the process command line and DreamCLI's refused-spawn error.
+    const userinfo = `${encodeURIComponent(dbConf.user)}${password ? `:${encodeURIComponent(password)}` : ''}`;
     const url = `${driverClass.syncDialect}://${userinfo}@${dbConf.host}:${dbConf.port}/${dbConf.name}`;
-    const args = [`--dialect=${driverClass.syncDialect}`, `--url=${url}`];
+    const args = [`--dialect=${driverClass.syncDialect}`, '--url=env(DATABASE_URL)'];
     if (lowLevelDbOpts?.tableIncludePattern) {
         args.push(`--include-pattern=${lowLevelDbOpts.tableIncludePattern}`);
     }
@@ -32,6 +30,7 @@ export default async function syncDbTypesFiles(connectionName) {
     args.push(`--out-file=${absoluteDbSyncPath}`);
     await DreamCLI.spawn('kysely-codegen', {
         args,
+        env: { ...process.env, DATABASE_URL: url },
         onStdout: message => {
             DreamCLI.logger.logContinueProgress(colorize(`[db]`, { color: 'greenBright' }) + ' ' + message, {
                 logPrefixColor: 'greenBright',

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

@@ -626,6 +626,13 @@ export default class QueryDriverBase {
     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
      *

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

@@ -71,6 +71,7 @@ import softDeleteDream from '../internal/softDeleteDream.js';
 import sqlResultToDreamInstance from '../internal/sqlResultToDreamInstance.js';
 import Query from '../Query.js';
 import QueryDriverBase from './Base.js';
+import { PasswordProviderPoolClient } from './helpers/pg/loadPgClient.js';
 import checkForNeedToBeRunMigrations from './helpers/kysely/checkForNeedToBeRunMigrations.js';
 import foreignKeyTypeFromPrimaryKey from './helpers/kysely/foreignKeyTypeFromPrimaryKey.js';
 import runMigration from './helpers/kysely/runMigration.js';
@@ -103,7 +104,10 @@ export default class KyselyQueryDriver extends QueryDriverBase {
                 // Spread pg passthrough first; Dream's resolved fields follow and
                 // always win (per-connection database name, TLS directive).
                 ...(connectionConf.pg ?? {}),
+                Client: typeof connectionConf.password === 'function' ? PasswordProviderPoolClient : undefined,
                 user: connectionConf.user || '',
+                // pg accepts a callback here and resolves it for each new client when
+                // the server requests password authentication.
                 password: connectionConf.password || '',
                 database: DreamApp.getOrFail().dbName(connectionName, dbConnectionType),
                 host: connectionConf.host || 'localhost',
@@ -227,6 +231,9 @@ export default class KyselyQueryDriver extends QueryDriverBase {
     static get syncDialect() {
         return 'postgres';
     }
+    static async codegenPassword(password) {
+        return typeof password === 'function' ? await password() : password;
+    }
     /**
      * @internal
      *
@@ -344,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/QueryDriver/Postgres.js

@@ -332,7 +332,13 @@ export default class PostgresQueryDriver extends KyselyQueryDriver {
             keepAlive: true,
             keepAliveInitialDelayMillis: LOCK_CONNECTION_KEEPALIVE_INITIAL_DELAY_MS,
         });
-        await client.connect();
+        try {
+            await client.connect();
+        }
+        catch (err) {
+            await client.end().catch(() => undefined);
+            throw err;
+        }
         return {
             async tryAcquire(namespace, index) {
                 const result = await client.query('SELECT pg_try_advisory_lock($1::int4, $2::int4) AS locked', [

package/dist/cjs/src/dream/QueryDriver/helpers/pg/loadPgClient.js

@@ -8,6 +8,28 @@
 // @ts-ignore
 import pg from 'pg';
 import DreamApp from '../../../../dream-app/index.js';
+export class PasswordProviderPoolClient extends pg.Client {
+    connect(callback) {
+        if (callback) {
+            super.connect(err => {
+                if (err)
+                    this.destroyConnectionStream();
+                callback(err);
+            });
+        }
+        else {
+            return super.connect().catch(err => {
+                this.destroyConnectionStream();
+                throw err;
+            });
+        }
+    }
+    destroyConnectionStream() {
+        // pg reports a rejected password provider without closing its socket.
+        ;
+        this.connection?.stream.destroy();
+    }
+}
 export default async function loadPgClient({ connectionName, useSystemDb, }) {
     const dreamconf = DreamApp.getOrFail();
     const creds = dreamconf.dbCredentialsFor(connectionName)?.primary;
@@ -20,6 +42,12 @@ export default async function loadPgClient({ connectionName, useSystemDb, }) {
         user: creds.user,
         password: creds.password,
     });
-    await client.connect();
+    try {
+        await client.connect();
+    }
+    catch (err) {
+        await client.end().catch(() => undefined);
+        throw err;
+    }
     return client;
 }

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

@@ -2946,6 +2946,10 @@ 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, every
+     * column counts as changed: the object has a key
+     * for every column.
+     *
      * ```ts
      *  const user = User.new({ email: 'original@email', password: 'howyadoin' })
      *  await user.save()
@@ -3077,6 +3081,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, every
+     * column counts as changed, so this returns true
+     * for every column, whether or not it was assigned.
+     *
      * @param attribute - the column name to check
      * @returns A boolean
      */
@@ -3096,10 +3104,15 @@ export default class Dream {
      * of columns that have changed since last persist,
      * and their current values.
      *
+     * On a record that has not been persisted, every
+     * column counts as changed: the object has a key
+     * for every column, including those never assigned,
+     * whose value is `undefined`.
+     *
      * ```ts
      *  const user = User.new({ email: 'hello@world' })
      *  user.dirtyAttributes()
-     *  // { email: 'hello@world' }
+     *  // { id: undefined, email: 'hello@world', name: undefined, ...every other column: undefined }
      *
      *  await user.save()
      *

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

@@ -508,10 +508,10 @@ ${INDENT}Examples: User, Place, Room/Bedroom, Settings/CommunicationPreferences`
      * (package.json scripts, CLI argv, scaffold templates) — never from
      * runtime request input or any other untrusted external source.
      *
-     * Argv-form is the safe choice for any caller that interpolates a
-     * config value, path, or credential: a database password containing
-     * `$` or backticks is passed literally to the child rather than
-     * interpreted by a shell.
+     * Argv-form passes config values and paths literally to the child,
+     * without interpreting shell metacharacters. Credentials belong in
+     * the child's environment, since argv is visible in process listings
+     * and in the refused-spawn error.
      *
      * ## Layered defense
      *

package/dist/esm/src/db/helpers/syncDbTypesFiles.js

@@ -13,16 +13,14 @@ export default async function syncDbTypesFiles(connectionName) {
     const dbFilename = dbTypesFilenameForConnection(connectionName);
     const dbSyncFilePath = path.join(dreamPath('types'), dbFilename);
     const absoluteDbSyncPath = path.join(dreamApp.projectRoot, dbSyncFilePath);
+    const password = await driverClass.codegenPassword(dbConf.password);
     await CliFileWriter.cache(absoluteDbSyncPath);
     const lowLevelDbOpts = dreamApp.dbCredentialsFor(connectionName);
-    // Argv form (R-015): the connection URL embeds the DB password, and passwords
-    // may legitimately contain shell meta-characters (`$`, backticks, spaces, etc.).
-    // DreamCLI.spawn always uses shell:false, so each arg is passed literally to
-    // the child rather than parsed by a shell — credentials are preserved and any
-    // future mutable source can't open a command-injection surface.
-    const userinfo = `${dbConf.user}${dbConf.password ? `:${dbConf.password}` : ''}`;
+    // Pass the URL only in the child's environment. A URL in argv exposes the
+    // password in the process command line and DreamCLI's refused-spawn error.
+    const userinfo = `${encodeURIComponent(dbConf.user)}${password ? `:${encodeURIComponent(password)}` : ''}`;
     const url = `${driverClass.syncDialect}://${userinfo}@${dbConf.host}:${dbConf.port}/${dbConf.name}`;
-    const args = [`--dialect=${driverClass.syncDialect}`, `--url=${url}`];
+    const args = [`--dialect=${driverClass.syncDialect}`, '--url=env(DATABASE_URL)'];
     if (lowLevelDbOpts?.tableIncludePattern) {
         args.push(`--include-pattern=${lowLevelDbOpts.tableIncludePattern}`);
     }
@@ -32,6 +30,7 @@ export default async function syncDbTypesFiles(connectionName) {
     args.push(`--out-file=${absoluteDbSyncPath}`);
     await DreamCLI.spawn('kysely-codegen', {
         args,
+        env: { ...process.env, DATABASE_URL: url },
         onStdout: message => {
             DreamCLI.logger.logContinueProgress(colorize(`[db]`, { color: 'greenBright' }) + ' ' + message, {
                 logPrefixColor: 'greenBright',

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