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

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
 
@@ -19,11 +24,13 @@ const api = createOsmCoverageApi<{ source: OsmDataSource }>({
   minZoom: 14,
   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 +39,5 @@ await api.ensureCoverage(queryClient, {
 })
 
 const data = queryClient.getQueryData(api.sessionKey(params))
-// { graph, coverage, fetchHistory }
+// { graph, coverage, fetchHistory, savedAt }
 ```

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;
@@ -209,29 +203,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 +319,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 +357,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 +389,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 +425,8 @@ function createOsmCoverageApi({
     sessionKey: getSessionKey,
     coverageKey: getCoverageKey,
     ensureCoverage,
+    restoreSession,
+    clearPersisted,
     createUseQuery,
     createUseIsFetching,
     createUseResetOnSessionChange
@@ -358,4 +453,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,6 +1,6 @@
 {
   "name": "@osm-editor-kit/osm-coverage",
-  "version": "0.1.0-alpha.0",
+  "version": "0.1.0-alpha.2",
   "description": "Incremental OSM coverage fetching for map viewports with TanStack Query session state.",
   "license": "MIT",
   "author": "Tobias Jordans",
@@ -9,6 +9,7 @@
     "url": "git+https://github.com/osmberlin/street-space-editor.git",
     "directory": "packages/osm-coverage"
   },
+  "homepage": "https://github.com/osmberlin/street-space-editor/tree/main/packages/osm-coverage",
   "type": "module",
   "sideEffects": false,
   "files": [