@honua/app-platform 0.1.0-beta.0 → 0.1.1-beta.0

package/geocoding/providers/photon.js

@@ -0,0 +1,107 @@
+/**
+ * Photon adapter for the {@link GeocodingProvider} contract.
+ *
+ * Photon (komoot) is typeahead-first, so it supports all three operations:
+ * `geocode`, `reverse`, and `suggest` (suggest reuses the search endpoint,
+ * which is designed for as-you-type queries).
+ *
+ * There is no default endpoint: pass the `baseUrl` of an instance you are
+ * entitled to use (e.g. a self-hosted Photon, or `https://photon.komoot.io`
+ * within its fair-use terms).
+ *
+ * @packageDocumentation
+ */
+import { providerGetJson, stringifyProviderAttributes, trimProviderBaseUrl, } from "../provider-http.js";
+import { assertGeocodingCapability, } from "../provider.js";
+const PHOTON_ATTRIBUTION = "Data © OpenStreetMap contributors, ODbL 1.0";
+const PHOTON_USAGE_POLICY_URL = "https://photon.komoot.io/";
+const PHOTON_CAPABILITIES = ["geocode", "reverse", "suggest"];
+function photonLabel(feature) {
+    const p = feature.properties ?? {};
+    const streetLine = p.housenumber && p.street ? `${p.street} ${p.housenumber}` : p.street;
+    const parts = [p.name, streetLine, p.city, p.state, p.country].filter((part) => typeof part === "string" && part.length > 0);
+    // Photon repeats `name` for street-level results; drop consecutive duplicates.
+    return parts.filter((part, index) => part !== parts[index - 1]).join(", ");
+}
+/**
+ * Create a {@link GeocodingProvider} backed by a Photon instance.
+ *
+ * @experimental
+ */
+export function photonGeocodingProvider(options) {
+    const baseUrl = trimProviderBaseUrl(options.baseUrl);
+    const policy = options.capabilityPolicy ?? "strict";
+    const provenance = Object.freeze({
+        provider: "photon",
+        attribution: options.attribution ?? PHOTON_ATTRIBUTION,
+        usagePolicyUrl: options.usagePolicyUrl ?? PHOTON_USAGE_POLICY_URL,
+    });
+    const request = (path, params, label) => {
+        if (options.language) {
+            params.set("lang", options.language);
+        }
+        return providerGetJson(`${baseUrl}${path}?${params.toString()}`, {
+            fetchFn: options.fetchFn,
+            timeoutMs: options.timeoutMs,
+            label,
+        });
+    };
+    const toMatch = (feature) => {
+        const [longitude, latitude] = feature.geometry?.coordinates ?? [Number.NaN, Number.NaN];
+        const p = feature.properties ?? {};
+        return {
+            address: photonLabel(feature),
+            latitude,
+            longitude,
+            attributes: stringifyProviderAttributes({
+                osm_id: p.osm_id,
+                osm_type: p.osm_type,
+                osm_key: p.osm_key,
+                osm_value: p.osm_value,
+                postcode: p.postcode,
+                type: p.type,
+            }),
+            provenance,
+        };
+    };
+    const search = async (query, limit, label) => {
+        const params = new URLSearchParams({ q: query });
+        if (limit !== undefined) {
+            params.set("limit", String(limit));
+        }
+        const data = await request("/api", params, label);
+        return (data.features ?? []).map(toMatch);
+    };
+    return {
+        id: "photon",
+        capabilities: PHOTON_CAPABILITIES,
+        attribution: provenance.attribution,
+        usagePolicyUrl: provenance.usagePolicyUrl,
+        async geocode(query, geocodeOptions) {
+            assertGeocodingCapability({ id: "photon", capabilities: PHOTON_CAPABILITIES }, "geocode", policy);
+            return search(query, geocodeOptions?.limit, "photon geocode");
+        },
+        async reverse(latitude, longitude) {
+            assertGeocodingCapability({ id: "photon", capabilities: PHOTON_CAPABILITIES }, "reverse", policy);
+            const params = new URLSearchParams({ lat: String(latitude), lon: String(longitude) });
+            const data = await request("/reverse", params, "photon reverse");
+            const feature = data.features?.[0];
+            if (!feature) {
+                return null;
+            }
+            const match = toMatch(feature);
+            return {
+                address: match.address,
+                latitude: match.latitude,
+                longitude: match.longitude,
+                attributes: match.attributes,
+                provenance,
+            };
+        },
+        async suggest(text, suggestOptions) {
+            assertGeocodingCapability({ id: "photon", capabilities: PHOTON_CAPABILITIES }, "suggest", policy);
+            const matches = await search(text, suggestOptions?.limit, "photon suggest");
+            return matches.map((match) => ({ text: match.address, provenance }));
+        },
+    };
+}

package/geometry/convert.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Esri-JSON ↔ GeoJSON conversion for the geometry package.
+ *
+ * These are re-exports of the single canonical converter utility in
+ * `src/core/esri-geojson.ts` (heritage of issue #264) — the geometry package
+ * deliberately does not fork its own Esri conversion logic. `esriToGeoJson` /
+ * `geoJsonToEsri` are the ergonomic aliases used by `@honua/geometry` and the
+ * `geometryEngine` compat shim.
+ *
+ * @module
+ */
+export { esriGeometryToGeoJSON as esriToGeoJson, esriFeatureToGeoJSON as esriFeatureToGeoJson, geoJsonToEsriGeometry as geoJsonToEsri, } from "../core/esri-geojson.js";
+//# sourceMappingURL=convert.d.ts.map

package/geometry/convert.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"convert.d.ts","sourceRoot":"","sources":["../../../src/geometry/convert.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EACL,qBAAqB,IAAI,aAAa,EACtC,oBAAoB,IAAI,oBAAoB,EAC5C,qBAAqB,IAAI,aAAa,GACvC,MAAM,yBAAyB,CAAC"}

package/geometry/convert.js

@@ -0,0 +1,12 @@
+/**
+ * Esri-JSON ↔ GeoJSON conversion for the geometry package.
+ *
+ * These are re-exports of the single canonical converter utility in
+ * `src/core/esri-geojson.ts` (heritage of issue #264) — the geometry package
+ * deliberately does not fork its own Esri conversion logic. `esriToGeoJson` /
+ * `geoJsonToEsri` are the ergonomic aliases used by `@honua/geometry` and the
+ * `geometryEngine` compat shim.
+ *
+ * @module
+ */
+export { esriGeometryToGeoJSON as esriToGeoJson, esriFeatureToGeoJSON as esriFeatureToGeoJson, geoJsonToEsriGeometry as geoJsonToEsri, } from "../core/esri-geojson.js";

package/geometry/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `@honua/geometry` — curated, tree-shakeable client-side geometry operations
+ * for the Honua SDK.
+ *
+ * This subpath (`@honua/sdk-js/geometry`, split-packaged as `@honua/geometry`)
+ * wraps the individual `@turf/*` packages and `proj4`, typed against the SDK's
+ * own GeoJSON contract. Importing a single op only pulls that op's turf backing
+ * into a consumer bundle; the core SDK never imports this module, so core-only
+ * consumers never pay for turf/proj4.
+ *
+ * @module
+ */
+export { area, bbox, booleanContains, booleanIntersects, booleanWithin, buffer, centroid, convex, difference, intersect, length, nearestPoint, simplify, union, } from "./ops.js";
+export { defineProjection, normalizeCrs, project, toWebMercator, toWgs84 } from "./project.js";
+export { esriFeatureToGeoJson, esriToGeoJson, geoJsonToEsri } from "./convert.js";
+export type { GeoJsonFeature, GeoJsonFeatureCollection, GeoJsonGeometry, GeoJsonLineString, GeoJsonMultiLineString, GeoJsonMultiPoint, GeoJsonMultiPolygon, GeoJsonPoint, GeoJsonPolygon, GeometryInput, LinearUnit, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/geometry/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/geometry/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EACL,IAAI,EACJ,IAAI,EACJ,eAAe,EACf,iBAAiB,EACjB,aAAa,EACb,MAAM,EACN,QAAQ,EACR,MAAM,EACN,UAAU,EACV,SAAS,EACT,MAAM,EACN,YAAY,EACZ,QAAQ,EACR,KAAK,GACN,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE/F,OAAO,EAAE,oBAAoB,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElF,YAAY,EACV,cAAc,EACd,wBAAwB,EACxB,eAAe,EACf,iBAAiB,EACjB,sBAAsB,EACtB,iBAAiB,EACjB,mBAAmB,EACnB,YAAY,EACZ,cAAc,EACd,aAAa,EACb,UAAU,GACX,MAAM,YAAY,CAAC"}

package/geometry/index.js

@@ -0,0 +1,15 @@
+/**
+ * `@honua/geometry` — curated, tree-shakeable client-side geometry operations
+ * for the Honua SDK.
+ *
+ * This subpath (`@honua/sdk-js/geometry`, split-packaged as `@honua/geometry`)
+ * wraps the individual `@turf/*` packages and `proj4`, typed against the SDK's
+ * own GeoJSON contract. Importing a single op only pulls that op's turf backing
+ * into a consumer bundle; the core SDK never imports this module, so core-only
+ * consumers never pay for turf/proj4.
+ *
+ * @module
+ */
+export { area, bbox, booleanContains, booleanIntersects, booleanWithin, buffer, centroid, convex, difference, intersect, length, nearestPoint, simplify, union, } from "./ops.js";
+export { defineProjection, normalizeCrs, project, toWebMercator, toWgs84 } from "./project.js";
+export { esriFeatureToGeoJson, esriToGeoJson, geoJsonToEsri } from "./convert.js";

package/geometry/internal.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Internal bridge between the SDK's GeoJSON contract types and the `geojson`
+ * declarations that the `@turf/*` packages are typed against. The two are
+ * structurally identical for the primitive geometry types the geometry package
+ * supports, so the conversions are erased casts — kept in one place so the ops
+ * modules stay free of scattered `as unknown as` noise.
+ *
+ * @internal
+ * @module
+ */
+import type { Feature as TurfFeature, FeatureCollection as TurfFeatureCollection, Geometry as TurfGeometry } from "geojson";
+import type { GeoJsonFeature } from "../core/types.js";
+import type { GeoJsonGeometry } from "../expr/expression.js";
+import type { GeometryInput } from "./types.js";
+/** Narrow an input to its bare geometry, unwrapping a `Feature` if needed. */
+export declare function inputToGeometry(input: GeometryInput): GeoJsonGeometry;
+/** Present an SDK geometry to turf as a `geojson` geometry. */
+export declare function toTurfGeometry(geometry: GeoJsonGeometry): TurfGeometry;
+/** Present an SDK geometry input to turf as a `geojson` value. */
+export declare function toTurfInput(input: GeometryInput): TurfFeature | TurfFeatureCollection | TurfGeometry;
+/** Convert a turf geometry back into an SDK geometry. */
+export declare function fromTurfGeometry(geometry: TurfGeometry): GeoJsonGeometry;
+/** Convert a turf feature back into an SDK feature. */
+export declare function fromTurfFeature(feature: TurfFeature): GeoJsonFeature;
+//# sourceMappingURL=internal.d.ts.map

package/geometry/internal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../../../src/geometry/internal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,OAAO,IAAI,WAAW,EACtB,iBAAiB,IAAI,qBAAqB,EAC1C,QAAQ,IAAI,YAAY,EACzB,MAAM,SAAS,CAAC;AAEjB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,8EAA8E;AAC9E,wBAAgB,eAAe,CAAC,KAAK,EAAE,aAAa,GAAG,eAAe,CAYrE;AAED,+DAA+D;AAC/D,wBAAgB,cAAc,CAAC,QAAQ,EAAE,eAAe,GAAG,YAAY,CAEtE;AAED,kEAAkE;AAClE,wBAAgB,WAAW,CAAC,KAAK,EAAE,aAAa,GAAG,WAAW,GAAG,qBAAqB,GAAG,YAAY,CAEpG;AAED,yDAAyD;AACzD,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,YAAY,GAAG,eAAe,CAExE;AAED,uDAAuD;AACvD,wBAAgB,eAAe,CAAC,OAAO,EAAE,WAAW,GAAG,cAAc,CAEpE"}

package/geometry/internal.js

@@ -0,0 +1,40 @@
+/**
+ * Internal bridge between the SDK's GeoJSON contract types and the `geojson`
+ * declarations that the `@turf/*` packages are typed against. The two are
+ * structurally identical for the primitive geometry types the geometry package
+ * supports, so the conversions are erased casts — kept in one place so the ops
+ * modules stay free of scattered `as unknown as` noise.
+ *
+ * @internal
+ * @module
+ */
+/** Narrow an input to its bare geometry, unwrapping a `Feature` if needed. */
+export function inputToGeometry(input) {
+    if (input.type === "Feature") {
+        const geometry = input.geometry;
+        if (!geometry) {
+            throw new TypeError("@honua/geometry: feature has no geometry");
+        }
+        return geometry;
+    }
+    if (input.type === "FeatureCollection") {
+        throw new TypeError("@honua/geometry: expected a geometry or Feature, received a FeatureCollection");
+    }
+    return input;
+}
+/** Present an SDK geometry to turf as a `geojson` geometry. */
+export function toTurfGeometry(geometry) {
+    return geometry;
+}
+/** Present an SDK geometry input to turf as a `geojson` value. */
+export function toTurfInput(input) {
+    return input;
+}
+/** Convert a turf geometry back into an SDK geometry. */
+export function fromTurfGeometry(geometry) {
+    return geometry;
+}
+/** Convert a turf feature back into an SDK feature. */
+export function fromTurfFeature(feature) {
+    return feature;
+}

package/geometry/ops.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Curated, tree-shakeable wrappers over the individual `@turf/*` packages,
+ * typed against the SDK's GeoJSON contract.
+ *
+ * Each function wraps exactly one turf package so a consumer importing a single
+ * op (e.g. `import { buffer } from "@honua/geometry"`) only pulls that op's turf
+ * dependency into their bundle. Nothing here is reimplemented — the algorithms
+ * live in turf; this module only adapts types and defaults.
+ *
+ * All turf area/length/buffer math is **geodesic** (great-circle on a sphere)
+ * and assumes coordinates are WGS84 longitude/latitude degrees, matching turf's
+ * contract. See `docs/geometry.md` for the planar-vs-geodesic caveats that
+ * matter when bridging Esri geometries.
+ *
+ * @module
+ */
+import type { GeoJsonFeature } from "../core/types.js";
+import type { GeoJsonGeometry, GeoJsonPoint } from "../expr/expression.js";
+import type { GeometryInput, LinearUnit } from "./types.js";
+/**
+ * Buffer a geometry by `radius` (default unit: meters). Wraps `@turf/buffer`.
+ * Returns `null` when turf cannot produce a buffer (e.g. an empty geometry).
+ */
+export declare function buffer(input: GeometryInput, radius: number, unit?: LinearUnit): GeoJsonGeometry | null;
+/** Geodesic area of a polygonal geometry in square meters. Wraps `@turf/area`. */
+export declare function area(input: GeometryInput): number;
+/**
+ * Geodesic length of a line (or polygon perimeter) in `unit` (default meters).
+ * Wraps `@turf/length`.
+ */
+export declare function length(input: GeometryInput, unit?: LinearUnit): number;
+/** Centroid of a geometry as a GeoJSON `Point`. Wraps `@turf/centroid`. */
+export declare function centroid(input: GeometryInput): GeoJsonPoint;
+/** Bounding box `[minX, minY, maxX, maxY]` of a geometry. Wraps `@turf/bbox`. */
+export declare function bbox(input: GeometryInput): [number, number, number, number];
+/**
+ * Ramer–Douglas–Peucker simplification. `tolerance` is in the geometry's
+ * coordinate units; `highQuality` trades speed for fidelity. Wraps
+ * `@turf/simplify`.
+ */
+export declare function simplify(input: GeometryInput, tolerance: number, highQuality?: boolean): GeoJsonGeometry;
+/** True if `a` and `b` share any point. Wraps `@turf/boolean-intersects`. */
+export declare function booleanIntersects(a: GeometryInput, b: GeometryInput): boolean;
+/** True if `a` completely contains `b`. Wraps `@turf/boolean-contains`. */
+export declare function booleanContains(a: GeometryInput, b: GeometryInput): boolean;
+/** True if `a` is completely within `b`. Wraps `@turf/boolean-within`. */
+export declare function booleanWithin(a: GeometryInput, b: GeometryInput): boolean;
+/**
+ * Polygon union of two or more polygonal geometries. Wraps `@turf/union`.
+ * Returns `null` when the inputs do not combine into a polygon.
+ */
+export declare function union(...polygons: readonly GeometryInput[]): GeoJsonGeometry | null;
+/**
+ * Polygon intersection of two polygonal geometries. Wraps `@turf/intersect`.
+ * Returns `null` when the polygons do not overlap.
+ */
+export declare function intersect(a: GeometryInput, b: GeometryInput): GeoJsonGeometry | null;
+/**
+ * Polygon difference `a − b`. Wraps `@turf/difference`. Returns `null` when the
+ * subtraction removes the whole polygon.
+ */
+export declare function difference(a: GeometryInput, b: GeometryInput): GeoJsonGeometry | null;
+/** Convex hull of a geometry. Wraps `@turf/convex`. Returns `null` if undefined. */
+export declare function convex(input: GeometryInput): GeoJsonGeometry | null;
+/**
+ * Nearest point in `points` to `target`, as a GeoJSON `Feature<Point>` carrying
+ * turf's `featureIndex` / `distanceToPoint` properties. Wraps
+ * `@turf/nearest-point`.
+ */
+export declare function nearestPoint(target: GeoJsonPoint, points: readonly GeoJsonPoint[]): GeoJsonFeature;
+//# sourceMappingURL=ops.d.ts.map

package/geometry/ops.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ops.d.ts","sourceRoot":"","sources":["../../../src/geometry/ops.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AA0BH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAE3E,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAmB5D;;;GAGG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,UAAqB,GAAG,eAAe,GAAG,IAAI,CAUhH;AAED,kFAAkF;AAClF,wBAAgB,IAAI,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAEjD;AAED;;;GAGG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,aAAa,EAAE,IAAI,GAAE,UAAqB,GAAG,MAAM,CAEhF;AAED,2EAA2E;AAC3E,wBAAgB,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,YAAY,CAE3D;AAED,iFAAiF;AACjF,wBAAgB,IAAI,CAAC,KAAK,EAAE,aAAa,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAG3E;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,UAAQ,GAAG,eAAe,CAItG;AAED,6EAA6E;AAC7E,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,aAAa,GAAG,OAAO,CAE7E;AAED,2EAA2E;AAC3E,wBAAgB,eAAe,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,aAAa,GAAG,OAAO,CAE3E;AAED,0EAA0E;AAC1E,wBAAgB,aAAa,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,aAAa,GAAG,OAAO,CAEzE;AAED;;;GAGG;AACH,wBAAgB,KAAK,CAAC,GAAG,QAAQ,EAAE,SAAS,aAAa,EAAE,GAAG,eAAe,GAAG,IAAI,CAMnF;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,aAAa,GAAG,eAAe,GAAG,IAAI,CAGpF;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,aAAa,GAAG,eAAe,GAAG,IAAI,CAGrF;AAED,oFAAoF;AACpF,wBAAgB,MAAM,CAAC,KAAK,EAAE,aAAa,GAAG,eAAe,GAAG,IAAI,CAGnE;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,YAAY,EAAE,GAAG,cAAc,CAWlG"}

package/geometry/ops.js

@@ -0,0 +1,147 @@
+/**
+ * Curated, tree-shakeable wrappers over the individual `@turf/*` packages,
+ * typed against the SDK's GeoJSON contract.
+ *
+ * Each function wraps exactly one turf package so a consumer importing a single
+ * op (e.g. `import { buffer } from "@honua/geometry"`) only pulls that op's turf
+ * dependency into their bundle. Nothing here is reimplemented — the algorithms
+ * live in turf; this module only adapts types and defaults.
+ *
+ * All turf area/length/buffer math is **geodesic** (great-circle on a sphere)
+ * and assumes coordinates are WGS84 longitude/latitude degrees, matching turf's
+ * contract. See `docs/geometry.md` for the planar-vs-geodesic caveats that
+ * matter when bridging Esri geometries.
+ *
+ * @module
+ */
+import { area as turfArea } from "@turf/area";
+import { bbox as turfBbox } from "@turf/bbox";
+import { booleanContains as turfBooleanContains } from "@turf/boolean-contains";
+import { booleanIntersects as turfBooleanIntersects } from "@turf/boolean-intersects";
+import { booleanWithin as turfBooleanWithin } from "@turf/boolean-within";
+import { buffer as turfBuffer } from "@turf/buffer";
+import { centroid as turfCentroid } from "@turf/centroid";
+import { convex as turfConvex } from "@turf/convex";
+import { difference as turfDifference } from "@turf/difference";
+import { intersect as turfIntersect } from "@turf/intersect";
+import { length as turfLength } from "@turf/length";
+import { nearestPoint as turfNearestPoint } from "@turf/nearest-point";
+import { simplify as turfSimplify } from "@turf/simplify";
+import { union as turfUnion } from "@turf/union";
+import { fromTurfFeature, fromTurfGeometry, inputToGeometry, toTurfGeometry, toTurfInput } from "./internal.js";
+function toPolygonFeatureCollection(inputs) {
+    return {
+        type: "FeatureCollection",
+        features: inputs.map((input) => ({
+            type: "Feature",
+            properties: {},
+            geometry: toTurfGeometry(inputToGeometry(input)),
+        })),
+    };
+}
+/**
+ * Buffer a geometry by `radius` (default unit: meters). Wraps `@turf/buffer`.
+ * Returns `null` when turf cannot produce a buffer (e.g. an empty geometry).
+ */
+export function buffer(input, radius, unit = "meters") {
+    // A single Feature/Geometry input yields a single buffered Feature (never a
+    // collection), so the return narrows to `Feature | undefined`.
+    const feature = {
+        type: "Feature",
+        properties: {},
+        geometry: toTurfGeometry(inputToGeometry(input)),
+    };
+    const result = turfBuffer(feature, radius, { units: unit });
+    return result?.geometry ? fromTurfGeometry(result.geometry) : null;
+}
+/** Geodesic area of a polygonal geometry in square meters. Wraps `@turf/area`. */
+export function area(input) {
+    return turfArea(toTurfInput(input));
+}
+/**
+ * Geodesic length of a line (or polygon perimeter) in `unit` (default meters).
+ * Wraps `@turf/length`.
+ */
+export function length(input, unit = "meters") {
+    return turfLength(toTurfInput(input), { units: unit });
+}
+/** Centroid of a geometry as a GeoJSON `Point`. Wraps `@turf/centroid`. */
+export function centroid(input) {
+    return fromTurfGeometry(turfCentroid(toTurfInput(input)).geometry);
+}
+/** Bounding box `[minX, minY, maxX, maxY]` of a geometry. Wraps `@turf/bbox`. */
+export function bbox(input) {
+    const [minX, minY, maxX, maxY] = turfBbox(toTurfInput(input));
+    return [minX, minY, maxX, maxY];
+}
+/**
+ * Ramer–Douglas–Peucker simplification. `tolerance` is in the geometry's
+ * coordinate units; `highQuality` trades speed for fidelity. Wraps
+ * `@turf/simplify`.
+ */
+export function simplify(input, tolerance, highQuality = false) {
+    const geometry = toTurfGeometry(inputToGeometry(input));
+    const simplified = turfSimplify(geometry, { tolerance, highQuality, mutate: false });
+    return fromTurfGeometry(simplified);
+}
+/** True if `a` and `b` share any point. Wraps `@turf/boolean-intersects`. */
+export function booleanIntersects(a, b) {
+    return turfBooleanIntersects(toTurfGeometry(inputToGeometry(a)), toTurfGeometry(inputToGeometry(b)));
+}
+/** True if `a` completely contains `b`. Wraps `@turf/boolean-contains`. */
+export function booleanContains(a, b) {
+    return turfBooleanContains(toTurfGeometry(inputToGeometry(a)), toTurfGeometry(inputToGeometry(b)));
+}
+/** True if `a` is completely within `b`. Wraps `@turf/boolean-within`. */
+export function booleanWithin(a, b) {
+    return turfBooleanWithin(toTurfGeometry(inputToGeometry(a)), toTurfGeometry(inputToGeometry(b)));
+}
+/**
+ * Polygon union of two or more polygonal geometries. Wraps `@turf/union`.
+ * Returns `null` when the inputs do not combine into a polygon.
+ */
+export function union(...polygons) {
+    if (polygons.length === 0) {
+        return null;
+    }
+    const result = turfUnion(toPolygonFeatureCollection(polygons));
+    return result?.geometry ? fromTurfGeometry(result.geometry) : null;
+}
+/**
+ * Polygon intersection of two polygonal geometries. Wraps `@turf/intersect`.
+ * Returns `null` when the polygons do not overlap.
+ */
+export function intersect(a, b) {
+    const result = turfIntersect(toPolygonFeatureCollection([a, b]));
+    return result?.geometry ? fromTurfGeometry(result.geometry) : null;
+}
+/**
+ * Polygon difference `a − b`. Wraps `@turf/difference`. Returns `null` when the
+ * subtraction removes the whole polygon.
+ */
+export function difference(a, b) {
+    const result = turfDifference(toPolygonFeatureCollection([a, b]));
+    return result?.geometry ? fromTurfGeometry(result.geometry) : null;
+}
+/** Convex hull of a geometry. Wraps `@turf/convex`. Returns `null` if undefined. */
+export function convex(input) {
+    const result = turfConvex(toTurfInput(input));
+    return result?.geometry ? fromTurfGeometry(result.geometry) : null;
+}
+/**
+ * Nearest point in `points` to `target`, as a GeoJSON `Feature<Point>` carrying
+ * turf's `featureIndex` / `distanceToPoint` properties. Wraps
+ * `@turf/nearest-point`.
+ */
+export function nearestPoint(target, points) {
+    const collection = {
+        type: "FeatureCollection",
+        features: points.map((point) => ({
+            type: "Feature",
+            properties: {},
+            geometry: toTurfGeometry(point),
+        })),
+    };
+    const nearest = turfNearestPoint(toTurfGeometry(target), collection);
+    return fromTurfFeature(nearest);
+}

package/geometry/project.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Reprojection helpers backed by `proj4`.
+ *
+ * Only EPSG:4326 (WGS84) and EPSG:3857 (Web Mercator) are needed by default —
+ * both are built into proj4, so this module registers **nothing** at import
+ * time and stays side-effect-free for tree-shaking. Additional coordinate
+ * systems are registered on demand via {@link defineProjection}.
+ *
+ * @module
+ */
+import type { GeoJsonGeometry } from "../expr/expression.js";
+import type { GeometryInput } from "./types.js";
+/**
+ * Normalize a CRS identifier into a proj4-resolvable string. Accepts:
+ * - a numeric EPSG code (`4326`, `102100`),
+ * - an `"EPSG:xxxx"` string,
+ * - a raw proj4/WKT definition string (passed through untouched).
+ */
+export declare function normalizeCrs(code: number | string): string;
+/**
+ * Register a coordinate system so {@link project} (and the `toWgs84` /
+ * `toWebMercator` fast paths) can resolve it. Idempotent; safe to call at app
+ * startup or lazily before the first `project` call.
+ *
+ * @param code EPSG code or name to register the definition under.
+ * @param proj4def A proj4 or WKT definition string.
+ */
+export declare function defineProjection(code: number | string, proj4def: string): void;
+/**
+ * Reproject a geometry from `fromCrs` to `toCrs`. CRS arguments accept EPSG
+ * codes, `"EPSG:xxxx"` strings, or raw proj4 definitions. Returns a new
+ * geometry; the input is never mutated. A no-op (deep clone) when the two CRS
+ * resolve to the same definition.
+ */
+export declare function project(input: GeometryInput, fromCrs: number | string, toCrs: number | string): GeoJsonGeometry;
+/** Fast path: reproject a geometry from `fromCrs` into WGS84 (EPSG:4326). */
+export declare function toWgs84(input: GeometryInput, fromCrs: number | string): GeoJsonGeometry;
+/** Fast path: reproject a geometry from `fromCrs` into Web Mercator (EPSG:3857). */
+export declare function toWebMercator(input: GeometryInput, fromCrs: number | string): GeoJsonGeometry;
+//# sourceMappingURL=project.d.ts.map

package/geometry/project.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project.d.ts","sourceRoot":"","sources":["../../../src/geometry/project.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAKhD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAc1D;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAE9E;AAqBD;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,eAAe,CAY/G;AAED,6EAA6E;AAC7E,wBAAgB,OAAO,CAAC,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,eAAe,CAEvF;AAED,oFAAoF;AACpF,wBAAgB,aAAa,CAAC,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,eAAe,CAE7F"}

package/geometry/project.js

@@ -0,0 +1,88 @@
+/**
+ * Reprojection helpers backed by `proj4`.
+ *
+ * Only EPSG:4326 (WGS84) and EPSG:3857 (Web Mercator) are needed by default —
+ * both are built into proj4, so this module registers **nothing** at import
+ * time and stays side-effect-free for tree-shaking. Additional coordinate
+ * systems are registered on demand via {@link defineProjection}.
+ *
+ * @module
+ */
+import proj4 from "proj4";
+import { inputToGeometry } from "./internal.js";
+/** EPSG codes that are aliases for Web Mercator across Esri/OGC usage. */
+const WEB_MERCATOR_ALIASES = new Set([3857, 3785, 900913, 102100, 102113]);
+/**
+ * Normalize a CRS identifier into a proj4-resolvable string. Accepts:
+ * - a numeric EPSG code (`4326`, `102100`),
+ * - an `"EPSG:xxxx"` string,
+ * - a raw proj4/WKT definition string (passed through untouched).
+ */
+export function normalizeCrs(code) {
+    if (typeof code === "number") {
+        return WEB_MERCATOR_ALIASES.has(code) ? "EPSG:3857" : `EPSG:${code}`;
+    }
+    const trimmed = code.trim();
+    // A definition string (proj4 or WKT), not a code — hand it to proj4 as-is.
+    if (trimmed.includes("+proj") || trimmed.includes("PROJCS") || trimmed.includes("GEOGCS")) {
+        return trimmed;
+    }
+    const epsgMatch = /^epsg:(\d+)$/i.exec(trimmed);
+    if (epsgMatch) {
+        return normalizeCrs(Number(epsgMatch[1]));
+    }
+    return trimmed;
+}
+/**
+ * Register a coordinate system so {@link project} (and the `toWgs84` /
+ * `toWebMercator` fast paths) can resolve it. Idempotent; safe to call at app
+ * startup or lazily before the first `project` call.
+ *
+ * @param code EPSG code or name to register the definition under.
+ * @param proj4def A proj4 or WKT definition string.
+ */
+export function defineProjection(code, proj4def) {
+    proj4.defs(normalizeCrs(code), proj4def);
+}
+function projectPosition(position, converter) {
+    const [x, y, ...rest] = position;
+    const projected = converter.forward([x, y]);
+    return [projected[0], projected[1], ...rest];
+}
+function projectCoordinates(coordinates, converter) {
+    if (!Array.isArray(coordinates)) {
+        return coordinates;
+    }
+    // A bare position is an array of finite numbers.
+    if (typeof coordinates[0] === "number") {
+        return projectPosition(coordinates, converter);
+    }
+    return coordinates.map((entry) => projectCoordinates(entry, converter));
+}
+/**
+ * Reproject a geometry from `fromCrs` to `toCrs`. CRS arguments accept EPSG
+ * codes, `"EPSG:xxxx"` strings, or raw proj4 definitions. Returns a new
+ * geometry; the input is never mutated. A no-op (deep clone) when the two CRS
+ * resolve to the same definition.
+ */
+export function project(input, fromCrs, toCrs) {
+    const geometry = inputToGeometry(input);
+    const from = normalizeCrs(fromCrs);
+    const to = normalizeCrs(toCrs);
+    if (from === to) {
+        return structuredClone(geometry);
+    }
+    const converter = proj4(from, to);
+    return {
+        ...geometry,
+        coordinates: projectCoordinates(geometry.coordinates, converter),
+    };
+}
+/** Fast path: reproject a geometry from `fromCrs` into WGS84 (EPSG:4326). */
+export function toWgs84(input, fromCrs) {
+    return project(input, fromCrs, "EPSG:4326");
+}
+/** Fast path: reproject a geometry from `fromCrs` into Web Mercator (EPSG:3857). */
+export function toWebMercator(input, fromCrs) {
+    return project(input, fromCrs, "EPSG:3857");
+}

package/geometry/types.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Public GeoJSON and unit types for `@honua/geometry`.
+ *
+ * The geometry operations are typed against the SDK's own GeoJSON contract
+ * (`src/expr/expression.ts` geometry union + `src/core/types.ts`
+ * {@link GeoJsonFeature}) rather than pulling in the `@types/geojson`
+ * declarations as a public surface. Internally the turf wrappers bridge to the
+ * `geojson` types, but consumers only ever see Honua's own types.
+ *
+ * @module
+ */
+export type { GeoJsonGeometry, GeoJsonPoint, GeoJsonMultiPoint, GeoJsonLineString, GeoJsonMultiLineString, GeoJsonPolygon, GeoJsonMultiPolygon, } from "../expr/expression.js";
+export type { GeoJsonFeature } from "../core/types.js";
+import type { GeoJsonFeature } from "../core/types.js";
+import type { GeoJsonGeometry } from "../expr/expression.js";
+/**
+ * A GeoJSON `FeatureCollection` typed against the SDK feature type. The SDK
+ * contract intentionally ships only `GeoJsonFeature`; the geometry package adds
+ * the collection wrapper it needs for union/nearest-point style operations.
+ */
+export interface GeoJsonFeatureCollection {
+    type: "FeatureCollection";
+    features: GeoJsonFeature[];
+}
+/**
+ * Anything the geometry ops accept as an input shape: a bare geometry, a
+ * `Feature`, or a `FeatureCollection`. Operations always return the SDK
+ * geometry (or feature) types.
+ */
+export type GeometryInput = GeoJsonGeometry | GeoJsonFeature | GeoJsonFeatureCollection;
+/**
+ * Linear distance units understood by {@link buffer} and {@link length}. This is
+ * the subset of turf's unit vocabulary that has an unambiguous geodesic meaning.
+ */
+export type LinearUnit = "meters" | "kilometers" | "miles" | "feet" | "yards" | "nauticalmiles";
+//# sourceMappingURL=types.d.ts.map

package/geometry/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/geometry/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,YAAY,EACV,eAAe,EACf,YAAY,EACZ,iBAAiB,EACjB,iBAAiB,EACjB,sBAAsB,EACtB,cAAc,EACd,mBAAmB,GACpB,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,mBAAmB,CAAC;IAC1B,QAAQ,EAAE,cAAc,EAAE,CAAC;CAC5B;AAED;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,eAAe,GAAG,cAAc,GAAG,wBAAwB,CAAC;AAExF;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,YAAY,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,GAAG,eAAe,CAAC"}