@scoova/mgl 1.0.0

package/src/util/struct_array.ts

@@ -0,0 +1,246 @@
+// Note: all "sizes" are measured in bytes
+
+/**
+ * @internal
+ * A view type size
+ */
+const viewTypes = {
+    'Int8': Int8Array,
+    'Uint8': Uint8Array,
+    'Int16': Int16Array,
+    'Uint16': Uint16Array,
+    'Int32': Int32Array,
+    'Uint32': Uint32Array,
+    'Float32': Float32Array
+};
+
+/**
+ * @internal
+ * A view type size
+ */
+export type ViewType = keyof typeof viewTypes;
+
+/** @internal */
+class Struct {
+    _pos1: number;
+    _pos2: number;
+    _pos4: number;
+    _pos8: number;
+    readonly _structArray: StructArray;
+
+    // The following properties are defined on the prototype of sub classes.
+    size: number;
+
+    /**
+     * @param structArray - The StructArray the struct is stored in
+     * @param index - The index of the struct in the StructArray.
+     */
+    constructor(structArray: StructArray, index: number) {
+        (this as any)._structArray = structArray;
+        this._pos1 = index * this.size;
+        this._pos2 = this._pos1 / 2;
+        this._pos4 = this._pos1 / 4;
+        this._pos8 = this._pos1 / 8;
+    }
+}
+
+const DEFAULT_CAPACITY = 128;
+const RESIZE_MULTIPLIER = 5;
+
+/**
+ * @internal
+ * A struct array member
+ */
+export type StructArrayMember = {
+    name: string;
+    type: ViewType;
+    components: number;
+    offset: number;
+};
+
+export type StructArrayLayout = {
+    members: Array<StructArrayMember>;
+    size: number;
+    alignment: number;
+};
+
+/**
+ * An array that can be deserialized
+ */
+export type SerializedStructArray = {
+    length: number;
+    arrayBuffer: ArrayBuffer;
+};
+
+/**
+ * @internal
+ * `StructArray` provides an abstraction over `ArrayBuffer` and `TypedArray`
+ * making it behave like an array of typed structs.
+ *
+ * Conceptually, a StructArray is comprised of elements, i.e., instances of its
+ * associated struct type. Each particular struct type, together with an
+ * alignment size, determines the memory layout of a StructArray whose elements
+ * are of that type.  Thus, for each such layout that we need, we have
+ * a corresponding StructArrayLayout class, inheriting from StructArray and
+ * implementing `emplaceBack()` and `_refreshViews()`.
+ *
+ * In some cases, where we need to access particular elements of a StructArray,
+ * we implement a more specific subclass that inherits from one of the
+ * StructArrayLayouts and adds a `get(i): T` accessor that returns a structured
+ * object whose properties are proxies into the underlying memory space for the
+ * i-th element.  This affords the convenience of working with (seemingly) plain
+ * Javascript objects without the overhead of serializing/deserializing them
+ * into ArrayBuffers for efficient web worker transfer.
+ */
+abstract class StructArray {
+    capacity: number;
+    length: number;
+    isTransferred: boolean;
+    arrayBuffer: ArrayBuffer;
+    uint8: Uint8Array;
+
+    // The following properties are defined on the prototype.
+    members: Array<StructArrayMember>;
+    bytesPerElement: number;
+    abstract emplaceBack(...v: number[]);
+    abstract emplace(i: number, ...v: number[]);
+
+    constructor() {
+        this.isTransferred = false;
+        this.capacity = -1;
+        this.resize(0);
+    }
+
+    /**
+     * Serialize a StructArray instance.  Serializes both the raw data and the
+     * metadata needed to reconstruct the StructArray base class during
+     * deserialization.
+     */
+    static serialize(array: StructArray, transferables?: Array<Transferable>): SerializedStructArray {
+
+        array._trim();
+
+        if (transferables) {
+            array.isTransferred = true;
+            transferables.push(array.arrayBuffer);
+        }
+
+        return {
+            length: array.length,
+            arrayBuffer: array.arrayBuffer,
+        };
+    }
+
+    static deserialize(input: SerializedStructArray) {
+        const structArray = Object.create(this.prototype);
+        structArray.arrayBuffer = input.arrayBuffer;
+        structArray.length = input.length;
+        structArray.capacity = input.arrayBuffer.byteLength / structArray.bytesPerElement;
+        structArray._refreshViews();
+        return structArray;
+    }
+
+    /**
+     * Resize the array to discard unused capacity.
+     */
+    _trim() {
+        if (this.length !== this.capacity) {
+            this.capacity = this.length;
+            this.arrayBuffer = this.arrayBuffer.slice(0, this.length * this.bytesPerElement);
+            this._refreshViews();
+        }
+    }
+
+    /**
+     * Resets the length of the array to 0 without de-allocating capacity.
+     */
+    clear() {
+        this.length = 0;
+    }
+
+    /**
+     * Resize the array.
+     * If `n` is greater than the current length then additional elements with undefined values are added.
+     * If `n` is less than the current length then the array will be reduced to the first `n` elements.
+     * @param n - The new size of the array.
+     */
+    resize(n: number) {
+        this.reserve(n);
+        this.length = n;
+    }
+
+    /**
+     * Indicate a planned increase in size, so that any necessary allocation may
+     * be done once, ahead of time.
+     * @param n - The expected size of the array.
+     */
+    reserve(n: number) {
+        if (n > this.capacity) {
+            this.capacity = Math.max(n, Math.floor(this.capacity * RESIZE_MULTIPLIER), DEFAULT_CAPACITY);
+            this.arrayBuffer = new ArrayBuffer(this.capacity * this.bytesPerElement);
+
+            const oldUint8Array = this.uint8;
+            this._refreshViews();
+            if (oldUint8Array) this.uint8.set(oldUint8Array);
+        }
+    }
+
+    /**
+     * Create TypedArray views for the current ArrayBuffer.
+     */
+    _refreshViews() {
+        throw new Error('_refreshViews() must be implemented by each concrete StructArray layout');
+    }
+}
+
+/**
+ * Given a list of member fields, create a full StructArrayLayout, in
+ * particular calculating the correct byte offset for each field.  This data
+ * is used at build time to generate StructArrayLayout_*#emplaceBack() and
+ * other accessors, and at runtime for binding vertex buffer attributes.
+ */
+function createLayout(
+    members: Array<{
+        name: string;
+        type: ViewType;
+        readonly components?: number;
+    }>,
+    alignment: number = 1
+): StructArrayLayout {
+
+    let offset = 0;
+    let maxSize = 0;
+    const layoutMembers = members.map((member) => {
+        const typeSize = sizeOf(member.type);
+        const memberOffset = offset = align(offset, Math.max(alignment, typeSize));
+        const components = member.components || 1;
+
+        maxSize = Math.max(maxSize, typeSize);
+        offset += typeSize * components;
+
+        return {
+            name: member.name,
+            type: member.type,
+            components,
+            offset: memberOffset,
+        };
+    });
+
+    const size = align(offset, Math.max(maxSize, alignment));
+
+    return {
+        members: layoutMembers,
+        size,
+        alignment
+    };
+}
+
+function sizeOf(type: ViewType): number {
+    return viewTypes[type].BYTES_PER_ELEMENT;
+}
+
+function align(offset: number, size: number): number {
+    return Math.ceil(offset / size) * size;
+}
+
+export {StructArray, Struct, viewTypes, createLayout};

package/src/util/style.test.ts

@@ -0,0 +1,34 @@
+import {coerceSpriteToArray} from './style';
+
+describe('style utils', () => {
+    describe('#coerceSpriteToArray', () => {
+        test('input === output when array', () => {
+            const inputSpriteArray = [{id: 'id', url: 'url'}];
+            const outputSpriteArray = coerceSpriteToArray(inputSpriteArray);
+            expect(outputSpriteArray).toHaveLength(1);
+            expect(outputSpriteArray[0].id).toBe('id');
+            expect(outputSpriteArray[0].url).toBe('url');
+        });
+
+        test('coerced to array when string', () => {
+            const expected = [{id: 'default', url: 'url'}];
+            expect(coerceSpriteToArray('url')).toEqual(expected);
+        });
+
+        test('returns an empty array when nothing\'s passed in', () => {
+            expect(coerceSpriteToArray()).toEqual([]);
+        });
+
+        test('duplicated entries should be removed', () => {
+            const spriteWithDuplicatedEntries = [
+                {id: 'sprite1', url: 'https://example.com'},
+                {id: 'sprite1', url: 'https://example.com'}];
+
+            const result = coerceSpriteToArray(spriteWithDuplicatedEntries);
+
+            expect(result).toHaveLength(1);
+            expect(result[0].id).toBe('sprite1');
+            expect(result[0].url).toBe('https://example.com');
+        });
+    });
+});

package/src/util/style.ts

@@ -0,0 +1,28 @@
+import type {SpriteSpecification} from '@maplibre/maplibre-gl-style-spec';
+
+/**
+ * Takes a SpriteSpecification value and returns it in its array form. If `undefined` is passed as an input value, an
+ * empty array is returned.
+ * duplicated entries with identical id/url will be removed in returned array
+ * @param sprite - optional sprite to coerce
+ * @returns an empty array in case `undefined` is passed; id-url pairs otherwise
+ */
+export function coerceSpriteToArray(sprite?: SpriteSpecification): {id: string; url: string}[] {
+    const resultArray: {id: string; url: string}[]  = [];
+
+    if (typeof sprite === 'string') {
+        resultArray.push({id: 'default', url: sprite});
+    } else if (sprite && sprite.length > 0) {
+        const dedupArray: string[] = [];
+        for (const {id, url} of sprite) {
+            const key = `${id}${url}`;
+            if (dedupArray.indexOf(key) === -1) {
+                dedupArray.push(key);
+                resultArray.push({id, url});
+            }
+        }
+    }
+
+    return resultArray;
+
+}

package/src/util/task_queue.test.ts

@@ -0,0 +1,114 @@
+import {TaskQueue} from './task_queue';
+
+describe('TaskQueue', () => {
+    test('Calls callbacks, in order', () => {
+        const q = new TaskQueue();
+        let first = 0;
+        let second = 0;
+        q.add(() => {
+            expect(++first).toBe(1);
+            expect(second).toBe(0);
+        });
+        q.add(() => {
+            expect(first).toBe(1);
+            expect(++second).toBe(1);
+        });
+        q.run();
+        expect(first).toBe(1);
+        expect(second).toBe(1);
+    });
+
+    test('Allows a given callback to be queued multiple times', () => {
+        const q = new TaskQueue();
+        const fn = jest.fn();
+        q.add(fn);
+        q.add(fn);
+        q.run();
+        expect(fn).toHaveBeenCalledTimes(2);
+    });
+
+    test('Does not call a callback that was cancelled before the queue was run', () => {
+        const q = new TaskQueue();
+        const yes = jest.fn();
+        const no = jest.fn();
+        q.add(yes);
+        const id = q.add(no);
+        q.remove(id);
+        q.run();
+        expect(yes).toHaveBeenCalledTimes(1);
+        expect(no).not.toHaveBeenCalled();
+    });
+
+    test('Does not call a callback that was cancelled while the queue was running', () => {
+        const q = new TaskQueue();
+        const yes = jest.fn();
+        const no = jest.fn();
+        q.add(yes);
+        let id; // eslint-disable-line prefer-const
+        q.add(() => q.remove(id));
+        id = q.add(no);
+        q.run();
+        expect(yes).toHaveBeenCalledTimes(1);
+        expect(no).not.toHaveBeenCalled();
+    });
+
+    test('Allows each instance of a multiply-queued callback to be cancelled independently', () => {
+        const q = new TaskQueue();
+        const cb = jest.fn();
+        q.add(cb);
+        const id = q.add(cb);
+        q.remove(id);
+        q.run();
+        expect(cb).toHaveBeenCalledTimes(1);
+    });
+
+    test('Does not throw if a remove() is called after running the queue', () => {
+        const q = new TaskQueue();
+        const cb = jest.fn();
+        const id = q.add(cb);
+        q.run();
+        q.remove(id);
+        expect(cb).toHaveBeenCalledTimes(1);
+    });
+
+    test('Does not add tasks to the currently-running queue', () => {
+        const q = new TaskQueue();
+        const cb = jest.fn();
+        q.add(() => q.add(cb));
+        q.run();
+        expect(cb).not.toHaveBeenCalled();
+        q.run();
+        expect(cb).toHaveBeenCalledTimes(1);
+    });
+
+    test('TaskQueue#run() throws on attempted re-entrance', () => {
+        const q = new TaskQueue();
+        q.add(() => q.run());
+        expect(() => q.run()).toThrow();
+    });
+
+    test('TaskQueue#clear() prevents queued task from being executed', () => {
+        const q = new TaskQueue();
+        const before = jest.fn();
+        const after = jest.fn();
+        q.add(before);
+        q.clear();
+        q.add(after);
+        q.run();
+        expect(before).not.toHaveBeenCalled();
+        expect(after).toHaveBeenCalledTimes(1);
+    });
+
+    test('TaskQueue#clear() interrupts currently-running queue', () => {
+        const q = new TaskQueue();
+        const before = jest.fn();
+        const after = jest.fn();
+        q.add(() => q.add(after));
+        q.add(() => q.clear());
+        q.add(before);
+        q.run();
+        expect(before).not.toHaveBeenCalled();
+        q.run();
+        expect(after).not.toHaveBeenCalled();
+    });
+});

package/src/util/task_queue.ts

@@ -0,0 +1,64 @@
+export type TaskID = number;
+
+type Task = {
+    callback: (timeStamp: number) => void;
+    id: TaskID;
+    cancelled: boolean;
+};
+
+export class TaskQueue {
+    _queue: Array<Task>;
+    _id: TaskID;
+    _cleared: boolean;
+    _currentlyRunning: Array<Task> | false;
+
+    constructor()  {
+        this._queue = [];
+        this._id = 0;
+        this._cleared = false;
+        this._currentlyRunning = false;
+    }
+
+    add(callback: (timeStamp: number) => void): TaskID {
+        const id = ++this._id;
+        const queue = this._queue;
+        queue.push({callback, id, cancelled: false});
+        return id;
+    }
+
+    remove(id: TaskID) {
+        const running = this._currentlyRunning;
+        const queue = running ? this._queue.concat(running) : this._queue;
+        for (const task of queue) {
+            if (task.id === id) {
+                task.cancelled = true;
+                return;
+            }
+        }
+    }
+
+    run(timeStamp: number = 0) {
+        if (this._currentlyRunning) throw new Error('Attempting to run(), but is already running.');
+        const queue = this._currentlyRunning = this._queue;
+
+        // Tasks queued by callbacks in the current queue should be executed
+        // on the next run, not the current run.
+        this._queue = [];
+
+        for (const task of queue) {
+            if (task.cancelled) continue;
+            task.callback(timeStamp);
+            if (this._cleared) break;
+        }
+
+        this._cleared = false;
+        this._currentlyRunning = false;
+    }
+
+    clear() {
+        if (this._currentlyRunning) {
+            this._cleared = true;
+        }
+        this._queue = [];
+    }
+}

package/src/util/test/util.ts

@@ -0,0 +1,185 @@
+import {Map} from '../../ui/map';
+import {extend} from '../../util/util';
+import {Dispatcher} from '../../util/dispatcher';
+import {IActor} from '../actor';
+import type {Evented} from '../evented';
+import {SourceSpecification, StyleSpecification} from '@maplibre/maplibre-gl-style-spec';
+
+export function createMap(options?, callback?) {
+    const container = window.document.createElement('div');
+    const defaultOptions = {
+        container,
+        interactive: false,
+        attributionControl: false,
+        maplibreLogo: false,
+        trackResize: true,
+        style: {
+            'version': 8,
+            'sources': {},
+            'layers': []
+        }
+    };
+
+    Object.defineProperty(container, 'clientWidth', {value: 200, configurable: true});
+    Object.defineProperty(container, 'clientHeight', {value: 200, configurable: true});
+
+    if (options?.deleteStyle) delete defaultOptions.style;
+
+    const map = new Map(extend(defaultOptions, options));
+    if (callback) map.on('load', () => {
+        callback(null, map);
+    });
+
+    return map;
+}
+
+export function equalWithPrecision(test, expected, actual, multiplier, message, extra) {
+    message = message || `should be equal to within ${multiplier}`;
+    const expectedRounded = Math.round(expected / multiplier) * multiplier;
+    const actualRounded = Math.round(actual / multiplier) * multiplier;
+
+    return test.equal(expectedRounded, actualRounded, message, extra);
+}
+
+export function setPerformance() {
+    window.performance.mark = jest.fn();
+    window.performance.clearMeasures = jest.fn();
+    window.performance.clearMarks = jest.fn();
+}
+
+export function setMatchMedia() {
+    // https://jestjs.io/docs/manual-mocks#mocking-methods-which-are-not-implemented-in-jsdom
+    Object.defineProperty(window, 'matchMedia', {
+        writable: true,
+        value: jest.fn().mockImplementation(query => ({
+            matches: false,
+            media: query,
+            onchange: null,
+            addListener: jest.fn(), // deprecated
+            removeListener: jest.fn(), // deprecated
+            addEventListener: jest.fn(),
+            removeEventListener: jest.fn(),
+            dispatchEvent: jest.fn(),
+        })),
+    });
+}
+
+function setResizeObserver() {
+    global.ResizeObserver = jest.fn().mockImplementation(() => ({
+        observe: jest.fn(),
+        unobserve: jest.fn(),
+        disconnect: jest.fn(),
+    }));
+}
+
+export function beforeMapTest() {
+    setPerformance();
+    setMatchMedia();
+    setResizeObserver();
+    // remove the following when the following is merged and released: https://github.com/Adamfsk/jest-webgl-canvas-mock/pull/5
+    (WebGLRenderingContext.prototype as any).bindVertexArray = WebGLRenderingContext.prototype.getExtension('OES_vertex_array_object').bindVertexArrayOES;
+    (WebGLRenderingContext.prototype as any).createVertexArray = WebGLRenderingContext.prototype.getExtension('OES_vertex_array_object').createVertexArrayOES;
+    if (!WebGLRenderingContext.prototype.drawingBufferHeight && !WebGLRenderingContext.prototype.drawingBufferWidth) {
+        Object.defineProperty(WebGLRenderingContext.prototype, 'drawingBufferWidth', {
+            get: jest.fn(),
+            configurable: true,
+        });
+        Object.defineProperty(WebGLRenderingContext.prototype, 'drawingBufferHeight', {
+            get: jest.fn(),
+            configurable: true,
+        });
+    }
+}
+
+export function getWrapDispatcher() {
+    const wrapDispatcher = (actor: IActor) => {
+        return {
+            getActor() {
+                return actor;
+            }
+        } as any as Dispatcher;
+    };
+
+    return wrapDispatcher;
+}
+
+export function getMockDispatcher() {
+    const wrapDispatcher = getWrapDispatcher();
+
+    const mockDispatcher = wrapDispatcher({
+        sendAsync() { return Promise.resolve({}); },
+    });
+
+    return mockDispatcher;
+}
+
+export function stubAjaxGetImage(createImageBitmap) {
+    global.createImageBitmap = createImageBitmap;
+
+    global.URL.revokeObjectURL = () => {};
+    global.URL.createObjectURL = (_) => { return null; };
+
+    // eslint-disable-next-line accessor-pairs
+    Object.defineProperty(global.Image.prototype, 'src', {
+        set(url: string) {
+            if (url === 'error') {
+                this.onerror();
+            } else if (this.onload) {
+                this.onload();
+            }
+        }
+    });
+}
+
+/**
+ * This should be used in test that use nise since the internal buffer returned from a file is not an instance of ArrayBuffer for some reason.
+ * @param data - the data read from a file, for example by `fs.readFileSync(...)`
+ * @returns a copy of the data in the file in `ArrayBuffer` format
+ */
+export function bufferToArrayBuffer(data: Buffer): ArrayBuffer {
+    const newBuffer = new ArrayBuffer(data.buffer.byteLength);
+    const view = new Uint8Array(newBuffer);
+    data.copy(view);
+    return view.buffer;
+}
+
+/**
+ * This allows test to wait for a certain amount of time before continuing.
+ * @param milliseconds - the amount of time to wait in milliseconds
+ * @returns - a promise that resolves after the specified amount of time
+ */
+export const sleep = (milliseconds: number = 0) => {
+    return new Promise<void>(resolve => setTimeout(resolve, milliseconds));
+};
+
+export function waitForMetadataEvent(source: Evented): Promise<void> {
+    return new Promise((resolve) => {
+        source.on('data', (e) => {
+            if (e.sourceDataType === 'metadata') {
+                resolve();
+            }
+        });
+    });
+}
+
+export function createStyleSource() {
+    return {
+        type: 'geojson',
+        data: {
+            type: 'FeatureCollection',
+            features: []
+        }
+    } as SourceSpecification;
+}
+
+export function createStyle(): StyleSpecification {
+    return {
+        version: 8,
+        center: [-73.9749, 40.7736],
+        zoom: 12.5,
+        bearing: 29,
+        pitch: 50,
+        sources: {},
+        layers: []
+    };
+}