BloomQueryScope class

Global query cache manager and request deduplicator for Bloom JS Native applications.

BloomData provides a centralized, pure-Dart memory cache for asynchronous queries:

• Key Normalization: Deterministically serializes complex structured keys (Strings, Lists, Maps) via normalizeKey.
• Request Deduplication: Collapses concurrent identical requests into a single in-flight Future via deduplicate.
• Cache Invalidation: Notifies active BloomQuery instances via invalidateQueries using prefix matching.
• Direct Manipulation: Allows optimistic cache writing via setQueryData and direct inspection via getQueryData.
• SSR Dehydration & Hydration: Serializes cache snapshots to JSON via dehydrate or dehydrateToScriptTag, and restores them on the client via hydrate or hydrateFromJson with zero redundant fetches.

SSR & Browser Compatibility

Pure Dart with zero Flutter or DOM dependencies. In SSR environments, BloomData can be pre-populated with server data before rendering or cleared between requests via clear.

Example

// Manually prime or update the cache
BloomData.setQueryData<User>(['user', 123], (old) => updatedUser);

// Invalidate all queries under the 'user' prefix
BloomData.invalidateQueries(['user']);

See also:

• BloomQuery, the reactive query coordinator that reads from and populates BloomData.
• BloomInfiniteQuery, for paginated and cursor-based infinite queries.
• BloomMutation, for executing mutations that invalidate or optimistically update BloomData. Request-isolated query cache scope holding private SSR state.

A BloomQueryScope owns its own cache entries, invalidation controllers, and in-flight deduplication trackers. Concurrent SSR requests each run in their own scope (via BloomData.runWithScope / BloomData.withRequestScope) so identical keys such as ['user', 'current'] never collide across requests sharing one Dart isolate.

The browser uses BloomData.browserScope implicitly. Explicitly shared public server data should use BloomData.sharedPublicScope via BloomData.runWithScope — never the per-request scope.

Scopes must be disposed after the request finishes (dispose) to close broadcast controllers and drop references. BloomData.withRequestScope does this automatically, including on errors. For streaming responses, keep the scope alive until the stream closes or is cancelled.