@sjvair/map-sdk 0.0.0-stage → 0.1.0-beta.2

package/dist/stores/abort.js

@@ -0,0 +1,52 @@
+// Ported from monitor-map (src/lib/abort.ts): the building blocks for cancelling requests.
+/**
+ * A signal that aborts as soon as any input does, with that input's reason. Already aborted if
+ * any input is. Undefined inputs are ignored. Call `dispose()` to drop the listeners.
+ */
+export function anySignal(...signals) {
+    const controller = new AbortController();
+    const cleanups = [];
+    const dispose = () => {
+        for (const cleanup of cleanups.splice(0))
+            cleanup();
+    };
+    for (const input of signals) {
+        if (!input)
+            continue;
+        if (input.aborted) {
+            controller.abort(input.reason);
+            dispose();
+            break;
+        }
+        const onAbort = () => {
+            controller.abort(input.reason);
+            dispose();
+        };
+        input.addEventListener("abort", onAbort, { once: true });
+        cleanups.push(() => input.removeEventListener("abort", onAbort));
+    }
+    return { signal: controller.signal, dispose };
+}
+/**
+ * Settles like `promise`, unless `signal` aborts first, in which case it rejects with
+ * `signal.reason`. The inner promise's later outcome is swallowed.
+ */
+export function untilAborted(promise, signal) {
+    if (!signal)
+        return promise;
+    if (signal.aborted) {
+        promise.catch(() => { });
+        return Promise.reject(signal.reason);
+    }
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(signal.reason);
+        signal.addEventListener("abort", onAbort, { once: true });
+        promise.then((value) => {
+            signal.removeEventListener("abort", onAbort);
+            resolve(value);
+        }, (error) => {
+            signal.removeEventListener("abort", onAbort);
+            reject(error);
+        });
+    });
+}

package/dist/stores/collocation-store.svelte.d.ts

@@ -0,0 +1,25 @@
+import type { CollocationFeatureProperties, DataSource, DataStatus } from "../data/types.js";
+import type { SignalOptions } from "./abort.js";
+import type { MonitorsStore } from "./monitors-store.svelte.js";
+export interface CollocationSitesStoreOptions {
+    /** The monitors and readings the sites join to; its entry type's scale colors them. */
+    monitors: MonitorsStore;
+}
+export interface CollocationSitesStore {
+    /** `loading` until the sites load, then `ready` or `error` (with `retry`). */
+    readonly status: DataStatus;
+    /**
+     * The sites for `collocationSitesPlugin`, each at its own position. Readings follow the
+     * monitors store's polling; a monitor missing from it gives null readings.
+     */
+    readonly dataSource: DataSource<CollocationFeatureProperties>;
+    /**
+     * Loads the sites once. Overlapping calls share one run, and a failed run can be retried. A
+     * caller's abort rejects only that caller; the run stops when every caller aborted. A no-op
+     * once loaded. It doesn't load the monitors store: init that too.
+     */
+    init(options?: SignalOptions): Promise<void>;
+    /** Cancels the in-flight request. A disposed store does nothing. */
+    dispose(): void;
+}
+export declare function createCollocationSitesStore(options: CollocationSitesStoreOptions): CollocationSitesStore;

package/dist/stores/collocation-store.svelte.js

@@ -0,0 +1,72 @@
+import { getCollocationSites } from "@sjvair/sdk";
+import { encodeRef } from "../data/refs.js";
+import { createLoadOnce } from "./load-once.svelte.js";
+function join(sites, monitors) {
+    const list = monitors.monitors;
+    const latest = monitors.latest;
+    const features = [];
+    for (const site of sites) {
+        if (!site.position)
+            continue;
+        const reference = list.get(site.reference_id);
+        const colocated = list.get(site.colocated_id);
+        const referenceReading = latest.get(site.reference_id);
+        const colocatedReading = latest.get(site.colocated_id);
+        features.push({
+            type: "Feature",
+            geometry: { type: "Point", coordinates: site.position.coordinates },
+            properties: {
+                refKey: encodeRef({ kind: "feature", id: site.id }),
+                name: site.name,
+                value: referenceReading?.value ?? null,
+                timestamp: referenceReading?.timestamp ?? null,
+                // A missing reference monitor draws as a sensor in the neutral color, not inactive
+                // gray.
+                type: reference?.type ?? "",
+                isActive: reference?.is_active ?? true,
+                isSjvair: reference?.is_sjvair ?? false,
+                location: reference?.location === "inside" ? "inside" : "outside",
+                referenceName: reference?.name ?? null,
+                colocatedId: site.colocated_id,
+                colocatedName: colocated?.name ?? null,
+                colocatedType: colocated?.type ?? null,
+                colocatedValue: colocatedReading?.value ?? null,
+                colocatedTimestamp: colocatedReading?.timestamp ?? null
+            }
+        });
+    }
+    return { type: "FeatureCollection", features };
+}
+export function createCollocationSitesStore(options) {
+    const { monitors } = options;
+    const loader = createLoadOnce((signal) => getCollocationSites({ signal }));
+    // Rebuilt only when an input changes, so every reader shares one object. Reading the inputs
+    // in the getter keeps it reactive to the monitors store's state.
+    let cached = null;
+    return {
+        get status() {
+            return loader.status;
+        },
+        dataSource: {
+            get status() {
+                return loader.status;
+            },
+            get features() {
+                const sites = loader.value;
+                if (sites === null)
+                    return null;
+                const list = monitors.monitors;
+                const latest = monitors.latest;
+                if (cached?.sites !== sites || cached.list !== list || cached.latest !== latest) {
+                    cached = { sites, list, latest, features: join(sites, monitors) };
+                }
+                return cached.features;
+            },
+            get scale() {
+                return monitors.dataSource.scale;
+            }
+        },
+        init: (initOptions) => loader.init(initOptions),
+        dispose: () => loader.dispose()
+    };
+}

package/dist/stores/hms-stores.svelte.d.ts

@@ -0,0 +1,35 @@
+import { type MessageProvider } from "../data/messages.js";
+import type { DataSource, DataStatus } from "../data/types.js";
+import type { SignalOptions } from "./abort.js";
+export interface HmsStoreOptions {
+    /** Names features ("Smoke", "Fire detection"). Default: the built-in English messages. */
+    messages?: MessageProvider;
+}
+export interface HmsSmokeStore {
+    /** `loading` until loaded, then `ready` (also when today has no plumes) or `error`. */
+    readonly status: DataStatus;
+    /** Today's plumes for `hmsSmokePlugin`; each feature's `value` is its density key. */
+    readonly dataSource: DataSource;
+    /**
+     * Loads today's smoke once. Overlapping calls share one run, and a failed run can be
+     * retried. A caller's abort rejects only that caller; the run stops when every caller
+     * aborted. A no-op once loaded.
+     */
+    init(options?: SignalOptions): Promise<void>;
+    /** Cancels the in-flight request. A disposed store does nothing. */
+    dispose(): void;
+}
+export interface HmsFireStore {
+    /** `loading` until loaded, then `ready` (also when today has no fires) or `error`. */
+    readonly status: DataStatus;
+    /** Nearby detections merged (`groupFires`), for `hmsFirePlugin`; `value` is the mean FRP. */
+    readonly groups: DataSource;
+    /** Each detection (`cleanFires`), for `hmsFirePlugin`; `value` is its FRP. */
+    readonly hotspots: DataSource;
+    /** As `HmsSmokeStore.init`. */
+    init(options?: SignalOptions): Promise<void>;
+    /** Cancels the in-flight request. A disposed store does nothing. */
+    dispose(): void;
+}
+export declare function createHmsSmokeStore(options?: HmsStoreOptions): HmsSmokeStore;
+export declare function createHmsFireStore(options?: HmsStoreOptions): HmsFireStore;

package/dist/stores/hms-stores.svelte.js

@@ -0,0 +1,97 @@
+import { getHMSFire, getHMSSmoke } from "@sjvair/sdk";
+import { encodeRef } from "../data/refs.js";
+import { defaultMessages } from "../data/messages.js";
+import { cleanFires, groupFires } from "../presets/fire-groups.js";
+import { createLoadOnce } from "./load-once.svelte.js";
+const SMOKE_SCALE = { dataset: "hms-smoke", entryType: "smoke-density" };
+const FIRE_SCALE = { dataset: "hms-fire", entryType: "fire-frp" };
+/** A source over a loader's value; `features` stays null until it loads. */
+function sourceOf(loader, scale, pick) {
+    // Built once per loaded value, so every reader shares one object.
+    let cached = null;
+    return {
+        get status() {
+            return loader.status;
+        },
+        get features() {
+            const value = loader.value;
+            if (value === null)
+                return null;
+            if (cached?.value !== value)
+                cached = { value, features: pick(value) };
+            return cached.features;
+        },
+        scale
+    };
+}
+export function createHmsSmokeStore(options = {}) {
+    const messages = options.messages ?? defaultMessages;
+    const loader = createLoadOnce(async (signal) => {
+        const smoke = await getHMSSmoke(undefined, { signal });
+        const name = messages("mapsdk_hms_smoke_name");
+        const features = smoke.map((plume) => ({
+            type: "Feature",
+            geometry: plume.geometry,
+            properties: {
+                refKey: encodeRef({ kind: "feature", id: plume.id }),
+                name,
+                value: plume.density
+            }
+        }));
+        return { type: "FeatureCollection", features };
+    });
+    return {
+        get status() {
+            return loader.status;
+        },
+        dataSource: sourceOf(loader, SMOKE_SCALE, (collection) => collection),
+        init: (initOptions) => loader.init(initOptions),
+        dispose: () => loader.dispose()
+    };
+}
+export function createHmsFireStore(options = {}) {
+    const messages = options.messages ?? defaultMessages;
+    const loader = createLoadOnce(async (signal) => {
+        const fires = await getHMSFire(undefined, { signal });
+        const detections = fires.map((fire) => ({
+            id: fire.id,
+            coordinates: fire.geometry.coordinates,
+            frp: fire.frp,
+            timestamp: fire.timestamp
+        }));
+        const detection = messages("mapsdk_hms_fire_detection");
+        const hotspots = cleanFires(detections).map((fire) => ({
+            type: "Feature",
+            geometry: { type: "Point", coordinates: fire.coordinates },
+            properties: {
+                refKey: encodeRef({ kind: "feature", id: fire.id }),
+                name: detection,
+                value: fire.frp
+            }
+        }));
+        const groups = groupFires(detections).map((group) => ({
+            type: "Feature",
+            geometry: { type: "Point", coordinates: group.coordinates },
+            properties: {
+                refKey: encodeRef({ kind: "feature", id: group.id }),
+                name: group.count === 1
+                    ? detection
+                    : messages("mapsdk_hms_fire_detections", { count: group.count }),
+                value: group.avgFrp
+            }
+        }));
+        return {
+            hotspots: { type: "FeatureCollection", features: hotspots },
+            groups: { type: "FeatureCollection", features: groups }
+        };
+    });
+    return {
+        get status() {
+            return loader.status;
+        },
+        groups: sourceOf(loader, FIRE_SCALE, (value) => value.groups),
+        hotspots: sourceOf(loader, FIRE_SCALE, (value) => value.hotspots),
+        init: (initOptions) => loader.init(initOptions),
+        dispose: () => loader.dispose()
+    };
+}

package/dist/stores/index.d.ts

@@ -0,0 +1,4 @@
+export { createMonitorsStore, type MonitorReading, type MonitorsInitOptions, type MonitorsListItem, type MonitorsStore, type MonitorsStoreOptions } from "./monitors-store.svelte.js";
+export { cleanFires, type FireDetection } from "../presets/fire-groups.js";
+export { createHmsFireStore, createHmsSmokeStore, type HmsFireStore, type HmsSmokeStore, type HmsStoreOptions } from "./hms-stores.svelte.js";
+export { createCollocationSitesStore, type CollocationSitesStore, type CollocationSitesStoreOptions } from "./collocation-store.svelte.js";

package/dist/stores/index.js

@@ -0,0 +1,4 @@
+export { createMonitorsStore } from "./monitors-store.svelte.js";
+export { cleanFires } from "../presets/fire-groups.js";
+export { createHmsFireStore, createHmsSmokeStore } from "./hms-stores.svelte.js";
+export { createCollocationSitesStore } from "./collocation-store.svelte.js";

package/dist/stores/load-once.svelte.d.ts

@@ -0,0 +1,25 @@
+import type { DataStatus } from "../data/types.js";
+import { type SignalOptions } from "./abort.js";
+export interface LoadOnceInitOptions extends SignalOptions {
+    /**
+     * 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. Ignored once loaded.
+     */
+    signal?: AbortSignal;
+}
+export interface LoadOnce<T> {
+    /** `loading` until the first load succeeds; `error` (with `retry`) after a failed run. */
+    readonly status: DataStatus;
+    /** The loaded value, or null before the first successful load. */
+    readonly value: T | null;
+    /**
+     * Loads once. Overlapping calls share one run, a failed run can be retried (call again, or
+     * `status.retry()`), and a no-op once loaded or disposed.
+     */
+    init(options?: LoadOnceInitOptions): Promise<void>;
+    /** Cancels the in-flight run. A disposed loader does nothing. */
+    dispose(): void;
+}
+/** A loader that fetches once with `load`. Nothing is fetched until `init()`. */
+export declare function createLoadOnce<T>(load: (signal: AbortSignal) => Promise<T>): LoadOnce<T>;

package/dist/stores/load-once.svelte.js

@@ -0,0 +1,93 @@
+import { untilAborted } from "./abort.js";
+class LoadOnceCore {
+    status = $state.raw({ state: "loading" });
+    value = $state.raw(null);
+    #load;
+    #run = null;
+    #loaded = false;
+    #disposed = false;
+    constructor(load) {
+        this.#load = load;
+    }
+    init(options = {}) {
+        if (this.#loaded || this.#disposed)
+            return Promise.resolve();
+        const { signal } = options;
+        if (signal?.aborted)
+            return Promise.reject(signal.reason);
+        const run = (this.#run ??= this.#start());
+        if (!signal) {
+            run.unsignalled = true;
+            return run.promise;
+        }
+        run.signalled++;
+        const onAbort = () => {
+            run.aborted++;
+            if (!run.unsignalled && run.aborted === run.signalled)
+                this.#abort(run);
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+        const cleanup = () => signal.removeEventListener("abort", onAbort);
+        run.promise.then(cleanup, cleanup);
+        return untilAborted(run.promise, signal);
+    }
+    #start() {
+        const controller = new AbortController();
+        if (this.status.state !== "loading")
+            this.status = { state: "loading" };
+        const run = {
+            // Cancelling rejects at once, even while a request that ignores the signal is pending.
+            promise: untilAborted(this.#fetch(controller.signal), controller.signal).then(() => {
+                if (this.#run === run)
+                    this.#run = null;
+            }, (error) => {
+                if (this.#run === run)
+                    this.#run = null;
+                if (!controller.signal.aborted) {
+                    this.status = {
+                        state: "error",
+                        error,
+                        retry: () => {
+                            this.init().catch(() => { });
+                        }
+                    };
+                }
+                throw error;
+            }),
+            controller,
+            signalled: 0,
+            aborted: 0,
+            unsignalled: false
+        };
+        return run;
+    }
+    async #fetch(signal) {
+        const value = await this.#load(signal);
+        // Cancelled while a request that ignores the signal was settling: leave state to the next
+        // run.
+        if (signal.aborted)
+            throw signal.reason;
+        this.value = value;
+        this.status = { state: "ready" };
+        this.#loaded = true;
+    }
+    /**
+     * 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.
+     */
+    #abort(run) {
+        if (this.#run !== run)
+            return;
+        this.#run = null;
+        run.controller.abort();
+    }
+    dispose() {
+        this.#disposed = true;
+        if (this.#run)
+            this.#abort(this.#run);
+    }
+}
+/** A loader that fetches once with `load`. Nothing is fetched until `init()`. */
+export function createLoadOnce(load) {
+    return new LoadOnceCore(load);
+}

package/dist/stores/monitors-store.svelte.d.ts

@@ -0,0 +1,85 @@
+import { type MonitorData, type MonitorsMeta } from "@sjvair/sdk";
+import type { DataSource, MonitorFeatureProperties } from "../data/types.js";
+import { type SignalOptions } from "./abort.js";
+/** A monitor from the monitors list. */
+export type MonitorsListItem = MonitorData;
+/** A monitor's latest reading for the store's entry type. */
+export interface MonitorReading {
+    /** Null when the server sent no numeric value. */
+    value: number | null;
+    /** When the reading was taken (ISO 8601). */
+    timestamp: string;
+}
+export interface MonitorsStoreOptions {
+    /** How often polling refreshes the data, in milliseconds. Default 120 000 (2 minutes). */
+    pollIntervalMs?: number;
+}
+export interface MonitorsInitOptions extends SignalOptions {
+    /**
+     * Start polling once the initial load finishes. Defaults to true; pass false to load the data
+     * without showing a map (`resumeAutoUpdate()` starts polling later).
+     */
+    autoUpdate?: boolean;
+    /**
+     * 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 entry type and `autoUpdate` stay
+     * recorded. Ignored once initialized.
+     */
+    signal?: AbortSignal;
+}
+export interface MonitorsStore {
+    /** True once the first load finished. */
+    readonly initialized: boolean;
+    /** The entry type the readings are for, such as "pm25". Null before init. */
+    readonly entryType: string | null;
+    /** Every monitor, by id, from the monitors list. */
+    readonly monitors: ReadonlyMap<string, MonitorsListItem>;
+    /** Each monitor's latest reading for `entryType`, by monitor id. */
+    readonly latest: ReadonlyMap<string, MonitorReading>;
+    /** The entry types the server publishes on the map (monitors meta `available_pollutants`). */
+    readonly availableEntryTypes: readonly string[];
+    /** The monitors meta from init (the SDK's `MonitorsMeta`), or null before init. Read-only. */
+    readonly meta: MonitorsMeta | null;
+    /**
+     * Sets the entry type. Once initialized, an entry type the server doesn't list falls back to
+     * its default, and the readings blank at once (so markers never show the previous entry
+     * type's readings) and are fetched again. Before init it is replaced by the entry type init
+     * settles on: pass the entry type to `init` instead.
+     */
+    entryTypeFor(next: string): void;
+    /**
+     * Loads the monitors, their latest readings, and the meta. Safe to call from several places:
+     * overlapping calls share one run, and a failed run can be retried. An explicit entry type
+     * wins over a call without one, whichever came first; between two explicit values the most
+     * recent wins. An entry type the server doesn't list falls back to its default. 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(entryType?: string, options?: MonitorsInitOptions): Promise<void>;
+    /**
+     * 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. A no-op before init.
+     */
+    update(options?: SignalOptions): Promise<void>;
+    /** Stops polling (for example when the last map showing the data goes away). */
+    pauseAutoUpdate(): void;
+    /**
+     * Starts polling when it is not running: after `pauseAutoUpdate()` 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;
+    /** The monitors and their readings for `monitorsPlugin`, with the entry type's scale. */
+    readonly dataSource: DataSource<MonitorFeatureProperties>;
+    /** Stops polling and cancels in-flight requests. A disposed store does nothing. */
+    dispose(): void;
+}
+/**
+ * The live monitors data for an app: the monitor list, the latest readings for one entry type,
+ * and polling every 2 minutes. One store can feed any number of maps and screens, or none: its
+ * `dataSource` goes straight to `monitorsPlugin`. Call `init()` to load, and `dispose()` when the
+ * app is done with it.
+ */
+export declare function createMonitorsStore(options?: MonitorsStoreOptions): MonitorsStore;