@zenstackhq/runtime 3.0.0-alpha.31 → 3.0.0-alpha.32

package/dist/{contract-5Wcmlo5v.d.cts → contract-CToGslMD.d.cts}

@@ -674,24 +674,26 @@ type OnQueryHookContext<Schema extends SchemaDef> = {
 };
 type EntityMutationHooksDef<Schema extends SchemaDef> = {
     /**
-     * This callback determines whether a mutation should be intercepted, and if so,
-     * what data should be loaded before and after the mutation.
-     */
-    mutationInterceptionFilter?: MutationInterceptionFilter<Schema>;
-    /**
-     * Called before an entity is mutated.
-     * @param args.entity Only available if `loadBeforeMutationEntities` is set to true in the
-     * return value of {@link RuntimePlugin.mutationInterceptionFilter}.
+     * Called before entities are mutated.
      */
     beforeEntityMutation?: BeforeEntityMutationCallback<Schema>;
     /**
-     * Called after an entity is mutated.
-     * @param args.beforeMutationEntity Only available if `loadBeforeMutationEntities` is set to true in the
-     * return value of {@link RuntimePlugin.mutationInterceptionFilter}.
-     * @param args.afterMutationEntity Only available if `loadAfterMutationEntities` is set to true in the
-     * return value of {@link RuntimePlugin.mutationInterceptionFilter}.
+     * Called after entities are mutated.
      */
     afterEntityMutation?: AfterEntityMutationCallback<Schema>;
+    /**
+     * Whether to run after-mutation hooks within the transaction that performs the mutation.
+     *
+     * If set to `true`, if the mutation already runs inside a transaction, the callbacks are
+     * executed immediately after the mutation within the transaction boundary. If the mutation
+     * is not running inside a transaction, a new transaction is created to run both the mutation
+     * and the callbacks.
+     *
+     * If set to `false`, the callbacks are executed after the mutation transaction is committed.
+     *
+     * Defaults to `false`.
+     */
+    runAfterMutationWithinTransaction?: boolean;
 };
 type MutationHooksArgs<Schema extends SchemaDef> = {
     /**
@@ -706,45 +708,41 @@ type MutationHooksArgs<Schema extends SchemaDef> = {
      * The mutation data. Only available for create and update actions.
      */
     queryNode: OperationNode;
-};
-type MutationInterceptionFilter<Schema extends SchemaDef> = (args: MutationHooksArgs<Schema>) => MaybePromise<MutationInterceptionFilterResult>;
-/**
- * The result of the hooks interception filter.
- */
-type MutationInterceptionFilterResult = {
     /**
-     * Whether to intercept the mutation or not.
+     * A query ID that uniquely identifies the mutation operation. You can use it to correlate
+     * data between the before and after mutation hooks.
      */
-    intercept: boolean;
-    /**
-     * Whether entities should be loaded before the mutation.
-     */
-    loadBeforeMutationEntities?: boolean;
-    /**
-     * Whether entities should be loaded after the mutation.
-     */
-    loadAfterMutationEntities?: boolean;
+    queryId: string;
 };
 type BeforeEntityMutationCallback<Schema extends SchemaDef> = (args: PluginBeforeEntityMutationArgs<Schema>) => MaybePromise<void>;
 type AfterEntityMutationCallback<Schema extends SchemaDef> = (args: PluginAfterEntityMutationArgs<Schema>) => MaybePromise<void>;
 type PluginBeforeEntityMutationArgs<Schema extends SchemaDef> = MutationHooksArgs<Schema> & {
     /**
-     * Entities that are about to be mutated. Only available if `loadBeforeMutationEntities` is set to
-     * true in the return value of {@link RuntimePlugin.mutationInterceptionFilter}.
+     * Loads the entities that are about to be mutated. The db operation that loads the entities is executed
+     * within the same transaction context as the mutation.
+     */
+    loadBeforeMutationEntities(): Promise<Record<string, unknown>[] | undefined>;
+    /**
+     * The ZenStack client you can use to perform additional operations. The database operations initiated
+     * from this client are executed within the same transaction as the mutation if the mutation is running
+     * inside a transaction.
+     *
+     * Mutations initiated from this client will NOT trigger entity mutation hooks to avoid infinite loops.
      */
-    entities?: unknown[];
+    client: ClientContract<Schema>;
 };
 type PluginAfterEntityMutationArgs<Schema extends SchemaDef> = MutationHooksArgs<Schema> & {
     /**
-     * Entities that are about to be mutated. Only available if `loadBeforeMutationEntities` is set to
-     * true in the return value of {@link RuntimePlugin.mutationInterceptionFilter}.
+     * Loads the entities that have been mutated.
      */
-    beforeMutationEntities?: unknown[];
+    loadAfterMutationEntities(): Promise<Record<string, unknown>[] | undefined>;
     /**
-     * Entities mutated. Only available if `loadAfterMutationEntities` is set to true in the return
-     * value of {@link RuntimePlugin.mutationInterceptionFilter}.
+     * The ZenStack client you can use to perform additional operations.
+     * See {@link EntityMutationHooksDef.runAfterMutationWithinTransaction} for detailed transaction behavior.
+     *
+     * Mutations initiated from this client will NOT trigger entity mutation hooks to avoid infinite loops.
      */
-    afterMutationEntities?: unknown[];
+    client: ClientContract<Schema>;
 };
 type OnKyselyQueryArgs<Schema extends SchemaDef> = {
     kysely: ToKysely<Schema>;

package/dist/{contract-5Wcmlo5v.d.ts → contract-CToGslMD.d.ts}

@@ -674,24 +674,26 @@ type OnQueryHookContext<Schema extends SchemaDef> = {
 };
 type EntityMutationHooksDef<Schema extends SchemaDef> = {
     /**
-     * This callback determines whether a mutation should be intercepted, and if so,
-     * what data should be loaded before and after the mutation.
-     */
-    mutationInterceptionFilter?: MutationInterceptionFilter<Schema>;
-    /**
-     * Called before an entity is mutated.
-     * @param args.entity Only available if `loadBeforeMutationEntities` is set to true in the
-     * return value of {@link RuntimePlugin.mutationInterceptionFilter}.
+     * Called before entities are mutated.
      */
     beforeEntityMutation?: BeforeEntityMutationCallback<Schema>;
     /**
-     * Called after an entity is mutated.
-     * @param args.beforeMutationEntity Only available if `loadBeforeMutationEntities` is set to true in the
-     * return value of {@link RuntimePlugin.mutationInterceptionFilter}.
-     * @param args.afterMutationEntity Only available if `loadAfterMutationEntities` is set to true in the
-     * return value of {@link RuntimePlugin.mutationInterceptionFilter}.
+     * Called after entities are mutated.
      */
     afterEntityMutation?: AfterEntityMutationCallback<Schema>;
+    /**
+     * Whether to run after-mutation hooks within the transaction that performs the mutation.
+     *
+     * If set to `true`, if the mutation already runs inside a transaction, the callbacks are
+     * executed immediately after the mutation within the transaction boundary. If the mutation
+     * is not running inside a transaction, a new transaction is created to run both the mutation
+     * and the callbacks.
+     *
+     * If set to `false`, the callbacks are executed after the mutation transaction is committed.
+     *
+     * Defaults to `false`.
+     */
+    runAfterMutationWithinTransaction?: boolean;
 };
 type MutationHooksArgs<Schema extends SchemaDef> = {
     /**
@@ -706,45 +708,41 @@ type MutationHooksArgs<Schema extends SchemaDef> = {
      * The mutation data. Only available for create and update actions.
      */
     queryNode: OperationNode;
-};
-type MutationInterceptionFilter<Schema extends SchemaDef> = (args: MutationHooksArgs<Schema>) => MaybePromise<MutationInterceptionFilterResult>;
-/**
- * The result of the hooks interception filter.
- */
-type MutationInterceptionFilterResult = {
     /**
-     * Whether to intercept the mutation or not.
+     * A query ID that uniquely identifies the mutation operation. You can use it to correlate
+     * data between the before and after mutation hooks.
      */
-    intercept: boolean;
-    /**
-     * Whether entities should be loaded before the mutation.
-     */
-    loadBeforeMutationEntities?: boolean;
-    /**
-     * Whether entities should be loaded after the mutation.
-     */
-    loadAfterMutationEntities?: boolean;
+    queryId: string;
 };
 type BeforeEntityMutationCallback<Schema extends SchemaDef> = (args: PluginBeforeEntityMutationArgs<Schema>) => MaybePromise<void>;
 type AfterEntityMutationCallback<Schema extends SchemaDef> = (args: PluginAfterEntityMutationArgs<Schema>) => MaybePromise<void>;
 type PluginBeforeEntityMutationArgs<Schema extends SchemaDef> = MutationHooksArgs<Schema> & {
     /**
-     * Entities that are about to be mutated. Only available if `loadBeforeMutationEntities` is set to
-     * true in the return value of {@link RuntimePlugin.mutationInterceptionFilter}.
+     * Loads the entities that are about to be mutated. The db operation that loads the entities is executed
+     * within the same transaction context as the mutation.
+     */
+    loadBeforeMutationEntities(): Promise<Record<string, unknown>[] | undefined>;
+    /**
+     * The ZenStack client you can use to perform additional operations. The database operations initiated
+     * from this client are executed within the same transaction as the mutation if the mutation is running
+     * inside a transaction.
+     *
+     * Mutations initiated from this client will NOT trigger entity mutation hooks to avoid infinite loops.
      */
-    entities?: unknown[];
+    client: ClientContract<Schema>;
 };
 type PluginAfterEntityMutationArgs<Schema extends SchemaDef> = MutationHooksArgs<Schema> & {
     /**
-     * Entities that are about to be mutated. Only available if `loadBeforeMutationEntities` is set to
-     * true in the return value of {@link RuntimePlugin.mutationInterceptionFilter}.
+     * Loads the entities that have been mutated.
      */
-    beforeMutationEntities?: unknown[];
+    loadAfterMutationEntities(): Promise<Record<string, unknown>[] | undefined>;
     /**
-     * Entities mutated. Only available if `loadAfterMutationEntities` is set to true in the return
-     * value of {@link RuntimePlugin.mutationInterceptionFilter}.
+     * The ZenStack client you can use to perform additional operations.
+     * See {@link EntityMutationHooksDef.runAfterMutationWithinTransaction} for detailed transaction behavior.
+     *
+     * Mutations initiated from this client will NOT trigger entity mutation hooks to avoid infinite loops.
      */
-    afterMutationEntities?: unknown[];
+    client: ClientContract<Schema>;
 };
 type OnKyselyQueryArgs<Schema extends SchemaDef> = {
     kysely: ToKysely<Schema>;