9. Kolekcije i pravila
Poglavlje 9

Kolekcije i pravila

Obične vrednosti aplikacije čitaju svi članovi. Kad aplikaciji treba više (anketa u kojoj svako vidi samo svoj odgovor, prijava sa fajlovima, kviz sa bodovima), vrednosti stoje u kolekcijama, pod pravilima koja potok drži pri svakom pozivu.

9.1. Šta je kolekcija

Kolekcija je imenovan skup vrednosti aplikacije. Pravila za nju urednici aplikacije pišu u njenu konfiguraciju: ko piše, ko čita sve, a ko samo svoje. Vrednosti kolekcija dolaze samo kroz pozive koji imenuju kolekciju ({collection: "…"}), nikad kroz onNewValue.

9.2. Konfiguracija

window.potok.getConfig()
Konfiguracija i, po svakoj kolekciji sa pravilom, šta gledalac sme tu. Odgovor:
  • config: {id, revision, data, updated_at} ili null dok je niko nije sačuvao;
  • caps: šta gledalac sme, po kolekciji (odeljak 9.4);
  • manage: gledalac uređuje aplikaciju; can_create_groups: sme i da napravi njene grupe za fajlove;
  • files: za urednike, stanje grupa za fajlove ("ok", "missing", "exposed");
  • process_warnings: za urednike, šta fali procesima (poglavlje 10);
  • visible_role_keys: uloge na koje je opis ograničen, [] za sve;
  • viewer: {signed_in, member, profile_id, username}.
window.potok.saveConfig(data, {revision})
Za urednike. Pošalji revision od koje si krenuo (0 za prvo čuvanje). Ako je neko drugi sačuvao u međuvremenu, odgovor je conflict sa current, onim što je sada tamo. Pravila koja ne mogu da važe daju invalid_rules sa reason.

data konfiguracije drži ono što aplikacija hoće (naslov, rok, izgled), a potok iz njega čita tri dela:

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

async function setupSurvey() {
  const current = await window.potok.getConfig();
  if (!current.ok) return console.error(current.error);
  if (!current.manage) return;   // only the app's editors save the config

  const data: PotokConfigData = {
    ...(current.config?.data ?? {}),
    title: 'Anketa o parku',
    rules: { answers: { write: ['everyone'], read: [], once: true } },
  };
  const reply = await window.potok.saveConfig(data, { revision: current.config?.revision ?? 0 });
  if (!reply.ok && reply.error === 'conflict') console.warn('someone saved first', reply.current);
  else if (!reply.ok) console.error(reply.error, reply.reason);
}

void setupSurvey();

9.3. Pravilo

Pravilo imenuje ključeve uloga: "everyone", "admin" ili UUID posebne uloge. Spisak uloga grupe daje listRoles(): {ok: true, roles: [{key, name, builtin}]}.

write
Ko dodaje vrednosti.
read
Ko čita sve vrednosti; svi ostali čitaju samo svoje.
summary
Ko vidi samo brojeve (summarizeValues), bez pojedinačnih vrednosti.
once
Jedna vrednost po osobi; druga daje already_answered.
edit_own
Autori smeju da menjaju svoju vrednost (updateValue).
anonymous
Vrednost napisana dok je kolekcija anonimna nikome osim autora ne pokazuje autora: creator_id i creator_username su null, a anonymous je true.
public
Prijavljeni nečlanovi javne grupe pišu i čitaju svoje.
open, closes_at
open: false ili prošao closes_at (ISO 8601 sa zonom): kolekcija više ne prima vrednosti (closed).
under
Putanja do mape odgovora u svakoj vrednosti (["a"]); iz nje čitaju fajlovi, kviz i zbirovi.
uploads
Mesta za fajlove (odeljak 9.7).
score
Kolekcija je kviz (odeljak 9.8).
process
Proces za svaku novu vrednost (poglavlje 10).

once važi po nalogu, bez obzira na profil. public postavlja write na ["everyone"]. Anonimna kolekcija ne prima fajlove, jer fajl čuva pošiljaoca.

9.4. Šta gledalac sme: caps

caps iz getConfig kaže, po kolekciji, šta gledalac sme, pa aplikacija može da prikaže formu samo onome ko sme da piše.

PoljeZnačenje
write, write_blocksme da piše; ako ne sme, zašto: "closed", "role", "blocked", "members_only", "not_permitted"
read"all" ili "own"
summarysme da vidi zbirove
edit_own, managemenja svoje; uređuje kolekciju
ruled, open, once, anonymous, public, releasedosobine pravila: postoji li, je li otvoreno, jedan odgovor, anonimno, javno, objavljeni bodovi
writtengledalac već ima vrednost tu
notifygledalac dobija obaveštenje za svaku novu vrednost
async function showForm(form: HTMLFormElement) {
  const reply = await window.potok.getConfig();
  if (!reply.ok) return console.error(reply.error);

  const caps = reply.caps['answers'];
  form.hidden = !caps?.write || (caps.once && caps.written);
  if (caps?.write_block === 'closed') console.log('Anketa je zatvorena.');
}

const form = document.querySelector<HTMLFormElement>('.app-form');
if (form) void showForm(form);

9.5. Upis i čitanje

insertValue(data, {collection})
Upis u kolekciju, kako pravilo dozvoljava. Vraća {ok: true, value}, gde je value PotokCollectionValue: obična vrednost plus collection, anonymous, revision i managed (ocena kviza).
listValues({collection, limit, offset, afterId, beforeId, orderDir, mine, total, match})
Strana kolekcije, po id-ju, najviše 100: sve vrednosti za one koji čitaju sve, inače samo gledaočeve. mine: true ostavlja samo gledaočeve; match rade samo oni koji čitaju sve.
type Answer = { a: { park: string; comment: string } };

async function answer(park: string, comment: string) {
  const reply = await window.potok.insertValue<Answer>({ a: { park, comment } }, { collection: 'answers' });
  if (!reply.ok) return console.error(reply.message ?? reply.error);
  console.log('revision', reply.value.revision, 'anonymous', reply.value.anonymous);
}

async function myAnswers() {
  const reply = await window.potok.listValues<Answer>({ collection: 'answers', mine: true, total: true });
  if (!reply.ok) return console.error(reply.error);
  console.log(reply.total, reply.values.map((v) => v.data?.a.park));
}

void answer('Dunavski park', 'Više klupa');
void myAnswers();

9.6. Izmena, brisanje i promene uživo

updateValue(id, data, {revision?})
Menja gledaočevu vrednost, gde pravilo daje edit_own. Pošalji revision vrednosti koju menjaš: ako se ona u međuvremenu promenila, odgovor je conflict sa current. Posle objave bodova kviza vrednost se više ne menja (released).
deleteValue(id), deleteValues(collection)
Za urednike: jedna vrednost, odnosno cela kolekcija, zajedno sa fajlovima.
onValues(listener, {collection?})
Promene u kolekcijama aplikacije koje gledalac sme da vidi; vraća funkciju za odjavu. Događaji su:
  • created, updated: {event, collection, value};
  • deleted: {event, collection, id};
  • cleared: cela kolekcija obrisana (collection: null za sve podatke aplikacije);
  • regraded: bodovi kviza ponovo izračunati;
  • config: konfiguracija je promenjena; pročitaj je ponovo;
  • process: instanca procesa se pomerila (poglavlje 10).
type Answer = { a: { park: string } };

const answers = new Map<number, Answer>();

const stop = window.potok.onValues<Answer>((change) => {
  if (change.event === 'created' || change.event === 'updated') {
    if (change.value.data) answers.set(change.value.id, change.value.data);
  } else if (change.event === 'deleted') {
    answers.delete(change.id);
  } else if (change.event === 'cleared') {
    answers.clear();
  }
  console.log(answers.size);
}, { collection: 'answers' });

window.addEventListener('pagehide', stop, potok.eventListenerOptions);

9.7. Fajlovi

Kolekcija prima fajlove samo na mestima (uploads) koja pravilo navodi. Svako mesto ima target ("private" ili "public": privatna ili javna grupa za fajlove aplikacije), i po želji max_files, max_bytes i types (document, presentation, spreadsheet, drawing, pdf, image, video, audio).

  1. Urednik jednom pozove ensureFileGroups(): pravi grupe „Files“ i „Private files“ ako ne postoje i upisuje ih u files konfiguracije. Bez konfiguracije poziv vraća no_config.
  2. Aplikacija šalje fajl sa uploadFile(file, {collection, slot, onProgress}); poziv čeka koliko traje slanje i vraća {ok: true, file: {file, name, size, type}}.
  3. Vrednost navodi fajl pod svojim mestom (u mapi odgovora, under): {file: <id>, …}.
  4. Za prikaz, fileUrl(id) daje adresu koja važi deset minuta: {ok: true, url, name, type, size}.
async function attach(input: HTMLInputElement) {
  const file = input.files?.[0];
  if (!file) return;

  const sent = await window.potok.uploadFile(file, {
    collection: 'applications',
    slot: 'cv',
    onProgress: (percent) => console.log(`${percent}%`),
  });
  if (!sent.ok) return console.error(sent.message ?? sent.error);

  const saved = await window.potok.insertValue(
    { a: { name: 'Ana', cv: [{ file: sent.file.file, name: sent.file.name }] } },
    { collection: 'applications' },
  );
  if (!saved.ok) console.error(saved.message ?? saved.error);
}

const input = document.querySelector<HTMLInputElement>('.app-cv');
input?.addEventListener('change', () => void attach(input), potok.eventListenerOptions);

9.8. Kvizovi

Pravilo sa score čini kolekciju kvizom: potok svaku vrednost boduje po ključu iz secret.score i u vrednost upisuje managed.

Ključ: secret.score[kolekcija][pitanje]
Za svako pitanje {points, …} sa jednom proverom: eq (jedan izbor), set (tačno ti izbori), text (bilo koji od tih tekstova; uz others_wrong ostali su netačni, inače čekaju urednika), rows i row_sets (tabele), manual (boduje urednik). Opciono ok i bad: poruke za tačan i netačan odgovor.
score.release, score.released, score.show
"immediate" ili "manual"; released: true objavljuje bodove; show bira šta autor vidi (missed, correct, points).
managed
Ocena vrednosti, koliko je gledalac sme da vidi: score, max, pending (odgovori koji čekaju urednika) i items po pitanju (ok, points, graded, feedback, expected).
gradeValue(id, items)
Bodovi i reči urednika: {pitanje: {points, feedback}}; points: null vraća odgovor ključu.
summarizeValues(collection, {under?, keys?, score?})
Brojevi nad odgovorima: {ok: true, summary: {total, keys, score}}. Za svaki ključ koliko je odgovorilo i najveće grupe odgovora; score: true dodaje prosek, medijanu, raspodelu i rezultate po pitanju. Kolekcija bez kviza daje not_scored, a bez under invalid_summary.
import type { PotokConfigData } from './potok';

const quiz: PotokConfigData = {
  rules: {
    quiz: { write: ['everyone'], once: true, under: ['a'], score: { release: 'immediate', show: { correct: true, points: true } } },
  },
  secret: { score: { quiz: { q1: { points: 2, eq: 'o3', ok: 'Tačno!', bad: 'Pogledaj poglavlje 3.' } } } },
};

async function results() {
  const reply = await window.potok.summarizeValues('quiz', { keys: ['q1'], score: true });
  if (!reply.ok) return console.error(reply.error);
  console.log(reply.summary.total, reply.summary.score?.average);
}

console.log(Object.keys(quiz.rules ?? {}));
void results();

Nov ključ ponovo boduje sve, a ocene urednika ostaju. "immediate" ne ide uz edit_own, i posle objave niko ne menja vrednost.

9.9. Obaveštenja

setNotifications(collection, on) uključuje ili isključuje gledaočevo obaveštenje (push) za svaku novu vrednost kolekcije; vraća {ok: true, on}. Stanje se vidi u caps[kolekcija].notify.

Obaveštenje dobija samo onaj ko čita celu kolekciju, samo za nove vrednosti (ne za izmene), nikad autor, i bez imena kad je kolekcija anonimna.

9.10. Greške i granice

KodKada
closedpravilo više ne prima vrednosti (zatvoreno ili posle roka)
already_answeredonce: osoba već ima vrednost
releasedbodovi su objavljeni, vrednost se više ne menja
conflictneko je sačuvao u međuvremenu; current je ono što je sada tamo
too_largevrednost preko 64 KB ili konfiguracija preko 512 KB kao JSON
invalid_collectionloše ili rezervisano ime kolekcije
invalid_rulespravila koja ne mogu da važe; reason kaže koje
invalid_files, files_missing, files_exposedfajlovi (odeljak 9.7)
no_configpoziv traži konfiguraciju, a nje nema
not_scored, invalid_summaryzbirovi kviza (odeljak 9.8)

Strana kolekcije ima najviše 100 vrednosti; vrednost najviše 64 KB, a konfiguracija 512 KB kao JSON.

Dev mock

Dev mock drži pravila kao server, za gledaoca koga glumi ?viewer=: editor (podrazumevano, admin), reader (uloga „pregled“), member (uloga „ispitanik“), outsider (prijavljen, nije član) ili guest. Konfiguracija svake aplikacije je u potok-dev:config, uključena obaveštenja u potok-dev:notify, a fajlovi poslati iz okvira žive do osvežavanja.

Aplikacija Forma u potok-u (šablon „Forma“) napravljena je na kolekcijama: pitanja, prava, fajlovi, kviz i proces za svaki odgovor. Njen opis u dokumentaciji potok-ide je dobar primer celine.