Member Junction
    Preparing search index...

    Interface IEntityDataProvider

    Interface for entity data providers. Defines core CRUD operations and record change tracking. Implementations handle database-specific operations for entity persistence.

    interface IEntityDataProvider {
        SupportsEntityTransactions?: boolean;
        BeginEntityTransaction?(): Promise<EntityTransactionScope>;
        Config(configData: ProviderConfigDataBase): Promise<boolean>;
        Delete(
            entity: BaseEntity,
            options: EntityDeleteOptions,
            user: UserInfo,
        ): Promise<boolean>;
        FindISAChildEntities?(
            entityInfo: EntityInfo,
            recordPKValue: string,
            contextUser?: UserInfo,
        ): Promise<{ ChildEntityName: string }[]>;
        FindISAChildEntitiesBatch?(
            entityInfo: EntityInfo,
            recordPKValues: string[],
            contextUser?: UserInfo,
        ): Promise<Map<string, string[]>>;
        FindISAChildEntity?(
            entityInfo: EntityInfo,
            recordPKValue: string,
            contextUser?: UserInfo,
        ): Promise<{ ChildEntityName: string }>;
        GetRecordChanges(
            entityName: string,
            CompositeKey: CompositeKey,
        ): Promise<RecordChange[]>;
        Load(
            entity: BaseEntity,
            CompositeKey: CompositeKey,
            EntityRelationshipsToLoad: string[],
            user: UserInfo,
        ): Promise<{}>;
        RunOutsideAmbientTransaction?<T>(fn: () => Promise<T>): Promise<T>;
        Save(
            entity: BaseEntity,
            user: UserInfo,
            options: EntitySaveOptions,
        ): Promise<{}>;
    }

    Implemented by

    Index

    Properties

    SupportsEntityTransactions?: boolean

    Whether this provider can execute a multi-record unit of work atomically, in-process.

    true for server-side database providers (DatabaseProviderBase and subclasses); false for client-side providers such as GraphQLDataProvider, which have no local transaction to begin. BaseEntity reads this to decide whether to run a multi-node save graph locally or route the whole unit of work to the server — see guides/TRANSACTIONS_AND_BATCHING_GUIDE.md.

    Optional on the interface so that external IMetadataProvider implementations are not broken by its introduction; ProviderBase supplies a concrete false default, so every provider in this repository answers it.

    Methods

    • Begins a provider-arbitrated transaction scope, or joins one already in flight.

      This is the single transaction primitive for all multi-record entity work — IS-A parent chains, composite graph saves and hand-written application cascades alike. Participants never ask whether someone else already opened a transaction; the provider arbitrates. See EntityTransactionScope for the full rationale, including the torn-write bug that the previous IS-A-specific trio caused.

      Only implemented where SupportsEntityTransactions is true.

      Returns Promise<EntityTransactionScope>

      A settle-once scope. Always pair with Commit() / Rollback(), or use RunInEntityTransaction() which does that for you.

    • Discovers ALL IS-A child entities that have records with the given primary key. Used for overlapping subtype parents (AllowMultipleSubtypes = true) where multiple children can coexist. Same UNION ALL query as FindISAChildEntity, but returns all matches.

      Parameters

      • entityInfo: EntityInfo

        The parent entity's EntityInfo (to find its child entity types)

      • recordPKValue: string

        The primary key value to search for in child tables

      • OptionalcontextUser: UserInfo

        Optional context user for server-side operations

      Returns Promise<{ ChildEntityName: string }[]>

      Array of child entity names found (empty if none)

    • Batch-discovers IS-A child entity types for multiple parent primary keys in a single UNION ALL SQL query (chunked automatically for large batches).

      Parameters

      • entityInfo: EntityInfo

        The parent entity's EntityInfo (whose ChildEntities are probed)

      • recordPKValues: string[]

        Primary key values to probe across child views

      • OptionalcontextUser: UserInfo

        Optional context user for server-side operations

      Returns Promise<Map<string, string[]>>

      Map keyed by canonical lowercased primary-key string to ordered matching child entity names

    • Discovers which IS-A child entity, if any, has a record with the given primary key. Used by BaseEntity.InitializeChildEntity() after loading a record to find the most-derived child type. Implementations should execute a single UNION ALL query across all child entity tables for efficiency.

      Parameters

      • entityInfo: EntityInfo

        The parent entity's EntityInfo (to find its child entity types)

      • recordPKValue: string

        The primary key value to search for in child tables

      • OptionalcontextUser: UserInfo

        Optional context user for server-side operations

      Returns Promise<{ ChildEntityName: string }>

      The child entity name if found, or null if no child record exists

    • Runs fn as if the caller were in no transaction on this provider, even when its async scope belongs to an open one: statements fn issues run on the pool and commit on their own.

      For fire-and-forget writes (see BaseEntitySaveQueue's detachFromTransaction): the caller never awaits them, so it cannot order them before its transaction's COMMIT. Bound to the transaction, such a write either reaches SQL behind the COMMIT and is rejected, or is rolled back with work it merely observed.

      Limit: if fn itself begins a transaction (an IS-A save, a save with companions, a save that enlists a Durable After* binding) while the caller's transaction is still open on this instance, that begin joins the open transaction as a foreign savepoint (logged once per transaction) rather than opening its own. Detaching only keeps fn's plain statements off the transaction.

      Implemented by GenericDatabaseProvider, which tracks which async scope owns its transaction. Absent on providers with no in-process transaction (e.g. GraphQLDataProvider): nothing to leave.

      Type Parameters

      • T

      Parameters

      • fn: () => Promise<T>

      Returns Promise<T>