@sakuzu/maplibre-gl-draw 1.0.0 → 2.1.0

package/dist/api/impl/datasets.js

@@ -0,0 +1,405 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+import { DrawError } from '../errors.js';
+import { describeStyleProblem } from './import-export/style-validation.js';
+import { toBBox, toBoundingBox, toDatasetRow } from './rows.js';
+import { invalidInput, isRecord, notFound, onlyKeys, optionalIndex, requireId, requireIds, } from './shared.js';
+/**
+ * The range a query of the rows takes: a `BBox` of four or six finite numbers (it is required,
+ * so a call without one is an invalid input rather than a TypeError from deep inside)
+ */
+function requireBBox(bbox) {
+    if (!Array.isArray(bbox) ||
+        (bbox.length !== 4 && bbox.length !== 6) ||
+        bbox.some((value) => typeof value !== 'number' || !Number.isFinite(value))) {
+        throw invalidInput('bbox must be [west, south, east, north] in degrees');
+    }
+    return bbox;
+}
+const ORDERS = ['below-store', 'above-store', 'layer-order'];
+const OPTION_KEYS = [
+    'id',
+    'rows',
+    'table',
+    'provider',
+    'styleRule',
+    'baseStyle',
+    'interactive',
+    'order',
+    'zoomScale',
+    'collisionThinning',
+    'externalPointRender',
+];
+/** The names of the events of a dataset of the engine for those of the API */
+const EVENT_NAMES = {
+    clicked: 'click',
+    hovered: 'hover',
+    changed: 'change',
+};
+// ============================================================================
+// Checks
+// ============================================================================
+function checkBaseStyle(value) {
+    if (value === undefined)
+        return;
+    if (!isRecord(value))
+        throw invalidInput('baseStyle must be an object');
+    onlyKeys(value, ['point', 'stroke', 'fill'], 'baseStyle');
+    for (const [key, style] of Object.entries(value)) {
+        if (style === undefined)
+            continue;
+        const problem = describeStyleProblem(style);
+        if (problem)
+            throw invalidInput(`baseStyle.${key} is ${problem}`);
+    }
+}
+function checkThinning(value) {
+    if (value === undefined || value === null)
+        return;
+    if (!isRecord(value))
+        throw invalidInput('collisionThinning must be an object');
+    onlyKeys(value, ['enabled', 'fullDisplayZoom', 'marginPx'], 'collisionThinning');
+    if (value.enabled !== undefined && typeof value.enabled !== 'boolean') {
+        throw invalidInput('collisionThinning.enabled must be a boolean');
+    }
+    for (const key of ['fullDisplayZoom', 'marginPx']) {
+        const number = value[key];
+        if (number !== undefined && (typeof number !== 'number' || !Number.isFinite(number))) {
+            throw invalidInput(`collisionThinning.${key} must be a number`);
+        }
+    }
+}
+function checkFunction(value, what) {
+    if (value !== undefined && typeof value !== 'function') {
+        throw invalidInput(`${what} must be a function`);
+    }
+}
+function checkRows(value) {
+    if (!Array.isArray(value) || value.some((row) => !isRecord(row))) {
+        throw invalidInput('The rows must be an array of GeoJSON features');
+    }
+}
+function checkTable(value) {
+    if (!isRecord(value))
+        throw invalidInput('The table must be a table or a prepared table');
+}
+/** Checks what `datasets.add` takes */
+function checkOptions(options) {
+    if (!isRecord(options))
+        throw invalidInput('The options of a dataset must be an object');
+    onlyKeys(options, OPTION_KEYS, 'The options of a dataset');
+    requireId(options.id);
+    const sources = ['rows', 'table', 'provider'].filter((key) => options[key] !== undefined);
+    if (sources.length > 1) {
+        throw invalidInput('A dataset takes at most one of rows, table and provider');
+    }
+    if (options.rows !== undefined)
+        checkRows(options.rows);
+    if (options.table !== undefined)
+        checkTable(options.table);
+    checkFunction(options.provider, 'provider');
+    if (options.styleRule !== undefined && !isRecord(options.styleRule)) {
+        throw invalidInput('styleRule must be an object');
+    }
+    checkBaseStyle(options.baseStyle);
+    if (options.interactive !== undefined && typeof options.interactive !== 'boolean') {
+        throw invalidInput('interactive must be a boolean');
+    }
+    if (options.order !== undefined && !ORDERS.includes(options.order)) {
+        throw invalidInput(`order must be one of ${ORDERS.join(', ')}`);
+    }
+    checkFunction(options.zoomScale, 'zoomScale');
+    checkThinning(options.collisionThinning);
+    checkFunction(options.externalPointRender, 'externalPointRender');
+}
+/** Checks where a dataset goes */
+function checkPlacement(placement) {
+    if (!isRecord(placement))
+        throw invalidInput('The placement must be an object');
+    onlyKeys(placement, ['order', 'index'], 'The placement');
+    if (placement.order !== undefined && !ORDERS.includes(placement.order)) {
+        throw invalidInput(`order must be one of ${ORDERS.join(', ')}`);
+    }
+    optionalIndex(placement.index);
+    return placement;
+}
+// ============================================================================
+// The conversions
+// ============================================================================
+/** A predicate on rows as a predicate on the features of the engine */
+function onFeatures(predicate) {
+    return predicate ? (feature) => predicate(toDatasetRow(feature)) : undefined;
+}
+/** The options of the engine for the options of the API */
+function toEngineOptions(options) {
+    const result = { id: options.id };
+    if ('rows' in options && options.rows !== undefined) {
+        result.rows = options.rows;
+    }
+    if ('table' in options && options.table !== undefined)
+        result.table = options.table;
+    if ('provider' in options && options.provider !== undefined) {
+        const provider = options.provider;
+        result.provider = async (bounds, zoom) => (await provider(toBBox(bounds), zoom));
+    }
+    if (options.styleRule !== undefined)
+        result.styleRule = options.styleRule;
+    if (options.baseStyle !== undefined)
+        result.baseStyle = options.baseStyle;
+    if (options.interactive !== undefined)
+        result.interactive = options.interactive;
+    if (options.order !== undefined)
+        result.order = options.order;
+    if (options.zoomScale !== undefined)
+        result.zoomScale = options.zoomScale;
+    if (options.collisionThinning !== undefined) {
+        result.collisionThinning = options.collisionThinning;
+    }
+    if (options.externalPointRender !== undefined) {
+        result.externalPointRender = onFeatures(options.externalPointRender);
+    }
+    return result;
+}
+/** A point on the screen of a payload of the engine */
+function toScreenPoint(point) {
+    return point ? [point.x, point.y] : [Number.NaN, Number.NaN];
+}
+function toClicked(payload) {
+    return {
+        datasetId: payload.datasetId,
+        rowIndex: payload.row,
+        row: toDatasetRow(payload.feature),
+        lngLat: [payload.lngLat[0], payload.lngLat[1]],
+        point: toScreenPoint(payload.point),
+    };
+}
+function toHovered(payload) {
+    return {
+        datasetId: payload.datasetId,
+        rowIndex: payload.row,
+        row: payload.feature ? toDatasetRow(payload.feature) : null,
+        lngLat: [payload.lngLat[0], payload.lngLat[1]],
+        point: toScreenPoint(payload.point),
+    };
+}
+function toChanged(payload) {
+    return { reason: payload.reason === 'features' ? 'rows' : payload.reason };
+}
+// ============================================================================
+// Dataset
+// ============================================================================
+/**
+ * A dataset of the API over a dataset of the engine
+ *
+ * @internal
+ */
+export function wrapDataset(dataset) {
+    /** The handlers given to the engine, by event and listener, so that off finds them */
+    const handlers = new Map();
+    const on = (event, listener) => {
+        const name = EVENT_NAMES[event];
+        if (!name)
+            throw invalidInput(`There is no event ${JSON.stringify(event)} of a dataset`);
+        if (typeof listener !== 'function')
+            throw invalidInput('The listener must be a function');
+        const convert = (payload) => {
+            if (event === 'clicked')
+                return toClicked(payload);
+            if (event === 'hovered')
+                return toHovered(payload);
+            return toChanged(payload);
+        };
+        const handler = (payload) => listener(convert(payload));
+        const byListener = handlers.get(event) ?? new Map();
+        handlers.set(event, byListener);
+        const previous = byListener.get(listener);
+        if (previous)
+            dataset.off(name, previous);
+        byListener.set(listener, handler);
+        dataset.on(name, handler);
+        return () => off(event, listener);
+    };
+    const off = (event, listener) => {
+        const name = EVENT_NAMES[event];
+        const handler = handlers.get(event)?.get(listener);
+        if (!name || !handler)
+            return;
+        handlers.get(event)?.delete(listener);
+        dataset.off(name, handler);
+    };
+    return {
+        get id() {
+            return dataset.id;
+        },
+        get order() {
+            return dataset.order;
+        },
+        get interactive() {
+            return dataset.interactive;
+        },
+        get visible() {
+            return dataset.visible;
+        },
+        setVisible(visible) {
+            if (typeof visible !== 'boolean')
+                throw invalidInput('visible must be a boolean');
+            dataset.setVisible(visible);
+        },
+        setRows(rows) {
+            checkRows(rows);
+            dataset.setRows(rows);
+        },
+        setTable(table) {
+            checkTable(table);
+            dataset.setTable(table);
+        },
+        setStyleRule(rule) {
+            if (rule !== undefined && !isRecord(rule))
+                throw invalidInput('The rule must be an object');
+            dataset.setStyleRule(rule);
+        },
+        getStyleRule: () => dataset.getStyleRule(),
+        setZoomScale(zoomScale) {
+            if (zoomScale !== null)
+                checkFunction(zoomScale, 'zoomScale');
+            dataset.setZoomScale(zoomScale ?? null);
+        },
+        getZoomScale: () => dataset.getZoomScale(),
+        setBaseStyle(style) {
+            checkBaseStyle(style);
+            dataset.setBaseStyle(style);
+        },
+        setExternalPointRender(predicate) {
+            checkFunction(predicate, 'The predicate');
+            dataset.setExternalPointRender(onFeatures(predicate));
+        },
+        getBaseStyle: () => dataset.getBaseStyle(),
+        listRows: () => dataset.getFeatures().map(toDatasetRow),
+        listVisibleRows: (bbox) => dataset.collectVisible(toBoundingBox(requireBBox(bbox))).map(toDatasetRow),
+        listDrawnRows: (bbox) => dataset.collectDrawnRows(toBoundingBox(requireBBox(bbox))),
+        getRow(index) {
+            const feature = dataset.getRow(index);
+            return feature ? toDatasetRow(feature) : undefined;
+        },
+        getRowId: (index) => dataset.getRowId(index),
+        getRowType: (index) => dataset.getRowType(index),
+        getRowBounds(index) {
+            const bounds = dataset.getRowBounds(index);
+            return bounds ? toBBox(bounds) : null;
+        },
+        getRowPoint(index) {
+            const point = dataset.getRowPoint(index);
+            return point ? [point[0], point[1]] : null;
+        },
+        findRow: (id) => dataset.findRow(id),
+        setSelectedRowIds(ids) {
+            dataset.setSelectedIds(requireIds(ids));
+        },
+        getSelectedRowIds: () => dataset.getSelectedIds(),
+        setCollisionThinning(options) {
+            checkThinning(options);
+            dataset.setCollisionThinning(options ?? null);
+        },
+        getCollisionThinning() {
+            const thinning = dataset.getCollisionThinning();
+            return thinning ? { ...thinning } : null;
+        },
+        listVisibleRowIds: () => dataset.getVisibleFeatureIds(),
+        getThinningStats: () => dataset.getThinningStats(),
+        getDrawnRowsRevision: () => dataset.getDrawnRowsRevision(),
+        refresh: () => dataset.invalidateProviderCache(),
+        on,
+        off,
+    };
+}
+// ============================================================================
+// draw.datasets
+// ============================================================================
+/**
+ * Creates `draw.datasets` and announces the datasets that come, go and move as events
+ *
+ * @param manager - The dataset manager of the engine
+ * @param events - The emitter of the events of the instance
+ * @param signals - The internal emitter the manager announces the datasets on
+ * @internal
+ */
+export function createDatasets(manager, events, signals) {
+    const wrappers = new WeakMap();
+    const wrap = (dataset) => {
+        let wrapper = wrappers.get(dataset);
+        if (!wrapper) {
+            wrapper = wrapDataset(dataset);
+            wrappers.set(dataset, wrapper);
+        }
+        return wrapper;
+    };
+    let order = manager.list().map((dataset) => dataset.id);
+    signals.on('dataset.add', ({ datasetId }) => {
+        order = manager.list().map((dataset) => dataset.id);
+        const dataset = manager.get(datasetId);
+        if (dataset)
+            events.emit('dataset.added', { dataset: wrap(dataset) });
+    });
+    signals.on('dataset.remove', ({ datasetId }) => {
+        order = manager.list().map((dataset) => dataset.id);
+        events.emit('dataset.removed', { datasetId });
+    });
+    signals.on('dataset.reorder', ({ order: next }) => {
+        const previous = order;
+        order = [...next];
+        events.emit('dataset.reordered', { order: [...next], previous });
+    });
+    const require = (id) => {
+        const dataset = manager.get(requireId(id));
+        if (!dataset)
+            throw notFound('dataset', id);
+        return dataset;
+    };
+    const checkNew = (options, taken) => {
+        checkOptions(options);
+        if (manager.get(options.id) || taken.has(options.id)) {
+            throw new DrawError('already-exists', `A dataset with the ID ${options.id} exists`, {
+                id: options.id,
+            });
+        }
+        taken.add(options.id);
+        return options;
+    };
+    const collection = {
+        get(id) {
+            const dataset = manager.get(requireId(id));
+            return dataset ? wrap(dataset) : undefined;
+        },
+        list: () => manager.list().map(wrap),
+        count: () => manager.list().length,
+        has: (id) => manager.get(requireId(id)) !== undefined,
+        add(options) {
+            const checked = checkNew(options, new Set());
+            return wrap(manager.add(toEngineOptions(checked)));
+        },
+        addMany(options) {
+            if (!Array.isArray(options))
+                throw invalidInput('The options must be an array');
+            const taken = new Set();
+            const checked = options.map((entry) => checkNew(entry, taken));
+            return checked.map((entry) => wrap(manager.add(toEngineOptions(entry))));
+        },
+        remove(id) {
+            require(id);
+            return manager.remove(id);
+        },
+        removeMany(ids) {
+            const unique = requireIds(ids);
+            for (const id of unique)
+                require(id);
+            for (const id of unique)
+                manager.remove(id);
+            return true;
+        },
+        move(id, placement) {
+            require(id);
+            return manager.move(id, checkPlacement(placement));
+        },
+    };
+    return collection;
+}

package/dist/api/impl/destroy-guard.js

@@ -0,0 +1,74 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * The guard of a destroyed instance: once `destroy()` has run, every method of the draw instance
+ * and of its collections throws `DrawError('invalid-state')` instead of reaching an engine that
+ * has released everything
+ */
+import { DrawError } from '../errors.js';
+/** The error of a call made after destroy */
+function destroyedError(path) {
+    return new DrawError('invalid-state', `The draw instance is destroyed: ${path} cannot be called`, {
+        member: path,
+    });
+}
+/** Whether the value is a plain object whose members are guarded in turn */
+function isPlainObject(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+/**
+ * Copies an object with every method (at any depth of plain objects) guarded: a call after
+ * `isDestroyed()` turned true throws `DrawError('invalid-state')`, or rejects with it for a
+ * method that returns a promise. A getter is guarded the same way.
+ *
+ * @param target - The object to guard
+ * @param isDestroyed - Whether the instance is destroyed
+ * @param options - `asyncMembers` names the methods (by their path, such as `document.load`)
+ *   that reject instead of throwing; `skip` names the members that are copied unguarded
+ * @internal
+ */
+export function guardAfterDestroy(target, isDestroyed, options = {}, prefix = '') {
+    const guarded = {};
+    for (const [key, descriptor] of Object.entries(Object.getOwnPropertyDescriptors(target))) {
+        const path = `${prefix}${key}`;
+        if (options.skip?.has(path)) {
+            Object.defineProperty(guarded, key, descriptor);
+            continue;
+        }
+        if (descriptor.get) {
+            const get = descriptor.get;
+            Object.defineProperty(guarded, key, {
+                enumerable: descriptor.enumerable,
+                get() {
+                    if (isDestroyed())
+                        throw destroyedError(path);
+                    return get.call(target);
+                },
+            });
+            continue;
+        }
+        const value = descriptor.value;
+        if (typeof value === 'function') {
+            const rejects = options.asyncMembers?.has(path) === true;
+            guarded[key] = (...args) => {
+                if (isDestroyed()) {
+                    const error = destroyedError(path);
+                    if (rejects)
+                        return Promise.reject(error);
+                    throw error;
+                }
+                return value.apply(target, args);
+            };
+        }
+        else if (isPlainObject(value)) {
+            guarded[key] = guardAfterDestroy(value, isDestroyed, options, `${path}.`);
+        }
+        else {
+            guarded[key] = value;
+        }
+    }
+    return guarded;
+}