lltz 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Utkarsh Kukreti
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,109 @@
+# lltz (Latitude & Longitude → Time Zone)
+
+A high-performance, memory-efficient offline timezone lookup library for TypeScript using a custom binary format and quadtree spatial indexing.
+
+This library uses GeoJSON data from [timezone-boundary-builder](https://github.com/evansiroky/timezone-boundary-builder).
+
+## Features
+
+- **Fast**: Performs **25-35 million lookups per second** (~30-40ns per op) on an Apple M4 Pro CPU.
+- **Tiny Memory Footprint**: Operates directly on raw binary data (ArrayBuffer/Uint8Array). Memory usage is limited to the LLTZ binary file size (approximately **26-44MiB**), with no additional object overhead.
+- **Zero Dependencies**: A lightweight, standalone TypeScript library with no external runtime dependencies.
+- **Universal**: Runs in both server (Node.js, Bun) and client (browser) environments.
+- **High Accuracy**: Validated to match [`geo-tz`](https://www.npmjs.com/package/geo-tz) results in **>99.99%** of cases.
+
+## Usage
+
+### Installation
+
+```bash
+pnpm add lltz # or npm, yarn, bun
+```
+
+### Data
+
+Three data variants are available, as described in the [timezone-boundary-builder README](https://github.com/evansiroky/timezone-boundary-builder#readme). We recommend `timezones.lltz` for the most comprehensive coverage, which is included in the NPM package.
+
+The other variants, `timezones-1970.lltz` and `timezones-now.lltz`, can be downloaded from the [releases page](https://github.com/utkarshkukreti/lltz/releases) and loaded similarly.
+
+### Node.js / Bun
+
+```typescript
+import fs from 'node:fs'
+
+import * as Lltz from 'lltz'
+
+const buffer = fs.readFileSync(new URL(import.meta.resolve('lltz/data/timezones.lltz')))
+// ↳ or fs.readFileSync('node_modules/lltz/data/timezones.lltz')
+const lookup = Lltz.make(buffer)
+
+const timezones = lookup(40.7128, -74.006) // New York
+console.log(timezones) // ['America/New_York']
+```
+
+### Browser
+
+```typescript
+import * as Lltz from 'lltz'
+
+const response = await fetch('/path/to/timezones.lltz')
+const arrayBuffer = await response.arrayBuffer()
+const lookup = Lltz.make(arrayBuffer)
+
+console.log(lookup(40.7128, -74.006)) // ['America/New_York']
+```
+
+## Architecture
+
+### Binary Format (.lltz)
+
+The LLTZ binary file format is designed for efficient querying on raw bytes. It consists of the following sections:
+
+- **Header**: The first eight bytes are `LLTZ1\0\0\0`.
+- **Timezone Strings**: A null-terminated list of timezone IDs.
+- **Grid Index**: A 180x360 coarse grid (1-degree resolution) for O(1) access.
+- **QuadTree Nodes**: Hierarchical spatial subdivision for complex regions.
+- **Polygon Data**: Compressed relative integer coordinates for final containment checks.
+
+### Builder & Runtime
+
+- **Builder (Python)**: Normalizes `timezone-boundary-builder` GeoJSON files to a 1,000,000 scale grid and constructs the spatial index.
+- **Runtime (TypeScript)**: Performs an initial O(1) lookup using a coarse grid. For points near boundaries, it falls back to precise point-in-polygon ray-casting. Oceans default to `Etc/GMT` offsets based on 15-degree longitude bands.
+
+## Development
+
+### Data Preparation
+
+To download the latest GeoJSON data and convert it into the optimized LLTZ binary format, run:
+
+> Requires [uv](https://docs.astral.sh/uv/) to be installed.
+
+```bash
+make -j
+```
+
+### Running Tests
+
+Test lookup results against the `geo-tz` package:
+
+```bash
+pnpm test
+```
+
+### Benchmarks
+
+Benchmark performance against the `geo-tz` package:
+
+```bash
+pnpm bench
+```
+
+Benchmark memory usage against the `geo-tz` package:
+
+```bash
+pnpm bench:memory
+```
+
+## License
+
+MIT for the code, [ODbL for the data](https://github.com/evansiroky/timezone-boundary-builder).

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+//#region src/index.d.ts
+type Lookup =
+/**
+ * Returns an array of timezone IDs for the given latitude and longitude.
+ * @param latitude - The latitude of the point in degrees (-90 to 90).
+ * @param longitude - The longitude of the point in degrees (-180 to 180).
+ * @throws An error if the latitude or longitude is out of range.
+ * @returns An array of timezone IDs. For points in unmapped areas (e.g., oceans), returns
+ * 'Etc/GMT'-based timezones.
+ */
+(latitude: number, longitude: number) => string[];
+/**
+ * Creates a timezone lookup function from the provided binary data.
+ *
+ * @param arrayBufferOrUint8Array - The binary data containing the timezone database (LLTZ format).
+ * @returns {Lookup} A timezone lookup function.
+ * @throws An error if the binary data is invalid.
+ */
+declare const make: (arrayBufferOrUint8Array: ArrayBuffer | Uint8Array) => Lookup;
+//#endregion
+export { Lookup, make };

package/dist/index.js

@@ -0,0 +1,186 @@
+//#region src/index.ts
+/**
+* The expected header for the LLTZ binary file format.
+*/
+const HEADER = "LLTZ1\0\0\0";
+/**
+* The scale factor used to convert floating-point coordinates to integers in the binary format.
+* 1 degree = 1,000,000 units.
+*/
+const SCALE = 1e6;
+/**
+* Default timezones returned when querying latitude 90 (North Pole).
+* Since lines of longitude converge at the poles, all GMT offsets are technically valid.
+*/
+const DEFAULT_LATITUDE_90 = [
+	"Etc/GMT",
+	...Array.from({ length: 12 }, (_, i) => `Etc/GMT+${i + 1}`),
+	...Array.from({ length: 12 }, (_, i) => `Etc/GMT-${i + 1}`)
+];
+/**
+* Default timezones returned when querying longitude -180 or 180 (International Date Line).
+* Can be either GMT+12 or GMT-12.
+*/
+const DEFAULT_LONGITUDE_ABS_180 = ["Etc/GMT+12", "Etc/GMT-12"];
+/**
+* Checks if the point (x, y) is inside or on the boundary of a polygon ring using the ray casting
+* algorithm.
+* @param dataView - The DataView of the binary data.
+* @param x - The integer-scaled x coordinate of the point relative to the polygon's base x.
+* @param y - The integer-scaled y coordinate of the point relative to the polygon's base y.
+* @param offset - The offset to the start of the polygon ring.
+* @returns A tuple containing a status ('in' | 'on' | false) indicating if the point is inside, on
+* the boundary, or outside the ring, and the offset to the next polygon ring.
+*/
+const isPointInOrOnRing = (dataView, x, y, offset) => {
+	const pointsCount = dataView.getUint16(offset, true);
+	offset += 2;
+	let xPrevious = dataView.getUint16(offset, true);
+	offset += 2;
+	let yPrevious = dataView.getUint16(offset, true);
+	offset += 2;
+	const xFirst = xPrevious;
+	const yFirst = yPrevious;
+	let inside = false;
+	for (let i = 1; i <= pointsCount; i++) {
+		let xCurrent = xFirst;
+		let yCurrent = yFirst;
+		if (i < pointsCount) {
+			xCurrent = dataView.getUint16(offset, true);
+			offset += 2;
+			yCurrent = dataView.getUint16(offset, true);
+			offset += 2;
+		}
+		const dx = xCurrent - xPrevious;
+		const dy = yCurrent - yPrevious;
+		const dpx = x - xPrevious;
+		const crossProduct = dx * (y - yPrevious) - dy * dpx;
+		if (crossProduct === 0 && (x >= xPrevious && x <= xCurrent || x >= xCurrent && x <= xPrevious) && (y >= yPrevious && y <= yCurrent || y >= yCurrent && y <= yPrevious)) return ["on", offset];
+		if (yCurrent > y !== yPrevious > y) {
+			if (yCurrent > yPrevious === crossProduct > 0) inside = !inside;
+		}
+		xPrevious = xCurrent;
+		yPrevious = yCurrent;
+	}
+	return [inside ? "in" : false, offset];
+};
+/**
+* Checks if the point (x, y) is inside a polygon, accounting for holes (inner rings).
+* @param dataView - The DataView of the binary data.
+* @param x - The integer-scaled x coordinate of the point.
+* @param y - The integer-scaled y coordinate of the point.
+* @param offset - The offset to the start of the polygon.
+* @param xMinBase - The integer-scaled base x coordinate of the polygon.
+* @param yMinBase - The integer-scaled base y coordinate of the polygon.
+* @returns A tuple containing a boolean indicating if the point is inside or on the boundary of the
+* polygon and the offset to the next polygon.
+*/
+const isPointInPolygon = (dataView, x, y, offset, xMinBase, yMinBase) => {
+	const size = dataView.getUint16(offset, true);
+	offset += 2;
+	const nextPolygonOffset = offset + size;
+	const ringsCount = dataView.getUint8(offset);
+	offset += 1;
+	const xMin = dataView.getUint16(offset, true) + xMinBase;
+	offset += 2;
+	const xMax = dataView.getUint16(offset, true) + xMinBase;
+	offset += 2;
+	const yMin = dataView.getUint16(offset, true) + yMinBase;
+	offset += 2;
+	const yMax = dataView.getUint16(offset, true) + yMinBase;
+	offset += 2;
+	if (x < xMin || x > xMax || y < yMin || y > yMax) return [false, nextPolygonOffset];
+	const [where, nextRingOffset] = isPointInOrOnRing(dataView, x - xMinBase, y - yMinBase, offset);
+	if (where !== "in") return [where === "on", nextPolygonOffset];
+	offset = nextRingOffset;
+	for (let i = 1; i < ringsCount; i++) {
+		const [where$1, nextRingOffset$1] = isPointInOrOnRing(dataView, x - xMinBase, y - yMinBase, offset);
+		if (where$1 !== false) return [where$1 === "on", nextPolygonOffset];
+		offset = nextRingOffset$1;
+	}
+	return [true, nextPolygonOffset];
+};
+/**
+* Creates a timezone lookup function from the provided binary data.
+*
+* @param arrayBufferOrUint8Array - The binary data containing the timezone database (LLTZ format).
+* @returns {Lookup} A timezone lookup function.
+* @throws An error if the binary data is invalid.
+*/
+const make = (arrayBufferOrUint8Array) => {
+	const bytes = ArrayBuffer.isView(arrayBufferOrUint8Array) ? arrayBufferOrUint8Array : new Uint8Array(arrayBufferOrUint8Array);
+	const dataView = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+	let offset = 0;
+	for (let i = 0; i < 8; i++) if (dataView.getUint8(offset + i) !== HEADER.charCodeAt(i)) throw new Error(`invalid file format: missing header ${JSON.stringify(HEADER)}`);
+	offset += 8;
+	const timezonesLength = dataView.getUint16(offset, true);
+	offset += 2;
+	const timezones = new TextDecoder().decode(bytes.subarray(offset, offset + timezonesLength)).split("\0");
+	offset += timezonesLength;
+	const offsetsOffset = offset;
+	offset += 180 * 360 * 4;
+	const baseOffset = offset;
+	return (latitude, longitude) => {
+		if (latitude < -90 || latitude > 90 || longitude < -180 || longitude > 180) throw new Error(`invalid latitude or longitude: ${latitude}, ${longitude}`);
+		const latitudeIndex = Math.min(latitude + 90 | 0, 179);
+		const longitudeIndex = Math.min(longitude + 180 | 0, 359);
+		let value = dataView.getUint32(offsetsOffset + (latitudeIndex * 360 + longitudeIndex) * 4, true);
+		let tag = value >>> 30;
+		if (tag === 1) return [timezones[value & (1 << 30) - 1]];
+		if (tag !== 0) {
+			const latitudeInteger = (latitude + 90) * SCALE + .5 | 0;
+			const longitudeInteger = (longitude + 180) * SCALE + .5 | 0;
+			let offset$1 = baseOffset;
+			let xMin = longitudeIndex * SCALE;
+			let yMin = latitudeIndex * SCALE;
+			let xMax = xMin + SCALE;
+			let yMax = yMin + SCALE;
+			while (tag === 3) {
+				offset$1 += value & (1 << 30) - 1;
+				const xMid = xMin + xMax >> 1;
+				const yMid = yMin + yMax >> 1;
+				const quadtreeIndex = (latitudeInteger >= yMid ? 1 : 0) << 1 | (longitudeInteger >= xMid ? 1 : 0);
+				value = dataView.getUint32(offset$1 + quadtreeIndex * 4, true);
+				tag = value >>> 30;
+				offset$1 += 16;
+				latitudeInteger >= yMid ? yMin = yMid : yMax = yMid;
+				longitudeInteger >= xMid ? xMin = xMid : xMax = xMid;
+			}
+			if (tag === 1) return [timezones[value & (1 << 30) - 1]];
+			else if (tag === 2) {
+				const output = [];
+				offset$1 += value & (1 << 30) - 1;
+				const count = dataView.getUint8(offset$1);
+				offset$1 += 1;
+				for (let i = 0; i < count; i++) {
+					const index = dataView.getUint16(offset$1, true);
+					offset$1 += 2;
+					const polygonsCount = dataView.getUint8(offset$1);
+					offset$1 += 1;
+					for (let j = 0; j < polygonsCount; j++) {
+						const [isIn, offset_] = isPointInPolygon(dataView, longitudeInteger, latitudeInteger, offset$1, xMin, yMin);
+						offset$1 = offset_;
+						if (isIn) {
+							output.push(timezones[index]);
+							for (let k = j + 1; k < polygonsCount; k++) offset$1 += 2 + dataView.getUint16(offset$1, true);
+							break;
+						}
+					}
+				}
+				if (output.length > 0) return output;
+			}
+		}
+		if (latitude === 90) return DEFAULT_LATITUDE_90;
+		else if (longitude === -180 || longitude === 180) return DEFAULT_LONGITUDE_ABS_180;
+		else {
+			const output = [];
+			const min = Math.ceil(longitude / 15 - .5);
+			const max = Math.floor(longitude / 15 + .5);
+			for (let n = min; n <= max; n++) output.push(n === 0 ? "Etc/GMT" : n > 0 ? `Etc/GMT-${n}` : `Etc/GMT+${-n}`);
+			return output;
+		}
+	};
+};
+
+//#endregion
+export { make };

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "lltz",
+  "version": "0.0.1",
+  "author": "Utkarsh Kukreti <utkarshkukreti@gmail.com>",
+  "description": "A high-performance, memory-efficient offline timezone lookup library for TypeScript using a custom binary format and quadtree spatial indexing.",
+  "keywords": [
+    "geo",
+    "latitude",
+    "longitude",
+    "lookup",
+    "timezone"
+  ],
+  "homepage": "https://github.com/utkarshkukreti/lltz",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/utkarshkukreti/lltz.git"
+  },
+  "bugs": {
+    "url": "https://github.com/utkarshkukreti/lltz/issues"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./data/*": "./data/*"
+  },
+  "files": [
+    "data/timezones.lltz",
+    "dist"
+  ],
+  "devDependencies": {
+    "@ianvs/prettier-plugin-sort-imports": "4.7.0",
+    "@types/node": "24.10.8",
+    "geo-tz": "8.1.5",
+    "prettier": "3.7.4",
+    "tinybench": "6.0.0",
+    "tsdown": "0.19.0",
+    "typescript": "5.9.3"
+  },
+  "scripts": {
+    "build": "tsc && tsdown",
+    "lint": "prettier --check .",
+    "format": "prettier --write .",
+    "test": "node --max-old-space-size=8192 tests/index.ts",
+    "bench": "node benches/index.ts",
+    "bench:memory": "node benches/memory.ts lltz:timezones && node benches/memory.ts geo-tz:timezones"
+  }
+}