5. Vrednosti
Poglavlje 5

Vrednosti

Data vrednosti su osnovni podaci aplikacije: svaki upis je nova vrednost sa JSON objektom, autorom i vremenom. Ovo poglavlje pokriva upis, čitanje (sve odjednom ili stranu po stranu), praćenje uživo, filtere i zbirove koje računa baza, i pokazuje kako se iz vrednosti računa stanje.

5.1. Šta je vrednost

Vrednost koju vraća upis i koju dobijaju slušaoci ima oblik PotokValue<T>:

PoljeZnačenje
idbroj vrednosti; noviji upis ima veći id
dataupisani JSON objekat, tipa T, ili null
content, content_format, is_datatekst vrednosti, njegov format ("markdown" ili "html") i oznaka da je to data vrednost
creator_id, creator_usernameko je upisao
group_id, parent_idgrupa i roditeljska vrednost
description_idaplikacija kojoj vrednost pripada: null za podrazumevani opis (poglavlje 7)

Vrednost iz liste (PotokListedValue<T>) ima i inserted_at i updated_at, kao ISO 8601 stringove. Vrednost koju vrate upis ili slušalac ih nema.

Oblik data zadaješ generikom: insertValue<Note>, listValues<Note>, PotokValue<Note>. Generik je samo obećanje TypeScript-u: server proverava samo da je data JSON objekat, pa vrednost drugog oblika (stara verzija aplikacije, ručni upis) i dalje može da stigne. Proveri polja pre upotrebe.

5.2. Upis

window.potok.insertValue(data, {contentFormat?})
data je objekat ili JSON string objekta. Vraća {ok: true, value}.
potok.insertGroupValue(json, {contentFormat?})
Legacy: json je JSON objekat kao string; sve što nije string šalje se kao "". Vraća {ok: true, value}.

contentFormat je "markdown" (podrazumevano) ili "html". Upis traži članstvo u grupi i troši limit upisa (poglavlje 6).

type Note = { text: string; done: boolean };

async function addNote(text: string) {
  const reply = await window.potok.insertValue<Note>({ text, done: false });
  if (!reply.ok) return console.error(reply.error);
  console.log('saved', reply.value.id, reply.value.data?.text);
}

async function addNoteLegacy(text: string) {
  const reply = await potok.insertGroupValue<Note>(JSON.stringify({ text, done: false }));
  if (!reply.ok) return console.error(reply.error);
  console.log('saved', reply.value.id);
}

void addNote('Kupiti mleko');
void addNoteLegacy('Platiti struju');
Pukne tek u potok-u

data je uvek JSON objekat. Niz, broj ili tekst server odbija sa invalid_value, a tsc niz propušta (poglavlje 4). Listu stavi u polje objekta: {items: [...]}.

5.3. Čitanje

potok.getGroupDataValues(options?)
Bez limit: {ok: true, values}, sve vrednosti, do 5000 (SDK ih čita u stranama od 200). Sa limit: jedna strana i has_more.
window.potok.listValues(options?)
Jedna strana: {ok: true, values, has_more, total}. Najviše 200 vrednosti po pozivu, podrazumevano 50. total je null osim uz total: true.

Bez orderBy vrednosti dolaze redom kojim su upisane, od najstarije (orderDir: "asc").

import type { PotokListedValue } from './potok';

type Note = { text: string; done: boolean };

async function loadAll(): Promise<PotokListedValue<Note>[]> {
  const all: PotokListedValue<Note>[] = [];
  let afterId: number | undefined;
  for (;;) {
    const reply = await window.potok.listValues<Note>({ limit: 200, afterId });
    if (!reply.ok) throw new Error(reply.error);
    all.push(...reply.values);
    if (!reply.has_more || reply.values.length === 0) return all;
    afterId = reply.values[reply.values.length - 1].id;
  }
}

void loadAll().then((notes) => console.log(notes.length));

5.4. Opcije listanja

Iste opcije primaju listValues i getGroupDataValues (bez limit i offset kad čita sve):

limit, offset
Veličina strane (najviše 200) i preskok. Uz kursor, offset se broji od kursora.
orderDir
"asc" (podrazumevano, od najstarije) ili "desc" (od najnovije).
afterId, beforeId
Strana odmah uz taj id, redom koji si tražio. beforeId daje vrednosti odmah pre njega, afterId one odmah posle, a oba one između. has_more kaže da li iza strane ima još, dalje od kursora: uz samo beforeId to su starije vrednosti.
match
Objekat; ostaju vrednosti čiji ga data sadrži ({status: "open"}). Poredi i JSON tip, pa {n: 5} ne nalazi "5", a {tags: ["a"]} nalazi svaku listu koja ima "a". Sve osim objekta do 4 KB (kao JSON) daje invalid_match.
Traži tekst u data[searchField], bez obzira na velika i mala slova; sužava zajedno sa match.
total: true
Dodaje total: koliko vrednosti filteri ostavljaju na svim stranama.
orderBy
Ključ u data po kome se sortira, u smeru orderDir; polje "number" se sortira numerički. Tada kursori samo sužavaju po id, a strane idu preko offset.
scope
Bez njega samo vrednosti ove aplikacije; "group" dodaje vrednosti ostalih aplikacija grupe koje gledalac sme da otvori (poglavlje 7).
type Task = { title: string; status: 'open' | 'done'; number: number };

async function openMilkTasks() {
  const reply = await window.potok.listValues<Task>({
    match: { status: 'open' },
    searchField: 'title',
    searchValue: 'mleko',
    orderBy: 'number',
    total: true,
  });
  if (!reply.ok) return console.error(reply.error);
  console.log(reply.total, reply.values.map((v) => v.data?.title));
}

async function newestTwenty() {
  const reply = await window.potok.listValues({ orderDir: 'desc', limit: 20 });
  if (!reply.ok) return console.error(reply.error);
  console.log(reply.values.map((v) => v.inserted_at));
}

void openMilkTasks();
void newestTwenty();

5.5. Uživo

window.potok.onNewValue(listener, {scope?})
Svaka nova vrednost ove aplikacije, i gledaočeva sopstvena; uz {scope: "group"} i vrednosti ostalih aplikacija grupe. Može više slušalaca; vraća funkciju za odjavu.
potok.setNewValueCallback(fn)
Legacy: fn dobija CustomEvent (phx:new_data_value) sa novom vrednošću u detail. Postoji samo jedan callback: novi zamenjuje stari.
type Note = { text: string; done: boolean };

const stop = window.potok.onNewValue<Note>((value) => {
  console.log(value.creator_username, value.data?.text);
});

potok.setNewValueCallback<Note>((event) => console.log(event.detail.id));

// later, when the list is no longer on screen
stop();

5.6. Demo korak po korak

Demo iz šablona je mali, ali pokazuje obrazac koji ponavlja gotovo svaka aplikacija. Svaki klik je vrednost {x, y, picture}, a avatar svakog člana stoji tamo gde je poslednji put kliknuo.

  1. Prvo pretplata, pa čitanje. load() postavlja setNewValueCallback pre getGroupDataValues, da se ne izgubi klik upisan dok se lista učitava.
  2. Lista i callback se preklapaju. Ista vrednost može da stigne dvaput, a starija posle novije. placeAvatar pamti id poslednjeg klika svakog člana i preskače svaki stariji: if (known && known.id >= value.id) return;
  3. Upis bez crtanja. Klik zove insertGroupValue(JSON.stringify(click)); avatar se pomera tek kad vrednost stigne kroz callback. Slušalac klika dobija potok.eventListenerOptions.
  4. Greška se pokazuje. showError ispisuje reply.message ?? reply.error.
function placeAvatar(value: PotokValue<Click>) {
  if (!value.data) return;

  // The list and the callback can overlap; an older click must not win.
  const known = avatars.get(value.creator_id);
  if (known && known.id >= value.id) return;
  // …
}

async function load() {
  // Subscribe first so that no click is missed while the list loads.
  potok.setNewValueCallback<Click>((event) => placeAvatar(event.detail));

  const reply = await potok.getGroupDataValues<Click>();
  if (!reply.ok) {
    showError(reply);
    return;
  }

  reply.values.forEach(placeAvatar);
}

5.7. Stanje se računa iz vrednosti

Legacy potok nema izmenu ni brisanje, a i u window.potok autor menja svoju vrednost samo u kolekciji sa edit_own. Zato stanje ne čuvaš u jednoj vrednosti koju menjaš, nego ga računaš iz svih. Tri česta obrasca:

Poslednja vrednost po korisniku
Glas, status, položaj: važi najnovija vrednost svakog člana. Tako radi demo.
Zbir ili brojanje
Troškovi, bodovi, prijave. Za velike skupove zbir računa baza (aggregateValues, odeljak 5.8).
Niz događaja
Svaka vrednost je događaj sa poljem type (add, done, move…), a stanje nastaje primenom svih događaja redom po id-ju.
import type { PotokValue } from './potok';

type Vote = { choice: string };

// The latest vote of each member counts: a higher id is a newer value.
function tally(values: PotokValue<Vote>[]): Map<string, number> {
  const latest = new Map<number, PotokValue<Vote>>();
  for (const value of values) {
    const known = latest.get(value.creator_id);
    if (!known || known.id < value.id) latest.set(value.creator_id, value);
  }

  const counts = new Map<string, number>();
  for (const value of latest.values()) {
    if (!value.data) continue;
    counts.set(value.data.choice, (counts.get(value.data.choice) ?? 0) + 1);
  }
  return counts;
}

console.log(tally([]));
import type { PotokValue } from './potok';

type Event =
  | { type: 'add'; key: string; title: string }
  | { type: 'done'; key: string };

type Card = { title: string; done: boolean };

function replay(values: PotokValue<Event>[]): Map<string, Card> {
  const cards = new Map<string, Card>();
  for (const value of [...values].sort((a, b) => a.id - b.id)) {
    const event = value.data;
    if (!event) continue;
    if (event.type === 'add') cards.set(event.key, { title: event.title, done: false });
    if (event.type === 'done') {
      const card = cards.get(event.key);
      if (card) card.done = true;
    }
  }
  return cards;
}

console.log(replay([]).size);
Napomena

Kad događaj menja stavku, stavci treba ključ koji aplikacija sama pravi pri prvom upisu (key u primeru, npr. crypto.randomUUID()): id vrednosti postoji tek kad server odgovori, a događaj „dodaj“ i događaj „završi“ su dve različite vrednosti.

5.8. Zbirovi koje računa baza

window.potok.aggregateValues(options?) vraća {ok: true, total, fields, buckets, other}: zbir, prosek, najmanji i najveći broj, izračunate u bazi, nad istim vrednostima koje bi listValues listao sa istim filterima. Aplikacija ne mora da čita sve vrednosti da bi dobila zbir.

fields
Do 5 ključeva. Za svaki, fields[ključ] je {count, sum, avg, min, max} nad vrednostima koje tu imaju broj: JSON broj ili string koji je običan decimalni broj ("12", "-3.5", ali ne "1,5" ni "1e3"), do 61 znak. count kaže koliko ih je bilo; bez nijednog, sum je 0, a ostalo null.
under
Putanja od najviše 3 ključa do objekta u kome se ključevi čitaju (["a"]); podrazumevano vrh data.
groupBy
Ključ. Tada je buckets lista [{value, count, fields}] po vrednosti tog ključa, prvo 50 najvećih, a other je {buckets, count} za ostale. String, broj ili boolean je grupa, kao tekst do 200 znakova; vrednosti bez ključa su grupa null. Bez groupBy su buckets i other null.
match, searchField/searchValue, scope, collection
Isti filteri kao kod listanja. collection radi za one koji čitaju celu kolekciju i čita na under iz njenog pravila (poglavlje 9).
async function totals() {
  const reply = await window.potok.aggregateValues({ fields: ['amount'], groupBy: 'who' });
  if (!reply.ok) return console.error(reply.error);

  console.log('ukupno', reply.fields.amount.sum, 'u', reply.total, 'vrednosti');
  for (const bucket of reply.buckets ?? []) {
    console.log(bucket.value ?? '(bez imena)', bucket.count, bucket.fields.amount.sum);
  }
}

void totals();
Važno

Ključevi imaju od 1 do 64 bajta; sve ostalo daje invalid_aggregate. Poziv traje najviše 5 s (timeout), a zajedno sa summarizeValues ulazi u limit od 120 poziva u minuti po gledaocu (rate_limited), jer svaki čita sve vrednosti koje filteri ostavljaju.