API Reference

import { make, Store } from "@tilia/query";

type Card = { id: string; deck: string; front: string; back: string; seen: number };
type DeckQuery = { deck: string };

const [cards, store] = make({
  id: (card: Card) => card.id,
  matches: (query: DeckQuery, card: Card) => card.deck === query.deck,
  store: Store.make<Card, DeckQuery>({ find, upsert, remove }),
});

// Two handles, two verbs. A view reads through `cards`; a review writes
// through `store`, and every open deck that lists the card follows.
const spanish = cards.array({ deck: "spanish" });
store.upsert({ id: "cat.es", deck: "spanish", front: "cat", back: "gato", seen: 1 });

open TiliaQuery

type card = {id: string, deck: string, front: string, mutable back: string, mutable seen: int}
type deckQuery = {deck: string}

let (cards, store) = make({
  id: card => card.id,
  matches: (query, card) => card.deck === query.deck,
  store: Store.make({find, upsert, remove}),
})

// Two handles, two verbs. A view reads through `cards`; a review writes
// through `store`, and every open deck that lists the card follows.
let spanish = cards.array({deck: "spanish"})
store.upsert({id: "cat.es", deck: "spanish", front: "cat", back: "gato", seen: 1})

// Three translations around an existing HTTP client. Ordering, batching and
// retry are the store's; this code only says what the backend answered.
const factory = Store.make<Card, DeckQuery>({
  find: (query, answer) =>
    api.get(`/decks/${query.deck}`).then(answer.fresh, (error: ApiError) => answer.fail(error.message)),
  upsert: (card, reply) =>
    api.put(`/cards/${card.id}`, card).then(
      (saved) => reply({ outcome: "saved", value: saved }),
      (error: ApiError) => {
        if (error.status === 409) reply({ outcome: "conflict", value: error.body });
        else if (error.status >= 500) reply("transient");
        else reply({ outcome: "rejected", message: error.message });
      },
    ),
  remove: (id, reply) =>
    api.delete(`/cards/${id}`).then(
      () => reply("removed"),
      (error: ApiError) => reply(error.status >= 500 ? "transient" : { outcome: "rejected", message: error.message }),
    ),
});

// Three translations around an existing HTTP client. Ordering, batching and
// retry are the store's; this code only says what the backend answered.
let factory = Store.make({
  find: (query, answer) =>
    Api.get(`/decks/${query.deck}`)
    ->Promise.thenResolve(result =>
      switch result {
      | Ok(cards) => answer.fresh(cards)
      | Error(message) => answer.fail(message)
      }
    )
    ->ignore,
  upsert: (card, reply) =>
    Api.put(`/cards/${card.id}`, card)
    ->Promise.thenResolve(result =>
      switch result {
      | Ok(saved) => reply(Saved({value: saved}))
      | Error(Stale(theirs)) => reply(Conflict({value: theirs}))
      | Error(Refused(message)) => reply(Rejected({message: message}))
      | Error(Unavailable) => reply(Transient)
      }
    )
    ->ignore,
  remove: (id, reply) =>
    Api.delete(`/cards/${id}`)
    ->Promise.thenResolve(result =>
      switch result {
      | Ok() => reply(Removed)
      | Error(Refused(message)) => reply(Rejected({message: message}))
      | Error(Stale(_)) => reply(Rejected({message: "changed on the server"}))
      | Error(Unavailable) => reply(Transient)
      }
    )
    ->ignore,
})

// `custom` is for a backend that pushes. This fetch subscribes and keeps the
// result fresh itself; `finally` is where the subscription ends, whether the
// query was evicted, superseded or the app disposed.
const factory = Store.custom<Card, DeckQuery>({
  remote: {
    online: Store.online(),
    fetch: (query, channel) => {
      const feed = socket.subscribe(query, channel.live);
      channel.finally(feed.close);
    },
    push,
  },
  persist: indexeddb({ name: "flashcards" }),
});

// `custom` is for a backend that pushes. This fetch subscribes and keeps the
// result fresh itself; `finally` is where the subscription ends, whether the
// query was evicted, superseded or the app disposed.
let factory = Store.custom({
  remote: {
    online: Store.online(),
    fetch: (query, channel) => {
      let feed = socket.subscribe(query, channel.live)
      channel.finally(feed.close)
    },
    push,
  },
  persist: TiliaQueryIndexedDb.make({name: "flashcards"}),
})

// A test builds the app on a keyspace that forgets with the process. Rows,
// query records and the outbox go down the same path as with IndexedDB, so
// what the test proves about persistence holds in production.
const [cards, store] = make({
  id: (card: Card) => card.id,
  matches: (query: DeckQuery, card: Card) => card.deck === query.deck,
  store: Store.make<Card, DeckQuery>({ find, upsert, remove, persist: Store.memory() }),
});

// A test builds the app on a keyspace that forgets with the process. Rows,
// query records and the outbox go down the same path as with IndexedDB, so
// what the test proves about persistence holds in production.
let (cards, store) = make({
  id: card => card.id,
  matches: (query, card) => card.deck === query.deck,
  store: Store.make({find, upsert, remove, persist: Store.memory()}),
})

import { Store } from "@tilia/query";
import { make as indexeddb } from "@tilia/query/indexeddb";

// One database for the app, opened on first use; a read or write made before
// it opens waits for it. `onError` is the only place a database that will not
// open makes itself known: reads answer empty and writes are dropped.
const persist = indexeddb({
  name: "flashcards",
  onError: (error) => console.error("persistence lost", error),
});

const factory = Store.make<Card, DeckQuery>({ find, upsert, remove, persist });

// One database for the app, opened on first use; a read or write made before
// it opens waits for it. `onError` is the only place a database that will not
// open makes itself known: reads answer empty and writes are dropped.
let persist = TiliaQueryIndexedDb.make({
  name: "flashcards",
  onError: error => Console.error2("persistence lost", error),
})

let factory = Store.make({find, upsert, remove, persist})

// The card under review: the first of the deck per `sort`. A deck with nothing
// left is `noMatch`, and it says so with the claim its rows would have had, so
// the view can tell "done" from "done as of last sync".
const review = () => {
  const next = cards.one({ deck: "spanish" });
  if (next === "loading") return spinner();
  if (next.state === "loaded") return flashcard(next.data);
  if (next.reason === "offline") return offlineNotice();
  return next.reason.reason === "noMatch" ? deckDone(next.reason.claim) : failure(next.reason.message);
};

// The card under review: the first of the deck per `sort`. A deck with nothing
// left is `NoMatch`, and it says so with the claim its rows would have had, so
// the view can tell "done" from "done as of last sync".
let review = () =>
  switch cards.one({deck: "spanish"}) {
  | Loading => spinner()
  | Loaded({data: card}) => flashcard(card)
  | NoData({reason: Offline}) => offlineNotice()
  | NoData({reason: NoMatch({claim})}) => deckDone(claim)
  | NoData({reason: Failed({message})}) => failure(message)
  }

// The deck list. `claim` is a field, not a state: the common path renders
// whatever is there, and only the badge asks how strong the answer is. An
// empty deck is a loaded empty list, not an absence.
const deckView = () => {
  const deck = cards.array({ deck: "spanish" });
  if (deck === "loading") return spinner();
  if (deck.state === "noData") return empty(deck.reason);
  return list(deck.data, deck.claim === "fresh" ? null : staleBadge(deck.claim));
};

// The deck list. `claim` is a field, not a state: the common path renders
// whatever is there, and only the badge asks how strong the answer is. An
// empty deck is a loaded empty list, not an absence.
let deckView = () =>
  switch cards.array({deck: "spanish"}) {
  | Loading => spinner()
  | NoData({reason}) => empty(reason)
  | Loaded({data, claim: Fresh}) => list(data, None)
  | Loaded({data, claim}) => list(data, Some(staleBadge(claim)))
  }

// The engine owns no timers. One interval drives refresh, ageing, eviction,
// local purge and push retries. Every 10 s lands three times inside the
// default 30 s refresh window, which is the "at least twice" the rule asks.
const timer = setInterval(cards.tick, 10_000);

// A test owns time instead: no interval, a tick where the scenario says so.
clock.advance(35_000);
cards.tick();

// The engine owns no timers. One interval drives refresh, ageing, eviction,
// local purge and push retries. Every 10 s lands three times inside the
// default 30 s refresh window, which is the "at least twice" the rule asks.
let timer = setInterval(cards.tick, 10_000)

// A test owns time instead: no interval, a tick where the scenario says so.
clock.advance(35_000)
cards.tick()

// Leaving the page. Stop the heartbeat first, then let the engine close its
// finds — each `finally` teardown runs once — and shut the store down.
// Nothing is written on the way out: local data keeps to its own expiry, so
// the next visit starts from it.
const leave = () => {
  clearInterval(timer);
  cards.dispose();
};
window.addEventListener("pagehide", leave);

// Leaving the page. Stop the heartbeat first, then let the engine close its
// finds — each `finally` teardown runs once — and shut the store down.
// Nothing is written on the way out: local data keeps to its own expiry, so
// the next visit starts from it.
let leave = () => {
  clearInterval(timer)
  cards.dispose()
}
Window.addEventListener("pagehide", leave)

// Alice passes a card in a tunnel. The deck view moves on now — the row is
// placed and every open query that lists it follows — while the write waits
// in the outbox and goes when the train comes out.
const pass = (card: Card) => store.upsert({ ...card, seen: card.seen + 1 });

// A new card is the same call. The id is the client's, and the backend keeps it.
const add = (deck: string, front: string, back: string) =>
  store.upsert({ id: crypto.randomUUID(), deck, front, back, seen: 0 });

// Alice passes a card in a tunnel. The deck view moves on now — the row is
// placed and every open query that lists it follows — while the write waits
// in the outbox and goes when the train comes out.
let pass = card => store.upsert({...card, seen: card.seen + 1})

// A new card is the same call. The id is the client's, and the backend keeps it.
let add = (~deck, ~front, ~back) => store.upsert({id: newId(), deck, front, back, seen: 0})

// The card leaves every open deck at once, and the outbox carries only its
// id. If the server refuses, the card comes back, with a rejection that holds
// the removed value as `base`.
const drop = (card: Card) => store.remove(card.id);

// The card leaves every open deck at once, and the outbox carries only its
// id. If the server refuses, the card comes back, with a rejection that holds
// the removed value as `base`.
let drop = card => store.remove(card.id)

// Nora edits a card on her phone and the server tells every device. Clean
// rows are replaced. A card Alice is editing offline is not overwritten: it
// goes through `merge`, and her edit is rebased or recorded as a conflict.
socket.on("cards:changed", (changed: Card[]) => store.receive.changed(changed));

// Nora edits a card on her phone and the server tells every device. Clean
// rows are replaced. A card Alice is editing offline is not overwritten: it
// goes through `merge`, and her edit is rebased or recorded as a conflict.
socket.on("cards:changed", changed => store.receive.changed(changed))

// Ids only: a deletion never needs the row. A pending edit to a card the
// server removed becomes a rejection instead of bringing the card back.
socket.on("cards:removed", (ids: string[]) => store.receive.removed(ids));

// Ids only: a deletion never needs the row. A pending edit to a card the
// server removed becomes a rejection instead of bringing the card back.
socket.on("cards:removed", ids => store.receive.removed(ids))

// A sync indicator in the header. `status` is a tilia object, so `observe`
// re-runs as the outbox drains and as rejections come and go.
observe(() => {
  const { pending, rejected } = store.status;
  syncBadge.textContent = pending > 0 ? `${pending} to sync` : "";
  syncBadge.hidden = pending === 0 && rejected.length === 0;
});

// A sync indicator in the header. `status` is a tilia object, so `observe`
// re-runs as the outbox drains and as rejections come and go.
Tilia.observe(() => {
  let {pending, rejected} = store.status
  syncBadge.textContent = pending > 0 ? `${pending->Int.toString} to sync` : ""
  syncBadge.hidden = pending === 0 && rejected->Array.length === 0
})->ignore

// The rejections panel. "Try again" queues the refused work as a new
// optimistic write against the row as it stands now. The record is spent
// either way: if the row has moved on since, `retry` on it is a no-op.
for (const rejection of store.status.rejected) {
  panel.row(describe(rejection), { tryAgain: () => store.retry(rejection) });
}

// The rejections panel. "Try again" queues the refused work as a new
// optimistic write against the row as it stands now. The record is spent
// either way: if the row has moved on since, `retry` on it is a no-op.
store.status.rejected->Array.forEach(rejection =>
  panel.row(describe(rejection), ~tryAgain=() => store.retry(rejection))
)

// The panel's other button. Remote truth already stands — a rejection is
// recorded after the revert — so "keep theirs" only drops the record.
for (const rejection of store.status.rejected) {
  panel.row(describe(rejection), { keepTheirs: () => store.discard(rejection) });
}

// The panel's other button. Remote truth already stands — a rejection is
// recorded after the revert — so "keep theirs" only drops the record.
store.status.rejected->Array.forEach(rejection =>
  panel.row(describe(rejection), ~keepTheirs=() => store.discard(rejection))
)

// Two views ask for the same deck with the keys in a different order. The
// default key sees one question: one find, one cached list, one identity.
const same = sortedStringify({ deck: "spanish", due: true }) === sortedStringify({ due: true, deck: "spanish" }); // true

// The same rule inside a custom `key`, for a query that carries a field the
// engine should not distinguish on.
const key = ({ label: _label, ...query }: DeckQuery & { label: string }) => sortedStringify(query);

// Two views ask for the same deck with the keys in a different order. The
// default key sees one question: one find, one cached list, one identity.
let same = sortedStringify({"deck": "spanish", "due": true}) === sortedStringify({"due": true, "deck": "spanish"}) // true

// The same rule inside a custom `key`, for a query that carries a field the
// engine should not distinguish on.
let key = (query: labelledQuery) => sortedStringify({deck: query.deck})

// A devtools panel: which questions the UI is asking right now, and which
// answers are kept warm for a return visit until memory expiry.
const { live, idle } = cards._canopy();
console.table({ observed: live, cached: idle });

// A devtools panel: which questions the UI is asking right now, and which
// answers are kept warm for a return visit until memory expiry.
let {live, idle} = cards._canopy()
Console.table({"observed": live, "cached": idle})

// A keyspace of your own keeps a deck index beside the rows. Each row is JSON
// under `rowTag`, keyed by its id, so `set` can maintain the index as rows
// come and go — and `lookup` can later answer a deck the store has no record
// of, and certify it.
const persist: Kv = {
  ...table,
  set: (tag, key, value) => {
    table.set(tag, key, value);
    if (tag === Store.rowTag) deckIndex.update(key, value);
  },
};

// A keyspace of your own keeps a deck index beside the rows. Each row is JSON
// under `rowTag`, keyed by its id, so `set` can maintain the index as rows
// come and go — and `lookup` can later answer a deck the store has no record
// of, and certify it.
let persist: Store.Kv.t = {
  ...table,
  set: (~tag, ~key, value) => {
    table.set(~tag, ~key, value)
    if tag === Store.rowTag {
      DeckIndex.update(key, value)
    }
  },
}

// One signal per process, shared by every store that does not bring its own.
// In a browser it follows online/offline events. Write to it where the browser
// cannot know: a "work offline" switch, or a test going into a tunnel.
const online = Store.online();
offlineSwitch.onchange = () => {
  online.value = !offlineSwitch.checked;
};

// One signal per process, shared by every store that does not bring its own.
// In a browser it follows online/offline events. Write to it where the browser
// cannot know: a "work offline" switch, or a test going into a tunnel.
let online = Store.online()
offlineSwitch.onchange = () => online.value = !offlineSwitch.checked

// A feature that only displays takes the query object, and nothing else: it
// can ask, it cannot write. The store handle stays with the feature that edits.
const dueCount = (cards: TiliaQuery<Card, DeckQuery>, deck: string) => {
  const result = cards.array({ deck });
  return result !== "loading" && result.state === "loaded" ? result.data.filter(due).length : 0;
};

// A feature that only displays takes the query object, and nothing else: it
// can ask, it cannot write. The store handle stays with the feature that edits.
let dueCount = (cards: t<deckQuery, card>, deck) =>
  switch cards.array({deck: deck}) {
  | Loaded({data}) => data->Array.filter(due)->Array.length
  | Loading | NoData(_) => 0
  }

// Everything the engine needs to know about cards and decks. The store gets
// the same answers through `Schema`, defaults resolved, and never re-derives them.
const config: Config<Card, DeckQuery, Store<Card>> = {
  id: (card) => card.id,
  matches: (query, card) => card.deck === query.deck,
  sort: () => (cards) => [...cards].sort((a, b) => a.seen - b.seen),
  expiry: { refresh: 15_000, memory: 5 * 60_000 },
  onError: (query, message) => console.warn(`refresh of ${query.deck} failed: ${message}`),
  store: Store.make({ find, upsert, remove }),
};

// Everything the engine needs to know about cards and decks. The store gets
// the same answers through `schema`, defaults resolved, and never re-derives them.
let config: config<deckQuery, card, Store.t<card>> = {
  id: card => card.id,
  matches: (query, card) => card.deck === query.deck,
  sort: _query => cards => cards->Array.toSorted((a, b) => Int.compare(a.seen, b.seen)),
  expiry: {refresh: 15_000., memory: 300_000.},
  onError: (~query, ~message) => Console.warn(`refresh of ${query.deck} failed: ${message}`),
  store: Store.make({find, upsert, remove}),
}

// One renderer for every read. `claim` is a field, so the loaded branch
// renders first and only the view asks how strong the answer is.
const render = <T>(value: Loadable<T>, view: (data: T, claim: Claim) => Node) => {
  if (value === "loading") return spinner();
  if (value.state === "loaded") return view(value.data, value.claim);
  return empty(value.reason);
};

// One renderer for every read. `claim` is a field, so the loaded branch
// renders first and only the view asks how strong the answer is.
let render = (value, view) =>
  switch value {
  | Loading => spinner()
  | Loaded({data, claim}) => view(data, claim)
  | NoData({reason}) => empty(reason)
  }

// A badge under the deck: nothing for fresh, a word for what local storage
// could and could not promise.
const badge = (claim: Claim) =>
  claim === "fresh" ? "" : claim === "local" ? "as of last sync" : "some cards, maybe not all";

// A badge under the deck: nothing for fresh, a word for what local storage
// could and could not promise.
let badge = claim =>
  switch claim {
  | Fresh => ""
  | Local => "as of last sync"
  | Partial => "some cards, maybe not all"
  }

// The empty state is not one message. Offline invites waiting; a failure
// carries the store's words; no match means the deck is done — with the same
// claim its rows would have had.
const explain = (reason: Reason) => {
  if (reason === "offline") return "No connection yet. Cards will appear when it returns.";
  if (reason.reason === "failed") return reason.message;
  return reason.claim === "fresh" ? "Deck complete." : "Nothing here as of last sync.";
};

// The empty state is not one message. Offline invites waiting; a failure
// carries the store's words; no match means the deck is done — with the same
// claim its rows would have had.
let explain = reason =>
  switch reason {
  | Offline => "No connection yet. Cards will appear when it returns."
  | Failed({message}) => message
  | NoMatch({claim: Fresh}) => "Deck complete."
  | NoMatch(_) => "Nothing here as of last sync."
  }

// A push translates each operation to the backend's verb. A remove carries
// the id only: nothing else is needed to delete, and nothing else is sent.
const send = (op: Op<Card>) =>
  op.op === "upsert" ? api.put(`/cards/${op.value.id}`, op.value) : api.delete(`/cards/${op.id}`);

// A push translates each operation to the backend's verb. A remove carries
// the id only: nothing else is needed to delete, and nothing else is sent.
let send = op =>
  switch op {
  | Upsert({value}) => Api.put(`/cards/${value.id}`, value)->Promise.thenResolve(_ => ())
  | Remove({id}) => Api.delete(`/cards/${id}`)->Promise.thenResolve(_ => ())
  }

// Field-level merge. Alice changed `back`; Nora, elsewhere, `seen`. Keep both:
// a field Alice left alone takes the remote's value, and her write goes again.
const merge = (change: Change<Card>, remote: Card) => {
  switch (change.change) {
    case "clean":
      Object.assign(change.value, remote);
      return true;
    case "updated": {
      const { base, edited } = change;
      if (edited.seen === base.seen) edited.seen = remote.seen;
      if (edited.back === base.back) edited.back = remote.back;
      return true;
    }
    default:
      return false; // a create or a remove against a row the server holds: record the conflict
  }
};

// Field-level merge. Alice changed `back`; Nora, elsewhere, `seen`. Keep both:
// a field Alice left alone takes the remote's value, and her write goes again.
let merge = (~change, ~remote) =>
  switch change {
  | Clean({value}) =>
    value.back = remote.back
    value.seen = remote.seen
    true
  | Updated({base, edited}) =>
    if edited.seen === base.seen {
      edited.seen = remote.seen
    }
    if edited.back === base.back {
      edited.back = remote.back
    }
    true
  | Created(_) | Removed(_) => false // a create or a remove against a row the server holds: record the conflict
  }

// One line per refused write, in outbox order: retry the first and the ones
// it caused may follow. Conflicts have no message of their own; failures
// carry the server's.
const describe = (rejection: Rejection<Card>) => {
  switch (rejection.rejection) {
    case "createConflict": return `"${rejection.edited.front}" already exists on the server`;
    case "updateConflict": return `"${rejection.edited.front}" changed on the server while you edited it`;
    case "removeConflict": return `"${rejection.base.front}" changed on the server before it was removed`;
    case "removeFailed": return `"${rejection.base.front}": ${rejection.message}`;
    default: return `"${rejection.edited.front}": ${rejection.message}`;
  }
};

// One line per refused write, in outbox order: retry the first and the ones
// it caused may follow. Conflicts have no message of their own; failures
// carry the server's.
let describe = rejection =>
  switch rejection {
  | CreateConflict({edited}) => `"${edited.front}" already exists on the server`
  | UpdateConflict({edited}) => `"${edited.front}" changed on the server while you edited it`
  | RemoveConflict({base}) => `"${base.front}" changed on the server before it was removed`
  | CreateFailed({edited, message}) | UpdateFailed({edited, message}) => `"${edited.front}": ${message}`
  | RemoveFailed({base, message}) => `"${base.front}": ${message}`
  }

// Sync state for the header, in one sentence. Reactive: `observe` re-runs as
// the outbox drains and as rejections come and go.
observe(() => {
  const { pending, rejected }: Status<Card> = store.status;
  header.sync = pending === 0 && rejected.length === 0 ? "up to date" : `${pending} waiting, ${rejected.length} refused`;
});

// Sync state for the header, in one sentence. Reactive: `observe` re-runs as
// the outbox drains and as rejections come and go.
Tilia.observe(() => {
  let {pending, rejected}: status<card> = store.status
  header.sync =
    pending === 0 && rejected->Array.length === 0
      ? "up to date"
      : `${pending->Int.toString} waiting, ${rejected->Array.length->Int.toString} refused`
})->ignore

// A remote for `Store.custom`: the app's connectivity signal, one fetch per
// query, one push per batch. `push` answers each operation through the write
// channel — see WriteChannel for it in full.
const remote: Remote<Card, DeckQuery> = {
  online: network.online,
  fetch: (query, channel) =>
    api.get(`/decks/${query.deck}`).then(channel.fresh, (error: ApiError) => channel.fail(error.message)),
  push,
};

// A remote for `Store.custom`: the app's connectivity signal, one fetch per
// query, one push per batch. `push` answers each operation through the write
// channel — see Channel.write for it in full.
let remote: remote<deckQuery, card> = {
  online: network.online,
  fetch: (query, channel) =>
    Api.get(`/decks/${query.deck}`)
    ->Promise.thenResolve(result =>
      switch result {
      | Ok(cards) => channel.fresh(cards)
      | Error(message) => channel.fail(message)
      }
    )
    ->ignore,
  push,
}

// The two inbound facts, wired once at startup. On reconnect the server
// replays what was missed through the same two calls, and every open deck
// catches up without a refetch.
const receive: Receive<Card> = store.receive;
socket.on("cards:changed", receive.changed);
socket.on("cards:removed", receive.removed);

// The two inbound facts, wired once at startup. On reconnect the server
// replays what was missed through the same two calls, and every open deck
// catches up without a refetch.
let receive: receive<card> = store.receive
socket.on("cards:changed", receive.changed)
socket.on("cards:removed", receive.removed)

// A feature that edits takes the store handle; one that only displays takes
// the query object. The reviewer needs both verbs and nothing about reads.
const reviewer = (store: Store<Card>) => ({
  pass: (card: Card) => store.upsert({ ...card, seen: card.seen + 1 }),
  drop: (card: Card) => store.remove(card.id),
});

// A feature that edits takes the store handle; one that only displays takes
// the query object. The reviewer needs both verbs and nothing about reads.
let reviewer = (store: Store.t<card>) => {
  pass: card => store.upsert({...card, seen: card.seen + 1}),
  drop: card => store.remove(card.id),
}

// A live scoreboard that can afford it: refresh every 10 s while someone is
// looking, forget a deck a minute after the last look. Storage keeps its own
// clock, in StoreExpiry.
const expiry: Expiry = { refresh: 10_000, memory: 60_000 };

// A live scoreboard that can afford it: refresh every 10 s while someone is
// looking, forget a deck a minute after the last look. Storage keeps its own
// clock, in Store.expiry.
let expiry: expiry = {refresh: 10_000., memory: 60_000.}

// One fetch, two kinds of server. A server that answers when asked gets
// `fresh`, and the engine refreshes on its own clock. A server that streams
// gets `live`: the find stays open, `fail` reports a hiccup without closing
// it, `end` hands the query back to periodic refresh, and `finally` is where
// the stream is closed — on eviction, on a superseding fetch, on dispose.
const fetch = (query: DeckQuery, channel: ReadChannel<Card>) => {
  if (!server.live) {
    server.fetch(query).then(channel.fresh, (error: Error) => channel.fail(error.message));
    return;
  }
  const feed = server.subscribe(query, channel.live);
  feed.onError((error) => channel.fail(error.message));
  feed.onClose(channel.end);
  channel.finally(feed.close);
};

// One fetch, two kinds of server. A server that answers when asked gets
// `fresh`, and the engine refreshes on its own clock. A server that streams
// gets `live`: the find stays open, `fail` reports a hiccup without closing
// it, `end` hands the query back to periodic refresh, and `finally` is where
// the stream is closed — on eviction, on a superseding fetch, on dispose.
let fetch = (query, channel: Channel.read<card>) =>
  if !server.live {
    server.fetch(query)
    ->Promise.thenResolve(result =>
      switch result {
      | Ok(cards) => channel.fresh(cards)
      | Error(message) => channel.fail(message)
      }
    )
    ->ignore
  } else {
    let feed = server.subscribe(query, channel.live)
    feed.onError(message => channel.fail(message))
    feed.onClose(channel.end)
    channel.finally(feed.close)
  }

// `lookup` is asked about a deck the store has no record of. A keyspace with
// a deck index can hand back its rows and certify they are all of them:
// `local`. A scan could only say `partial`, and an empty partial is not an
// answer — the engine keeps waiting for the network.
const lookup = (query: DeckQuery, channel: LocalChannel<Card>) =>
  deckIndex.rows(query.deck).then(channel.local);

// `lookup` is asked about a deck the store has no record of. A keyspace with
// a deck index can hand back its rows and certify they are all of them:
// `local`. A scan could only say `partial`, and an empty partial is not an
// answer — the engine keeps waiting for the network.
let lookup = (query, channel: Channel.local<card>) =>
  DeckIndex.rows(query.deck)->Promise.thenResolve(channel.local)->ignore

// A custom source answers one find twice: storage first, so the deck shows at
// once, then the network. The engine keeps the stronger claim — a `local`
// that lands after `fresh` cannot pull the result back down.
const find = (query: DeckQuery, channel: ReadChannel<Card> & LocalChannel<Card>) => {
  storage.rows(query).then(channel.local);
  if (online.value) server.fetch(query).then(channel.fresh, (error: Error) => channel.fail(error.message));
};

// A custom source answers one find twice: storage first, so the deck shows at
// once, then the network. The engine keeps the stronger claim — a `local`
// that lands after `fresh` cannot pull the result back down.
let find = (query, channel: Channel.find<card>) => {
  storage.rows(query)->Promise.thenResolve(channel.local)->ignore
  if online.value {
    server.fetch(query)
    ->Promise.thenResolve(result =>
      switch result {
      | Ok(cards) => channel.fresh(cards)
      | Error(message) => channel.fail(message)
      }
    )
    ->ignore
  }
}

// One request per operation, in outbox order, each answered by name. A 409
// hands back the server's row: the write rebases through `merge` and goes
// again on a later tick. An outage says nothing about the writes and ends the
// push; whatever was not answered goes again later. Any other refusal is this
// one write's, and the next one is still sent.
const push = (ops: Op<Card>[], channel: WriteChannel<Card>) => {
  const next = async (index: number): Promise<void> => {
    const op = ops[index];
    if (!op) return;
    try {
      if (op.op === "remove") {
        await api.delete(`/cards/${op.id}`);
        channel.removed(op.id);
      } else {
        channel.set(await api.put(`/cards/${op.value.id}`, op.value));
      }
    } catch (e) {
      const error = e as ApiError;
      if (error.status === 409 && op.op === "upsert") channel.conflict(error.body);
      else if (error.status >= 500) return channel.retry();
      else channel.reject(op.op === "remove" ? op.id : op.value.id, error.message);
    }
    return next(index + 1);
  };
  void next(0);
};

// One request per operation, in outbox order, each answered by name. A
// conflict hands back the server's row: the write rebases through `merge` and
// goes again on a later tick. An outage says nothing about the writes and
// ends the push; whatever was not answered goes again later. Any other
// refusal is this one write's, and the next one is still sent.
let push = (ops, channel: Channel.write<card>) => {
  let rec next = index =>
    switch ops[index] {
    | None => ()
    | Some(Remove({id})) =>
      Api.delete(`/cards/${id}`)
      ->Promise.thenResolve(result =>
        switch result {
        | Ok() =>
          channel.removed(id)
          next(index + 1)
        | Error(Unavailable) => channel.retry()
        | Error(Refused(message)) =>
          channel.reject(id, message)
          next(index + 1)
        | Error(Stale(_)) =>
          channel.reject(id, "changed on the server")
          next(index + 1)
        }
      )
      ->ignore
    | Some(Upsert({value})) =>
      Api.put(`/cards/${value.id}`, value)
      ->Promise.thenResolve(result =>
        switch result {
        | Ok(saved) =>
          channel.set(saved)
          next(index + 1)
        | Error(Stale(theirs)) =>
          channel.conflict(theirs)
          next(index + 1)
        | Error(Unavailable) => channel.retry()
        | Error(Refused(message)) =>
          channel.reject(value.id, message)
          next(index + 1)
        }
      )
      ->ignore
    }
  next(0)
}

// A devtools line: what the UI is asking right now, and what is kept warm
// for a return visit until memory expiry evicts it.
const report = ({ live, idle }: Canopy) => `${live.length} observed, ${idle.length} kept warm`;

// A devtools line: what the UI is asking right now, and what is kept warm
// for a return visit until memory expiry evicts it.
let report = ({live, idle}: canopy) =>
  `${live->Array.length->Int.toString} observed, ${idle->Array.length->Int.toString} kept warm`

// The three required functions, then what the shipped store can do with more:
// durable rows, an index to answer decks it has no record of, a merge that
// keeps both sides' edits, and a shorter memory than the default month.
const config: StoreConfig<Card, DeckQuery> = {
  find,
  upsert,
  remove,
  persist: indexeddb({ name: "flashcards" }),
  lookup,
  merge,
  expiry: { local: 7 * 24 * 60 * 60_000 },
};

// The three required functions, then what the shipped store can do with more:
// durable rows, an index to answer decks it has no record of, a merge that
// keeps both sides' edits, and a shorter memory than the default month.
let config: Store.config<deckQuery, card> = {
  find,
  upsert,
  remove,
  persist: TiliaQueryIndexedDb.make({name: "flashcards"}),
  lookup,
  merge,
  expiry: {local: 604_800_000.},
}

// A find answers once: the complete deck as of now, or why not. The weaker
// claims are not offered here — what the store already holds is its own
// business, and it has answered from it before this call was made.
const find = (query: DeckQuery, answer: Answer<Card>) =>
  api.get(`/decks/${query.deck}`).then(answer.fresh, (error: ApiError) => answer.fail(error.message));

// A find answers once: the complete deck as of now, or why not. The weaker
// claims are not offered here — what the store already holds is its own
// business, and it has answered from it before this call was made.
let find = (query, answer: Store.answer<card>) =>
  Api.get(`/decks/${query.deck}`)
  ->Promise.thenResolve(result =>
    switch result {
    | Ok(cards) => answer.fresh(cards)
    | Error(message) => answer.fail(message)
    }
  )
  ->ignore

// What became of one write, in the backend's terms. A 409 carries the row the
// server holds: `conflict` keeps the write pending, so it rebases through
// `merge` and goes again. An outage is `transient`: nothing is said about the
// write, and the batch stops here. Anything else refuses this write alone.
const upsert = (card: Card, reply: (outcome: Outcome<Card>) => void) =>
  api.put(`/cards/${card.id}`, card).then(
    (saved) => reply({ outcome: "saved", value: saved }),
    (error: ApiError) => {
      if (error.status === 409) reply({ outcome: "conflict", value: error.body });
      else if (error.status >= 500) reply("transient");
      else reply({ outcome: "rejected", message: error.message });
    },
  );

// What became of one write, in the backend's terms. A conflict carries the row
// the server holds: `Conflict` keeps the write pending, so it rebases through
// `merge` and goes again. An outage is `Transient`: nothing is said about the
// write, and the batch stops here. Anything else refuses this write alone.
let upsert = (card, reply: Store.Outcome.t<card> => unit) =>
  Api.put(`/cards/${card.id}`, card)
  ->Promise.thenResolve(result =>
    switch result {
    | Ok(saved) => reply(Saved({value: saved}))
    | Error(Stale(theirs)) => reply(Conflict({value: theirs}))
    | Error(Unavailable) => reply(Transient)
    | Error(Refused(message)) => reply(Rejected({message: message}))
    }
  )
  ->ignore