@osm-editor-kit/osm-data 0.1.0-alpha.1 → 1.0.0

package/README.md

@@ -1,23 +1,62 @@
 # `@osm-editor-kit/osm-data`
 
+Download OSM JSON from Overpass or the OSM API, parse it into an indexed in-memory store, and merge several downloads into one. For apps that show or check OSM data.
+
 > [!NOTE]
-> This package is an **alpha** release and still under active development. APIs may change; install with the npm `alpha` dist-tag.
+> Claude Opus 5.5 wrote and reviewed the code of this package. [@tordans](https://github.com/tordans) specified what it should do and tested and verified its user-facing behavior.
+
+## Install
+
+```bash
+npm install @osm-editor-kit/osm-data
+```
 
 ## What it does
 
-- Fetch OSM JSON from Overpass or the OSM API
-- Parse responses into in-memory indexes (ways, relations, tagged nodes, coordinates)
-- Look up which ways belong to a relation
-- Merge several downloads into one graph, preferring newer element versions
-- Shared TypeScript types for parsed OSM session data
+- Fetches OSM JSON from a URL (Overpass or OSM API).
+- Parses `elements` into indexes by id: ways, relations, tagged nodes, and node coordinates (`[lat, lon]`).
+- Marks which ways are members of a relation (`waysInRelation`).
+- Merges two parsed stores. Ways and relations keep the higher `version`; nodes and coordinates from the newer store replace existing ones.
+- Exports TypeScript types for OSM elements and the parsed store.
+
+It only fetches, parses, and indexes. It does not edit OSM data or write tags.
 
 ## Usage
 
 ```ts
-import { downloadOsmData, parseOsmResp, mergeParsedOsm } from '@osm-editor-kit/osm-data'
+import {
+  downloadOsmData,
+  emptyParsedOsmData,
+  mergeParsedOsm,
+  parseOsmResp,
+  type ParsedOsmData,
+  type RawOsmData,
+} from '@osm-editor-kit/osm-data'
+
+// Download from a URL that returns OSM JSON (throws when the request fails, for example HTTP 429)
+const downloaded: ParsedOsmData = await downloadOsmData(
+  'https://overpass-api.de/api/interpreter?data=[out:json];way(52.47,13.44,52.48,13.45)[highway];out;',
+)
 
-const parsed = await downloadOsmData(overpassUrl)
-const combined = mergeParsedOsm(parsed, parseOsmResp(rawOsmResp))
+// Or parse a response you already have
+const raw: RawOsmData = { elements: [] }
+const parsed = parseOsmResp(raw)
+
+// Merge into one store; start from an empty store if you have nothing yet
+const store = mergeParsedOsm(emptyParsedOsmData(), downloaded)
+const combined = mergeParsedOsm(store, parsed)
+
+combined.ways[42]?.tags.highway
+combined.nodeCoords[10] // [lat, lon]
+combined.waysInRelation[42] // true when a parsed relation lists way 42
 ```
 
-Fetch/parse/index only — not an OSM editor or tag writer.
+Notes:
+
+- `parseOsmResp` throws on element types other than `node`, `way`, and `relation`.
+- `waysInRelation` only marks ways that appear in the response before the relation. Overpass lists ways before relations, so this works with its default output.
+- Only nodes with tags are stored in `nodes`. All nodes are stored in `nodeCoords`.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export { downloadOsmData, emptyParsedOsmData, mergeParsedOsm, parseOsmResp } from './data-client';
 export type { LatLngLiteral, MapBounds } from './types/geo';
-export type { OsmElement, OsmNode, OsmObject, OsmRelation, OsmTags, OsmWay, RawOsmData, } from './types/osm-data';
+export type { OsmElement, OsmNode, OsmObject, OsmRelation, OsmTags, OsmType, OsmWay, RawOsmData, RelationMember, } from './types/osm-data';
 export type { ParsedOsmData, WaysInRelation } from './types/osm-data-storage';

package/dist/types/osm-data.d.ts

@@ -1,5 +1,5 @@
 export type OsmTags = Record<string, string>;
-type OsmType = 'node' | 'way' | 'relation';
+export type OsmType = 'node' | 'way' | 'relation';
 export interface OsmObject {
     id: number;
     type: OsmType;
@@ -11,7 +11,7 @@ export interface OsmObject {
     changeset: number;
     tags: OsmTags;
 }
-interface RelationMember {
+export interface RelationMember {
     type: OsmType;
     ref: number;
     role: string;
@@ -33,4 +33,3 @@ export type OsmElement = OsmNode | OsmWay | OsmRelation;
 export interface RawOsmData {
     elements: OsmElement[];
 }
-export {};

package/package.json

@@ -1,20 +1,20 @@
 {
   "name": "@osm-editor-kit/osm-data",
-  "version": "0.1.0-alpha.1",
+  "version": "1.0.0",
   "description": "Download, parse, and merge OSM API/Overpass responses into an indexed in-memory store.",
+  "homepage": "https://github.com/osm-editor-kit/street-space-editor/tree/main/packages/osm-data",
   "license": "MIT",
   "author": "Tobias Jordans",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/osmberlin/street-space-editor.git",
+    "url": "git+https://github.com/osm-editor-kit/street-space-editor.git",
     "directory": "packages/osm-data"
   },
-  "homepage": "https://github.com/osmberlin/street-space-editor/tree/main/packages/osm-data",
-  "type": "module",
-  "sideEffects": false,
   "files": [
     "dist"
   ],
+  "type": "module",
+  "sideEffects": false,
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -23,8 +23,7 @@
     "./package.json": "./package.json"
   },
   "publishConfig": {
-    "access": "public",
-    "tag": "alpha"
+    "access": "public"
   },
   "scripts": {
     "build": "tsup && rm -f .tsbuildinfo && tsc -p tsconfig.build.json",