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>:
| Polje | Značenje |
|---|---|
id | broj vrednosti; noviji upis ima veći id |
data | upisani JSON objekat, tipa T, ili null |
content, content_format, is_data | tekst vrednosti, njegov format ("markdown" ili "html") i oznaka da je to data vrednost |
creator_id, creator_username | ko je upisao |
group_id, parent_id | grupa i roditeljska vrednost |
description_id | aplikacija 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?})dataje objekat ili JSON string objekta. Vraća{ok: true, value}.potok.insertGroupValue(json, {contentFormat?})- Legacy:
jsonje 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');
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). Salimit: jedna strana ihas_more. window.potok.listValues(options?)- Jedna strana:
{ok: true, values, has_more, total}. Najviše 200 vrednosti po pozivu, podrazumevano 50.totaljenullosim uztotal: 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,
offsetse broji od kursora. orderDir"asc"(podrazumevano, od najstarije) ili"desc"(od najnovije).afterId,beforeId- Strana odmah uz taj
id, redom koji si tražio.beforeIddaje vrednosti odmah pre njega,afterIdone odmah posle, a oba one između.has_morekaže da li iza strane ima još, dalje od kursora: uz samobeforeIdto su starije vrednosti. match- Objekat; ostaju vrednosti čiji ga
datasadrž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) dajeinvalid_match. searchField,searchValue- Traži tekst u
data[searchField], bez obzira na velika i mala slova; sužava zajedno samatch. total: true- Dodaje
total: koliko vrednosti filteri ostavljaju na svim stranama. orderBy- Ključ u
datapo kome se sortira, u smeruorderDir; polje"number"se sortira numerički. Tada kursori samo sužavaju poid, a strane idu prekooffset. 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:
fndobijaCustomEvent(phx:new_data_value) sa novom vrednošću udetail. 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();
- Pošiljalac dobija i svoju vrednost. Zato demo ne crta avatar posle upisa, nego kad vrednost stigne kroz callback, kao svakom drugom članu.
- Nove vrednosti stižu samo dok je opis na ekranu. Posle prekida veze aplikacija se ponovo učitava, jer vrednosti poslate dok veze nije bilo ne stižu.
- Vrednosti kolekcija nikad ne stižu kroz
onNewValue; za njih postojionValues(poglavlje 9).
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.
- Prvo pretplata, pa čitanje.
load()postavljasetNewValueCallbackpregetGroupDataValues, da se ne izgubi klik upisan dok se lista učitava. - Lista i callback se preklapaju. Ista vrednost može da stigne dvaput, a starija posle novije.
placeAvatarpamtiidposlednjeg klika svakog člana i preskače svaki stariji:if (known && known.id >= value.id) return; - Upis bez crtanja. Klik zove
insertGroupValue(JSON.stringify(click)); avatar se pomera tek kad vrednost stigne kroz callback. Slušalac klika dobijapotok.eventListenerOptions. - Greška se pokazuje.
showErrorispisujereply.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 poid-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);
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.countkaže koliko ih je bilo; bez nijednog,sumje 0, a ostalonull. under- Putanja od najviše 3 ključa do objekta u kome se ključevi čitaju (
["a"]); podrazumevano vrhdata. groupBy- Ključ. Tada je
bucketslista[{value, count, fields}]po vrednosti tog ključa, prvo 50 najvećih, aotherje{buckets, count}za ostale. String, broj ili boolean je grupa, kao tekst do 200 znakova; vrednosti bez ključa su grupanull. BezgroupBysubucketsiothernull. match,searchField/searchValue,scope,collection- Isti filteri kao kod listanja.
collectionradi za one koji čitaju celu kolekciju i čita naunderiz 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();
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.