lltz 1.0.0 → 1.2.0

package/README.md

@@ -12,6 +12,48 @@ This library uses GeoJSON data from [timezone-boundary-builder](https://github.c
 - **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.
 
+## Performance
+
+The `benches` directory contains performance benchmarks comparing `lltz` with `geo-tz`. These are the performance numbers obtained on Node 24.13.0 on an Apple M4 Pro CPU.
+
+### CPU
+
+```
+$ node benches/index.ts lltz:timezones geo-tz:timezones
+┌─────────┬───────────────────────────────────────────────────┬───────────────────┬────────────────────┬────────────────────────┬────────────────────────┬─────────┐
+│ (index) │ Task name                                         │ Latency avg (ns)  │ Latency med (ns)   │ Throughput avg (ops/s) │ Throughput med (ops/s) │ Samples │
+├─────────┼───────────────────────────────────────────────────┼───────────────────┼────────────────────┼────────────────────────┼────────────────────────┼─────────┤
+│ 0       │ 'lltz: timezones: 1000x <random>'                 │ '41876 ± 0.20%'   │ '41250 ± 1458.0'   │ '24112 ± 0.10%'        │ '24242 ± 851'          │ 23880   │
+│ 1       │ 'lltz: timezones: 1000x <random> in central US'   │ '31205 ± 0.23%'   │ '30791 ± 583.00'   │ '32386 ± 0.07%'        │ '32477 ± 626'          │ 32047   │
+│ 2       │ 'geo-tz: timezones: 1000x <random>'               │ '1809670 ± 8.08%' │ '1270167 ± 425375' │ '819 ± 3.92%'          │ '787 ± 279'            │ 553     │
+│ 3       │ 'geo-tz: timezones: 1000x <random> in central US' │ '237485 ± 1.28%'  │ '231583 ± 4875.0'  │ '4291 ± 0.23%'         │ '4318 ± 91'            │ 4211    │
+└─────────┴───────────────────────────────────────────────────┴───────────────────┴────────────────────┴────────────────────────┴────────────────────────┴─────────┘
+```
+
+lltz is roughly 30x faster than geo-tz for random lookups in the entire world and 7x faster for random lookups in the central US.
+
+### Memory
+
+```
+$ node benches/memory.ts lltz:timezones && node benches/memory.ts geo-tz:timezones
+lltz: timezones
+Δ time: 56.807 ms
+Δ rss: 57.891 MiB
+Δ heapTotal: 4.250 MiB
+Δ heapUsed: 0.824 MiB
+Δ external: 42.179 MiB
+Δ arrayBuffers: 42.015 MiB
+geo-tz: timezones
+Δ time: 1560.153 ms
+Δ rss: 1581.656 MiB
+Δ heapTotal: 1528.344 MiB
+Δ heapUsed: 1431.117 MiB
+Δ external: -1.598 MiB
+Δ arrayBuffers: -1.688 MiB
+```
+
+Loading the data from disk and then querying 1 million random points is 27x faster with lltz than with geo-tz and uses 27x less memory.
+
 ## Usage
 
 ### Installation
@@ -28,6 +70,21 @@ The other variants, `timezones-1970.lltz` and `timezones-now.lltz`, can be downl
 
 ### Node.js / Bun
 
+#### Simple Usage
+
+```typescript
+import * as Lltz from 'lltz/server'
+
+const lookup = Lltz.make() // Automatically loads the built-in timezones.lltz file
+
+const timezones = lookup(40.7128, -74.006) // New York
+console.log(timezones) // ['America/New_York']
+```
+
+#### Manual Data Loading
+
+If you need to use a different data file or have custom requirements:
+
 ```typescript
 import fs from 'node:fs'
 

package/dist/index.js

@@ -94,9 +94,9 @@ const isPointInPolygon = (dataView, x, y, offset, xMinBase, yMinBase) => {
 	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;
+		const [where, nextRingOffset] = isPointInOrOnRing(dataView, x - xMinBase, y - yMinBase, offset);
+		if (where !== false) return [where === "on", nextPolygonOffset];
+		offset = nextRingOffset;
 	}
 	return [true, nextPolygonOffset];
 };
@@ -130,39 +130,39 @@ const make = (arrayBufferOrUint8Array) => {
 		if (tag !== 0) {
 			const latitudeInteger = (latitude + 90) * SCALE + .5 | 0;
 			const longitudeInteger = (longitude + 180) * SCALE + .5 | 0;
-			let offset$1 = baseOffset;
+			let offset = 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;
+				offset += 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);
+				value = dataView.getUint32(offset + quadtreeIndex * 4, true);
 				tag = value >>> 30;
-				offset$1 += 16;
+				offset += 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;
+				offset += value & (1 << 30) - 1;
+				const count = dataView.getUint8(offset);
+				offset += 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;
+					const index = dataView.getUint16(offset, true);
+					offset += 2;
+					const polygonsCount = dataView.getUint8(offset);
+					offset += 1;
 					for (let j = 0; j < polygonsCount; j++) {
-						const [isIn, offset_] = isPointInPolygon(dataView, longitudeInteger, latitudeInteger, offset$1, xMin, yMin);
-						offset$1 = offset_;
+						const [isIn, offset_] = isPointInPolygon(dataView, longitudeInteger, latitudeInteger, offset, xMin, yMin);
+						offset = offset_;
 						if (isIn) {
 							output.push(timezones[index]);
-							for (let k = j + 1; k < polygonsCount; k++) offset$1 += 2 + dataView.getUint16(offset$1, true);
+							for (let k = j + 1; k < polygonsCount; k++) offset += 2 + dataView.getUint16(offset, true);
 							break;
 						}
 					}
@@ -181,6 +181,5 @@ const make = (arrayBufferOrUint8Array) => {
 		}
 	};
 };
-
 //#endregion
-export { make };
+export { make };

package/dist/server.d.ts

@@ -0,0 +1,14 @@
+import { Lookup } from "./index.js";
+
+//#region src/server.d.ts
+/**
+ * Creates a timezone lookup function from the provided binary data.
+ *
+ * @param arrayBufferOrUint8Array - Optional binary data containing the timezone database (LLTZ
+ * format). If not provided, the built-in `timezones.lltz` file will be automatically loaded.
+ * @returns {Lookup} A timezone lookup function.
+ * @throws An error if the binary data is invalid or if the built-in data file cannot be loaded.
+ */
+declare const make: (arrayBufferOrUint8Array?: ArrayBuffer | Uint8Array) => Lookup;
+//#endregion
+export { type Lookup, make };

package/dist/server.js

@@ -0,0 +1,26 @@
+import { make as make$1 } from "./index.js";
+import fs from "node:fs";
+//#region src/server.ts
+const load = () => {
+	try {
+		return fs.readFileSync(new URL(import.meta.resolve("lltz/data/timezones.lltz")));
+	} catch {}
+	try {
+		return fs.readFileSync(new URL("../data/timezones.lltz", import.meta.url));
+	} catch {}
+	try {
+		return fs.readFileSync("node_modules/lltz/data/timezones.lltz");
+	} catch {}
+	throw new Error("failed to load built-in timezones.lltz file");
+};
+/**
+* Creates a timezone lookup function from the provided binary data.
+*
+* @param arrayBufferOrUint8Array - Optional binary data containing the timezone database (LLTZ
+* format). If not provided, the built-in `timezones.lltz` file will be automatically loaded.
+* @returns {Lookup} A timezone lookup function.
+* @throws An error if the binary data is invalid or if the built-in data file cannot be loaded.
+*/
+const make = (arrayBufferOrUint8Array) => make$1(arrayBufferOrUint8Array ?? load());
+//#endregion
+export { make };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lltz",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "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": [
@@ -20,12 +20,13 @@
   },
   "license": "MIT",
   "type": "module",
-  "packageManager": "pnpm@10.28.0",
+  "packageManager": "pnpm@10.32.1",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": "./dist/index.js",
+    "./server": "./dist/server.js",
     "./data/*": "./data/*"
   },
   "files": [
@@ -42,12 +43,12 @@
     "bench:memory": "node benches/memory.ts lltz:timezones && node benches/memory.ts geo-tz:timezones"
   },
   "devDependencies": {
-    "@ianvs/prettier-plugin-sort-imports": "4.7.0",
-    "@types/node": "24.10.8",
-    "geo-tz": "8.1.5",
-    "prettier": "3.7.4",
+    "@ianvs/prettier-plugin-sort-imports": "4.7.1",
+    "@types/node": "24.12.0",
+    "geo-tz": "8.1.6",
+    "prettier": "3.8.1",
     "tinybench": "6.0.0",
-    "tsdown": "0.19.0",
+    "tsdown": "0.21.1",
     "typescript": "5.9.3"
   }
 }