@sjvair/monitor-map 4.3.0 → 5.0.0-beta.0

package/src/lib/monitors/monitors.svelte.ts

@@ -1,17 +1,6 @@
-import {
-	getMonitors,
-	getMonitorsList,
-	getMonitorsMeta,
-	type MonitorData,
-	type MonitorLatestType,
-	type MonitorsMeta,
-	type SJVAirEntryLevel
-} from "@sjvair/sdk";
-import { XMap } from "@tstk/builtin-extensions";
-import { Interval } from "@tstk/utils";
-import { untrack } from "svelte";
-import { anySignal, untilAborted, type SignalOptions } from "$lib/abort";
-import type { MonitorsDataSource, MonitorsPollutant } from "./types";
+import type { MonitorData, MonitorsMeta } from "@sjvair/sdk";
+import type { MonitorsStore } from "@sjvair/map-sdk/stores";
+import { monitorsStore } from "../stores.svelte.js";
 
 export interface MonitorsInitOptions {
 	/**
@@ -22,261 +11,69 @@ export interface MonitorsInitOptions {
 	/**
 	 * Stops waiting: the returned promise rejects with the signal's reason. The shared run keeps
 	 * going for the other calls waiting on it, and is cancelled only when every call waiting on it
-	 * passed a signal and all of those aborted. An aborted call's pollutant and `autoUpdate` stay
-	 * recorded. Ignored once initialized.
+	 * passed a signal and all of those aborted. Ignored once initialized.
 	 */
 	signal?: AbortSignal;
 }
 
-/** One shared init run and the calls waiting on it. */
-interface InitRun {
-	promise: Promise<void>;
-	controller: AbortController;
-	/** Calls waiting with a signal, and how many of those aborted. */
-	signalled: number;
-	aborted: number;
-	/** Whether any call waits without a signal, which keeps the run going. */
-	unsignalled: boolean;
-}
-
-class MonitorsManager implements MonitorsDataSource {
-	autoUpdate: Interval = new Interval(async () => await this.update(), 2 * 60 * 1000);
-	initialized: boolean = $state(false);
-
-	latest: XMap<string, MonitorLatestType<"pm25" | "o3">> | null = $state(null);
-	list: Array<MonitorData> | null = $state(null);
-
-	meta: MonitorsMeta | null = $state(null);
-
-	pollutant: "pm25" | "o3" | null = $state(null);
-
-	levels: Array<SJVAirEntryLevel> | null = $derived(
-		this.meta?.entryType(this.pollutant ?? this.meta.default_pollutant).asIter.levels || null
-	);
-
-	#initRun: InitRun | null = null;
-	#requestedPollutant: MonitorsPollutant | null = null;
-	#requestedAutoUpdate = false;
-	#updateController: AbortController | null = null;
-
-	constructor() {
-		// Refetch monitors when the pollutant changes after the initial load, wherever the change
-		// comes from (Pollutant menu, URL sync, a host's own UI). Clearing first blanks the markers
-		// instead of briefly coloring them with the previous pollutant's readings.
-		let fetchedPollutant: string | null = null;
-		$effect.root(() => {
-			$effect(() => {
-				const pollutant = this.pollutant;
-				if (!this.initialized) return;
-				if (fetchedPollutant !== null && fetchedPollutant !== pollutant) {
-					untrack(() => {
-						this.list = [];
-						this.latest = null;
-						this.update();
-					});
-				}
-				fetchedPollutant = pollutant;
-			});
-		});
-	}
-
-	/**
-	 * Safe to call from several places: overlapping calls share one run, and a failed run can
-	 * be retried. An explicit "pm25"/"o3" wins over a call without one, whichever came first;
-	 * between two explicit values the most recent wins. Polling starts when the run finishes
-	 * unless every call sharing it passed `autoUpdate: false`. A no-op once initialized, so it
-	 * never restarts polling either: that is `resumeAutoUpdate()`.
-	 */
-	init(urlPollutant?: string | number | boolean, options: MonitorsInitOptions = {}): Promise<void> {
-		if (this.initialized) return Promise.resolve();
-
-		const { signal } = options;
-		// Nothing is recorded or started for a call that is already cancelled.
-		if (signal?.aborted) return Promise.reject(signal.reason);
-
-		if (options.autoUpdate !== false) this.#requestedAutoUpdate = true;
-
-		if (urlPollutant === "pm25" || urlPollutant === "o3") {
-			this.#requestedPollutant = urlPollutant;
-		}
-
-		const run = (this.#initRun ??= this.#startInitRun());
-
-		if (!signal) {
-			run.unsignalled = true;
-			return run.promise;
-		}
-
-		run.signalled++;
-		const onAbort = () => {
-			run.aborted++;
-			if (!run.unsignalled && run.aborted === run.signalled) this.#abortInitRun(run);
-		};
-		signal.addEventListener("abort", onAbort, { once: true });
-		const cleanup = () => signal.removeEventListener("abort", onAbort);
-		run.promise.then(cleanup, cleanup);
-
-		return untilAborted(run.promise, signal);
-	}
-
-	#startInitRun(): InitRun {
-		const controller = new AbortController();
-		const run: InitRun = {
-			promise: this.#runInit(controller.signal).finally(() => {
-				if (this.#initRun === run) this.#clearInitRun();
-			}),
-			controller,
-			signalled: 0,
-			aborted: 0,
-			unsignalled: false
-		};
-		return run;
-	}
-
+/**
+ * The live monitors data, as hosts have used it since 4.x: a thin view over map-sdk's monitors
+ * store, which owns the data, the shared init and the polling.
+ */
+export interface MonitorsManager {
+	/** Loads the monitors. Only "pm25" and "o3" pass through; anything else means the default. */
+	init(pollutant?: unknown, options?: MonitorsInitOptions): Promise<void>;
+	readonly initialized: boolean;
+	readonly meta: MonitorsMeta | null;
 	/**
-	 * Cancels a run nobody is waiting on. It is detached at once, so a call arriving before its
-	 * rejection settles starts a fresh run instead of joining the cancelled one.
+	 * Every monitor, or null until initialized. The same array between reads until the store's
+	 * monitors are replaced.
 	 */
-	#abortInitRun(run: InitRun): void {
-		if (this.#initRun !== run) return;
-		this.#clearInitRun();
-		run.controller.abort();
-	}
-
-	#clearInitRun(): void {
-		this.#initRun = null;
-		this.#requestedPollutant = null;
-		this.#requestedAutoUpdate = false;
-	}
-
-	async #runInit(signal: AbortSignal): Promise<void> {
-		// The pollutant the latest readings were requested for.
-		let fetchedPollutant = this.#requestedPollutant;
-
-		const metaRequest = getMonitorsMeta({ signal });
-		const listAndMeta = Promise.all([getMonitorsList({ signal }), metaRequest]).then(
-			([list, meta]) => {
-				if (signal.aborted) throw signal.reason;
-				this.list = list;
-				this.meta = meta;
-				return meta;
-			}
-		);
-		// The latest readings only need the pollutant, so they never wait for the list. An explicit
-		// pollutant may still arrive before meta does, in which case the default is never fetched.
-		const latestRequest = fetchedPollutant
-			? getMonitorsLatestMap(fetchedPollutant, signal)
-			: metaRequest.then((meta) => {
-					const pollutant = this.#requestedPollutant ?? meta.default_pollutant;
-					fetchedPollutant = pollutant;
-					return getMonitorsLatestMap(pollutant, signal);
-				});
-
-		// One Promise.all so a failure in either never leaves the other unhandled.
-		const [meta, firstLatest] = await Promise.all([listAndMeta, latestRequest]);
-		let latest = firstLatest;
-
-		// An explicit pollutant may have arrived while the requests above were in flight.
-		let wanted = this.#requestedPollutant ?? meta.default_pollutant;
-		while (wanted !== fetchedPollutant) {
-			latest = await getMonitorsLatestMap(wanted, signal);
-			fetchedPollutant = wanted;
-			wanted = this.#requestedPollutant ?? meta.default_pollutant;
-		}
-
-		// Cancelled while a request that ignores the signal was settling: leave state to the next run.
-		if (signal.aborted) throw signal.reason;
-
-		this.pollutant = fetchedPollutant;
-		this.latest = latest;
-		if (this.#requestedAutoUpdate) this.autoUpdate.start();
-		this.initialized = true;
-	}
-
-	/**
-	 * Starts polling when it is not running: after something stopped it (MonitorMapLayout stops
-	 * it on destroy) or after an init that opted out of it. Refreshes first since the data may
-	 * be stale. A no-op before init or while polling.
-	 */
-	resumeAutoUpdate(): void {
-		if (!this.initialized || this.autoUpdate.isActive) return;
-
-		this.update().catch(console.error);
-		this.autoUpdate.start();
-	}
-
-	/**
-	 * Refreshes the list and the latest readings. Starting an update aborts the previous
-	 * in-flight one, which then resolves without touching state. Pass `signal` to cancel from the
-	 * outside: that rejects with the signal's reason.
-	 */
-	async update(options: SignalOptions = {}): Promise<void> {
-		if (!this.initialized) return;
-
-		// Nothing has started yet, so an in-flight update is left alone.
-		if (options.signal?.aborted) throw options.signal.reason;
-
-		const supersededInFlight = this.#updateController !== null;
-		this.#updateController?.abort();
-		const controller = new AbortController();
-		this.#updateController = controller;
-		const combined = anySignal(controller.signal, options.signal);
-
-		// The caller cancelled this update. If it is still the latest and it cut off an update that
-		// was in flight, that update's data is lost too, so refresh again without a signal.
-		const callerAborted = (signal: AbortSignal) => {
-			if (supersededInFlight && this.#updateController === controller) {
-				this.update().catch(console.error);
-			}
-			return signal.reason;
-		};
-
-		// Set once callerAborted has run, so the catch below does not run it a second time.
-		let abortedError: unknown;
-
-		try {
-			const pollutant = this.pollutant;
-			const [list, latest] = await Promise.all([
-				getMonitorsList({ signal: combined.signal }),
-				getMonitorsLatestMap(pollutant || this.meta?.default_pollutant || "pm25", combined.signal)
-			]);
-
-			// Superseded or cancelled while the requests were settling.
-			if (options.signal?.aborted) throw (abortedError = callerAborted(options.signal));
-			if (controller.signal.aborted) return;
-
-			// The pollutant changed while this was in flight: these readings belong to the previous
-			// one, and the change has already started its own update.
-			if (this.pollutant !== pollutant) return;
-
-			this.list = list;
-			this.latest = latest;
-		} catch (error) {
-			// The caller's own abort rejects with its reason. A superseded update resolves quietly.
-			if (options.signal?.aborted)
-				throw error === abortedError ? error : callerAborted(options.signal);
-			if (controller.signal.aborted) return;
-			throw error;
-		} finally {
-			combined.dispose();
-			if (this.#updateController === controller) this.#updateController = null;
-		}
-	}
+	readonly list: MonitorData[] | null;
+	/** The pollutant the readings are for, or null before init. */
+	readonly pollutant: string | null;
+	setPollutant(pollutant: "pm25" | "o3"): void;
+	update(options?: { signal?: AbortSignal }): Promise<void>;
+	resumeAutoUpdate(): void;
+	pauseAutoUpdate(): void;
+	/** The store underneath, for map-sdk plugins and stores. */
+	readonly store: MonitorsStore;
 }
 
-async function getMonitorsLatestMap(
-	pollutant: "pm25" | "o3",
-	signal?: AbortSignal
-): Promise<XMap<string, MonitorLatestType<"pm25" | "o3">>> {
-	const monitors = await getMonitors(pollutant, undefined, { signal });
-	const latest = new XMap<string, MonitorLatestType<"pm25" | "o3">>();
-
-	for (const monitor of monitors) {
-		latest.set(monitor.id, monitor);
-	}
+function initPollutant(pollutant: unknown): "pm25" | "o3" | undefined {
+	return pollutant === "pm25" || pollutant === "o3" ? pollutant : undefined;
+}
 
-	return latest;
+export function createMonitorsManager(store: MonitorsStore): MonitorsManager {
+	// The list built from `store.monitors`, which the store replaces rather than mutates.
+	let listFrom: MonitorsStore["monitors"] | null = null;
+	let list: MonitorData[] = [];
+	return {
+		init: (pollutant, options) => store.init(initPollutant(pollutant), options),
+		get initialized() {
+			return store.initialized;
+		},
+		get meta() {
+			return store.meta;
+		},
+		get list() {
+			if (!store.initialized) return null;
+			const monitors = store.monitors;
+			if (monitors !== listFrom) {
+				listFrom = monitors;
+				list = [...monitors.values()];
+			}
+			return list;
+		},
+		get pollutant() {
+			return store.entryType;
+		},
+		setPollutant: (pollutant) => store.entryTypeFor(pollutant),
+		update: (options) => store.update(options),
+		resumeAutoUpdate: () => store.resumeAutoUpdate(),
+		pauseAutoUpdate: () => store.pauseAutoUpdate(),
+		store
+	};
 }
 
-export const monitorsManager = new MonitorsManager();
-export type { MonitorsManager };
+export const monitorsManager: MonitorsManager = createMonitorsManager(monitorsStore);

package/src/lib/monitors/retry-load.ts

@@ -0,0 +1,14 @@
+import type { monitorsStore } from "$lib/stores.svelte.js";
+
+/**
+ * Retries a failed initial monitors load through the store's own `status.retry()`, which repeats
+ * the failed `init()` call. When the status is not an error (nothing to retry), runs `fallback`.
+ */
+export function retryMonitorsLoad(
+	store: { dataSource: Pick<typeof monitorsStore.dataSource, "status"> },
+	fallback: () => void
+) {
+	const { status } = store.dataSource;
+	if (status.state === "error") status.retry();
+	else fallback();
+}

package/src/lib/monitors/types.ts

@@ -1,48 +1,2 @@
-import type { Feature, Geometry } from "geojson";
-import type { MonitorLatestType, MonitorsMeta, MonitorType, SJVAirEntryLevel } from "@sjvair/sdk";
-import type { MapGeoJSONFeature } from "@maptiler/sdk";
-import type { XMap } from "@tstk/builtin-extensions";
-
-export type MonitorMapFeature = Feature<Geometry, MonitorMarkerProperties>;
-
-export interface MonitorClusterMapFeature extends MapGeoJSONFeature {
-	properties: MonitorClusterMarkerProperties;
-}
-
-export interface MonitorMarkerProperties {
-	icon: string;
-	id: string;
-	is_active: boolean;
-	is_sjvair?: boolean;
-	location: string;
-	name: string;
-	order: number;
-	type: MonitorType;
-	value: string;
-}
-
-export interface MonitorClusterMarkerProperties {
-	cluster: true;
-	cluster_id: number;
-	point_count: number;
-	point_count_abbreviated: string | number;
-	sumValues: number;
-	countValues: number;
-}
-
-/** The pollutants monitorsMapIntegration/monitorsIconManager can render. */
+/** The pollutants the map can show. */
 export type MonitorsPollutant = "pm25" | "o3";
-
-/**
- * The reactive data a monitors map display needs: which monitors exist, their
- * per-monitor "latest" value for the active pollutant, and the entry-level metadata
- * used to color icons. `monitorsManager` (live, auto-polling) is the default
- * implementation; a host app can supply its own (e.g. one backed by historical
- * summaries instead of live readings) to reuse the map rendering with different data.
- */
-export interface MonitorsDataSource {
-	readonly meta: MonitorsMeta | null;
-	readonly pollutant: MonitorsPollutant | null;
-	readonly latest: XMap<string, MonitorLatestType<MonitorsPollutant>> | null;
-	readonly levels: Array<SJVAirEntryLevel> | null;
-}

package/src/lib/options/map-option-defaults.ts

@@ -1,10 +1,22 @@
-import type { MonitorsPollutant } from "$lib/monitors/types";
-import { applyPollutantSelection, type PollutantTargets } from "./pollutant-param";
+/** The map options the toolbar edits; `mapOptions` holds the live copy. */
+export interface MapOptions {
+	/** False for the Pollutant menu's "None": no monitors (or collocation sites) on the map. */
+	monitorsOn: boolean;
+	/** Which monitor types draw, keyed by server type; a type with no key never draws. */
+	monitorTypes: Record<string, boolean>;
+	inactive: boolean;
+	inside: boolean;
+	/** Monitors' and EV chargers' clustering. */
+	clustered: boolean;
+	collocationSites: boolean;
+	/** HMS smoke and fire together. */
+	fireAndSmoke: boolean;
+	evStations: boolean;
+	evLevels: { lvl2: boolean; lvl3: boolean };
+	wind: boolean;
+}
 
-/**
- * Defaults restored by "Reset Map Options". Keep in sync with the constructor defaults in each
- * integration (monitors/EV display options, `enabled`, `clustered`) so a reset matches a fresh load.
- */
+/** Defaults restored by "Reset Map Options"; a fresh load starts at them too. */
 export const MAP_OPTION_DEFAULTS = {
 	monitorTypes: {
 		airnow: true,
@@ -13,59 +25,24 @@ export const MAP_OPTION_DEFAULTS = {
 		bam1022: true,
 		airgradient: true,
 		purpleair: true,
-		vozbox: true,
-		inactive: false,
-		inside: false
+		vozbox: true
 	},
+	inactive: false,
+	inside: false,
 	clustered: true,
 	collocationSites: false,
 	fireAndSmoke: true,
 	evStations: false,
 	evLevels: { lvl2: true, lvl3: true },
 	wind: false
-} as const;
-
-type Toggle = { enabled: boolean };
-type Option = { value: boolean };
-
-export interface MapOptionTargets extends PollutantTargets {
-	integration: PollutantTargets["integration"] & {
-		clustered: boolean;
-		displayOptions: Record<string, Option>;
+} as const satisfies Omit<MapOptions, "monitorsOn">;
+
+/** A fresh copy of the defaults, with monitors on. */
+export function defaultMapOptions(): MapOptions {
+	return {
+		...MAP_OPTION_DEFAULTS,
+		monitorsOn: true,
+		monitorTypes: { ...MAP_OPTION_DEFAULTS.monitorTypes },
+		evLevels: { ...MAP_OPTION_DEFAULTS.evLevels }
 	};
-	collocationSites: Toggle;
-	hmsFire: Toggle;
-	hmsSmoke: Toggle;
-	evStations: Toggle & { clustered: boolean; displayOptions: { lvl2: Option; lvl3: Option } };
-	wind: Toggle;
-	mapStyle: { reset(): void };
-}
-
-export function applyMapOptionDefaults(
-	targets: MapOptionTargets,
-	defaultPollutant: MonitorsPollutant | null
-): void {
-	if (defaultPollutant) {
-		applyPollutantSelection(defaultPollutant, targets);
-	} else {
-		targets.integration.enabled = true;
-	}
-
-	for (const [key, value] of Object.entries(MAP_OPTION_DEFAULTS.monitorTypes)) {
-		const option = targets.integration.displayOptions[key];
-		if (option) option.value = value;
-	}
-	targets.integration.clustered = MAP_OPTION_DEFAULTS.clustered;
-
-	targets.collocationSites.enabled = MAP_OPTION_DEFAULTS.collocationSites;
-	targets.hmsFire.enabled = MAP_OPTION_DEFAULTS.fireAndSmoke;
-	targets.hmsSmoke.enabled = MAP_OPTION_DEFAULTS.fireAndSmoke;
-
-	targets.evStations.enabled = MAP_OPTION_DEFAULTS.evStations;
-	targets.evStations.clustered = MAP_OPTION_DEFAULTS.clustered;
-	targets.evStations.displayOptions.lvl2.value = MAP_OPTION_DEFAULTS.evLevels.lvl2;
-	targets.evStations.displayOptions.lvl3.value = MAP_OPTION_DEFAULTS.evLevels.lvl3;
-
-	targets.wind.enabled = MAP_OPTION_DEFAULTS.wind;
-	targets.mapStyle.reset();
 }

package/src/lib/options/map-options.svelte.ts

@@ -0,0 +1,30 @@
+import { monitorsManager } from "../monitors/monitors.svelte.js";
+import type { MonitorsPollutant } from "../monitors/types";
+import { defaultMapOptions, MAP_OPTION_DEFAULTS, type MapOptions } from "./map-option-defaults";
+
+export type { MapOptions } from "./map-option-defaults";
+
+/**
+ * The toolbar's map options. Module-level, so they survive the layout remounting (as the 4.x
+ * integrations' state did); the layout turns them into map-sdk plugins.
+ */
+export const mapOptions: MapOptions = $state(defaultMapOptions());
+
+/**
+ * "Reset Map Options": every option back to its default, monitors on, and the pollutant back to
+ * `defaultPollutant` (the server's default; null before the meta loads leaves it as it is).
+ */
+export function resetMapOptions(defaultPollutant: MonitorsPollutant | null): void {
+	if (defaultPollutant) monitorsManager.setPollutant(defaultPollutant);
+	mapOptions.monitorsOn = true;
+	Object.assign(mapOptions.monitorTypes, MAP_OPTION_DEFAULTS.monitorTypes);
+	mapOptions.inactive = MAP_OPTION_DEFAULTS.inactive;
+	mapOptions.inside = MAP_OPTION_DEFAULTS.inside;
+	mapOptions.clustered = MAP_OPTION_DEFAULTS.clustered;
+	mapOptions.collocationSites = MAP_OPTION_DEFAULTS.collocationSites;
+	mapOptions.fireAndSmoke = MAP_OPTION_DEFAULTS.fireAndSmoke;
+	mapOptions.evStations = MAP_OPTION_DEFAULTS.evStations;
+	mapOptions.evLevels.lvl2 = MAP_OPTION_DEFAULTS.evLevels.lvl2;
+	mapOptions.evLevels.lvl3 = MAP_OPTION_DEFAULTS.evLevels.lvl3;
+	mapOptions.wind = MAP_OPTION_DEFAULTS.wind;
+}

package/src/lib/options/menus/LayersMenu.svelte

@@ -4,43 +4,31 @@
 	import CheckboxRow from "../rows/CheckboxRow.svelte";
 	import SubmenuRow from "../rows/SubmenuRow.svelte";
 	import MarkerIcon from "../rows/MarkerIcon.svelte";
-	import { hmsFireMapIntegration } from "$lib/hms/hms-fire-map-integration.svelte";
-	import { hmsSmokeMapIntegration } from "$lib/hms/hms-smoke-map-integration.svelte";
-	import { evStationsMapIntegration } from "$lib/ev-stations/ev-stations-map-integration.svelte";
-
-	const levels = $derived(evStationsMapIntegration.displayOptions);
+	import { mapOptions } from "../map-options.svelte.js";
+	import { ROW_ICONS } from "../row-icons";
 </script>
 
 <OptionsMenu id="layers" label="Layers">
 	{#snippet icon()}
 		<LayersIcon size={20} color="#708090" />
 	{/snippet}
-	<CheckboxRow
-		label="Fire & Smoke"
-		bind:checked={
-			() => hmsFireMapIntegration.enabled && hmsSmokeMapIntegration.enabled,
-			(value) => {
-				hmsFireMapIntegration.enabled = value;
-				hmsSmokeMapIntegration.enabled = value;
-			}
-		}
-	>
+	<CheckboxRow label="Fire & Smoke" bind:checked={mapOptions.fireAndSmoke}>
 		{#snippet icon()}
 			<FlameIcon size={18} color="#ff4500" />
 		{/snippet}
 	</CheckboxRow>
-	<SubmenuRow label="EV Chargers" bind:checked={evStationsMapIntegration.enabled}>
+	<SubmenuRow label="EV Chargers" bind:checked={mapOptions.evStations}>
 		{#snippet icon()}
 			<EvChargerIcon size={18} color="#708090" />
 		{/snippet}
-		<CheckboxRow label="Level 2" bind:checked={evStationsMapIntegration.displayOptions.lvl2.value}>
+		<CheckboxRow label="Level 2" bind:checked={mapOptions.evLevels.lvl2}>
 			{#snippet icon()}
-				<MarkerIcon icon={levels.lvl2.icon} class="w-5" />
+				<MarkerIcon svg={ROW_ICONS.evLevel2} class="w-5" />
 			{/snippet}
 		</CheckboxRow>
-		<CheckboxRow label="Level 3" bind:checked={evStationsMapIntegration.displayOptions.lvl3.value}>
+		<CheckboxRow label="Level 3" bind:checked={mapOptions.evLevels.lvl3}>
 			{#snippet icon()}
-				<MarkerIcon icon={levels.lvl3.icon} class="w-5" />
+				<MarkerIcon svg={ROW_ICONS.evLevel3} class="w-5" />
 			{/snippet}
 		</CheckboxRow>
 	</SubmenuRow>