# Populiariausi paketai Specifikacijos atitiktis negarantuoja, kad veiks realios bibliotekos. JS varikliai, atitinkantys 99 % test262, vis tiek nuolat stringa su gamybiniu kodu, nes bibliotekos priklauso nuo daugybės rečiau pasitaikančių „specifikacijos kampinių atvejų“: tam tikra tvarka suveikiančių Proxy gaudyklių, `Function.prototype.toString` struktūros, reguliariųjų reiškinių veikimo su kebliais įvesties duomenimis ir tikslios sąveikos tarp `Object.keys` tvarkos bei apskaičiuojamų savybių pavadinimų. Phasis baitas į baitą tikrina **204 plačiai naudojamas bibliotekas**, palygindama jas su Node.js (V8). Jos saugomos repo kataloge `tests/Popular/`, o CI jas paleidžia kaskart pasikeitus variklio šaltinio kodui ar testų rinkiniui. ## Aprėptis pagal kategorijas | Kategorija | Bibliotekos | |---|---| | **Analizatoriai / 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 | | **Šablonai / 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 | | **Pagalbinės / funkcinės** | 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 | | **Objektų prieiga** | 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 | | **Tikrinimas / schemos** | 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 | | **Data / laikas** | dayjs 1.11.20, date-fns 4.1.0, timeago.js 4.0.2, luxon 3.7.3, moment 2.30.2 | | **Matematika / skaičiai** | 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 | | **Maišos funkcijos / kriptografija** | 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 | | **Paieška / skirtumų palyginimas** | 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 / duomenų formatai** | 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 | | **Eilutės / kalbotyra** | 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 / žiniatinklis** | 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 | | **Glaudinimas / kodavimas / archyvavimas** | pako 2.1.0, lz-string 1.5.0, base64-js 1.5.1, JSZip 3.10.1 | | **Spalvos** | 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 | | **Klonai / lygybė** | rfdc 1.4.1, klona 2.0.6, fast-copy 3.0.2 | | **Formatavimas / atvaizdavimas** | ms 2.1.3, bytes 3.1.2 | | **ID / UUID** | uuid 10.0.0, hexoid 2.0.0, ulid 3.0.1, cuid2 2.2.2, short-unique-id 5.4.3 | | **Tipų nustatymas / 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 / konfigūracija** | semver 7.6.3, compare-versions 6.1.1, semver-compare 1.0.0 | | **Talpyklos / našumas** | lru-cache 11.0.2, marky 1.3.0, array-flatten 3.0.0, arr-diff 4.0.0 | | **Asinchroniškumas / įvykiai** | 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 | | **Reaktyvioji būsena** | 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 / stiliai** | postcss 8.5.7, stylis 4.3.6, css-tree 3.0.4 | | **Kūrimas / AST / kompiliatoriai** | 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 (kompiliatorius), typescript 6.0.3 | | **MQTT / protokolas** | mqtt-packet 9.0.4 | | **GraphQL** | graphql-js 16.11.0 | | **Sintaksės paryškinimas** | highlight.js 11.11.1 | | **Testavimas / tvirtinimai** | chai 6.2.1 | Iš viso: **204 bibliotekų** tiksliai atkuria Node išvestį. Visos prisegtos prie naujausios pirminės versijos, išleistos iki paskutinio atnaujinimo. ## Kaip tai veikia Kiekvienas scenarijus yra `tests/Popular//` katalogas su trimis failais: ```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) ``` `tests/Popular/PopularPackagesTest.php` yra PHPUnit duomenų teikėjo testas, kuris: 1. Įkelia `lodash.js` + `runner.js` į naują `new Phasis\Engine()`. 2. Fiksuoja `console.log` išvestį buferyje. 3. Patikrina, ar užfiksuotas buferis po baitą sutampa su `oracle.txt`. Iš naujo sugeneruokite etaloną naudodami: ```bash node tests/Popular/gen-oracle.js tests/Popular/ ``` (Naudojama atnaujinant įtrauktą biblioteką: iš naujo paleidžia vykdyklę tikroje Node aplinkoje ir perrašo `oracle.txt`.) ## CI patikros vartai Darbo eiga: [`.github/workflows/popular.yml`](https://github.com/inline0/phasis/blob/main/.github/workflows/popular.yml). Paleidžiama atliekant `main` pakeitimus ir teikiant PR į `src/`, kai pakeičiama `tests/Popular/`, `phpunit.xml.dist`, Composer failai arba pati darbo eiga, taip pat paleidžiama rankiniu būdu. Du žingsniai: 1. **Phasis pusė** — paleidžia PHPUnit `popular` testų rinkinį, kuris vykdo kiekvieną biblioteką per Phasis ir palygina su įrašytu etalonu. Testas nepraeina, jei skiriasi bent vienas baitas. 2. **Pakartotinis tikrinimas Node aplinkoje** — vykdo `node tests/Popular/gen-oracle.js …` su kiekviena biblioteka ir patikrina, ar naujai sugeneruotas etalonas sutampa su saugomu repozitorijoje. Aptinka neatitikimus, kai „įtraukta biblioteka atnaujinta, bet etalonas ne“. PR sujungiama tik praėjus abiem patikroms. test262 laimėjimas, dėl kurio sugenda lodash, nepriimtinas; taip pat nepriimtina, jei laimėjimas su lodash sugadina test262. ## Kodėl pasirinktos šios bibliotekos - **acorn** — analizė yra pažeidžiamiausia bet kurios JS variklio dalis. Ji tikrina visus šiuolaikinės JS sintaksės kraštinius atvejus. Jei Phasis gali su acorn analizuoti bet kokį šiuolaikinį kodą, vykdymo aplinka veikia patikimai. - **mustache.js** — šablonų kūrimas yra vienas iš įterpimo scenarijų, kuriems aiškiai skirta Phasis (pirmasis konkretus README pavyzdys — „šablonų varikliai“). Mustache tikrina iteraciją, sričių sprendimą ir eilučių transformacijas tokia tvarka, kokia jos vyksta tikruose šablonuose. - **lodash** — plačiausiai naudojama JS pagalbinė biblioteka pasaulyje. Jos daugiau nei 300 funkcijų netiesiogiai paliečia kiekvieną standartinės bibliotekos metodą. Jei veikia lodash, veikia ir bendro pobūdžio duomenų transformavimo JS. - **marked** — Markdown atvaizdavimas. Tai praktiškas bandymas, tikrinantis reguliariuosius reiškinius (jų naudojama daug) ir eilučių manipuliavimą su būsenos išsaugojimu tarp eilučių. Išryškina reguliariųjų reiškinių variklio skirtumus tarp PCRE2 (atsarginės Phasis realizacijos) ir V8 Irregexp. - **dayjs** — datos ir laiko skaičiavimai dažnai sukelia poslinkio per vieną vienetą klaidų, kurių neaptinka jokie test262 atvejai. dayjs apima skirtingus konstruktoriaus variantus, skaičiavimus per DST atitinkančias mėnesių ribas ir formato žymų išplėtimą maždaug tais pačiais kodo keliais kaip ir bet kuri JS datų biblioteka. - **bignumber.js** — savavališko tikslumo aritmetika be TypedArrays tikrina skaičių analizę iš eilučių, didelių sveikųjų skaičių daugybos ir dalybos ciklus bei apvalinimo režimų parinkimą — visa tai atliekama grynuoju JS, todėl variklis prisiima visą apkrovą. Taip aptinkami subtilūs skaičių konvertavimo į eilutes ir atvirkščiai trikdžiai. - **json5** — atlaidesnis JSON analizavimas labai priklauso nuo simbolių klasių reguliariųjų reiškinių ir būseną sekančios žymenų analizės. Puikus bandymas reguliariųjų reiškinių tikslumui ir eilučių iteravimo kraštiniams atvejams tikrinti. - **fuse.js** — Babel transpiliuota UMD, tikrinanti `_classCallCheck` (`this instanceof Ctor` šabloną, kurį naudoja kiekviena iki ES6 transpiliuota klasė) ir visą Bitap neaiškios paieškos algoritmą. Tokia struktūra būdinga Babel transpiliuotoms bibliotekoms, todėl dėl klaidos Fuse gali sutrikti pusė npm ekosistemos. - **handlebars** — visavertė šablonų biblioteka, kurioje pirmiausia kompiliuojama, o tada atvaizduojama. Ji tikrina vykdymo kelią be `eval` per vieną didžiulį `compile()` įrašą, AST perėjimą, pagalbinių funkcijų iškvietimą per dinaminę paieškos lentelę ir `SafeString` tipo patikrą, kuri naudoja `instanceof` skirtinguose kontekstuose. Tai alternatyva paprastesniam mustache.js šablonų analizatoriui. - **zod** — schemų tikrinimas vykdymo metu. Sudėtingos klasių hierarchijos (`ZodString`, `ZodObject`, `ZodArray`, `ZodUnion`, …), kuriose metodų grandinės grąžina patikslintas poklases; struktūruotas klaidų formatavimas, kai JS pusės `.issues` masyvo struktūra turi sutapti su Node baitas į baitą; ir diskriminatoriaus bei pažymėtų literalų šablonai. Tikrinamas objektinio programavimo požiūriu sudėtingas validavimo kodas, naudojamas pusėje šiuolaikinių TypeScript programų. - **typescript** — *tikrasis* TypeScript kompiliatorius, veikiantis įterptajame variklyje. 9 MB minifikuoto kompiliatoriaus iš naujo analizuoja bet kokį TS, pereina per AST ir sukuria JS — tai didžiausias įmanomas grynojo JS turinys. Jei Phasis gali transpiliuoti bendrinius tipus, async/await, enum tipus ir klasių hierarchijas taip, kad rezultatas baitas į baitą sutaptų su `tsc`, kalbos semantika veikia patikimai. - **prettier** — griežtą nuomonę turintis JS formatavimo įrankis. Formatuojant JS *su* JS, visi variklio specifikacijos kraštiniai atvejai tikrinami tuo pačiu valdymo srautu, kuris formatuoja jūsų kodą — tai išskirtinai sudėtinga apkrova. - **svelte/compiler** — atskiras Svelte kompiliatorius. Analizuoja `.svelte` šaltinio kodą, pereina per AST ir sukuria JS klientui ir SSR tikslams. - **terser / @babel/parser / postcss** — JS minifikatorius, JS analizatorius, CSS postprocesorius. Dešimtys tūkstančių minifikuoto kodo eilučių iš naujo analizuoja bet kokią įvestį — būtent čia pasitaiko retų AST struktūrų. - **ajv** — JSON schemų tikrinimo priemonė, kuri JIT būdu kompiliuoja kiekvieną schemą į pritaikytą tikrinimo funkciją naudodama `new Function(...)`. Tikrinamas Function konstruktoriaus kelias, kurį naudoja dauguma schemų ir šablonų bibliotekų. - **mobx** — reaktyvioji būsena, paremta tarpiniais objektais. Kiekvienas stebimos reikšmės skaitymas vyksta per Proxy `get` gaudyklę, kuri užregistruoja priklausomybę; kiekvienas įrašymas sužadina reakcijas. Tai Proxy infrastruktūros, stebimų Map, masyvų ir įdėtinių objektų bei autorun planuoklio apkrovos bandymas. - **cheerio / htmlparser2** — serverio pusės jQuery, veikianti su sparčiu HTML analizatoriumi. Viename pakete atliekama selektorių analizė, DOM tipo perėjimas, atributų keitimas ir HTML serializavimas. - **graphql-js / jsonata** — GraphQL etaloninė realizacija ir JSON užklausų kalba. Abiejose gausu schemų, tikrinimo ir rekursinių vertinimo funkcijų — tai tipiškas „duomenų sluoksnio naršyklėje“ kodas. - **JSZip** — asinchroninis ZIP archyvų kūrimo įrankis. Darbą planuoja naudodamas `setImmediate`, o rezultatas yra tikri dvejetainiai duomenys; taip tikrinamas ir laikmačių palaikymas, ir `Uint8Array` reikalaujantys keliai. - **moment / luxon** — datos ir laiko skaičiavimai. moment yra keičiamas, rankiniu būdu optimizuotas UMD; luxon — šiuolaikinė nekintamų duomenų versija. Kartu jos apima visą formatavimo, analizavimo ir laiko juostų atitikmenų mėnesių bei metų skaičiavimo sričių spektrą. - **mqtt-packet** — grynasis JS MQTT 3.1.1 / 5.0 kodekas. Pakavimas ir iškodavimas baitų lygmeniu bei bazinės 64 sistemos abėcėlei nepriklausančių simbolių klasių reguliarieji reiškiniai tikrina Annex-B gramatikos kraštinius atvejus. - **xstate / valtio / nanostores / jotai / redux-saga** — šiuolaikinės būsenos valdymo priemonės. Būsenų automatai, tarpiniais objektais paremta būsena, atomų saugyklos, išvestiniai atomai ir generatoriais pagrįsti efektų vykdytojai — kiekviena biblioteka tikrina skirtingą reaktyvumo struktūrą. - **escodegen / acorn-walk / estraverse / magic-string** — AST įrankiai. Kodo generavimas, perėjimas ir šaltinio redagavimas nekeičiant originalo — pagrindinės priemonės bet kokiam JS per JS transformatoriui (kūrimo įrankiams, kodo modifikavimo įrankiams, linteriams). - **papaparse / lunr / yaml / sax / css-tree** — grynieji analizatoriai ir žymenų analizavimo priemonės. CSV, viso teksto paieškos indeksas, YAML 1.2, srautinis SAX tipo XML ir CSS AST. Skirtingos gramatikos — puikūs bandymai simbolių lygmens skenavimui ir reguliariųjų reiškinių veikimui tikrinti. ## Kaip pridėti daugiau Sukurkite naują katalogą `tests/Popular//` su trimis failais, tada: ```bash node tests/Popular/gen-oracle.js tests/Popular/ # one-time, generates oracle.txt git add tests/Popular/ ``` Kitą kartą paleidus, PHPUnit testų rinkinys jį aptiks automatiškai, o CI jį įtrauks, nes pakeitimas liečia `tests/Popular/`. Verta pridėti šias perspektyvias bibliotekas: `chevrotain` (parserių kombinatorius, tikrina uždarymus ir reguliariuosius reiškinius), `nanoid` (kriptografijos ir atsitiktinių skaičių riba), `date-fns` (laiko juostų aprėptis, platesnė nei dayjs).