@rvoh/dream 2.33.0 → 2.35.0

package/dist/types/src/decorators/Decorators.d.ts

@@ -399,9 +399,14 @@ export default class Decorators<TD extends typeof Dream, T extends Dream = Insta
      * }
      * ```
      *
+     * 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(this: Decorators<TD>, opts?: AfterHookOpts<T>): any;
+    AfterCreateCommit(this: Decorators<TD>, opts?: AfterHookOpts<T>): import("../types/lifecycle.js").CommitHookDecorator;
     /**
      * AfterSave decorator
      *
@@ -430,10 +435,15 @@ export default class Decorators<TD extends typeof Dream, T extends Dream = Insta
      * }
      * ```
      *
+     * 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
      *
      */
-    AfterSaveCommit(this: Decorators<TD>, opts?: AfterHookOpts<T>): any;
+    AfterSaveCommit(this: Decorators<TD>, opts?: AfterHookOpts<T>): import("../types/lifecycle.js").CommitHookDecorator;
     /**
      * AfterUpdate decorator
      *
@@ -462,10 +472,15 @@ export default class Decorators<TD extends typeof Dream, T extends Dream = Insta
      * }
      * ```
      *
+     * 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
      *
      */
-    AfterUpdateCommit(this: Decorators<TD>, opts?: AfterHookOpts<T>): any;
+    AfterUpdateCommit(this: Decorators<TD>, opts?: AfterHookOpts<T>): import("../types/lifecycle.js").CommitHookDecorator;
     /**
      * AfterDestroy decorator
      *
@@ -494,8 +509,13 @@ export default class Decorators<TD extends typeof Dream, T extends Dream = Insta
      * }
      * ```
      *
+     * 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
      *
      */
-    AfterDestroyCommit(this: Decorators<TD>): any;
+    AfterDestroyCommit(this: Decorators<TD>): import("../types/lifecycle.js").CommitHookDecorator;
 }

package/dist/types/src/decorators/field/lifecycle/AfterCreateCommit.d.ts

@@ -1,5 +1,5 @@
 import Dream from '../../../Dream.js';
-import { AfterHookOpts } from '../../../types/lifecycle.js';
+import { AfterHookOpts, CommitHookDecorator } from '../../../types/lifecycle.js';
 /**
  * Calls the decorated method whenever a dream has finished
  * being created. If the save takes place within a transaction,
@@ -8,6 +8,10 @@ import { AfterHookOpts } from '../../../types/lifecycle.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() {
@@ -17,5 +21,5 @@ import { AfterHookOpts } from '../../../types/lifecycle.js';
  *
  * @param opts.ifChanged - Optional. A list of columns which should must change in order for this function to be called.
  */
-export default function AfterCreateCommit<T extends Dream>(opts?: AfterHookOpts<T>): any;
+export default function AfterCreateCommit<T extends Dream>(opts?: AfterHookOpts<T>): CommitHookDecorator;
 export declare function afterCreateCommitImplementation<T extends Dream>(target: T, key: string, opts?: AfterHookOpts<T>): void;

package/dist/types/src/decorators/field/lifecycle/AfterDestroyCommit.d.ts

@@ -1,4 +1,5 @@
 import Dream from '../../../Dream.js';
+import { CommitHookDecorator } from '../../../types/lifecycle.js';
 /**
  * Calls the decorated method whenever a dream has finished
  * being destroyed. If the destroy takes place within a transaction,
@@ -7,6 +8,10 @@ import Dream from '../../../Dream.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() {
@@ -14,5 +19,5 @@ import Dream from '../../../Dream.js';
  *   }
  * }
  */
-export default function AfterDestroyCommit(): any;
+export default function AfterDestroyCommit(): CommitHookDecorator;
 export declare function afterDestroyCommitImplementation<T extends Dream>(target: T, key: string): void;

package/dist/types/src/decorators/field/lifecycle/AfterSaveCommit.d.ts

@@ -1,5 +1,5 @@
 import Dream from '../../../Dream.js';
-import { AfterHookOpts } from '../../../types/lifecycle.js';
+import { AfterHookOpts, CommitHookDecorator } from '../../../types/lifecycle.js';
 /**
  * Calls the decorated method whenever a dream has finished
  * being saved. If the save takes place within a transaction,
@@ -8,6 +8,10 @@ import { AfterHookOpts } from '../../../types/lifecycle.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() {
@@ -17,5 +21,5 @@ import { AfterHookOpts } from '../../../types/lifecycle.js';
  *
  * @param opts.ifChanged - Optional. A list of columns which should must change in order for this function to be called.
  */
-export default function AfterSaveCommit<T extends Dream>(opts?: AfterHookOpts<T>): any;
+export default function AfterSaveCommit<T extends Dream>(opts?: AfterHookOpts<T>): CommitHookDecorator;
 export declare function afterSaveCommitImplementation<T extends Dream>(target: T, key: string, opts?: AfterHookOpts<T>): void;

package/dist/types/src/decorators/field/lifecycle/AfterUpdateCommit.d.ts

@@ -1,5 +1,5 @@
 import Dream from '../../../Dream.js';
-import { AfterHookOpts } from '../../../types/lifecycle.js';
+import { AfterHookOpts, CommitHookDecorator } from '../../../types/lifecycle.js';
 /**
  * Calls the decorated method whenever a dream has finished
  * being updated. If the save takes place within a transaction,
@@ -8,6 +8,10 @@ import { AfterHookOpts } from '../../../types/lifecycle.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() {
@@ -17,5 +21,5 @@ import { AfterHookOpts } from '../../../types/lifecycle.js';
  *
  * @param opts.ifChanged - Optional. A list of columns which should must change in order for this function to be called.
  */
-export default function AfterUpdateCommit<T extends Dream>(opts?: AfterHookOpts<T>): any;
+export default function AfterUpdateCommit<T extends Dream>(opts?: AfterHookOpts<T>): CommitHookDecorator;
 export declare function afterUpdateCommitImplementation<T extends Dream>(target: T, key: string, opts?: AfterHookOpts<T>): void;

package/dist/types/src/dream/DreamTransaction.d.ts

@@ -8,8 +8,15 @@ export interface TransactionCommitHookStatement {
 export default class DreamTransaction<T extends Dream, DB extends T['DB'] = T['DB']> {
     private _kyselyTransaction;
     private commitHooks;
+    private committed;
     get kyselyTransaction(): Transaction<DB>;
     set kyselyTransaction(txn: Transaction<DB>);
     addCommitHook(hookStatement: HookStatement, dreamInstance: Dream): void;
-    runAfterCommitHooks(txn: DreamTransaction<any>): Promise<void>;
+    /**
+     * 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.
+     */
+    runAfterCommitHooks(): Promise<void>;
 }

package/dist/types/src/dream/internal/runHooksFor.d.ts

@@ -6,3 +6,8 @@ export default function runHooksFor<T extends Dream>(key: HookType, dream: T, al
     now: any;
 }>> | null, txn: DreamTransaction<any> | null): Promise<void>;
 export declare function runHook<T extends Dream>(statement: HookStatement, dream: T, txn: DreamTransaction<any> | null): Promise<void>;
+/**
+ * Commit hooks run after the transaction has committed, so they are called
+ * with no argument.
+ */
+export declare function runCommitHook<T extends Dream>(statement: HookStatement, dream: T): Promise<void>;

package/dist/types/src/dream/internal/withConcurrentWriterRetry.d.ts

@@ -23,7 +23,8 @@ export declare 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

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

@@ -2,6 +2,35 @@ import Dream from '../Dream.js';
 import { DreamColumnNames } from './dream.js';
 export type HookType = 'beforeCreate' | 'beforeSave' | 'beforeUpdate' | 'beforeDestroy' | 'afterCreate' | 'afterSave' | 'afterUpdate' | 'afterDestroy' | CommitHookType;
 export type CommitHookType = 'afterCreateCommit' | 'afterSaveCommit' | 'afterUpdateCommit' | 'afterDestroyCommit';
+/**
+ * The decorator returned by `deco.AfterCreateCommit()`,
+ * `deco.AfterSaveCommit()`, `deco.AfterUpdateCommit()` and
+ * `deco.AfterDestroyCommit()`.
+ *
+ * Dream calls every commit hook with no argument: by the time it runs, the
+ * transaction has already committed, so there is no transaction to hand it.
+ * Decorating an instance method that declares a parameter — required,
+ * optional, defaulted or rest — is therefore a compile error.
+ *
+ * Other placements of the decorator (an arrow-function field, an `accessor`
+ * field, a getter, a static method) are not checked.
+ *
+ * A subclass that overrides a decorated commit hook without decorating the
+ * override is not checked either, so `override hook(txn?: ...)` compiles; at
+ * runtime the override is still called with no argument.
+ */
+export interface CommitHookDecorator {
+    <This, Method extends (...args: any[]) => unknown>(value: This extends abstract new (...args: any[]) => unknown ? Method : CommitHookMethod<Method>, context: ClassMethodDecoratorContext<This, Method>): void;
+    (value: any, context: ClassFieldDecoratorContext<any, any> | ClassGetterDecoratorContext<any, any> | ClassSetterDecoratorContext<any, any> | ClassAccessorDecoratorContext<any, any> | ClassDecoratorContext<any>): void;
+}
+/**
+ * A method a commit-hook decorator accepts: one that declares no parameter.
+ * Any other method resolves to a message naming the problem, which the
+ * decorated method is not assignable to. The parameter tuple is compared
+ * whole, so a rest parameter typed as a union such as `[] | [X]` is rejected
+ * too.
+ */
+export type CommitHookMethod<Method> = Method extends (...args: infer Params) => unknown ? [Params] extends [[]] ? Method : 'a commit hook is called with no argument: remove its parameters' : never;
 export interface HookStatement {
     type: HookType;
     className: string;

package/dist/types/src/types/types/lifecycle.ts

@@ -18,6 +18,52 @@ export type CommitHookType =
   | 'afterUpdateCommit'
   | 'afterDestroyCommit'
 
+/**
+ * The decorator returned by `deco.AfterCreateCommit()`,
+ * `deco.AfterSaveCommit()`, `deco.AfterUpdateCommit()` and
+ * `deco.AfterDestroyCommit()`.
+ *
+ * Dream calls every commit hook with no argument: by the time it runs, the
+ * transaction has already committed, so there is no transaction to hand it.
+ * Decorating an instance method that declares a parameter — required,
+ * optional, defaulted or rest — is therefore a compile error.
+ *
+ * Other placements of the decorator (an arrow-function field, an `accessor`
+ * field, a getter, a static method) are not checked.
+ *
+ * A subclass that overrides a decorated commit hook without decorating the
+ * override is not checked either, so `override hook(txn?: ...)` compiles; at
+ * runtime the override is still called with no argument.
+ */
+export interface CommitHookDecorator {
+  <This, Method extends (...args: any[]) => unknown>(
+    value: This extends abstract new (...args: any[]) => unknown ? Method : CommitHookMethod<Method>,
+    context: ClassMethodDecoratorContext<This, Method>
+  ): void
+  (
+    value: any,
+    context:
+      | ClassFieldDecoratorContext<any, any>
+      | ClassGetterDecoratorContext<any, any>
+      | ClassSetterDecoratorContext<any, any>
+      | ClassAccessorDecoratorContext<any, any>
+      | ClassDecoratorContext<any>
+  ): void
+}
+
+/**
+ * A method a commit-hook decorator accepts: one that declares no parameter.
+ * Any other method resolves to a message naming the problem, which the
+ * decorated method is not assignable to. The parameter tuple is compared
+ * whole, so a rest parameter typed as a union such as `[] | [X]` is rejected
+ * too.
+ */
+export type CommitHookMethod<Method> = Method extends (...args: infer Params) => unknown
+  ? [Params] extends [[]]
+    ? Method
+    : 'a commit hook is called with no argument: remove its parameters'
+  : never
+
 export interface HookStatement {
   type: HookType
   className: string