.chainlink/issues.db

reviewed

This is a binary file and will not be displayed.

+4

CHANGELOG.md

reviewed

··· 11 11 ### Fixed 12 12 13 13 ### Changed 14 14 + - geocoder.ts — TDD (#3) 15 15 + - Refactor geocoder (#13) 16 16 + - Implement geocoder (#12) 17 17 + - Write geocoder tests (#11) 14 18 - Adversarial review: parser.ts (#23) 15 19 - parser.ts — TDD (#2) 16 20 - Refactor parser (#10)

+222

src/geocoder.ts

reviewed

··· 1 1 + /** 2 2 + * geocoder.ts — Nominatim Geocoder (Effectful) 3 3 + * 4 4 + * Convert place names to lat/lng coordinates via OpenStreetMap Nominatim API. 5 5 + * Handles rate limiting, deduplication, cancellation, and progressive updates. 6 6 + */ 7 7 + 8 8 + import type { Place } from "./parser"; 9 9 + 10 10 + export interface GeoResult { 11 11 + lat: number; 12 12 + lng: number; 13 13 + } 14 14 + 15 15 + export interface GeocodeCallbacks { 16 16 + onProgress?: (place: Place, result: GeoResult | null) => void; 17 17 + } 18 18 + 19 19 + /** Minimum delay between sequential Nominatim requests (ms). */ 20 20 + const RATE_LIMIT_MS = 1100; 21 21 + 22 22 + /** Per-request fetch timeout (ms). */ 23 23 + const FETCH_TIMEOUT_MS = 10_000; 24 24 + 25 25 + /** Consecutive failure threshold for showing an Obsidian Notice. */ 26 26 + const CONSECUTIVE_FAILURE_NOTICE_THRESHOLD = 3; 27 27 + 28 28 + const NOMINATIM_BASE = "https://nominatim.openstreetmap.org/search"; 29 29 + const USER_AGENT = "ObsidianMapViewer/1.0"; 30 30 + 31 31 + /** 32 32 + * Geocode an array of places via Nominatim. 33 33 + * 34 34 + * - Only geocodes places where lat AND lng are both undefined/null. 35 35 + * - Deduplicates by case-insensitive trimmed name. 36 36 + * - Rate-limits to 1100ms between sequential requests. 37 37 + * - Supports external cancellation via AbortSignal. 38 38 + * - Reports progress via onProgress callback. 39 39 + */ 40 40 + export async function geocodePlaces( 41 41 + places: Place[], 42 42 + callbacks?: GeocodeCallbacks, 43 43 + signal?: AbortSignal 44 44 + ): Promise<Place[]> { 45 45 + // Contract 13: empty array short-circuit 46 46 + if (places.length === 0) return []; 47 47 + 48 48 + // Build dedup map: normalized name -> { queryName, indices } 49 49 + const dedupMap = new Map< 50 50 + string, 51 51 + { queryName: string; indices: number[] } 52 52 + >(); 53 53 + 54 54 + // Collect which places need geocoding and build dedup groups 55 55 + const geocodeOrder: string[] = []; // order of unique normalized names to geocode 56 56 + 57 57 + for (let i = 0; i < places.length; i++) { 58 58 + const place = places[i]; 59 59 + 60 60 + // Contract 1: skip places with existing coordinates 61 61 + if (place.lat != null && place.lng != null) { 62 62 + continue; 63 63 + } 64 64 + 65 65 + const normalizedName = place.name.trim().toLowerCase(); 66 66 + 67 67 + if (dedupMap.has(normalizedName)) { 68 68 + // Contract 5: deduplication — add index to existing group 69 69 + dedupMap.get(normalizedName)!.indices.push(i); 70 70 + } else { 71 71 + // First encounter of this name 72 72 + dedupMap.set(normalizedName, { 73 73 + queryName: place.name.trim(), 74 74 + indices: [i], 75 75 + }); 76 76 + geocodeOrder.push(normalizedName); 77 77 + } 78 78 + } 79 79 + 80 80 + let consecutiveFailures = 0; 81 81 + 82 82 + // Process each unique name sequentially 83 83 + for (let g = 0; g < geocodeOrder.length; g++) { 84 84 + const normalizedName = geocodeOrder[g]; 85 85 + const group = dedupMap.get(normalizedName)!; 86 86 + 87 87 + // Contract 11: check external abort signal before making request 88 88 + if (signal?.aborted) { 89 89 + break; 90 90 + } 91 91 + 92 92 + // Contract 4: rate limiting — wait 1100ms between requests (not before first) 93 93 + // Contract 11: delay is cancellable — signal aborts immediately, not after full delay 94 94 + if (g > 0) { 95 95 + await delay(RATE_LIMIT_MS, signal); 96 96 + if (signal?.aborted) { 97 97 + break; 98 98 + } 99 99 + } 100 100 + 101 101 + // Perform the geocode 102 102 + const result = await fetchGeocode(group.queryName, signal); 103 103 + 104 104 + if (result === null) { 105 105 + consecutiveFailures++; 106 106 + // Contract 12: Notice on exactly the 3rd consecutive failure (not every subsequent one) 107 107 + if (consecutiveFailures === CONSECUTIVE_FAILURE_NOTICE_THRESHOLD) { 108 108 + try { 109 109 + // eslint-disable-next-line no-undef 110 110 + new (globalThis as any).Notice( 111 111 + "Map Viewer: Geocoding issues — check your network connection" 112 112 + ); 113 113 + } catch { 114 114 + // Notice may not exist outside Obsidian — swallow silently 115 115 + } 116 116 + } 117 117 + } else { 118 118 + consecutiveFailures = 0; 119 119 + } 120 120 + 121 121 + // Contract 7 & 9: apply result to all places in this dedup group 122 122 + for (const idx of group.indices) { 123 123 + if (result) { 124 124 + places[idx].lat = result.lat; 125 125 + places[idx].lng = result.lng; 126 126 + } 127 127 + } 128 128 + 129 129 + // Contract 7: call onProgress for the first place in the group 130 130 + if (callbacks?.onProgress) { 131 131 + const firstIdx = group.indices[0]; 132 132 + callbacks.onProgress(places[firstIdx], result); 133 133 + } 134 134 + } 135 135 + 136 136 + return places; 137 137 + } 138 138 + 139 139 + /** 140 140 + * Fetch geocode result for a single place name from Nominatim. 141 141 + * Returns GeoResult on success, null on failure/empty/timeout. 142 142 + */ 143 143 + async function fetchGeocode( 144 144 + name: string, 145 145 + externalSignal?: AbortSignal 146 146 + ): Promise<GeoResult | null> { 147 147 + // Contract 10: 10-second timeout via AbortController 148 148 + const timeoutController = new AbortController(); 149 149 + const timeoutId = setTimeout(() => timeoutController.abort(), FETCH_TIMEOUT_MS); 150 150 + 151 151 + // Combine external signal and timeout signal 152 152 + const combinedController = new AbortController(); 153 153 + 154 154 + // If external signal aborts, abort combined 155 155 + const onExternalAbort = () => combinedController.abort(); 156 156 + if (externalSignal) { 157 157 + if (externalSignal.aborted) { 158 158 + clearTimeout(timeoutId); 159 159 + return null; 160 160 + } 161 161 + externalSignal.addEventListener("abort", onExternalAbort); 162 162 + } 163 163 + 164 164 + // If timeout aborts, abort combined 165 165 + timeoutController.signal.addEventListener("abort", () => 166 166 + combinedController.abort() 167 167 + ); 168 168 + 169 169 + // Contract 2: build Nominatim URL 170 170 + const url = `${NOMINATIM_BASE}?format=json&limit=1&q=${encodeURIComponent(name)}`; 171 171 + 172 172 + try { 173 173 + // Contract 6: User-Agent header 174 174 + const response = await fetch(url, { 175 175 + headers: { "User-Agent": USER_AGENT }, 176 176 + signal: combinedController.signal, 177 177 + }); 178 178 + 179 179 + const data = await response.json(); 180 180 + 181 181 + // Empty results 182 182 + if (!Array.isArray(data) || data.length === 0) { 183 183 + // Contract 12: warn for empty results 184 184 + console.warn("[MapViewer] No results for:", name); 185 185 + return null; 186 186 + } 187 187 + 188 188 + const lat = parseFloat(data[0].lat); 189 189 + const lng = parseFloat(data[0].lon); 190 190 + 191 191 + if (isNaN(lat) || isNaN(lng)) { 192 192 + console.warn("[MapViewer] Invalid coordinates for:", name); 193 193 + return null; 194 194 + } 195 195 + 196 196 + return { lat, lng }; 197 197 + } catch (err) { 198 198 + // Contract 8 & 12: network failures logged, place skipped 199 199 + console.warn("[MapViewer] Geocode failed for:", name, err); 200 200 + return null; 201 201 + } finally { 202 202 + clearTimeout(timeoutId); 203 203 + if (externalSignal) { 204 204 + externalSignal.removeEventListener("abort", onExternalAbort); 205 205 + } 206 206 + } 207 207 + } 208 208 + 209 209 + /** Promise-based delay that can be cancelled via AbortSignal. */ 210 210 + function delay(ms: number, signal?: AbortSignal): Promise<void> { 211 211 + return new Promise((resolve) => { 212 212 + if (signal?.aborted) { 213 213 + resolve(); 214 214 + return; 215 215 + } 216 216 + const timerId = setTimeout(resolve, ms); 217 217 + signal?.addEventListener("abort", () => { 218 218 + clearTimeout(timerId); 219 219 + resolve(); 220 220 + }, { once: true }); 221 221 + }); 222 222 + }

+720

tests/geocoder.test.ts

reviewed

··· 1 1 + /** 2 2 + * geocoder.test.ts — Tests for all geocoder.ts behavioral contracts 3 3 + * 4 4 + * Tests mock global fetch via vi.fn() and use fake timers for rate-limit testing. 5 5 + */ 6 6 + import { describe, it, expect, vi, beforeEach, afterEach } from "vitest"; 7 7 + import { geocodePlaces } from "../src/geocoder"; 8 8 + import type { Place } from "../src/parser"; 9 9 + 10 10 + // ─── Helpers ────────────────────────────────────────────────────────── 11 11 + 12 12 + /** Create a Place with sensible defaults */ 13 13 + function makePlace( 14 14 + name: string, 15 15 + overrides: Partial<Place> = {} 16 16 + ): Place { 17 17 + return { 18 18 + name, 19 19 + fields: {}, 20 20 + notes: [], 21 21 + startLine: 0, 22 22 + endLine: 0, 23 23 + ...overrides, 24 24 + }; 25 25 + } 26 26 + 27 27 + /** Build a successful Nominatim JSON response */ 28 28 + function nominatimOk(lat: number, lng: number): Response { 29 29 + return new Response(JSON.stringify([{ lat: String(lat), lon: String(lng) }]), { 30 30 + status: 200, 31 31 + headers: { "Content-Type": "application/json" }, 32 32 + }); 33 33 + } 34 34 + 35 35 + /** Build an empty Nominatim response (no results) */ 36 36 + function nominatimEmpty(): Response { 37 37 + return new Response(JSON.stringify([]), { 38 38 + status: 200, 39 39 + headers: { "Content-Type": "application/json" }, 40 40 + }); 41 41 + } 42 42 + 43 43 + // ─── Mock Setup ─────────────────────────────────────────────────────── 44 44 + 45 45 + let mockFetch: ReturnType<typeof vi.fn>; 46 46 + 47 47 + beforeEach(() => { 48 48 + mockFetch = vi.fn(); 49 49 + vi.stubGlobal("fetch", mockFetch); 50 50 + vi.stubGlobal("Notice", vi.fn()); 51 51 + vi.spyOn(console, "warn").mockImplementation(() => {}); 52 52 + }); 53 53 + 54 54 + afterEach(() => { 55 55 + vi.restoreAllMocks(); 56 56 + vi.unstubAllGlobals(); 57 57 + }); 58 58 + 59 59 + // ─── Contract 13: Empty array short-circuit ─────────────────────────── 60 60 + 61 61 + describe("Contract 13: empty array short-circuit", () => { 62 62 + it("returns [] immediately for empty input, no API calls", async () => { 63 63 + const result = await geocodePlaces([]); 64 64 + expect(result).toEqual([]); 65 65 + expect(mockFetch).not.toHaveBeenCalled(); 66 66 + }); 67 67 + }); 68 68 + 69 69 + // ─── Contract 1: Skip places with existing coordinates ──────────────── 70 70 + 71 71 + describe("Contract 1: skip places with existing coordinates", () => { 72 72 + it("returns places with lat/lng unchanged, no API calls", async () => { 73 73 + const places = [ 74 74 + makePlace("Sagrada Familia", { lat: 41.4036, lng: 2.1744 }), 75 75 + ]; 76 76 + const result = await geocodePlaces(places); 77 77 + expect(result).toHaveLength(1); 78 78 + expect(result[0].lat).toBe(41.4036); 79 79 + expect(result[0].lng).toBe(2.1744); 80 80 + expect(mockFetch).not.toHaveBeenCalled(); 81 81 + }); 82 82 + 83 83 + it("only geocodes places missing coordinates", async () => { 84 84 + mockFetch.mockResolvedValueOnce(nominatimOk(48.8606, 2.3376)); 85 85 + 86 86 + const places = [ 87 87 + makePlace("Sagrada Familia", { lat: 41.4036, lng: 2.1744 }), 88 88 + makePlace("The Louvre"), 89 89 + ]; 90 90 + const result = await geocodePlaces(places); 91 91 + expect(result).toHaveLength(2); 92 92 + expect(result[0].lat).toBe(41.4036); // unchanged 93 93 + expect(result[1].lat).toBe(48.8606); // geocoded 94 94 + expect(mockFetch).toHaveBeenCalledTimes(1); 95 95 + }); 96 96 + 97 97 + it("treats lat: 0, lng: 0 as valid existing coordinates (not falsy)", async () => { 98 98 + const places = [ 99 99 + makePlace("Null Island", { lat: 0, lng: 0 }), 100 100 + ]; 101 101 + const result = await geocodePlaces(places); 102 102 + expect(result[0].lat).toBe(0); 103 103 + expect(result[0].lng).toBe(0); 104 104 + expect(mockFetch).not.toHaveBeenCalled(); 105 105 + }); 106 106 + 107 107 + it("geocodes places with only lat set (half-populated)", async () => { 108 108 + mockFetch.mockResolvedValueOnce(nominatimOk(41.4036, 2.1744)); 109 109 + 110 110 + const places = [makePlace("Half Place", { lat: 41.4036 })]; 111 111 + const result = await geocodePlaces(places); 112 112 + // Only lat was set, lng was undefined — should geocode 113 113 + expect(result[0].lat).toBe(41.4036); 114 114 + expect(result[0].lng).toBe(2.1744); 115 115 + expect(mockFetch).toHaveBeenCalledTimes(1); 116 116 + }); 117 117 + 118 118 + it("geocodes places with only lng set (half-populated)", async () => { 119 119 + mockFetch.mockResolvedValueOnce(nominatimOk(41.4036, 2.1744)); 120 120 + 121 121 + const places = [makePlace("Half Place", { lng: 2.1744 })]; 122 122 + const result = await geocodePlaces(places); 123 123 + expect(result[0].lat).toBe(41.4036); 124 124 + expect(result[0].lng).toBe(2.1744); 125 125 + expect(mockFetch).toHaveBeenCalledTimes(1); 126 126 + }); 127 127 + }); 128 128 + 129 129 + // ─── Contract 2 & 3: Nominatim URL and query string ────────────────── 130 130 + 131 131 + describe("Contract 2 & 3: Nominatim URL and query params", () => { 132 132 + it("queries Nominatim with correct URL, format, limit, and encoded name", async () => { 133 133 + mockFetch.mockResolvedValueOnce(nominatimOk(41.4036, 2.1744)); 134 134 + 135 135 + await geocodePlaces([makePlace("Sagrada Familia")]); 136 136 + 137 137 + expect(mockFetch).toHaveBeenCalledTimes(1); 138 138 + const [url, options] = mockFetch.mock.calls[0]; 139 139 + const parsedUrl = new URL(url); 140 140 + 141 141 + expect(parsedUrl.origin + parsedUrl.pathname).toBe( 142 142 + "https://nominatim.openstreetmap.org/search" 143 143 + ); 144 144 + expect(parsedUrl.searchParams.get("format")).toBe("json"); 145 145 + expect(parsedUrl.searchParams.get("limit")).toBe("1"); 146 146 + expect(parsedUrl.searchParams.get("q")).toBe("Sagrada Familia"); 147 147 + }); 148 148 + }); 149 149 + 150 150 + // ─── Contract 6: User-Agent header ──────────────────────────────────── 151 151 + 152 152 + describe("Contract 6: User-Agent header", () => { 153 153 + it("sets User-Agent to ObsidianMapViewer/1.0", async () => { 154 154 + mockFetch.mockResolvedValueOnce(nominatimOk(41.4036, 2.1744)); 155 155 + 156 156 + await geocodePlaces([makePlace("Sagrada Familia")]); 157 157 + 158 158 + const [, options] = mockFetch.mock.calls[0]; 159 159 + expect(options.headers["User-Agent"]).toBe("ObsidianMapViewer/1.0"); 160 160 + }); 161 161 + }); 162 162 + 163 163 + // ─── Contract 4: Rate limiting ──────────────────────────────────────── 164 164 + 165 165 + describe("Contract 4: rate limiting (1100ms between requests)", () => { 166 166 + it("waits at least 1100ms between sequential API calls", async () => { 167 167 + vi.useFakeTimers(); 168 168 + 169 169 + mockFetch 170 170 + .mockResolvedValueOnce(nominatimOk(41.4036, 2.1744)) 171 171 + .mockResolvedValueOnce(nominatimOk(48.8606, 2.3376)); 172 172 + 173 173 + const places = [makePlace("Place A"), makePlace("Place B")]; 174 174 + const promise = geocodePlaces(places); 175 175 + 176 176 + // First fetch fires immediately 177 177 + await vi.advanceTimersByTimeAsync(0); 178 178 + expect(mockFetch).toHaveBeenCalledTimes(1); 179 179 + 180 180 + // At 1099ms, second fetch should not have fired yet 181 181 + await vi.advanceTimersByTimeAsync(1099); 182 182 + expect(mockFetch).toHaveBeenCalledTimes(1); 183 183 + 184 184 + // At 1100ms, second fetch should fire 185 185 + await vi.advanceTimersByTimeAsync(1); 186 186 + expect(mockFetch).toHaveBeenCalledTimes(2); 187 187 + 188 188 + // Let the promise resolve 189 189 + await vi.advanceTimersByTimeAsync(0); 190 190 + await promise; 191 191 + 192 192 + vi.useRealTimers(); 193 193 + }); 194 194 + 195 195 + it("requests are fully sequential — waits for response before delaying", async () => { 196 196 + vi.useFakeTimers(); 197 197 + 198 198 + let resolveFirst: (value: Response) => void; 199 199 + const firstFetchPromise = new Promise<Response>((resolve) => { 200 200 + resolveFirst = resolve; 201 201 + }); 202 202 + 203 203 + mockFetch 204 204 + .mockReturnValueOnce(firstFetchPromise) 205 205 + .mockResolvedValueOnce(nominatimOk(48.8606, 2.3376)); 206 206 + 207 207 + const places = [makePlace("Place A"), makePlace("Place B")]; 208 208 + const promise = geocodePlaces(places); 209 209 + 210 210 + // First fetch fires 211 211 + await vi.advanceTimersByTimeAsync(0); 212 212 + expect(mockFetch).toHaveBeenCalledTimes(1); 213 213 + 214 214 + // Even after 2000ms, second fetch shouldn't fire because first hasn't resolved 215 215 + await vi.advanceTimersByTimeAsync(2000); 216 216 + expect(mockFetch).toHaveBeenCalledTimes(1); 217 217 + 218 218 + // Resolve first fetch 219 219 + resolveFirst!(nominatimOk(41.4036, 2.1744)); 220 220 + await vi.advanceTimersByTimeAsync(0); 221 221 + 222 222 + // Still need to wait 1100ms after response 223 223 + expect(mockFetch).toHaveBeenCalledTimes(1); 224 224 + await vi.advanceTimersByTimeAsync(1100); 225 225 + expect(mockFetch).toHaveBeenCalledTimes(2); 226 226 + 227 227 + await vi.advanceTimersByTimeAsync(0); 228 228 + await promise; 229 229 + 230 230 + vi.useRealTimers(); 231 231 + }); 232 232 + }); 233 233 + 234 234 + // ─── Contract 5: Deduplication ──────────────────────────────────────── 235 235 + 236 236 + describe("Contract 5: deduplication (case-insensitive, trimmed)", () => { 237 237 + it("makes only one API call for duplicate names", async () => { 238 238 + mockFetch.mockResolvedValueOnce(nominatimOk(41.4036, 2.1744)); 239 239 + 240 240 + const places = [ 241 241 + makePlace("Sagrada Familia"), 242 242 + makePlace("sagrada familia"), 243 243 + ]; 244 244 + const result = await geocodePlaces(places); 245 245 + 246 246 + expect(mockFetch).toHaveBeenCalledTimes(1); 247 247 + // Both places get the same result 248 248 + expect(result[0].lat).toBe(41.4036); 249 249 + expect(result[1].lat).toBe(41.4036); 250 250 + }); 251 251 + 252 252 + it("uses the first-encountered variant for the API call", async () => { 253 253 + mockFetch.mockResolvedValueOnce(nominatimOk(41.4036, 2.1744)); 254 254 + 255 255 + const places = [ 256 256 + makePlace("Sagrada Familia"), 257 257 + makePlace("SAGRADA FAMILIA"), 258 258 + ]; 259 259 + await geocodePlaces(places); 260 260 + 261 261 + const [url] = mockFetch.mock.calls[0]; 262 262 + const parsedUrl = new URL(url); 263 263 + expect(parsedUrl.searchParams.get("q")).toBe("Sagrada Familia"); 264 264 + }); 265 265 + 266 266 + it("trims names for dedup comparison", async () => { 267 267 + mockFetch.mockResolvedValueOnce(nominatimOk(41.4036, 2.1744)); 268 268 + 269 269 + const places = [ 270 270 + makePlace(" Sagrada Familia "), 271 271 + makePlace("Sagrada Familia"), 272 272 + ]; 273 273 + const result = await geocodePlaces(places); 274 274 + 275 275 + expect(mockFetch).toHaveBeenCalledTimes(1); 276 276 + expect(result[0].lat).toBe(41.4036); 277 277 + expect(result[1].lat).toBe(41.4036); 278 278 + }); 279 279 + }); 280 280 + 281 281 + // ─── Contract 7: onProgress callback ───────────────────────────────── 282 282 + 283 283 + describe("Contract 7: onProgress callback", () => { 284 284 + it("calls onProgress after each unique geocode completes (success)", async () => { 285 285 + vi.useFakeTimers(); 286 286 + mockFetch 287 287 + .mockResolvedValueOnce(nominatimOk(41.4036, 2.1744)) 288 288 + .mockResolvedValueOnce(nominatimOk(48.8606, 2.3376)); 289 289 + 290 290 + const onProgress = vi.fn(); 291 291 + const places = [makePlace("Place A"), makePlace("Place B")]; 292 292 + const promise = geocodePlaces(places, { onProgress }); 293 293 + await vi.runAllTimersAsync(); 294 294 + await promise; 295 295 + 296 296 + expect(onProgress).toHaveBeenCalledTimes(2); 297 297 + expect(onProgress).toHaveBeenCalledWith( 298 298 + expect.objectContaining({ name: "Place A" }), 299 299 + { lat: 41.4036, lng: 2.1744 } 300 300 + ); 301 301 + expect(onProgress).toHaveBeenCalledWith( 302 302 + expect.objectContaining({ name: "Place B" }), 303 303 + { lat: 48.8606, lng: 2.3376 } 304 304 + ); 305 305 + vi.useRealTimers(); 306 306 + }); 307 307 + 308 308 + it("calls onProgress with null for failed geocodes", async () => { 309 309 + mockFetch.mockRejectedValueOnce(new Error("Network error")); 310 310 + 311 311 + const onProgress = vi.fn(); 312 312 + await geocodePlaces([makePlace("Bad Place")], { onProgress }); 313 313 + 314 314 + expect(onProgress).toHaveBeenCalledTimes(1); 315 315 + expect(onProgress).toHaveBeenCalledWith( 316 316 + expect.objectContaining({ name: "Bad Place" }), 317 317 + null 318 318 + ); 319 319 + }); 320 320 + 321 321 + it("calls onProgress with null for empty Nominatim results", async () => { 322 322 + mockFetch.mockResolvedValueOnce(nominatimEmpty()); 323 323 + 324 324 + const onProgress = vi.fn(); 325 325 + await geocodePlaces([makePlace("Nonexistent Place")], { onProgress }); 326 326 + 327 327 + expect(onProgress).toHaveBeenCalledTimes(1); 328 328 + expect(onProgress).toHaveBeenCalledWith( 329 329 + expect.objectContaining({ name: "Nonexistent Place" }), 330 330 + null 331 331 + ); 332 332 + }); 333 333 + 334 334 + it("calls onProgress for all duplicate places, not just the first", async () => { 335 335 + mockFetch.mockResolvedValueOnce(nominatimOk(41.4036, 2.1744)); 336 336 + 337 337 + const onProgress = vi.fn(); 338 338 + const places = [ 339 339 + makePlace("Sagrada Familia"), 340 340 + makePlace("sagrada familia"), 341 341 + ]; 342 342 + await geocodePlaces(places, { onProgress }); 343 343 + 344 344 + // onProgress should be called once for the unique geocode, but reported 345 345 + // for each place that shares the name 346 346 + expect(onProgress).toHaveBeenCalledTimes(1); 347 347 + // The first place triggers the call 348 348 + expect(onProgress).toHaveBeenCalledWith( 349 349 + expect.objectContaining({ name: "Sagrada Familia" }), 350 350 + { lat: 41.4036, lng: 2.1744 } 351 351 + ); 352 352 + }); 353 353 + }); 354 354 + 355 355 + // ─── Contract 8: Network failure resilience ─────────────────────────── 356 356 + 357 357 + describe("Contract 8: network failures don't abort batch", () => { 358 358 + it("skips failed place and continues with remaining", async () => { 359 359 + vi.useFakeTimers(); 360 360 + mockFetch 361 361 + .mockRejectedValueOnce(new Error("Network error")) 362 362 + .mockResolvedValueOnce(nominatimOk(48.8606, 2.3376)); 363 363 + 364 364 + const places = [makePlace("Bad Place"), makePlace("Good Place")]; 365 365 + const promise = geocodePlaces(places); 366 366 + await vi.runAllTimersAsync(); 367 367 + const result = await promise; 368 368 + 369 369 + expect(result).toHaveLength(2); 370 370 + expect(result[0].lat).toBeUndefined(); 371 371 + expect(result[0].lng).toBeUndefined(); 372 372 + expect(result[1].lat).toBe(48.8606); 373 373 + expect(result[1].lng).toBe(2.3376); 374 374 + vi.useRealTimers(); 375 375 + }); 376 376 + 377 377 + it("keeps lat/lng undefined for places with no Nominatim results", async () => { 378 378 + mockFetch.mockResolvedValueOnce(nominatimEmpty()); 379 379 + 380 380 + const result = await geocodePlaces([makePlace("Nonexistent")]); 381 381 + expect(result[0].lat).toBeUndefined(); 382 382 + expect(result[0].lng).toBeUndefined(); 383 383 + }); 384 384 + 385 385 + it("handles non-200 HTTP responses gracefully (e.g., 429 rate limit)", async () => { 386 386 + mockFetch.mockResolvedValueOnce( 387 387 + new Response(JSON.stringify({ error: "Rate limit exceeded" }), { 388 388 + status: 429, 389 389 + }) 390 390 + ); 391 391 + 392 392 + const result = await geocodePlaces([makePlace("Rate Limited")]); 393 393 + expect(result[0].lat).toBeUndefined(); 394 394 + expect(result[0].lng).toBeUndefined(); 395 395 + }); 396 396 + 397 397 + it("handles invalid JSON response body gracefully", async () => { 398 398 + mockFetch.mockResolvedValueOnce( 399 399 + new Response("<html>Server Error</html>", { 400 400 + status: 200, 401 401 + headers: { "Content-Type": "text/html" }, 402 402 + }) 403 403 + ); 404 404 + 405 405 + const result = await geocodePlaces([makePlace("Bad Response")]); 406 406 + expect(result[0].lat).toBeUndefined(); 407 407 + expect(result[0].lng).toBeUndefined(); 408 408 + }); 409 409 + }); 410 410 + 411 411 + // ─── Contract 9: Return full array with geocoded lat/lng ────────────── 412 412 + 413 413 + describe("Contract 9: returns full array with geocoded results", () => { 414 414 + it("returns all places with successfully geocoded lat/lng set", async () => { 415 415 + vi.useFakeTimers(); 416 416 + mockFetch 417 417 + .mockResolvedValueOnce(nominatimOk(41.4036, 2.1744)) 418 418 + .mockResolvedValueOnce(nominatimOk(48.8606, 2.3376)); 419 419 + 420 420 + const places = [makePlace("Place A"), makePlace("Place B")]; 421 421 + const promise = geocodePlaces(places); 422 422 + await vi.runAllTimersAsync(); 423 423 + const result = await promise; 424 424 + 425 425 + expect(result).toHaveLength(2); 426 426 + expect(result[0]).toEqual( 427 427 + expect.objectContaining({ name: "Place A", lat: 41.4036, lng: 2.1744 }) 428 428 + ); 429 429 + expect(result[1]).toEqual( 430 430 + expect.objectContaining({ name: "Place B", lat: 48.8606, lng: 2.3376 }) 431 431 + ); 432 432 + vi.useRealTimers(); 433 433 + }); 434 434 + 435 435 + it("preserves all original place properties", async () => { 436 436 + mockFetch.mockResolvedValueOnce(nominatimOk(41.4036, 2.1744)); 437 437 + 438 438 + const places = [ 439 439 + makePlace("Sagrada Familia", { 440 440 + url: "https://example.com", 441 441 + fields: { category: "Architecture" }, 442 442 + notes: ["Amazing"], 443 443 + startLine: 5, 444 444 + endLine: 8, 445 445 + }), 446 446 + ]; 447 447 + const result = await geocodePlaces(places); 448 448 + 449 449 + expect(result[0].url).toBe("https://example.com"); 450 450 + expect(result[0].fields).toEqual({ category: "Architecture" }); 451 451 + expect(result[0].notes).toEqual(["Amazing"]); 452 452 + expect(result[0].startLine).toBe(5); 453 453 + expect(result[0].endLine).toBe(8); 454 454 + expect(result[0].lat).toBe(41.4036); 455 455 + expect(result[0].lng).toBe(2.1744); 456 456 + }); 457 457 + }); 458 458 + 459 459 + // ─── Contract 10: 10-second fetch timeout ───────────────────────────── 460 460 + 461 461 + describe("Contract 10: 10-second fetch timeout", () => { 462 462 + it("aborts fetch after 10 seconds and treats as network failure", async () => { 463 463 + vi.useFakeTimers(); 464 464 + 465 465 + // A fetch that never resolves 466 466 + mockFetch.mockImplementationOnce( 467 467 + (_url: string, options: { signal: AbortSignal }) => { 468 468 + return new Promise<Response>((resolve, reject) => { 469 469 + options.signal.addEventListener("abort", () => { 470 470 + reject(new DOMException("The operation was aborted.", "AbortError")); 471 471 + }); 472 472 + }); 473 473 + } 474 474 + ); 475 475 + 476 476 + const places = [makePlace("Slow Place")]; 477 477 + const promise = geocodePlaces(places); 478 478 + 479 479 + // Advance past the 10s timeout 480 480 + await vi.advanceTimersByTimeAsync(10_000); 481 481 + const result = await promise; 482 482 + 483 483 + expect(result[0].lat).toBeUndefined(); 484 484 + expect(result[0].lng).toBeUndefined(); 485 485 + 486 486 + vi.useRealTimers(); 487 487 + }); 488 488 + 489 489 + it("fetch timeout is treated as network failure (place skipped, batch continues)", async () => { 490 490 + vi.useFakeTimers(); 491 491 + 492 492 + // First fetch times out, second succeeds 493 493 + mockFetch 494 494 + .mockImplementationOnce( 495 495 + (_url: string, options: { signal: AbortSignal }) => { 496 496 + return new Promise<Response>((resolve, reject) => { 497 497 + options.signal.addEventListener("abort", () => { 498 498 + reject( 499 499 + new DOMException("The operation was aborted.", "AbortError") 500 500 + ); 501 501 + }); 502 502 + }); 503 503 + } 504 504 + ) 505 505 + .mockResolvedValueOnce(nominatimOk(48.8606, 2.3376)); 506 506 + 507 507 + const places = [makePlace("Slow Place"), makePlace("Fast Place")]; 508 508 + const promise = geocodePlaces(places); 509 509 + 510 510 + // Advance past timeout + rate limit 511 511 + await vi.advanceTimersByTimeAsync(10_000 + 1100); 512 512 + const result = await promise; 513 513 + 514 514 + expect(result[0].lat).toBeUndefined(); 515 515 + expect(result[1].lat).toBe(48.8606); 516 516 + 517 517 + vi.useRealTimers(); 518 518 + }); 519 519 + }); 520 520 + 521 521 + // ─── Contract 11: External AbortSignal cancellation ─────────────────── 522 522 + 523 523 + describe("Contract 11: external AbortSignal cancellation", () => { 524 524 + it("stops processing when signal fires, returns partial results", async () => { 525 525 + const controller = new AbortController(); 526 526 + 527 527 + mockFetch.mockImplementation(() => { 528 528 + // After first fetch, abort the signal 529 529 + controller.abort(); 530 530 + return Promise.resolve(nominatimOk(41.4036, 2.1744)); 531 531 + }); 532 532 + 533 533 + const places = [makePlace("Place A"), makePlace("Place B")]; 534 534 + const result = await geocodePlaces(places, {}, controller.signal); 535 535 + 536 536 + // Place A should be geocoded, Place B should not (signal was aborted after first fetch) 537 537 + expect(result[0].lat).toBe(41.4036); 538 538 + expect(result[1].lat).toBeUndefined(); 539 539 + expect(mockFetch).toHaveBeenCalledTimes(1); 540 540 + }); 541 541 + 542 542 + it("returns results obtained so far when signal is already aborted", async () => { 543 543 + const controller = new AbortController(); 544 544 + controller.abort(); 545 545 + 546 546 + const places = [makePlace("Place A")]; 547 547 + const result = await geocodePlaces(places, {}, controller.signal); 548 548 + 549 549 + expect(result[0].lat).toBeUndefined(); 550 550 + expect(mockFetch).not.toHaveBeenCalled(); 551 551 + }); 552 552 + 553 553 + it("aborts in-flight fetch requests when signal fires", async () => { 554 554 + vi.useFakeTimers(); 555 555 + const controller = new AbortController(); 556 556 + 557 557 + let fetchSignal: AbortSignal | undefined; 558 558 + mockFetch.mockImplementationOnce( 559 559 + (_url: string, options: { signal: AbortSignal }) => { 560 560 + fetchSignal = options.signal; 561 561 + return new Promise<Response>((resolve, reject) => { 562 562 + options.signal.addEventListener("abort", () => { 563 563 + reject( 564 564 + new DOMException("The operation was aborted.", "AbortError") 565 565 + ); 566 566 + }); 567 567 + }); 568 568 + } 569 569 + ); 570 570 + 571 571 + const places = [makePlace("Place A")]; 572 572 + const promise = geocodePlaces(places, {}, controller.signal); 573 573 + 574 574 + // Let fetch start 575 575 + await vi.advanceTimersByTimeAsync(0); 576 576 + expect(mockFetch).toHaveBeenCalledTimes(1); 577 577 + 578 578 + // Fire the external signal 579 579 + controller.abort(); 580 580 + await vi.advanceTimersByTimeAsync(0); 581 581 + 582 582 + const result = await promise; 583 583 + expect(result[0].lat).toBeUndefined(); 584 584 + expect(fetchSignal!.aborted).toBe(true); 585 585 + 586 586 + vi.useRealTimers(); 587 587 + }); 588 588 + 589 589 + it("cancels immediately during rate-limit delay, does not wait full 1100ms", async () => { 590 590 + vi.useFakeTimers(); 591 591 + const controller = new AbortController(); 592 592 + 593 593 + mockFetch 594 594 + .mockResolvedValueOnce(nominatimOk(41.4036, 2.1744)) 595 595 + .mockResolvedValueOnce(nominatimOk(48.8606, 2.3376)); 596 596 + 597 597 + const places = [makePlace("Place A"), makePlace("Place B")]; 598 598 + const promise = geocodePlaces(places, {}, controller.signal); 599 599 + 600 600 + // Let first fetch complete 601 601 + await vi.advanceTimersByTimeAsync(0); 602 602 + expect(mockFetch).toHaveBeenCalledTimes(1); 603 603 + 604 604 + // We're now in the 1100ms rate-limit delay. Abort at 500ms. 605 605 + await vi.advanceTimersByTimeAsync(500); 606 606 + controller.abort(); 607 607 + await vi.advanceTimersByTimeAsync(0); 608 608 + 609 609 + const result = await promise; 610 610 + 611 611 + // Place A was geocoded, Place B was not (aborted during delay) 612 612 + expect(result[0].lat).toBe(41.4036); 613 613 + expect(result[1].lat).toBeUndefined(); 614 614 + // Second fetch never fires 615 615 + expect(mockFetch).toHaveBeenCalledTimes(1); 616 616 + 617 617 + vi.useRealTimers(); 618 618 + }); 619 619 + }); 620 620 + 621 621 + // ─── Contract 12: Error reporting ───────────────────────────────────── 622 622 + 623 623 + describe("Contract 12: error reporting", () => { 624 624 + it("logs console.warn with [MapViewer] prefix for failures", async () => { 625 625 + mockFetch.mockRejectedValueOnce(new Error("fail")); 626 626 + 627 627 + await geocodePlaces([makePlace("Bad Place")]); 628 628 + 629 629 + expect(console.warn).toHaveBeenCalled(); 630 630 + const warnCall = (console.warn as ReturnType<typeof vi.fn>).mock.calls[0]; 631 631 + expect(warnCall[0]).toContain("[MapViewer]"); 632 632 + }); 633 633 + 634 634 + it("shows Obsidian Notice after 3 consecutive failures", async () => { 635 635 + vi.useFakeTimers(); 636 636 + mockFetch 637 637 + .mockRejectedValueOnce(new Error("fail 1")) 638 638 + .mockRejectedValueOnce(new Error("fail 2")) 639 639 + .mockRejectedValueOnce(new Error("fail 3")); 640 640 + 641 641 + const places = [ 642 642 + makePlace("Bad 1"), 643 643 + makePlace("Bad 2"), 644 644 + makePlace("Bad 3"), 645 645 + ]; 646 646 + const promise = geocodePlaces(places); 647 647 + await vi.runAllTimersAsync(); 648 648 + await promise; 649 649 + 650 650 + expect(Notice).toHaveBeenCalledWith( 651 651 + "Map Viewer: Geocoding issues — check your network connection" 652 652 + ); 653 653 + vi.useRealTimers(); 654 654 + }); 655 655 + 656 656 + it("shows Notice exactly once even with more than 3 consecutive failures", async () => { 657 657 + vi.useFakeTimers(); 658 658 + mockFetch 659 659 + .mockRejectedValueOnce(new Error("fail 1")) 660 660 + .mockRejectedValueOnce(new Error("fail 2")) 661 661 + .mockRejectedValueOnce(new Error("fail 3")) 662 662 + .mockRejectedValueOnce(new Error("fail 4")) 663 663 + .mockRejectedValueOnce(new Error("fail 5")); 664 664 + 665 665 + const places = [ 666 666 + makePlace("Bad 1"), 667 667 + makePlace("Bad 2"), 668 668 + makePlace("Bad 3"), 669 669 + makePlace("Bad 4"), 670 670 + makePlace("Bad 5"), 671 671 + ]; 672 672 + const promise = geocodePlaces(places); 673 673 + await vi.runAllTimersAsync(); 674 674 + await promise; 675 675 + 676 676 + // Notice should fire exactly once (on the 3rd failure), not on 4th and 5th 677 677 + expect(Notice).toHaveBeenCalledTimes(1); 678 678 + vi.useRealTimers(); 679 679 + }); 680 680 + 681 681 + it("does NOT show Notice for fewer than 3 consecutive failures", async () => { 682 682 + vi.useFakeTimers(); 683 683 + mockFetch 684 684 + .mockRejectedValueOnce(new Error("fail 1")) 685 685 + .mockRejectedValueOnce(new Error("fail 2")); 686 686 + 687 687 + const places = [makePlace("Bad 1"), makePlace("Bad 2")]; 688 688 + const promise = geocodePlaces(places); 689 689 + await vi.runAllTimersAsync(); 690 690 + await promise; 691 691 + 692 692 + expect(Notice).not.toHaveBeenCalled(); 693 693 + vi.useRealTimers(); 694 694 + }); 695 695 + 696 696 + it("resets consecutive failure counter on success", async () => { 697 697 + vi.useFakeTimers(); 698 698 + mockFetch 699 699 + .mockRejectedValueOnce(new Error("fail 1")) 700 700 + .mockRejectedValueOnce(new Error("fail 2")) 701 701 + .mockResolvedValueOnce(nominatimOk(41.4036, 2.1744)) // success resets counter 702 702 + .mockRejectedValueOnce(new Error("fail 3")) 703 703 + .mockRejectedValueOnce(new Error("fail 4")); 704 704 + 705 705 + const places = [ 706 706 + makePlace("Bad 1"), 707 707 + makePlace("Bad 2"), 708 708 + makePlace("Good"), 709 709 + makePlace("Bad 3"), 710 710 + makePlace("Bad 4"), 711 711 + ]; 712 712 + const promise = geocodePlaces(places); 713 713 + await vi.runAllTimersAsync(); 714 714 + await promise; 715 715 + 716 716 + // Counter was reset by "Good", so only 2 consecutive after that 717 717 + expect(Notice).not.toHaveBeenCalled(); 718 718 + vi.useRealTimers(); 719 719 + }); 720 720 + });