@johnmorrisdotca/kuni 1.6.1 → 1.6.2

package/dist/zones.d.cts

@@ -0,0 +1,66 @@
+import { L as LatLon } from './types-CWqSLWHx.cjs';
+
+/**
+ * A zone, and whether it was worked out rather than read: `estimated` is true where kuni had to choose.
+ *
+ * @example
+ * ```ts
+ * import { subdivisionTimeZone, type ZoneAnswer } from "@johnmorrisdotca/kuni/zones";
+ *
+ * const answer: ZoneAnswer | null = subdivisionTimeZone("CA-BC");
+ * console.log(answer?.zone); // "America/Vancouver"
+ * ```
+ */
+interface ZoneAnswer {
+    /** The IANA zone, "America/Los_Angeles". */
+    zone: string;
+    /** True where kuni chose it (nearest a capital or a point), false where a source names it alone. */
+    estimated: boolean;
+}
+/**
+ * The IANA time zone of a first-level subdivision, by its ISO 3166-2 code: what a map of a country's regions shows.
+ *
+ * In a country with one zone, that zone (`estimated: false`). In a country with several, the zone Wikidata gives the
+ * subdivision where it gives one of the country's zones alone (`estimated: false`); where it gives several (Indiana,
+ * Idaho) or none, the one whose principal city in IANA's zone.tab is nearest the subdivision's capital
+ * (`estimated: true`); and for the few kuni has no point for and Wikidata names no zone of (Beijing, Catalonia), the
+ * zone of the country's capital (`estimated: true`).
+ *
+ * @param code - An ISO 3166-2 code, "US-WA" or "us-wa".
+ * @returns The zone and whether it was estimated; `null` for a code kuni does not list as a first-level subdivision,
+ * or one in a country with no zone.
+ * @example
+ * ```ts
+ * import { subdivisionTimeZone } from "@johnmorrisdotca/kuni/zones";
+ *
+ * console.log(subdivisionTimeZone("US-WA")); // { zone: "America/Los_Angeles", estimated: false }
+ * console.log(subdivisionTimeZone("JP-13")?.zone); // "Asia/Tokyo"
+ * ```
+ */
+declare const subdivisionTimeZone: (code: string) => ZoneAnswer | null;
+/**
+ * The IANA time zone at a point in a country, and whether it is known or estimated.
+ *
+ * A country with one zone gives that zone, `estimated: false`. In a country with several: a point within 30 km of a
+ * zone's principal city in IANA's zone.tab takes that zone (Ciudad Juárez, America/Ciudad_Juarez); any other takes the
+ * zone of the subdivision whose capital or middle is nearest (`subdivisionTimeZone`). Both are `estimated: true`.
+ *
+ * Limits, since kuni has no boundaries: a point near the edge of a state or province can be given its neighbour's
+ * zone; a subdivision split between zones gives its most-populous part's (East Tennessee is given Central time); and a
+ * place that keeps a different rule inside a subdivision is not known (the Navajo Nation keeps daylight saving time in
+ * Arizona). Say "estimated" where it is shown. A map of regions that knows the region asks `subdivisionTimeZone`.
+ *
+ * @param code - The country the point is in, an ISO 3166-1 alpha-2 code in either case.
+ * @param point - The point, `{ lat, lon }` in degrees.
+ * @returns The zone and whether it was estimated; `null` for a code that is not a country or a country with no zone.
+ * @example
+ * ```ts
+ * import { timeZoneAt } from "@johnmorrisdotca/kuni/zones";
+ *
+ * console.log(timeZoneAt("JP", { lat: 43.06, lon: 141.35 })); // { zone: "Asia/Tokyo", estimated: false }
+ * console.log(timeZoneAt("US", { lat: 47.61, lon: -122.33 })?.zone); // "America/Los_Angeles"
+ * ```
+ */
+declare const timeZoneAt: (code: string, point: LatLon) => ZoneAnswer | null;
+
+export { type ZoneAnswer, subdivisionTimeZone, timeZoneAt };

package/dist/zones.d.ts

@@ -0,0 +1,66 @@
+import { L as LatLon } from './types-CWqSLWHx.js';
+
+/**
+ * A zone, and whether it was worked out rather than read: `estimated` is true where kuni had to choose.
+ *
+ * @example
+ * ```ts
+ * import { subdivisionTimeZone, type ZoneAnswer } from "@johnmorrisdotca/kuni/zones";
+ *
+ * const answer: ZoneAnswer | null = subdivisionTimeZone("CA-BC");
+ * console.log(answer?.zone); // "America/Vancouver"
+ * ```
+ */
+interface ZoneAnswer {
+    /** The IANA zone, "America/Los_Angeles". */
+    zone: string;
+    /** True where kuni chose it (nearest a capital or a point), false where a source names it alone. */
+    estimated: boolean;
+}
+/**
+ * The IANA time zone of a first-level subdivision, by its ISO 3166-2 code: what a map of a country's regions shows.
+ *
+ * In a country with one zone, that zone (`estimated: false`). In a country with several, the zone Wikidata gives the
+ * subdivision where it gives one of the country's zones alone (`estimated: false`); where it gives several (Indiana,
+ * Idaho) or none, the one whose principal city in IANA's zone.tab is nearest the subdivision's capital
+ * (`estimated: true`); and for the few kuni has no point for and Wikidata names no zone of (Beijing, Catalonia), the
+ * zone of the country's capital (`estimated: true`).
+ *
+ * @param code - An ISO 3166-2 code, "US-WA" or "us-wa".
+ * @returns The zone and whether it was estimated; `null` for a code kuni does not list as a first-level subdivision,
+ * or one in a country with no zone.
+ * @example
+ * ```ts
+ * import { subdivisionTimeZone } from "@johnmorrisdotca/kuni/zones";
+ *
+ * console.log(subdivisionTimeZone("US-WA")); // { zone: "America/Los_Angeles", estimated: false }
+ * console.log(subdivisionTimeZone("JP-13")?.zone); // "Asia/Tokyo"
+ * ```
+ */
+declare const subdivisionTimeZone: (code: string) => ZoneAnswer | null;
+/**
+ * The IANA time zone at a point in a country, and whether it is known or estimated.
+ *
+ * A country with one zone gives that zone, `estimated: false`. In a country with several: a point within 30 km of a
+ * zone's principal city in IANA's zone.tab takes that zone (Ciudad Juárez, America/Ciudad_Juarez); any other takes the
+ * zone of the subdivision whose capital or middle is nearest (`subdivisionTimeZone`). Both are `estimated: true`.
+ *
+ * Limits, since kuni has no boundaries: a point near the edge of a state or province can be given its neighbour's
+ * zone; a subdivision split between zones gives its most-populous part's (East Tennessee is given Central time); and a
+ * place that keeps a different rule inside a subdivision is not known (the Navajo Nation keeps daylight saving time in
+ * Arizona). Say "estimated" where it is shown. A map of regions that knows the region asks `subdivisionTimeZone`.
+ *
+ * @param code - The country the point is in, an ISO 3166-1 alpha-2 code in either case.
+ * @param point - The point, `{ lat, lon }` in degrees.
+ * @returns The zone and whether it was estimated; `null` for a code that is not a country or a country with no zone.
+ * @example
+ * ```ts
+ * import { timeZoneAt } from "@johnmorrisdotca/kuni/zones";
+ *
+ * console.log(timeZoneAt("JP", { lat: 43.06, lon: 141.35 })); // { zone: "Asia/Tokyo", estimated: false }
+ * console.log(timeZoneAt("US", { lat: 47.61, lon: -122.33 })?.zone); // "America/Los_Angeles"
+ * ```
+ */
+declare const timeZoneAt: (code: string, point: LatLon) => ZoneAnswer | null;
+
+export { type ZoneAnswer, subdivisionTimeZone, timeZoneAt };