@chelone/core 0.6.0 → 0.7.0

package/dist/geo/overpass.d.ts

@@ -2,6 +2,18 @@ import type { QueryFunctionContext } from "@tanstack/query-core";
 export interface OverpassRequestOptions {
     signal?: AbortSignal;
 }
+export type OverpassElement = {
+    type: "node" | "way" | "relation";
+    id: number;
+    tags?: Readonly<Record<string, string>>;
+};
+/** The JSON body of an Overpass interpreter answer. */
+export type OverpassAnswer = {
+    elements: OverpassElement[];
+    remark?: string;
+};
+/** True for a body with an `elements` array, which Overpass always sends. */
+export declare function isOverpassAnswer(value: unknown): value is OverpassAnswer;
 export interface OverpassProvider {
     name: string;
     /**
@@ -10,7 +22,7 @@ export interface OverpassProvider {
      */
     cacheKey?: string;
     /** Runs an Overpass QL query and resolves to the parsed JSON answer. */
-    query(query: string, options?: OverpassRequestOptions): Promise<unknown>;
+    query(query: string, options?: OverpassRequestOptions): Promise<OverpassAnswer>;
 }
 export declare class OverpassError extends Error {
     readonly status?: number;
@@ -41,7 +53,7 @@ export interface OverpassQueryOptions {
 }
 export interface OverpassQuery {
     queryKey: readonly unknown[];
-    queryFn: (context: Pick<QueryFunctionContext, "signal">) => Promise<unknown>;
+    queryFn: (context: Pick<QueryFunctionContext, "signal">) => Promise<OverpassAnswer>;
     enabled: boolean;
     staleTime: number;
 }

package/dist/geo/overpass.js

@@ -1,97 +1,90 @@
-class OverpassError extends Error {
-  status;
-  constructor(message, status) {
-    super(message);
-    this.name = "OverpassError";
-    this.status = status;
-  }
-}
-class OverpassRateLimitError extends OverpassError {
-  constructor(message = "Overpass rate limit reached (429)") {
-    super(message, 429);
-    this.name = "OverpassRateLimitError";
-  }
-}
-class OverpassTimeoutError extends OverpassError {
-  constructor(message = "Overpass query timed out", status) {
-    super(message, status);
-    this.name = "OverpassTimeoutError";
-  }
+// src/geo/overpass.ts
+/** True for a body with an `elements` array, which Overpass always sends. */
+function isOverpassAnswer(value) {
+	return typeof value === "object" && value !== null && "elements" in value && Array.isArray(value.elements);
 }
+var OverpassError = class extends Error {
+	status;
+	constructor(message, status) {
+		super(message);
+		this.name = "OverpassError";
+		this.status = status;
+	}
+};
+var OverpassRateLimitError = class extends OverpassError {
+	constructor(message = "Overpass rate limit reached (429)") {
+		super(message, 429);
+		this.name = "OverpassRateLimitError";
+	}
+};
+/** The server answered 504, or the client's own timeout fired. */
+var OverpassTimeoutError = class extends OverpassError {
+	constructor(message = "Overpass query timed out", status) {
+		super(message, status);
+		this.name = "OverpassTimeoutError";
+	}
+};
+/**
+* A query that hits the server's time or memory limit still answers 200, with
+* the elements found so far and a `remark`. That partial list must not pass
+* for a complete one.
+*/
 function throwOnRuntimeError(answer) {
-  const remark = answer?.remark;
-  if (typeof remark !== "string" || !/^runtime error/i.test(remark.trim())) {
-    return;
-  }
-  throw /timed out/i.test(remark) ? new OverpassTimeoutError(`Overpass ${remark.trim()}`) : new OverpassError(`Overpass ${remark.trim()}`);
+	const { remark } = answer;
+	if (typeof remark !== "string" || !/^runtime error/i.test(remark.trim())) return;
+	throw /timed out/i.test(remark) ? new OverpassTimeoutError(`Overpass ${remark.trim()}`) : new OverpassError(`Overpass ${remark.trim()}`);
 }
 function createOverpassProvider(options) {
-  const { endpoint } = options;
-  if (typeof endpoint !== "string" || endpoint.trim() === "") {
-    throw new TypeError(
-      'createOverpassProvider: the "endpoint" option is required'
-    );
-  }
-  const url = endpoint.trim();
-  const timeoutMs = options.timeoutMs ?? 3e4;
-  const doFetch = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
-  return {
-    name: "overpass",
-    cacheKey: `overpass|${url}`,
-    async query(query, { signal } = {}) {
-      const timer = new AbortController();
-      let timedOut = false;
-      const handle = setTimeout(() => {
-        timedOut = true;
-        timer.abort();
-      }, timeoutMs);
-      try {
-        const response = await doFetch(url, {
-          method: "POST",
-          headers: { "Content-Type": "application/x-www-form-urlencoded" },
-          body: new URLSearchParams({ data: query }).toString(),
-          signal: signal ? AbortSignal.any([signal, timer.signal]) : timer.signal
-        });
-        if (response.status === 429) throw new OverpassRateLimitError();
-        if (response.status === 504) {
-          throw new OverpassTimeoutError(
-            "Overpass query timed out (504)",
-            response.status
-          );
-        }
-        if (!response.ok) {
-          throw new OverpassError(
-            `Overpass query failed (${response.status})`,
-            response.status
-          );
-        }
-        const answer = await response.json();
-        throwOnRuntimeError(answer);
-        return answer;
-      } catch (error) {
-        if (timedOut && !(error instanceof OverpassError)) {
-          throw new OverpassTimeoutError();
-        }
-        throw error;
-      } finally {
-        clearTimeout(handle);
-      }
-    }
-  };
+	const { endpoint } = options;
+	if (typeof endpoint !== "string" || endpoint.trim() === "") throw new TypeError("createOverpassProvider: the \"endpoint\" option is required");
+	const url = endpoint.trim();
+	const timeoutMs = options.timeoutMs ?? 3e4;
+	const doFetch = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
+	return {
+		name: "overpass",
+		cacheKey: `overpass|${url}`,
+		async query(query, { signal } = {}) {
+			const timer = new AbortController();
+			let timedOut = false;
+			const handle = setTimeout(() => {
+				timedOut = true;
+				timer.abort();
+			}, timeoutMs);
+			try {
+				const response = await doFetch(url, {
+					method: "POST",
+					headers: { "Content-Type": "application/x-www-form-urlencoded" },
+					body: new URLSearchParams({ data: query }).toString(),
+					signal: signal ? AbortSignal.any([signal, timer.signal]) : timer.signal
+				});
+				if (response.status === 429) throw new OverpassRateLimitError();
+				if (response.status === 504) throw new OverpassTimeoutError("Overpass query timed out (504)", response.status);
+				if (!response.ok) throw new OverpassError(`Overpass query failed (${response.status})`, response.status);
+				const answer = await response.json();
+				if (!isOverpassAnswer(answer)) throw new OverpassError("Overpass answered JSON without elements");
+				throwOnRuntimeError(answer);
+				return answer;
+			} catch (error) {
+				if (timedOut && !(error instanceof OverpassError)) throw new OverpassTimeoutError();
+				throw error;
+			} finally {
+				clearTimeout(handle);
+			}
+		}
+	};
 }
-const ONE_HOUR_MS = 60 * 60 * 1e3;
+var ONE_HOUR_MS = 36e5;
+/** Query options for `useQuery`; the query's `signal` reaches the provider. */
 function overpassQueryOptions(provider, query, options = {}) {
-  return {
-    queryKey: ["overpass", provider.cacheKey ?? provider.name, query],
-    queryFn: ({ signal }) => provider.query(query, { signal }),
-    enabled: query.trim() !== "",
-    staleTime: options.staleTime ?? ONE_HOUR_MS
-  };
+	return {
+		queryKey: [
+			"overpass",
+			provider.cacheKey ?? provider.name,
+			query
+		],
+		queryFn: ({ signal }) => provider.query(query, { signal }),
+		enabled: query.trim() !== "",
+		staleTime: options.staleTime ?? ONE_HOUR_MS
+	};
 }
-export {
-  OverpassError,
-  OverpassRateLimitError,
-  OverpassTimeoutError,
-  createOverpassProvider,
-  overpassQueryOptions
-};
+export { OverpassError, OverpassRateLimitError, OverpassTimeoutError, createOverpassProvider, isOverpassAnswer, overpassQueryOptions };

package/dist/geo/shape-value.d.ts

@@ -1,8 +1,11 @@
-import type { GeoBBox, GeoFeature, GeoJsonValue } from "./geojson.js";
+import type { Feature, FeatureCollection, Geometry } from "geojson";
+import type { JsonObject } from "../guards.js";
+import type { LngLatBox } from "./bounds.js";
 /** What a drawing input stores in its form field. */
 export type ShapeValueKind = "Point" | "MultiPoint" | "LineString" | "MultiLineString" | "Polygon" | "MultiPolygon" | "GeometryCollection" | "Geometry" | "Feature" | "FeatureCollection" | "BBox";
 /** A form value of any {@link ShapeValueKind}. */
-export type ShapeValue = GeoJsonValue | GeoBBox;
+export type ShapeValue = Geometry | Feature<Geometry | null, JsonObject | null> | FeatureCollection<Geometry | null, JsonObject | null> | LngLatBox;
+type ShapeFeature = Feature<Geometry | null, JsonObject | null>;
 export interface FeaturesToShapeOptions {
     /** Width over height of a `BBox` value. */
     aspectRatio?: number;
@@ -18,14 +21,14 @@ export interface FeaturesToShapeOptions {
  * ring. A Multi kind gives one feature per part and a GeometryCollection one
  * per geometry. A value of the wrong kind, null or malformed gives `[]`.
  */
-export declare function shapeToFeatures(kind: ShapeValueKind, value: unknown): GeoFeature[];
+export declare function shapeToFeatures(kind: ShapeValueKind, value: unknown): ShapeFeature[];
 /**
  * The parts of a value the editor cannot hold: a Polygon with holes, and a
  * FeatureCollection feature with no geometry, a GeometryCollection or a Multi
  * geometry, and a Multi geometry inside a GeometryCollection. The Geometry kind
  * holds a GeometryCollection whole. {@link featuresToShape} puts them back.
  */
-export declare function heldFeatures(kind: ShapeValueKind, value: unknown): GeoFeature[];
+export declare function heldFeatures(kind: ShapeValueKind, value: unknown): ShapeFeature[];
 /**
  * The value to store for the editor's `features`, or `null` when none is left.
  * `prev` is the value being edited: its held parts come back, and a Feature
@@ -33,4 +36,5 @@ export declare function heldFeatures(kind: ShapeValueKind, value: unknown): GeoF
  * last feature, since a new drawing replaces the old shape. A FeatureCollection
  * keeps its other members, such as `name` and `crs`, but not its `bbox`.
  */
-export declare function featuresToShape(kind: ShapeValueKind, features: GeoFeature[], prev: unknown, options?: FeaturesToShapeOptions): ShapeValue | null;
+export declare function featuresToShape(kind: ShapeValueKind, features: ShapeFeature[], prev: unknown, options?: FeaturesToShapeOptions): ShapeValue | null;
+export {};

package/dist/geo/shape-value.js

@@ -1,172 +1,195 @@
-import { polygonToBBox, aspectLockedBBox, bboxToPolygon } from "./bbox.js";
-import { isGeoFeatureCollection, isGeoFeature, isGeoGeometry } from "./geojson.js";
+import { aspectLockedBBox, bboxToPolygon, polygonToBBox } from "./bbox.js";
+import { isGeoFeature, isGeoFeatureCollection, isGeoGeometry } from "./geojson.js";
+// src/geo/shape-value.ts
 function wrap(geometry) {
-  return { type: "Feature", geometry, properties: {} };
+	return {
+		type: "Feature",
+		geometry,
+		properties: {}
+	};
 }
+/**
+* One geometry per part of a Multi geometry or a GeometryCollection. A Multi
+* geometry or a GeometryCollection inside a GeometryCollection stays whole, so
+* it is held and written back as it was.
+*/
 function singles(geometry) {
-  switch (geometry.type) {
-    case "MultiPoint":
-      return geometry.coordinates.map((coordinates) => ({
-        type: "Point",
-        coordinates
-      }));
-    case "MultiLineString":
-      return geometry.coordinates.map((coordinates) => ({
-        type: "LineString",
-        coordinates
-      }));
-    case "MultiPolygon":
-      return geometry.coordinates.map((coordinates) => ({
-        type: "Polygon",
-        coordinates
-      }));
-    case "GeometryCollection":
-      return geometry.geometries;
-    default:
-      return [geometry];
-  }
+	switch (geometry.type) {
+		case "MultiPoint": return geometry.coordinates.map((coordinates) => ({
+			type: "Point",
+			coordinates
+		}));
+		case "MultiLineString": return geometry.coordinates.map((coordinates) => ({
+			type: "LineString",
+			coordinates
+		}));
+		case "MultiPolygon": return geometry.coordinates.map((coordinates) => ({
+			type: "Polygon",
+			coordinates
+		}));
+		case "GeometryCollection": return geometry.geometries;
+		default: return [geometry];
+	}
 }
+/** The editor holds a Point, a LineString and a Polygon with one ring. */
 function isEditable(geometry) {
-  if (!geometry) return false;
-  if (geometry.type === "Point" || geometry.type === "LineString") return true;
-  return geometry.type === "Polygon" && geometry.coordinates.length === 1;
+	if (!geometry) return false;
+	if (geometry.type === "Point" || geometry.type === "LineString") return true;
+	return geometry.type === "Polygon" && geometry.coordinates.length === 1;
 }
+/** A Polygon with no ring has nothing to hold or to show. */
 function isEmptyPolygon(geometry) {
-  return geometry.type === "Polygon" && geometry.coordinates.length === 0;
+	return geometry.type === "Polygon" && geometry.coordinates.length === 0;
 }
 function splitGeometries(geometries) {
-  const editable = [];
-  const held = [];
-  for (const geometry of geometries) {
-    if (isEditable(geometry)) editable.push(wrap(geometry));
-    else if (!isEmptyPolygon(geometry)) held.push(wrap(geometry));
-  }
-  return { editable, held };
+	const editable = [];
+	const held = [];
+	for (const geometry of geometries) if (isEditable(geometry)) editable.push(wrap(geometry));
+	else if (!isEmptyPolygon(geometry)) held.push(wrap(geometry));
+	return {
+		editable,
+		held
+	};
 }
 function splitFeatures(features) {
-  const editable = [];
-  const held = [];
-  for (const feature of features) {
-    (isEditable(feature.geometry) ? editable : held).push(feature);
-  }
-  return { editable, held };
+	const editable = [];
+	const held = [];
+	for (const feature of features) (isEditable(feature.geometry) ? editable : held).push(feature);
+	return {
+		editable,
+		held
+	};
 }
-const NOTHING = { editable: [], held: [] };
+var NOTHING = {
+	editable: [],
+	held: []
+};
 function split(kind, value) {
-  switch (kind) {
-    case "Point":
-    case "LineString":
-    case "Polygon":
-      return isGeoGeometry(value) && value.type === kind ? splitGeometries([value]) : NOTHING;
-    case "MultiPoint":
-    case "MultiLineString":
-    case "MultiPolygon":
-    case "GeometryCollection":
-      return isGeoGeometry(value) && value.type === kind ? splitGeometries(singles(value)) : NOTHING;
-    case "Geometry":
-      return isGeoGeometry(value) ? splitGeometries([value]) : NOTHING;
-    case "Feature":
-      return isGeoFeature(value) ? splitFeatures([value]) : NOTHING;
-    case "FeatureCollection":
-      return isGeoFeatureCollection(value) ? splitFeatures(value.features) : NOTHING;
-    case "BBox": {
-      const polygon = bboxToPolygon(value);
-      return polygon ? splitGeometries([polygon]) : NOTHING;
-    }
-  }
+	switch (kind) {
+		case "Point":
+		case "LineString":
+		case "Polygon": return isGeoGeometry(value) && value.type === kind ? splitGeometries([value]) : NOTHING;
+		case "MultiPoint":
+		case "MultiLineString":
+		case "MultiPolygon":
+		case "GeometryCollection": return isGeoGeometry(value) && value.type === kind ? splitGeometries(singles(value)) : NOTHING;
+		case "Geometry": return isGeoGeometry(value) ? splitGeometries([value]) : NOTHING;
+		case "Feature": return isGeoFeature(value) ? splitFeatures([value]) : NOTHING;
+		case "FeatureCollection": return isGeoFeatureCollection(value) ? splitFeatures(value.features) : NOTHING;
+		case "BBox": {
+			const polygon = bboxToPolygon(value);
+			return polygon ? splitGeometries([polygon]) : NOTHING;
+		}
+	}
 }
+/**
+* The features the editor can hold: Points, LineStrings and Polygons with one
+* ring. A Multi kind gives one feature per part and a GeometryCollection one
+* per geometry. A value of the wrong kind, null or malformed gives `[]`.
+*/
 function shapeToFeatures(kind, value) {
-  return split(kind, value).editable;
+	return split(kind, value).editable;
 }
+/**
+* The parts of a value the editor cannot hold: a Polygon with holes, and a
+* FeatureCollection feature with no geometry, a GeometryCollection or a Multi
+* geometry, and a Multi geometry inside a GeometryCollection. The Geometry kind
+* holds a GeometryCollection whole. {@link featuresToShape} puts them back.
+*/
 function heldFeatures(kind, value) {
-  return split(kind, value).held;
+	return split(kind, value).held;
 }
+/** The geometry of the last feature, of `type` when given. */
 function lastGeometry(features, type) {
-  for (let i = features.length - 1; i >= 0; i--) {
-    const geometry = features[i]?.geometry;
-    if (!geometry) continue;
-    if (type ? geometry.type === type : geometry.type !== "GeometryCollection") {
-      return geometry;
-    }
-  }
-  return null;
+	for (let i = features.length - 1; i >= 0; i--) {
+		const geometry = features[i]?.geometry;
+		if (!geometry) continue;
+		if (type ? geometry.type === type : geometry.type !== "GeometryCollection") return geometry;
+	}
+	return null;
 }
 function joinMulti(kind, geometries) {
-  switch (kind) {
-    case "MultiPoint": {
-      const coordinates = geometries.flatMap(
-        (g) => g.type === "Point" ? [g.coordinates] : []
-      );
-      return coordinates.length ? { type: "MultiPoint", coordinates } : null;
-    }
-    case "MultiLineString": {
-      const coordinates = geometries.flatMap(
-        (g) => g.type === "LineString" ? [g.coordinates] : []
-      );
-      return coordinates.length ? { type: "MultiLineString", coordinates } : null;
-    }
-    case "MultiPolygon": {
-      const coordinates = geometries.flatMap(
-        (g) => g.type === "Polygon" ? [g.coordinates] : []
-      );
-      return coordinates.length ? { type: "MultiPolygon", coordinates } : null;
-    }
-  }
+	switch (kind) {
+		case "MultiPoint": {
+			const coordinates = geometries.flatMap((g) => g.type === "Point" ? [g.coordinates] : []);
+			return coordinates.length ? {
+				type: "MultiPoint",
+				coordinates
+			} : null;
+		}
+		case "MultiLineString": {
+			const coordinates = geometries.flatMap((g) => g.type === "LineString" ? [g.coordinates] : []);
+			return coordinates.length ? {
+				type: "MultiLineString",
+				coordinates
+			} : null;
+		}
+		case "MultiPolygon": {
+			const coordinates = geometries.flatMap((g) => g.type === "Polygon" ? [g.coordinates] : []);
+			return coordinates.length ? {
+				type: "MultiPolygon",
+				coordinates
+			} : null;
+		}
+	}
 }
 function heldGeometries(kind, prev, addHeld) {
-  if (!addHeld) return [];
-  return heldFeatures(kind, prev).flatMap(
-    (f) => f.geometry ? [f.geometry] : []
-  );
+	if (!addHeld) return [];
+	return heldFeatures(kind, prev).flatMap((f) => f.geometry ? [f.geometry] : []);
 }
+/**
+* The value to store for the editor's `features`, or `null` when none is left.
+* `prev` is the value being edited: its held parts come back, and a Feature
+* keeps its `id`, `properties` and other members. A single kind takes the
+* last feature, since a new drawing replaces the old shape. A FeatureCollection
+* keeps its other members, such as `name` and `crs`, but not its `bbox`.
+*/
 function featuresToShape(kind, features, prev, options = {}) {
-  const addHeld = options.addHeld ?? true;
-  switch (kind) {
-    case "Point":
-    case "LineString":
-    case "Polygon":
-      return lastGeometry(features, kind);
-    case "Geometry":
-      return lastGeometry(features);
-    case "MultiPoint":
-    case "MultiLineString":
-    case "MultiPolygon":
-      return joinMulti(kind, [
-        ...features.flatMap((f) => f.geometry ? [f.geometry] : []),
-        ...heldGeometries(kind, prev, addHeld)
-      ]);
-    case "GeometryCollection": {
-      const geometries = [
-        ...features.flatMap((f) => f.geometry ? [f.geometry] : []),
-        ...heldGeometries(kind, prev, addHeld)
-      ];
-      return geometries.length ? { type: "GeometryCollection", geometries } : null;
-    }
-    case "Feature": {
-      const geometry = lastGeometry(features);
-      if (!geometry) return null;
-      if (!isGeoFeature(prev)) {
-        return { type: "Feature", geometry, properties: {} };
-      }
-      const { bbox: _bbox, ...rest } = prev;
-      return { ...rest, geometry };
-    }
-    case "FeatureCollection": {
-      const all = addHeld ? [...features, ...heldFeatures(kind, prev)] : features;
-      if (!all.length) return null;
-      const { bbox: _bbox, ...rest } = isGeoFeatureCollection(prev) ? prev : {};
-      return { ...rest, type: "FeatureCollection", features: all };
-    }
-    case "BBox": {
-      const polygon = lastGeometry(features, "Polygon");
-      if (!polygon) return null;
-      const toBBox = options.aspectRatio === void 0 ? polygonToBBox : aspectLockedBBox(options.aspectRatio);
-      return toBBox(polygon);
-    }
-  }
+	const addHeld = options.addHeld ?? true;
+	switch (kind) {
+		case "Point":
+		case "LineString":
+		case "Polygon": return lastGeometry(features, kind);
+		case "Geometry": return lastGeometry(features);
+		case "MultiPoint":
+		case "MultiLineString":
+		case "MultiPolygon": return joinMulti(kind, [...features.flatMap((f) => f.geometry ? [f.geometry] : []), ...heldGeometries(kind, prev, addHeld)]);
+		case "GeometryCollection": {
+			const geometries = [...features.flatMap((f) => f.geometry ? [f.geometry] : []), ...heldGeometries(kind, prev, addHeld)];
+			return geometries.length ? {
+				type: "GeometryCollection",
+				geometries
+			} : null;
+		}
+		case "Feature": {
+			const geometry = lastGeometry(features);
+			if (!geometry) return null;
+			if (!isGeoFeature(prev)) return {
+				type: "Feature",
+				geometry,
+				properties: {}
+			};
+			const { bbox: _bbox, ...rest } = prev;
+			return {
+				...rest,
+				geometry
+			};
+		}
+		case "FeatureCollection": {
+			const all = addHeld ? [...features, ...heldFeatures(kind, prev)] : features;
+			if (!all.length) return null;
+			const { bbox: _bbox, ...rest } = isGeoFeatureCollection(prev) ? prev : {};
+			return {
+				...rest,
+				type: "FeatureCollection",
+				features: all
+			};
+		}
+		case "BBox": {
+			const polygon = lastGeometry(features, "Polygon");
+			if (!polygon) return null;
+			return (options.aspectRatio === void 0 ? polygonToBBox : aspectLockedBBox(options.aspectRatio))(polygon);
+		}
+	}
 }
-export {
-  featuresToShape,
-  heldFeatures,
-  shapeToFeatures
-};
+export { featuresToShape, heldFeatures, shapeToFeatures };

package/dist/geo/snap-to-roads.d.ts

@@ -1,10 +1,10 @@
-import type { GeoLineString } from "./geojson.js";
+import type { LineString } from "geojson";
 export interface RoutingProvider {
     name: string;
     /** Resolves to the line matched to roads, or `null` when it cannot be. */
-    snapToRoad(line: GeoLineString, options?: {
+    snapToRoad(line: LineString, options?: {
         signal?: AbortSignal;
-    }): Promise<GeoLineString | null>;
+    }): Promise<LineString | null>;
 }
 export interface OsrmProviderOptions {
     /**