@gkucmierz/geo-words

Deterministic spatial string encoder mapping geographic HEALPix grids (BigInt) into 1 to 5 word sequences.

Concept

Translating raw numeric IDs into spoken words is a major UI/UX improvement. This package uses a strict BIP39 English dictionary of exactly 2048 words. Since $2^{11} = 2048$, each word encapsulates exactly 11 bits of data.

To make the algorithm resistant to human typos and word-scrambling, the 11-bit capacity of each word is divided into:

• 10 bits of actual spatial geographic payload.
• 1 bit of cascading checksum parity.

For 5 words, the system utilizes 50 bits for spatial bounding (perfect for targeting ~0.60 m² street-level precision via @gkucmierz/geo-number) and 5 bits for error detection, providing a ~96.8% immediate rejection rate on invalid inputs.

Dictionary Structure

The src/wordlist.js dictionary is directly derived from the standard open-source BIP39 English specification. In this repository, it is stored as a flattened, fully expanded Javascript Array file. Flattening it drastically improves developer experience (DX)—scrolling through the asset allows a developer to instantly correlate a word to its 1-based index line number without parsing JSON, resolving linting issues, or calculating object offsets.

Cascading FNV-1a Checksum

To prevent the user from accidentally swapping two valid words (which would otherwise produce a valid but wildly incorrect location), the 1-bit checksum for each word relies on the sequence of all preceding words.

This is achieved using a robust 32-bit FNV-1a hash algorithm mixed with an bitwise avalanche step:

/**
 * Robust cascading hash for checksum bit generation.
 * Utilizes a 32-bit FNV-1a hash base, augmented with an avalanche
 * step to ensure that payload permutations (e.g. swapping word 1 and 2)
 * aggressively alter the resulting parity bit.
 */
function getChecksumBit(payloads) {
  let hash = 0x811c9dc5; // 32-bit FNV offset basis
  for (let i = 0; i < payloads.length; i++) {
    // Incorporate current chunk
    hash ^= Number(payloads[i]);
    // Multiply by FNV prime
    hash = Math.imul(hash, 0x01000193); 
  }
  
  // Avalanche mix for strong bit distribution
  hash ^= hash >>> 13;
  hash ^= hash >>> 16;
  
  // Return Least Significant Bit as 1-bit checksum
  return (hash >>> 0) & 1; 
}

By hashing the history of payloads, words[2] is mathematically fused with words[1] and words[0]. Any scrambling instantly breaks the cascade and throws a verification error.

Installation

npm install @gkucmierz/geo-words

Usage

import { encode, decode } from '@gkucmierz/geo-words';

// Encode a HEALPix BigInt to 5 words
const words = encode(12345678n, 5); 

// Decode back to ID and Order
const { id, order } = decode(words);