# Népszerű csomagok

A specifikációnak való megfelelés nem garantálja, hogy a valódi könyvtárak működnek. Azok a JS-motorok, amelyek a test262 tesztjeinek 99 %-át teljesítik, gyakran mégis elbuknak éles kóddal, mert a könyvtárak a „specifikáció sarkos eseteinek” hosszú sorára támaszkodnak — például a Proxy-csapdák meghatározott sorrendjére, a `Function.prototype.toString` alakjára, a regex viselkedésére trükkös bemeneteknél, illetve arra, hogy a `Object.keys` sorrendje pontosan hogyan működik együtt a számított tulajdonságnevekkel.

A Phasis byte-ról byte-ra ellenőrzi a **204 széles körben használt könyvtárat** a Node.js-hez (V8) viszonyítva. A tároló `tests/Popular/` könyvtárában találhatók, és a CI minden alkalommal lefuttatja őket, amikor változik a motor forráskódja vagy a tesztcsomag.

## Lefedettség kategóriánként

| Kategória | Könyvtárak |
|---|---|
| **Elemzők / AST** | acorn 8.16.0, chevrotain 11.0.3, parse5 7.2.1, parsimmon 1.18.1, jsep 1.4.0, postcss-value-parser 4.2.0, acorn-walk 8.3.4, estraverse 5.3.0, escodegen 2.1.0, css-tree 3.0.4, sax 1.4.1, nearley 2.20.1 |
| **Sablonkezelés / Markdown / HTML** | mustache 4.2.0, handlebars 4.7.9, marked 18.0.3, markdown-it 14.1.0 (+ markdown-it-emoji), markdown-table 3.0.4, showdown 2.1.0, cheerio 1.1.2, htmlparser2 11.0.0 |
| **Segédeszközök / funkcionális** | lodash 4.18.1, ramda 0.31.3, remeda 2.17.4, es-toolkit 1.27.0, immutable 5.1.3, immer 10.1.1, redux 5.0.1, deepmerge 4.3.1, dot-object 2.1.5, lodash.merge 4.6.2, lodash.clonedeep 4.5.0, extend 3.0.2, extend-shallow 3.0.2, mixin-deep 2.0.1, merge-options 3.0.4 |
| **Objektumelérés** | dequal 2.0.3, clsx 2.1.1, classnames 2.5.1, get-value 4.0.1, set-value 4.1.0, object.omit 3.0.0, object.pick 1.3.0, is-plain-obj 4.1.0, kind-of 6.0.3 |
| **Érvényesítés / séma** | zod 4.4.3, yup 1.4.0, valibot 1.1.0, superstruct 2.0.2, validator 13.12.0, email-validator 2.0.4, ajv 8.17.1, @sinclair/typebox 0.34.42, runtypes 6.7.0, typanion 3.14.0, ow 2.0.0 |
| **Dátum / idő** | dayjs 1.11.20, date-fns 4.1.0, timeago.js 4.0.2, luxon 3.7.3, moment 2.30.2 |
| **Matematika / számok** | bignumber.js 11.1.1, decimal.js 10.6.0, numeral 2.0.6, jsbi 4.3.0, big.js 6.2.2, fraction.js 4.3.7, complex.js 2.4.2, simple-statistics 7.8.8 |
| **Hashelés / kriptográfia** | blueimp-md5 2.19.0, crypto-js 4.2.0, fnv-plus 1.3.1, murmurhash3js 3.0.1, hash-sum 2.0.0, jwt-decode 4.0.0, @noble/hashes 2.2.0, tweetnacl 1.0.3, aes-js 3.1.2, bcryptjs 3.0.2, xxhashjs 0.2.2, object-hash 3.0.0 |
| **Keresés / diff** | fuse.js 7.3.0, minisearch 7.1.1, diff 8.0.2, diff-match-patch 1.0.5, fast-deep-equal 3.1.3, fast-equals 5.2.2, fastest-levenshtein 1.0.16, lunr 2.3.9 |
| **JSON / adatformátumok** | json5 2.2.3, js-yaml 4.1.0, yaml 2.6.1, toml 3.0.0, smol-toml 1.3.1, fast-json-patch 3.1.1, jmespath 0.16.0, jsonata 2.0.6, jsonpath-plus 10.3.0, mingo 6.7.0, sift 17.1.3, fast-json-stable-stringify 2.1.0, safe-stable-stringify 2.5.0, json-stringify-safe 5.0.1, canonicalize 2.1.0, papaparse 5.5.4 |
| **Karakterláncok / nyelvészet** | he 1.2.0, slugify 1.6.9, camelcase 8.0.0, entities 6.0.1, pluralize 8.0.0, inflection 3.0.2, wcwidth 1.0.1, emoji-regex 10.4.0, unraw 3.0.0, jsesc 3.1.0, lower-case 2.0.2, upper-case 2.0.2, dot-case 3.0.4, pascal-case 3.1.2, snake-case 3.0.4, title-case 3.0.3, xregexp 5.1.1, escape-string-regexp 5.0.0, ansi-regex 6.1.0, strip-ansi 7.1.2, string-width 8.1.0 |
| **URL / web** | url-parse 1.5.10, qs 6.13.1, query-string 9.1.1, tldts 6.1.69, punycode 2.3.1, linkifyjs 4.3.1, ipaddr.js 2.2.0, uri-js 4.4.1, url-template 3.1.1, bowser 2.11.0 |
| **Tömörítés / kódolás / archívum** | pako 2.1.0, lz-string 1.5.0, base64-js 1.5.1, JSZip 3.10.1 |
| **Színek** | color-string 2.1.1, d3-color 3.1.0, chroma-js 3.1.2, color-name 2.0.0, tinycolor2 1.6.0, color 5.0.3 |
| **Klónozás / egyenlőség** | rfdc 1.4.1, klona 2.0.6, fast-copy 3.0.2 |
| **Formázás / megjelenítés** | ms 2.1.3, bytes 3.1.2 |
| **Azonosítók / UUID-k** | uuid 10.0.0, hexoid 2.0.0, ulid 3.0.1, cuid2 2.2.2, short-unique-id 5.4.3 |
| **Típusfelismerés / glob** | type-detect 4.1.0, picomatch 4.0.2, minimatch 10.1.1, wildcard-match 5.1.4, glob-to-regexp 0.4.1, to-regex 4.0.4, array-uniq 3.0.0, array-unique 0.3.2 |
| **Semver / konfiguráció** | semver 7.6.3, compare-versions 6.1.1, semver-compare 1.0.0 |
| **Gyorsítótárak / teljesítmény** | lru-cache 11.0.2, marky 1.3.0, array-flatten 3.0.0, arr-diff 4.0.0 |
| **Aszinkron műveletek / események** | eventemitter3 5.0.1, eventemitter2 6.4.10, mitt 3.0.1, p-limit 7.1.1, p-queue 9.0.2, p-defer 5.0.0, p-retry 7.1.0, throttle-debounce 5.0.2, async 3.2.6 |
| **Reaktív állapot** | mobx 6.13.7, xstate 5.23.0, valtio 2.1.5, nanostores 1.0.1, jotai 2.16.1, redux-saga 1.3.0, redux 5.0.1 |
| **CSS / stíluskezelés** | postcss 8.5.7, stylis 4.3.6, css-tree 3.0.4 |
| **Összeállítás / AST / fordítók** | magic-string 0.30.20, escodegen 2.1.0, acorn-walk 8.3.4, estraverse 5.3.0, @babel/parser 7.28.5, terser 5.46.0, prettier 3.3.3, svelte 5.55.7 (fordító), typescript 6.0.3 |
| **MQTT / protokoll** | mqtt-packet 9.0.4 |
| **GraphQL** | graphql-js 16.11.0 |
| **Szintaxiskiemelés** | highlight.js 11.11.1 |
| **Tesztelés / állítások** | chai 6.2.1 |

Összesen: **204 könyvtár**, mindegyik a Node pontos kimenetét állítja elő. Mindegyik a legutóbbi frissítéskor elérhető legújabb upstream kiadáshoz van rögzítve.

## Működés

Minden forgatókönyv egy `tests/Popular/<lib>/` könyvtár, benne három fájllal:

```text
tests/Popular/lodash/
├── lodash.js     ← vendored upstream library (untouched, UMD bundle)
├── runner.js     ← Phasis-side script that exercises the library
└── oracle.txt    ← Node.js output of running runner.js (committed)
```

A `tests/Popular/PopularPackagesTest.php` egy PHPUnit adatforrásos teszt, amely:

1. Betölti a `lodash.js` és a `runner.js` elemet egy új `new Phasis\Engine()`-be.
2. Pufferbe rögzíti a `console.log` kimenetét.
3. Ellenőrzi, hogy a rögzített puffer bájtról bájtra megegyezik-e a `oracle.txt`-gyel.

Referenciakimenet újragenerálása ezzel:

```bash
node tests/Popular/gen-oracle.js tests/Popular/<lib>
```

(Akkor használja, amikor frissíti a vendorizált könyvtárat — a futtatót valódi Node alatt futtatja újra, és felülírja a `oracle.txt`-t.)

## CI-ellenőrzés

Munkafolyamat: [`.github/workflows/popular.yml`](https://github.com/inline0/phasis/blob/main/.github/workflows/popular.yml).

Lefut a `main`-ra irányuló pushoknál és pull requesteknél, amelyek módosítják a `src/`, a `tests/Popular/`, a `phpunit.xml.dist`, a Composer fájljait vagy magát a munkafolyamatot, valamint kézi indításkor. Két lépésből áll:

1. **Phasis oldala** — lefuttatja a PHPUnit `popular` tesztcsomagot, amely minden könyvtárat a Phasis segítségével futtat, majd összehasonlítja az eredményt a beküldött referenciakimenettel. Már egyetlen eltérő bájt esetén is hibát jelez.
2. **Node-újraellenőrzés** — minden könyvtáron lefuttatja a `node tests/Popular/gen-oracle.js …`-t, és ellenőrzi, hogy az újonnan előállított referencia megegyezik-e a tárolóban lévővel. Felismeri az „újabb vendorizált könyvtárhoz nem frissítették a referenciát” jellegű eltéréseket.

Mindkét lépésnek sikeresnek kell lennie a PR összevonása előtt. Nem elfogadható, ha egy test262-beli fejlesztés elrontja a lodash működését; az sem, ha egy lodash-fejlesztés elrontja a test262-et.

## Miért éppen ezek a könyvtárak

- **acorn** — az elemzés a legérzékenyebb terület minden JS-motorban. A modern JS által bevezetett összes szintaktikai szélső esetet próbára teszi. Ha a Phasis az acorn segítségével tetszőleges modern kódot elemez, akkor a futtatókörnyezet megbízható.
- **mustache.js** — a sablonkezelés az egyik olyan beágyazási felhasználási eset, amelyet a Phasis kifejezetten megcéloz (a README első konkrét példája a „sablonkezelő motorok”). A Mustache a valós sablonok működési sorrendjében teszteli az iterációt, a hatókör feloldását és a karakterlánc-átalakításokat.
- **lodash** — a világ leggyakrabban használt JS segédkönyvtára. Több mint 300 függvénye közvetve minden standard könyvtári metódust érint. Ha a lodash működik, az általános adatátalakító JS is működik.
- **marked** — Markdown-megjelenítés. Gyakorlati tesztként a reguláris kifejezéseket (méghozzá sokat) és a sorokon átívelő állapotú karakterlánc-kezelést próbálja ki. Felszínre hozza a PCRE2 (a Phasis tartalék motorja) és a V8 Irregexpje közötti eltéréseket.
- **dayjs** — a dátum- és időszámítás gyakori forrása az olyan, eggyel eltérő eredményt adó hibáknak, amelyeket egyetlen test262-eset sem észlel. A dayjs a konstruktorváltozatokat, a DST-nek megfelelő hónaphatárokon átívelő műveleteket és a formázási tokenek kiterjesztését teszteli nagyjából ugyanazokon a kódútvonalakon, amelyeket minden JS-dátumkönyvtár használ.
- **bignumber.js** — tetszőleges pontosságú számítások TypedArrays nélkül: próbára teszi a karakterlánc-alapú számfeldolgozást, a nagy egész számok szorzási és osztási ciklusait, valamint a kerekítési mód kiválasztását — mindezt tisztán JS-ban, így a teljes terhelést a motor viseli. Felszínre hozza a Number ↔ String átalakítás esetleges finom hibáit.
- **json5** — a megengedő JSON-elemzés nagymértékben támaszkodik a karakterosztályos reguláris kifejezésekre és az állapottartó tokenizálásra. Jó próba a regex helyességéhez és a karakterlánc-bejárás szélső eseteihez is.
- **fuse.js** — Babellel transzpilált UMD, amely próbára teszi a `_classCallCheck`-t (az `this instanceof Ctor` mintát, amelyet minden ES6 előtti transzpilált osztály használ), valamint a teljes Bitap fuzzy keresőalgoritmust. Minden Babellel transzpilált könyvtárra jellemző szerkezet, ezért ami elrontja a Fuse működését, az a npm-ök felét is elrontja.
- **handlebars** — teljes funkcionalitású sablonkezelés fordítás utáni megjelenítéssel. A `eval`-mentes futtatókörnyezeti útvonalat teszteli egyetlen hatalmas `compile()`-belépési ponton keresztül, AST-bejárással, dinamikus keresőtáblán át végzett helper-kiválasztással, valamint a realmokon átívelő `SafeString`-ellenőrzéssel, amely a `instanceof`-t használja. Ellentéte a mustache.js egyszerűbb sablonbejárójának.
- **zod** — futásidejű sémaellenőrzés. Összetett osztályhierarchiák (`ZodString`, `ZodObject`, `ZodArray`, `ZodUnion`, …), finomított alosztályokat visszaadó metódusláncolás, strukturált hibák formázása, ahol a JS-oldali `.issues` tömb szerkezetének bájtról bájtra egyeznie kell a Node-éval, valamint megkülönböztető- és literálcímke-minták. A modern TypeScript-alkalmazások felét körülvevő, erősen objektumorientált érvényesítő kódot teszteli.
- **typescript** — a *valódi* TypeScript-fordító fut a beágyazott motoron. A 9 MB-os, minimalizált fordító tetszőleges TS-kódot elemez újra, bejárja az AST-t, majd JS-t állít elő — ez az elképzelhető legnagyobb tiszta JS-terhelés. Ha a Phasis bájtról bájtra a `tsc`-gyel egyezően képes transzpilálni a generikus típusokat, az async/awaitet, az enumokat és az osztályhierarchiákat, akkor a nyelvi szemantika megbízható.
- **prettier** — véleményes JS-formázó. A JS JS-szel végzett formázása a motor minden specifikációs szélső esetét ugyanazon a vezérlési folyamaton keresztül érinti, amely a kódot formázza — egyedülállóan megterhelő feladat.
- **svelte/compiler** — a Svelte önálló fordítója. Elemzi a `.svelte` forráskódját, bejárja az AST-t, és JS-t állít elő mind a kliens-, mind az SSR-célhoz.
- **terser / @babel/parser / postcss** — JS minifikáló, JS parser, CSS utófeldolgozó. Több tízezer sor minifikált kód, amely tetszőleges bemenetet parse-ol újra — ez az a felület, ahol ritka AST-alakzatok jelennek meg.
- **ajv** — JSON sémavalidátor, amely JIT-fordítással minden sémához egyedi validátorfüggvényt készít a(z) `new Function(...)` segítségével. Próbára teszi a Function-konstruktor útvonalát, amelyre a legtöbb séma- és sablonkönyvtár támaszkodik.
- **mobx** — proxyalapú reaktív állapot. Minden megfigyelhető érték olvasása egy Proxy `get` csapdán halad át, amely függőséget regisztrál; minden írás reakciókat vált ki. Stresszteszt a Proxy-infrastruktúrához, a megfigyelhető Mapekhez, tömbökhöz és beágyazott objektumokhoz, valamint az autorun ütemezőhöz.
- **cheerio / htmlparser2** — szerveroldali jQuery egy gyors HTML parserre építve. Szelektormotoros parse-olás, DOM-stílusú bejárás, attribútumkezelés és HTML szerializálás egy csomagban.
- **graphql-js / jsonata** — GraphQL referencia-implementáció és JSON lekérdezőnyelv. Mindkettő erősen támaszkodik sémákra, validálásra és rekurzív kiértékelőkre — tipikus „adatkezelő réteg a böngészőben” kód.
- **JSZip** — aszinkron ZIP-archívum-készítő. A munkát `setImmediate`-vezérelt ütemezéssel végzi, és valódi bináris kimenetet állít elő, így a timerfelületet és az `Uint8Array`-igényes útvonalakat is próbára teszi.
- **moment / luxon** — dátum- és időszámítás. A moment módosítható, kézzel hangolt UMD; a luxon ennek modern, nem módosítható újraírása. Együtt lefedik a formázás, a parse-olás és az időzónákkal egyenértékű hónap- és évszámítás teljes területét.
- **mqtt-packet** — tisztán JS MQTT 3.1.1 / 5.0 kodek. Bájtszintű csomagolás és dekódolás, valamint a base64 ábécéjén kívüli karaktereket kezelő regexosztályok, amelyek az Annex-B nyelvtani széleit is próbára teszik.
- **xstate / valtio / nanostores / jotai / redux-saga** — a modern állapotkezelési megoldások széles választéka. Állapotgépek, proxyállapot, atomtárolók, származtatott atomok és generátoralapú effektusfuttatók — mindegyik könyvtár a reaktivitás más formáját teszi próbára.
- **escodegen / acorn-walk / estraverse / magic-string** — AST-eszközök. Kódgenerálás, bejárás és nem destruktív forráskódszerkesztés — minden JS-on-JS transzformátor (buildeszköz, kódmódosító, linter) építőelemei.
- **papaparse / lunr / yaml / sax / css-tree** — tisztán parserek és tokenizálók. CSV, teljes szöveges keresési index, YAML 1.2, adatfolyamos, SAX-stílusú XML és CSS AST. Különböző nyelvtanok, mindegyik jó jelző a karakterenkénti pásztázás és a regex viselkedésének tesztelésére.

## További elemek hozzáadása

Hozzon létre egy új könyvtárat `tests/Popular/<name>/` alatt a háromfájlos felépítéssel, majd:

```bash
node tests/Popular/gen-oracle.js tests/Popular/<name>   # one-time, generates oracle.txt
git add tests/Popular/<name>
```

A PHPUnit tesztkészlet a következő futtatáskor automatikusan felfedezi, a CI pedig felveszi, mert a módosítás érinti a(z) `tests/Popular/` elemet.

Érdemes hozzáadni ezeket az erős jelölteket: `chevrotain` (parserkombinátor, lezárásokat és regexet tesz próbára), `nanoid` (kriptográfiai és véletlenszám-határ), `date-fns` (a dayjsen túlmutató időzóna-felület).