Keep Large JavaScript IDs Exact Across Every Boundary

A JavaScript number can look valid while carrying the wrong ID. The break starts above Number.MAX_SAFE_INTEGER, but it often stays invisible until an API, database driver, log line, or browser parser converts an opaque identifier into Number.

This guide belongs to reel R077. Comment INTS for the matching module and runnable starter.

Define the boundary before building

Input: representative ID values, API response examples, database column types, serializer settings, client parsing code, and affected routes.

Output: an ID boundary map, unsafe coercion findings, string or BigInt decisions, serializer changes, and precision regression tests.

The starter keeps exact checks in code and gives Claude only the reviewable drafting work. Dry-run is the default. Live mode can call Anthropic's Messages API, but it still returns a draft and performs no external action.

Paste this boundary into Claude Code before asking for implementation:

Workflow: Keep Large JavaScript IDs Exact Across Every Boundary
Input: representative ID values, API response examples, database column types, serializer settings, client parsing code, and affected routes
Output: an ID boundary map, unsafe coercion findings, string or BigInt decisions, serializer changes, and precision regression tests

Map the trigger, strict input fields, deterministic code checks, Claude drafting step, approval gate, failure queue, and saved evidence. Use null for missing facts. Do not change code or call an external service yet.

The modules that matter

Map every conversion

Search database schemas, driver settings, JSON serializers, API types, validation schemas, logs, and frontend parsers. Record the type at each boundary. One accidental Number conversion is enough to change the digits.

Choose one representation

Use strings for IDs when callers only compare and transport them. Use BigInt only inside boundaries that support it, and add an explicit serializer because JSON.stringify does not serialize BigInt by default.

Test the boundary

Keep fixtures for 9007199254740991, 9007199254740992, and 9007199254740993. Round-trip them through the same driver and HTTP path the application uses, then compare digit for digit.

Rules worth keeping beside the code

Treat identifiers as opaque values rather than quantities.
Test values immediately below, at, and above Number.MAX_SAFE_INTEGER.
Keep the chosen representation consistent across database, API, logs, and browser code.
Require round-trip tests before changing a production identifier type.

The dangerous version is silently rounding identifiers, converting database strings to Number, breaking JSON serialization, or changing public API types without compatibility planning. The pack deliberately stops at a draft so a person can inspect those boundaries before enabling anything real.

Test the ugly paths

Database returns a large ID as a string.
Server serialization preserves every digit.
Browser parsing does not call Number or parseInt.
Logs and queues retain the same value.
Old clients receive a compatible type during migration.

The final verification is concrete: Round-trip boundary IDs through the database driver, server serializer, HTTP response, and browser parser and compare the exact original digits.

Use this prompt to turn the evidence into acceptance tests:

Design tests for Keep Large JavaScript IDs Exact Across Every Boundary using only the attached fictional fixtures.
Cover the normal path, missing input, malformed input, a repeated event, a permission failure, a dependency failure, and the named safety boundary.
For each test return: input, expected state, prohibited side effect, and evidence to save.
Do not execute external actions.

Run the pack locally

The ZIP is a complete Node 22 starter with no third-party npm dependency. It includes an importable n8n webhook, Docker Compose, GitHub Actions validation and manual-run workflows, deterministic samples, and tests.

npm test
npm run validate
npm run sample
cp .env.example .env
docker compose up --build

Only set WORKFLOW_MODE=live, ANTHROPIC_API_KEY, and ANTHROPIC_MODEL after the dry-run output and tests make sense for your system. Keep real secrets in the environment, never in the n8n export.

Download the runnable pack

Start with the fictional dry-run. It validates the input and returns a reviewable draft without changing code, production data, customer accounts, or an external service.

Before enabling a real action

Replace every fictional fixture, assign the approval owner, define the duplicate key, set a timeout and retry rule, and save the original evidence. Then test one failure on purpose. If the workflow cannot stop visibly and replay safely, it is not ready to act.