entity_graph_flutter library
entity_graph_flutter
Flutter/Dart mirror of the Prometheus entity-graph ecosystem.
Mirrors the three-layer model of entity-graph-core: Layer 1 → EntityGraph (the normalized in-memory store) Layer 2 → Riverpod providers (entityProvider, entityListProvider) Transport → EntityTransport + EntityTransportRegistry
The SDL shared contract is modelled by EntityGraphIR. Use parseSdl to parse a JSON/Map SDL document into the validated IR.
Classes
-
ChangeEvent<
T> - Realtime change event — mirrors ChangeEvent in transport/types.ts.
- EditBuffer
- Local dirty-path edit state. It is UI orchestration state, not graph data.
-
Entity<
T extends Object> - Generated Riverpod family for a single normalized entity.
- EntityChangeBinding
- Result of mounting an entity type's optional realtime feed.
-
EntityChangeBridge<
T extends Object> - Mounts at most one generated-provider instance per entity type and translates transport changes into canonical graph writes/invalidation.
- EntityChangeBridgeFamily
- Mounts at most one generated-provider instance per entity type and translates transport changes into canonical graph writes/invalidation.
-
EntityChangeBridgeProvider<
T extends Object> - Mounts at most one generated-provider instance per entity type and translates transport changes into canonical graph writes/invalidation.
- EntityChanged
- An entity was upserted, replaced, or patched.
-
EntityConfig<
T extends Object> - Compatibility configuration for provider factories.
-
EntityCrud<
T extends Object> - Generated per-entity CRUD controller with isolated edits and optimistic graph feedback.
- EntityCrudFamily
- Generated per-entity CRUD controller with isolated edits and optimistic graph feedback.
-
EntityCrudProvider<
T extends Object> - Generated per-entity CRUD controller with isolated edits and optimistic graph feedback.
- EntityFamily
- Generated Riverpod family for a single normalized entity.
- EntityGraph
- Normalized entity graph — the single source of truth.
- EntityGraphIR
- Fully validated IR — consumed by code generators and transport builders.
- EntityGraphProvider
- Process-wide graph owner. Override with an isolated EntityGraph in tests or a deliberately scoped application graph.
- EntityGraphSnapshot
- Immutable graph data captured at one publication boundary.
-
EntityList<
T extends Object> - Generated Riverpod family for normalized local, remote, and hybrid lists.
-
EntityListConfig<
T extends Object> - Compatibility configuration for applications that construct providers in factories. New code normally passes these fields directly to entityListProvider.
- EntityListFamily
- Generated Riverpod family for normalized local, remote, and hybrid lists.
-
EntityListProvider<
T extends Object> - Generated Riverpod family for normalized local, remote, and hybrid lists.
-
EntityListSnapshot<
T extends Object> - Stable list data derived from ID-only graph membership.
-
EntityMutations<
T extends Object> - Collection-level controller for optimistic creates.
- EntityMutationsFamily
- Collection-level controller for optimistic creates.
-
EntityMutationsProvider<
T extends Object> - Collection-level controller for optimistic creates.
-
EntityMutationState<
T extends Object> - State for collection-level create operations.
-
EntityProvider<
T extends Object> - Generated Riverpod family for a single normalized entity.
- EntityRemovalSnapshot
- Complete rollback receipt for an optimistic entity removal.
- EntityRemoved
- An entity was removed.
-
EntitySnapshot<
T extends Object> - Stable single-entity data derived from the graph.
- EntityState
- Fetch / cache metadata for a single entity instance.
- EntitySyncMetadata
- Optional sync metadata kept beside the canonical entity payload.
-
EntityTransport<
T extends Object> -
Per-entity transport contract — mirrors
EntityTransport<T>in transport/types.ts. - EntityTransportRegistry
- Process-global registry of EntityTransport instances keyed by entity type.
- EntityTransportRegistryProvider
- Process-wide transport registry. It is injectable without changing the graph's state ownership.
-
FfiEntityBridge<
T extends Object> - Host-owned bridge implemented by optional native integration packages.
-
FfiEntityTransportAdapter<
T extends Object> - Adapts an optional native bridge to the transport-neutral package contract.
- FilterClause
- Atomic filter clause.
- GraphChange
- Coarse-grained graph change event.
- GraphEntityIdentity
- GraphPublication
- One completed outer graph write with deduplicated affected identities.
- GraphReset
- The complete graph was cleared or replaced.
- GraphViewDefinition
- GraphViewLifecycleEvent
- GraphViewRecord
- GraphViewRegistration
- IrEntity
- Validated IR entity.
- IrField
- Validated IR field — what generators consume.
- IrRelation
- Validated IR relation.
- ListChanged
- A list slot was updated.
- ListQuery
- Transport-agnostic list query — mirrors ListQuery in transport/types.ts.
-
ListResult<
T> - Page of results returned by EntityTransport.list.
- ListState
- Ordered entity-id array + pagination metadata. Lists store ids, never embedded entity payloads — cross-view reactivity depends on this invariant.
- SdlAiConfig
- SdlConfig
- SDL config block.
- SdlFieldDef
- Raw SDL field definition.
- SdlLocalFirstConfig
- SdlRelationDef
- Raw SDL relation definition.
- SortClause
- Single sort key.
Enums
- ChangeOp
- Change operation for realtime events.
- FilterOperator
- Filter operator — mirrors FilterOperator in view/types.ts.
- GraphViewKind
- GraphViewLifecycleState
- SdlRelationKind
- Relation kind.
- SdlScalarType
- Supported SDL scalar types.
- SortDirection
- Sort direction.
- SyncOrigin
- Provenance of the latest known entity state.
- ViewCompleteness
- Declares whether a view is complete locally, remotely, or through both.
Properties
- entityChangeBridgeProvider → EntityChangeBridgeFamily
-
Mounts at most one generated-provider instance per entity type and
translates transport changes into canonical graph writes/invalidation.
final
- entityCrudProvider → EntityCrudFamily
-
Generated per-entity CRUD controller with isolated edits and optimistic
graph feedback.
final
- entityGraphProvider → EntityGraphProvider
-
Process-wide graph owner. Override with an isolated EntityGraph in tests
or a deliberately scoped application graph.
final
- entityListProvider → EntityListFamily
-
Generated Riverpod family for normalized local, remote, and hybrid lists.
final
- entityMutationsProvider → EntityMutationsFamily
-
Collection-level controller for optimistic creates.
final
- entityProvider → EntityFamily
-
Generated Riverpod family for a single normalized entity.
final
- entityTransportRegistryProvider → EntityTransportRegistryProvider
-
Process-wide transport registry. It is injectable without changing the
graph's state ownership.
final
Functions
-
entityGraph(
Ref ref) → EntityGraph - Process-wide graph owner. Override with an isolated EntityGraph in tests or a deliberately scoped application graph.
-
entityProviderRetry(
int retryCount, Object error) → Duration? - Bounded Riverpod 3 retry policy shared by fetch providers.
-
entityToGraphRow<
T extends Object> (T row, EntityEncoder< T> ? encoder) → Map<String, Object?> - Encode a transport row without requiring Freezed or JSON code generation.
-
entityTransportRegistry(
Ref ref) → EntityTransportRegistry - Process-wide transport registry. It is injectable without changing the graph's state ownership.
-
evaluateLocalEntityIds(
EntityGraph graph, String type, ListQuery query) → List< String> -
Evaluate
queryagainst canonical entities and return ordered IDs only. -
parseSdl(
Object? doc) → EntityGraphIR - Parse + validate a Map SDL document (already decoded from JSON/TOML) into a validated EntityGraphIR.
-
parseSdlJson(
String json) → EntityGraphIR - Parse an SDL document from a JSON string.
-
toEntityGraphError(
Object error) → EntityGraphError - Convert an arbitrary exception to a typed EntityGraphError.
Typedefs
-
EntityDecoder<
T extends Object> = T Function(Map< String, Object?> row) - Converts a canonical graph row into a feature model.
-
EntityEncoder<
T extends Object> = Map< String, Object?> Function(T row) - Converts a transport model into canonical graph fields.
-
EntityListNotifier<
T extends Object> = EntityList< T> - Backwards-compatible notifier type name; the generated family is entityListProvider.
-
EntityNotifier<
T extends Object> = Entity< T> - Backwards-compatible notifier type name; the generated family is entityProvider.
- GraphPublicationListener = void Function(GraphPublication publication)
- Receives one completed graph publication synchronously after its write.
- GraphViewLifecycleListener = void Function(GraphViewLifecycleEvent event)
Exceptions / Errors
- EntityGraphError
- Base class for all entity-graph errors.
- SdlValidationError
- Thrown when an SDL document fails validation.
- TerminalError
- Permanent failure — do not retry.
- TransientError
- Temporary failure — safe to retry with back-off.