osmfeatures 0.1.0

package/dist/preset/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Opt-in OSM Features layer presets + zoom detail policies.
+ *
+ * Use nothing from here if you want raw tag queries only.
+ *
+ * Catalog (full detail; no zoom floors; no bbox)
+ *   OSM_FEATURES_LAYER_PRESETS / OSM_FEATURES_LAYER_PRESET_ORDER
+ *   getPreset(id)
+ *
+ * Resolve
+ *   resolvePresetFromQuery({ preset, bbox, zoom? })
+ *   resolveCustomLayerFromQuery({ tags?/or_tags?/not_tags?, bbox })
+ *   resolveLayerFromQuery(...) — preset if set, else custom tags
+ *   bbox required — zoom optional (omit for full catalog detail)
+ *
+ * Policies (callable alone; omit zoom = no-op / full detail)
+ *   applyRoadsPathsZoomPolicy(preset, zoom?)
+ *   applyWaterwaysZoomPolicy(preset, zoom?)
+ *   applyPublicTransportZoomPolicy(preset, zoom?)
+ *   resolveBuildingsMinAreaM2(presetId, bbox, zoom?)  → optional min_area_m2
+ *   ROADS_PATHS_FULL_DETAIL_ZOOM — z at/above this keeps all highway tags
+ *   WATERWAYS_FULL_DETAIL_ZOOM — z at/above this keeps all waterway classes
+ *   PUBLIC_TRANSPORT_FULL_DETAIL_ZOOM — z at/above this keeps all transport tags
+ */
+export { OSM_FEATURES_LAYER_PRESETS, OSM_FEATURES_LAYER_PRESET_ORDER, type OSMFeaturesLayerPreset, type OSMFeaturesPresetId, } from './catalog.js';
+export { applyRoadsPathsZoomPolicy, ROADS_PATHS_FULL_DETAIL_ZOOM, } from './roads-paths-zoom.js';
+export { applyWaterwaysZoomPolicy, WATERWAYS_FULL_DETAIL_ZOOM, } from './waterways-zoom.js';
+export { applyPublicTransportZoomPolicy, PUBLIC_TRANSPORT_FULL_DETAIL_ZOOM, } from './public-transport-zoom.js';
+export { resolveBuildingsMinAreaM2 } from './buildings-min-area.js';
+export { getPreset, resolvePresetFromQuery, resolveCustomLayerFromQuery, resolveLayerFromQuery, type PresetQuery, type ResolvedCustomLayer, type ResolvedDemoLayer, type ResolvedPresetLayer, } from './resolve.js';

package/dist/preset/index.js

@@ -0,0 +1,30 @@
+/**
+ * Opt-in OSM Features layer presets + zoom detail policies.
+ *
+ * Use nothing from here if you want raw tag queries only.
+ *
+ * Catalog (full detail; no zoom floors; no bbox)
+ *   OSM_FEATURES_LAYER_PRESETS / OSM_FEATURES_LAYER_PRESET_ORDER
+ *   getPreset(id)
+ *
+ * Resolve
+ *   resolvePresetFromQuery({ preset, bbox, zoom? })
+ *   resolveCustomLayerFromQuery({ tags?/or_tags?/not_tags?, bbox })
+ *   resolveLayerFromQuery(...) — preset if set, else custom tags
+ *   bbox required — zoom optional (omit for full catalog detail)
+ *
+ * Policies (callable alone; omit zoom = no-op / full detail)
+ *   applyRoadsPathsZoomPolicy(preset, zoom?)
+ *   applyWaterwaysZoomPolicy(preset, zoom?)
+ *   applyPublicTransportZoomPolicy(preset, zoom?)
+ *   resolveBuildingsMinAreaM2(presetId, bbox, zoom?)  → optional min_area_m2
+ *   ROADS_PATHS_FULL_DETAIL_ZOOM — z at/above this keeps all highway tags
+ *   WATERWAYS_FULL_DETAIL_ZOOM — z at/above this keeps all waterway classes
+ *   PUBLIC_TRANSPORT_FULL_DETAIL_ZOOM — z at/above this keeps all transport tags
+ */
+export { OSM_FEATURES_LAYER_PRESETS, OSM_FEATURES_LAYER_PRESET_ORDER, } from './catalog.js';
+export { applyRoadsPathsZoomPolicy, ROADS_PATHS_FULL_DETAIL_ZOOM, } from './roads-paths-zoom.js';
+export { applyWaterwaysZoomPolicy, WATERWAYS_FULL_DETAIL_ZOOM, } from './waterways-zoom.js';
+export { applyPublicTransportZoomPolicy, PUBLIC_TRANSPORT_FULL_DETAIL_ZOOM, } from './public-transport-zoom.js';
+export { resolveBuildingsMinAreaM2 } from './buildings-min-area.js';
+export { getPreset, resolvePresetFromQuery, resolveCustomLayerFromQuery, resolveLayerFromQuery, } from './resolve.js';

package/dist/preset/public-transport-zoom.d.ts

@@ -0,0 +1,4 @@
+import type { OSMFeaturesLayerPreset } from './catalog.js';
+export declare const PUBLIC_TRANSPORT_FULL_DETAIL_ZOOM = 13.8;
+/** Opt-in: drop stop/platform clutter on public_transport as map zooms out. Omit zoom for full detail. */
+export declare function applyPublicTransportZoomPolicy<T extends OSMFeaturesLayerPreset>(preset: T, zoom?: number): T;

package/dist/preset/public-transport-zoom.js

@@ -0,0 +1,39 @@
+// public_transport detail floors (omit zoom = full detail, same as z >= FULL):
+//   z >= 14     — full catalog (stops, platforms, bus routes, …)
+//   12 <= z < 14 — rail network + urban rail + major stops (no bus-stop clutter)
+//   z < 12      — mainline rail + stations only
+// Roughly matches OpenMapTiles railway class floors (rail early; subway/tram/stops later).
+export const PUBLIC_TRANSPORT_FULL_DETAIL_ZOOM = 13.8;
+const PUBLIC_TRANSPORT_MAJOR_ZOOM = 11.8;
+const PUBLIC_TRANSPORT_MAJOR_OR_TAGS = [
+    'railway=rail',
+    'railway=station',
+    'route=train',
+];
+const PUBLIC_TRANSPORT_MID_OR_TAGS = [
+    ...PUBLIC_TRANSPORT_MAJOR_OR_TAGS,
+    'railway=narrow_gauge',
+    'railway=light_rail',
+    'railway=subway',
+    'railway=tram',
+    'railway=halt',
+    'amenity=bus_station',
+    'route=subway',
+    'route=light_rail',
+    'route=tram',
+];
+/** Opt-in: drop stop/platform clutter on public_transport as map zooms out. Omit zoom for full detail. */
+export function applyPublicTransportZoomPolicy(preset, zoom) {
+    if (preset.id !== 'public_transport' || zoom == null || zoom >= PUBLIC_TRANSPORT_FULL_DETAIL_ZOOM) {
+        return preset;
+    }
+    const orTags = zoom < PUBLIC_TRANSPORT_MAJOR_ZOOM
+        ? PUBLIC_TRANSPORT_MAJOR_OR_TAGS
+        : PUBLIC_TRANSPORT_MID_OR_TAGS;
+    return {
+        ...preset,
+        tags: undefined,
+        orTags: [...orTags],
+        notTags: preset.notTags,
+    };
+}

package/dist/preset/resolve.d.ts

@@ -0,0 +1,35 @@
+import { type OSMFeaturesLayerPreset } from './catalog.js';
+type QueryValue = unknown;
+export type PresetQuery = Record<string, QueryValue>;
+/** Catalog preset + required bbox for an upstream query. */
+export type ResolvedPresetLayer = OSMFeaturesLayerPreset & {
+    bbox: string;
+};
+/** Tag filters + bbox for a custom (non-preset) upstream query. */
+export type ResolvedCustomLayer = {
+    bbox: string;
+    tags?: string[];
+    orTags?: string[];
+    notTags?: string[];
+    type?: string;
+    shape?: 'line' | 'polygon' | 'all';
+};
+export type ResolvedDemoLayer = ResolvedPresetLayer | ResolvedCustomLayer;
+/** Catalog lookup only. No zoom policies. */
+export declare function getPreset(id: string): OSMFeaturesLayerPreset | undefined;
+/**
+ * Opt-in helper: resolve `preset` + required `bbox` (+ optional `zoom`) from a query map.
+ * Applies known zoom tag policies (roads_paths, waterways, public_transport). Does not set min_area_m2.
+ */
+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`).
+ */
+export declare function resolveCustomLayerFromQuery(query: PresetQuery): ResolvedCustomLayer;
+/**
+ * Demo / relay helper: `preset`+bbox, or custom `tags`/`or_tags`/`not_tags`+bbox.
+ * Preset wins when both are present.
+ */
+export declare function resolveLayerFromQuery(query: PresetQuery): ResolvedDemoLayer;
+export {};

package/dist/preset/resolve.js

@@ -0,0 +1,133 @@
+import createHttpError from 'http-errors';
+import { OSM_FEATURES_LAYER_PRESETS, } from './catalog.js';
+import { applyPublicTransportZoomPolicy } from './public-transport-zoom.js';
+import { applyRoadsPathsZoomPolicy } from './roads-paths-zoom.js';
+import { applyWaterwaysZoomPolicy } from './waterways-zoom.js';
+function appError(status, code, detail) {
+    const err = createHttpError(status, detail);
+    err.code = code;
+    return err;
+}
+function optionalString(query, key) {
+    const raw = query[key];
+    if (raw == null || raw === '') {
+        return undefined;
+    }
+    if (Array.isArray(raw)) {
+        const first = raw[0];
+        if (first == null || first === '') {
+            return undefined;
+        }
+        return String(first);
+    }
+    return String(raw);
+}
+function optionalNumber(query, key) {
+    const raw = query[key];
+    if (raw == null || raw === '') {
+        return undefined;
+    }
+    if (typeof raw === 'number') {
+        return Number.isFinite(raw) ? raw : undefined;
+    }
+    const text = optionalString(query, key);
+    if (text == null) {
+        return undefined;
+    }
+    const parsed = Number.parseFloat(text);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+/** Repeatable query params (`tags=a&tags=b`) or one value. */
+function stringList(query, key) {
+    const raw = query[key];
+    if (raw == null || raw === '') {
+        return [];
+    }
+    const values = Array.isArray(raw) ? raw : [raw];
+    const out = [];
+    for (const value of values) {
+        if (value == null || value === '') {
+            continue;
+        }
+        const trimmed = String(value).trim();
+        if (trimmed) {
+            out.push(trimmed);
+        }
+    }
+    return out;
+}
+function requireBbox(query) {
+    const bbox = optionalString(query, 'bbox');
+    if (bbox == null) {
+        throw appError(400, 'invalid_bbox', 'bbox is required.');
+    }
+    return bbox;
+}
+/** Catalog lookup only. No zoom policies. */
+export function getPreset(id) {
+    return OSM_FEATURES_LAYER_PRESETS[id];
+}
+/**
+ * Opt-in helper: resolve `preset` + required `bbox` (+ optional `zoom`) from a query map.
+ * Applies known zoom tag policies (roads_paths, waterways, public_transport). Does not set min_area_m2.
+ */
+export function resolvePresetFromQuery(query) {
+    const rawPreset = query['preset'];
+    if (typeof rawPreset !== 'string' || rawPreset.trim() === '') {
+        throw appError(400, 'invalid_preset', 'preset is required.');
+    }
+    const presetId = rawPreset.trim();
+    const preset = getPreset(presetId);
+    if (!preset) {
+        throw appError(400, 'invalid_preset', `Unknown preset: ${presetId}`);
+    }
+    const withBbox = { ...preset, bbox: requireBbox(query) };
+    const zoom = optionalNumber(query, 'zoom');
+    // Zoom optional: omit / invalid → catalog tags as-is (full detail).
+    if (zoom == null) {
+        return withBbox;
+    }
+    return applyPublicTransportZoomPolicy(applyWaterwaysZoomPolicy(applyRoadsPathsZoomPolicy(withBbox, zoom), zoom), zoom);
+}
+/**
+ * Custom layer: `tags` / `or_tags` / `not_tags` + required `bbox`.
+ * Optional `type` / `shape`. Needs at least one positive filter (`tags` or `or_tags`).
+ */
+export function resolveCustomLayerFromQuery(query) {
+    const tags = stringList(query, 'tags');
+    const orTags = stringList(query, 'or_tags');
+    const notTags = stringList(query, 'not_tags');
+    if (tags.length === 0 && orTags.length === 0) {
+        throw appError(400, 'invalid_tags', 'tags or or_tags is required for a custom layer.');
+    }
+    const layer = { bbox: requireBbox(query) };
+    if (tags.length > 0) {
+        layer.tags = tags;
+    }
+    if (orTags.length > 0) {
+        layer.orTags = orTags;
+    }
+    if (notTags.length > 0) {
+        layer.notTags = notTags;
+    }
+    const type = optionalString(query, 'type');
+    if (type) {
+        layer.type = type;
+    }
+    const shape = optionalString(query, 'shape');
+    if (shape === 'line' || shape === 'polygon' || shape === 'all') {
+        layer.shape = shape;
+    }
+    return layer;
+}
+/**
+ * Demo / relay helper: `preset`+bbox, or custom `tags`/`or_tags`/`not_tags`+bbox.
+ * Preset wins when both are present.
+ */
+export function resolveLayerFromQuery(query) {
+    const rawPreset = query['preset'];
+    if (typeof rawPreset === 'string' && rawPreset.trim() !== '') {
+        return resolvePresetFromQuery(query);
+    }
+    return resolveCustomLayerFromQuery(query);
+}

package/dist/preset/roads-paths-zoom.d.ts

@@ -0,0 +1,4 @@
+import type { OSMFeaturesLayerPreset } from './catalog.js';
+export declare const ROADS_PATHS_FULL_DETAIL_ZOOM = 13.5;
+/** Opt-in: drop path / minor-road clutter on roads_paths as map zooms out. Omit zoom for full detail. */
+export declare function applyRoadsPathsZoomPolicy<T extends OSMFeaturesLayerPreset>(preset: T, zoom?: number): T;

package/dist/preset/roads-paths-zoom.js

@@ -0,0 +1,37 @@
+// roads_paths detail floors (omit zoom = full detail, same as z >= FULL):
+//   z >= 13     — full highway set
+//   11 <= z < 13 — arteries + neighbourhood roads (whitelist; no service/track/paths)
+//   z < 11      — major roads only (whitelist)
+export const ROADS_PATHS_FULL_DETAIL_ZOOM = 13.5;
+const ROADS_PATHS_MAJOR_ZOOM = 12.4;
+const ROADS_PATHS_MAJOR_OR_TAGS = [
+    'highway=motorway',
+    'highway=motorway_link',
+    'highway=trunk',
+    'highway=trunk_link',
+    'highway=primary',
+    'highway=primary_link',
+];
+const ROADS_PATHS_MID_OR_TAGS = [
+    ...ROADS_PATHS_MAJOR_OR_TAGS,
+    'highway=secondary',
+    'highway=secondary_link',
+    'highway=tertiary',
+    'highway=tertiary_link',
+    'highway=unclassified',
+    'highway=residential',
+    'highway=living_street',
+];
+/** Opt-in: drop path / minor-road clutter on roads_paths as map zooms out. Omit zoom for full detail. */
+export function applyRoadsPathsZoomPolicy(preset, zoom) {
+    if (preset.id !== 'roads_paths' || zoom == null || zoom >= ROADS_PATHS_FULL_DETAIL_ZOOM) {
+        return preset;
+    }
+    const orTags = zoom < ROADS_PATHS_MAJOR_ZOOM ? ROADS_PATHS_MAJOR_OR_TAGS : ROADS_PATHS_MID_OR_TAGS;
+    return {
+        ...preset,
+        tags: undefined,
+        orTags: [...orTags],
+        notTags: preset.notTags,
+    };
+}

package/dist/preset/waterways-zoom.d.ts

@@ -0,0 +1,4 @@
+import type { OSMFeaturesLayerPreset } from './catalog.js';
+export declare const WATERWAYS_FULL_DETAIL_ZOOM = 13;
+/** Opt-in: drop minor waterways on waterways as map zooms out. Omit zoom for full detail. */
+export declare function applyWaterwaysZoomPolicy<T extends OSMFeaturesLayerPreset>(preset: T, zoom?: number): T;

package/dist/preset/waterways-zoom.js

@@ -0,0 +1,22 @@
+// waterways detail floors (omit zoom = full detail, same as z >= FULL):
+//   z >= 13 — river + canal + stream + drain + ditch
+//   z == 12 — river + canal
+//   z < 12  — river only
+// Matches OpenMapTiles waterway class generalization (OSM data; no Natural Earth).
+export const WATERWAYS_FULL_DETAIL_ZOOM = 13;
+const WATERWAYS_CANAL_ZOOM = 12;
+const WATERWAYS_RIVER_OR_TAGS = ['waterway=river'];
+const WATERWAYS_RIVER_CANAL_OR_TAGS = [...WATERWAYS_RIVER_OR_TAGS, 'waterway=canal'];
+/** Opt-in: drop minor waterways on waterways as map zooms out. Omit zoom for full detail. */
+export function applyWaterwaysZoomPolicy(preset, zoom) {
+    if (preset.id !== 'waterways' || zoom == null || zoom >= WATERWAYS_FULL_DETAIL_ZOOM) {
+        return preset;
+    }
+    const orTags = zoom < WATERWAYS_CANAL_ZOOM ? WATERWAYS_RIVER_OR_TAGS : WATERWAYS_RIVER_CANAL_OR_TAGS;
+    return {
+        ...preset,
+        tags: undefined,
+        orTags: [...orTags],
+        notTags: preset.notTags,
+    };
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "osmfeatures",
+  "version": "0.1.0",
+  "description": "Official client for the MapLark OSM Features API (GeoJSON, FlatGeobuf, GeoParquet, CSV)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "tsx src/index.test.ts && tsx src/geojson-feature.test.ts && tsx src/preset/preset.test.ts",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "openstreetmap",
+    "osm",
+    "geojson",
+    "flatgeobuf",
+    "geoparquet",
+    "overpass",
+    "maplark",
+    "geospatial",
+    "maps"
+  ],
+  "homepage": "https://maplark.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MapLark/osmfeatures-typescript.git"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "http-errors": "^2.0.0"
+  },
+  "devDependencies": {
+    "@types/http-errors": "^2.0.5",
+    "@types/node": "^22.10.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  }
+}