osm2geojson-lite 1.2.0 → 2.0.1

package/README.md

@@ -34,6 +34,11 @@ Usage:
     let geojson = osm2geojson(osm, opts);
 ```
 
+### In the command line
+```sh
+    npx osm2geojson-lite --help
+```
+
 API
 ---
 

package/dist/cli.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { readFile, writeFile } from "node:fs/promises";
+import osm2geojson from "./index.js";
+//#region src/cli.ts
+function printHelp() {
+	process.stdout.write([
+		"Convert OpenStreetMap XML or JSON data to GeoJSON.",
+		"",
+		"Usage:",
+		"  npx osm2geojson INPUT_FILE OUTPUT_FILE",
+		"  npx osm2geojson < INPUT_FILE > OUTPUT_FILE",
+		""
+	].join("\n"));
+}
+async function main(positionals) {
+	const [inputFile = "/dev/stdin", outputFile = "/dev/stdout"] = positionals;
+	const geojson = osm2geojson(await readFile(inputFile, "utf-8"), {
+		completeFeature: true,
+		renderTagged: true
+	});
+	await writeFile(outputFile, `${JSON.stringify(geojson)}\n`);
+}
+const { values, positionals } = parseArgs({
+	args: process.argv.slice(2),
+	options: { help: {
+		short: "h",
+		type: "boolean"
+	} }
+});
+if (values.help) printHelp();
+else main(positionals).catch((err) => {
+	process.stderr.write(`${err.stack}\n`);
+	process.exit(1);
+});
+//#endregion

package/dist/index.d.ts

@@ -0,0 +1,203 @@
+//#region node_modules/@types/geojson/index.d.ts
+/**
+ * The value values for the "type" property of GeoJSON Objects.
+ * https://tools.ietf.org/html/rfc7946#section-1.4
+ */
+type GeoJsonTypes = GeoJSON["type"];
+/**
+ * Bounding box
+ * https://tools.ietf.org/html/rfc7946#section-5
+ */
+type BBox = [number, number, number, number] | [number, number, number, number, number, number];
+/**
+ * A Position is an array of coordinates.
+ * https://tools.ietf.org/html/rfc7946#section-3.1.1
+ * Array should contain between two and three elements.
+ * The previous GeoJSON specification allowed more elements (e.g., which could be used to represent M values),
+ * but the current specification only allows X, Y, and (optionally) Z to be defined.
+ *
+ * Note: the type will not be narrowed down to `[number, number] | [number, number, number]` due to
+ * marginal benefits and the large impact of breaking change.
+ *
+ * See previous discussions on the type narrowing:
+ * - {@link https://github.com/DefinitelyTyped/DefinitelyTyped/pull/21590|Nov 2017}
+ * - {@link https://github.com/DefinitelyTyped/DefinitelyTyped/discussions/67773|Dec 2023}
+ * - {@link https://github.com/DefinitelyTyped/DefinitelyTyped/discussions/71441| Dec 2024}
+ *
+ * One can use a
+ * {@link https://www.typescriptlang.org/docs/handbook/2/narrowing.html#using-type-predicates|user-defined type guard that returns a type predicate}
+ * to determine if a position is a 2D or 3D position.
+ *
+ * @example
+ * import type { Position } from 'geojson';
+ *
+ * type StrictPosition = [x: number, y: number] | [x: number, y: number, z: number]
+ *
+ * function isStrictPosition(position: Position): position is StrictPosition {
+ *   return position.length === 2 || position.length === 3
+ * };
+ *
+ * let position: Position = [-116.91, 45.54];
+ *
+ * let x: number;
+ * let y: number;
+ * let z: number | undefined;
+ *
+ * if (isStrictPosition(position)) {
+ *   // `tsc` would throw an error if we tried to destructure a fourth parameter
+ * 	 [x, y, z] = position;
+ * } else {
+ * 	 throw new TypeError("Position is not a 2D or 3D point");
+ * }
+ */
+type Position = number[];
+/**
+ * The base GeoJSON object.
+ * https://tools.ietf.org/html/rfc7946#section-3
+ * The GeoJSON specification also allows foreign members
+ * (https://tools.ietf.org/html/rfc7946#section-6.1)
+ * Developers should use "&" type in TypeScript or extend the interface
+ * to add these foreign members.
+ */
+interface GeoJsonObject {
+  // Don't include foreign members directly into this type def.
+  // in order to preserve type safety.
+  // [key: string]: any;
+  /**
+   * Specifies the type of GeoJSON object.
+   */
+  type: GeoJsonTypes;
+  /**
+   * Bounding box of the coordinate range of the object's Geometries, Features, or Feature Collections.
+   * The value of the bbox member is an array of length 2*n where n is the number of dimensions
+   * represented in the contained geometries, with all axes of the most southwesterly point
+   * followed by all axes of the more northeasterly point.
+   * The axes order of a bbox follows the axes order of geometries.
+   * https://tools.ietf.org/html/rfc7946#section-5
+   */
+  bbox?: BBox | undefined;
+}
+/**
+ * Union of GeoJSON objects.
+ */
+type GeoJSON<G extends Geometry | null = Geometry, P = GeoJsonProperties> = G | Feature<G, P> | FeatureCollection<G, P>;
+/**
+ * Geometry object.
+ * https://tools.ietf.org/html/rfc7946#section-3
+ */
+type Geometry = Point | MultiPoint | LineString | MultiLineString | Polygon | MultiPolygon | GeometryCollection;
+type GeometryObject = Geometry;
+/**
+ * Point geometry object.
+ * https://tools.ietf.org/html/rfc7946#section-3.1.2
+ */
+interface Point extends GeoJsonObject {
+  type: "Point";
+  coordinates: Position;
+}
+/**
+ * MultiPoint geometry object.
+ *  https://tools.ietf.org/html/rfc7946#section-3.1.3
+ */
+interface MultiPoint extends GeoJsonObject {
+  type: "MultiPoint";
+  coordinates: Position[];
+}
+/**
+ * LineString geometry object.
+ * https://tools.ietf.org/html/rfc7946#section-3.1.4
+ */
+interface LineString extends GeoJsonObject {
+  type: "LineString";
+  coordinates: Position[];
+}
+/**
+ * MultiLineString geometry object.
+ * https://tools.ietf.org/html/rfc7946#section-3.1.5
+ */
+interface MultiLineString extends GeoJsonObject {
+  type: "MultiLineString";
+  coordinates: Position[][];
+}
+/**
+ * Polygon geometry object.
+ * https://tools.ietf.org/html/rfc7946#section-3.1.6
+ */
+interface Polygon extends GeoJsonObject {
+  type: "Polygon";
+  coordinates: Position[][];
+}
+/**
+ * MultiPolygon geometry object.
+ * https://tools.ietf.org/html/rfc7946#section-3.1.7
+ */
+interface MultiPolygon extends GeoJsonObject {
+  type: "MultiPolygon";
+  coordinates: Position[][][];
+}
+/**
+ * Geometry Collection
+ * https://tools.ietf.org/html/rfc7946#section-3.1.8
+ */
+interface GeometryCollection<G extends Geometry = Geometry> extends GeoJsonObject {
+  type: "GeometryCollection";
+  geometries: G[];
+}
+type GeoJsonProperties = {
+  [name: string]: any;
+} | null;
+/**
+ * A feature object which contains a geometry and associated properties.
+ * https://tools.ietf.org/html/rfc7946#section-3.2
+ */
+interface Feature<G extends Geometry | null = Geometry, P = GeoJsonProperties> extends GeoJsonObject {
+  type: "Feature";
+  /**
+   * The feature's geometry
+   */
+  geometry: G;
+  /**
+   * A value that uniquely identifies this feature in a
+   * https://tools.ietf.org/html/rfc7946#section-3.2.
+   */
+  id?: string | number | undefined;
+  /**
+   * Properties associated with this feature.
+   */
+  properties: P;
+}
+/**
+ * A collection of feature objects.
+ *  https://tools.ietf.org/html/rfc7946#section-3.3
+ */
+interface FeatureCollection<G extends Geometry | null = Geometry, P = GeoJsonProperties> extends GeoJsonObject {
+  type: "FeatureCollection";
+  features: Array<Feature<G, P>>;
+}
+//#endregion
+//#region src/index.d.ts
+interface IOptions {
+  /**
+   * When it's set to `true`, the returned geojson will include all elements that meet the specified conditions in `FeatureCollection` format;
+   * otherwise, only the bare geometry of the first `relation` element will be returned.
+   * @default false
+   */
+  completeFeature?: boolean;
+  /**
+   * When it's set to `true`, the returned geojson will include all elements with tags (i.e., tagged)
+   * until `suppressWay` changes its behavior a bit; otherwise only the unreferenced ones get returned.
+   * @default false
+   */
+  renderTagged?: boolean;
+  /**
+   * When it's set to `true`, the returned `FeatureCollection` will exclude all referenced `way`s even though they are tagged;
+   * otherwise the features of those `way`s will be included in the resulted result as well.
+   * @default true
+   */
+  excludeWay?: boolean;
+}
+declare function osm2geojson(osm: string | {
+  [k: string]: any;
+}, opts?: IOptions): FeatureCollection<GeometryObject>;
+//#endregion
+export { osm2geojson as default };