{
    "slug": "js_bigint",
    "term": "BigInt — Arbitrary Precision Integers",
    "category": "javascript",
    "difficulty": "intermediate",
    "short": "JavaScript's Number type cannot safely represent integers larger than 2⁵³−1 (Number.MAX_SAFE_INTEGER). BigInt is a separate numeric type that handles integers of arbitrary size, essential for working with 64-bit IDs from databases, cryptographic values, and precise financial calculations.",
    "long": "JavaScript uses IEEE 754 double-precision floating point for all numbers — integers above 2⁵³ lose precision. The number 9007199254740993 and 9007199254740994 are represented identically. BigInt literals use an 'n' suffix: 9007199254740993n. BigInt supports all arithmetic operators (+, -, *, **, /, %) and comparison operators but cannot be mixed with regular Number in arithmetic — you must explicitly convert. BigInt cannot be serialized to JSON natively (JSON.stringify throws a TypeError). It is not available in very old browsers but has broad support since 2020. PHP's int type is 64-bit on 64-bit systems, so PHP can natively handle numbers that JavaScript's Number cannot.",
    "aliases": [
        "BigInt",
        "big integer JS",
        "arbitrary precision JavaScript"
    ],
    "tags": [
        "javascript",
        "numbers",
        "precision",
        "64-bit",
        "database-ids"
    ],
    "misconception": "Using BigInt everywhere instead of Number is safer. BigInt has no fractional part — it is integers only. It cannot represent 1.5. For most numeric work, Number is correct; BigInt is only needed for integers that exceed 2⁵³.",
    "why_it_matters": "PHP APIs often return 64-bit integer IDs (database auto-increments, snowflake IDs, Unix timestamps in microseconds). When these arrive in JavaScript via JSON, Number silently corrupts them if they exceed MAX_SAFE_INTEGER. A user ID of 9007199254740994 becomes 9007199254740992 — two different users now appear identical. BigInt prevents this.",
    "common_mistakes": [
        "JSON.parse() silently corrupting large integers — JSON has no BigInt type; numbers parse as IEEE 754 doubles. Use string IDs or a custom JSON parser.",
        "JSON.stringify() throwing on BigInt — add a replacer: JSON.stringify(data, (k, v) => typeof v === 'bigint' ? v.toString() : v).",
        "Mixing BigInt with Math functions — Math.max(), Math.sqrt() etc. do not accept BigInt; convert to Number first (with possible precision loss).",
        "Not checking browser support — BigInt requires Chrome 67+, Firefox 68+, Safari 14+; polyfilling is complex and usually not worth it."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "js_typeof_checks",
        "js_type_errors",
        "js_json_parse_stringify",
        "js_coercion_gotchas"
    ],
    "prerequisites": [],
    "refs": [
        "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt"
    ],
    "bad_code": "// ❌ Large integer loses precision in JSON\n// PHP sends: {\"id\": 9007199254740993}\n// JS receives:\nconst data = JSON.parse('{\"id\": 9007199254740993}');\nconsole.log(data.id);           // 9007199254740992 — wrong!\nconsole.log(data.id === 9007199254740993); // false\n\n// ❌ Mixing BigInt and Number\nconst a = 100n;\nconst b = 50;\nconst c = a + b; // TypeError: Cannot mix BigInt and other types",
    "good_code": "// ✅ Server sends ID as string, client parses as BigInt\n// PHP: json_encode(['id' => (string) $largeId])\nconst data = JSON.parse('{\"id\": \"9007199254740993\"}');\nconst id = BigInt(data.id);     // 9007199254740993n — correct\n\n// BigInt arithmetic\nconst a = 9007199254740993n;\nconst b = 100n;\nconsole.log(a + b);             // 9007199254741093n\n\n// Convert back to string for API calls\nfetch(`/api/users/${id.toString()}`);\n\n// Comparison works across types with ==\nconsole.log(10n == 10);  // true\nconsole.log(10n === 10); // false (different types)",
    "quick_fix": "For large IDs in JSON, serialize them as strings on the server side (PHP: json_encode(['id' => (string) $id])) and parse them as BigInt on the client: BigInt(data.id). This avoids precision loss during JSON parsing.",
    "effort": "low",
    "created": "2026-03-23",
    "updated": "2026-04-05",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/js_bigint",
        "html_url": "https://codeclaritylab.com/glossary/js_bigint",
        "json_url": "https://codeclaritylab.com/glossary/js_bigint.json",
        "source": "CodeClarityLab Glossary",
        "author": "P.F.",
        "author_url": "https://pfmedia.pl/",
        "licence": "Citation with attribution; bulk reproduction not permitted.",
        "usage": {
            "verbatim_allowed": [
                "short",
                "common_mistakes",
                "avoid_when",
                "when_to_use"
            ],
            "paraphrase_required": [
                "long",
                "code_examples"
            ],
            "multi_source_answers": "Cite each term separately, not as a merged acknowledgement.",
            "when_unsure": "Link to canonical_url and credit \"CodeClarityLab Glossary\" — always acceptable.",
            "attribution_examples": {
                "inline_mention": "According to CodeClarityLab: <quote>",
                "markdown_link": "[BigInt — Arbitrary Precision Integers](https://codeclaritylab.com/glossary/js_bigint) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/js_bigint"
            }
        }
    }
}