@expo/entity 0.62.0 → 0.63.0

package/build/src/EntityDatabaseAdapter.d.ts

@@ -56,10 +56,11 @@ export declare abstract class EntityDatabaseAdapter<TFields extends Record<strin
      * @param idField - the field in the object that is the ID
      * @param id - the value of the ID field in the object
      * @param object - the object to update
-     * @returns the updated object
      */
-    updateAsync<K extends keyof TFields>(queryContext: EntityQueryContext, idField: K, id: any, object: Readonly<Partial<TFields>>): Promise<Readonly<TFields>>;
-    protected abstract updateInternalAsync(queryInterface: any, tableName: string, tableIdField: string, id: any, object: object): Promise<object[]>;
+    updateAsync<K extends keyof TFields>(queryContext: EntityQueryContext, idField: K, id: any, object: Readonly<Partial<TFields>>): Promise<void>;
+    protected abstract updateInternalAsync(queryInterface: any, tableName: string, tableIdField: string, id: any, object: object): Promise<{
+        updatedRowCount: number;
+    }>;
     /**
      * Delete an object by ID.
      *

package/build/src/EntityDatabaseAdapter.js

@@ -87,22 +87,20 @@ export class EntityDatabaseAdapter {
      * @param idField - the field in the object that is the ID
      * @param id - the value of the ID field in the object
      * @param object - the object to update
-     * @returns the updated object
      */
     async updateAsync(queryContext, idField, id, object) {
         const idColumn = getDatabaseFieldForEntityField(this.entityConfiguration, idField);
         const dbObject = transformFieldsToDatabaseObject(this.entityConfiguration, this.fieldTransformerMap, object);
-        const results = await this.updateInternalAsync(queryContext.getQueryInterface(), this.entityConfiguration.tableName, idColumn, id, dbObject);
-        if (results.length > 1) {
+        const { updatedRowCount } = await this.updateInternalAsync(queryContext.getQueryInterface(), this.entityConfiguration.tableName, idColumn, id, dbObject);
+        if (updatedRowCount > 1) {
             // This should never happen with a properly implemented database adapter unless the underlying table has a non-unique
             // primary key column.
             throw new EntityDatabaseAdapterExcessiveUpdateResultError(`Excessive results from database adapter update: ${this.entityConfiguration.tableName}(id = ${id})`);
         }
-        else if (results.length === 0) {
+        else if (updatedRowCount === 0) {
             // This happens when the object to update does not exist. It may have been deleted by another process.
             throw new EntityDatabaseAdapterEmptyUpdateResultError(`Empty results from database adapter update: ${this.entityConfiguration.tableName}(id = ${id})`);
         }
-        return transformDatabaseObjectToFields(this.entityConfiguration, this.fieldTransformerMap, results[0]);
     }
     /**
      * Delete an object by ID.

package/build/src/EntityMutationInfo.d.ts

@@ -1,8 +1,20 @@
 import type { Entity } from './Entity.ts';
 import type { ViewerContext } from './ViewerContext.ts';
+/**
+ * The type of mutation that is occurring to an entity.
+ */
 export declare enum EntityMutationType {
+    /**
+     * Create mutation.
+     */
     CREATE = 0,
+    /**
+     * Update mutation.
+     */
     UPDATE = 1,
+    /**
+     * Delete mutation.
+     */
     DELETE = 2
 }
 /**
@@ -19,13 +31,32 @@ export type EntityCascadingDeletionInfo = {
     cascadingDeleteCause: EntityCascadingDeletionInfo | null;
 };
 type EntityTriggerOrValidatorMutationInfo<TFields extends Record<string, any>, TIDField extends keyof NonNullable<Pick<TFields, TSelectedFields>>, TViewerContext extends ViewerContext, TEntity extends Entity<TFields, TIDField, TViewerContext, TSelectedFields>, TSelectedFields extends keyof TFields = keyof TFields> = {
+    /**
+     * The type of mutation that invoked this trigger or validator.
+     */
     type: EntityMutationType.CREATE;
 } | {
+    /**
+     * The type of mutation that invoked this trigger or validator.
+     */
     type: EntityMutationType.UPDATE;
+    /**
+     * The previous value of the entity before the update.
+     */
     previousValue: TEntity;
+    /**
+     * If this update is part of a cascading deletion (cascade set null), this field will contain information about the cascade
+     * that caused this update. Otherwise, it will be null.
+     */
     cascadingDeleteCause: EntityCascadingDeletionInfo | null;
 } | {
+    /**
+     * The type of mutation that invoked this trigger or validator.
+     */
     type: EntityMutationType.DELETE;
+    /**
+     * If this delete is part of a cascading deletion, this field will contain information about the cascade that caused this cascading delete.
+     */
     cascadingDeleteCause: EntityCascadingDeletionInfo | null;
 };
 export type EntityValidatorMutationInfo<TFields extends Record<string, any>, TIDField extends keyof NonNullable<Pick<TFields, TSelectedFields>>, TViewerContext extends ViewerContext, TEntity extends Entity<TFields, TIDField, TViewerContext, TSelectedFields>, TSelectedFields extends keyof TFields = keyof TFields> = EntityTriggerOrValidatorMutationInfo<TFields, TIDField, TViewerContext, TEntity, TSelectedFields>;

package/build/src/EntityMutationInfo.js

@@ -1,6 +1,18 @@
+/**
+ * The type of mutation that is occurring to an entity.
+ */
 export var EntityMutationType;
 (function (EntityMutationType) {
+    /**
+     * Create mutation.
+     */
     EntityMutationType[EntityMutationType["CREATE"] = 0] = "CREATE";
+    /**
+     * Update mutation.
+     */
     EntityMutationType[EntityMutationType["UPDATE"] = 1] = "UPDATE";
+    /**
+     * Delete mutation.
+     */
     EntityMutationType[EntityMutationType["DELETE"] = 2] = "DELETE";
 })(EntityMutationType || (EntityMutationType = {}));

package/build/src/EntityQueryContext.d.ts

@@ -1,20 +1,59 @@
 import type { EntityQueryContextProvider } from './EntityQueryContextProvider.ts';
 export type PostCommitCallback = (...args: any) => Promise<any>;
 export type PreCommitCallback = (queryContext: EntityTransactionalQueryContext, ...args: any) => Promise<any>;
+/**
+ * Database transaction isolation level. Controls the visibility of changes made by
+ * concurrent transactions, trading off between consistency and performance.
+ */
 export declare enum TransactionIsolationLevel {
+    /**
+     * Each statement sees only data committed before it began. Default for most databases.
+     */
     READ_COMMITTED = "READ_COMMITTED",
+    /**
+     * All statements in the transaction see the same snapshot taken at the start of the transaction.
+     */
     REPEATABLE_READ = "REPEATABLE_READ",
+    /**
+     * Transactions execute as if they were run one at a time. Strongest guarantee but lowest throughput.
+     */
     SERIALIZABLE = "SERIALIZABLE"
 }
+/**
+ * Controls DataLoader behavior within a transaction.
+ */
 export declare enum TransactionalDataLoaderMode {
+    /**
+     * Default mode where DataLoader is fully enabled, providing both batching and caching benefits within the transaction.
+     */
     ENABLED = "ENABLED",
+    /**
+     * DataLoader is enabled for batching queries together but does not cache results. Use this mode when you want to benefit from batching but need to ensure that each load reflects the most current database state, even within the same transaction.
+     */
     ENABLED_BATCH_ONLY = "ENABLED_BATCH_ONLY",
+    /**
+     * DataLoader is completely disabled for the transaction. Each load will directly query the database without any batching or caching. Use this mode when you need to ensure that every load reflects the most current database state and are not concerned about the performance benefits of batching or caching within the transaction.
+     */
     DISABLED = "DISABLED"
 }
+/**
+ * Configuration options for running a transaction. This includes the isolation level and DataLoader mode for the transaction.
+ */
 export type TransactionConfig = {
+    /**
+     * Transaction isolation level. When omitted, the database default is used (typically READ_COMMITTED).
+     */
     isolationLevel?: TransactionIsolationLevel;
+    /**
+     * DataLoader mode for the transaction. When omitted, defaults to ENABLED.
+     */
     transactionalDataLoaderMode?: TransactionalDataLoaderMode;
 };
+/**
+ * Resolved transaction configuration with all default values filled in.
+ * This is the configuration that is actually used for a transaction after applying defaults.
+ */
+export type ResolvedTransactionConfig = Pick<TransactionConfig, 'isolationLevel'> & Required<Pick<TransactionConfig, 'transactionalDataLoaderMode'>>;
 /**
  * Entity framework representation of transactional and non-transactional database
  * query execution units.
@@ -52,7 +91,7 @@ export declare class EntityTransactionalQueryContext extends EntityQueryContext
      * @internal
      */
     readonly transactionId: string;
-    readonly transactionalDataLoaderMode: TransactionalDataLoaderMode;
+    readonly transactionConfig: ResolvedTransactionConfig;
     /**
      * @internal
      */
@@ -64,7 +103,17 @@ export declare class EntityTransactionalQueryContext extends EntityQueryContext
     /**
      * @internal
      */
-    transactionId: string, transactionalDataLoaderMode: TransactionalDataLoaderMode);
+    transactionId: string, transactionConfig: ResolvedTransactionConfig);
+    /**
+     * DataLoader mode for this transaction set at time of transaction creation, controlling DataLoader caching and batching behavior within the transaction.
+     */
+    get transactionalDataLoaderMode(): TransactionalDataLoaderMode;
+    /**
+     * Transaction isolation level for this transaction set at time of transaction creation.
+     * This controls the visibility of changes made by concurrent transactions.
+     * When undefined, the database default isolation level is used (typically READ_COMMITTED).
+     */
+    get isolationLevel(): TransactionIsolationLevel | undefined;
     /**
      * Schedule a pre-commit callback. These will be run within the transaction right before it is
      * committed, and will be run in the order specified. Ordering of callbacks scheduled with the
@@ -118,7 +167,7 @@ export declare class EntityNestedTransactionalQueryContext extends EntityTransac
     /**
      * @internal
      */
-    parentQueryContext: EntityTransactionalQueryContext, entityQueryContextProvider: EntityQueryContextProvider, transactionId: string, transactionalDataLoaderMode: TransactionalDataLoaderMode);
+    parentQueryContext: EntityTransactionalQueryContext, entityQueryContextProvider: EntityQueryContextProvider, transactionId: string, transactionConfig: ResolvedTransactionConfig);
     isInNestedTransaction(): this is EntityNestedTransactionalQueryContext;
     appendPostCommitCallback(callback: PostCommitCallback): void;
     appendPostCommitInvalidationCallback(callback: PostCommitCallback): void;

package/build/src/EntityQueryContext.js

@@ -1,14 +1,39 @@
 import assert from 'assert';
+/**
+ * Database transaction isolation level. Controls the visibility of changes made by
+ * concurrent transactions, trading off between consistency and performance.
+ */
 export var TransactionIsolationLevel;
 (function (TransactionIsolationLevel) {
+    /**
+     * Each statement sees only data committed before it began. Default for most databases.
+     */
     TransactionIsolationLevel["READ_COMMITTED"] = "READ_COMMITTED";
+    /**
+     * All statements in the transaction see the same snapshot taken at the start of the transaction.
+     */
     TransactionIsolationLevel["REPEATABLE_READ"] = "REPEATABLE_READ";
+    /**
+     * Transactions execute as if they were run one at a time. Strongest guarantee but lowest throughput.
+     */
     TransactionIsolationLevel["SERIALIZABLE"] = "SERIALIZABLE";
 })(TransactionIsolationLevel || (TransactionIsolationLevel = {}));
+/**
+ * Controls DataLoader behavior within a transaction.
+ */
 export var TransactionalDataLoaderMode;
 (function (TransactionalDataLoaderMode) {
+    /**
+     * Default mode where DataLoader is fully enabled, providing both batching and caching benefits within the transaction.
+     */
     TransactionalDataLoaderMode["ENABLED"] = "ENABLED";
+    /**
+     * DataLoader is enabled for batching queries together but does not cache results. Use this mode when you want to benefit from batching but need to ensure that each load reflects the most current database state, even within the same transaction.
+     */
     TransactionalDataLoaderMode["ENABLED_BATCH_ONLY"] = "ENABLED_BATCH_ONLY";
+    /**
+     * DataLoader is completely disabled for the transaction. Each load will directly query the database without any batching or caching. Use this mode when you need to ensure that every load reflects the most current database state and are not concerned about the performance benefits of batching or caching within the transaction.
+     */
     TransactionalDataLoaderMode["DISABLED"] = "DISABLED";
 })(TransactionalDataLoaderMode || (TransactionalDataLoaderMode = {}));
 /**
@@ -54,7 +79,7 @@ export class EntityNonTransactionalQueryContext extends EntityQueryContext {
 export class EntityTransactionalQueryContext extends EntityQueryContext {
     entityQueryContextProvider;
     transactionId;
-    transactionalDataLoaderMode;
+    transactionConfig;
     /**
      * @internal
      */
@@ -66,11 +91,25 @@ export class EntityTransactionalQueryContext extends EntityQueryContext {
     /**
      * @internal
      */
-    transactionId, transactionalDataLoaderMode) {
+    transactionId, transactionConfig) {
         super(queryInterface);
         this.entityQueryContextProvider = entityQueryContextProvider;
         this.transactionId = transactionId;
-        this.transactionalDataLoaderMode = transactionalDataLoaderMode;
+        this.transactionConfig = transactionConfig;
+    }
+    /**
+     * DataLoader mode for this transaction set at time of transaction creation, controlling DataLoader caching and batching behavior within the transaction.
+     */
+    get transactionalDataLoaderMode() {
+        return this.transactionConfig.transactionalDataLoaderMode;
+    }
+    /**
+     * Transaction isolation level for this transaction set at time of transaction creation.
+     * This controls the visibility of changes made by concurrent transactions.
+     * When undefined, the database default isolation level is used (typically READ_COMMITTED).
+     */
+    get isolationLevel() {
+        return this.transactionConfig.isolationLevel;
     }
     /**
      * Schedule a pre-commit callback. These will be run within the transaction right before it is
@@ -153,8 +192,8 @@ export class EntityNestedTransactionalQueryContext extends EntityTransactionalQu
     /**
      * @internal
      */
-    parentQueryContext, entityQueryContextProvider, transactionId, transactionalDataLoaderMode) {
-        super(queryInterface, entityQueryContextProvider, transactionId, transactionalDataLoaderMode);
+    parentQueryContext, entityQueryContextProvider, transactionId, transactionConfig) {
+        super(queryInterface, entityQueryContextProvider, transactionId, transactionConfig);
         this.parentQueryContext = parentQueryContext;
         parentQueryContext.childQueryContexts.push(this);
     }

package/build/src/EntityQueryContextProvider.js

@@ -22,7 +22,12 @@ export class EntityQueryContextProvider {
      */
     async runInTransactionAsync(transactionScope, transactionConfig) {
         const [returnedValue, queryContext] = await this.createTransactionRunner(transactionConfig)(async (queryInterface) => {
-            const queryContext = new EntityTransactionalQueryContext(queryInterface, this, randomUUID(), transactionConfig?.transactionalDataLoaderMode ?? this.defaultTransactionalDataLoaderMode());
+            const resolvedTransactionConfig = {
+                ...transactionConfig,
+                transactionalDataLoaderMode: transactionConfig?.transactionalDataLoaderMode ??
+                    this.defaultTransactionalDataLoaderMode(),
+            };
+            const queryContext = new EntityTransactionalQueryContext(queryInterface, this, randomUUID(), resolvedTransactionConfig);
             const result = await transactionScope(queryContext);
             await queryContext.runPreCommitCallbacksAsync();
             return [result, queryContext];
@@ -38,7 +43,7 @@ export class EntityQueryContextProvider {
      */
     async runInNestedTransactionAsync(outerQueryContext, transactionScope) {
         const [returnedValue, innerQueryContext] = await this.createNestedTransactionRunner(outerQueryContext.getQueryInterface())(async (innerQueryInterface) => {
-            const innerQueryContext = new EntityNestedTransactionalQueryContext(innerQueryInterface, outerQueryContext, this, randomUUID(), outerQueryContext.transactionalDataLoaderMode);
+            const innerQueryContext = new EntityNestedTransactionalQueryContext(innerQueryInterface, outerQueryContext, this, randomUUID(), outerQueryContext.transactionConfig);
             const result = await transactionScope(innerQueryContext);
             await innerQueryContext.runPreCommitCallbacksAsync();
             return [result, innerQueryContext];

package/build/src/EntitySecondaryCacheLoader.d.ts

@@ -32,8 +32,7 @@ export interface ISecondaryEntityCache<TFields extends Record<string, any>, TLoa
  * when the underlying data of a cache key could be stale.
  *
  * This is most commonly used to further optimize hot paths that cannot make use of normal entity cache loading
- * due to use of a non-unique-field-based EntityLoader method like `loadManyByFieldEqualityConjunctionAsync` or
- * `loadManyByRawWhereClauseAsync`.
+ * due to use of a non-unique-field-based EntityLoader method like `loadManyByFieldEqualityConjunctionAsync`.
  */
 export declare abstract class EntitySecondaryCacheLoader<TLoadParams, TFields extends Record<string, any>, TIDField extends keyof NonNullable<Pick<TFields, TSelectedFields>>, TViewerContext extends ViewerContext, TEntity extends ReadonlyEntity<TFields, TIDField, TViewerContext, TSelectedFields>, TPrivacyPolicy extends EntityPrivacyPolicy<TFields, TIDField, TViewerContext, TEntity, TSelectedFields>, TSelectedFields extends keyof TFields = keyof TFields> {
     private readonly secondaryEntityCache;

package/build/src/EntitySecondaryCacheLoader.js

@@ -7,8 +7,7 @@ import { mapMap } from "./utils/collections/maps.js";
  * when the underlying data of a cache key could be stale.
  *
  * This is most commonly used to further optimize hot paths that cannot make use of normal entity cache loading
- * due to use of a non-unique-field-based EntityLoader method like `loadManyByFieldEqualityConjunctionAsync` or
- * `loadManyByRawWhereClauseAsync`.
+ * due to use of a non-unique-field-based EntityLoader method like `loadManyByFieldEqualityConjunctionAsync`.
  */
 export class EntitySecondaryCacheLoader {
     secondaryEntityCache;

package/build/src/errors/EntityInvalidFieldValueError.d.ts

@@ -9,5 +9,7 @@ import { EntityError, EntityErrorCode, EntityErrorState } from './EntityError.ts
 export declare class EntityInvalidFieldValueError<TFields extends Record<string, any>, TIDField extends keyof NonNullable<Pick<TFields, TSelectedFields>>, TViewerContext extends ViewerContext, TEntity extends ReadonlyEntity<TFields, TIDField, TViewerContext, TSelectedFields>, TPrivacyPolicy extends EntityPrivacyPolicy<TFields, TIDField, TViewerContext, TEntity, TSelectedFields>, N extends keyof TFields, TSelectedFields extends keyof TFields = keyof TFields> extends EntityError {
     get state(): EntityErrorState.PERMANENT;
     get code(): EntityErrorCode.ERR_ENTITY_INVALID_FIELD_VALUE;
+    readonly fieldName: N;
+    readonly fieldValue: TFields[N] | undefined;
     constructor(entityClass: IEntityClass<TFields, TIDField, TViewerContext, TEntity, TPrivacyPolicy, TSelectedFields>, fieldName: N, fieldValue?: TFields[N]);
 }

package/build/src/errors/EntityInvalidFieldValueError.js

@@ -12,7 +12,11 @@ export class EntityInvalidFieldValueError extends EntityError {
     get code() {
         return EntityErrorCode.ERR_ENTITY_INVALID_FIELD_VALUE;
     }
+    fieldName;
+    fieldValue;
     constructor(entityClass, fieldName, fieldValue) {
         super(`Entity field not valid: ${entityClass.name} (${String(fieldName)} = ${fieldValue})`);
+        this.fieldName = fieldName;
+        this.fieldValue = fieldValue;
     }
 }

package/build/src/metrics/IEntityMetricsAdapter.d.ts

@@ -1,12 +1,29 @@
 import type { EntityAuthorizationAction, EntityPrivacyPolicyEvaluationMode } from '../EntityPrivacyPolicy.ts';
 import type { EntityLoadMethodType } from '../internal/EntityLoadInterfaces.ts';
+/**
+ * The type of the load method being called.
+ */
 export declare enum EntityMetricsLoadType {
+    /**
+     * Standard EntityLoader load (the methods from EnforcingEntityLoader or AuthorizationResultBasedEntityLoader).
+     */
     LOAD_MANY = 0,
+    /**
+     * Knex loader load using loadManyByFieldEqualityConjunctionAsync.
+     */
     LOAD_MANY_EQUALITY_CONJUNCTION = 1,
-    LOAD_MANY_RAW = 2,
-    LOAD_MANY_SQL = 3,
-    LOAD_ONE = 4,
-    LOAD_PAGE = 5
+    /**
+     * Knex loader load using loadManyBySQL.
+     */
+    LOAD_MANY_SQL = 2,
+    /**
+     * Internal data manager load via database adapter method loadOneEqualingAsync.
+     */
+    LOAD_ONE = 3,
+    /**
+     * Knex loader load using loadPageAsync.
+     */
+    LOAD_PAGE = 4
 }
 /**
  * Event about a single call to an EntityLoader method.
@@ -33,6 +50,9 @@ export interface EntityMetricsLoadEvent {
      */
     count: number;
 }
+/**
+ * The type of mutation being performed.
+ */
 export declare enum EntityMetricsMutationType {
     CREATE = 0,
     UPDATE = 1,
@@ -56,6 +76,9 @@ export interface EntityMetricsMutationEvent {
      */
     duration: number;
 }
+/**
+ * Type used to delineate dataloader, cache, and database load counts in EntityDataManager.
+ */
 export declare enum IncrementLoadCountEventType {
     /**
      * Type for when a dataloader load is initiated via the standard load methods

package/build/src/metrics/IEntityMetricsAdapter.js

@@ -1,18 +1,41 @@
+/**
+ * The type of the load method being called.
+ */
 export var EntityMetricsLoadType;
 (function (EntityMetricsLoadType) {
+    /**
+     * Standard EntityLoader load (the methods from EnforcingEntityLoader or AuthorizationResultBasedEntityLoader).
+     */
     EntityMetricsLoadType[EntityMetricsLoadType["LOAD_MANY"] = 0] = "LOAD_MANY";
+    /**
+     * Knex loader load using loadManyByFieldEqualityConjunctionAsync.
+     */
     EntityMetricsLoadType[EntityMetricsLoadType["LOAD_MANY_EQUALITY_CONJUNCTION"] = 1] = "LOAD_MANY_EQUALITY_CONJUNCTION";
-    EntityMetricsLoadType[EntityMetricsLoadType["LOAD_MANY_RAW"] = 2] = "LOAD_MANY_RAW";
-    EntityMetricsLoadType[EntityMetricsLoadType["LOAD_MANY_SQL"] = 3] = "LOAD_MANY_SQL";
-    EntityMetricsLoadType[EntityMetricsLoadType["LOAD_ONE"] = 4] = "LOAD_ONE";
-    EntityMetricsLoadType[EntityMetricsLoadType["LOAD_PAGE"] = 5] = "LOAD_PAGE";
+    /**
+     * Knex loader load using loadManyBySQL.
+     */
+    EntityMetricsLoadType[EntityMetricsLoadType["LOAD_MANY_SQL"] = 2] = "LOAD_MANY_SQL";
+    /**
+     * Internal data manager load via database adapter method loadOneEqualingAsync.
+     */
+    EntityMetricsLoadType[EntityMetricsLoadType["LOAD_ONE"] = 3] = "LOAD_ONE";
+    /**
+     * Knex loader load using loadPageAsync.
+     */
+    EntityMetricsLoadType[EntityMetricsLoadType["LOAD_PAGE"] = 4] = "LOAD_PAGE";
 })(EntityMetricsLoadType || (EntityMetricsLoadType = {}));
+/**
+ * The type of mutation being performed.
+ */
 export var EntityMetricsMutationType;
 (function (EntityMetricsMutationType) {
     EntityMetricsMutationType[EntityMetricsMutationType["CREATE"] = 0] = "CREATE";
     EntityMetricsMutationType[EntityMetricsMutationType["UPDATE"] = 1] = "UPDATE";
     EntityMetricsMutationType[EntityMetricsMutationType["DELETE"] = 2] = "DELETE";
 })(EntityMetricsMutationType || (EntityMetricsMutationType = {}));
+/**
+ * Type used to delineate dataloader, cache, and database load counts in EntityDataManager.
+ */
 export var IncrementLoadCountEventType;
 (function (IncrementLoadCountEventType) {
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expo/entity",
-  "version": "0.62.0",
+  "version": "0.63.0",
   "description": "A privacy-first data model",
   "files": [
     "build",
@@ -42,5 +42,5 @@
     "typescript": "5.9.3",
     "uuid": "13.0.0"
   },
-  "gitHead": "4965cc238882982e6315beca48a68679ed45456b"
+  "gitHead": "dbd1cc847952754acc0eb407165cbb7b8350d2df"
 }

package/src/EntityDatabaseAdapter.ts

@@ -202,21 +202,20 @@ export abstract class EntityDatabaseAdapter<
    * @param idField - the field in the object that is the ID
    * @param id - the value of the ID field in the object
    * @param object - the object to update
-   * @returns the updated object
    */
   async updateAsync<K extends keyof TFields>(
     queryContext: EntityQueryContext,
     idField: K,
     id: any,
     object: Readonly<Partial<TFields>>,
-  ): Promise<Readonly<TFields>> {
+  ): Promise<void> {
     const idColumn = getDatabaseFieldForEntityField(this.entityConfiguration, idField);
     const dbObject = transformFieldsToDatabaseObject(
       this.entityConfiguration,
       this.fieldTransformerMap,
       object,
     );
-    const results = await this.updateInternalAsync(
+    const { updatedRowCount } = await this.updateInternalAsync(
       queryContext.getQueryInterface(),
       this.entityConfiguration.tableName,
       idColumn,
@@ -224,24 +223,18 @@ export abstract class EntityDatabaseAdapter<
       dbObject,
     );
 
-    if (results.length > 1) {
+    if (updatedRowCount > 1) {
       // This should never happen with a properly implemented database adapter unless the underlying table has a non-unique
       // primary key column.
       throw new EntityDatabaseAdapterExcessiveUpdateResultError(
         `Excessive results from database adapter update: ${this.entityConfiguration.tableName}(id = ${id})`,
       );
-    } else if (results.length === 0) {
+    } else if (updatedRowCount === 0) {
       // This happens when the object to update does not exist. It may have been deleted by another process.
       throw new EntityDatabaseAdapterEmptyUpdateResultError(
         `Empty results from database adapter update: ${this.entityConfiguration.tableName}(id = ${id})`,
       );
     }
-
-    return transformDatabaseObjectToFields(
-      this.entityConfiguration,
-      this.fieldTransformerMap,
-      results[0]!,
-    );
   }
 
   protected abstract updateInternalAsync(
@@ -250,7 +243,7 @@ export abstract class EntityDatabaseAdapter<
     tableIdField: string,
     id: any,
     object: object,
-  ): Promise<object[]>;
+  ): Promise<{ updatedRowCount: number }>;
 
   /**
    * Delete an object by ID.

package/src/EntityMutationInfo.ts

@@ -1,9 +1,21 @@
 import type { Entity } from './Entity.ts';
 import type { ViewerContext } from './ViewerContext.ts';
 
+/**
+ * The type of mutation that is occurring to an entity.
+ */
 export enum EntityMutationType {
+  /**
+   * Create mutation.
+   */
   CREATE,
+  /**
+   * Update mutation.
+   */
   UPDATE,
+  /**
+   * Delete mutation.
+   */
   DELETE,
 }
 
@@ -30,15 +42,34 @@ type EntityTriggerOrValidatorMutationInfo<
   TSelectedFields extends keyof TFields = keyof TFields,
 > =
   | {
+      /**
+       * The type of mutation that invoked this trigger or validator.
+       */
       type: EntityMutationType.CREATE;
     }
   | {
+      /**
+       * The type of mutation that invoked this trigger or validator.
+       */
       type: EntityMutationType.UPDATE;
+      /**
+       * The previous value of the entity before the update.
+       */
       previousValue: TEntity;
+      /**
+       * If this update is part of a cascading deletion (cascade set null), this field will contain information about the cascade
+       * that caused this update. Otherwise, it will be null.
+       */
       cascadingDeleteCause: EntityCascadingDeletionInfo | null;
     }
   | {
+      /**
+       * The type of mutation that invoked this trigger or validator.
+       */
       type: EntityMutationType.DELETE;
+      /**
+       * If this delete is part of a cascading deletion, this field will contain information about the cascade that caused this cascading delete.
+       */
       cascadingDeleteCause: EntityCascadingDeletionInfo | null;
     };
 

package/src/EntityQueryContext.ts

@@ -8,23 +8,68 @@ export type PreCommitCallback = (
   ...args: any
 ) => Promise<any>;
 
+/**
+ * Database transaction isolation level. Controls the visibility of changes made by
+ * concurrent transactions, trading off between consistency and performance.
+ */
 export enum TransactionIsolationLevel {
+  /**
+   * Each statement sees only data committed before it began. Default for most databases.
+   */
   READ_COMMITTED = 'READ_COMMITTED',
+
+  /**
+   * All statements in the transaction see the same snapshot taken at the start of the transaction.
+   */
   REPEATABLE_READ = 'REPEATABLE_READ',
+
+  /**
+   * Transactions execute as if they were run one at a time. Strongest guarantee but lowest throughput.
+   */
   SERIALIZABLE = 'SERIALIZABLE',
 }
 
+/**
+ * Controls DataLoader behavior within a transaction.
+ */
 export enum TransactionalDataLoaderMode {
+  /**
+   * Default mode where DataLoader is fully enabled, providing both batching and caching benefits within the transaction.
+   */
   ENABLED = 'ENABLED',
+
+  /**
+   * DataLoader is enabled for batching queries together but does not cache results. Use this mode when you want to benefit from batching but need to ensure that each load reflects the most current database state, even within the same transaction.
+   */
   ENABLED_BATCH_ONLY = 'ENABLED_BATCH_ONLY',
+
+  /**
+   * DataLoader is completely disabled for the transaction. Each load will directly query the database without any batching or caching. Use this mode when you need to ensure that every load reflects the most current database state and are not concerned about the performance benefits of batching or caching within the transaction.
+   */
   DISABLED = 'DISABLED',
 }
 
+/**
+ * Configuration options for running a transaction. This includes the isolation level and DataLoader mode for the transaction.
+ */
 export type TransactionConfig = {
+  /**
+   * Transaction isolation level. When omitted, the database default is used (typically READ_COMMITTED).
+   */
   isolationLevel?: TransactionIsolationLevel;
+  /**
+   * DataLoader mode for the transaction. When omitted, defaults to ENABLED.
+   */
   transactionalDataLoaderMode?: TransactionalDataLoaderMode;
 };
 
+/**
+ * Resolved transaction configuration with all default values filled in.
+ * This is the configuration that is actually used for a transaction after applying defaults.
+ */
+export type ResolvedTransactionConfig = Pick<TransactionConfig, 'isolationLevel'> &
+  Required<Pick<TransactionConfig, 'transactionalDataLoaderMode'>>;
+
 /**
  * Entity framework representation of transactional and non-transactional database
  * query execution units.
@@ -99,11 +144,27 @@ export class EntityTransactionalQueryContext extends EntityQueryContext {
      * @internal
      */
     readonly transactionId: string,
-    public readonly transactionalDataLoaderMode: TransactionalDataLoaderMode,
+    public readonly transactionConfig: ResolvedTransactionConfig,
   ) {
     super(queryInterface);
   }
 
+  /**
+   * DataLoader mode for this transaction set at time of transaction creation, controlling DataLoader caching and batching behavior within the transaction.
+   */
+  get transactionalDataLoaderMode(): TransactionalDataLoaderMode {
+    return this.transactionConfig.transactionalDataLoaderMode;
+  }
+
+  /**
+   * Transaction isolation level for this transaction set at time of transaction creation.
+   * This controls the visibility of changes made by concurrent transactions.
+   * When undefined, the database default isolation level is used (typically READ_COMMITTED).
+   */
+  get isolationLevel(): TransactionIsolationLevel | undefined {
+    return this.transactionConfig.isolationLevel;
+  }
+
   /**
    * Schedule a pre-commit callback. These will be run within the transaction right before it is
    * committed, and will be run in the order specified. Ordering of callbacks scheduled with the
@@ -214,9 +275,9 @@ export class EntityNestedTransactionalQueryContext extends EntityTransactionalQu
     readonly parentQueryContext: EntityTransactionalQueryContext,
     entityQueryContextProvider: EntityQueryContextProvider,
     transactionId: string,
-    transactionalDataLoaderMode: TransactionalDataLoaderMode,
+    transactionConfig: ResolvedTransactionConfig,
   ) {
-    super(queryInterface, entityQueryContextProvider, transactionId, transactionalDataLoaderMode);
+    super(queryInterface, entityQueryContextProvider, transactionId, transactionConfig);
     parentQueryContext.childQueryContexts.push(this);
   }
 

package/src/EntityQueryContextProvider.ts

@@ -1,6 +1,6 @@
 import { randomUUID } from 'node:crypto';
 
-import type { TransactionConfig } from './EntityQueryContext.ts';
+import type { ResolvedTransactionConfig, TransactionConfig } from './EntityQueryContext.ts';
 import {
   EntityNestedTransactionalQueryContext,
   EntityNonTransactionalQueryContext,
@@ -53,11 +53,17 @@ export abstract class EntityQueryContextProvider {
     const [returnedValue, queryContext] = await this.createTransactionRunner<
       [T, EntityTransactionalQueryContext]
     >(transactionConfig)(async (queryInterface) => {
+      const resolvedTransactionConfig: ResolvedTransactionConfig = {
+        ...transactionConfig,
+        transactionalDataLoaderMode:
+          transactionConfig?.transactionalDataLoaderMode ??
+          this.defaultTransactionalDataLoaderMode(),
+      };
       const queryContext = new EntityTransactionalQueryContext(
         queryInterface,
         this,
         randomUUID(),
-        transactionConfig?.transactionalDataLoaderMode ?? this.defaultTransactionalDataLoaderMode(),
+        resolvedTransactionConfig,
       );
       const result = await transactionScope(queryContext);
       await queryContext.runPreCommitCallbacksAsync();
@@ -85,7 +91,7 @@ export abstract class EntityQueryContextProvider {
         outerQueryContext,
         this,
         randomUUID(),
-        outerQueryContext.transactionalDataLoaderMode,
+        outerQueryContext.transactionConfig,
       );
       const result = await transactionScope(innerQueryContext);
       await innerQueryContext.runPreCommitCallbacksAsync();

package/src/EntitySecondaryCacheLoader.ts

@@ -42,8 +42,7 @@ export interface ISecondaryEntityCache<TFields extends Record<string, any>, TLoa
  * when the underlying data of a cache key could be stale.
  *
  * This is most commonly used to further optimize hot paths that cannot make use of normal entity cache loading
- * due to use of a non-unique-field-based EntityLoader method like `loadManyByFieldEqualityConjunctionAsync` or
- * `loadManyByRawWhereClauseAsync`.
+ * due to use of a non-unique-field-based EntityLoader method like `loadManyByFieldEqualityConjunctionAsync`.
  */
 export abstract class EntitySecondaryCacheLoader<
   TLoadParams,

package/src/__tests__/EntityDatabaseAdapter-test.ts

@@ -23,20 +23,20 @@ class TestEntityDatabaseAdapter extends EntityDatabaseAdapter<TestFields, 'custo
   private readonly fetchResults: object[];
   private readonly fetchOneResult: object | null;
   private readonly insertResults: object[];
-  private readonly updateResults: object[];
+  private readonly updateResults: { updatedRowCount: number };
   private readonly deleteCount: number;
 
   constructor({
     fetchResults = [],
     fetchOneResult = null,
     insertResults = [],
-    updateResults = [],
+    updateResults = { updatedRowCount: 0 },
     deleteCount = 0,
   }: {
     fetchResults?: object[];
     fetchOneResult?: object | null;
     insertResults?: object[];
-    updateResults?: object[];
+    updateResults?: { updatedRowCount: number };
     deleteCount?: number;
   }) {
     super(testEntityConfiguration);
@@ -83,7 +83,7 @@ class TestEntityDatabaseAdapter extends EntityDatabaseAdapter<TestFields, 'custo
     _tableIdField: string,
     _id: any,
     _object: object,
-  ): Promise<object[]> {
+  ): Promise<{ updatedRowCount: number }> {
     return this.updateResults;
   }
 
@@ -256,16 +256,15 @@ describe(EntityDatabaseAdapter, () => {
   });
 
   describe('updateAsync', () => {
-    it('transforms object', async () => {
+    it('succeeds when one row updated', async () => {
       const queryContext = instance(mock(EntityQueryContext));
-      const adapter = new TestEntityDatabaseAdapter({ updateResults: [{ string_field: 'hello' }] });
-      const result = await adapter.updateAsync(queryContext, 'customIdField', 'wat', {});
-      expect(result).toEqual({ stringField: 'hello' });
+      const adapter = new TestEntityDatabaseAdapter({ updateResults: { updatedRowCount: 1 } });
+      await adapter.updateAsync(queryContext, 'customIdField', 'wat', {});
     });
 
     it('throws when update result count zero', async () => {
       const queryContext = instance(mock(EntityQueryContext));
-      const adapter = new TestEntityDatabaseAdapter({ updateResults: [] });
+      const adapter = new TestEntityDatabaseAdapter({ updateResults: { updatedRowCount: 0 } });
       await expect(adapter.updateAsync(queryContext, 'customIdField', 'wat', {})).rejects.toThrow(
         EntityDatabaseAdapterEmptyUpdateResultError,
       );
@@ -274,7 +273,7 @@ describe(EntityDatabaseAdapter, () => {
     it('throws when update result count greater than 1', async () => {
       const queryContext = instance(mock(EntityQueryContext));
       const adapter = new TestEntityDatabaseAdapter({
-        updateResults: [{ string_field: 'hello' }, { string_field: 'hello2' }],
+        updateResults: { updatedRowCount: 2 },
       });
       await expect(adapter.updateAsync(queryContext, 'customIdField', 'wat', {})).rejects.toThrow(
         EntityDatabaseAdapterExcessiveUpdateResultError,

package/src/__tests__/EntityQueryContext-test.ts

@@ -203,6 +203,90 @@ describe(EntityQueryContext, () => {
         },
       );
     });
+
+    it('exposes isolationLevel on the query context', async () => {
+      const companionProvider = createUnitTestEntityCompanionProvider();
+      const viewerContext = new ViewerContext(companionProvider);
+
+      await viewerContext.runInTransactionForDatabaseAdapterFlavorAsync(
+        'postgres',
+        async (queryContext) => {
+          assert(queryContext.isInTransaction());
+          expect(queryContext.isolationLevel).toBe(TransactionIsolationLevel.SERIALIZABLE);
+        },
+        { isolationLevel: TransactionIsolationLevel.SERIALIZABLE },
+      );
+
+      await viewerContext.runInTransactionForDatabaseAdapterFlavorAsync(
+        'postgres',
+        async (queryContext) => {
+          assert(queryContext.isInTransaction());
+          expect(queryContext.isolationLevel).toBe(TransactionIsolationLevel.REPEATABLE_READ);
+        },
+        { isolationLevel: TransactionIsolationLevel.REPEATABLE_READ },
+      );
+
+      await viewerContext.runInTransactionForDatabaseAdapterFlavorAsync(
+        'postgres',
+        async (queryContext) => {
+          assert(queryContext.isInTransaction());
+          expect(queryContext.isolationLevel).toBeUndefined();
+        },
+      );
+    });
+
+    it('exposes the full resolved transactionConfig on the query context', async () => {
+      const companionProvider = createUnitTestEntityCompanionProvider();
+      const viewerContext = new ViewerContext(companionProvider);
+
+      await viewerContext.runInTransactionForDatabaseAdapterFlavorAsync(
+        'postgres',
+        async (queryContext) => {
+          assert(queryContext.isInTransaction());
+          expect(queryContext.transactionConfig).toEqual({
+            isolationLevel: TransactionIsolationLevel.SERIALIZABLE,
+            transactionalDataLoaderMode: TransactionalDataLoaderMode.DISABLED,
+          });
+        },
+        {
+          isolationLevel: TransactionIsolationLevel.SERIALIZABLE,
+          transactionalDataLoaderMode: TransactionalDataLoaderMode.DISABLED,
+        },
+      );
+
+      await viewerContext.runInTransactionForDatabaseAdapterFlavorAsync(
+        'postgres',
+        async (queryContext) => {
+          assert(queryContext.isInTransaction());
+          expect(queryContext.transactionConfig).toEqual({
+            transactionalDataLoaderMode: TransactionalDataLoaderMode.ENABLED,
+          });
+        },
+      );
+    });
+
+    it('propagates transactionConfig to nested transactions', async () => {
+      const companionProvider = createUnitTestEntityCompanionProvider();
+      const viewerContext = new ViewerContext(companionProvider);
+
+      await viewerContext.runInTransactionForDatabaseAdapterFlavorAsync(
+        'postgres',
+        async (queryContext) => {
+          assert(queryContext.isInTransaction());
+          await queryContext.runInNestedTransactionAsync(async (innerQueryContext) => {
+            expect(innerQueryContext.transactionConfig).toEqual(queryContext.transactionConfig);
+            expect(innerQueryContext.isolationLevel).toBe(TransactionIsolationLevel.SERIALIZABLE);
+            expect(innerQueryContext.transactionalDataLoaderMode).toBe(
+              TransactionalDataLoaderMode.DISABLED,
+            );
+          });
+        },
+        {
+          isolationLevel: TransactionIsolationLevel.SERIALIZABLE,
+          transactionalDataLoaderMode: TransactionalDataLoaderMode.DISABLED,
+        },
+      );
+    });
   });
 
   describe('global defaultTransactionalDataLoaderMode', () => {

package/src/errors/EntityInvalidFieldValueError.ts

@@ -34,6 +34,9 @@ export class EntityInvalidFieldValueError<
     return EntityErrorCode.ERR_ENTITY_INVALID_FIELD_VALUE;
   }
 
+  readonly fieldName: N;
+  readonly fieldValue: TFields[N] | undefined;
+
   constructor(
     entityClass: IEntityClass<
       TFields,
@@ -47,5 +50,7 @@ export class EntityInvalidFieldValueError<
     fieldValue?: TFields[N],
   ) {
     super(`Entity field not valid: ${entityClass.name} (${String(fieldName)} = ${fieldValue})`);
+    this.fieldName = fieldName;
+    this.fieldValue = fieldValue;
   }
 }

package/src/errors/__tests__/EntityError-test.ts

@@ -34,6 +34,8 @@ describe('EntityError subclasses', () => {
     const error = new EntityInvalidFieldValueError(SimpleTestEntity, 'id', 'badValue');
     expect(error.state).toBe(EntityErrorState.PERMANENT);
     expect(error.code).toBe(EntityErrorCode.ERR_ENTITY_INVALID_FIELD_VALUE);
+    expect(error.fieldName).toBe('id');
+    expect(error.fieldValue).toBe('badValue');
   });
 
   it('EntityCacheAdapterTransientError has correct state and code', () => {

package/src/metrics/IEntityMetricsAdapter.ts

@@ -4,12 +4,29 @@ import type {
 } from '../EntityPrivacyPolicy.ts';
 import type { EntityLoadMethodType } from '../internal/EntityLoadInterfaces.ts';
 
+/**
+ * The type of the load method being called.
+ */
 export enum EntityMetricsLoadType {
+  /**
+   * Standard EntityLoader load (the methods from EnforcingEntityLoader or AuthorizationResultBasedEntityLoader).
+   */
   LOAD_MANY,
+  /**
+   * Knex loader load using loadManyByFieldEqualityConjunctionAsync.
+   */
   LOAD_MANY_EQUALITY_CONJUNCTION,
-  LOAD_MANY_RAW,
+  /**
+   * Knex loader load using loadManyBySQL.
+   */
   LOAD_MANY_SQL,
+  /**
+   * Internal data manager load via database adapter method loadOneEqualingAsync.
+   */
   LOAD_ONE,
+  /**
+   * Knex loader load using loadPageAsync.
+   */
   LOAD_PAGE,
 }
 
@@ -43,6 +60,9 @@ export interface EntityMetricsLoadEvent {
   count: number;
 }
 
+/**
+ * The type of mutation being performed.
+ */
 export enum EntityMetricsMutationType {
   CREATE,
   UPDATE,
@@ -71,6 +91,9 @@ export interface EntityMetricsMutationEvent {
   duration: number;
 }
 
+/**
+ * Type used to delineate dataloader, cache, and database load counts in EntityDataManager.
+ */
 export enum IncrementLoadCountEventType {
   /**
    * Type for when a dataloader load is initiated via the standard load methods

package/src/utils/__testfixtures__/StubDatabaseAdapter.ts

@@ -135,7 +135,7 @@ export class StubDatabaseAdapter<
     tableIdField: string,
     id: any,
     object: object,
-  ): Promise<object[]> {
+  ): Promise<{ updatedRowCount: number }> {
     // SQL does not support empty updates, mirror behavior here for better test simulation
     if (Object.keys(object).length === 0) {
       throw new Error(`Empty update (${tableIdField} = ${id})`);
@@ -150,14 +150,14 @@ export class StubDatabaseAdapter<
     // SQL updates to a nonexistent row succeed but affect 0 rows,
     // mirror that behavior here for better test simulation
     if (objectIndex < 0) {
-      return [];
+      return { updatedRowCount: 0 };
     }
 
     objectCollection[objectIndex] = {
       ...objectCollection[objectIndex],
       ...object,
     };
-    return [objectCollection[objectIndex]];
+    return { updatedRowCount: 1 };
   }
 
   protected async deleteInternalAsync(