fasq_hooks library

Classes

AuthScope: Exact non-secret identity under which required work was queued.
AuthScopeGate: Auth scope gate enforcing exact identity matching.
AuthSessionProvider: Injected auth boundary. Tokens and credential clients stay outside Fasq.
AuthSessionSnapshot: Non-secret current authentication state.
AutoRegisterSerializers: Annotation to mark a class for automatic serializer registration.
BackgroundReplayAdapter: Platform boundary for best-effort background wake-up requests.
BackgroundReplayRequest: Safe metadata supplied to a background scheduling adapter.
BlockedSyncDagNode<TPayload>: A node that could not be ordered, with reason details.
CacheConfig: Configuration for the query cache.
CacheDataCodecRegistry: Registry of serializers used by cache persistence.
CacheDataCodecResult: Serialized value plus type information.
CacheDataSerializer<T>: Serializer definition for a single cache data type.
CacheEntry<T>: Represents a cached data entry with metadata for staleness and eviction.
CacheInfo: Snapshot of cache state for inspection.
CacheMetrics: Metrics for monitoring cache performance.
CancellationToken: A token that signals when a query operation should be cancelled.
CircuitBreaker: A circuit breaker that prevents repeated execution of operations likely to fail.
CircuitBreakerOptions: Configuration options for a circuit breaker.
CircuitBreakerRegistry: Registry for managing multiple circuit breaker instances with per-endpoint isolation.
CircuitOpenEvent: Event data structure for circuit open events.
CircuitStats: Statistics tracked by a circuit breaker for state transition decisions.
ConflictClassification: Safe normalized conflict classification returned by an adapter.
ConflictDiscardAction: Fresh audit identity for an explicit discard action.
ConflictDiscarded
ConflictEvidence: Immutable, restart-safe evidence for one conflict.
ConflictPrecondition: Opaque revision, version, or ETag-like compare-and-set token.
ConflictRepair: Creates only explicit repairs; never retries unchanged or merges generically.
ConflictRepairOperation: Fresh queued work produced by explicit replacement/domain resolution.
ConflictRepairPlan
ConflictRepairResult
ConflictReplaced
ConflictResolutionContext: Inputs supplied to an explicit domain resolver.
ConflictUnresolved
ConsoleExporter: Exports performance snapshots to the developer console.
CursorPagination<TData, TCursor>: Cursor-based pagination configuration.
DefaultMutationFailureClassifier: Conservative default exception classifier.
Dependent<T>: Represents a dependency value that is only usable when enabled is true.
DirectMutationExecutionAdapter: Default adapter that fails closed for unclassified exceptions.
DiscardConflictPlan
DurableDependencyObservation: Safe dependency metadata for one observed operation.
DurableEnqueueAcknowledgement: Durable acknowledgement returned after the enqueue transaction commits.
DurableFailureObservation: Safe failure metadata retained for public observation.
DurableHistoryObservation: Immutable retained completion/deletion ledger entry.
DurableMutation<TData, TVariables>: One durable mutation handle shared by immediate execution and replay.
DurableMutationCatalog: Runtime catalog of durable mutation contracts registered at bootstrap.
DurableMutationDefinition<TData, TVariables>: Low-level durable mutation registration contract.
DurableMutationDefinitionBase: Runtime registration contract for one durable mutation.
DurableMutationQueue: Public durable queue facade for registered mutation functions.
DurableMutationQueueOptions<TVariables>: Configuration required to persist and replay a mutation after restart.
DurableObservation: Read-only projection of one durable outbox snapshot.
DurableOperationFilter: Immutable filter for operation and dead-letter observation.
DurableOperationObservation: Immutable, redacted view of active or dead-letter operation metadata.
DurableOutboxRecovery: Safe, inspectable state left after a store cannot be opened.
DurableOutboxStore: Versioned durable storage boundary for offline mutation work.
DurableQueueObservation: Immutable queue observation for one filtered durable snapshot.
DurableRepairService: Explicit durable retry, replacement, discard, and quarantine restore.
DurableReplayCoordinator: Coordinates one-owner, dependency-aware replay over a durable outbox.
DurableUnknownRecordObservation: Safe metadata for a persisted record that needs explicit recovery.
EncryptionProvider: Abstract interface for encryption/decryption operations.
FasqErrorContext: Context information captured when a query fails.
FasqLogger: Logs query and mutation lifecycle events for debugging.
FasqMutation: Marks a one-argument function as a durable mutation contract.
FasqMutationDependency<TParentData, TParentVariables, TVariables, TValue>: Maps a producer mutation result into this mutation's input at runtime.
FasqMutationDependencyDeclaration<TParentData, TParentVariables, TVariables, TValue>: Declares a producer mutation result to current mutation input mapping in a durable-mutation annotation.
FasqMutationField<TOwner, TValue>: A typed field used by a durable mutation dependency.
FasqMutationKey<TData, TVariables>: Compile-time typed identity for one durable mutation contract.
FasqMutationSource<TData, TVariables>: A typed reference to another annotated mutation function.
FasqProvider: Exposes one initialized query and durable-mutation runtime to a widget tree.
FasqRuntime: Runtime resources exposed by the core Fasq provider.
FileDurableOutbox: Default crash-safe encrypted file backend for the durable outbox.
GlobalPerformanceConfig: Global performance configuration for the cache system.
HotCache<T>: A fast-access cache for frequently used items with LRU eviction.
HotCacheOverallStats: Overall statistics for the hot cache
HotCacheStats: Statistics for a specific hot cache entry
IdempotencyKey: Stable key reused across automatic retries and restarts.
InfiniteQuery<TData, TParam>: Manages infinite/paginated data fetching with support for forward and backward pagination.
InfiniteQueryOptions<TData, TParam>: Configuration options for infinite queries.
InfiniteQueryState<TData, TParam>: Immutable state for an infinite query.
InMemoryAuthSessionProvider: In-memory provider useful for lifecycle integration and deterministic tests.
IoOutboxFileSystem: Default dart:io filesystem implementation.
IsolatePool: A pool of isolates for executing heavy computation tasks.
IsolatePoolStatus: Status information about an isolate pool
IsolateTask<T, R>: A task wrapper for isolate execution.
JsonExporter: Exports performance snapshots as JSON payloads.
JsonMutationCodec<TVariables>: Codec backed by explicit JSON encode/decode functions.
KahnDagSorter<TPayload>: Kahn-based topological sorter for sync DAGs.
LineageId: Identifier connecting an operation and its explicit repairs.
MemoryPressureHandler: Handles system memory pressure warnings.
MetricsConfig: Configuration for managing multiple metrics exporters and export settings.
MetricsExporter: Contract for exporting performance snapshots to external sinks.
Mutation<T, TVariables>: Executes and tracks a mutation with optional offline queueing.
MutationAdapterFailure: Safe, transport-neutral failure returned by an execution adapter.
MutationBuilder<T, TVariables>: A widget that builds UI from the state of a mutation.
MutationCodec<TVariables>: Encodes and decodes one typed mutation variable model.
MutationCodecRegistry: Registry of typed variable codecs keyed by versioned MutationKey.
MutationDependency: Explicit dependency edge from a child operation to a parent operation.
MutationExecutionAdapter: Boundary for transport, auth, and arbitrary async execution policies.
MutationExecutionContext: Context passed to transport-independent execution adapters.
MutationExecutionFailure: Failed adapter result.
MutationExecutionResult: Result returned by an execution adapter.
MutationExecutionSuccess: Successful adapter result.
MutationFailure: Safe, transport-agnostic failure metadata for durable operation state.
MutationFailureClassifier: Classifies arbitrary adapter exceptions without inspecting transport fields.
MutationIdentityLink: Local identity produced by one durable mutation operation.
MutationKey: Stable, versioned logical identity for a queueable mutation.
MutationMeta: Metadata for mutation side effects and user-facing messages.
MutationOperation: JSON-safe durable contract for a queued mutation operation.
MutationOptions<T, TVariables>: Configuration options for mutation behavior and lifecycle callbacks.
MutationProjectionDescriptor: Explicit cache projection plan reference.
MutationRegistrationRegistry: Runtime-only registration of a typed codec and async executor.
MutationSnapshot<TData, TVariables>: Snapshot of a mutation transition at a specific point in time.
MutationState<T>: Immutable state model for a mutation lifecycle.
MutationSubmission<T>: Outcome returned by Mutation.submit.
NamedQueryConfig<T>: Named configuration for queries
NetworkStatus: In-memory network connectivity state notifier.
OpenTelemetryExporter: Exports performance snapshots in OpenTelemetry (OTLP) JSON format.
OperationId: Stable identifier for one durable operation occurrence.
OutboxCapacityPolicy: Capacity limits for the complete logical outbox.
OutboxDeadLetter: One terminal operation retained for repair and inspection.
OutboxEncryption: Encryption boundary used by durable outbox backends.
OutboxEnvelope: Unencrypted metadata surrounding an encrypted logical store payload.
OutboxFileSystem: Filesystem operations used by the durable backend.
OutboxHistoryEntry: A compact completion ledger entry retained after active work is removed.
OutboxMigration: A validated copy-on-write migration between logical store schemas.
OutboxSecurityPolicy: Validates data before it crosses the durable persistence boundary.
OutboxSnapshot: The single logical state committed by a durable outbox transaction.
OutboxUnknownRecord: Safe durable marker for a record that requires explicit recovery.
Page<TData, TParam>: Snapshot of a single page in an infinite query.
PageNumberPagination<TData>: Page-number based pagination configuration.
PerformanceMonitor: Centralized performance monitoring service.
PerformanceOptions: Performance configuration options for a query.
PerformanceReport: Detailed performance report with comprehensive metrics.
PerformanceSnapshot: Snapshot of performance state at a specific point in time.
PerformanceSummary: Quick performance summary for monitoring dashboards
PersistenceOptions: Configuration options for cache persistence.
PersistenceProvider: Abstract interface for encrypted data persistence operations.
PrefetchConfig<T>: Configuration describing a query to prefetch.
ProjectionCoordinator
ProjectionDefinition
ProjectionFailure
ProjectionOutcome
ProjectionOverlay
ProjectionPlan
ProjectionRegistry
ProjectionState
ProjectionView
Query<T>: A query represents an async operation with managed state and lifecycle.
QueryBuilder<T>: A widget that executes an async operation and builds UI based on its state.
QueryCache: Core cache storage and management for queries.
QueryClient: Global registry for all queries in the application.
QueryClientObserver: Observer hooks for query and mutation lifecycle events.
QueryClientProvider: Provider widget for QueryClient configuration.
QueryConfig<T>: Configuration for a single query in a parallel query setup.
QueryDebugInfo: Debug information for a Query instance (debug mode only).
QueryDependencyManager: Manages parent-child relationships between queries.
QueryKey: Base type for stable query identifiers used by the cache/client registry.
QueryMeta: Describes optional metadata for query lifecycle side effects.
QueryMetrics: Metrics for a specific query's performance.
QueryOptions: Configuration options for a query.
QuerySnapshot<T>: Immutable state transition snapshot emitted by a query update.
QueryState<T>: Represents the current state of a query.
RecoverableDurableOutboxStore: Optional recovery diagnostics exposed by stores that support them.
RegisteredMutationExecution: Typed in-process result plus JSON-safe durable projection.
RepairActionResult: Redacted result returned from an explicit action.
RepairIdentityFactory: Supplies fresh identities for every explicit repair attempt.
RepairTelemetryEvent: Redacted event emitted after an action attempt.
ReplacementConflictPlan
ReplayCancellationToken: Cooperative cancellation token owned by one replay attempt.
ReplayDiagnostic: Safe, durable diagnostic for a blocked replay operation.
ReplayLifecycleController: Debounced, single-flight bridge from lifecycle signals to replay.
ReplayReadiness: Readiness barrier required before lifecycle-triggered replay.
ReplayReadinessBarrier: Mutable readiness barrier with observable state.
ReplayRunResult: Observable result of one replay request.
RetryPlan: Deterministic retry decision for one failed invocation.
RetryPolicy: Exponential full-jitter retry policy with durable age and attempt limits.
SecurityPlugin: Abstract interface for security plugins.
SecurityProvider: Abstract interface for secure key storage operations.
SecurityProviderOutboxEncryption: Adapter that connects Fasq's security providers to the durable outbox.
StringQueryKey: Query key backed by a plain string value.
SyncDagNode<TPayload>: A node in a directed acyclic graph for sync execution.
SyncDagResolution<TPayload>: Topological ordering output for sync orchestration.
ThroughputMetrics: Metrics representing query throughput over a time window.
TypedQueryKey<T>: A QueryKey that carries an associated result type.
UnresolvedConflictPlan
UseMutationResult<TData, TVariables>: Convenience wrapper returned by useMutation.
UuidRepairIdentityFactory: Production identity source; tests can inject a deterministic source.

Enums

AuthExecutionDecision: Result of checking one operation against current auth state.
AuthPolicy: Authentication policy selected by a queueable mutation.
AuthSessionStatus: Readiness of the current authentication session.
CircuitState: The state of a circuit breaker.
ConflictKind: Transport-independent reason supplied by an execution adapter.
ConflictPolicy: Explicit stale-write protection selected for one mutation.
DurableObservationRecordKind: Identifies which durable retention area produced an observation.
DurableOperationState: Public durable state exposed for one observed operation.
DurableOutboxErrorCode: Stable categories for durable outbox failures.
DurableQueueAggregateState: Durable aggregate state for a filtered queue view.
EvictionPolicy: Policy for selecting which cache entries to evict when memory limit is reached.
MutationExecutionPhase: Whether an execution adapter invoked its executor before cancellation.
MutationFailureCategory: Categories used to classify expected mutation outcomes.
MutationFailureDisposition: Scheduler action requested by a normalized adapter failure.
MutationOperationState: Durable lifecycle state for one queued mutation operation.
MutationOutcomeKnowledge: Whether an adapter knows if its failed operation changed remote state.
MutationRegistrationReadiness: Runtime readiness of a mutation codec and executor registration.
MutationStatus: Lifecycle status of a mutation operation.
MutationSubmissionStatus: Immediate outcome of a mutation submission.
OutboxUnknownRecordKind: Logical collection in which an unrecognized record was found.
ProjectionOverlayState
ProjectionRepairAction
QueryStatus: The status of a query's lifecycle.
RepairAction: Explicit actions available for terminal durable work.
RepairActionErrorCode: Safe categories for action failures.
ReplayBlockReason: Why a pending operation cannot be admitted to replay.
ReplayLifecycleTrigger: Source of a replay request.
RetryPlanAction: Final action selected by RetryPolicy.
SyncDagBlockReason: Why a node was not schedulable in the current graph.

Extensions

FasqProviderContext on BuildContext: Convenient access to the nearest core Fasq runtime.
JsonSerializableRegistry on CacheDataCodecRegistry: Helper registration APIs for JSON-serializable models.
QueryClientContext on BuildContext: Extension on BuildContext to easily access QueryClient.
StringQueryKeyExtension on String: Converts strings to QueryKey instances.

Constants

currentOutboxSchemaVersion → const int: Current on-disk envelope schema.
defaultOutboxSensitiveFieldNames → const Set<String>: Names that are never allowed in durable mutation payloads.

Functions

buildQueueObservation(OutboxSnapshot snapshot, {DurableOperationFilter? filter}) → DurableQueueObservation: Builds a redacted queue observation from one durable store snapshot.
classifyConflictFailure(MutationAdapterFailure failure) → ConflictClassification?: Converts only an explicit normalized conflict failure into conflict data. Transport adapters own HTTP/status/error interpretation before this seam.
filterQueueObservation(DurableQueueObservation observation, DurableOperationFilter filter) → DurableQueueObservation: Applies filter to an already-built queue observation.
logCircuitOpenEvent(CircuitOpenEvent event) → void: Default logging callback for circuit open events.
parseMutationOperationState(String value) → MutationOperationState: Parses a persisted operation state without silently accepting unknown data.
remapProjectionReferences(Object? value, {required String temporaryId, required String serverId}) → Object?: Replaces a temporary identifier in a JSON-safe value and its nested references.
remapQueryKeyIdentifier(String queryKey, String from, String to) → String: Remaps one exact identifier segment in a serialized query key.
useInfiniteQuery<TData, TParam>(QueryKey queryKey, Future<TData> queryFn(TParam param), {InfiniteQueryOptions<TData, TParam>? options, QueryClient? client}) → InfiniteQueryState<TData, TParam>: Observes an InfiniteQuery from a HookWidget and returns its state.
useMutation<TData, TVariables>(Future<TData> mutationFn(TVariables variables), {MutationOptions<TData, TVariables>? options, void onSuccess(TData data)?, void onError(Object error)?}) → UseMutationResult<TData, TVariables>: Creates a FASQ Mutation and exposes its state through a hook.
useNamedQueries(List<NamedQueryConfig> configs, {QueryClient? client}) → Map<String, QueryState>: Hook for named queries with map-based access
usePrefetchOnMount(List<PrefetchConfig> configs, {QueryClient? client}) → void: Hook that prefetches queries on mount.
usePrefetchQuery<T>({QueryClient? client}) → void Function(QueryKey, Future<T> (), {QueryOptions? options}): Hook that provides a callback to prefetch queries.
useQueries(List<QueryConfig> configs, {QueryClient? client}) → List<QueryState>: Hook that executes multiple queries in parallel and returns their states.
useQuery<T>(QueryKey queryKey, Future<T> queryFn(), {QueryOptions? options, QueryClient? client}) → QueryState<T>: Watches a single query inside a HookWidget and returns its state.
useQueryClient({QueryClient? client}) → QueryClient: Returns the ambient QueryClient instance for hook-enabled widgets.
validateJsonValue(Object? value, [String path = 'value']) → void: Validates a value against durable JSON value grammar.
whenReady<T, R>(QueryState<T> state, R selector(T value)) → R?: Applies selector only when state is ready with non-null data.

Typedefs

CacheDataDecoder<T> = T Function(Object? value): Decodes a JSON-safe object back into a typed cache value.
CacheDataEncoder<T> = Object? Function(T value): Encodes a typed cache value into a JSON-safe object.
CircuitOpenCallback = void Function(CircuitOpenEvent event): Callback function signature for circuit open events.
ConflictDomainResolver = ConflictRepairPlan Function(ConflictResolutionContext context)
CursorSelector<TData, TCursor> = TCursor? Function(TData pageData): Extracts a pagination cursor from page data.
DurableObservationFilter = DurableOperationFilter: Queue-facing name for the durable operation filter.
DurableOutboxTransaction = OutboxSnapshot Function(OutboxSnapshot current): A synchronous logical transformation committed as one durable transaction.
DurableQueueObservationFilter = DurableOperationFilter: Compatibility name for queue-level callers that filter observations.
FasqErrorReporter = void Function(FasqErrorContext context): Callback for reporting query errors to external systems.
GetNextPageParam<TData> = int? Function(TData lastPageData, int pageCount): Computes the next page number from page data and loaded page count.
GetPrevPageParam<TData> = int? Function(TData firstPageData, int pageCount): Computes the previous page number from page data and loaded page count.
MemoryPressureListener = void Function({required bool critical}): Callback used for memory pressure notifications.
ProjectionReducer = Object? Function(Object? base, Object? value)
RepairTelemetryAdapter = void Function(RepairTelemetryEvent event): Optional best-effort redacted telemetry adapter.

Exceptions / Errors

CancelledException: Exception thrown when a query operation is cancelled.
CircuitBreakerOpenException: Exception thrown when a request is made to an open circuit breaker.
ConflictAuthScopeMismatchException
ConflictRepairException
DuplicateMutationLocalIdentityException: Raised when one scope reuses an unresolved local mutation identity.
DuplicateMutationOperationException: Raised when an operation or idempotency identity is already retained.
DuplicateMutationRegistrationException: Raised when a duplicate registration would make replay ambiguous.
DurableMutationExecutionException: Raised when write-ahead replay executes but cannot complete its operation.
DurableMutationQueueStorageException: Safe typed storage failure raised when a backend returns an unknown error.
DurableOutboxException: Base exception for durable outbox operations.
InvalidMutationEnqueueStateException: Raised when callers try to enqueue a non-replayable operation state.
InvalidMutationPayloadException: Raised when a mutation payload is not JSON-safe or cannot be decoded.
InvalidMutationResultException: Raised when an executor result cannot be durably encoded.
IsolateExecutionException: Exception thrown when isolate execution fails.
IsolateTaskCancelledException: Exception thrown when an isolate task is cancelled.
MissingConflictPreconditionException: Raised when required compare-and-set protection has no token.
MutationAdapterException: Exception adapter implementations can throw to provide normalized failure.
MutationContractException: Base error for invalid or unavailable durable mutation contracts.
MutationRegistrationTypeException: Raised when a typed key disagrees with its bootstrapped definition.
OutboxCapacityExceededException: Raised when a configured capacity limit would be exceeded.
OutboxCorruptException: Raised when no validated store copy remains available.
OutboxCredentialRejectedException: Raised when durable data contains a credential-like field.
OutboxEncryptionException: Raised when encryption cannot safely protect or recover the store.
OutboxGenerationConflictException: Raised when a generation compare-and-swap check fails.
OutboxMigrationRequiredException: Raised when the stored data requires a newer or unavailable migration.
OutboxOwnershipException: Raised when the store is owned by another process or isolate.
RepairActionException: Safe public exception; it never carries variables or exception objects.
ReplayCancelledException: Safe cancellation failure for work that did not start or was interrupted.
UnexpectedConflictPreconditionException: Raised when a token is supplied for a mutation without protection.
UnknownMutationKeyException: Raised when a persisted key has no registered codec or executor.
UnknownMutationStateException: Raised when persisted operation state contains an unknown value.

fasq_hooks library

Classes

Enums

Extensions

Constants

Functions

Typedefs

Exceptions / Errors

fasq_hooks package

fasq_hooks library