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

package/dist/presets/monitors.js

@@ -0,0 +1,243 @@
+import { createRawSnippet, mount, unmount } from "svelte";
+import { circle, square, triangle } from "../plugins/icons.js";
+import { pointsPlugin } from "../plugins/points.svelte.js";
+import { hasNumericValue, levelKeyExpression, levelLookup, MISSING_VALUE } from "../plugins/style.js";
+import { levelChip } from "../ui/level-chip.js";
+import { reactiveProps } from "./reactive-props.svelte.js";
+import MonitorClusterTooltip from "./MonitorClusterTooltip.svelte";
+import MonitorTooltip from "./MonitorTooltip.svelte";
+// Ported from monitor-map 4.3.0 (src/lib/monitors/): shapes, draw order, icon variants, and
+// cluster rendering. Shapes, sizes, and order are presentation; colors come from the scale and
+// the theme, except the two fixed monitor colors below.
+// The user's decision (2026-11-04), an exception to the theme-token rule: inactive monitors are
+// this gray and inside monitors have a black outline, on every map and theme, as on sjvair.com.
+export const MONITOR_INACTIVE_COLOR = "#969696";
+export const MONITOR_INSIDE_OUTLINE = "#000000";
+/** The marker shape for a monitor type: reference monitors are triangles, sensors circles. */
+export function monitorShape(type) {
+    switch (type) {
+        case "airnow":
+        case "aqview":
+        case "bam1022":
+        case "aqlite":
+            return "triangle";
+        default:
+            return "circle";
+    }
+}
+/** monitor-map's draw order (`getOrder`): higher draws on top. Unknown types draw lowest. */
+function monitorOrder(props) {
+    switch (props.type) {
+        case "airgradient":
+            return 5;
+        case "airnow":
+            return 2;
+        case "aqview":
+            return 3;
+        case "bam1022":
+            return 6;
+        case "purpleair":
+            return props.isSjvair ? 4 : 1;
+        case "vozbox":
+            return 7;
+        case "aqlite":
+            return 8;
+        default:
+            return 0;
+    }
+}
+/** The marker drawing for each shape. */
+export const SHAPES = { circle, square, triangle };
+const ICON_SIZE = 24;
+const BORDER_WIDTH = 2;
+const CLUSTER_RADIUS = 40;
+const CLUSTER_MAX_ZOOM = 9;
+const CLUSTER_OPACITY = 0.8;
+/** Cluster icons grow with the count: 1.3×, then 1.6× from 10, then 2× from 25. */
+const CLUSTER_SIZES = [1.3, 10, 1.6, 25, 2.0];
+/** `shape:location`, e.g. "triangle:inside". */
+function category(props) {
+    return `${monitorShape(props.type)}:${props.location === "inside" ? "inside" : "outside"}`;
+}
+/** Readings by `numericValue`'s rule (numbers and numeric strings), as levels and tooltips count. */
+const IS_READING = hasNumericValue("value");
+const COUNT = ["get", "countValues"];
+const MEAN = ["/", ["get", "sumValues"], ["max", COUNT, 1]];
+/** The cluster's average reading, or MISSING_VALUE when none of its monitors has one. */
+const AVERAGE = ["case", [">", COUNT, 0], MEAN, MISSING_VALUE];
+/** Readable text on `color`, or `fallback` for an unparseable color. */
+function readable(color, fallback) {
+    return levelChip(color)?.text ?? fallback;
+}
+/** A type's cluster: its shape colored by the average's level, with the rounded average on it. */
+function clusterLayers({ group, sourceId, scale, theme, iconImage, iconSizeScale }) {
+    const filter = ["has", "point_count"];
+    const sizes = CLUSTER_SIZES.map((n, i) => (i % 2 === 0 ? n * iconSizeScale : n));
+    return [
+        {
+            local: "cluster-icon",
+            spec: {
+                type: "symbol",
+                source: sourceId,
+                filter,
+                layout: {
+                    "icon-image": iconImage(`${monitorShape(group)}:outside`, levelKeyExpression(scale, AVERAGE)),
+                    "icon-size": [
+                        "step",
+                        ["get", "point_count"],
+                        ...sizes
+                    ],
+                    "icon-ignore-placement": true,
+                    "icon-allow-overlap": true
+                },
+                paint: { "icon-opacity": CLUSTER_OPACITY }
+            }
+        },
+        {
+            local: "cluster-average",
+            spec: {
+                type: "symbol",
+                source: sourceId,
+                filter,
+                layout: {
+                    "text-field": [
+                        "case",
+                        [">", COUNT, 0],
+                        ["to-string", ["round", MEAN]],
+                        ""
+                    ],
+                    "text-size": 12,
+                    "text-ignore-placement": true,
+                    "text-allow-overlap": true
+                },
+                paint: {
+                    "text-color": levelLookup(scale, AVERAGE, readable(theme.neutral, theme.foreground), (l) => readable(l.color || theme.neutral, theme.foreground))
+                }
+            }
+        }
+    ];
+}
+/**
+ * A snippet that mounts `component` with `props` (a tooltip outside the map's component tree).
+ * It mounts at once; `late`, when given, updates the props once it resolves (e.g. a note that
+ * needs a lookup), so a slow lookup never leaves an empty card. Nothing is mounted or updated
+ * after the tooltip closes, and a failure to mount or update is logged, not thrown.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function componentSnippet(component, props, late) {
+    return createRawSnippet(() => ({
+        render: () => "<div></div>",
+        setup(target) {
+            let instance;
+            let closed = false;
+            const live = reactiveProps(props);
+            try {
+                instance = mount(component, { target, props: live });
+            }
+            catch (error) {
+                console.error("map-sdk: a tooltip failed to mount", error);
+            }
+            void late?.then((extra) => {
+                if (closed || !instance)
+                    return;
+                try {
+                    Object.assign(live, extra);
+                }
+                catch (error) {
+                    console.error("map-sdk: a tooltip failed to update", error);
+                }
+            });
+            return () => {
+                closed = true;
+                if (instance)
+                    void unmount(instance);
+            };
+        }
+    }));
+}
+/**
+ * Looks up a monitor type's reporting interval (e.g. "1 hour") for tooltips' "(N avg)" note,
+ * once per type; null when the provider has none. Failures (a rejection or a synchronous throw)
+ * give null and are forgotten, so they're retried.
+ */
+export function intervalLookup() {
+    const intervals = new Map();
+    return function intervalFor(type, metadata) {
+        if (!metadata.monitorTypeInterval)
+            return Promise.resolve(null);
+        let found = intervals.get(type);
+        if (!found) {
+            let call;
+            try {
+                call = Promise.resolve(metadata.monitorTypeInterval(type));
+            }
+            catch {
+                return Promise.resolve(null);
+            }
+            const lookup = call.then((value) => (value === "unavailable" ? null : value), () => null);
+            found = lookup;
+            intervals.set(type, lookup);
+            void lookup.then((value) => {
+                if (value === null && intervals.get(type) === lookup)
+                    intervals.delete(type);
+            });
+        }
+        return found;
+    };
+}
+/**
+ * Air-quality monitors as on today's live map: a shape per monitor type filled with its level's
+ * color, inactive monitors in the neutral color, inside monitors outlined, and per-type clusters
+ * colored by their average that zoom in when clicked.
+ */
+export function monitorsPlugin(options) {
+    const clustered = options.clustered ?? true;
+    const intervalFor = intervalLookup();
+    return pointsPlugin({
+        id: options.id ?? "monitors",
+        source: options.source,
+        layerLabel: options.layerLabel,
+        legendTitle: "entry-type",
+        selectable: options.selectable ?? true,
+        selectedStyle: options.selectedStyle,
+        icon: {
+            category,
+            draw(cat, color) {
+                const [shape, location] = cat.split(":");
+                return SHAPES[shape](color, BORDER_WIDTH, location === "inside" ? MONITOR_INSIDE_OUTLINE : undefined);
+            },
+            size: ICON_SIZE,
+            muted: (props) => !props.isActive,
+            mutedColor: MONITOR_INACTIVE_COLOR
+        },
+        sortKey: monitorOrder,
+        cluster: clustered
+            ? {
+                radius: CLUSTER_RADIUS,
+                maxZoom: CLUSTER_MAX_ZOOM,
+                groupBy: (props) => props.type,
+                properties: {
+                    sumValues: ["+", ["case", IS_READING, ["to-number", ["get", "value"], 0], 0]],
+                    countValues: ["+", ["case", IS_READING, 1, 0]]
+                },
+                layers: clusterLayers,
+                tooltip: (cluster, env) => componentSnippet(MonitorClusterTooltip, {
+                    cluster,
+                    scale: env.scale,
+                    messages: env.messages,
+                    format: env.format,
+                    metadata: env.metadata
+                })
+            }
+            : undefined,
+        tooltipShowsName: true,
+        tooltip: (item, props, env) => componentSnippet(MonitorTooltip, {
+            item,
+            timestamp: props.timestamp ?? null,
+            scale: env.scale,
+            messages: env.messages,
+            format: env.format,
+            interval: null
+        }, intervalFor(props.type, env.metadata).then((interval) => ({ interval })))
+    });
+}

package/dist/presets/reactive-props.svelte.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Props for a component mounted outside the map's tree that can be updated by assigning to them.
+ */
+export declare function reactiveProps<T extends object>(initial: T): T;

package/dist/presets/reactive-props.svelte.js

@@ -0,0 +1,7 @@
+/**
+ * Props for a component mounted outside the map's tree that can be updated by assigning to them.
+ */
+export function reactiveProps(initial) {
+    const props = $state(initial);
+    return props;
+}

package/dist/presets/regions.d.ts

@@ -0,0 +1,24 @@
+import type { MapPlugin } from "../core/plugin.js";
+import type { DataSource } from "../data/types.js";
+export interface RegionsPluginOptions {
+    /** Default "regions". */
+    id?: string;
+    source: DataSource;
+    /** Already-translated layer name for the list and summary. */
+    layerLabel: string;
+    /** Default true. */
+    selectable?: boolean;
+}
+/**
+ * Region polygons (counties, cities, and other server regions) filled by a pollutant's level.
+ *
+ * The source's `scale` is expected to be the ScaleRef
+ * `{ dataset: "air-quality", entryType: <pollutant> }` (e.g. `pm25`).
+ *
+ * This preset does not fetch. The host's data source supplies the features, and each feature's
+ * `refKey` must already be `region:<type>:<external_id>`: a region of any type, e.g.
+ * `region:county:fresno`. Use the region's `external_id` (its code), never the server's `id` (a
+ * sqid), which is not a ref. A picked feature selects
+ * `{ kind: "regions", ids: ["<type>:<code>"] }`.
+ */
+export declare function regionsPlugin(options: RegionsPluginOptions): MapPlugin;

package/dist/presets/regions.js

@@ -0,0 +1,22 @@
+import { shapesPlugin } from "../plugins/shapes.svelte.js";
+/**
+ * Region polygons (counties, cities, and other server regions) filled by a pollutant's level.
+ *
+ * The source's `scale` is expected to be the ScaleRef
+ * `{ dataset: "air-quality", entryType: <pollutant> }` (e.g. `pm25`).
+ *
+ * This preset does not fetch. The host's data source supplies the features, and each feature's
+ * `refKey` must already be `region:<type>:<external_id>`: a region of any type, e.g.
+ * `region:county:fresno`. Use the region's `external_id` (its code), never the server's `id` (a
+ * sqid), which is not a ref. A picked feature selects
+ * `{ kind: "regions", ids: ["<type>:<code>"] }`.
+ */
+export function regionsPlugin(options) {
+    return shapesPlugin({
+        id: options.id ?? "regions",
+        source: options.source,
+        layerLabel: options.layerLabel,
+        mode: "choropleth",
+        selectable: options.selectable ?? true
+    });
+}

package/dist/stores/abort.d.ts

@@ -0,0 +1,16 @@
+export type SignalOptions = {
+    signal?: AbortSignal;
+};
+/**
+ * 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 declare function anySignal(...signals: Array<AbortSignal | undefined>): {
+    signal: AbortSignal;
+    dispose(): void;
+};
+/**
+ * Settles like `promise`, unless `signal` aborts first, in which case it rejects with
+ * `signal.reason`. The inner promise's later outcome is swallowed.
+ */
+export declare function untilAborted<T>(promise: Promise<T>, signal: AbortSignal | undefined): Promise<T>;

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,38 @@
+import { type MessageProvider } from "../data/messages.js";
+import type { DataSource, DataStatus, FireFeatureProperties } 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 and
+     * `count` how many detections it merges.
+     */
+    readonly groups: DataSource<FireFeatureProperties>;
+    /** 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
+            }
+        }));
+        // Every group names its count, a group of 1 included ("1 fire detection").
+        const groups = groupFires(detections).map((group) => ({
+            type: "Feature",
+            geometry: { type: "Point", coordinates: group.coordinates },
+            properties: {
+                refKey: encodeRef({ kind: "feature", id: group.id }),
+                name: messages("mapsdk_hms_fire_detections", { count: group.count }),
+                value: group.avgFrp,
+                count: group.count
+            }
+        }));
+        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>;