@gisce/bigint-helper

BigInt helper functions for the GISCE ecosystem. This library provides utilities for safely working with BigInt IDs in JavaScript/TypeScript applications.

Why BigInt?

JavaScript's Number type loses precision for integers larger than Number.MAX_SAFE_INTEGER (9,007,199,254,740,991). Database IDs often exceed this limit, causing bugs when IDs get truncated or compared incorrectly.

BigInt solves this, but introduces challenges:

• 5n === 5 is false (strict equality fails across types)
• [1n, 2n, 3n].includes(2) is false
• JSON.parse/JSON.stringify don't support BigInt

This library provides drop-in utilities to handle these edge cases.

Installation

npm install @gisce/bigint-helper

API

parseJSON<T>(text: string): T

Parses JSON with BigInt support. Numbers larger than Number.MAX_SAFE_INTEGER are automatically parsed as BigInt.

import { parseJSON } from "@gisce/bigint-helper";

const data = parseJSON('{"id": 9007199254740993}');
// data.id is 9007199254740993n (BigInt), not 9007199254740992 (truncated)

stringifyJSON(value: unknown, space?: number): string

Stringifies values to JSON with BigInt support. BigInt values are serialized as numbers without quotes.

import { stringifyJSON } from "@gisce/bigint-helper";

const json = stringifyJSON({ id: 9007199254740993n });
// '{"id":9007199254740993}'

toSafeBigIntKey(id: number | bigint | undefined | null): string

Converts an ID to a string safe for use as object keys or React keys.

import { toSafeBigIntKey } from "@gisce/bigint-helper";

toSafeBigIntKey(123n);      // "123"
toSafeBigIntKey(456);       // "456"
toSafeBigIntKey(undefined); // "undefined"
toSafeBigIntKey(null);      // "null"

isValidId(value: unknown): value is number | bigint

Type guard to check if a value is a valid ID (number or bigint).

import { isValidId } from "@gisce/bigint-helper";

isValidId(123);       // true
isValidId(123n);      // true
isValidId("123");     // false
isValidId(undefined); // false

idsEqual(a, b): boolean

Compares two IDs for equality, handling BigInt/number mixed comparisons.

import { idsEqual } from "@gisce/bigint-helper";

idsEqual(5n, 5);           // true (unlike 5n === 5 which is false)
idsEqual(123n, 123n);      // true
idsEqual(null, undefined); // false

includesId(arr: (number | bigint)[], id: number | bigint): boolean

Checks if an array includes an ID, handling BigInt/number mixed comparisons. Replacement for arr.includes(id) which uses strict equality.

import { includesId } from "@gisce/bigint-helper";

const ids = [1n, 2n, 3n];
includesId(ids, 2);  // true (unlike ids.includes(2) which is false)
includesId(ids, 2n); // true
includesId(ids, 5);  // false

findIdIndex(arr: (number | bigint)[], id: number | bigint): number

Finds the index of an ID in an array, handling BigInt/number mixed comparisons.

import { findIdIndex } from "@gisce/bigint-helper";

const ids = [10n, 20n, 30n];
findIdIndex(ids, 20);  // 1 (unlike ids.indexOf(20) which is -1)
findIdIndex(ids, 20n); // 1
findIdIndex(ids, 99);  // -1

License

ISC