@osm-editor-kit/osm-coverage 0.1.0-alpha.0 → 0.1.0-alpha.3

package/README.md

@@ -1,12 +1,17 @@
 # `@osm-editor-kit/osm-coverage`
 
-**Status:** First npm **alpha** (`0.1.0-alpha.0`). Publish with `bun run packages:release -- --publish-only` after `npm login`.
+> [!NOTE]
+> This package is an **alpha** release and still under active development. APIs may change; install with the npm `alpha` dist-tag.
 
 ## What it does
 
-TanStack Query–backed OSM viewport coverage for map editors: incremental downloads, merged `ParsedOsmData` graphs, coverage polygons, and fetch-history GeoJSON. Includes zoom-aware missing-area detection (`computeMissingFetchRequests`, `unionIntoCoverage`), Overpass URL helpers (`boundsToOverpassBbox`, `buildOverpassInterpreterUrl`, `overpassDeUrl`, `overpassVkUrl`), and an `OsmDataSource` enum for download backends.
-
-The `@osm-editor-kit/osm-coverage/dev-osm-map-fixture` subpath is **editor-dev only** — local OSM Map API fixture handler, bbox filtering, and fixture index loader.
+- Download OSM data for the current map viewport (and only the parts you have not covered yet)
+- Keep a session graph of ways/nodes/relations as the map moves and pans
+- Track covered areas as polygons so refetches skip what you already have
+- Record fetch history as GeoJSON for debugging and UI
+- Build Overpass query URLs for common interpreters
+- Optional durable session storage (`storage` adapter) for graph + coverage across reloads
+- Optional editor-dev fixture loader via `@osm-editor-kit/osm-coverage/dev-osm-map-fixture` (not for production apps; not on the main export)
 
 ## Usage
 
@@ -17,13 +22,14 @@ import { createOsmCoverageApi, OsmDataSource } from '@osm-editor-kit/osm-coverag
 const api = createOsmCoverageApi<{ source: OsmDataSource }>({
   getSessionKey: ({ source }) => ['osm', source] as const,
   minZoom: 14,
-  getDownloadUrl: (bounds, { source }) =>
-  /* build Overpass or Map API URL */ '',
+  getDownloadUrl: (bounds, { source }) => /* build Overpass or Map API URL */ '',
+  // optional: storage: { load, save, clear }
 })
 
 const queryClient = new QueryClient()
 const params = { source: OsmDataSource.OverpassVk }
 
+await api.restoreSession(queryClient, params)
 await api.ensureCoverage(queryClient, {
   bounds: { south: 52.47, west: 13.44, north: 52.48, east: 13.45 },
   zoom: 18,
@@ -32,5 +38,5 @@ await api.ensureCoverage(queryClient, {
 })
 
 const data = queryClient.getQueryData(api.sessionKey(params))
-// { graph, coverage, fetchHistory }
+// { graph, coverage, fetchHistory, savedAt }
 ```

package/dist/coverage-geometry.d.ts

@@ -31,6 +31,11 @@ export declare function isValidBounds(bounds: MapBounds): boolean;
 export declare function boundsArea(bounds: MapBounds): number;
 export declare function bufferBoundsInViewport(request: MapBounds, viewport: MapBounds, zoom: number, mapSizePx: MapSizePx): MapBounds;
 export declare function clampBoundsToViewport(request: MapBounds, viewport: MapBounds): MapBounds;
+/** Lon/lat length of the zoom-aware seam overlap (same magnitude as fetch buffer). */
+export declare function overlapDeltaAtZoom(viewport: MapBounds, zoom: number, mapSizePx: MapSizePx): {
+    lon: number;
+    lat: number;
+};
 export declare function createViewportFetchRequest(viewport: MapBounds, zoom: number, mapSizePx: MapSizePx, kind: CoverageFetchKind): CoverageFetchRequest | null;
 export declare function computeMissingFetchRequests(viewport: MapBounds, coverage: Feature<Polygon | MultiPolygon> | null, zoom: number, mapSizePx: MapSizePx): CoverageFetchRequest[];
 export declare function unionIntoCoverage(coverage: Feature<Polygon | MultiPolygon> | null, requestBounds: MapBounds): Feature<Polygon | MultiPolygon>;

package/dist/create-osm-coverage-api.d.ts

@@ -2,11 +2,16 @@ import { type MapBounds, type ParsedOsmData } from '@osm-editor-kit/osm-data';
 import { type QueryClient } from '@tanstack/react-query';
 import type { Feature, FeatureCollection, MultiPolygon, Polygon } from 'geojson';
 import { type CoverageFetchProps, type MapSizePx } from './coverage-geometry';
+import type { OsmCoverageStorage } from './osm-coverage-storage';
 export type { CoverageFetchProps, MapSizePx } from './coverage-geometry';
+export type { OsmCoveragePersisted, OsmCoverageStorage } from './osm-coverage-storage';
+export { formatCoverageAgeHour, getCoverageSavedAt } from './osm-coverage-storage';
 export type OsmCoverageQueryData = {
     graph: ParsedOsmData;
     coverage: Feature<Polygon | MultiPolygon> | null;
     fetchHistory: FeatureCollection<Polygon, CoverageFetchProps>;
+    /** ISO timestamp of last durable save / successful network merge; null if never saved. */
+    savedAt: string | null;
 };
 export type CreateOsmCoverageApiOptions<TSessionParams> = {
     getSessionKey: (params: TSessionParams) => readonly unknown[];
@@ -15,22 +20,34 @@ export type CreateOsmCoverageApiOptions<TSessionParams> = {
     download?: (url: string) => Promise<ParsedOsmData>;
     /** When false, session queries stay enabled=false and ensureCoverage skips network. */
     isNetworkEnabled?: () => boolean;
+    /** Optional durable store for graph + coverage across reloads. */
+    storage?: OsmCoverageStorage;
+    /** Debounce durable writes after merges (ms). Default 500. */
+    storageSaveDebounceMs?: number;
 };
-export declare function createOsmCoverageApi<TSessionParams>({ getSessionKey, minZoom, getDownloadUrl, download, isNetworkEnabled, }: CreateOsmCoverageApiOptions<TSessionParams>): {
+export declare function createOsmCoverageApi<TSessionParams>({ getSessionKey, minZoom, getDownloadUrl, download, isNetworkEnabled, storage, storageSaveDebounceMs, }: CreateOsmCoverageApiOptions<TSessionParams>): {
     emptyData: () => OsmCoverageQueryData;
     sessionKey: (params: TSessionParams) => readonly unknown[];
     coverageKey: (params: TSessionParams) => readonly [...unknown[], "coverage"];
-    ensureCoverage: (queryClient: QueryClient, { bounds, zoom, mapSizePx, force, ...sessionParams }: {
+    ensureCoverage: (queryClient: QueryClient, { bounds, zoom, mapSizePx, force, skipRestore, clearPersistedOnForce, ...sessionParams }: {
         bounds: MapBounds;
         zoom: number;
         mapSizePx: MapSizePx;
         force?: boolean;
+        /** Skip durable hydrate for this call (e.g. prefer-fresh). */
+        skipRestore?: boolean;
+        /** When force=true, also wipe durable storage before refetch. */
+        clearPersistedOnForce?: boolean;
     } & TSessionParams) => Promise<{
         skipped: boolean;
     }>;
+    restoreSession: (queryClient: QueryClient, params: TSessionParams, options?: {
+        forceReload?: boolean;
+    }) => Promise<boolean>;
+    clearPersisted: (params: TSessionParams) => Promise<void>;
     createUseQuery: (useSessionParams: () => TSessionParams) => <TData = OsmCoverageQueryData>(options?: {
         select?: (data: OsmCoverageQueryData) => TData;
-    }) => import("@tanstack/react-query").DefinedUseQueryResult<NoInfer<TData>, Error>;
+    }) => import("@tanstack/react-query").UseQueryResult<NoInfer<TData>, Error>;
     createUseIsFetching: (useSessionParams: () => TSessionParams) => () => boolean;
     createUseResetOnSessionChange: (useSessionParams: () => TSessionParams) => () => void;
 };

package/dist/index.d.ts

@@ -1,5 +1,4 @@
-export { DEV_OSM_MAP_FIXTURE_ROUTE, devOsmMapFixtureMapUrl, } from './dev-osm-map-fixture/dev-osm-map-fixture-url';
-export { createOsmCoverageApi, type OsmCoverageQueryData } from './create-osm-coverage-api';
+export { createOsmCoverageApi, type OsmCoverageQueryData, type OsmCoveragePersisted, type OsmCoverageStorage, formatCoverageAgeHour, getCoverageSavedAt, } from './create-osm-coverage-api';
 export { type CoverageFetchProps, type CoverageFetchKind, type MapSizePx, boundsToPolygon, bufferPxAtZoom, computeMissingFetchRequests, unionIntoCoverage, } from './coverage-geometry';
 export { OsmDataSource } from './osm-data-source';
 export { boundsToOverpassBbox, buildOverpassInterpreterUrl } from './overpass-url';

package/dist/index.js

@@ -10,13 +10,7 @@ import { featureCollection } from '@turf/helpers';
 import intersect from '@turf/intersect';
 import union from '@turf/union';
 
-// src/dev-osm-map-fixture/dev-osm-map-fixture-url.ts
-var DEV_OSM_MAP_FIXTURE_ROUTE = "dev-osm-map-fixture";
-function devOsmMapFixtureMapUrl(baseUrl, bounds) {
-  const base = baseUrl.replace(/\/$/, "");
-  const bbox2 = [bounds.west, bounds.south, bounds.east, bounds.north].join(",");
-  return `${base}/${DEV_OSM_MAP_FIXTURE_ROUTE}/api/0.6/map?bbox=${bbox2}`;
-}
+// src/create-osm-coverage-api.ts
 var BUFFER_PX_AT_Z13 = 200;
 var MIN_MISSING_AREA_RATIO = 5e-3;
 var FULL_FETCH_RATIO = 0.85;
@@ -54,19 +48,15 @@ function bufferBoundsInViewport(request, viewport, zoom, mapSizePx) {
     north: request.north + latBuffer
   };
 }
-function clampBoundsToViewport(request, viewport) {
+function overlapDeltaAtZoom(viewport, zoom, mapSizePx) {
+  const px = bufferPxAtZoom(zoom);
   return {
-    west: Math.max(request.west, viewport.west),
-    south: Math.max(request.south, viewport.south),
-    east: Math.min(request.east, viewport.east),
-    north: Math.min(request.north, viewport.north)
+    lon: px * (viewport.east - viewport.west) / mapSizePx.width,
+    lat: px * (viewport.north - viewport.south) / mapSizePx.height
   };
 }
 function prepareFetchBounds(request, viewport, zoom, mapSizePx) {
-  const buffered = clampBoundsToViewport(
-    bufferBoundsInViewport(request, viewport, zoom, mapSizePx),
-    viewport
-  );
+  const buffered = bufferBoundsInViewport(request, viewport, zoom, mapSizePx);
   if (!isValidBounds(buffered)) return null;
   const viewportArea = boundsArea(viewport);
   if (boundsArea(buffered) < MIN_MISSING_AREA_RATIO * viewportArea) return null;
@@ -80,27 +70,28 @@ function missingParts(viewport, coverage) {
     (feature) => feature.geometry.type === "Polygon"
   );
 }
-function stripCandidates(viewport, coverage, missingPart) {
+function stripCandidates(viewport, coverage, missingPart, zoom, mapSizePx) {
   const viewportPoly = boundsToPolygon(viewport);
   const covered = intersect(featureCollection([viewportPoly, coverage]));
   if (!covered) return [];
   const coveredBbox = polygonToBounds(covered);
+  const { lon, lat } = overlapDeltaAtZoom(viewport, zoom, mapSizePx);
   const candidates = [
     {
       west: viewport.west,
       south: viewport.south,
-      east: coveredBbox.west,
+      east: Math.min(viewport.east, coveredBbox.west + lon),
       north: viewport.north
     },
     {
-      west: coveredBbox.east,
+      west: Math.max(viewport.west, coveredBbox.east - lon),
       south: viewport.south,
       east: viewport.east,
       north: viewport.north
     },
     {
       west: viewport.west,
-      south: coveredBbox.north,
+      south: Math.max(viewport.south, coveredBbox.north - lat),
       east: viewport.east,
       north: viewport.north
     },
@@ -108,7 +99,7 @@ function stripCandidates(viewport, coverage, missingPart) {
       west: viewport.west,
       south: viewport.south,
       east: viewport.east,
-      north: coveredBbox.south
+      north: Math.min(viewport.north, coveredBbox.south + lat)
     }
   ];
   return candidates.filter((strip) => {
@@ -117,14 +108,14 @@ function stripCandidates(viewport, coverage, missingPart) {
     return overlap !== null && area(overlap) > 0;
   });
 }
-function chooseBoundsForMissingPart(viewport, coverage, missingPart) {
+function chooseBoundsForMissingPart(viewport, coverage, missingPart, zoom, mapSizePx) {
   const partArea = area(missingPart);
   const partBbox = polygonToBounds(missingPart);
   const fillRatio = partArea / area(boundsToPolygon(partBbox));
   if (fillRatio >= HIGH_FILL_RATIO) {
     return [partBbox];
   }
-  const strips = stripCandidates(viewport, coverage, missingPart);
+  const strips = stripCandidates(viewport, coverage, missingPart, zoom, mapSizePx);
   const stripAreas = strips.map((strip) => ({ bounds: strip, area: boundsArea(strip) })).sort((a, b) => b.area - a.area);
   const stripTotalArea = stripAreas.reduce((sum, strip) => sum + strip.area, 0);
   const bboxArea = boundsArea(partBbox);
@@ -149,7 +140,7 @@ function computeMissingFetchRequests(viewport, coverage, zoom, mapSizePx) {
   );
   if (significantParts.length === 0) return [];
   const rawBounds = significantParts.flatMap(
-    (part) => chooseBoundsForMissingPart(viewport, coverage, part)
+    (part) => chooseBoundsForMissingPart(viewport, coverage, part, zoom, mapSizePx)
   );
   let requests = rawBounds.map((request) => {
     const prepared = prepareFetchBounds(request, viewport, zoom, mapSizePx);
@@ -166,6 +157,15 @@ function computeMissingFetchRequests(viewport, coverage, zoom, mapSizePx) {
     return full ? [full] : [];
   }
   requests = requests.slice(0, MAX_STRIP_REQUESTS);
+  let projected = coverage;
+  for (const request of requests) {
+    projected = unionIntoCoverage(projected, request.bounds);
+  }
+  const leftover = missingParts(viewport, projected).reduce((sum, part) => sum + area(part), 0);
+  if (leftover >= MIN_MISSING_AREA_RATIO * viewportArea) {
+    const full = createViewportFetchRequest(viewport, zoom, mapSizePx, "full");
+    return full ? [full] : [];
+  }
   return requests.map((request) => ({
     bounds: request.bounds,
     kind: request.kind
@@ -209,29 +209,112 @@ function appendFetchHistory(history, groupId, fetchedAt, requests) {
   });
 }
 
+// src/osm-coverage-storage.ts
+function getCoverageSavedAt(savedAt) {
+  if (!savedAt) return null;
+  const parsed = Date.parse(savedAt);
+  return Number.isNaN(parsed) ? null : savedAt;
+}
+function formatCoverageAgeHour(savedAt, now = /* @__PURE__ */ new Date()) {
+  const iso = getCoverageSavedAt(savedAt);
+  if (!iso) return null;
+  const saved = new Date(iso);
+  saved.setMinutes(0, 0, 0);
+  const hour = String(saved.getHours()).padStart(2, "0");
+  const sameDay = saved.getFullYear() === now.getFullYear() && saved.getMonth() === now.getMonth() && saved.getDate() === now.getDate();
+  if (sameDay) {
+    return `${hour}:00`;
+  }
+  const y = saved.getFullYear();
+  const m = String(saved.getMonth() + 1).padStart(2, "0");
+  const d = String(saved.getDate()).padStart(2, "0");
+  return `${y}-${m}-${d} ${hour}:00`;
+}
+
 // src/create-osm-coverage-api.ts
+var DEFAULT_STORAGE_SAVE_DEBOUNCE_MS = 500;
 function createOsmCoverageApi({
   getSessionKey,
   minZoom,
   getDownloadUrl,
   download = downloadOsmData,
-  isNetworkEnabled
+  isNetworkEnabled,
+  storage,
+  storageSaveDebounceMs = DEFAULT_STORAGE_SAVE_DEBOUNCE_MS
 }) {
   const getCoverageKey = (params) => [...getSessionKey(params), "coverage"];
   const networkEnabled = () => isNetworkEnabled?.() ?? true;
   const coverageChains = /* @__PURE__ */ new Map();
+  const hydratedSessions = /* @__PURE__ */ new Set();
+  const saveTimers = /* @__PURE__ */ new Map();
   function emptyData() {
     return {
       graph: emptyParsedOsmData(),
       coverage: null,
-      fetchHistory: emptyFetchHistory()
+      fetchHistory: emptyFetchHistory(),
+      savedAt: null
     };
   }
+  function scheduleSave(sessionKey, data) {
+    if (!storage || !data.coverage) return;
+    const chainKey = JSON.stringify(sessionKey);
+    const previous = saveTimers.get(chainKey);
+    if (previous) clearTimeout(previous);
+    const persisted = {
+      graph: data.graph,
+      coverage: data.coverage,
+      savedAt: data.savedAt ?? (/* @__PURE__ */ new Date()).toISOString()
+    };
+    saveTimers.set(
+      chainKey,
+      setTimeout(() => {
+        saveTimers.delete(chainKey);
+        void storage.save(sessionKey, persisted).catch((error) => {
+          console.error("Failed to persist OSM coverage session", error);
+        });
+      }, storageSaveDebounceMs)
+    );
+  }
+  async function restoreSession(queryClient, params, options) {
+    if (!storage) return false;
+    const sessionKey = getSessionKey(params);
+    const chainKey = JSON.stringify(sessionKey);
+    if (options?.forceReload) {
+      hydratedSessions.delete(chainKey);
+    }
+    if (hydratedSessions.has(chainKey)) return false;
+    hydratedSessions.add(chainKey);
+    const loaded = await storage.load(sessionKey);
+    if (!loaded?.coverage) return false;
+    const current = queryClient.getQueryData(sessionKey);
+    if (current?.coverage) return false;
+    queryClient.setQueryData(sessionKey, {
+      graph: loaded.graph,
+      coverage: loaded.coverage,
+      fetchHistory: emptyFetchHistory(),
+      savedAt: loaded.savedAt
+    });
+    return true;
+  }
+  async function clearPersisted(params) {
+    if (!storage) return;
+    const sessionKey = getSessionKey(params);
+    const chainKey = JSON.stringify(sessionKey);
+    const pending = saveTimers.get(chainKey);
+    if (pending) {
+      clearTimeout(pending);
+      saveTimers.delete(chainKey);
+    }
+    hydratedSessions.delete(chainKey);
+    await storage.clear(sessionKey);
+  }
   async function ensureCoverage(queryClient, {
     bounds,
     zoom,
     mapSizePx,
     force = false,
+    skipRestore = false,
+    clearPersistedOnForce = false,
     ...sessionParams
   }) {
     if (!networkEnabled()) {
@@ -242,6 +325,12 @@ function createOsmCoverageApi({
     const coverageKey = getCoverageKey(params);
     const chainKey = JSON.stringify(sessionKey);
     const run = async () => {
+      if (!skipRestore && !force) {
+        await restoreSession(queryClient, params);
+      }
+      if (force && clearPersistedOnForce) {
+        await clearPersisted(params);
+      }
       const requestKey = [...coverageKey, crypto.randomUUID()];
       return queryClient.fetchQuery({
         queryKey: requestKey,
@@ -274,7 +363,14 @@ function createOsmCoverageApi({
             for (const newGraph of fetchedGraphs) {
               graph = mergeParsedOsm(graph, newGraph);
             }
-            return { graph, coverage, fetchHistory };
+            const next2 = {
+              graph,
+              coverage,
+              fetchHistory,
+              savedAt: fetchedAt
+            };
+            scheduleSave(sessionKey, next2);
+            return next2;
           });
           return { skipped: false };
         },
@@ -299,8 +395,11 @@ function createOsmCoverageApi({
       return useQuery({
         queryKey: getSessionKey(params),
         queryFn: () => emptyData(),
-        initialData: emptyData(),
+        // Placeholder (not initialData) so durable restore via setQueryData is not fought
+        // by a permanently seeded empty session.
+        placeholderData: emptyData(),
         staleTime: Number.POSITIVE_INFINITY,
+        gcTime: Number.POSITIVE_INFINITY,
         enabled: networkEnabled(),
         select: options?.select
       });
@@ -332,6 +431,8 @@ function createOsmCoverageApi({
     sessionKey: getSessionKey,
     coverageKey: getCoverageKey,
     ensureCoverage,
+    restoreSession,
+    clearPersisted,
     createUseQuery,
     createUseIsFetching,
     createUseResetOnSessionChange
@@ -358,4 +459,4 @@ function buildOverpassInterpreterUrl(server, query) {
 var overpassDeUrl = "https://overpass-api.de/api/interpreter?data=";
 var overpassVkUrl = "https://maps.mail.ru/osm/tools/overpass/api/interpreter?data=";
 
-export { DEV_OSM_MAP_FIXTURE_ROUTE, OsmDataSource, boundsToOverpassBbox, boundsToPolygon, bufferPxAtZoom, buildOverpassInterpreterUrl, computeMissingFetchRequests, createOsmCoverageApi, devOsmMapFixtureMapUrl, overpassDeUrl, overpassVkUrl, unionIntoCoverage };
+export { OsmDataSource, boundsToOverpassBbox, boundsToPolygon, bufferPxAtZoom, buildOverpassInterpreterUrl, computeMissingFetchRequests, createOsmCoverageApi, formatCoverageAgeHour, getCoverageSavedAt, overpassDeUrl, overpassVkUrl, unionIntoCoverage };

package/dist/osm-coverage-storage.d.ts

@@ -0,0 +1,20 @@
+import type { ParsedOsmData } from '@osm-editor-kit/osm-data';
+import type { Feature, MultiPolygon, Polygon } from 'geojson';
+/** Durable session blob — fetchHistory stays memory-only. */
+export type OsmCoveragePersisted = {
+    graph: ParsedOsmData;
+    coverage: Feature<Polygon | MultiPolygon> | null;
+    savedAt: string;
+};
+export type OsmCoverageStorage = {
+    load(sessionKey: readonly unknown[]): Promise<OsmCoveragePersisted | null>;
+    save(sessionKey: readonly unknown[], data: OsmCoveragePersisted): Promise<void>;
+    clear(sessionKey: readonly unknown[]): Promise<void>;
+};
+/** ISO `savedAt` from session query data, or null when never persisted/fetched. */
+export declare function getCoverageSavedAt(savedAt: string | null | undefined): string | null;
+/**
+ * Round `savedAt` down to the hour for UI (“OSM data from 14:00”).
+ * Returns null when missing/invalid.
+ */
+export declare function formatCoverageAgeHour(savedAt: string | null | undefined, now?: Date): string | null;

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@osm-editor-kit/osm-coverage",
-  "version": "0.1.0-alpha.0",
+  "version": "0.1.0-alpha.3",
   "description": "Incremental OSM coverage fetching for map viewports with TanStack Query session state.",
+  "homepage": "https://github.com/osmberlin/street-space-editor/tree/main/packages/osm-coverage",
   "license": "MIT",
   "author": "Tobias Jordans",
   "repository": {
@@ -9,11 +10,11 @@
     "url": "git+https://github.com/osmberlin/street-space-editor.git",
     "directory": "packages/osm-coverage"
   },
-  "type": "module",
-  "sideEffects": false,
   "files": [
     "dist"
   ],
+  "type": "module",
+  "sideEffects": false,
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -35,7 +36,7 @@
     "postpack": "bun ../../scripts/package-exports-restore.ts"
   },
   "dependencies": {
-    "@osm-editor-kit/osm-data": "workspace:*",
+    "@osm-editor-kit/osm-data": "^0.1.0-alpha.1",
     "@tanstack/react-query": "^5.85.5",
     "@turf/area": "^7.3.5",
     "@turf/bbox": "^7.3.5",