KoolbaseCollectionController class

The data half of KoolbaseCollectionList, deliberately widget-free.

Owns everything about GETTING the records correctly:

  • a FRESH query per fetch — KoolbaseQuery.where mutates its instance, and stream identity is derived from the filters, so a reused query whose shape drifts would change identity after subscription
  • the stale-while-revalidate contract: KoolbaseQuery.get seeds (cache-first), the query's stream delivers background refreshes, and both land through one path so data arriving twice is normal
  • subscription lifecycle: one stream subscription per query identity, replaced only if the identity changes, cancelled on dispose
  • refresh: a new fetch through the same discipline

The widget below is one opinionated skin over this. A custom-scroll or grid variant later consumes this controller unchanged.

Inheritance

Constructors

KoolbaseCollectionController({required String collection, KoolbaseQueryBuilder? queryBuilder, KoolbaseQuery baseQuery()?, bool live = false, @visibleForTesting Stream<Object?> liveEvents(String collection)?})

Properties

collection → String
The collection to list.
final
error → Object?
no setter
hashCode → int
The hash code for this object.
no setterinherited
hasListeners → bool
Whether any listeners are currently registered.
no setterinherited
hasMore → bool
Whether the collection has records past what is loaded. Exact: every page comes back with the query's total, so this is loaded < total, not a guess from a short page. True before the first load -- "we do not know yet" reads as "there may be more".
no setter
isFromCache → bool
True while the shown records came from cache and no network result has replaced them yet — the SWR first arrival. UIs can show a subtle refreshing hint.
no setter
live → bool
Re-read page one, silently, when Koolbase realtime reports a record created, updated or deleted in collection -- once per burst (250 ms), not once per event. The list's own query re-runs, so filters, order and read rules stay right. Signed out, only a collection anyone can read (read rule "public") is live; any other behaves as a normal list until a user signs in.
final
loadingMore → bool
True while loadMore runs, for a spinner at the foot of the list.
no setter
queryBuilder → KoolbaseQueryBuilder?
Shapes each fresh query (filters, order, limit). Null lists unfiltered.
final
records → List<KoolbaseRecord>
no setter
refreshing → bool
True while an explicit refresh is in flight.
no setter
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
status → KoolbaseListStatus
no setter

Methods

addListener(VoidCallback listener) → void
Register a closure to be called when the object changes.
inherited
dispose() → void
Discards any resources used by the object.
override
load() → Future<void>
First load. Safe to call once; refresh for subsequent loads.
loadMore() → Future<void>
The next page, appended.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
notifyListeners() → void
Call all the registered listeners.
inherited
refresh() → Future<void>
Fetch again through a fresh query. Existing records stay visible while it runs; a failure keeps them (stale beats blank).
removeListener(VoidCallback listener) → void
Remove a previously registered closure from the list of closures that are notified when the object changes.
inherited
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited