{"id":11613,"library":"quadbin","title":"Quadbin Spatial Index Utilities","description":"The `quadbin` library (version 0.4.2) provides essential utility functions for working with the Quadbin spatial index, a hierarchical geospatial indexing system developed by CARTO. Quadbins represent map cells using 64-bit integers, offering a distinct approach compared to variable-length indexing systems like Quadkey. This TypeScript-first library emphasizes performance and type safety, making it suitable for geospatial data processing in Node.js environments (requiring Node.js >=18). It's primarily used in WebGL and visualization contexts for efficient spatial queries and data aggregation. The library's main differentiator is its use of JavaScript's `BigInt` type for quadbin indices, which necessitates explicit conversion functions like `bigIntToHex` and `hexToBigInt` when serializing or deserializing data (e.g., for JSON). While specific release cadences aren't strictly defined, the package receives active maintenance, with recent dependency updates reflecting ongoing support.","status":"active","version":"0.4.2","language":"javascript","source_language":"en","source_url":"https://github.com/CartoDB/quadbin-js","tags":["javascript","quadbin","webgl","visualization","typescript"],"install":[{"cmd":"npm install quadbin","lang":"bash","label":"npm"},{"cmd":"yarn add quadbin","lang":"bash","label":"yarn"},{"cmd":"pnpm add quadbin","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library is primarily designed for ESM imports. All Quadbin indices are BigInts.","wrong":"const tileToCell = require('quadbin').tileToCell;","symbol":"tileToCell","correct":"import { tileToCell } from 'quadbin';"},{"note":"All functions are named exports from the main package entry point.","wrong":"import cellToTile from 'quadbin/cellToTile';","symbol":"cellToTile","correct":"import { cellToTile } from 'quadbin';"},{"note":"Use `bigIntToHex` and `hexToBigInt` for JSON serialization as `BigInt` cannot be directly serialized. Note the camelCase naming.","wrong":"import { BigIntToHex } from 'quadbin';","symbol":"bigIntToHex","correct":"import { bigIntToHex, hexToBigInt } from 'quadbin';"}],"quickstart":{"code":"import { tileToCell, cellToTile, bigIntToHex, hexToBigInt } from 'quadbin';\n\n// Example: Convert an XYZ tile to a Quadbin BigInt\nconst zoom = 10;\nconst x = 325;\nconst y = 373;\n\nconst tile = { x, y, z: zoom };\nconst quadbinBigInt = tileToCell(tile);\n\nconsole.log(`Tile {z: ${zoom}, x: ${x}, y: ${y}} converts to Quadbin BigInt: ${quadbinBigInt}n`);\n\n// Quadbin BigInts cannot be directly serialized to JSON. Convert to hex string.\nconst quadbinHexString = bigIntToHex(quadbinBigInt);\nconsole.log(`Quadbin BigInt as hex string for JSON: ${quadbinHexString}n`);\n\n// To use the hex string back in the library, convert it back to BigInt.\nconst restoredQuadbinBigInt = hexToBigInt(quadbinHexString);\nconsole.log(`Restored Quadbin BigInt from hex string: ${restoredQuadbinBigInt}n`);\n\n// Convert the Quadbin BigInt back to an XYZ tile\nconst convertedTile = cellToTile(restoredQuadbinBigInt);\n\nconsole.log(`Quadbin BigInt ${restoredQuadbinBigInt} converts back to Tile: {z: ${convertedTile.z}, x: ${convertedTile.x}, y: ${convertedTile.y}}`);\n\n// Verify the conversion\nif (convertedTile.z === zoom && convertedTile.x === x && convertedTile.y === y) {\n  console.log('\\nConversion successful and consistent!');\n} else {\n  console.error('\\nConversion resulted in a different tile!');\n}","lang":"typescript","description":"Demonstrates converting an XYZ tile to a Quadbin BigInt, handling JSON serialization via hex strings, and converting back."},"warnings":[{"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.","message":"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`.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Ensure your Node.js environment is updated to version 18 or higher. Use `node -v` to check your current version.","message":"This library explicitly requires Node.js version 18 or newer due to its modern JavaScript features and dependencies.","severity":"gotcha","affected_versions":"<=0.4.2"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Before `JSON.stringify()`, convert BigInt indices to hexadecimal strings using `bigIntToHex(quadbinBigInt)`. When deserializing, use `hexToBigInt(hexString)`.","cause":"Attempting to serialize a Quadbin BigInt index directly to JSON without conversion.","error":"TypeError: Do not know how to serialize a BigInt"},{"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.","cause":"Incorrect CommonJS `require()` syntax or attempting to use `quadbin` as a default export.","error":"quadbin_1.tileToCell is not a function (or similar for other functions)"}],"ecosystem":"npm"}