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

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

@@ -1,5 +1,5 @@
 import Decimal, { Decimal as Decimal$1 } from 'decimal.js';
-import { SchemaDef, GetModels, ScalarFields, ForeignKeyFields, GetModelFields, FieldHasDefault, GetModelFieldType, ModelFieldIsOptional, GetModelField, NonRelationFields, RelationFields, FieldIsArray, RelationFieldType, FieldIsRelation, GetModel, FieldDef, GetEnums, GetEnum, GetTypeDefs, GetTypeDefFields, GetTypeDefField, TypeDefFieldIsOptional, BuiltinType, IsDelegateModel, GetModelDiscriminator, GetSubModels, FieldIsDelegateDiscriminator, FieldType, RelationInfo, FieldIsDelegateRelation, DataSourceProviderType, ProcedureDef } from '@zenstackhq/sdk/schema';
+import { SchemaDef, GetModels, ScalarFields, ForeignKeyFields, GetModelFields, FieldHasDefault, GetModelFieldType, ModelFieldIsOptional, GetModelField, NonRelationFields, RelationFields, FieldIsArray, RelationFieldType, FieldIsRelation, GetModel, FieldDef, GetEnums, GetEnum, GetTypeDefs, GetTypeDefFields, GetTypeDefField, TypeDefFieldIsOptional, BuiltinType, IsDelegateModel, GetModelDiscriminator, GetSubModels, FieldIsDelegateDiscriminator, FieldType, RelationInfo, FieldIsDelegateRelation, ModelDef, DataSourceProviderType, ProcedureDef } from '@zenstackhq/sdk/schema';
 import { Generated, Kysely, ExpressionBuilder, OperandExpression, SqlBool, SelectQueryBuilder, Expression, ExpressionWrapper, OperationNode, RootOperationNode, QueryResult, UnknownRow, Dialect, KyselyConfig } from 'kysely';
 
 type Optional<T extends object, K extends keyof T = keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
@@ -558,6 +558,7 @@ declare abstract class BaseCrudDialect<Schema extends SchemaDef> {
     private buildEnumFilter;
     buildOrderBy(query: SelectQueryBuilder<any, any, any>, model: string, modelAlias: string, orderBy: OrArray<OrderBy<Schema, GetModels<Schema>, boolean, boolean>> | undefined, useDefaultIfEmpty: boolean, negated: boolean): SelectQueryBuilder<any, any, any>;
     buildSelectAllFields(model: string, query: SelectQueryBuilder<any, any, any>, omit: Record<string, boolean | undefined> | undefined, modelAlias: string): SelectQueryBuilder<any, any, any>;
+    protected buildModelSelect(eb: ExpressionBuilder<any, any>, model: GetModels<Schema>, subQueryAlias: string, payload: true | FindArgs<Schema, GetModels<Schema>, true>, selectAllFields: boolean): SelectQueryBuilder<any, any, {}>;
     buildSelectField(query: SelectQueryBuilder<any, any, any>, model: string, modelAlias: string, field: string): SelectQueryBuilder<any, any, any>;
     buildDelegateJoin(thisModel: string, thisModelAlias: string, otherModelAlias: string, query: SelectQueryBuilder<any, any, any>): SelectQueryBuilder<any, any, any>;
     buildCountJson(model: string, eb: ExpressionBuilder<any, any>, parentAlias: string, payload: any): ExpressionWrapper<any, any, unknown>;
@@ -570,6 +571,7 @@ declare abstract class BaseCrudDialect<Schema extends SchemaDef> {
     protected or(eb: ExpressionBuilder<any, any>, ...args: Expression<SqlBool>[]): Expression<SqlBool>;
     protected not(eb: ExpressionBuilder<any, any>, ...args: Expression<SqlBool>[]): ExpressionWrapper<any, any, SqlBool>;
     fieldRef(model: string, field: string, eb: ExpressionBuilder<any, any>, modelAlias?: string, inlineComputedField?: boolean): ExpressionWrapper<any, any, unknown>;
+    protected canJoinWithoutNestedSelect(modelDef: ModelDef, payload: boolean | FindArgs<Schema, GetModels<Schema>, true>): boolean;
     abstract get provider(): DataSourceProviderType;
     /**
      * Builds selection for a relation field.
@@ -674,24 +676,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 +710,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-CusA0mQO.d.ts}

@@ -1,5 +1,5 @@
 import Decimal, { Decimal as Decimal$1 } from 'decimal.js';
-import { SchemaDef, GetModels, ScalarFields, ForeignKeyFields, GetModelFields, FieldHasDefault, GetModelFieldType, ModelFieldIsOptional, GetModelField, NonRelationFields, RelationFields, FieldIsArray, RelationFieldType, FieldIsRelation, GetModel, FieldDef, GetEnums, GetEnum, GetTypeDefs, GetTypeDefFields, GetTypeDefField, TypeDefFieldIsOptional, BuiltinType, IsDelegateModel, GetModelDiscriminator, GetSubModels, FieldIsDelegateDiscriminator, FieldType, RelationInfo, FieldIsDelegateRelation, DataSourceProviderType, ProcedureDef } from '@zenstackhq/sdk/schema';
+import { SchemaDef, GetModels, ScalarFields, ForeignKeyFields, GetModelFields, FieldHasDefault, GetModelFieldType, ModelFieldIsOptional, GetModelField, NonRelationFields, RelationFields, FieldIsArray, RelationFieldType, FieldIsRelation, GetModel, FieldDef, GetEnums, GetEnum, GetTypeDefs, GetTypeDefFields, GetTypeDefField, TypeDefFieldIsOptional, BuiltinType, IsDelegateModel, GetModelDiscriminator, GetSubModels, FieldIsDelegateDiscriminator, FieldType, RelationInfo, FieldIsDelegateRelation, ModelDef, DataSourceProviderType, ProcedureDef } from '@zenstackhq/sdk/schema';
 import { Generated, Kysely, ExpressionBuilder, OperandExpression, SqlBool, SelectQueryBuilder, Expression, ExpressionWrapper, OperationNode, RootOperationNode, QueryResult, UnknownRow, Dialect, KyselyConfig } from 'kysely';
 
 type Optional<T extends object, K extends keyof T = keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
@@ -558,6 +558,7 @@ declare abstract class BaseCrudDialect<Schema extends SchemaDef> {
     private buildEnumFilter;
     buildOrderBy(query: SelectQueryBuilder<any, any, any>, model: string, modelAlias: string, orderBy: OrArray<OrderBy<Schema, GetModels<Schema>, boolean, boolean>> | undefined, useDefaultIfEmpty: boolean, negated: boolean): SelectQueryBuilder<any, any, any>;
     buildSelectAllFields(model: string, query: SelectQueryBuilder<any, any, any>, omit: Record<string, boolean | undefined> | undefined, modelAlias: string): SelectQueryBuilder<any, any, any>;
+    protected buildModelSelect(eb: ExpressionBuilder<any, any>, model: GetModels<Schema>, subQueryAlias: string, payload: true | FindArgs<Schema, GetModels<Schema>, true>, selectAllFields: boolean): SelectQueryBuilder<any, any, {}>;
     buildSelectField(query: SelectQueryBuilder<any, any, any>, model: string, modelAlias: string, field: string): SelectQueryBuilder<any, any, any>;
     buildDelegateJoin(thisModel: string, thisModelAlias: string, otherModelAlias: string, query: SelectQueryBuilder<any, any, any>): SelectQueryBuilder<any, any, any>;
     buildCountJson(model: string, eb: ExpressionBuilder<any, any>, parentAlias: string, payload: any): ExpressionWrapper<any, any, unknown>;
@@ -570,6 +571,7 @@ declare abstract class BaseCrudDialect<Schema extends SchemaDef> {
     protected or(eb: ExpressionBuilder<any, any>, ...args: Expression<SqlBool>[]): Expression<SqlBool>;
     protected not(eb: ExpressionBuilder<any, any>, ...args: Expression<SqlBool>[]): ExpressionWrapper<any, any, SqlBool>;
     fieldRef(model: string, field: string, eb: ExpressionBuilder<any, any>, modelAlias?: string, inlineComputedField?: boolean): ExpressionWrapper<any, any, unknown>;
+    protected canJoinWithoutNestedSelect(modelDef: ModelDef, payload: boolean | FindArgs<Schema, GetModels<Schema>, true>): boolean;
     abstract get provider(): DataSourceProviderType;
     /**
      * Builds selection for a relation field.
@@ -674,24 +676,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 +710,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>;