Grid9 JavaScript Implementation

The JavaScript implementation of Grid9 provides universal coordinate compression for both Node.js and browser environments. With full TypeScript support and comprehensive test coverage, it's perfect for web applications, Node.js servers, and cross-platform development.

Installation

NPM Package

# Install with npm
npm install grid9

# Install with yarn
yarn add grid9

# Install with pnpm
pnpm add grid9

Browser Usage

<!-- Via CDN -->
<script src="https://unpkg.com/grid9/dist/grid9.min.js"></script>

<!-- Or download and host locally -->
<script src="./grid9.min.js"></script>

From Source

git clone https://github.com/pedrof69/Grid9.git
cd Grid9/javascript
npm install
npm run build

Quick Start

Node.js (CommonJS)

const Grid9 = require('grid9');

// Encode coordinates to Grid9 code
const code = Grid9.encode(40.7128, -74.0060);
// Result: "Q7KH2BBYF"

// Decode Grid9 code to coordinates
const coords = Grid9.decode("Q7KH2BBYF");
// Result: { latitude: 40.712779, longitude: -74.005988 }

// Human-readable format
const readable = Grid9.encode(40.7128, -74.0060, true);
// Result: "Q7K-H2B-BYF"

ES6 Modules

import { encode, decode, calculateDistance } from 'grid9';

// Encode coordinates
const code = encode(40.7128, -74.0060);

// Calculate distance between two locations
const nyc = encode(40.7128, -74.0060);
const london = encode(51.5074, -0.1278);
const distance = calculateDistance(nyc, london);
// Result: 5570224 meters

TypeScript

import { UniformPrecisionCoordinateCompressor } from 'grid9';

// TypeScript types are included
const encoder = new UniformPrecisionCoordinateCompressor();

// Encode with type safety
const code: string = encoder.encode(40.7128, -74.0060);

// Decode returns typed coordinates
const coords: { latitude: number; longitude: number } = encoder.decode(code);

Browser Usage

<script>
// Grid9 is available as a global variable
const code = Grid9.encode(40.7128, -74.0060);
console.log(code); // "Q7KH2BBYF"

// Use in your web app
function shareLocation() {
    navigator.geolocation.getCurrentPosition(position => {
        const code = Grid9.encode(
            position.coords.latitude,
            position.coords.longitude,
            true // human-readable
        );
        document.getElementById('location-code').textContent = code;
    });
}
</script>

API Reference

Core Functions

Function	Description	Returns
encode(lat, lon, humanReadable?)	Encode coordinates to Grid9 code	string
decode(code)	Decode Grid9 code to coordinates	{latitude, longitude}
calculateDistance(code1, code2)	Calculate distance in meters	number
getNeighbors(code)	Get adjacent Grid9 codes	string[]
isValid(code)	Validate Grid9 code format	boolean
getPrecision(lat, lon)	Get precision at coordinates	{x, y, total}

Batch Operations

const CoordinateOperations = require('grid9/operations');

// Batch encode multiple coordinates
const locations = [
    { lat: 40.7128, lon: -74.0060 },  // NYC
    { lat: 51.5074, lon: -0.1278 },   // London
    { lat: 35.6762, lon: 139.6503 }   // Tokyo
];

const codes = CoordinateOperations.batchEncode(locations);
// Result: ["Q7KH2BBYF", "S50MBZX2Y", "PAYMZ39T7"]

// Find nearby locations
const nearby = CoordinateOperations.findNearby(40.7128, -74.0060, 1000);
// Returns all Grid9 codes within 1km radius

Advanced Features

React Integration

import React, { useState } from 'react';
import { encode, decode } from 'grid9';

function LocationSharing() {
    const [code, setCode] = useState('');
    
    const shareCurrentLocation = () => {
        navigator.geolocation.getCurrentPosition(position => {
            const grid9Code = encode(
                position.coords.latitude,
                position.coords.longitude,
                true
            );
            setCode(grid9Code);
        });
    };
    
    return (
        <div>
            <button onClick={shareCurrentLocation}>
                Share Location
            </button>
            {code && <p>Your location: {code}</p>}
        </div>
    );
}

Express.js API

const express = require('express');
const Grid9 = require('grid9');

const app = express();
app.use(express.json());

app.post('/api/encode', (req, res) => {
    try {
        const { latitude, longitude } = req.body;
        const code = Grid9.encode(latitude, longitude);
        res.json({ grid9: code });
    } catch (error) {
        res.status(400).json({ error: error.message });
    }
});

app.get('/api/decode/:code', (req, res) => {
    try {
        const coords = Grid9.decode(req.params.code);
        res.json(coords);
    } catch (error) {
        res.status(400).json({ error: 'Invalid Grid9 code' });
    }
});

Geolocation Utilities

// Calculate bearing between two locations
function getBearing(code1, code2) {
    const coord1 = Grid9.decode(code1);
    const coord2 = Grid9.decode(code2);
    
    const dLon = (coord2.longitude - coord1.longitude) * Math.PI / 180;
    const lat1 = coord1.latitude * Math.PI / 180;
    const lat2 = coord2.latitude * Math.PI / 180;
    
    const y = Math.sin(dLon) * Math.cos(lat2);
    const x = Math.cos(lat1) * Math.sin(lat2) -
              Math.sin(lat1) * Math.cos(lat2) * Math.cos(dLon);
    
    const bearing = Math.atan2(y, x) * 180 / Math.PI;
    return (bearing + 360) % 360;
}

Performance

Testing

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Generate coverage report
npm run test:coverage

# Run linting
npm run lint

Browser Compatibility

• Chrome 60+ ✓
• Firefox 55+ ✓
• Safari 11+ ✓
• Edge 79+ ✓
• Node.js 14+ ✓

TypeScript Support

Grid9 includes comprehensive TypeScript definitions:

// Type definitions are automatically included
import { Grid9Code, Coordinates, PrecisionInfo } from 'grid9/types';

// Use typed interfaces
function processLocation(coords: Coordinates): Grid9Code {
    return encode(coords.latitude, coords.longitude);
}

// Type-safe precision information
const precision: PrecisionInfo = getPrecision(40.7128, -74.0060);
console.log(`Precision: ${precision.total}m`);

Common Use Cases

Location Sharing App

// Generate shareable location links
function createLocationLink(latitude, longitude) {
    const code = Grid9.encode(latitude, longitude, true);
    return `https://yourapp.com/location/${code}`;
}

// Parse location from URL
function parseLocationLink(url) {
    const code = url.split('/').pop();
    if (Grid9.isValid(code)) {
        return Grid9.decode(code);
    }
    throw new Error('Invalid location code');
}

Geofencing

// Check if location is within radius
function isWithinRadius(centerCode, checkCode, radiusMeters) {
    const distance = Grid9.calculateDistance(centerCode, checkCode);
    return distance <= radiusMeters;
}

// Monitor location changes
function monitorLocation(targetCode, callback) {
    navigator.geolocation.watchPosition(position => {
        const currentCode = Grid9.encode(
            position.coords.latitude,
            position.coords.longitude
        );
        const distance = Grid9.calculateDistance(targetCode, currentCode);
        callback(currentCode, distance);
    });
}

View on GitHub Back to Home