@sakuzu/maplibre-gl-draw 1.0.0

package/dist/geometry/boolean.d.ts

@@ -0,0 +1,162 @@
+import type { AreaCoordinates, MultiPolygonCoordinates } from './types.js';
+/**
+ * Converts Polygon or MultiPolygon coordinates into normalized MultiPolygon coordinates.
+ *
+ * Resolves self-intersections (a figure-eight becomes two parts), unifies the ring
+ * orientations (outer rings counter-clockwise, holes clockwise) and removes the rings that
+ * have no area. Rings with fewer than 3 positions or with a position that is not finite are
+ * dropped first, and a part whose outer ring is dropped is dropped with its holes.
+ *
+ * @param coordinates Polygon or MultiPolygon coordinates in degrees
+ * @returns The normalized MultiPolygon coordinates, each ring closed. An empty array means
+ *   the input has no area
+ * @throws {@link GeometryError} when the boolean operation engine fails even after the
+ *   retry on the 1e-9 degree grid
+ *
+ * @example
+ * ```ts
+ * import { normalizeArea } from '@sakuzu/maplibre-gl-draw/geometry';
+ *
+ * // A self-intersecting bow tie becomes two triangles
+ * normalizeArea([[[0, 0], [1, 1], [1, 0], [0, 1], [0, 0]]]);
+ * // [[[[0, 0], [0.5, 0.5], [0, 1], [0, 0]]], [[[0.5, 0.5], [1, 0], [1, 1], [0.5, 0.5]]]]
+ * ```
+ */
+export declare function normalizeArea(coordinates: AreaCoordinates): MultiPolygonCoordinates;
+/**
+ * Returns the union of two polygons.
+ *
+ * The operation is topological and runs on the lng/lat plane as it is. Rings that cannot
+ * bound an area are dropped first (see {@link normalizeArea}), so an input with no area
+ * leaves the other input normalized.
+ *
+ * @param a Polygon or MultiPolygon coordinates in degrees
+ * @param b Polygon or MultiPolygon coordinates in degrees
+ * @returns The normalized MultiPolygon coordinates of the union. Disjoint inputs become
+ *   several parts. An empty array when neither input has an area
+ * @throws {@link GeometryError} when the boolean operation engine fails even after the
+ *   retry on the 1e-9 degree grid
+ *
+ * @example
+ * ```ts
+ * import type { PolygonCoordinates } from '@sakuzu/maplibre-gl-draw/geometry';
+ * import { union } from '@sakuzu/maplibre-gl-draw/geometry';
+ *
+ * const a: PolygonCoordinates = [[[0, 0], [1, 0], [1, 1], [0, 1], [0, 0]]];
+ * const b: PolygonCoordinates = [[[0.5, 0], [1.5, 0], [1.5, 1], [0.5, 1], [0.5, 0]]];
+ * union(a, b); // [[[[0, 0], [1.5, 0], [1.5, 1], [0, 1], [0, 0]]]]
+ * ```
+ */
+export declare function union(a: AreaCoordinates, b: AreaCoordinates): MultiPolygonCoordinates;
+/**
+ * Returns the part of one polygon that lies outside another.
+ *
+ * Removing a region inside `a` produces a hole (an inner ring).
+ *
+ * @param a The Polygon or MultiPolygon coordinates to subtract from, in degrees
+ * @param b The Polygon or MultiPolygon coordinates to subtract, in degrees
+ * @returns The normalized MultiPolygon coordinates of `a` with `b` removed. An empty array
+ *   when `a` has no area or `b` covers it. `a` normalized when `b` has no area
+ * @throws {@link GeometryError} when the boolean operation engine fails even after the
+ *   retry on the 1e-9 degree grid
+ *
+ * @example
+ * ```ts
+ * import type { PolygonCoordinates } from '@sakuzu/maplibre-gl-draw/geometry';
+ * import { difference } from '@sakuzu/maplibre-gl-draw/geometry';
+ *
+ * const a: PolygonCoordinates = [[[0, 0], [1, 0], [1, 1], [0, 1], [0, 0]]];
+ * const b: PolygonCoordinates = [[[0.5, 0], [1.5, 0], [1.5, 1], [0.5, 1], [0.5, 0]]];
+ * difference(a, b); // [[[[0, 0], [0.5, 0], [0.5, 1], [0, 1], [0, 0]]]]
+ * ```
+ */
+export declare function difference(a: AreaCoordinates, b: AreaCoordinates): MultiPolygonCoordinates;
+/**
+ * Returns the common part of two polygons.
+ *
+ * @param a Polygon or MultiPolygon coordinates in degrees
+ * @param b Polygon or MultiPolygon coordinates in degrees
+ * @returns The normalized MultiPolygon coordinates of the common part. An empty array when
+ *   the inputs do not overlap, when only their boundaries touch, and when either has no
+ *   area
+ * @throws {@link GeometryError} when the boolean operation engine fails even after the
+ *   retry on the 1e-9 degree grid
+ *
+ * @example
+ * ```ts
+ * import type { PolygonCoordinates } from '@sakuzu/maplibre-gl-draw/geometry';
+ * import { intersection } from '@sakuzu/maplibre-gl-draw/geometry';
+ *
+ * const a: PolygonCoordinates = [[[0, 0], [1, 0], [1, 1], [0, 1], [0, 0]]];
+ * const b: PolygonCoordinates = [[[0.5, 0], [1.5, 0], [1.5, 1], [0.5, 1], [0.5, 0]]];
+ * intersection(a, b); // [[[[0.5, 0], [1, 0], [1, 1], [0.5, 1], [0.5, 0]]]]
+ * ```
+ */
+export declare function intersection(a: AreaCoordinates, b: AreaCoordinates): MultiPolygonCoordinates;
+/**
+ * Keeps only the part of a subject polygon that lies inside a clip region.
+ *
+ * Between polygons it is the same operation as {@link intersection}; it differs only in
+ * that the meaning of the arguments (the subject and the region) is fixed.
+ *
+ * @param subject The Polygon or MultiPolygon coordinates to clip, in degrees
+ * @param clipRegion The Polygon or MultiPolygon coordinates of the region, in degrees
+ * @returns The normalized MultiPolygon coordinates that remain inside the region. An empty
+ *   array when nothing remains or either input has no area
+ * @throws {@link GeometryError} when the boolean operation engine fails even after the
+ *   retry on the 1e-9 degree grid
+ */
+export declare function clip(subject: AreaCoordinates, clipRegion: AreaCoordinates): MultiPolygonCoordinates;
+/**
+ * Returns the union of every polygon in an array.
+ *
+ * Passing many inputs to the engine at once can make it fail to close the output ring, so
+ * they are folded in the shape of a binary tree (cascaded union). The union is associative
+ * and the order of the folding is fixed, so the result is deterministic. Elements with no
+ * area are skipped.
+ *
+ * @param geometries Polygon or MultiPolygon coordinates in degrees
+ * @returns The normalized MultiPolygon coordinates of the union. An empty array for an
+ *   empty array and when no element has an area
+ * @throws {@link GeometryError} when the boolean operation engine fails even after the
+ *   retry on the 1e-9 degree grid
+ *
+ * @example
+ * ```ts
+ * import { unionAll } from '@sakuzu/maplibre-gl-draw/geometry';
+ *
+ * const merged = unionAll([
+ *   [[[0, 0], [1, 0], [1, 1], [0, 1], [0, 0]]],
+ *   [[[0.5, 0], [1.5, 0], [1.5, 1], [0.5, 1], [0.5, 0]]],
+ *   [[[5, 5], [6, 5], [6, 6], [5, 5]]],
+ * ]);
+ * merged.length; // 2 (the overlapping squares fuse; the triangle stays apart)
+ * ```
+ */
+export declare function unionAll(geometries: AreaCoordinates[]): MultiPolygonCoordinates;
+/**
+ * Returns the part common to every polygon in an array.
+ *
+ * The intersection shrinks monotonically, so the elements are folded in order from the
+ * head and the fold stops as soon as it becomes empty.
+ *
+ * @param geometries Polygon or MultiPolygon coordinates in degrees
+ * @returns The normalized MultiPolygon coordinates common to all of them. An empty array for
+ *   an empty array and when even one element has no area
+ * @throws {@link GeometryError} when the boolean operation engine fails even after the
+ *   retry on the 1e-9 degree grid
+ */
+export declare function intersectionAll(geometries: AreaCoordinates[]): MultiPolygonCoordinates;
+/**
+ * Returns a subject polygon with every polygon in an array removed.
+ *
+ * @param subject The Polygon or MultiPolygon coordinates to subtract from, in degrees
+ * @param geometries The Polygon or MultiPolygon coordinates to subtract, in degrees.
+ *   Elements with no area are skipped
+ * @returns The normalized MultiPolygon coordinates of the difference. An empty array when
+ *   the subject has no area or is covered. The subject normalized when nothing is
+ *   subtracted
+ * @throws {@link GeometryError} when the boolean operation engine fails even after the
+ *   retry on the 1e-9 degree grid
+ */
+export declare function differenceAll(subject: AreaCoordinates, geometries: AreaCoordinates[]): MultiPolygonCoordinates;

package/dist/geometry/boolean.js

@@ -0,0 +1,331 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Boolean operations
+ *
+ * The body is polygon-clipping. The input accepts either Polygon coordinates or
+ * MultiPolygon coordinates, and the result is always returned as MultiPolygon
+ * coordinates. Because these are topological operations that use no metric of
+ * distance or area, they close correctly on the lng/lat plane as it is.
+ */
+import polygonClipping from 'polygon-clipping';
+import { usableAreaParts } from './coords.js';
+import { toGeometryError } from './errors.js';
+/**
+ * Shapes the input into a form that can be passed to polygon-clipping
+ *
+ * A ring that cannot bound an area (fewer than 3 points, or a coordinate that is not a
+ * finite number) is dropped, and a part whose outer ring is dropped is removed with its
+ * holes. polygon-clipping itself throws an internal error on NaN and silently drops
+ * Infinity, so this is the boundary that keeps such input from reaching it.
+ */
+function sanitize(coordinates) {
+    return usableAreaParts(coordinates);
+}
+/**
+ * The step of the grid onto which the coordinates are placed on a retry (degrees)
+ *
+ * 1e-9 degrees is roughly 0.1mm at the equator, and the displacement caused by the
+ * rounding is half of that, so it does not show up in the measurements of a feature
+ * (the same step as NODE_QUANTUM in split.ts). On the other hand it is 5 digits larger
+ * than the smallest step of double precision (about 1.4e-14 degrees in the 140-degree
+ * longitude range), so a discrepancy arising from cancellation is absorbed for certain.
+ */
+const SNAP_QUANTUM = 1e-9;
+/**
+ * Returns a copy with the coordinates placed onto the grid
+ */
+function snap(parts) {
+    return parts.map((polygon) => polygon.map((ring) => ring.map(([x, y]) => [
+        Math.round(x / SNAP_QUANTUM) * SNAP_QUANTUM,
+        Math.round(y / SNAP_QUANTUM) * SNAP_QUANTUM,
+    ])));
+}
+/** The operations of polygon-clipping, by name */
+const OPERATIONS = {
+    union: polygonClipping.union,
+    difference: polygonClipping.difference,
+    intersection: polygonClipping.intersection,
+};
+/**
+ * Calls polygon-clipping and, only when it fails, rounds the coordinates and retries
+ * once
+ *
+ * Vertices that adjacent polygons hold on the same edge can differ by the smallest step
+ * of double precision when they are produced by separate operations. polygon-clipping
+ * regards this difference as identical in its comparisons while treating the points as
+ * distinct in value, so it fails to close the output ring and throws an exception.
+ * Placing the coordinates back onto the grid makes the shifted vertices take the same
+ * value, and the same operation then succeeds.
+ *
+ * The rounding is applied only to the input that failed. If every input were rounded in
+ * advance, there are inputs in which edges that were barely separated by the jitter
+ * would overlap completely and become unsolvable instead (the buffer of a nearly
+ * collinear line is a real example). The rule of the rounding is deterministic, so even
+ * when the retry is entered the result is determined by the input alone.
+ *
+ * When the retry fails too, the error leaves as a GeometryError with a reason code
+ * instead of the internal message of polygon-clipping.
+ */
+function run(operation, parts) {
+    const clipper = OPERATIONS[operation];
+    const [first, ...rest] = parts;
+    try {
+        return clipper(first, ...rest);
+    }
+    catch {
+        const [snapped, ...snappedRest] = parts.map(snap);
+        try {
+            return clipper(snapped, ...snappedRest);
+        }
+        catch (error) {
+            throw toGeometryError(error, operation);
+        }
+    }
+}
+/**
+ * Resolves self-intersections and normalizes the orientations (the normalized form of
+ * polygon-clipping)
+ */
+function normalize(coordinates) {
+    if (coordinates.length === 0) {
+        return [];
+    }
+    return run('union', [coordinates]);
+}
+/**
+ * Converts Polygon or MultiPolygon coordinates into normalized MultiPolygon coordinates.
+ *
+ * Resolves self-intersections (a figure-eight becomes two parts), unifies the ring
+ * orientations (outer rings counter-clockwise, holes clockwise) and removes the rings that
+ * have no area. Rings with fewer than 3 positions or with a position that is not finite are
+ * dropped first, and a part whose outer ring is dropped is dropped with its holes.
+ *
+ * @param coordinates Polygon or MultiPolygon coordinates in degrees
+ * @returns The normalized MultiPolygon coordinates, each ring closed. An empty array means
+ *   the input has no area
+ * @throws {@link GeometryError} when the boolean operation engine fails even after the
+ *   retry on the 1e-9 degree grid
+ *
+ * @example
+ * ```ts
+ * import { normalizeArea } from '@sakuzu/maplibre-gl-draw/geometry';
+ *
+ * // A self-intersecting bow tie becomes two triangles
+ * normalizeArea([[[0, 0], [1, 1], [1, 0], [0, 1], [0, 0]]]);
+ * // [[[[0, 0], [0.5, 0.5], [0, 1], [0, 0]]], [[[0.5, 0.5], [1, 0], [1, 1], [0.5, 0.5]]]]
+ * ```
+ */
+export function normalizeArea(coordinates) {
+    return normalize(sanitize(coordinates));
+}
+/**
+ * Returns the union of two polygons.
+ *
+ * The operation is topological and runs on the lng/lat plane as it is. Rings that cannot
+ * bound an area are dropped first (see {@link normalizeArea}), so an input with no area
+ * leaves the other input normalized.
+ *
+ * @param a Polygon or MultiPolygon coordinates in degrees
+ * @param b Polygon or MultiPolygon coordinates in degrees
+ * @returns The normalized MultiPolygon coordinates of the union. Disjoint inputs become
+ *   several parts. An empty array when neither input has an area
+ * @throws {@link GeometryError} when the boolean operation engine fails even after the
+ *   retry on the 1e-9 degree grid
+ *
+ * @example
+ * ```ts
+ * import type { PolygonCoordinates } from '@sakuzu/maplibre-gl-draw/geometry';
+ * import { union } from '@sakuzu/maplibre-gl-draw/geometry';
+ *
+ * const a: PolygonCoordinates = [[[0, 0], [1, 0], [1, 1], [0, 1], [0, 0]]];
+ * const b: PolygonCoordinates = [[[0.5, 0], [1.5, 0], [1.5, 1], [0.5, 1], [0.5, 0]]];
+ * union(a, b); // [[[[0, 0], [1.5, 0], [1.5, 1], [0, 1], [0, 0]]]]
+ * ```
+ */
+export function union(a, b) {
+    const left = sanitize(a);
+    const right = sanitize(b);
+    if (left.length === 0) {
+        return normalize(right);
+    }
+    if (right.length === 0) {
+        return normalize(left);
+    }
+    return run('union', [left, right]);
+}
+/**
+ * Returns the part of one polygon that lies outside another.
+ *
+ * Removing a region inside `a` produces a hole (an inner ring).
+ *
+ * @param a The Polygon or MultiPolygon coordinates to subtract from, in degrees
+ * @param b The Polygon or MultiPolygon coordinates to subtract, in degrees
+ * @returns The normalized MultiPolygon coordinates of `a` with `b` removed. An empty array
+ *   when `a` has no area or `b` covers it. `a` normalized when `b` has no area
+ * @throws {@link GeometryError} when the boolean operation engine fails even after the
+ *   retry on the 1e-9 degree grid
+ *
+ * @example
+ * ```ts
+ * import type { PolygonCoordinates } from '@sakuzu/maplibre-gl-draw/geometry';
+ * import { difference } from '@sakuzu/maplibre-gl-draw/geometry';
+ *
+ * const a: PolygonCoordinates = [[[0, 0], [1, 0], [1, 1], [0, 1], [0, 0]]];
+ * const b: PolygonCoordinates = [[[0.5, 0], [1.5, 0], [1.5, 1], [0.5, 1], [0.5, 0]]];
+ * difference(a, b); // [[[[0, 0], [0.5, 0], [0.5, 1], [0, 1], [0, 0]]]]
+ * ```
+ */
+export function difference(a, b) {
+    const left = sanitize(a);
+    const right = sanitize(b);
+    if (left.length === 0) {
+        return [];
+    }
+    if (right.length === 0) {
+        return normalize(left);
+    }
+    return run('difference', [left, right]);
+}
+/**
+ * Returns the common part of two polygons.
+ *
+ * @param a Polygon or MultiPolygon coordinates in degrees
+ * @param b Polygon or MultiPolygon coordinates in degrees
+ * @returns The normalized MultiPolygon coordinates of the common part. An empty array when
+ *   the inputs do not overlap, when only their boundaries touch, and when either has no
+ *   area
+ * @throws {@link GeometryError} when the boolean operation engine fails even after the
+ *   retry on the 1e-9 degree grid
+ *
+ * @example
+ * ```ts
+ * import type { PolygonCoordinates } from '@sakuzu/maplibre-gl-draw/geometry';
+ * import { intersection } from '@sakuzu/maplibre-gl-draw/geometry';
+ *
+ * const a: PolygonCoordinates = [[[0, 0], [1, 0], [1, 1], [0, 1], [0, 0]]];
+ * const b: PolygonCoordinates = [[[0.5, 0], [1.5, 0], [1.5, 1], [0.5, 1], [0.5, 0]]];
+ * intersection(a, b); // [[[[0.5, 0], [1, 0], [1, 1], [0.5, 1], [0.5, 0]]]]
+ * ```
+ */
+export function intersection(a, b) {
+    const left = sanitize(a);
+    const right = sanitize(b);
+    if (left.length === 0 || right.length === 0) {
+        return [];
+    }
+    return run('intersection', [left, right]);
+}
+/**
+ * Keeps only the part of a subject polygon that lies inside a clip region.
+ *
+ * Between polygons it is the same operation as {@link intersection}; it differs only in
+ * that the meaning of the arguments (the subject and the region) is fixed.
+ *
+ * @param subject The Polygon or MultiPolygon coordinates to clip, in degrees
+ * @param clipRegion The Polygon or MultiPolygon coordinates of the region, in degrees
+ * @returns The normalized MultiPolygon coordinates that remain inside the region. An empty
+ *   array when nothing remains or either input has no area
+ * @throws {@link GeometryError} when the boolean operation engine fails even after the
+ *   retry on the 1e-9 degree grid
+ */
+export function clip(subject, clipRegion) {
+    return intersection(subject, clipRegion);
+}
+/**
+ * Returns the union of every polygon in an array.
+ *
+ * Passing many inputs to the engine at once can make it fail to close the output ring, so
+ * they are folded in the shape of a binary tree (cascaded union). The union is associative
+ * and the order of the folding is fixed, so the result is deterministic. Elements with no
+ * area are skipped.
+ *
+ * @param geometries Polygon or MultiPolygon coordinates in degrees
+ * @returns The normalized MultiPolygon coordinates of the union. An empty array for an
+ *   empty array and when no element has an area
+ * @throws {@link GeometryError} when the boolean operation engine fails even after the
+ *   retry on the 1e-9 degree grid
+ *
+ * @example
+ * ```ts
+ * import { unionAll } from '@sakuzu/maplibre-gl-draw/geometry';
+ *
+ * const merged = unionAll([
+ *   [[[0, 0], [1, 0], [1, 1], [0, 1], [0, 0]]],
+ *   [[[0.5, 0], [1.5, 0], [1.5, 1], [0.5, 1], [0.5, 0]]],
+ *   [[[5, 5], [6, 5], [6, 6], [5, 5]]],
+ * ]);
+ * merged.length; // 2 (the overlapping squares fuse; the triangle stays apart)
+ * ```
+ */
+export function unionAll(geometries) {
+    const parts = geometries.map(sanitize).filter((part) => part.length > 0);
+    if (parts.length === 0) {
+        return [];
+    }
+    if (parts.length === 1) {
+        return run('union', [parts[0]]);
+    }
+    let level = parts;
+    while (level.length > 1) {
+        const next = [];
+        for (let i = 0; i < level.length; i += 2) {
+            // The odd one out is carried up to the next level as it is
+            next.push(i + 1 < level.length ? run('union', [level[i], level[i + 1]]) : level[i]);
+        }
+        level = next;
+    }
+    return level[0];
+}
+/**
+ * Returns the part common to every polygon in an array.
+ *
+ * The intersection shrinks monotonically, so the elements are folded in order from the
+ * head and the fold stops as soon as it becomes empty.
+ *
+ * @param geometries Polygon or MultiPolygon coordinates in degrees
+ * @returns The normalized MultiPolygon coordinates common to all of them. An empty array for
+ *   an empty array and when even one element has no area
+ * @throws {@link GeometryError} when the boolean operation engine fails even after the
+ *   retry on the 1e-9 degree grid
+ */
+export function intersectionAll(geometries) {
+    if (geometries.length === 0) {
+        return [];
+    }
+    const parts = geometries.map(sanitize);
+    if (parts.some((part) => part.length === 0)) {
+        return [];
+    }
+    let result = normalize(parts[0]);
+    for (let i = 1; i < parts.length; i++) {
+        if (result.length === 0) {
+            return [];
+        }
+        result = run('intersection', [result, parts[i]]);
+    }
+    return result;
+}
+/**
+ * Returns a subject polygon with every polygon in an array removed.
+ *
+ * @param subject The Polygon or MultiPolygon coordinates to subtract from, in degrees
+ * @param geometries The Polygon or MultiPolygon coordinates to subtract, in degrees.
+ *   Elements with no area are skipped
+ * @returns The normalized MultiPolygon coordinates of the difference. An empty array when
+ *   the subject has no area or is covered. The subject normalized when nothing is
+ *   subtracted
+ * @throws {@link GeometryError} when the boolean operation engine fails even after the
+ *   retry on the 1e-9 degree grid
+ */
+export function differenceAll(subject, geometries) {
+    const left = sanitize(subject);
+    if (left.length === 0) {
+        return [];
+    }
+    const parts = geometries.map(sanitize).filter((part) => part.length > 0);
+    if (parts.length === 0) {
+        return normalize(left);
+    }
+    return run('difference', [left, ...parts]);
+}

package/dist/geometry/buffer.d.ts

@@ -0,0 +1,72 @@
+import type { GeometryInput, MultiPolygonCoordinates } from './types.js';
+/** The default number of segments per circle of {@link buffer}: 64. */
+export declare const DEFAULT_BUFFER_SEGMENTS = 64;
+/**
+ * The options of {@link buffer}.
+ */
+export interface BufferOptions {
+    /**
+     * The number of segments of the arc parts (64 by default). Rounded down and clamped to
+     * 3-1024; NaN gives the default
+     */
+    segments?: number;
+}
+/**
+ * Builds the area within a distance in meters of a geometry.
+ *
+ * The distances are laid out without a map projection, through {@link destinationPoint},
+ * the direct problem on the sphere. Every generated vertex lies at the buffer distance from
+ * its source vertex at any latitude, up to floating-point rounding; the edges between the
+ * generated vertices are straight in longitude and latitude. A point becomes a circle (the
+ * same as {@link generateCirclePolygon}); a line becomes the union of a circle at each
+ * vertex and a band along each edge, offset ±90 degrees from the great-circle bearing of
+ * the edge; a polygon becomes the union (positive distance) or the difference (negative
+ * distance) of the original polygon and the band along its rings.
+ *
+ * | Input | Positive | 0 | Negative |
+ * | --- | --- | --- | --- |
+ * | Point / MultiPoint | circle | `null` | `null` |
+ * | LineString / MultiLineString | band | `null` | `null` |
+ * | Polygon / MultiPolygon | expansion | normalized original | contraction |
+ *
+ * With a negative distance, parts narrower than `2 * |meters|` disappear, and an empty array
+ * is returned when the whole polygon disappears. `null` means the operation is not defined
+ * for the input: the table above, a distance that is not finite, a coordinate that is not
+ * finite, a vertex whose distance reaches a pole (`|lat|` plus the distance in degrees of
+ * latitude is 90 or more), and an edge that spans more than 180 degrees of longitude.
+ *
+ * @param geometry The geometry to buffer, coordinates in degrees
+ * @param meters The buffer distance in meters. A negative value shrinks a polygon
+ * @param options The number of segments per circle
+ * @returns The normalized MultiPolygon coordinates of the area. An empty array when a
+ *   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;