Quadbin Spatial Index Utilities

Common errors

• TypeError: Do not know how to serialize a BigInt

  cause Attempting to serialize a Quadbin BigInt index directly to JSON without conversion.
  fix Before `JSON.stringify()`, convert BigInt indices to hexadecimal strings using `bigIntToHex(quadbinBigInt)`. When deserializing, use `hexToBigInt(hexString)`.

• quadbin_1.tileToCell is not a function (or similar for other functions)

  cause Incorrect CommonJS `require()` syntax or attempting to use `quadbin` as a default export.
  fix This is an ESM-first library. Use named imports: `import { tileToCell } from 'quadbin';`. If using CommonJS, ensure your build setup transpiles correctly or consider `const { tileToCell } = require('quadbin');` as a last resort, though full ESM is recommended.

Warnings

• gotcha Quadbin indices are represented as JavaScript `BigInt` types. Standard JSON serialization does not support `BigInt`s, leading to `TypeError: Do not know how to serialize a BigInt`.
  Fix: Use `bigIntToHex(quadbin: bigint): string` to convert BigInts to hexadecimal strings before JSON serialization, and `hexToBigInt(hex: string): bigint` to convert them back for library use.
• gotcha This library explicitly requires Node.js version 18 or newer due to its modern JavaScript features and dependencies.
  Fix: Ensure your Node.js environment is updated to version 18 or higher. Use `node -v` to check your current version.

Install

• npm install quadbin npm
• yarn add quadbin yarn
• pnpm add quadbin pnpm

Imports

• tileToCell
  wrong:

  const tileToCell = require('quadbin').tileToCell;

  correct:

  import { tileToCell } from 'quadbin';

  The library is primarily designed for ESM imports. All Quadbin indices are BigInts.
• cellToTile
  wrong:

  import cellToTile from 'quadbin/cellToTile';

  correct:

  import { cellToTile } from 'quadbin';

  All functions are named exports from the main package entry point.
• bigIntToHex
  wrong:

  import { BigIntToHex } from 'quadbin';

  correct:

  import { bigIntToHex, hexToBigInt } from 'quadbin';

  Use `bigIntToHex` and `hexToBigInt` for JSON serialization as `BigInt` cannot be directly serialized. Note the camelCase naming.

Quickstart

Demonstrates converting an XYZ tile to a Quadbin BigInt, handling JSON serialization via hex strings, and converting back.

import { tileToCell, cellToTile, bigIntToHex, hexToBigInt } from 'quadbin';

// Example: Convert an XYZ tile to a Quadbin BigInt
const zoom = 10;
const x = 325;
const y = 373;

const tile = { x, y, z: zoom };
const quadbinBigInt = tileToCell(tile);

console.log(`Tile {z: ${zoom}, x: ${x}, y: ${y}} converts to Quadbin BigInt: ${quadbinBigInt}n`);

// Quadbin BigInts cannot be directly serialized to JSON. Convert to hex string.
const quadbinHexString = bigIntToHex(quadbinBigInt);
console.log(`Quadbin BigInt as hex string for JSON: ${quadbinHexString}n`);

// To use the hex string back in the library, convert it back to BigInt.
const restoredQuadbinBigInt = hexToBigInt(quadbinHexString);
console.log(`Restored Quadbin BigInt from hex string: ${restoredQuadbinBigInt}n`);

// Convert the Quadbin BigInt back to an XYZ tile
const convertedTile = cellToTile(restoredQuadbinBigInt);

console.log(`Quadbin BigInt ${restoredQuadbinBigInt} converts back to Tile: {z: ${convertedTile.z}, x: ${convertedTile.x}, y: ${convertedTile.y}}`);

// Verify the conversion
if (convertedTile.z === zoom && convertedTile.x === x && convertedTile.y === y) {
  console.log('\nConversion successful and consistent!');
} else {
  console.error('\nConversion resulted in a different tile!');
}