# Examples

> Every feature as a live screen you can run in the browser, one whole small app that composes them, and the package's one-file example.

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](https://dualmeta-gmbh.github.io/query_kit/docs/examples/task-manager.md)**: 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](https://dualmeta-gmbh.github.io/query_kit/docs/examples/one-file-tour.md)**: the package's own example, a
  provider, one query read two ways and a mutation, in a single file with no
  server.

## Basics

- [Simple](https://dualmeta-gmbh.github.io/query_kit/docs/examples/simple.md): One query, its states, and a refetch.
- [Basic](https://dualmeta-gmbh.github.io/query_kit/docs/examples/basic.md): A list, a detail, and what the cache already knows.
- [Four call styles](https://dualmeta-gmbh.github.io/query_kit/docs/examples/four-call-styles.md): The same query through context, builder, mixin and controller.

## Queries

- [Default query function](https://dualmeta-gmbh.github.io/query_kit/docs/examples/default-query-function.md): A query function derived from the key, set once as a default.
- [Dependent queries](https://dualmeta-gmbh.github.io/query_kit/docs/examples/dependent-queries.md): A query that waits for another to have data.
- [Parallel queries](https://dualmeta-gmbh.github.io/query_kit/docs/examples/parallel-queries.md): Several queries in one widget, and the global fetching count.
- [Query collections](https://dualmeta-gmbh.github.io/query_kit/docs/examples/query-collections.md): A list of queries that grows, shrinks and reorders at runtime.
- [Combine](https://dualmeta-gmbh.github.io/query_kit/docs/examples/combine.md): Three queries of three types, read as one result.
- [Initial and placeholder data](https://dualmeta-gmbh.github.io/query_kit/docs/examples/initial-and-placeholder.md): Data before the first fetch: written to the cache, or shown only.
- [Select and structural sharing](https://dualmeta-gmbh.github.io/query_kit/docs/examples/select-and-sharing.md): What a reader rebuilds on, and what it does not.

## Paging

- [Pagination](https://dualmeta-gmbh.github.io/query_kit/docs/examples/pagination.md): Page by page, keeping the previous page on screen while the next loads.
- [Load more and infinite scroll](https://dualmeta-gmbh.github.io/query_kit/docs/examples/load-more.md): An infinite query that appends pages as you scroll.
- [Infinite query with max pages](https://dualmeta-gmbh.github.io/query_kit/docs/examples/max-pages.md): Pages in both directions, with a window of three.

## Mutations

- [Mutations](https://dualmeta-gmbh.github.io/query_kit/docs/examples/mutations.md): mutate, mutateAsync, reset, callbacks, and scopes.
- [Optimistic updates](https://dualmeta-gmbh.github.io/query_kit/docs/examples/optimistic-updates.md): Show the write before the server answers — two ways.
- [Mutation context and cancel](https://dualmeta-gmbh.github.io/query_kit/docs/examples/mutation-cancel.md): A write that reads what onMutate kept, and can be called off.
- [Mutation state](https://dualmeta-gmbh.github.io/query_kit/docs/examples/mutation-state.md): Every running mutation in the cache, read by a widget that owns none of them.

## Cache

- [Prefetching](https://dualmeta-gmbh.github.io/query_kit/docs/examples/prefetching.md): Warm the cache before the screen that needs it opens.
- [Stale time and garbage collection](https://dualmeta-gmbh.github.io/query_kit/docs/examples/stale-and-gc.md): When data goes stale, and when an unused entry is dropped.
- [Invalidation and filters](https://dualmeta-gmbh.github.io/query_kit/docs/examples/invalidation-and-filters.md): Invalidate, refetch, reset and remove, by prefix, type or predicate.
- [Playground](https://dualmeta-gmbh.github.io/query_kit/docs/examples/playground.md): Todos with live knobs for stale time, gc time, latency and errors.
- [Cache inspector](https://dualmeta-gmbh.github.io/query_kit/docs/examples/cache-inspector.md): Every entry and every event, live.

## Network

- [Auto refetching](https://dualmeta-gmbh.github.io/query_kit/docs/examples/auto-refetching.md): Polling on an interval, in the foreground or not.
- [Retry](https://dualmeta-gmbh.github.io/query_kit/docs/examples/retry.md): Retry policies and delays, and what the result shows meanwhile.
- [Cancellation](https://dualmeta-gmbh.github.io/query_kit/docs/examples/cancellation.md): A query cancelled is a request aborted.
- [Offline](https://dualmeta-gmbh.github.io/query_kit/docs/examples/offline.md): Network modes, paused mutations, and coming back online.
- [Focus refetch](https://dualmeta-gmbh.github.io/query_kit/docs/examples/focus-refetch.md): What happens when the app comes back to the foreground.

## Advanced

- [Filtering rebuilds](https://dualmeta-gmbh.github.io/query_kit/docs/examples/build-when.md): buildWhen on the eight keyless reads, each beside its unfiltered twin.
- [Global callbacks](https://dualmeta-gmbh.github.io/query_kit/docs/examples/global-callbacks.md): Cache-level callbacks, and meta on its way through.
- [Diagnostics](https://dualmeta-gmbh.github.io/query_kit/docs/examples/diagnostics.md): What 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:

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

```bash
cd examples/showcase && flutter run -d chrome
```

The task manager runs on the web and iOS:

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

```bash
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](https://dualmeta-gmbh.github.io/query_kit/docs/project/examples.md).
