@sqlrooms/deck 0.29.0-rc.2 → 0.29.0-rc.4

package/dist/dashboardConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dashboardConfig.js","sourceRoot":"","sources":["../src/dashboardConfig.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,GACN,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAC,QAAQ,EAAC,MAAM,sBAAsB,CAAC;AAC9C,OAAO,EAAC,QAAQ,EAAC,MAAM,oBAAoB,CAAC;AAI5C,MAAM,CAAC,MAAM,6BAA6B,GAAG,eAAe,CAAC;AAiD7D,MAAM,UAAU,mBAAmB,CACjC,MAA+B;IAE/B,IACE,CAAC,MAAM,CAAC,IAAI;QACZ,CAAC,MAAM,CAAC,QAAQ;QAChB,OAAO,MAAM,CAAC,QAAQ,KAAK,QAAQ;QACnC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,EAC9B,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,MAAqC,CAAC;AAC/C,CAAC;AAED,MAAM,UAAU,iCAAiC,CAC/C,OAAiD;IAEjD,MAAM,EAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,EAAC,GAAG,OAAO,CAAC;IAC3C,OAAO;QACL,EAAE,EAAE,QAAQ,EAAE;QACd,IAAI,EAAE,6BAA6B;QACnC,KAAK,EAAE,KAAK,IAAI,KAAK;QACrB,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAC,MAAM,EAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3B,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAA4B;KACtE,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,oCAAoC,CAAC,OAIpD;IACC,MAAM,aAAa,GAAG,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC;IAC9C,IAAI,aAAa,EAAE,QAAQ,IAAI,aAAa,EAAE,SAAS,EAAE,CAAC;QACxD,OAAO,aAAa,CAAC;IACvB,CAAC;IACD,IAAI,OAAO,CAAC,KAAK,CAAC,MAAM,EAAE,QAAQ,IAAI,OAAO,CAAC,KAAK,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC;QACtE,OAAO,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC;IAC9B,CAAC;IACD,OAAO,OAAO,CAAC,SAAS,CAAC,aAAa;QACpC,CAAC,CAAC,EAAC,SAAS,EAAE,OAAO,CAAC,SAAS,CAAC,aAAa,EAAC;QAC9C,CAAC,CAAC,SAAS,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,kCAAkC,CAChD,MAAsC,EACtC,MAAe;IAEf,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ;QAC3B,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC;YACT,uBAAuB,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,QAAQ,GAAG,CAAC;SAC1D,CAAC;QACJ,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC;IAEvC,OAAO,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,MAAe,CAAC,CAAC;AAClD,CAAC;AAED,MAAM,UAAU,8BAA8B,CAC5C,SAAsC,EACtC,aAGC;IAED,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC;QAC/D,SAAS;QACT;YACE,UAAU,EAAE,aAAa,CAAC,SAAS,CAAC,EAAE,UAAU;YAChD,cAAc,EAAE,OAAO,CAAC,cAAc;YACtC,oBAAoB,EAAE,OAAO,CAAC,oBAAoB;SACnD;KACF,CAAC,CACH,CAAC;AACJ,CAAC","sourcesContent":["import {\n  type MosaicDashboardEntryType,\n  type MosaicDashboardPanelConfigType,\n  type MosaicDashboardPanelSourceType,\n  Query,\n} from '@sqlrooms/mosaic';\nimport {createId} from '@paralleldrive/cuid2';\nimport {verbatim} from '@uwdata/mosaic-sql';\nimport type {Table as ArrowTable} from 'apache-arrow';\nimport type {DeckJsonMapProps, DeckSqlDatasetInput} from './types';\n\nexport const DECK_MAP_DASHBOARD_PANEL_TYPE = 'deck-json-map';\n\nexport type DeckMapDashboardDatasetConfig = Omit<\n  DeckSqlDatasetInput,\n  'sqlQuery'\n> & {\n  source?: MosaicDashboardPanelSourceType;\n};\n\nexport type DeckMapDashboardInteractionConfig = {\n  type: 'point-radius-brush';\n  dataset: string;\n  longitudeColumn: string;\n  latitudeColumn: string;\n  radiusMeters?: number;\n  event?: 'hover' | 'click';\n};\n\nexport type DeckMapDashboardFitToDataConfig = {\n  dataset: string;\n  longitudeColumn: string;\n  latitudeColumn: string;\n  padding?: number;\n  maxZoom?: number;\n};\n\nexport type DeckMapDashboardPanelConfig = {\n  spec: DeckJsonMapProps['spec'];\n  datasets: Record<string, DeckMapDashboardDatasetConfig>;\n  mapStyle?: string;\n  mapProps?: Record<string, unknown>;\n  showLegends?: boolean;\n  interaction?: DeckMapDashboardInteractionConfig;\n  fitToData?: DeckMapDashboardFitToDataConfig;\n};\n\nexport type CreateDeckMapDashboardPanelConfigOptions =\n  DeckMapDashboardPanelConfig & {\n    title?: string;\n    source?: MosaicDashboardPanelSourceType;\n  };\n\nexport type DeckMapDashboardDatasetClientState = {\n  arrowTable?: ArrowTable;\n  isLoading: boolean;\n  error?: Error;\n  client: unknown;\n};\n\nexport function asDeckJsonMapConfig(\n  config: Record<string, unknown>,\n): DeckMapDashboardPanelConfig | null {\n  if (\n    !config.spec ||\n    !config.datasets ||\n    typeof config.datasets !== 'object' ||\n    Array.isArray(config.datasets)\n  ) {\n    return null;\n  }\n\n  return config as DeckMapDashboardPanelConfig;\n}\n\nexport function createDeckMapDashboardPanelConfig(\n  options: CreateDeckMapDashboardPanelConfigOptions,\n): MosaicDashboardPanelConfigType {\n  const {title, source, ...config} = options;\n  return {\n    id: createId(),\n    type: DECK_MAP_DASHBOARD_PANEL_TYPE,\n    title: title ?? 'Map',\n    ...(source ? {source} : {}),\n    config: JSON.parse(JSON.stringify(config)) as Record<string, unknown>,\n  };\n}\n\nexport function resolveDeckMapDashboardDatasetSource(options: {\n  dashboard: MosaicDashboardEntryType;\n  panel: MosaicDashboardPanelConfigType;\n  dataset?: DeckMapDashboardDatasetConfig;\n}): MosaicDashboardPanelSourceType | undefined {\n  const datasetSource = options.dataset?.source;\n  if (datasetSource?.sqlQuery || datasetSource?.tableName) {\n    return datasetSource;\n  }\n  if (options.panel.source?.sqlQuery || options.panel.source?.tableName) {\n    return options.panel.source;\n  }\n  return options.dashboard.selectedTable\n    ? {tableName: options.dashboard.selectedTable}\n    : undefined;\n}\n\nexport function createDeckMapDashboardDatasetQuery(\n  source: MosaicDashboardPanelSourceType,\n  filter: unknown,\n) {\n  const query = source.sqlQuery\n    ? Query.from({\n        __dashboard_map_dataset: verbatim(`(${source.sqlQuery})`),\n      })\n    : Query.from(source.tableName ?? '');\n\n  return query.select('*').where(filter as never);\n}\n\nexport function createDeckMapDashboardDatasets(\n  mapConfig: DeckMapDashboardPanelConfig,\n  datasetStates: Record<\n    string,\n    Pick<DeckMapDashboardDatasetClientState, 'arrowTable'>\n  >,\n): DeckJsonMapProps['datasets'] {\n  return Object.fromEntries(\n    Object.entries(mapConfig.datasets).map(([datasetId, dataset]) => [\n      datasetId,\n      {\n        arrowTable: datasetStates[datasetId]?.arrowTable,\n        geometryColumn: dataset.geometryColumn,\n        geometryEncodingHint: dataset.geometryEncodingHint,\n      },\n    ]),\n  );\n}\n"]}

package/dist/datasets/PreparedDatasetStore.d.ts

@@ -0,0 +1,120 @@
+import type { QueryHandle } from '@sqlrooms/duckdb';
+import { type DeckDatasetInput, type PreparedDeckDatasetState } from '../types';
+import type { PreparedDatasetCacheEntry, PreparedDatasetStoreOptions } from './types';
+/**
+ * Internal store state for the prepared-dataset cache.
+ *
+ * `DeckJsonMap` never talks to this shape directly; `usePreparedDatasetStates`
+ * uses it as the backing state machine for preparation, reuse, and eviction.
+ */
+type PreparedDatasetStoreState = {
+    /**
+     * Cache keys currently referenced by each hook consumer.
+     *
+     * This lets the store update consumer memberships incrementally when a map's
+     * dataset registry changes, instead of resetting all cache state.
+     */
+    consumerKeys: Record<string, string[]>;
+    /**
+     * Prepared entries keyed by resolved dataset identity.
+     *
+     * Keys are based on query/table identity plus geometry options, not dataset
+     * id, so the same prepared result can be reused across multiple maps or
+     * differently named datasets that point at the same underlying data.
+     */
+    entries: Record<string, PreparedDatasetCacheEntry>;
+    /**
+     * Ensure a cache entry exists for the given dataset key.
+     *
+     * If an entry already exists, this is a no-op other than touching its LRU
+     * metadata. Otherwise the store creates a `loading` entry, resolves the
+     * source table through DuckDB if needed, runs `prepareDeckDataset(...)`, and
+     * stores the resulting `ready` or `error` state.
+     */
+    ensureEntry: (options: {
+        cacheKey: string;
+        datasetId: string;
+        executeSql: (query: string, version?: number) => Promise<QueryHandle | null>;
+        input: DeckDatasetInput;
+    }) => void;
+    /**
+     * Remove all subscriptions for one hook consumer.
+     *
+     * This is called when a `DeckJsonMap` instance unmounts so the store can
+     * release the consumer's references and allow now-unreferenced entries to be
+     * evicted later.
+     */
+    removeConsumer: (consumerId: string) => void;
+    /**
+     * Reconcile the set of cache keys referenced by one hook consumer.
+     *
+     * This adds the consumer to newly needed entries, removes it from entries no
+     * longer needed, and preserves existing entries in place so unrelated dataset
+     * states do not get reset during prop changes.
+     */
+    syncConsumer: (consumerId: string, keys: string[]) => void;
+    /**
+     * Reconcile and ensure all prepared entries needed by one dataset registry.
+     *
+     * This is the store-level orchestration entrypoint used by
+     * `usePreparedDatasetStates`. It computes cache keys for the current dataset
+     * registry, syncs consumer memberships, and eagerly ensures any resolvable
+     * entries exist.
+     */
+    syncDatasetsForConsumer: (options: {
+        consumerId: string;
+        datasets: Record<string, DeckDatasetInput>;
+        executeSql: (query: string, version?: number) => Promise<QueryHandle | null>;
+        sqlSourceIdentity: object;
+    }) => void;
+};
+/**
+ * Create a feature-local cache store for prepared deck datasets.
+ *
+ * The store is intentionally scoped to deck's preparation layer. It reuses the
+ * expensive result of `prepareDeckDataset(...)` across consumers while leaving
+ * raw query/result caching to the upstream data provider:
+ *
+ * - Mosaic handles cached query results through its coordinator/query manager
+ * - DuckDB-backed SQL datasets still use the DuckDB slice execution path
+ *
+ * This keeps `@sqlrooms/deck` independent from either provider while still
+ * avoiding repeated geometry decoding and GeoArrow/GeoJSON shaping work.
+ */
+export declare function createPreparedDatasetStore(options?: PreparedDatasetStoreOptions): import("zustand").StoreApi<PreparedDatasetStoreState>;
+/**
+ * Resolve a shared prepared-store entry back into the dataset-state shape
+ * consumed by `DeckJsonMap`.
+ *
+ * Prepared entries are shared by cache key, while `datasetId` stays a
+ * view-level label used by layer binding and user-facing errors. When a shared
+ * prepared entry is reused for a different dataset id, this helper remaps the
+ * prepared payload so downstream callers still see the dataset id they asked
+ * for.
+ */
+export declare function resolvePreparedDeckDatasetState(options: {
+    datasetId: string;
+    entry?: PreparedDatasetCacheEntry;
+}): PreparedDeckDatasetState;
+/**
+ * Resolve the full `datasetId -> state` map for a dataset registry.
+ *
+ * This mirrors the lookup logic used by `DeckJsonMap`: unresolved Arrow
+ * datasets remain `loading`, while resolvable datasets reuse shared prepared
+ * entries keyed by data identity rather than by dataset id.
+ */
+export declare function resolvePreparedDeckDatasetStates(options: {
+    datasets: Record<string, DeckDatasetInput>;
+    entries: Record<string, PreparedDatasetCacheEntry>;
+    sqlSourceIdentity: object;
+}): Record<string, PreparedDeckDatasetState>;
+/**
+ * Module-global prepared dataset cache shared by all `DeckJsonMap` instances.
+ *
+ * The cache stores only deck-specific prepared payloads, not raw query
+ * results, and applies a small internal LRU policy so settled entries do not
+ * grow without bound.
+ */
+export declare const preparedDatasetStore: import("zustand").StoreApi<PreparedDatasetStoreState>;
+export {};
+//# sourceMappingURL=PreparedDatasetStore.d.ts.map

package/dist/datasets/PreparedDatasetStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PreparedDatasetStore.d.ts","sourceRoot":"","sources":["../../src/datasets/PreparedDatasetStore.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,kBAAkB,CAAC;AAGlD,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,wBAAwB,EAC9B,MAAM,UAAU,CAAC;AAUlB,OAAO,KAAK,EACV,yBAAyB,EACzB,2BAA2B,EAC5B,MAAM,SAAS,CAAC;AAEjB;;;;;GAKG;AACH,KAAK,yBAAyB,GAAG;IAC/B;;;;;OAKG;IACH,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACvC;;;;;;OAMG;IACH,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAC;IACnD;;;;;;;OAOG;IACH,WAAW,EAAE,CAAC,OAAO,EAAE;QACrB,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,UAAU,EAAE,CACV,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,MAAM,KACb,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;QACjC,KAAK,EAAE,gBAAgB,CAAC;KACzB,KAAK,IAAI,CAAC;IACX;;;;;;OAMG;IACH,cAAc,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7C;;;;;;OAMG;IACH,YAAY,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;IAC3D;;;;;;;OAOG;IACH,uBAAuB,EAAE,CAAC,OAAO,EAAE;QACjC,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;QAC3C,UAAU,EAAE,CACV,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,MAAM,KACb,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;QACjC,iBAAiB,EAAE,MAAM,CAAC;KAC3B,KAAK,IAAI,CAAC;CACZ,CAAC;AAwBF;;;;;;;;;;;;GAYG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,GAAE,2BAAgC,yDAwO1C;AAED;;;;;;;;;GASG;AACH,wBAAgB,+BAA+B,CAAC,OAAO,EAAE;IACvD,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,yBAAyB,CAAC;CACnC,GAAG,wBAAwB,CAqB3B;AAED;;;;;;GAMG;AACH,wBAAgB,gCAAgC,CAAC,OAAO,EAAE;IACxD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAC3C,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAC;IACnD,iBAAiB,EAAE,MAAM,CAAC;CAC3B,GAAG,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAc3C;AAED;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,uDAA+B,CAAC"}

package/dist/datasets/PreparedDatasetStore.js

@@ -0,0 +1,262 @@
+import { createStore } from 'zustand/vanilla';
+import { prepareDeckDataset } from '../prepare/prepareDeckDataset';
+import { isSqlDatasetInput, } from '../types';
+import { DEFAULT_MAX_PREPARED_DATASET_ENTRIES, cloneEntryWithConsumers, evictLruEntries, nextAccessTimestamp, resolvePreparedDatasetCacheKey, touchEntry, } from './helpers';
+import { resolveArrowTable } from './normalizeDatasets';
+function resolvePreparedDatasetDescriptors(options) {
+    const { datasets, sqlSourceIdentity } = options;
+    return Object.entries(datasets).map(([datasetId, input]) => ({
+        datasetId,
+        input,
+        cacheKey: resolvePreparedDatasetCacheKey({
+            input,
+            sqlSourceIdentity,
+        }),
+    }));
+}
+/**
+ * Create a feature-local cache store for prepared deck datasets.
+ *
+ * The store is intentionally scoped to deck's preparation layer. It reuses the
+ * expensive result of `prepareDeckDataset(...)` across consumers while leaving
+ * raw query/result caching to the upstream data provider:
+ *
+ * - Mosaic handles cached query results through its coordinator/query manager
+ * - DuckDB-backed SQL datasets still use the DuckDB slice execution path
+ *
+ * This keeps `@sqlrooms/deck` independent from either provider while still
+ * avoiding repeated geometry decoding and GeoArrow/GeoJSON shaping work.
+ */
+export function createPreparedDatasetStore(options = {}) {
+    const { maxEntries = DEFAULT_MAX_PREPARED_DATASET_ENTRIES, prepareDataset = prepareDeckDataset, } = options;
+    return createStore((set, get) => ({
+        consumerKeys: {},
+        entries: {},
+        ensureEntry({ cacheKey, datasetId, executeSql, input }) {
+            const existing = get().entries[cacheKey];
+            if (existing) {
+                if (existing.status !== 'loading') {
+                    set((state) => ({
+                        ...state,
+                        entries: {
+                            ...state.entries,
+                            [cacheKey]: touchEntry(existing),
+                        },
+                    }));
+                }
+                return;
+            }
+            const promise = Promise.resolve().then(async () => {
+                try {
+                    let table = resolveArrowTable(input);
+                    if (!table && isSqlDatasetInput(input)) {
+                        const queryHandle = await executeSql(input.sqlQuery);
+                        if (!queryHandle) {
+                            throw new Error(`Query for dataset "${datasetId}" was cancelled.`);
+                        }
+                        table = await queryHandle;
+                    }
+                    if (!table) {
+                        return;
+                    }
+                    const prepared = prepareDataset({
+                        datasetId,
+                        table,
+                        geometryColumn: input.geometryColumn,
+                        geometryEncodingHint: input.geometryEncodingHint,
+                    });
+                    set((state) => ({
+                        ...state,
+                        entries: evictLruEntries({
+                            ...state.entries,
+                            [cacheKey]: {
+                                status: 'ready',
+                                prepared,
+                                consumers: state.entries[cacheKey]?.consumers ?? new Set(),
+                                lastAccessedAt: nextAccessTimestamp(),
+                            },
+                        }, maxEntries),
+                    }));
+                }
+                catch (error) {
+                    set((state) => ({
+                        ...state,
+                        entries: evictLruEntries({
+                            ...state.entries,
+                            [cacheKey]: {
+                                status: 'error',
+                                error: error instanceof Error ? error : new Error(String(error)),
+                                consumers: state.entries[cacheKey]?.consumers ?? new Set(),
+                                lastAccessedAt: nextAccessTimestamp(),
+                            },
+                        }, maxEntries),
+                    }));
+                }
+            });
+            set((state) => ({
+                ...state,
+                entries: {
+                    ...state.entries,
+                    [cacheKey]: {
+                        status: 'loading',
+                        promise,
+                        consumers: state.entries[cacheKey]?.consumers ?? new Set(),
+                        lastAccessedAt: nextAccessTimestamp(),
+                    },
+                },
+            }));
+        },
+        syncConsumer(consumerId, keys) {
+            const previousKeys = new Set(get().consumerKeys[consumerId] ?? []);
+            const nextKeys = new Set(keys);
+            set((state) => {
+                let didChangeEntries = false;
+                let nextEntries = state.entries;
+                const updateEntry = (cacheKey, updater) => {
+                    const currentEntry = nextEntries[cacheKey];
+                    if (!currentEntry) {
+                        return;
+                    }
+                    if (!didChangeEntries) {
+                        nextEntries = { ...nextEntries };
+                        didChangeEntries = true;
+                    }
+                    nextEntries[cacheKey] = updater(currentEntry);
+                };
+                for (const cacheKey of previousKeys) {
+                    if (nextKeys.has(cacheKey)) {
+                        continue;
+                    }
+                    updateEntry(cacheKey, (entry) => {
+                        const consumers = new Set(entry.consumers);
+                        consumers.delete(consumerId);
+                        return cloneEntryWithConsumers(entry, consumers);
+                    });
+                }
+                for (const cacheKey of nextKeys) {
+                    updateEntry(cacheKey, (entry) => {
+                        const consumers = new Set(entry.consumers);
+                        consumers.add(consumerId);
+                        return cloneEntryWithConsumers(entry, consumers);
+                    });
+                }
+                return {
+                    ...state,
+                    consumerKeys: {
+                        ...state.consumerKeys,
+                        [consumerId]: [...nextKeys],
+                    },
+                    entries: didChangeEntries
+                        ? evictLruEntries(nextEntries, maxEntries)
+                        : state.entries,
+                };
+            });
+        },
+        removeConsumer(consumerId) {
+            const previousKeys = get().consumerKeys[consumerId];
+            if (!previousKeys) {
+                return;
+            }
+            set((state) => {
+                let didChangeEntries = false;
+                let nextEntries = state.entries;
+                for (const cacheKey of previousKeys) {
+                    const entry = nextEntries[cacheKey];
+                    if (!entry) {
+                        continue;
+                    }
+                    const consumers = new Set(entry.consumers);
+                    consumers.delete(consumerId);
+                    if (!didChangeEntries) {
+                        nextEntries = { ...nextEntries };
+                        didChangeEntries = true;
+                    }
+                    nextEntries[cacheKey] = cloneEntryWithConsumers(entry, consumers);
+                }
+                const { [consumerId]: _removedConsumer, ...nextConsumerKeys } = state.consumerKeys;
+                return {
+                    ...state,
+                    consumerKeys: nextConsumerKeys,
+                    entries: didChangeEntries
+                        ? evictLruEntries(nextEntries, maxEntries)
+                        : state.entries,
+                };
+            });
+        },
+        syncDatasetsForConsumer({ consumerId, datasets, executeSql, sqlSourceIdentity, }) {
+            const descriptors = resolvePreparedDatasetDescriptors({
+                datasets,
+                sqlSourceIdentity,
+            });
+            const cacheKeys = descriptors
+                .map((descriptor) => descriptor.cacheKey)
+                .filter((cacheKey) => Boolean(cacheKey));
+            for (const descriptor of descriptors) {
+                if (!descriptor.cacheKey) {
+                    continue;
+                }
+                get().ensureEntry({
+                    cacheKey: descriptor.cacheKey,
+                    datasetId: descriptor.datasetId,
+                    executeSql,
+                    input: descriptor.input,
+                });
+            }
+            get().syncConsumer(consumerId, cacheKeys);
+        },
+    }));
+}
+/**
+ * Resolve a shared prepared-store entry back into the dataset-state shape
+ * consumed by `DeckJsonMap`.
+ *
+ * Prepared entries are shared by cache key, while `datasetId` stays a
+ * view-level label used by layer binding and user-facing errors. When a shared
+ * prepared entry is reused for a different dataset id, this helper remaps the
+ * prepared payload so downstream callers still see the dataset id they asked
+ * for.
+ */
+export function resolvePreparedDeckDatasetState(options) {
+    const { datasetId, entry } = options;
+    if (!entry || entry.status === 'loading') {
+        return { status: 'loading' };
+    }
+    if (entry.status === 'error') {
+        return { status: 'error', error: entry.error };
+    }
+    return {
+        status: 'ready',
+        prepared: entry.prepared.datasetId === datasetId
+            ? entry.prepared
+            : {
+                ...entry.prepared,
+                datasetId,
+            },
+    };
+}
+/**
+ * Resolve the full `datasetId -> state` map for a dataset registry.
+ *
+ * This mirrors the lookup logic used by `DeckJsonMap`: unresolved Arrow
+ * datasets remain `loading`, while resolvable datasets reuse shared prepared
+ * entries keyed by data identity rather than by dataset id.
+ */
+export function resolvePreparedDeckDatasetStates(options) {
+    const { datasets, entries, sqlSourceIdentity } = options;
+    return Object.fromEntries(resolvePreparedDatasetDescriptors({ datasets, sqlSourceIdentity }).map(({ datasetId, cacheKey }) => [
+        datasetId,
+        resolvePreparedDeckDatasetState({
+            datasetId,
+            entry: cacheKey ? entries[cacheKey] : undefined,
+        }),
+    ]));
+}
+/**
+ * Module-global prepared dataset cache shared by all `DeckJsonMap` instances.
+ *
+ * The cache stores only deck-specific prepared payloads, not raw query
+ * results, and applies a small internal LRU policy so settled entries do not
+ * grow without bound.
+ */
+export const preparedDatasetStore = createPreparedDatasetStore();
+//# sourceMappingURL=PreparedDatasetStore.js.map

package/dist/datasets/PreparedDatasetStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PreparedDatasetStore.js","sourceRoot":"","sources":["../../src/datasets/PreparedDatasetStore.ts"],"names":[],"mappings":"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","sourcesContent":["import type {QueryHandle} from '@sqlrooms/duckdb';\nimport {createStore} from 'zustand/vanilla';\nimport {prepareDeckDataset} from '../prepare/prepareDeckDataset';\nimport {\n  isSqlDatasetInput,\n  type DeckDatasetInput,\n  type PreparedDeckDatasetState,\n} from '../types';\nimport {\n  DEFAULT_MAX_PREPARED_DATASET_ENTRIES,\n  cloneEntryWithConsumers,\n  evictLruEntries,\n  nextAccessTimestamp,\n  resolvePreparedDatasetCacheKey,\n  touchEntry,\n} from './helpers';\nimport {resolveArrowTable} from './normalizeDatasets';\nimport type {\n  PreparedDatasetCacheEntry,\n  PreparedDatasetStoreOptions,\n} from './types';\n\n/**\n * Internal store state for the prepared-dataset cache.\n *\n * `DeckJsonMap` never talks to this shape directly; `usePreparedDatasetStates`\n * uses it as the backing state machine for preparation, reuse, and eviction.\n */\ntype PreparedDatasetStoreState = {\n  /**\n   * Cache keys currently referenced by each hook consumer.\n   *\n   * This lets the store update consumer memberships incrementally when a map's\n   * dataset registry changes, instead of resetting all cache state.\n   */\n  consumerKeys: Record<string, string[]>;\n  /**\n   * Prepared entries keyed by resolved dataset identity.\n   *\n   * Keys are based on query/table identity plus geometry options, not dataset\n   * id, so the same prepared result can be reused across multiple maps or\n   * differently named datasets that point at the same underlying data.\n   */\n  entries: Record<string, PreparedDatasetCacheEntry>;\n  /**\n   * Ensure a cache entry exists for the given dataset key.\n   *\n   * If an entry already exists, this is a no-op other than touching its LRU\n   * metadata. Otherwise the store creates a `loading` entry, resolves the\n   * source table through DuckDB if needed, runs `prepareDeckDataset(...)`, and\n   * stores the resulting `ready` or `error` state.\n   */\n  ensureEntry: (options: {\n    cacheKey: string;\n    datasetId: string;\n    executeSql: (\n      query: string,\n      version?: number,\n    ) => Promise<QueryHandle | null>;\n    input: DeckDatasetInput;\n  }) => void;\n  /**\n   * Remove all subscriptions for one hook consumer.\n   *\n   * This is called when a `DeckJsonMap` instance unmounts so the store can\n   * release the consumer's references and allow now-unreferenced entries to be\n   * evicted later.\n   */\n  removeConsumer: (consumerId: string) => void;\n  /**\n   * Reconcile the set of cache keys referenced by one hook consumer.\n   *\n   * This adds the consumer to newly needed entries, removes it from entries no\n   * longer needed, and preserves existing entries in place so unrelated dataset\n   * states do not get reset during prop changes.\n   */\n  syncConsumer: (consumerId: string, keys: string[]) => void;\n  /**\n   * Reconcile and ensure all prepared entries needed by one dataset registry.\n   *\n   * This is the store-level orchestration entrypoint used by\n   * `usePreparedDatasetStates`. It computes cache keys for the current dataset\n   * registry, syncs consumer memberships, and eagerly ensures any resolvable\n   * entries exist.\n   */\n  syncDatasetsForConsumer: (options: {\n    consumerId: string;\n    datasets: Record<string, DeckDatasetInput>;\n    executeSql: (\n      query: string,\n      version?: number,\n    ) => Promise<QueryHandle | null>;\n    sqlSourceIdentity: object;\n  }) => void;\n};\n\ntype PreparedDatasetDescriptor = {\n  datasetId: string;\n  input: DeckDatasetInput;\n  cacheKey: string | undefined;\n};\n\nfunction resolvePreparedDatasetDescriptors(options: {\n  datasets: Record<string, DeckDatasetInput>;\n  sqlSourceIdentity: object;\n}): PreparedDatasetDescriptor[] {\n  const {datasets, sqlSourceIdentity} = options;\n\n  return Object.entries(datasets).map(([datasetId, input]) => ({\n    datasetId,\n    input,\n    cacheKey: resolvePreparedDatasetCacheKey({\n      input,\n      sqlSourceIdentity,\n    }),\n  }));\n}\n\n/**\n * Create a feature-local cache store for prepared deck datasets.\n *\n * The store is intentionally scoped to deck's preparation layer. It reuses the\n * expensive result of `prepareDeckDataset(...)` across consumers while leaving\n * raw query/result caching to the upstream data provider:\n *\n * - Mosaic handles cached query results through its coordinator/query manager\n * - DuckDB-backed SQL datasets still use the DuckDB slice execution path\n *\n * This keeps `@sqlrooms/deck` independent from either provider while still\n * avoiding repeated geometry decoding and GeoArrow/GeoJSON shaping work.\n */\nexport function createPreparedDatasetStore(\n  options: PreparedDatasetStoreOptions = {},\n) {\n  const {\n    maxEntries = DEFAULT_MAX_PREPARED_DATASET_ENTRIES,\n    prepareDataset = prepareDeckDataset,\n  } = options;\n\n  return createStore<PreparedDatasetStoreState>((set, get) => ({\n    consumerKeys: {},\n    entries: {},\n\n    ensureEntry({cacheKey, datasetId, executeSql, input}) {\n      const existing = get().entries[cacheKey];\n      if (existing) {\n        if (existing.status !== 'loading') {\n          set((state) => ({\n            ...state,\n            entries: {\n              ...state.entries,\n              [cacheKey]: touchEntry(existing),\n            },\n          }));\n        }\n        return;\n      }\n\n      const promise = Promise.resolve().then(async () => {\n        try {\n          let table = resolveArrowTable(input);\n          if (!table && isSqlDatasetInput(input)) {\n            const queryHandle = await executeSql(input.sqlQuery);\n            if (!queryHandle) {\n              throw new Error(\n                `Query for dataset \"${datasetId}\" was cancelled.`,\n              );\n            }\n\n            table = await queryHandle;\n          }\n\n          if (!table) {\n            return;\n          }\n\n          const prepared = prepareDataset({\n            datasetId,\n            table,\n            geometryColumn: input.geometryColumn,\n            geometryEncodingHint: input.geometryEncodingHint,\n          });\n\n          set((state) => ({\n            ...state,\n            entries: evictLruEntries(\n              {\n                ...state.entries,\n                [cacheKey]: {\n                  status: 'ready',\n                  prepared,\n                  consumers:\n                    state.entries[cacheKey]?.consumers ?? new Set<string>(),\n                  lastAccessedAt: nextAccessTimestamp(),\n                },\n              },\n              maxEntries,\n            ),\n          }));\n        } catch (error) {\n          set((state) => ({\n            ...state,\n            entries: evictLruEntries(\n              {\n                ...state.entries,\n                [cacheKey]: {\n                  status: 'error',\n                  error:\n                    error instanceof Error ? error : new Error(String(error)),\n                  consumers:\n                    state.entries[cacheKey]?.consumers ?? new Set<string>(),\n                  lastAccessedAt: nextAccessTimestamp(),\n                },\n              },\n              maxEntries,\n            ),\n          }));\n        }\n      });\n\n      set((state) => ({\n        ...state,\n        entries: {\n          ...state.entries,\n          [cacheKey]: {\n            status: 'loading',\n            promise,\n            consumers: state.entries[cacheKey]?.consumers ?? new Set<string>(),\n            lastAccessedAt: nextAccessTimestamp(),\n          },\n        },\n      }));\n    },\n\n    syncConsumer(consumerId, keys) {\n      const previousKeys = new Set(get().consumerKeys[consumerId] ?? []);\n      const nextKeys = new Set(keys);\n\n      set((state) => {\n        let didChangeEntries = false;\n        let nextEntries = state.entries;\n\n        const updateEntry = (\n          cacheKey: string,\n          updater: (\n            entry: PreparedDatasetCacheEntry,\n          ) => PreparedDatasetCacheEntry,\n        ) => {\n          const currentEntry = nextEntries[cacheKey];\n          if (!currentEntry) {\n            return;\n          }\n\n          if (!didChangeEntries) {\n            nextEntries = {...nextEntries};\n            didChangeEntries = true;\n          }\n\n          nextEntries[cacheKey] = updater(currentEntry);\n        };\n\n        for (const cacheKey of previousKeys) {\n          if (nextKeys.has(cacheKey)) {\n            continue;\n          }\n\n          updateEntry(cacheKey, (entry) => {\n            const consumers = new Set(entry.consumers);\n            consumers.delete(consumerId);\n            return cloneEntryWithConsumers(entry, consumers);\n          });\n        }\n\n        for (const cacheKey of nextKeys) {\n          updateEntry(cacheKey, (entry) => {\n            const consumers = new Set(entry.consumers);\n            consumers.add(consumerId);\n            return cloneEntryWithConsumers(entry, consumers);\n          });\n        }\n\n        return {\n          ...state,\n          consumerKeys: {\n            ...state.consumerKeys,\n            [consumerId]: [...nextKeys],\n          },\n          entries: didChangeEntries\n            ? evictLruEntries(nextEntries, maxEntries)\n            : state.entries,\n        };\n      });\n    },\n\n    removeConsumer(consumerId) {\n      const previousKeys = get().consumerKeys[consumerId];\n      if (!previousKeys) {\n        return;\n      }\n\n      set((state) => {\n        let didChangeEntries = false;\n        let nextEntries = state.entries;\n\n        for (const cacheKey of previousKeys) {\n          const entry = nextEntries[cacheKey];\n          if (!entry) {\n            continue;\n          }\n\n          const consumers = new Set(entry.consumers);\n          consumers.delete(consumerId);\n\n          if (!didChangeEntries) {\n            nextEntries = {...nextEntries};\n            didChangeEntries = true;\n          }\n\n          nextEntries[cacheKey] = cloneEntryWithConsumers(entry, consumers);\n        }\n\n        const {[consumerId]: _removedConsumer, ...nextConsumerKeys} =\n          state.consumerKeys;\n\n        return {\n          ...state,\n          consumerKeys: nextConsumerKeys,\n          entries: didChangeEntries\n            ? evictLruEntries(nextEntries, maxEntries)\n            : state.entries,\n        };\n      });\n    },\n\n    syncDatasetsForConsumer({\n      consumerId,\n      datasets,\n      executeSql,\n      sqlSourceIdentity,\n    }) {\n      const descriptors = resolvePreparedDatasetDescriptors({\n        datasets,\n        sqlSourceIdentity,\n      });\n      const cacheKeys = descriptors\n        .map((descriptor) => descriptor.cacheKey)\n        .filter((cacheKey): cacheKey is string => Boolean(cacheKey));\n\n      for (const descriptor of descriptors) {\n        if (!descriptor.cacheKey) {\n          continue;\n        }\n\n        get().ensureEntry({\n          cacheKey: descriptor.cacheKey,\n          datasetId: descriptor.datasetId,\n          executeSql,\n          input: descriptor.input,\n        });\n      }\n\n      get().syncConsumer(consumerId, cacheKeys);\n    },\n  }));\n}\n\n/**\n * Resolve a shared prepared-store entry back into the dataset-state shape\n * consumed by `DeckJsonMap`.\n *\n * Prepared entries are shared by cache key, while `datasetId` stays a\n * view-level label used by layer binding and user-facing errors. When a shared\n * prepared entry is reused for a different dataset id, this helper remaps the\n * prepared payload so downstream callers still see the dataset id they asked\n * for.\n */\nexport function resolvePreparedDeckDatasetState(options: {\n  datasetId: string;\n  entry?: PreparedDatasetCacheEntry;\n}): PreparedDeckDatasetState {\n  const {datasetId, entry} = options;\n\n  if (!entry || entry.status === 'loading') {\n    return {status: 'loading'};\n  }\n\n  if (entry.status === 'error') {\n    return {status: 'error', error: entry.error};\n  }\n\n  return {\n    status: 'ready',\n    prepared:\n      entry.prepared.datasetId === datasetId\n        ? entry.prepared\n        : {\n            ...entry.prepared,\n            datasetId,\n          },\n  };\n}\n\n/**\n * Resolve the full `datasetId -> state` map for a dataset registry.\n *\n * This mirrors the lookup logic used by `DeckJsonMap`: unresolved Arrow\n * datasets remain `loading`, while resolvable datasets reuse shared prepared\n * entries keyed by data identity rather than by dataset id.\n */\nexport function resolvePreparedDeckDatasetStates(options: {\n  datasets: Record<string, DeckDatasetInput>;\n  entries: Record<string, PreparedDatasetCacheEntry>;\n  sqlSourceIdentity: object;\n}): Record<string, PreparedDeckDatasetState> {\n  const {datasets, entries, sqlSourceIdentity} = options;\n\n  return Object.fromEntries(\n    resolvePreparedDatasetDescriptors({datasets, sqlSourceIdentity}).map(\n      ({datasetId, cacheKey}) => [\n        datasetId,\n        resolvePreparedDeckDatasetState({\n          datasetId,\n          entry: cacheKey ? entries[cacheKey] : undefined,\n        }),\n      ],\n    ),\n  );\n}\n\n/**\n * Module-global prepared dataset cache shared by all `DeckJsonMap` instances.\n *\n * The cache stores only deck-specific prepared payloads, not raw query\n * results, and applies a small internal LRU policy so settled entries do not\n * grow without bound.\n */\nexport const preparedDatasetStore = createPreparedDatasetStore();\n"]}

package/dist/datasets/helpers.d.ts

@@ -0,0 +1,57 @@
+import type * as arrow from 'apache-arrow';
+import { type DeckDatasetInput } from '../types';
+import type { PreparedDatasetCacheEntry } from './types';
+export declare const DEFAULT_MAX_PREPARED_DATASET_ENTRIES = 20;
+/** Return a monotonic access timestamp used by the prepared-dataset LRU. */
+export declare function nextAccessTimestamp(): number;
+/**
+ * Assign a stable cache identity to an Arrow table object.
+ *
+ * Table identities are stored in a `WeakMap` so this cache does not extend the
+ * lifetime of tables once they are no longer referenced elsewhere.
+ */
+export declare function getTableIdentity(table: arrow.Table): string;
+/**
+ * Assign a stable cache identity to the current SQL source object.
+ *
+ * For SQL datasets we include the upstream DuckDB connector identity in the
+ * cache key so two rooms using the same SQL text do not accidentally share
+ * prepared results across different database instances.
+ */
+export declare function getSqlSourceIdentity(sqlSourceIdentity: object): string;
+export declare function buildGeometryKey(input: DeckDatasetInput): string;
+/**
+ * Build the canonical cache key for one dataset input.
+ *
+ * The key intentionally ignores the user-facing dataset id and instead uses
+ * the underlying data identity:
+ *
+ * - SQL datasets: DuckDB connector identity + SQL text + geometry options
+ * - Arrow datasets: table object identity + geometry options
+ *
+ * Unresolved Arrow inputs (`arrowTable: undefined`) return `undefined`, which
+ * signals that the dataset should remain in `loading` until a table exists.
+ */
+export declare function resolvePreparedDatasetCacheKey(options: {
+    input: DeckDatasetInput;
+    sqlSourceIdentity?: object;
+}): string | undefined;
+/**
+ * Clone a cache entry while replacing its consumer set and refreshing the
+ * access timestamp.
+ *
+ * This keeps the discriminated union shape intact while centralizing the
+ * bookkeeping needed by consumer reconciliation and LRU tracking.
+ */
+export declare function cloneEntryWithConsumers(entry: PreparedDatasetCacheEntry, consumers: Set<string>): PreparedDatasetCacheEntry;
+/** Mark an entry as recently used without changing its lifecycle payload. */
+export declare function touchEntry(entry: PreparedDatasetCacheEntry): PreparedDatasetCacheEntry;
+/**
+ * Evict least-recently-used settled entries when the cache exceeds capacity.
+ *
+ * Only `ready` and `error` entries participate in eviction. `loading` entries
+ * are preserved so in-flight work is not discarded, and referenced entries are
+ * preserved so active maps never lose their prepared data mid-render.
+ */
+export declare function evictLruEntries(entries: Record<string, PreparedDatasetCacheEntry>, maxEntries: number): Record<string, PreparedDatasetCacheEntry>;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/datasets/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/datasets/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAoB,KAAK,gBAAgB,EAAC,MAAM,UAAU,CAAC;AAElE,OAAO,KAAK,EAAC,yBAAyB,EAAC,MAAM,SAAS,CAAC;AAEvD,eAAO,MAAM,oCAAoC,KAAK,CAAC;AASvD,4EAA4E;AAC5E,wBAAgB,mBAAmB,IAAI,MAAM,CAG5C;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,GAAG,MAAM,CAU3D;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,iBAAiB,EAAE,MAAM,GAAG,MAAM,CAUtE;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAEhE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,8BAA8B,CAAC,OAAO,EAAE;IACtD,KAAK,EAAE,gBAAgB,CAAC;IACxB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,GAAG,MAAM,GAAG,SAAS,CA0BrB;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,yBAAyB,EAChC,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,GACrB,yBAAyB,CA2B3B;AAED,6EAA6E;AAC7E,wBAAgB,UAAU,CACxB,KAAK,EAAE,yBAAyB,GAC/B,yBAAyB,CAE3B;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,EAClD,UAAU,EAAE,MAAM,GACjB,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,CA8B3C"}

package/dist/datasets/helpers.js

@@ -0,0 +1,146 @@
+import { isSqlDatasetInput } from '../types';
+import { resolveArrowTable } from './normalizeDatasets';
+export const DEFAULT_MAX_PREPARED_DATASET_ENTRIES = 20;
+let nextDatasetAccess = 0;
+let nextTableIdentity = 0;
+let nextSqlSourceIdentity = 0;
+const tableIdentities = new WeakMap();
+const sqlSourceIdentities = new WeakMap();
+/** Return a monotonic access timestamp used by the prepared-dataset LRU. */
+export function nextAccessTimestamp() {
+    nextDatasetAccess += 1;
+    return nextDatasetAccess;
+}
+/**
+ * Assign a stable cache identity to an Arrow table object.
+ *
+ * Table identities are stored in a `WeakMap` so this cache does not extend the
+ * lifetime of tables once they are no longer referenced elsewhere.
+ */
+export function getTableIdentity(table) {
+    const cached = tableIdentities.get(table);
+    if (cached) {
+        return cached;
+    }
+    nextTableIdentity += 1;
+    const identity = `table:${nextTableIdentity}`;
+    tableIdentities.set(table, identity);
+    return identity;
+}
+/**
+ * Assign a stable cache identity to the current SQL source object.
+ *
+ * For SQL datasets we include the upstream DuckDB connector identity in the
+ * cache key so two rooms using the same SQL text do not accidentally share
+ * prepared results across different database instances.
+ */
+export function getSqlSourceIdentity(sqlSourceIdentity) {
+    const cached = sqlSourceIdentities.get(sqlSourceIdentity);
+    if (cached) {
+        return cached;
+    }
+    nextSqlSourceIdentity += 1;
+    const identity = `sql-source:${nextSqlSourceIdentity}`;
+    sqlSourceIdentities.set(sqlSourceIdentity, identity);
+    return identity;
+}
+export function buildGeometryKey(input) {
+    return `${input.geometryColumn ?? ''}\u0001${input.geometryEncodingHint ?? ''}`;
+}
+/**
+ * Build the canonical cache key for one dataset input.
+ *
+ * The key intentionally ignores the user-facing dataset id and instead uses
+ * the underlying data identity:
+ *
+ * - SQL datasets: DuckDB connector identity + SQL text + geometry options
+ * - Arrow datasets: table object identity + geometry options
+ *
+ * Unresolved Arrow inputs (`arrowTable: undefined`) return `undefined`, which
+ * signals that the dataset should remain in `loading` until a table exists.
+ */
+export function resolvePreparedDatasetCacheKey(options) {
+    const { input, sqlSourceIdentity } = options;
+    if (isSqlDatasetInput(input)) {
+        if (!sqlSourceIdentity) {
+            throw new Error('SQL dataset cache keys require a sqlSourceIdentity object.');
+        }
+        return [
+            'sql',
+            getSqlSourceIdentity(sqlSourceIdentity),
+            input.sqlQuery,
+            buildGeometryKey(input),
+        ].join('\u0001');
+    }
+    const table = resolveArrowTable(input);
+    if (!table) {
+        return undefined;
+    }
+    return ['arrow', getTableIdentity(table), buildGeometryKey(input)].join('\u0001');
+}
+/**
+ * Clone a cache entry while replacing its consumer set and refreshing the
+ * access timestamp.
+ *
+ * This keeps the discriminated union shape intact while centralizing the
+ * bookkeeping needed by consumer reconciliation and LRU tracking.
+ */
+export function cloneEntryWithConsumers(entry, consumers) {
+    const lastAccessedAt = nextAccessTimestamp();
+    if (entry.status === 'loading') {
+        return {
+            status: 'loading',
+            promise: entry.promise,
+            consumers,
+            lastAccessedAt,
+        };
+    }
+    if (entry.status === 'ready') {
+        return {
+            status: 'ready',
+            prepared: entry.prepared,
+            consumers,
+            lastAccessedAt,
+        };
+    }
+    return {
+        status: 'error',
+        error: entry.error,
+        consumers,
+        lastAccessedAt,
+    };
+}
+/** Mark an entry as recently used without changing its lifecycle payload. */
+export function touchEntry(entry) {
+    return cloneEntryWithConsumers(entry, new Set(entry.consumers));
+}
+/**
+ * Evict least-recently-used settled entries when the cache exceeds capacity.
+ *
+ * Only `ready` and `error` entries participate in eviction. `loading` entries
+ * are preserved so in-flight work is not discarded, and referenced entries are
+ * preserved so active maps never lose their prepared data mid-render.
+ */
+export function evictLruEntries(entries, maxEntries) {
+    const settledEntries = Object.entries(entries).filter(([, entry]) => entry.status !== 'loading');
+    if (settledEntries.length <= maxEntries) {
+        return entries;
+    }
+    const evictable = settledEntries
+        .filter(([, entry]) => entry.consumers.size === 0)
+        .sort(([, left], [, right]) => left.lastAccessedAt - right.lastAccessedAt);
+    if (evictable.length === 0) {
+        return entries;
+    }
+    const nextEntries = { ...entries };
+    let settledCount = settledEntries.length;
+    for (const [cacheKey] of evictable) {
+        if (settledCount <= maxEntries) {
+            break;
+        }
+        delete nextEntries[cacheKey];
+        settledCount -= 1;
+    }
+    return nextEntries;
+}
+//# sourceMappingURL=helpers.js.map