Arsitektur Modul dan Peta Ekspor

Repository ini mengirimkan satu implementasi inti di src/main/ua-parser.js dan menurunkan seluruh entry point lain darinya. Versi ESM bukan hasil tulis ulang, melainkan berkas hasil generate: src/main/ua-parser.mjs dibuka dengan komentar // DO NOT EDIT THIS FILE! dan ditutup oleh export {UAParser}; src/main/ua-parser.mjs:1513-1519¹. Sisi CommonJS menutup berkas dengan cabang lingkungan yang berbeda: module.exports untuk Node.js, define untuk AMD, dan window.UAParser untuk browser src/main/ua-parser.js:1526-1543².

package.json menetapkan "type": "commonjs", sehingga semua berkas .js dimuat sebagai CJS, sementara .mjs disediakan khusus untuk import package.json:195-199³.

Peta field exports

Enam subpath dipublikasikan. Setiap subpath memetakan tiga berkas: satu implementasi CJS, satu hasil generate ESM, dan satu deklarasi tipe package.json:200-236⁴.

Field main, module, browser, dan types di tingkat atas menunjuk ke jalur yang sama dengan subpath ., ditambah bundel dist/ua-parser.pack.js untuk lingkungan browser package.json:195-199³. Artifact dist/ sendiri tidak diekspos sebagai subpath exports; ia hanya masuk daftar files bersama direktori src package.json:237-242⁵.

Dari .js ke .mjs dan .d.ts

script/build-esm.js menjalankan serangkaian regex atas berkas sumber, bukan menyalin apa adanya. Tiga penggantian utama mengubah const X = require('...') menjadi import X from '...', menambahkan sufiks .mjs pada require relatif, dan mengganti module.exports = menjadi export script/build-esm.js:5-12⁶. Daftar berkas yang diproses memuat lima pasangan .js → .mjs plus satu pengecualian penting: src/enums/ua-parser-enums.js juga diturunkan menjadi src/enums/ua-parser-enums.d.ts script/build-esm.js:32-91⁷.

⚠️ src/enums/ua-parser-enums.d.ts adalah berkas hasil generate, begitu pula seluruh *.mjs. Mengubah keduanya secara manual akan hilang pada npm run build berikutnya, karena build menjalankan ./script/build-esm.js && ./script/build-dist.sh package.json:244-246⁸. Perubahan regex atau konstanta enum harus ditulis di berkas .js sumbernya, yaitu src/enums/ua-parser-enums.js script/build-esm.js:68-78⁹.

Sebaliknya, src/main/ua-parser.d.ts ditulis manual. Berkas ini mengimpor tipe dari enums, bukan mendefinisikan ulang nama browser dan OS src/main/ua-parser.d.ts:5¹⁰, lalu memusatkan bentuk data lewat IData, IResult, dan tiga tipe bantu: RegexMap, UAParserProps, serta UAParserExt src/main/ua-parser.d.ts:57-60¹¹. UAParserExt inilah tipe yang harus cocok dengan bentuk objek yang diterima useExtension.

Arah ketergantungan antar modul

src/main adalah akar: ia tidak mengimpor enums maupun extensions, melainkan membangun enum statisnya sendiri lewat enumerize src/main/ua-parser.js:146-152¹² yang kemudian dipasang sebagai UAParser.BROWSER, UAParser.CPU, UAParser.DEVICE, dan UAParser.ENGINE/UAParser.OS src/main/ua-parser.js:1516-1520¹³. Semua submodule justru bergerak ke arah sebaliknya: mengimpor UAParser dari ../main/ua-parser src/bot-detection/bot-detection.js:10-13, src/browser-detection/browser-detection.js:10-13, src/device-detection/device-detection.js:10-11.

graph TD
  main["src/main/ua-parser.js<br/>UAParser"]
  enums["src/enums/ua-parser-enums.js"]
  ext["src/extensions/ua-parser-extensions.js"]
  bot["src/bot-detection"]
  br["src/browser-detection"]
  dev["src/device-detection"]
  helpers["src/helpers/ua-parser-helpers.js"]
  pwa["is-standalone-pwa"]
  eu["detect-europe-js"]
  frozen["ua-is-frozen"]

  bot --> main
  bot --> ext
  bot --> enums
  br --> main
  br --> enums
  br --> pwa
  br --> eu
  dev --> main
  dev --> enums
  helpers --> bot
  helpers --> br
  helpers --> dev
  helpers --> frozen

  style main fill:#f59e0b,color:#000
  style enums fill:#8b5cf6,color:#fff
  style ext fill:#8b5cf6,color:#fff
  style bot fill:#2d7d46,color:#fff
  style br fill:#2d7d46,color:#fff
  style dev fill:#2d7d46,color:#fff
  style helpers fill:#336791,color:#fff
%% fig: Arah ketergantungan antar modul
%% desc: Submodule deteksi mengimpor UAParser dari src/main, enums dan extensions menyuplai konstanta serta pola regex, dan helpers merangkum ketiga submodule ditambah satu dependensi eksternal.

Modul enums dan extensions berada di lapisan paling bawah: keduanya tidak mengimpor submodule apa pun. enums mengekspor daftar nama yang dipakai bersama, dan enam di antaranya ditandai // deprecated karena hanya dipertahankan demi kompatibilitas src/enums/ua-parser-enums.js:857-872¹⁷. extensions mengekspor sepuluh kumpulan pola, dari Bots sampai Vehicles src/extensions/ua-parser-extensions.js:505-516¹⁸. Bentuk setiap kumpulan adalah objek beku dengan kunci browser, cpu, device, engine, atau os, dan tiap entri berisi pasangan regex dan daftar field hasil src/extensions/ua-parser-extensions.js:42-47¹⁹.

Bentuk objek itulah yang diperiksa isExtensions lewat regex /^(browser|cpu|device|engine|os)$/ src/main/ua-parser.js:162-166²⁰, sehingga UAParser dapat membedakan argumen extensions dari objek headers pada konstruktornya src/main/ua-parser.js:1422-1438²¹. Setelah dikenali, extend menggabungkan pola extension di depan pola bawaan src/main/ua-parser.js:130-145²², dan useExtension menyimpannya ke regexMap yang dipakai setiap pemanggilan getBrowser, getCPU, dan seterusnya src/main/ua-parser.js:1505-1508²³.

src/helpers adalah agregator, bukan implementasi baru. Ia mengimpor ulang fungsi dari ketiga submodule dengan alias berawalan garis bawah, lalu mengekspornya kembali bersama isAICrawler dan getOutlookEdition src/helpers/ua-parser-helpers.js:10-14²⁴, src/helpers/ua-parser-helpers.js:100-111²⁵. Nama lama seperti isAIBot dipertahankan sebagai alias dengan anotasi @deprecated yang menunjuk submodule penggantinya src/helpers/ua-parser-helpers.js:26-29²⁶.

Ekspor publik per modul

Artifact dist/ dibangun terpisah dari peta exports: script/build-dist.sh menghasilkan empat berkas, yaitu ua-parser.min.js, ua-parser.min.mjs, ua-parser.pack.js, dan ua-parser.pack.mjs, masing-masing dari sumber .js atau .mjs yang sesuai script/build-dist.sh:1-9³⁰. Rincian perintah dan urutan build ada di Build, Test, dan Rilis.

Untuk perilaku setiap modul, lihat Enums dan Konstanta Deteksi, Extensions: Bots, Crawlers, dan Lainnya, dan Submodule bot-detection, browser-detection, dan device-detection. Bentuk hasil yang dikembalikan UAParser dijelaskan di API Utama dan Bentuk Hasil.