osmfeatures 0.2.3 → 0.2.4

package/README.md

@@ -12,11 +12,11 @@ The translation layer is very simple:
 
 You filter with the same tags mappers already use (`amenity=cafe`, `building=yes`, and so on). Knowledge from OSM, Overpass, and tagging docs transfers immediately.
 
-To narrow down between "open ways" and "closed ways", use the `shape` parameter:
+To narrow down between "open ways" and "closed ways", use the `way_shape` parameter:
 
-- `shape=line` - open ways (roads, paths, rivers) or line-shaped relations (routes, boundaries)
-- `shape=polygon` - closed ways (buildings, parks) or multipolygon relations.
-- `shape=all` - both shapes (default when shape is omitted).
+- `way_shape=line` - open ways (roads, paths, rivers) or line-shaped relations (routes, boundaries)
+- `way_shape=polygon` - closed ways (buildings, parks) or multipolygon relations.
+- `way_shape=all` - both shapes (default when way_shape is omitted).
 
 For example, to get all buildings in an area:
 
@@ -102,7 +102,7 @@ Geometric filters such specific OSM element type, min length, or including centr
 | Param        | Type                   | Default | Description                                                                             |
 | ------------ | ---------------------- | ------- | --------------------------------------------------------------------------------------- |
 | `type`       | `string`               | all     | OSM element types, e.g. `node`, `way`, `relation`, or comma-separated (`way,relation`). |
-| `shape`      | `line | polygon | all` | `all`   | Geometry shape filter for ways and relations.                                           |
+| `wayShape`   | `line | polygon | all` | `all`   | Geometry class for ways and relations. `shape` is a deprecated alias.                   |
 | `centroid`   | `boolean`              | `false` | When `true`, include a centroid on non-point features.                                  |
 | `clipGeometry` | `boolean`            | `true`  | When `true`, clip returned geometry to the requested `bbox`. Set `false` for full geometry. |
 | `minLengthM` | `number`               |         | Minimum length in metres (lines).                                                       |
@@ -168,7 +168,7 @@ console.log(all.meta.page_count, all.meta.has_more, all.meta.units_charged);
 
 ### Params
 
-Same filter params as `query` (`bbox`, `tags`, `orTags`, `notTags`, `type`, `shape`, `zoom`, `location`, `radius`, `osmIds`, `minLengthM`, `maxLengthM`, `minAreaM2`, `maxAreaM2`, `centroid`, `clipGeometry`, `disableBudgetWarning`), plus:
+Same filter params as `query` (`bbox`, `tags`, `orTags`, `notTags`, `type`, `wayShape`, `zoom`, `location`, `radius`, `osmIds`, `minLengthM`, `maxLengthM`, `minAreaM2`, `maxAreaM2`, `centroid`, `clipGeometry`, `disableBudgetWarning`), plus:
 
 
 | Param          | Type            | Default                | Description                                                                                                                                               |

package/dist/index.d.ts

@@ -32,6 +32,8 @@ export type OSMFeaturesLayer = {
     orTags?: string[];
     notTags?: string[];
     type?: string;
+    wayShape?: 'line' | 'polygon' | 'all';
+    /** @deprecated Use `wayShape`. */
     shape?: 'line' | 'polygon' | 'all';
 };
 /** Flat query params (same idea as Python `query(**params)`). */
@@ -146,9 +148,9 @@ export declare class OSMFeatures {
     /** Single HTTP request with retry. Throws on non-OK (same role as Python `_raw_query`). */
     private _rawQuery;
     /** Single upstream page. Params map 1:1 to server query string (no tiling). */
-    query({ bbox, tags, orTags, notTags, type, shape, limit, cursor, zoom, location, radius, osmIds, minLengthM, maxLengthM, minAreaM2, maxAreaM2, disableBudgetWarning, centroid, clipGeometry, accept, }: OSMFeaturesParams, dependencies?: OSMFeaturesDependencies): Promise<OSMFeaturesResult>;
+    query({ bbox, tags, orTags, notTags, type, wayShape, shape, limit, cursor, zoom, location, radius, osmIds, minLengthM, maxLengthM, minAreaM2, maxAreaM2, disableBudgetWarning, centroid, clipGeometry, accept, }: OSMFeaturesParams, dependencies?: OSMFeaturesDependencies): Promise<OSMFeaturesResult>;
     /** Auto-paginate (and optionally tile) until complete. Each page uses `_rawQuery`. */
-    query_all({ bbox, tags, orTags, notTags, type, shape, zoom, location, radius, osmIds, minLengthM, maxLengthM, minAreaM2, maxAreaM2, disableBudgetWarning, centroid, clipGeometry, accept, limitPerPage, bboxTiles, maxPages, maxFeatures, }: Omit<OSMFeaturesParams, 'limit' | 'cursor'> & {
+    query_all({ bbox, tags, orTags, notTags, type, wayShape, shape, zoom, location, radius, osmIds, minLengthM, maxLengthM, minAreaM2, maxAreaM2, disableBudgetWarning, centroid, clipGeometry, accept, limitPerPage, bboxTiles, maxPages, maxFeatures, }: Omit<OSMFeaturesParams, 'limit' | 'cursor'> & {
         /** Upstream `limit` per HTTP request (page size). */
         limitPerPage?: number;
         bboxTiles?: number;

package/dist/index.js

@@ -189,8 +189,9 @@ function buildFeaturesQuery(params) {
     if (params.type) {
         query.set('type', params.type);
     }
-    if (params.shape) {
-        query.set('shape', params.shape);
+    const wayShape = params.wayShape ?? params.shape;
+    if (wayShape) {
+        query.set('way_shape', wayShape);
     }
     for (const tag of params.tags ?? []) {
         query.append('tags', tag);
@@ -518,13 +519,14 @@ export class OSMFeatures {
         };
     }
     /** Single upstream page. Params map 1:1 to server query string (no tiling). */
-    async query({ bbox, tags, orTags, notTags, type, shape, limit = DEFAULT_LIMIT, cursor, zoom, location, radius, osmIds, minLengthM, maxLengthM, minAreaM2, maxAreaM2, disableBudgetWarning, centroid, clipGeometry, accept, }, dependencies = {}) {
+    async query({ bbox, tags, orTags, notTags, type, wayShape, shape, limit = DEFAULT_LIMIT, cursor, zoom, location, radius, osmIds, minLengthM, maxLengthM, minAreaM2, maxAreaM2, disableBudgetWarning, centroid, clipGeometry, accept, }, dependencies = {}) {
         const payload = await this._rawQuery({
             bbox,
             tags,
             orTags,
             notTags,
             type,
+            wayShape,
             shape,
             limit,
             cursor,
@@ -544,7 +546,7 @@ export class OSMFeatures {
         return payload;
     }
     /** Auto-paginate (and optionally tile) until complete. Each page uses `_rawQuery`. */
-    async query_all({ bbox, tags, orTags, notTags, type, shape, zoom, location, radius, osmIds, minLengthM, maxLengthM, minAreaM2, maxAreaM2, disableBudgetWarning, centroid, clipGeometry, accept, limitPerPage = DEFAULT_LIMIT, bboxTiles = 2, maxPages = 15, maxFeatures = 55_000, }, dependencies = {}) {
+    async query_all({ bbox, tags, orTags, notTags, type, wayShape, shape, zoom, location, radius, osmIds, minLengthM, maxLengthM, minAreaM2, maxAreaM2, disableBudgetWarning, centroid, clipGeometry, accept, limitPerPage = DEFAULT_LIMIT, bboxTiles = 2, maxPages = 15, maxFeatures = 55_000, }, dependencies = {}) {
         if (!isGeojsonAccept(accept)) {
             throw appError(400, 'invalid_accept', 'query_all only supports GeoJSON; use query({ accept }) for binary encodings.');
         }
@@ -570,6 +572,7 @@ export class OSMFeatures {
             orTags,
             notTags,
             type,
+            wayShape,
             shape,
             limit: limitPerPage,
             zoom,
@@ -670,7 +673,7 @@ export class OSMFeatures {
             orTags: params.orTags,
             notTags: params.notTags,
             type: params.type,
-            shape: params.shape,
+            wayShape: params.wayShape ?? params.shape,
             limit: params.limit ?? DEFAULT_LIMIT,
             zoom: params.zoom,
             location: params.location,

package/dist/preset/catalog.d.ts

@@ -7,6 +7,8 @@ export type OSMFeaturesLayerPreset = {
     orTags?: string[];
     notTags?: string[];
     type?: string;
+    wayShape?: 'line' | 'polygon';
+    /** @deprecated Use `wayShape`. */
     shape?: 'line' | 'polygon';
 };
 export declare const OSM_FEATURES_LAYER_PRESETS: Record<OSMFeaturesPresetId, OSMFeaturesLayerPreset>;

package/dist/preset/catalog.js

@@ -4,14 +4,14 @@ export const OSM_FEATURES_LAYER_PRESETS = {
         label: 'Buildings',
         tags: ['building'],
         type: 'way,relation',
-        shape: 'polygon',
+        wayShape: 'polygon',
     },
     roads_paths: {
         id: 'roads_paths',
         label: 'Roads & paths',
         tags: ['highway'],
         type: 'way,relation',
-        shape: 'line',
+        wayShape: 'line',
     },
     parks_green_space: {
         id: 'parks_green_space',
@@ -37,7 +37,7 @@ export const OSM_FEATURES_LAYER_PRESETS = {
             'amenity=pub',
             'amenity=biergarten',
         ],
-        shape: 'polygon',
+        wayShape: 'polygon',
     },
     shops_commerce: {
         id: 'shops_commerce',
@@ -112,7 +112,7 @@ export const OSM_FEATURES_LAYER_PRESETS = {
             'waterway=ditch',
         ],
         type: 'way,relation',
-        shape: 'line',
+        wayShape: 'line',
     },
 };
 export const OSM_FEATURES_LAYER_PRESET_ORDER = [

package/dist/preset/resolve.d.ts

@@ -12,6 +12,8 @@ export type ResolvedCustomLayer = {
     orTags?: string[];
     notTags?: string[];
     type?: string;
+    wayShape?: 'line' | 'polygon' | 'all';
+    /** @deprecated Use `wayShape`. */
     shape?: 'line' | 'polygon' | 'all';
 };
 export type ResolvedDemoLayer = ResolvedPresetLayer | ResolvedCustomLayer;
@@ -24,7 +26,7 @@ export declare function getPreset(id: string): OSMFeaturesLayerPreset | undefine
 export declare function resolvePresetFromQuery(query: PresetQuery): ResolvedPresetLayer;
 /**
  * Custom layer: `tags` / `or_tags` / `not_tags` + required `bbox`.
- * Optional `type` / `shape`. Needs at least one positive filter (`tags` or `or_tags`).
+ * Optional `type` / `way_shape`. Needs at least one positive filter (`tags` or `or_tags`).
  */
 export declare function resolveCustomLayerFromQuery(query: PresetQuery): ResolvedCustomLayer;
 /**

package/dist/preset/resolve.js

@@ -91,7 +91,7 @@ export function resolvePresetFromQuery(query) {
 }
 /**
  * Custom layer: `tags` / `or_tags` / `not_tags` + required `bbox`.
- * Optional `type` / `shape`. Needs at least one positive filter (`tags` or `or_tags`).
+ * Optional `type` / `way_shape`. Needs at least one positive filter (`tags` or `or_tags`).
  */
 export function resolveCustomLayerFromQuery(query) {
     const tags = stringList(query, 'tags');
@@ -114,9 +114,9 @@ export function resolveCustomLayerFromQuery(query) {
     if (type) {
         layer.type = type;
     }
-    const shape = optionalString(query, 'shape');
-    if (shape === 'line' || shape === 'polygon' || shape === 'all') {
-        layer.shape = shape;
+    const wayShape = optionalString(query, 'way_shape') ?? optionalString(query, 'shape');
+    if (wayShape === 'line' || wayShape === 'polygon' || wayShape === 'all') {
+        layer.wayShape = wayShape;
     }
     return layer;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "osmfeatures",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Get OpenStreetMap features such as buildings, roads, or points of interest from dedicated servers with a single API call in GeoJSON, FlatGeobuf, Geoparquet, and CSV formats.",
   "type": "module",
   "main": "./dist/index.js",
@@ -18,7 +18,7 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "tsx src/index.test.ts && tsx src/geojson-feature.test.ts && tsx src/preset/preset.test.ts",
+    "test": "tsx src/index.test.ts && tsx src/geojson-feature.test.ts && tsx src/preset/preset.test.ts && tsx src/tutorial.test.ts",
     "prepare": "npm run build",
     "prepublishOnly": "npm run build"
   },
@@ -36,7 +36,7 @@
   "homepage": "https://maplark.com",
   "repository": {
     "type": "git",
-    "url": "https://github.com/MapLark/osmfeatures-typescript.git"
+    "url": "https://github.com/MapLark/osmfeatures-ts.git"
   },
   "license": "MIT",
   "engines": {