osm2geojson-lite 1.2.0 → 2.1.0

package/README.md

@@ -27,11 +27,20 @@ Usage:
 ```
 
 ### In the Browser
+
+Modern browsers load the ESM build directly via `<script type="module">`. Import it from a CDN (e.g. [esm.sh](https://esm.sh) or [jsDelivr](https://www.jsdelivr.com)):
+
 ```html
-    <script src='your/path/to/osm2geojson-lite.js'/>
+    <script type="module">
+        import osm2geojson from 'https://esm.sh/osm2geojson-lite';
+
+        const geojson = osm2geojson(osm, opts);
+    </script>
 ```
-```js
-    let geojson = osm2geojson(osm, opts);
+
+### In the command line
+```sh
+    npx osm2geojson-lite --help
 ```
 
 API
@@ -46,29 +55,42 @@ Converts OSM data (XML/JSON) to GeoJSON.
     - `completeFeature`:  the default value is `false`. 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.
     - `renderTagged`: the default value is `false`. When it's set to `true`, the returned geojson will include all elements with tags (i.e., tagged) until `excludeWay` changes its behavior a bit; otherwise only the unreferenced ones get returned.
     - `excludeWay`: the default value is `true`. 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.
+    - `elementId`: optional, an OSM element id in the form `type/id` (e.g. `way/123`). When set, only that single `Feature` is returned; `undefined` is returned when the element does not exist.
+    - `tainted`: the default value is `false`. When set to `true`, features whose referenced nodes/ways/relations are missing (e.g. partial Overpass responses) receive an `@tainted: true` property.
+    - `polygonTags`: optional, alternative polygon tag rules for ways. The shape matches the bundled `polytags.json`, e.g. `{ "building": { "ignore": ["no"] } }`; the legacy `whitelist`/`blacklist` spellings are still accepted.
+
+Beyond plain OSM data the converter understands the shapes produced by Overpass
+`out geom`, `out center`, `out bb`, `convert`, `make` and `local` (both JSON and
+XML), including derived `Point`/`LineString`/`Polygon`/`GeometryCollection`
+output, member geometries, `center` fallbacks and `bounds`-only rectangles.
 
 
 Performance
 ---
 1. Workloads include the boundary XML and JSON of 4 administrive areas (zhucheng, hebei, tokyodo, usa)
-2. Call each conversion for 100 rounds to mitigate the impacts of GC and other factors
-3. For each script, run as many as times seperately and then calculate the average cost time (ACT for short)
-4. The # listed in the table below are coarse lowest values of dividing the ACT of `osmtogeojson` by the one of this library
+2. The benchmark is written with [Vitest's `bench`](https://vitest.dev/guide/features.html#benchmarking), which warms up and then samples each conversion many times, comparing this library against [`osm2geojson-ultra`](https://www.npmjs.com/package/osm2geojson-ultra) (which uses the `txml` parser) and `osmtogeojson` (+ `xmldom` for XML).
 ```
-$ cd test
 $ npm run bench
 ```
+3. The # listed in the tables below are coarse lowest speed-up factors (this library vs. the competitor) observed on the sample data.
+
 1. XML
-   
-| zhucheng  | hebei    | tokyodo | usa  |
-|-----------|----------|---------|------|
-| >2.5x     | >4.0x    | >3.0x   | >3.0x|
+
+|                 | zhucheng | hebei | tokyodo | usa   |
+|-----------------|----------|-------|---------|-------|
+| vs osmtogeojson | >10.9x   | >20.8x| >14.9x  | >14.8x|
+| vs ultra        | >2.5x    | >3.0x | >3.7x   | >4.2x |
 
 2. Overpass JSON
-   
-| zhucheng  | hebei    | tokyodo | usa  |
-|-----------|----------|---------|------|
-| >2.5x     | >11.0x   | >7.0x   | >5.0x|
+
+|                 | zhucheng | hebei  | tokyodo | usa   |
+|-----------------|----------|--------|---------|-------|
+| vs osmtogeojson | >13.7x   | >56.3x | >21.8x  | >27.5x|
+| vs ultra        | >4.4x    | >7.4x  | >14.2x  | >20.3x|
+
+> **Note on column values:** the numbers are `hz` ratios reported by Vitest on
+> the reference machine (Node 26, Apple silicon). Run `npm run bench` on your
+> own hardware to compare.
 
 
 Correctness