Examples

Each page below is one screen of the showcase app: what it demonstrates, a live demo that runs in your browser against an in-memory backend (nothing is downloaded until you press Run), what to try in it, and the source of the screen, taken from the compiled file. Every screen draws its cache entries' state as it changes, so you can watch what the library does, not just what the widget shows.

A demo is a Flutter web app in a frame, and it behaves like one: clicking outside it and back in is a window focus change, so a stale query refetches on the way back in, as it would in your app. A fetches= count a page promises can therefore be one higher if you clicked away in between.

Whole apps

• Task manager: one ordinary small app, a to-do list against a slow backend that fails on cue. Where the showcase lets you look a feature up, this shows how six of them compose: a list two widgets share, a detail screen, optimistic writes with rollback, and a reminder that is accepted before it is confirmed.
• One-file tour: the package's own example, a provider, one query read two ways and a mutation, in a single file with no server.

Basics

• SimpleOne query, its states, and a refetch.
• BasicA list, a detail, and what the cache already knows.
• Four call stylesThe same query through context, builder, mixin and controller.

Queries

• Default query functionA query function derived from the key, set once as a default.
• Dependent queriesA query that waits for another to have data.
• Parallel queriesSeveral queries in one widget, and the global fetching count.
• Query collectionsA list of queries that grows, shrinks and reorders at runtime.
• CombineThree queries of three types, read as one result.
• Initial and placeholder dataData before the first fetch: written to the cache, or shown only.
• Select and structural sharingWhat a reader rebuilds on, and what it does not.

Paging

• PaginationPage by page, keeping the previous page on screen while the next loads.
• Load more and infinite scrollAn infinite query that appends pages as you scroll.
• Infinite query with max pagesPages in both directions, with a window of three.

Mutations

• Mutationsmutate, mutateAsync, reset, callbacks, and scopes.
• Optimistic updatesShow the write before the server answers — two ways.
• Mutation context and cancelA write that reads what onMutate kept, and can be called off.
• Mutation stateEvery running mutation in the cache, read by a widget that owns none of them.

Cache

• PrefetchingWarm the cache before the screen that needs it opens.
• Stale time and garbage collectionWhen data goes stale, and when an unused entry is dropped.
• Invalidation and filtersInvalidate, refetch, reset and remove, by prefix, type or predicate.
• PlaygroundTodos with live knobs for stale time, gc time, latency and errors.
• Cache inspectorEvery entry and every event, live.

Network

• Auto refetchingPolling on an interval, in the foreground or not.
• RetryRetry policies and delays, and what the result shows meanwhile.
• CancellationA query cancelled is a request aborted.
• OfflineNetwork modes, paused mutations, and coming back online.
• Focus refetchWhat happens when the app comes back to the foreground.

Advanced

• Filtering rebuildsbuildWhen on the eight keyless reads, each beside its unfiltered twin.
• Global callbacksCache-level callbacks, and meta on its way through.
• DiagnosticsWhat the library throws, and when: the wrong type, the missing function.

Running them yourself

Both apps live in the repository with a small backend each. The showcase:

cd examples/showcase/server && npm install && npm run dev

cd examples/showcase && flutter run -d chrome

The task manager runs on the web and iOS:

cd examples/task_manager/server && npm install && npm run dev

cd examples/task_manager && flutter run -d chrome

Either app also runs with no server, as the live demos do: flutter run -d chrome --dart-define=QK_BACKEND=inmemory.

How all of them are tested, from widget tests to a browser suite against the real backend, is on how the examples are built.