tz-at-point 1.0.0

package/dist/cli.js

@@ -0,0 +1,396 @@
+#!/usr/bin/env node
+import { randomUUID } from 'node:crypto';
+import { accessSync, closeSync, constants, existsSync, fchmodSync, fsyncSync, lstatSync, openSync, readFileSync, readlinkSync, realpathSync, renameSync, rmSync, statSync, writeFileSync, } from 'node:fs';
+import { basename, dirname, join, resolve as resolvePath } from 'node:path';
+import { parseArgs } from 'node:util';
+import { keyOf, parseKey } from './key.js';
+import { pointsFromCsv, pointsFromJson } from './points.js';
+import { resolve } from './radius.js';
+import { formatTable, isRadius, isZone, MAX_RADIUS, RADIUS_STEP, readTable, tableGeoTz, tableMaxRadius } from './table.js';
+import { printable } from './text.js';
+const USAGE = `usage:
+  tz-at-point build <points.json|points.csv> -o <zones.json> [--check | --refresh] [--max-radius 250]
+  tz-at-point check <zones.json> [--raster]
+  tz-at-point --version`;
+/** A mistake at the command line. Its message is tz-at-point's own multi-line text, so newlines survive printing. */
+class UsageError extends Error {
+}
+/**
+ * parseArgs with its errors rewritten. Node's own messages explain positionals and `--x=-y` syntax at
+ * length, one of them with an unterminated quote, and they would be printed under tz-at-point's name.
+ */
+function parse(args, options) {
+    try {
+        return parseArgs({ args, allowPositionals: true, options });
+    }
+    catch (err) {
+        const { code, message } = err;
+        // Node quotes the option as '-o, --out <value>' or '--frobnicate'. Name the long form; and the
+        // unknown-option text is the user's own, so it is escaped before it joins a multi-line message.
+        const quoted = /'([^']*)'/.exec(message)?.[1] ?? '';
+        const raw = /--[^\s,]+/.exec(quoted)?.[0] ?? /-[^\s,]+/.exec(quoted)?.[0] ?? 'an option';
+        // Some of Node's messages quote only the short alias; name the long option it stands for.
+        const long = raw.length === 2 ? Object.entries(options).find(([, o]) => o.short === raw[1])?.[0] : undefined;
+        const option = printable(long ? `--${long}` : raw);
+        if (code === 'ERR_PARSE_ARGS_UNKNOWN_OPTION')
+            throw new UsageError(`unknown option ${option}\n${USAGE}`);
+        if (code === 'ERR_PARSE_ARGS_INVALID_OPTION_VALUE') {
+            throw new UsageError(message.includes('does not take an argument') ? `${option} does not take a value` : `${option} needs a value`);
+        }
+        throw err;
+    }
+}
+const READ_FAILURES = {
+    ENOENT: 'no such file or directory', EISDIR: 'is a directory', ENOTDIR: 'not a directory', EACCES: 'permission denied', EPERM: 'permission denied',
+    ELOOP: 'symlink loop', ENAMETOOLONG: 'name too long',
+};
+const WRITE_FAILURES = { ...READ_FAILURES, ENOENT: 'no such directory', EACCES: 'not writable', EPERM: 'not writable' };
+/** A filesystem failure as a sentence about the user's path, not an errno and a syscall. */
+function described(err, path, reasons = READ_FAILURES) {
+    const reason = reasons[err.code ?? ''];
+    return reason ? new Error(`${path}: ${reason}`) : err;
+}
+const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
+const verb = (n, singular, plural_) => (n === 1 ? singular : plural_);
+/** A path as it can be pasted into a POSIX shell. */
+const shellQuote = (path) => (/^[\w./-]+$/.test(path) ? path : `'${path.replace(/'/g, `'\\''`)}'`);
+/** Print lines made from input safely, at most 20, then how many were left out. */
+function printCapped(lines, print = console.log) {
+    for (const line of lines.slice(0, 20))
+        print(printable(line));
+    if (lines.length > 20)
+        print(`...and ${lines.length - 20} more`);
+}
+/** The installed geo-tz version, recorded in the table so a boundary bump shows up in the diff. */
+function geoTzVersion() {
+    try {
+        // geo-tz does not export ./package.json, so resolve the dataset entry and walk up out of dist/.
+        const entry = new URL(import.meta.resolve('geo-tz/all'));
+        const { name, version } = JSON.parse(readFileSync(new URL('../package.json', entry), 'utf8'));
+        return name === 'geo-tz' && typeof version === 'string' && /^[\w.+-]{1,32}$/.test(version) ? version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function loadFind() {
+    // geo-tz/all, not the default export: the default dataset merges zones that have shared rules
+    // since 1970, and answers Tromsø as Europe/Berlin.
+    const geoTz = await import('geo-tz/all').catch((err) => {
+        if (['ERR_MODULE_NOT_FOUND', 'ERR_PACKAGE_PATH_NOT_EXPORTED'].includes(err?.code)) {
+            throw new Error('this command needs geo-tz 8 or later: npm install --save-dev geo-tz');
+        }
+        throw err;
+    });
+    return (lat, lng) => geoTz.find(lat, lng)[0];
+}
+/** A file's text, without a byte-order mark. */
+function readText(file) {
+    try {
+        return readFileSync(file, 'utf8').replace(/^/, '');
+    }
+    catch (err) {
+        throw described(err, file);
+    }
+}
+function readJson(file) {
+    const text = readText(file);
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        // Not the parser's message: it quotes the file, and the file may not be what the user meant to pass.
+        throw new Error(`${file}: not valid JSON`);
+    }
+}
+function readPoints(file) {
+    const lower = file.toLowerCase();
+    let points;
+    if (lower.endsWith('.json'))
+        points = pointsFromJson(readJson(file));
+    else if (lower.endsWith('.csv'))
+        points = pointsFromCsv(readText(file));
+    else
+        throw new Error(`${file}: points must be a .json or .csv file`);
+    return points;
+}
+/** The real file behind `out` (following a symlink), after checking its directory is writable. */
+function writableTarget(out) {
+    let target;
+    try {
+        // A symlink is followed even when its target does not exist yet, so the link survives the write.
+        const link = lstatSync(out, { throwIfNoEntry: false })?.isSymbolicLink() ? resolvePath(dirname(out), readlinkSync(out)) : out;
+        // statSync rather than existsSync: existsSync answers false to a symlink loop, and the write
+        // would then land on the loop itself.
+        target = statSync(link, { throwIfNoEntry: false }) ? realpathSync(link) : resolvePath(link);
+    }
+    catch (err) {
+        throw described(err, out);
+    }
+    try {
+        accessSync(dirname(target), constants.W_OK);
+    }
+    catch (err) {
+        throw described(err, dirname(target), WRITE_FAILURES);
+    }
+    return target;
+}
+/**
+ * Replace `target` in one rename: an unguessable temp file created exclusively (so nothing planted at
+ * that name is followed), synced, renamed over the target, then the directory synced. A crash or power
+ * loss leaves either the old table or the new one. The target's permissions are kept.
+ */
+function writeAtomically(target, text) {
+    const dir = dirname(target);
+    // Bounded so a long but legal target name cannot push the temp name past NAME_MAX.
+    const temp = join(dir, `.${basename(target).slice(0, 180)}.${randomUUID().slice(0, 8)}.tmp`);
+    const fd = openSync(temp, 'wx', 0o644);
+    try {
+        // Node's permission model disables both of these; the rename still makes the swap atomic.
+        if (existsSync(target))
+            tolerate(() => fchmodSync(fd, statSync(target).mode & 0o777));
+        writeFileSync(fd, text);
+        tolerate(() => fsyncSync(fd));
+    }
+    catch (err) {
+        closeSync(fd);
+        rmSync(temp, { force: true });
+        throw err;
+    }
+    closeSync(fd);
+    try {
+        renameSync(temp, target);
+    }
+    catch (err) {
+        rmSync(temp, { force: true });
+        throw err;
+    }
+    tolerate(() => {
+        const dirFd = openSync(dir, 'r');
+        try {
+            fsyncSync(dirFd);
+        }
+        finally {
+            closeSync(dirFd);
+        }
+    });
+}
+/** Durability extras that some environments forbid (Node's permission model, odd filesystems). */
+function tolerate(action) {
+    try {
+        action();
+    }
+    catch (err) {
+        const code = err.code;
+        if (code !== 'ERR_ACCESS_DENIED' && code !== 'EPERM' && code !== 'EINVAL' && code !== 'ENOTSUP')
+            throw err;
+    }
+}
+async function build(args) {
+    const { values, positionals } = parse(args, {
+        out: { type: 'string', short: 'o' },
+        check: { type: 'boolean' },
+        refresh: { type: 'boolean' },
+        'max-radius': { type: 'string', default: '250' },
+        help: { type: 'boolean', short: 'h' },
+    });
+    if (values.help) {
+        console.log(USAGE);
+        return 0;
+    }
+    const [input] = positionals;
+    const { out } = values;
+    if (!input || !out || positionals.length > 1)
+        throw new UsageError(USAGE);
+    if (values.check && values.refresh)
+        throw new Error('--check and --refresh cannot be combined');
+    const maxRadius = /^\d+$/.test(values['max-radius']) ? Number(values['max-radius']) : NaN;
+    if (!isRadius(maxRadius))
+        throw new Error(`--max-radius must be a multiple of ${RADIUS_STEP} from 0 to ${MAX_RADIUS}`);
+    const exists = existsSync(out);
+    const readCommitted = () => (existsSync(out) ? readTable(readJson(out), out) : []);
+    const table = new Map(readCommitted().map((e) => [e.key, [e.zone, e.radius]]));
+    const builtWith = exists ? tableMaxRadius(readJson(out)) : undefined;
+    // Radii mean nothing without the cap they were probed under, so a different --max-radius re-resolves.
+    const reResolve = values.refresh || (builtWith !== undefined && builtWith !== maxRadius);
+    const points = readPoints(input).map((p) => ({ ...p, key: keyOf(p.lat, p.lng) }));
+    const added = points.filter((p) => !table.has(p.key));
+    const todo = new Set(added.map((p) => p.key));
+    if (reResolve)
+        for (const key of table.keys())
+            todo.add(key);
+    if (values.check) {
+        if (exists && todo.size === 0) {
+            console.log(`up to date: ${plural(table.size, 'point')}`);
+            return 0;
+        }
+        console.log(printable(exists ? `${plural(todo.size, 'point')} missing from ${out}:` : `${out} does not exist yet`));
+        printCapped([...todo].sort().map((key) => `  ${key}`));
+        const sameRadius = values['max-radius'] === '250' ? '' : ` --max-radius ${maxRadius}`;
+        console.log(printable(`run: npx tz-at-point build ${shellQuote(input)} -o ${shellQuote(out)}${sameRadius}`));
+        return 1;
+    }
+    const warnings = new Set();
+    // An empty table is a legitimate first commit, so it is written; but a header with no rows, or `[]`,
+    // is also what the wrong file looks like, and silence would send every lookup quietly to the raster.
+    // A table that already has entries keeps answering them, so there is nothing to warn about then.
+    if (points.length === 0 && table.size === 0)
+        warnings.add(`warning: ${input} has no points, so ${out} answers nothing`);
+    let geoTz;
+    if (todo.size > 0 || !exists) {
+        const target = writableTarget(out);
+        const before = new Map(table);
+        if (todo.size > 0) {
+            const find = await loadFind();
+            geoTz = geoTzVersion();
+            for (const key of todo) {
+                const [zone, radius] = resolve(find, ...parseKey(key), maxRadius);
+                if (!zone)
+                    throw new Error(`no zone found for ${key}`);
+                // Checked before anything is written, not only when the table is read back afterwards.
+                if (!isZone(zone))
+                    throw new Error(`${key}: geo-tz returned an invalid zone name`);
+                table.set(key, [zone, radius]);
+            }
+            // The table answers for the rounded key. Within a few metres of a border the point itself can be across it.
+            for (const p of added) {
+                const zone = find(p.lat, p.lng);
+                const [keyZone] = table.get(p.key);
+                if (zone !== keyZone)
+                    warnings.add(`warning: ${p.lat},${p.lng} is in ${zone}, but its key ${p.key} is in ${keyZone}; lookups there answer ${keyZone}`);
+            }
+        }
+        // Another build may have written between our read and this write: merge with whatever is on disk now,
+        // keeping our freshly resolved entries, and confirm the file we leave behind holds all of them.
+        for (let attempt = 1;; attempt++) {
+            for (const e of readCommitted())
+                if (!table.has(e.key))
+                    table.set(e.key, [e.zone, e.radius]);
+            // Lineage describes the whole table, so only a run that resolved every entry may stamp it. A partial
+            // build keeps what is recorded and says so, rather than claiming entries it never touched are fresh.
+            const resolvedEverything = !exists || reResolve;
+            const recorded = exists ? tableGeoTz(readJson(out)) : undefined;
+            const lineage = resolvedEverything ? geoTz : recorded;
+            if (!resolvedEverything && recorded && geoTz && recorded !== geoTz) {
+                warnings.add(`warning: ${out} still records geo-tz ${recorded}; new points were resolved with ${geoTz}; run --refresh to re-resolve the rest`);
+            }
+            writeAtomically(target, formatTable(table, maxRadius, lineage));
+            const committed = new Map(readCommitted().map((e) => [e.key, `${e.zone},${e.radius}`]));
+            const lost = [...table].filter(([key, [zone, radius]]) => committed.get(key) !== `${zone},${radius}`);
+            if (lost.length === 0)
+                break;
+            if (attempt === 5)
+                throw new Error(`${out} kept changing underneath this build; run it again`);
+        }
+        const changed = [...before].filter(([key, [zone, radius]]) => table.get(key)[0] !== zone || table.get(key)[1] !== radius).length;
+        const detail = reResolve ? `, ${changed} changed` : '';
+        const what = reResolve && !values.refresh ? `re-resolved at --max-radius ${maxRadius}: ` : '';
+        console.log(printable(`${what}wrote ${out}: ${plural(table.size, 'point')} (${todo.size} resolved${detail})`));
+    }
+    else {
+        console.log(`up to date: ${plural(table.size, 'point')}`);
+    }
+    // A radius-0 entry still answers its whole ~11m key cell, including any part of it across the border.
+    // A radius of 0 that came from --max-radius 0 says nothing about borders, so it earns no warning.
+    for (const p of maxRadius === 0 ? [] : points) {
+        const [zone, radius] = table.get(p.key);
+        if (radius === 0)
+            warnings.add(`warning: ${p.key} is within 10m of another zone; lookups that round to it answer ${zone}, even from across the border`);
+    }
+    printCapped([...warnings], console.error);
+    return 0;
+}
+async function check(args) {
+    const { values, positionals } = parse(args, { raster: { type: 'boolean' }, help: { type: 'boolean', short: 'h' } });
+    if (values.help) {
+        console.log(USAGE);
+        return 0;
+    }
+    if (positionals.length !== 1)
+        throw new UsageError(USAGE);
+    const [file] = positionals;
+    const raw = readJson(file);
+    const entries = readTable(raw, file);
+    const find = await loadFind();
+    const builtWith = tableGeoTz(raw);
+    const installed = geoTzVersion();
+    if (builtWith && installed && builtWith !== installed) {
+        console.log(`built with geo-tz ${builtWith}, checked against ${installed}`);
+    }
+    else if (builtWith) {
+        console.log(`built with geo-tz ${builtWith}`);
+    }
+    const unknownZones = [];
+    for (const zone of new Set(entries.map((e) => e.zone))) {
+        try {
+            new Intl.DateTimeFormat('en', { timeZone: zone });
+        }
+        catch {
+            unknownZones.push(`FAIL ${zone}: not a zone this runtime's Intl accepts`);
+        }
+    }
+    const stale = [];
+    for (const { key, lat, lng, zone, radius } of entries) {
+        const [truth, safe] = resolve(find, lat, lng, radius);
+        if (truth !== zone)
+            stale.push(`FAIL ${key}: table says ${zone}, polygons say ${truth}`);
+        else if (safe < radius)
+            stale.push(`FAIL ${key}: radius ${radius}m reaches another zone`);
+    }
+    // What the raster alone would answer for these same points: the case for keeping the table at all.
+    if (values.raster) {
+        const { default: tzlookup } = await import('@photostructure/tz-lookup');
+        // Sampled across the year ahead, so a zone that diverges only for part of it (Ramadan in Casablanca,
+        // a southern-hemisphere summer) is not reported as harmless. Unknown zones count as different.
+        const quarters = [0, 3, 6, 9].map((months) => { const d = new Date(); d.setMonth(d.getMonth() + months); return d; });
+        const offsets = (zone) => {
+            try {
+                return quarters.map((d) => new Intl.DateTimeFormat('en', { timeZone: zone, timeZoneName: 'longOffset' }).format(d)).join();
+            }
+            catch {
+                return `unknown:${zone}`;
+            }
+        };
+        const differing = entries.map((e) => ({ e, raster: tzlookup(e.lat, e.lng) })).filter(({ e, raster }) => raster !== e.zone);
+        const shifted = differing.filter(({ e, raster }) => offsets(raster) !== offsets(e.zone));
+        console.log(`raster: ${differing.length} of ${plural(entries.length, 'point')} ${verb(differing.length, 'disagrees', 'disagree')} with the table, ${shifted.length} by a different UTC offset`);
+        printCapped(differing.map(({ e, raster }) => `  ${e.key}: raster says ${raster}, table says ${e.zone}`));
+    }
+    if (unknownZones.length === 0 && stale.length === 0) {
+        console.log(`ok: ${plural(entries.length, 'point')} ${verb(entries.length, 'matches', 'match')} the polygons`);
+        return 0;
+    }
+    printCapped([...unknownZones, ...stale]);
+    if (unknownZones.length)
+        console.log("fix: update Node; its timezone data doesn't know these zones");
+    if (stale.length)
+        console.log('fix: rebuild the table with --refresh');
+    return 1;
+}
+/** This package's own version, from the package.json one directory up from dist/ and from src/ alike. */
+const ownVersion = () => JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+async function main([command, ...args]) {
+    if (command === '--help' || command === '-h') {
+        console.log(USAGE);
+        return 0;
+    }
+    if (command === '--version') {
+        console.log(ownVersion());
+        return 0;
+    }
+    try {
+        if (command === 'build')
+            return await build(args);
+        if (command === 'check')
+            return await check(args);
+        throw new UsageError(USAGE);
+    }
+    catch (err) {
+        // A usage error is several lines of tz-at-point's own text, so its newlines are kept. Every other
+        // message can carry a path or file content, where a newline would forge a log line.
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(`tz-at-point: ${printable(message, err instanceof UsageError)}`);
+        return 2;
+    }
+}
+process.exitCode = await main(process.argv.slice(2));

package/dist/geo.d.ts

@@ -0,0 +1,7 @@
+export declare const RAD: number;
+/** Remainder with the sign of the divisor, so negative values wrap around. */
+export declare const mod: (a: number, n: number) => number;
+/** Great-circle distance in metres. */
+export declare function metres(aLat: number, aLng: number, bLat: number, bLng: number): number;
+/** The point `distance` metres from `lat,lng` along `bearing` degrees, longitude wrapped to [-180, 180). */
+export declare function destination(lat: number, lng: number, distance: number, bearing: number): [number, number];

package/dist/geo.js

@@ -0,0 +1,19 @@
+const R = 6_371_008.8;
+export const RAD = Math.PI / 180;
+/** Remainder with the sign of the divisor, so negative values wrap around. */
+export const mod = (a, n) => ((a % n) + n) % n;
+/** Great-circle distance in metres. */
+export function metres(aLat, aLng, bLat, bLng) {
+    const h = Math.sin(((bLat - aLat) * RAD) / 2) ** 2
+        + Math.cos(aLat * RAD) * Math.cos(bLat * RAD) * Math.sin(((bLng - aLng) * RAD) / 2) ** 2;
+    return 2 * R * Math.asin(Math.sqrt(Math.min(1, h)));
+}
+/** The point `distance` metres from `lat,lng` along `bearing` degrees, longitude wrapped to [-180, 180). */
+export function destination(lat, lng, distance, bearing) {
+    const d = distance / R;
+    const b = bearing * RAD;
+    const p1 = lat * RAD;
+    const p2 = Math.asin(Math.sin(p1) * Math.cos(d) + Math.cos(p1) * Math.sin(d) * Math.cos(b));
+    const l2 = lng * RAD + Math.atan2(Math.sin(b) * Math.sin(d) * Math.cos(p1), Math.cos(d) - Math.sin(p1) * Math.sin(p2));
+    return [p2 / RAD, mod(l2 / RAD + 180, 360) - 180];
+}

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+import type { Lookup, Options } from './lookup.ts';
+/**
+ * Build a lookup from a table made by `npx tz-at-point build points.json -o zones.json`.
+ *
+ * Call it once, at module scope, with the table imported as JSON so your bundler embeds it; the lookup
+ * then reads no files, which is what makes it safe in serverless functions. Points the table doesn't
+ * cover are answered by a bundled raster unless you pass `fallback`. The table is validated here (it is
+ * typed `unknown` because JSON imports are typed loosely): a malformed table throws a TypeError at
+ * startup. The returned function never throws.
+ *
+ * @example
+ * import { createLookup } from 'tz-at-point';
+ * import table from './zones.json' with { type: 'json' };
+ *
+ * const zoneAt = createLookup(table);
+ *
+ * const { zone } = zoneAt(51.5561, -0.2794); // 'Europe/London'
+ * const local = zone && new Intl.DateTimeFormat('en-GB', { timeZone: zone, timeStyle: 'short' }).format(new Date('2026-11-14T19:45:00Z')); // '19:45'
+ */
+export declare const createLookup: (table: unknown, options?: Options | null) => Lookup;
+export type { Lookup, Options, Result, Source } from './lookup.ts';
+export { pointKey } from './key.ts';
+export type { Table } from './table.ts';

package/dist/index.js

@@ -0,0 +1,33 @@
+/**
+ * tz-at-point: the IANA timezone at a coordinate, exact at the points you care about, with no file reads at
+ * runtime.
+ *
+ * Workflow: list your points, run `npx tz-at-point build points.json -o zones.json` (needs geo-tz as a dev
+ * dependency), commit zones.json, import it as JSON and call `createLookup(table)` once.
+ *
+ * Coding agents: the full guide is in this package at `skills/tz-at-point/SKILL.md`.
+ *
+ * @packageDocumentation
+ */
+import tzlookup from '@photostructure/tz-lookup';
+import { createLookup as fromTable } from './lookup.js';
+/**
+ * Build a lookup from a table made by `npx tz-at-point build points.json -o zones.json`.
+ *
+ * Call it once, at module scope, with the table imported as JSON so your bundler embeds it; the lookup
+ * then reads no files, which is what makes it safe in serverless functions. Points the table doesn't
+ * cover are answered by a bundled raster unless you pass `fallback`. The table is validated here (it is
+ * typed `unknown` because JSON imports are typed loosely): a malformed table throws a TypeError at
+ * startup. The returned function never throws.
+ *
+ * @example
+ * import { createLookup } from 'tz-at-point';
+ * import table from './zones.json' with { type: 'json' };
+ *
+ * const zoneAt = createLookup(table);
+ *
+ * const { zone } = zoneAt(51.5561, -0.2794); // 'Europe/London'
+ * const local = zone && new Intl.DateTimeFormat('en-GB', { timeZone: zone, timeStyle: 'short' }).format(new Date('2026-11-14T19:45:00Z')); // '19:45'
+ */
+export const createLookup = (table, options) => fromTable(table, { fallback: options?.fallback === undefined ? tzlookup : options.fallback });
+export { pointKey } from './key.js';

package/dist/key.d.ts

@@ -0,0 +1,15 @@
+/** `[lat, lng]` if both are finite numbers on the globe, otherwise null. */
+export declare function latLng(lat: unknown, lng: unknown): [number, number] | null;
+/** The table key for a valid coordinate: rounded to 4 decimals (~11m), with -180 and 180 as one meridian. */
+export declare function keyOf(lat: number, lng: number): string;
+/** The coordinate a key was made from (NaN parts if it is not a key). */
+export declare const parseKey: (key: string) => [number, number];
+/**
+ * The table key for a coordinate: latitude and longitude rounded to 4 decimals, or `null` if either is
+ * not a finite number in range. Use it to check whether a point is already in a table.
+ *
+ * @example
+ * pointKey(51.55614, -0.27936); // '51.5561,-0.2794'
+ * pointKey('51.5', 0);          // null
+ */
+export declare function pointKey(lat: unknown, lng: unknown): string | null;

package/dist/key.js

@@ -0,0 +1,28 @@
+/** `[lat, lng]` if both are finite numbers on the globe, otherwise null. */
+export function latLng(lat, lng) {
+    return typeof lat === 'number' && typeof lng === 'number' && Math.abs(lat) <= 90 && Math.abs(lng) <= 180 ? [lat, lng] : null;
+}
+const fixed = (v) => {
+    const s = v.toFixed(4);
+    // Rounding, not the input, produces negative zero: -0.000004 must key the same as 0.000004.
+    return s === '-0.0000' ? '0.0000' : s;
+};
+/** The table key for a valid coordinate: rounded to 4 decimals (~11m), with -180 and 180 as one meridian. */
+export function keyOf(lat, lng) {
+    const lngKey = fixed(lng);
+    return `${fixed(lat)},${lngKey === '-180.0000' ? '180.0000' : lngKey}`;
+}
+/** The coordinate a key was made from (NaN parts if it is not a key). */
+export const parseKey = (key) => key.split(',').map(Number);
+/**
+ * The table key for a coordinate: latitude and longitude rounded to 4 decimals, or `null` if either is
+ * not a finite number in range. Use it to check whether a point is already in a table.
+ *
+ * @example
+ * pointKey(51.55614, -0.27936); // '51.5561,-0.2794'
+ * pointKey('51.5', 0);          // null
+ */
+export function pointKey(lat, lng) {
+    const point = latLng(lat, lng);
+    return point && keyOf(...point);
+}

package/dist/lookup.d.ts

@@ -0,0 +1,55 @@
+import { type Entry } from './table.ts';
+/**
+ * Where an answer came from.
+ * - `table`: the coordinate rounds to a table key (4 decimals, a cell about 11m across).
+ * - `table-near`: within the safe radius of the nearest covering table entry. A normal, correct answer.
+ * - `raster`: not covered by the table, so the fallback answered. Approximate near borders.
+ */
+export type Source = 'table' | 'table-near' | 'raster';
+/**
+ * A lookup's answer. `zone` is an IANA name such as `Europe/London`; it is `null` only when the input is
+ * not a coordinate, or no fallback is configured (or it had no answer) for a point outside the table.
+ */
+export type Result = {
+    zone: string;
+    source: Source;
+} | {
+    zone: null;
+    source: null;
+};
+/** Answers the IANA zone at a coordinate. Never throws, whatever it is passed. */
+export type Lookup = (lat: unknown, lng: unknown) => Result;
+export interface Options {
+    /**
+     * Answers points the table does not cover. Imported from `tz-at-point`, this defaults to
+     * `@photostructure/tz-lookup` (a 73KB raster, no file reads); imported from `tz-at-point/core`, it defaults
+     * to nothing, so the raster never enters your bundle. Answers that are not zone names are ignored.
+     *
+     * @example
+     * const tableOnly = createLookup(table, { fallback: null });
+     */
+    fallback?: ((lat: number, lng: number) => string | null | undefined) | null;
+}
+/** Every cell an entry's radius reaches. Exported for tests. */
+export declare function cellsReached({ lat, lng, radius }: Entry): Generator<number, void, unknown>;
+/**
+ * Build a lookup that answers only from the table (`tz-at-point/core`). `tz-at-point` re-exports this with the
+ * raster fallback applied; import from here when you never want that 73KB in your bundle.
+ *
+ * Build a lookup from a table made by `npx tz-at-point build points.json -o zones.json`.
+ *
+ * Call it once, at module scope, with the table imported as JSON so your bundler embeds it; the lookup
+ * then reads no files, which is what makes it safe in serverless functions. The table is validated here
+ * (it is typed `unknown` because JSON imports are typed loosely): a malformed table throws a TypeError at
+ * startup. The returned function never throws.
+ *
+ * @example
+ * import { createLookup } from 'tz-at-point';
+ * import table from './zones.json' with { type: 'json' };
+ *
+ * const zoneAt = createLookup(table);
+ *
+ * const { zone } = zoneAt(51.5561, -0.2794); // 'Europe/London'
+ * const local = zone && new Intl.DateTimeFormat('en-GB', { timeZone: zone, timeStyle: 'short' }).format(new Date('2026-11-14T19:45:00Z')); // '19:45'
+ */
+export declare function createLookup(table: unknown, options?: Options | null): Lookup;