4. Pravila koja build ne hvata
Poglavlje 4

Pravila koja build ne hvata

Kršenje ovih pravila obično prolazi npm run dev, pa i npm run build, a aplikacija pukne tek u potok-u. Svako pravilo ima primer koji ne radi, primer koji radi i razlog.

Pukne tek u potok-u

Dev mock i build nisu potok: u dev-u nema wrapper-a, iframe-a ni servera, a tsc proverava tipove, ne okruženje. Ova pravila pokrivaju upravo tu razliku.

4.1. Bez top-level await

Wrapper ubacuje bundle u običnu funkciju (poglavlje 3). await van async funkcije je tada sintaksna greška, i ceo skript se ne pokreće. U dev-u main.ts radi kao ES modul, gde je top-level await dozvoljen, a tsc i vite build ga takođe prihvataju.

// src/main.ts
const reply = await window.potok.listValues();
if (reply.ok) render(reply.values);
async function load() {
  const reply = await window.potok.listValues();
  if (!reply.ok) return console.error(reply.error);
  console.log(reply.values);
}

void load();

Jedini izuzetak je blok if (import.meta.env.DEV) na vrhu src/main.ts: on uvozi dev mock sa await import('./potok-dev'), a build ga izbacuje, pa u potok-build.html ne stigne.

4.2. Ceo JS u jednom fajlu

Objavljuje se samo potok-build.html. Dinamički import() pravi poseban chunk u dist/assets, koji dodatak ne ubacuje u fajl, pa ga u potok-u nema. Uvozi sve statički, na vrhu modula.

button.addEventListener('click', async () => {
  const { drawChart } = await import('./chart');   // chunk koji se ne objavljuje
  drawChart();
}, potok.eventListenerOptions);
import { drawChart } from './chart';

button.addEventListener('click', () => drawChart(), potok.eventListenerOptions);

4.3. Slike i fontovi inline ili sa apsolutnog URL-a

public/ i dist/assets se ne objavljuju. Vite sam ubacuje inline samo fajlove manje od 4 KB; veći ostaju u dist/assets, a u potok-u ih nema. U dev-u Vite servira sve, pa slika tamo radi.

<img src="/logo.png" alt="Logo">   <!-- iz public/: u potok-u ne postoji -->
<!-- SVG u HTML-u, data URL ili apsolutan URL -->
<svg viewBox="0 0 24 24" class="size-6"><path d="M4 12h16"/></svg>
<img src="data:image/png;base64,iVBORw0KGgo…" alt="Logo">
<img src="https://primer.rs/logo.png" alt="Logo">

4.4. potok se ne uvozi

U build-u potok daje wrapper kao lokalnu promenljivu, a u dev-u ga postavlja dev mock. src/potok.ts ima samo tipove i declare global, pa se iz njega uvoze samo tipovi, sa import type.

import { installDevPotok } from './potok-dev';   // dev mock bi ušao u build
installDevPotok();
import type { PotokValue } from './potok';

if (import.meta.env.DEV) {
  const { installDevPotok } = await import('./potok-dev');
  installDevPotok();
}

Statički uvoz ./potok-dev bi ugurao ceo dev mock (preko 3000 linija) u build. Uvoz u DEV bloku build izbacuje.

4.5. potok i window.potok su dva API-ja

potok je legacy (insertGroupValue, getGroupDataValues…), a window.potok noviji SDK (insertValue, listValues…). Dev mock postavlja potok kao jedan objekat sa oba API-ja ({ ...sdk, ...legacy }), a u potok-u su to dva objekta.

// radi u dev-u, u potok-u: TypeError: potok.insertValue is not a function
await (potok as any).insertValue({ done: true });
async function markDone() {
  const reply = await window.potok.insertValue({ done: true });
  if (!reply.ok) console.error(reply.error);
}

void markDone();

Tipovi poštuju podelu: PotokApi nema insertValue, pa potok.insertValue ne prolazi tsc. Greška u potok-u nastaje tek kad se tipovi zaobiđu (any, // @ts-ignore) ili kad se kod piše u čistom JS-u.

4.6. Slušaoci dobijaju potok.eventListenerOptions

Wrapper postavlja potok.eventListenerOptions = {signal: potok.abortController.signal}. Kad se aplikacija ponovo učita, abortController uklanja svakog slušaoca koji je dobio taj signal. Slušalac bez njega ostaje, pa posle ponovnog učitavanja isti događaj može da obradi dvaput.

document.addEventListener('keydown', onKey);
function onKey(event: KeyboardEvent) {
  if (event.key === 'Escape') console.log('close');
}

document.addEventListener('keydown', onKey, potok.eventListenerOptions);
window.addEventListener('resize', () => console.log('resize'), potok.eventListenerOptions);

Legacy potok uz to ima potok.el, sam element #group-panel-description u kome stoji tvoj HTML, i potok.abortController, čiji je signal u eventListenerOptions.

Slušaoci SDK-a (onNewValue, onValues, onPollChange…) vraćaju funkciju za odjavu; pozovi je kad ti slušalac više ne treba.

4.7. data je uvek JSON objekat

Server odbija niz, broj ili tekst greškom invalid_value. tsc to ne hvata: insertValue<T extends object> prima i niz, jer je niz u TypeScript-u objekat. Dev mock odbija isto što i server, pa se greška vidi već u npm run dev, ali samo ako proveriš reply.ok.

await window.potok.insertValue([1, 2, 3]);              // invalid_value
await potok.insertGroupValue(JSON.stringify('zdravo')); // invalid_value
async function save(scores: number[]) {
  const reply = await window.potok.insertValue({ scores });
  if (!reply.ok) console.error(reply.error);
}

void save([1, 2, 3]);

4.8. Vrednosti se uglavnom samo dodaju

Legacy potok nema izmenu ni brisanje. U window.potok autor menja svoju vrednost (updateValue) samo u kolekciji čije pravilo ima edit_own, a brišu samo urednici (deleteValue, deleteValues). Zato stanje računaj iz svih vrednosti: na primer poslednja vrednost po korisniku, kao u demou, ili zbir (poglavlje 5).

4.9. updateGroupDescription menja samu aplikaciju

Opis je HTML aplikacije. updateGroupDescription (i updateDescription u window.potok) ga zamenjuje, pa se aplikacija ponovo pokreće sa novim kodom. Menja samo opis te aplikacije, podrazumevani ili alternativni, i traži pravo na izmenu grupe. Ne koristi ga za čuvanje stanja: za to su vrednosti, kolekcije i lična memorija (poglavlje 8).

Dev mock

U dev mock-u updateGroupDescription samo zapamti opis, a aplikacija nastavlja da radi. U potok-u bi se ponovo učitala.

4.10. Proveri reply.ok

Pozivi koji vraćaju ok mogu da ne uspeju: gost, korisnik bez prava, limit upisa, zatvorena kolekcija. Dev mock je uvek admin i nema limita, pa grešku koja će se u potok-u desiti svakom članu u dev-u ne vidiš. Proveri if (!reply.ok) i pokaži poruku (reply.message ?? reply.error), kao demo.

4.11. Ostalo iz „Pravila i zamki“