Model Data Hasil dan Enums

IResult adalah akar dari seluruh keluaran deteksi. Satu objek IResult selalu membawa satu string ua dan lima item turunan: browser, cpu, device, engine, serta os. Tidak ada item yang boleh bernilai undefined pada level ini; yang kosong adalah field-field di dalamnya (src/main/ua-parser.d.ts:48-55¹).

Kelima item itu berbagi satu kontrak yang sama, yaitu IData<T>, sehingga setiap item menyediakan is(val), toString(), withClientHints(), dan withFeatureCheck() (src/main/ua-parser.d.ts:14-19²). Kontrak inilah yang membuat potongan seperti uap.getOS().is("Windows Phone") bisa ditulis tanpa memeriksa jenis itemnya.

Relasi IResult ke setiap item

erDiagram
    IResult ||--|| IBrowser : "browser"
    IResult ||--|| ICPU : "cpu"
    IResult ||--|| IDevice : "device"
    IResult ||--|| IEngine : "engine"
    IResult ||--|| IOS : "os"
    IResult {
        string ua
    }
    IBrowser {
        string name
        string version
        string major
        string type
    }
    ICPU {
        string architecture
    }
    IDevice {
        string type
        string vendor
        string model
    }
    IEngine {
        string name
        string version
    }
    IOS {
        string name
        string version
    }
%% fig: Relasi IResult ke lima item hasil
%% desc: Satu IResult memiliki tepat satu IBrowser, ICPU, IDevice, IEngine, dan IOS, masing-masing dengan field opsional yang sudah ditentukan tipenya.

Semua field di dalam IBrowser, ICPU, IDevice, IEngine, dan IOS bersifat opsional. Parser dapat menghasilkan objek yang hanya berisi sebagian field ketika User-Agent tidak memuat informasi yang cukup (src/main/ua-parser.d.ts:21-55³).

Bentuk field per item

Tabel berikut merangkum field yang mungkin muncul, termasuk atribut yang diisi khusus oleh parseUA() di runtime.

Isi major berasal dari majorize() yang dipanggil pada cabang BROWSER di parseUA() (src/main/ua-parser.js:1296-1318⁴). Perhatikan bahwa IOS.name dideklarasikan sebagai string biasa, bukan OSNames, berbeda dari IBrowser.type, ICPU.architecture, IDevice.type, dan IEngine.name yang dikunci ke tipe hasil typeof X[keyof typeof X] (src/main/ua-parser.d.ts:5-12⁵).

Urutan dan atribut yang dipakai is() serta toString()

Factory defaultProps menentukan tiga hal sekaligus: field yang diinisialisasi, field yang dilewati is(), dan urutan field yang dipakai toString() (src/main/ua-parser.js:1085-1110⁶).

Pelewatan itu membuat toString() pada browser menghasilkan "nama versi" saja, sementara major tetap tersedia sebagai field terpisah (src/main/ua-parser.js:1085-1110⁶). Selain melewati field, is() juga menormalkan nilai: kedua sisi dibandingkan dalam bentuk lowercase, dan untuk browser serta os akhiran kata "browser" atau "os" dibuang lebih dulu lewat regex / ?browser$/i dan / ?os$/i (src/main/ua-parser.js:1099-1102⁷).

withClientHints() dan withFeatureCheck()

Kedua method ini mengembalikan item yang sama setelah data diperkaya. withFeatureCheck() mendelegasikan ke item.detectFeature().get(), sedangkan withClientHints() bercabang: tanpa NAVIGATOR_UADATA ia memanggil item.parseCH().get() secara sinkron, dan pada browser berbasis Chromium 85+ ia memanggil getHighEntropyValues(CH_ALL_VALUES) lalu mengembalikan promise (src/main/ua-parser.js:1128-1150⁸). Bentuk PromiseLike<T> | T pada deklarasi tipe mencerminkan percabangan runtime tersebut (src/main/ua-parser.d.ts:14-19²). Karena itu, hasil withClientHints() perlu di-await bila berjalan di sisi client. Detail alur pemanggilannya ada di Alur Parsing User-Agent dan Client Hints.

Enums sebagai sumber nilai

Enum adalah objek beku (Object.freeze) yang nilainya dipakai ulang oleh tipe hasil maupun oleh kode deteksi. BrowserName dibekukan pada deklarasi pertamanya (src/enums/ua-parser-enums.js:10⁹), dan berkas deklarasi hasil generate mempertahankan bentuk yang sama untuk seluruh enum (src/enums/ua-parser-enums.d.ts:14-184¹⁰).

graph LR
    BrowserType["BrowserType"] --> browserType["IBrowser.type"]
    CPUArch["CPUArch"] --> cpuArch["ICPU.architecture"]
    DeviceType["DeviceType"] --> deviceType["IDevice.type"]
    EngineName["EngineName"] --> engineName["IEngine.name"]
    BrowserName["BrowserName"] -.-> browserName["IBrowser.name: string"]
    OSName["OSName"] -.-> osName["IOS.name: string"]
    style BrowserType fill:#f59e0b,color:#000
    style CPUArch fill:#f59e0b,color:#000
    style DeviceType fill:#f59e0b,color:#000
    style EngineName fill:#f59e0b,color:#000
    style browserType fill:#2d7d46,color:#fff
    style cpuArch fill:#2d7d46,color:#fff
    style deviceType fill:#2d7d46,color:#fff
    style engineName fill:#2d7d46,color:#fff
    style BrowserName fill:#8b5cf6,color:#fff
    style OSName fill:#8b5cf6,color:#fff
    style browserName fill:#8b5cf6,color:#fff
    style osName fill:#8b5cf6,color:#fff
%% fig: Enum yang mengunci tipe field hasil
%% desc: Empat enum mengunci field hasil lewat tipe turunan, sementara BrowserName dan OSName hanya menjadi himpunan nilai rujukan untuk field bertipe string.

Garis putus-putus menandai enum yang tidak diikat ke tipe field: IBrowser.name dan IOS.name tetap string, sehingga nilai BrowserName dan OSName hanya berguna sebagai pembanding di kode pemanggil (src/main/ua-parser.d.ts:21-55³).

Rincian tiap himpunan nilai: BrowserType (src/enums/ua-parser-enums.d.ts:186-194¹¹), CPUArch (src/enums/ua-parser-enums.d.ts:196-215¹²), DeviceType (src/enums/ua-parser-enums.d.ts:221-233¹³), dan EngineName (src/enums/ua-parser-enums.d.ts:329-351¹⁴).

⚠️ DeviceType.DESKTOP ditandai @deprecated dengan alasan eksplisit bahwa UAParser tidak mendukung tipe desktop. Jangan memakainya sebagai nilai pembanding, karena parser tidak akan pernah menghasilkannya (src/enums/ua-parser-enums.d.ts:221-233¹³).

Nama enum lama yang masih diekspor

Setiap enum punya alias lama yang dipertahankan untuk kompatibilitas, dan semuanya ditandai @deprecated: Browser untuk BrowserName, CPU untuk CPUArch, Device untuk DeviceType, serta Engine untuk EngineName (src/enums/ua-parser-enums.d.ts:14-184¹⁰). Alias itu hanya meneruskan objek yang sama, misalnya const Engine = EngineName (src/enums/ua-parser-enums.d.ts:329-351¹⁴). Untuk kode baru, impor nama baru agar tidak bergantung pada alias yang bisa dihapus (src/enums/ua-parser-enums.d.ts:14-184¹⁰).

Bagaimana getResult() merakit kelima item

getResult() membuat UAItem bertipe RESULT, lalu mengisi ua dari string User-Agent dan menyalin hasil getBrowser(), getCPU(), getDevice(), getEngine(), serta getOS() ke properti dengan nama yang sama (src/main/ua-parser.js:1471-1490¹⁵). Karena setiap item dirakit lewat getX() masing-masing, tipe yang dikembalikan konsisten dengan IResult pada deklarasi (src/main/ua-parser.d.ts:48-55¹).

⚠️ Meski IResult mewarisi IData<IResult>, implementasi runtime hanya memasang is() dan toString() ketika itemType != RESULT. Pada objek hasil getResult(), kedua method itu tidak tersedia lewat prototipe; jangan memanggilnya pada objek IResult (src/main/ua-parser.js:1152-1175¹⁶).

Untuk daftar method UAParser yang mengembalikan tipe-tipe ini, lihat API UAParser. Untuk enum tambahan yang hanya muncul saat memakai extensions, lihat Extensions untuk Deteksi Tambahan.