@sakuzu/maplibre-gl-draw 1.0.0 → 2.1.0

package/dist/geometry/buffer.d.ts

@@ -42,31 +42,5 @@ export interface BufferOptions {
  *   shrunk polygon vanishes. `null` when the operation is not defined for the input
  * @throws {@link GeometryError} when the boolean operation engine fails even after the
  *   retry on the 1e-9 degree grid
- *
- * @example
- * ```ts
- * import { buffer } from '@sakuzu/maplibre-gl-draw/geometry';
- *
- * // The area within 100 m of a line
- * const corridor = buffer(
- *   { type: 'LineString', coordinates: [[139.76, 35.68], [139.77, 35.69]] },
- *   100,
- *   { segments: 32 },
- * );
- *
- * // Shrink a polygon by 50 m
- * const shrunk = buffer(
- *   {
- *     type: 'Polygon',
- *     coordinates: [[[139.76, 35.68], [139.77, 35.68], [139.77, 35.69], [139.76, 35.68]]],
- *   },
- *   -50,
- * );
- * if (shrunk === null) {
- *   // Not defined for the input
- * } else if (shrunk.length === 0) {
- *   // The whole area vanished
- * }
- * ```
  */
 export declare function buffer(geometry: GeometryInput, meters: number, options?: BufferOptions): MultiPolygonCoordinates | null;

package/dist/geometry/buffer.js

@@ -161,32 +161,6 @@ function isAreaGeometry(geometry) {
  *   shrunk polygon vanishes. `null` when the operation is not defined for the input
  * @throws {@link GeometryError} when the boolean operation engine fails even after the
  *   retry on the 1e-9 degree grid
- *
- * @example
- * ```ts
- * import { buffer } from '@sakuzu/maplibre-gl-draw/geometry';
- *
- * // The area within 100 m of a line
- * const corridor = buffer(
- *   { type: 'LineString', coordinates: [[139.76, 35.68], [139.77, 35.69]] },
- *   100,
- *   { segments: 32 },
- * );
- *
- * // Shrink a polygon by 50 m
- * const shrunk = buffer(
- *   {
- *     type: 'Polygon',
- *     coordinates: [[[139.76, 35.68], [139.77, 35.68], [139.77, 35.69], [139.76, 35.68]]],
- *   },
- *   -50,
- * );
- * if (shrunk === null) {
- *   // Not defined for the input
- * } else if (shrunk.length === 0) {
- *   // The whole area vanished
- * }
- * ```
  */
 export function buffer(geometry, meters, options) {
     if (!Number.isFinite(meters)) {

package/dist/geometry/circle.d.ts

@@ -26,15 +26,6 @@ export declare function normalizeCircleSegments(segments: number | undefined, fa
  * @returns The ring, `segments + 1` positions `[lng, lat]` with the first repeated at the
  *   end. An empty array for a center that is not finite and for a radius that is negative
  *   or not finite
- *
- * @example
- * ```ts
- * import { generateCirclePolygon } from '@sakuzu/maplibre-gl-draw/geometry';
- *
- * const ring = generateCirclePolygon([139.767, 35.681], 500, 32);
- * ring.length; // 33
- * const polygon = [ring]; // Polygon coordinates
- * ```
  */
 export declare function generateCirclePolygon(center: Coordinate, radiusMeters: number, segments?: number): Coordinate[];
 /**

package/dist/geometry/circle.js

@@ -48,15 +48,6 @@ export function normalizeCircleSegments(segments, fallback = DEFAULT_CIRCLE_SEGM
  * @returns The ring, `segments + 1` positions `[lng, lat]` with the first repeated at the
  *   end. An empty array for a center that is not finite and for a radius that is negative
  *   or not finite
- *
- * @example
- * ```ts
- * import { generateCirclePolygon } from '@sakuzu/maplibre-gl-draw/geometry';
- *
- * const ring = generateCirclePolygon([139.767, 35.681], 500, 32);
- * ring.length; // 33
- * const polygon = [ring]; // Polygon coordinates
- * ```
  */
 export function generateCirclePolygon(center, radiusMeters, segments = DEFAULT_CIRCLE_SEGMENTS) {
     if (!isFiniteCoordinate(center) || !Number.isFinite(radiusMeters) || radiusMeters < 0) {

package/dist/geometry/coords.d.ts

@@ -18,15 +18,6 @@ import type { AreaCoordinates, Coordinate, MultiPolygonCoordinates, Ring } from
  * @param coordinates Polygon or MultiPolygon coordinates
  * @returns `true` for MultiPolygon coordinates (a type guard). `false` for Polygon
  *   coordinates and for coordinates with no position
- *
- * @example
- * ```ts
- * import { isMultiPolygonCoordinates } from '@sakuzu/maplibre-gl-draw/geometry';
- *
- * const ring: [number, number][] = [[0, 0], [1, 0], [1, 1], [0, 0]];
- * isMultiPolygonCoordinates([ring]); // false (Polygon)
- * isMultiPolygonCoordinates([[ring]]); // true (MultiPolygon)
- * ```
  */
 export declare function isMultiPolygonCoordinates(coordinates: AreaCoordinates): coordinates is MultiPolygonCoordinates;
 /**
@@ -75,13 +66,6 @@ export declare function isRingClosed(ring: Ring): boolean;
  *
  * @param ring A coordinate sequence
  * @returns A new closed array. The input itself when it is already closed or empty
- *
- * @example
- * ```ts
- * import { closeRing } from '@sakuzu/maplibre-gl-draw/geometry';
- *
- * closeRing([[0, 0], [1, 0], [1, 1]]); // [[0, 0], [1, 0], [1, 1], [0, 0]]
- * ```
  */
 export declare function closeRing(ring: Ring): Ring;
 /**

package/dist/geometry/coords.js

@@ -13,15 +13,6 @@
  * @param coordinates Polygon or MultiPolygon coordinates
  * @returns `true` for MultiPolygon coordinates (a type guard). `false` for Polygon
  *   coordinates and for coordinates with no position
- *
- * @example
- * ```ts
- * import { isMultiPolygonCoordinates } from '@sakuzu/maplibre-gl-draw/geometry';
- *
- * const ring: [number, number][] = [[0, 0], [1, 0], [1, 1], [0, 0]];
- * isMultiPolygonCoordinates([ring]); // false (Polygon)
- * isMultiPolygonCoordinates([[ring]]); // true (MultiPolygon)
- * ```
  */
 export function isMultiPolygonCoordinates(coordinates) {
     for (const element of coordinates) {
@@ -112,13 +103,6 @@ export function isRingClosed(ring) {
  *
  * @param ring A coordinate sequence
  * @returns A new closed array. The input itself when it is already closed or empty
- *
- * @example
- * ```ts
- * import { closeRing } from '@sakuzu/maplibre-gl-draw/geometry';
- *
- * closeRing([[0, 0], [1, 0], [1, 1]]); // [[0, 0], [1, 0], [1, 1], [0, 0]]
- * ```
  */
 export function closeRing(ring) {
     if (ring.length === 0 || isRingClosed(ring)) {

package/dist/geometry/distance.d.ts

@@ -15,14 +15,6 @@ import type { Coordinate } from './types.js';
  * @param coord1 A position `[lng, lat]` in degrees
  * @param coord2 A position `[lng, lat]` in degrees
  * @returns The distance in meters. 0 for identical positions
- *
- * @example
- * ```ts
- * import { haversineDistanceMeters } from '@sakuzu/maplibre-gl-draw/geometry';
- *
- * // Tokyo Station to Osaka Station
- * haversineDistanceMeters([139.767, 35.681], [135.495, 34.702]); // about 403,139 m
- * ```
  */
 export declare function haversineDistanceMeters(coord1: Coordinate, coord2: Coordinate): number;
 /**
@@ -35,14 +27,6 @@ export declare function haversineDistanceMeters(coord1: Coordinate, coord2: Coor
  * @param to The end `[lng, lat]` in degrees
  * @returns The bearing in degrees, clockwise with north as 0, in the range [0, 360). 0 when
  *   the two positions are identical
- *
- * @example
- * ```ts
- * import { initialBearingDegrees } from '@sakuzu/maplibre-gl-draw/geometry';
- *
- * initialBearingDegrees([0, 0], [1, 0]); // 90 (due east)
- * initialBearingDegrees([0, 0], [0, 1]); // 0 (due north)
- * ```
  */
 export declare function initialBearingDegrees(from: Coordinate, to: Coordinate): number;
 /**
@@ -67,13 +51,5 @@ export declare function initialBearingDegrees(from: Coordinate, to: Coordinate):
  *   goes the opposite way
  * @param bearingDegrees The initial bearing in degrees, clockwise with north as 0
  * @returns The position reached, `[lng, lat]` in degrees
- *
- * @example
- * ```ts
- * import { destinationPoint } from '@sakuzu/maplibre-gl-draw/geometry';
- *
- * // 1 km due east of Tokyo Station
- * destinationPoint([139.767, 35.681], 1000, 90); // [139.77807..., 35.68099...]
- * ```
  */
 export declare function destinationPoint(origin: Coordinate, distanceMeters: number, bearingDegrees: number): Coordinate;

package/dist/geometry/distance.js

@@ -11,14 +11,6 @@ import { EARTH_RADIUS_METERS, toDegrees, toRadians } from './units.js';
  * @param coord1 A position `[lng, lat]` in degrees
  * @param coord2 A position `[lng, lat]` in degrees
  * @returns The distance in meters. 0 for identical positions
- *
- * @example
- * ```ts
- * import { haversineDistanceMeters } from '@sakuzu/maplibre-gl-draw/geometry';
- *
- * // Tokyo Station to Osaka Station
- * haversineDistanceMeters([139.767, 35.681], [135.495, 34.702]); // about 403,139 m
- * ```
  */
 export function haversineDistanceMeters(coord1, coord2) {
     const R = EARTH_RADIUS_METERS;
@@ -41,14 +33,6 @@ export function haversineDistanceMeters(coord1, coord2) {
  * @param to The end `[lng, lat]` in degrees
  * @returns The bearing in degrees, clockwise with north as 0, in the range [0, 360). 0 when
  *   the two positions are identical
- *
- * @example
- * ```ts
- * import { initialBearingDegrees } from '@sakuzu/maplibre-gl-draw/geometry';
- *
- * initialBearingDegrees([0, 0], [1, 0]); // 90 (due east)
- * initialBearingDegrees([0, 0], [0, 1]); // 0 (due north)
- * ```
  */
 export function initialBearingDegrees(from, to) {
     const [lng1, lat1] = from;
@@ -86,14 +70,6 @@ export function initialBearingDegrees(from, to) {
  *   goes the opposite way
  * @param bearingDegrees The initial bearing in degrees, clockwise with north as 0
  * @returns The position reached, `[lng, lat]` in degrees
- *
- * @example
- * ```ts
- * import { destinationPoint } from '@sakuzu/maplibre-gl-draw/geometry';
- *
- * // 1 km due east of Tokyo Station
- * destinationPoint([139.767, 35.681], 1000, 90); // [139.77807..., 35.68099...]
- * ```
  */
 export function destinationPoint(origin, distanceMeters, bearingDegrees) {
     const [lng, lat] = origin;

package/dist/geometry/errors.d.ts

@@ -4,47 +4,32 @@
  * The boolean operations run on polygon-clipping, which reports a failure by throwing an
  * Error whose message is its own internal wording (a sweep-line event, a segment id). Such
  * a failure leaves the module as a GeometryError instead: the reason is a stable code the
- * caller can branch on, and the original error is kept as `cause` for diagnosis.
+ * caller can branch on, and the original error is kept as `cause` for diagnosis. An input
+ * whose shape a function cannot take leaves as a GeometryError too.
  */
 /**
- * Why a geometry operation failed
- *
- * - `invalid-input`: the input is not a polygon the operation can take (a degenerate
- *   segment, a malformed ring)
- * - `unclosed-ring`: the output ring could not be closed, typically because edges nearly
- *   coincide within floating-point precision (still failing after the retry on the grid)
- * - `too-complex`: the operation gave up on an input too large or tangled for it
- * - `internal`: any other failure inside the boolean operation engine
- */
-export type GeometryErrorCode = 'invalid-input' | 'unclosed-ring' | 'too-complex' | 'internal';
-/**
- * The boolean operation that failed.
- *
- * It can differ from the function called: {@link normalizeArea} and {@link unionAll} run
- * `union`, and {@link buffer} runs `union` and `difference`.
+ * Why a geometry function failed: `invalid-input` for an input whose shape the function cannot
+ * take, `engine-failure` for a boolean operation that could not compute a result.
  */
-export type GeometryOperation = 'union' | 'difference' | 'intersection';
+export type GeometryErrorCode = 'invalid-input' | 'engine-failure';
 /**
- * The error a geometry operation throws when the boolean operation engine cannot compute a
- * result.
+ * The error a geometry function throws for an input it cannot take or when its boolean
+ * operation cannot compute a result.
  *
- * Every function that runs a boolean operation can throw it: the boolean operations,
- * {@link splitArea}, {@link buffer}, the polygon predicates and {@link sphericalArea}. A
- * failure is first retried once with the coordinates rounded to a 1e-9 degree grid (about
- * 0.1 mm); this error is thrown only when the retry fails too. Branch on `code`, which is
- * stable across versions of the engine; the message is `<operation>: <reason>` in English
- * and is meant for logs.
+ * A failure of a boolean operation is first retried once with the coordinates rounded to a
+ * 1e-9 degree grid (about 0.1 mm); the error is thrown only when the retry fails too. Branch
+ * on `code`; the message is `<operation>: <reason>` in English and is meant for logs.
  *
  * @example
  * ```ts
- * import type { PolygonCoordinates } from '@sakuzu/maplibre-gl-draw/geometry';
+ * import type { Polygon } from 'geojson';
  * import { GeometryError, union } from '@sakuzu/maplibre-gl-draw/geometry';
  *
- * function tryMerge(a: PolygonCoordinates, b: PolygonCoordinates) {
+ * function tryMerge(a: Polygon, b: Polygon) {
  *   try {
- *     return union(a, b);
+ *     return union([a, b]);
  *   } catch (error) {
- *     if (error instanceof GeometryError && error.code === 'unclosed-ring') {
+ *     if (error instanceof GeometryError && error.code === 'engine-failure') {
  *       // Keep the inputs as they are and tell the user the merge failed
  *       return null;
  *     }
@@ -54,21 +39,21 @@ export type GeometryOperation = 'union' | 'difference' | 'intersection';
  * ```
  */
 export declare class GeometryError extends Error {
-    /** Why the operation failed */
+    /** Why the function failed */
     readonly code: GeometryErrorCode;
-    /** The boolean operation that failed */
-    readonly operation: GeometryOperation;
-    /** The error thrown by the boolean operation engine, kept for diagnosis */
+    /** The name of the function that failed, such as `union` or `buffer` */
+    readonly operation: string;
+    /** The error that caused this one, kept for diagnosis */
     readonly cause: unknown;
     /**
      * Creates the error. The library creates it; a caller only needs to catch it.
      *
-     * @param code Why the operation failed
-     * @param operation The boolean operation that failed
+     * @param code Why the function failed
+     * @param operation The name of the function that failed
      * @param message The message, `<operation>: <reason>`
      * @param options The original error as `cause`
      */
-    constructor(code: GeometryErrorCode, operation: GeometryOperation, message: string, options?: {
+    constructor(code: GeometryErrorCode, operation: string, message: string, options?: {
         cause?: unknown;
     });
 }

package/dist/geometry/errors.js

@@ -1,26 +1,23 @@
 // SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
 // SPDX-License-Identifier: AGPL-3.0-only
 /**
- * The error a geometry operation throws when the boolean operation engine cannot compute a
- * result.
+ * The error a geometry function throws for an input it cannot take or when its boolean
+ * operation cannot compute a result.
  *
- * Every function that runs a boolean operation can throw it: the boolean operations,
- * {@link splitArea}, {@link buffer}, the polygon predicates and {@link sphericalArea}. A
- * failure is first retried once with the coordinates rounded to a 1e-9 degree grid (about
- * 0.1 mm); this error is thrown only when the retry fails too. Branch on `code`, which is
- * stable across versions of the engine; the message is `<operation>: <reason>` in English
- * and is meant for logs.
+ * A failure of a boolean operation is first retried once with the coordinates rounded to a
+ * 1e-9 degree grid (about 0.1 mm); the error is thrown only when the retry fails too. Branch
+ * on `code`; the message is `<operation>: <reason>` in English and is meant for logs.
  *
  * @example
  * ```ts
- * import type { PolygonCoordinates } from '@sakuzu/maplibre-gl-draw/geometry';
+ * import type { Polygon } from 'geojson';
  * import { GeometryError, union } from '@sakuzu/maplibre-gl-draw/geometry';
  *
- * function tryMerge(a: PolygonCoordinates, b: PolygonCoordinates) {
+ * function tryMerge(a: Polygon, b: Polygon) {
  *   try {
- *     return union(a, b);
+ *     return union([a, b]);
  *   } catch (error) {
- *     if (error instanceof GeometryError && error.code === 'unclosed-ring') {
+ *     if (error instanceof GeometryError && error.code === 'engine-failure') {
  *       // Keep the inputs as they are and tell the user the merge failed
  *       return null;
  *     }
@@ -33,28 +30,28 @@ export class GeometryError extends Error {
     /**
      * Creates the error. The library creates it; a caller only needs to catch it.
      *
-     * @param code Why the operation failed
-     * @param operation The boolean operation that failed
+     * @param code Why the function failed
+     * @param operation The name of the function that failed
      * @param message The message, `<operation>: <reason>`
      * @param options The original error as `cause`
      */
     constructor(code, operation, message, options) {
         super(message);
-        /** Why the operation failed */
+        /** Why the function failed */
         Object.defineProperty(this, "code", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
-        /** The boolean operation that failed */
+        /** The name of the function that failed, such as `union` or `buffer` */
         Object.defineProperty(this, "operation", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
-        /** The error thrown by the boolean operation engine, kept for diagnosis */
+        /** The error that caused this one, kept for diagnosis */
         Object.defineProperty(this, "cause", {
             enumerable: true,
             configurable: true,
@@ -70,7 +67,8 @@ export class GeometryError extends Error {
 /**
  * Classifies an error thrown by polygon-clipping by its message
  *
- * The messages are those of polygon-clipping 0.15; one that is not recognized is `internal`.
+ * The messages are those of polygon-clipping 0.15. An input it rejects is `invalid-input`;
+ * everything else is `engine-failure`.
  */
 function classify(error) {
     const message = error instanceof Error ? error.message : String(error);
@@ -78,20 +76,12 @@ function classify(error) {
         message.startsWith('Tried to create degenerate segment')) {
         return 'invalid-input';
     }
-    if (message.startsWith('Unable to complete output ring')) {
-        return 'unclosed-ring';
-    }
-    if (message.startsWith('Infinite loop')) {
-        return 'too-complex';
-    }
-    return 'internal';
+    return 'engine-failure';
 }
-/** The message of each reason */
+/** The message of each reason of a boolean operation */
 const MESSAGES = {
     'invalid-input': 'the input is not a valid polygon',
-    'unclosed-ring': 'the output ring could not be closed',
-    'too-complex': 'the input is too complex',
-    internal: 'the boolean operation failed',
+    'engine-failure': 'the boolean operation failed',
 };
 /**
  * Wraps an error thrown by polygon-clipping into a GeometryError
@@ -102,3 +92,33 @@ export function toGeometryError(error, operation) {
     const code = classify(error);
     return new GeometryError(code, operation, `${operation}: ${MESSAGES[code]}`, { cause: error });
 }
+/**
+ * Creates the error for an input whose shape a function cannot take
+ *
+ * @internal
+ */
+export function invalidInput(operation, reason) {
+    return new GeometryError('invalid-input', operation, `${operation}: ${reason}`);
+}
+/**
+ * Runs a computation and renames the function of a GeometryError it throws
+ *
+ * The boolean operations name themselves (`union`, `difference`, `intersection`); a public
+ * function that runs them reports its own name instead, keeping the reason and the cause.
+ *
+ * @internal
+ */
+export function withOperation(operation, run) {
+    try {
+        return run();
+    }
+    catch (error) {
+        if (error instanceof GeometryError && error.operation !== operation) {
+            const reason = error.message.slice(error.message.indexOf(': ') + 2);
+            throw new GeometryError(error.code, operation, `${operation}: ${reason}`, {
+                cause: error.cause,
+            });
+        }
+        throw error;
+    }
+}

package/dist/geometry/geojson.d.ts

@@ -0,0 +1,85 @@
+/**
+ * GeoJSON input and output of the public functions
+ *
+ * The public functions take GeoJSON geometries, or anything that carries one in a `geometry`
+ * field (GeoJSON features, the features of the drawing), and return GeoJSON geometries;
+ * the computations underneath work on coordinate arrays. These helpers take the coordinates
+ * out of an input, reject an input whose shape a function cannot take with a GeometryError
+ * (`invalid-input`), and wrap the computed coordinates back into a geometry.
+ */
+import type { Geometry, LineString, MultiLineString, MultiPolygon, Point, Polygon, Position } from 'geojson';
+import type { AreaCoordinates, Coordinate, MultiPolygonCoordinates } from './types.js';
+/** A point as taken by the public functions */
+export type PointInput = Position | Point;
+/** A polygon as taken by the public functions */
+export type AreaInput = Polygon | MultiPolygon | {
+    readonly geometry: Geometry;
+};
+/** A line as taken by the public functions */
+export type LineInput = LineString | MultiLineString | {
+    readonly geometry: Geometry;
+};
+/**
+ * Returns the geometry of a geometry, or of anything that carries one in a `geometry` field
+ * (a GeoJSON feature, a feature of the drawing)
+ *
+ * A value whose `geometry` member is a geometry is read as a feature first, whatever its own
+ * `type` says: a feature of the drawing names its feature type there (`'Polygon'`,
+ * `'Circle'`, `'Freehand'` and so on), which is not the type of a geometry it is.
+ *
+ * @throws GeometryError (`invalid-input`) for a value that is neither, and for a feature
+ *   without a geometry
+ */
+export declare function geometryOf(input: Geometry | {
+    readonly geometry: Geometry;
+}, operation: string): Geometry;
+/**
+ * Returns the coordinates of a point given as a position or a Point
+ *
+ * @throws GeometryError (`invalid-input`) for anything else
+ */
+export declare function positionOf(input: PointInput, operation: string): Coordinate;
+/**
+ * Returns the geometry of a Polygon or a MultiPolygon, given as it is or in a feature
+ *
+ * @throws GeometryError (`invalid-input`) for any other geometry
+ */
+export declare function areaGeometryOf(input: AreaInput, operation: string): Polygon | MultiPolygon;
+/**
+ * Returns the coordinates of a Polygon or a MultiPolygon, given as it is or in a feature
+ *
+ * @throws GeometryError (`invalid-input`) for any other geometry
+ */
+export declare function areaOf(input: AreaInput, operation: string): AreaCoordinates;
+/**
+ * Returns the coordinates of each polygon in an array
+ *
+ * @throws GeometryError (`invalid-input`) for a value that is not an array, and for an
+ *   element that is not a Polygon or a MultiPolygon
+ */
+export declare function areasOf(inputs: readonly AreaInput[], operation: string): AreaCoordinates[];
+/**
+ * Returns the coordinates of a LineString, given as it is or in a feature
+ *
+ * @throws GeometryError (`invalid-input`) for any other geometry
+ */
+export declare function lineOf(input: LineString | {
+    readonly geometry: Geometry;
+}, operation: string): Coordinate[];
+/**
+ * Returns the lines of a LineString or a MultiLineString, given as it is or in a feature
+ *
+ * @throws GeometryError (`invalid-input`) for any other geometry
+ */
+export declare function linesOf(input: LineInput, operation: string): Coordinate[][];
+/** Every position of a geometry, the members of a collection included */
+export declare function positionsOf(geometry: Geometry): Coordinate[];
+/** A copy of a position, as returned by the public functions */
+export declare function toPosition(coordinate: Coordinate): Position;
+/** A Point geometry at a position */
+export declare function toPoint(coordinate: Coordinate): Point;
+/**
+ * Wraps MultiPolygon coordinates into a geometry: a Polygon for one part, a MultiPolygon for
+ * several, and null for none
+ */
+export declare function toAreaGeometry(coordinates: MultiPolygonCoordinates): Polygon | MultiPolygon | null;