@scoova/mgl 1.0.0

package/src/source/rtl_text_plugin_main_thread.test.ts

@@ -0,0 +1,170 @@
+import {FakeServer, fakeServer} from 'nise';
+import {rtlMainThreadPluginFactory} from './rtl_text_plugin_main_thread';
+import {sleep} from '../util/test/util';
+import {browser} from '../util/browser';
+import {Dispatcher} from '../util/dispatcher';
+import {PluginState} from './rtl_text_plugin_status';
+import {MessageType} from '../util/actor_messages';
+const rtlMainThreadPlugin = rtlMainThreadPluginFactory();
+
+describe('RTLMainThreadPlugin', () => {
+    let server: FakeServer;
+    let broadcastSpy: jest.SpyInstance;
+    const url = 'http://example.com/plugin';
+    const failedToLoadMessage = `RTL Text Plugin failed to import scripts from ${url}`;
+    const SyncRTLPluginStateMessageName = MessageType.syncRTLPluginState;
+
+    beforeEach(() => {
+        server = fakeServer.create();
+        global.fetch = null;
+        // Reset the singleton instance before each test
+        rtlMainThreadPlugin.clearRTLTextPlugin();
+        broadcastSpy = jest.spyOn(Dispatcher.prototype, 'broadcast').mockImplementation(() => { return Promise.resolve({} as any); });
+    });
+
+    function broadcastMockSuccess(message: MessageType, payload: PluginState): Promise<PluginState[]> {
+        console.log('broadcastMockSuccessDefer', payload.pluginStatus);
+        if (message === SyncRTLPluginStateMessageName) {
+            if (payload.pluginStatus === 'loading') {
+                const resultState: PluginState = {
+                    pluginStatus: 'loaded',
+                    pluginURL: payload.pluginURL
+                };
+                return Promise.resolve([resultState]);
+            }
+        }
+    }
+
+    function broadcastMockSuccessDefer(message: MessageType, payload: PluginState): Promise<PluginState[]> {
+        if (message === SyncRTLPluginStateMessageName) {
+            if (payload.pluginStatus === 'deferred') {
+                const resultState: PluginState = {
+                    pluginStatus: 'deferred',
+                    pluginURL: payload.pluginURL
+                };
+                return Promise.resolve([resultState]);
+            }
+        }
+    }
+
+    function broadcastMockFailure(message: MessageType, payload: PluginState): Promise<PluginState[]> {
+        if (message === SyncRTLPluginStateMessageName) {
+            if (payload.pluginStatus === 'loading') {
+                return Promise.reject(failedToLoadMessage);
+            }
+        } else {
+            return Promise.resolve([]);
+        }
+    }
+
+    afterEach(() => {
+        server.restore();
+        broadcastSpy.mockRestore();
+    });
+
+    it('should get the RTL text plugin status', () => {
+        const status = rtlMainThreadPlugin.getRTLTextPluginStatus();
+        expect(status).toBe('unavailable');
+    });
+
+    it('should set the RTL text plugin and download it', async () => {
+        broadcastSpy = jest.spyOn(Dispatcher.prototype, 'broadcast').mockImplementation(broadcastMockSuccess as any);
+        await rtlMainThreadPlugin.setRTLTextPlugin(url);
+        expect(rtlMainThreadPlugin.url).toEqual(url);
+        expect(rtlMainThreadPlugin.status).toBe('loaded');
+    });
+
+    it('should set the RTL text plugin but deffer downloading', async () => {
+        await rtlMainThreadPlugin.setRTLTextPlugin(url, true);
+        expect(rtlMainThreadPlugin.status).toBe('deferred');
+        expect(broadcastSpy).toHaveBeenCalledWith(SyncRTLPluginStateMessageName, {pluginStatus: 'deferred', pluginURL: url});
+    });
+
+    it('should throw if the plugin is already set', async () => {
+        await rtlMainThreadPlugin.setRTLTextPlugin(url, true);
+        await expect(rtlMainThreadPlugin.setRTLTextPlugin(url)).rejects.toThrow('setRTLTextPlugin cannot be called multiple times.');
+    });
+
+    it('should throw if the plugin url is not set', async () => {
+        const spy = jest.spyOn(browser, 'resolveURL').mockImplementation(() => { return ''; });
+        await expect(rtlMainThreadPlugin.setRTLTextPlugin(null)).rejects.toThrow('requested url null is invalid');
+        spy.mockRestore();
+    });
+
+    it('should be in error state if download fails', async () => {
+        broadcastSpy = jest.spyOn(Dispatcher.prototype, 'broadcast').mockImplementation(broadcastMockFailure as any);
+        const resultPromise = rtlMainThreadPlugin.setRTLTextPlugin(url);
+        await expect(resultPromise).rejects.toBe(failedToLoadMessage);
+        expect(rtlMainThreadPlugin.url).toEqual(url);
+        expect(rtlMainThreadPlugin.status).toBe('error');
+    });
+
+    it('should lazy load the plugin if deferred', async () => {
+        // use success spy to make sure test case does not throw exception
+        const deferredSpy = jest.spyOn(Dispatcher.prototype, 'broadcast').mockImplementation(broadcastMockSuccessDefer as any);
+        await rtlMainThreadPlugin.setRTLTextPlugin(url, true);
+        expect(deferredSpy).toHaveBeenCalledTimes(1);
+        expect(deferredSpy).toHaveBeenCalledWith(SyncRTLPluginStateMessageName, {pluginStatus: 'deferred', pluginURL: url});
+        expect(rtlMainThreadPlugin.status).toBe('deferred');
+        deferredSpy.mockRestore();
+
+        // this is really a fire and forget
+        broadcastSpy = jest.spyOn(Dispatcher.prototype, 'broadcast').mockImplementation(broadcastMockSuccess as any);
+        rtlMainThreadPlugin.lazyLoad();
+        await sleep(1);
+
+        // 'loading'
+        expect(broadcastSpy).toHaveBeenCalledWith(SyncRTLPluginStateMessageName, {pluginStatus: 'loading', pluginURL: url});
+        expect(broadcastSpy).toHaveBeenCalledTimes(1);
+
+        // second call to lazyLoad should not change anything
+        rtlMainThreadPlugin.lazyLoad();
+        expect(broadcastSpy).toHaveBeenCalledTimes(1);
+
+        expect(rtlMainThreadPlugin.status).toBe('loaded');
+
+        // 3rd call to lazyLoad should not change anything
+        rtlMainThreadPlugin.lazyLoad();
+        expect(rtlMainThreadPlugin.status).toBe('loaded');
+        expect(broadcastSpy).toHaveBeenCalledTimes(1);
+    });
+
+    it('should set status to requested if RTL plugin was not set', async () => {
+        rtlMainThreadPlugin.lazyLoad();
+        expect(rtlMainThreadPlugin.status).toBe('requested');
+    });
+
+    it('should immediately download if RTL plugin was already requested, ignoring deferred:true', async () => {
+        broadcastSpy = jest.spyOn(Dispatcher.prototype, 'broadcast').mockImplementation(broadcastMockSuccess as any);
+        rtlMainThreadPlugin.lazyLoad();
+        expect(rtlMainThreadPlugin.status).toBe('requested');
+        await sleep(1);
+
+        // notice even when deferred is true, it should download because already requested
+        await rtlMainThreadPlugin.setRTLTextPlugin(url, true);
+        expect(rtlMainThreadPlugin.status).toBe('loaded');
+        expect(broadcastSpy).toHaveBeenCalledWith(SyncRTLPluginStateMessageName, {pluginStatus: 'loading', pluginURL: url});
+    });
+
+    it('should allow multiple calls to lazyLoad', async () => {
+        rtlMainThreadPlugin.lazyLoad();
+        expect(rtlMainThreadPlugin.status).toBe('requested');
+        rtlMainThreadPlugin.lazyLoad();
+        expect(rtlMainThreadPlugin.status).toBe('requested');
+    });
+
+    it('should be in error state if lazyLoad fails', async () => {
+        broadcastSpy = jest.spyOn(Dispatcher.prototype, 'broadcast').mockImplementation(broadcastMockSuccessDefer);
+        const resultPromise = rtlMainThreadPlugin.setRTLTextPlugin(url, true);
+        await expect(resultPromise).resolves.toBeUndefined();
+
+        expect(rtlMainThreadPlugin.status).toBe('deferred');
+
+        // the next one should fail
+        broadcastSpy = jest.spyOn(Dispatcher.prototype, 'broadcast').mockImplementation(broadcastMockFailure as any);
+
+        await expect(rtlMainThreadPlugin._requestImport()).rejects.toBe(failedToLoadMessage);
+        expect(rtlMainThreadPlugin.url).toEqual(url);
+        expect(rtlMainThreadPlugin.status).toBe('error');
+    });
+});

package/src/source/rtl_text_plugin_main_thread.ts

@@ -0,0 +1,89 @@
+
+import {browser} from '../util/browser';
+import {Event, Evented} from '../util/evented';
+import {RTLPluginStatus, RTLPluginLoadedEventName, PluginState} from './rtl_text_plugin_status';
+import {Dispatcher, getGlobalDispatcher} from '../util/dispatcher';
+import {MessageType} from '../util/actor_messages';
+
+class RTLMainThreadPlugin extends Evented {
+    status: RTLPluginStatus = 'unavailable';
+    url: string = null;
+    dispatcher: Dispatcher = getGlobalDispatcher();
+
+    /** Sync RTL plugin state by broadcasting a message to the worker */
+    _syncState(statusToSend: RTLPluginStatus): Promise<PluginState[]> {
+        this.status = statusToSend;
+        return this.dispatcher.broadcast(MessageType.syncRTLPluginState, {pluginStatus: statusToSend, pluginURL: this.url})
+            .catch((e: any) => {
+                this.status = 'error';
+                throw e;
+            });
+    }
+
+    /** This one is exposed to outside */
+    getRTLTextPluginStatus(): RTLPluginStatus {
+        return this.status;
+    }
+
+    clearRTLTextPlugin(): void {
+        this.status = 'unavailable';
+        this.url = null;
+    }
+
+    async setRTLTextPlugin(url: string, deferred: boolean = false): Promise<void> {
+        if (this.url) {
+            // error
+            throw new Error('setRTLTextPlugin cannot be called multiple times.');
+        }
+
+        this.url = browser.resolveURL(url);
+        if (!this.url) {
+            throw new Error(`requested url ${url} is invalid`);
+        }
+        if (this.status === 'unavailable') {
+
+            // from initial state:
+            if (deferred) {
+
+                this.status = 'deferred';
+                // fire and forget: in this case it does not need wait for the broadcasting result
+                // it is important to sync the deferred status once because
+                // symbol_bucket will be checking it in worker
+                this._syncState(this.status);
+
+            } else {
+                return this._requestImport();
+            }
+
+        } else if (this.status === 'requested') {
+            return this._requestImport();
+        }
+    }
+
+    /** Send a message to worker which will import the RTL plugin script */
+    async _requestImport() : Promise<void> {
+
+        // all errors/exceptions will be handled by _syncState
+        await this._syncState('loading');
+        this.status = 'loaded';
+        this.fire(new Event(RTLPluginLoadedEventName));
+    }
+
+    /** Start a lazy loading process of RTL plugin */
+    lazyLoad(): void {
+        if (this.status === 'unavailable') {
+            this.status = 'requested';
+        } else if (this.status === 'deferred') {
+            this._requestImport();
+        }
+    }
+}
+
+let rtlMainThreadPlugin: RTLMainThreadPlugin = null;
+
+export function rtlMainThreadPluginFactory(): RTLMainThreadPlugin {
+    if (!rtlMainThreadPlugin) {
+        rtlMainThreadPlugin = new RTLMainThreadPlugin();
+    }
+    return rtlMainThreadPlugin;
+}

package/src/source/rtl_text_plugin_status.ts

@@ -0,0 +1,33 @@
+/**
+ * The possible option of the plugin's status
+ *
+ * `unavailable`: Not loaded.
+ *
+ * `deferred`: The plugin URL has been specified, but loading has been deferred.
+ *
+ * `requested`: at least one tile needs RTL to render, but the plugin has not been set
+ *
+ * `loading`: RTL is in the process of being loaded by worker.
+ *
+ * `loaded`: The plugin is now loaded
+ *
+ *  `error`: The plugin failed to load
+ */
+export type RTLPluginStatus =
+                'unavailable' |
+                'deferred' |
+                'requested' |
+                'loading' |
+                'loaded' |
+                'error';
+
+/**
+ * The RTL plugin state
+ */
+export type PluginState = {
+    pluginStatus: RTLPluginStatus;
+    pluginURL: string;
+};
+
+export const RTLPluginLoadedEventName = 'RTLPluginLoaded';
+

package/src/source/rtl_text_plugin_worker.ts

@@ -0,0 +1,49 @@
+import {PluginState, RTLPluginStatus} from './rtl_text_plugin_status';
+
+export interface RTLTextPlugin {
+    applyArabicShaping: (a: string) => string;
+    processBidirectionalText: ((b: string, a: Array<number>) => Array<string>);
+    processStyledBidirectionalText: ((c: string, b: Array<number>, a: Array<number>) => Array<[string, Array<number>]>);
+}
+
+class RTLWorkerPlugin implements RTLTextPlugin {
+    applyArabicShaping: (a: string) => string = null;
+    processBidirectionalText: ((b: string, a: Array<number>) => Array<string>) = null;
+    processStyledBidirectionalText: ((c: string, b: Array<number>, a: Array<number>) => Array<[string, Array<number>]>) = null;
+    pluginStatus: RTLPluginStatus = 'unavailable';
+    pluginURL: string = null;
+
+    setState(state: PluginState) {
+        this.pluginStatus = state.pluginStatus;
+        this.pluginURL = state.pluginURL;
+    }
+
+    getState(): PluginState {
+        return {
+            pluginStatus: this.pluginStatus,
+            pluginURL: this.pluginURL
+        };
+    }
+
+    setMethods(rtlTextPlugin: RTLTextPlugin) {
+        this.applyArabicShaping = rtlTextPlugin.applyArabicShaping;
+        this.processBidirectionalText = rtlTextPlugin.processBidirectionalText;
+        this.processStyledBidirectionalText = rtlTextPlugin.processStyledBidirectionalText;
+    }
+
+    isParsed(): boolean {
+        return this.applyArabicShaping != null &&
+            this.processBidirectionalText != null &&
+            this.processStyledBidirectionalText != null;
+    }
+
+    getPluginURL(): string {
+        return this.pluginURL;
+    }
+
+    getRTLTextPluginStatus() {
+        return this.pluginStatus;
+    }
+}
+
+export const rtlWorkerPlugin = new RTLWorkerPlugin();

package/src/source/source.test.ts

@@ -0,0 +1,41 @@
+import {Dispatcher} from '../util/dispatcher';
+import {SourceClass, addSourceType, create} from './source';
+
+describe('addSourceType', () => {
+    test('adds factory function without a worker url does not dispatch to worker', async () => {
+        const sourceType = jest.fn().mockImplementation(function (id) { this.id = id; }) as SourceClass;
+
+        // expect no call to load worker source
+        const spy = jest.spyOn(Dispatcher.prototype, 'broadcast');
+
+        await addSourceType('foo', sourceType);
+        expect(spy).not.toHaveBeenCalled();
+
+        create('id', {type: 'foo'} as any, null, null);
+        expect(sourceType).toHaveBeenCalled();
+    });
+
+    test('create a custom source without an id throws', async () => {
+        const sourceType = jest.fn() as SourceClass;
+
+        // expect no call to load worker source
+        const spy = jest.spyOn(Dispatcher.prototype, 'broadcast');
+
+        await addSourceType('foo2', sourceType);
+        expect(spy).not.toHaveBeenCalled();
+
+        expect(() => create('id', {type: 'foo2'} as any, null, null)).toThrow();
+        expect(sourceType).toHaveBeenCalled();
+    });
+
+    test('refuses to add new type over existing name', async () => {
+        const sourceType = function () {} as any as SourceClass;
+        await expect(addSourceType('canvas', sourceType)).rejects.toThrow();
+        await expect(addSourceType('geojson', sourceType)).rejects.toThrow();
+        await expect(addSourceType('image', sourceType)).rejects.toThrow();
+        await expect(addSourceType('raster', sourceType)).rejects.toThrow();
+        await expect(addSourceType('raster-dem', sourceType)).rejects.toThrow();
+        await expect(addSourceType('vector', sourceType)).rejects.toThrow();
+        await expect(addSourceType('video', sourceType)).rejects.toThrow();
+    });
+});

package/src/source/source.ts

@@ -0,0 +1,186 @@
+import {VectorTileSource} from '../source/vector_tile_source';
+import {RasterTileSource} from '../source/raster_tile_source';
+import {RasterDEMTileSource} from '../source/raster_dem_tile_source';
+import {GeoJSONSource} from '../source/geojson_source';
+import {VideoSource} from '../source/video_source';
+import {ImageSource} from '../source/image_source';
+import {CanvasSource} from '../source/canvas_source';
+import {Dispatcher} from '../util/dispatcher';
+
+import type {SourceSpecification} from '@maplibre/maplibre-gl-style-spec';
+import type {Event, Evented} from '../util/evented';
+import type {Map} from '../ui/map';
+import type {Tile} from './tile';
+import type {OverscaledTileID, CanonicalTileID} from './tile_id';
+import type {CanvasSourceSpecification} from '../source/canvas_source';
+
+const registeredSources = {} as {[key:string]: SourceClass};
+
+/**
+ * The `Source` interface must be implemented by each source type, including "core" types (`vector`, `raster`,
+ * `video`, etc.) and all custom, third-party types.
+ *
+ * **Event** `data` - Fired with `{dataType: 'source', sourceDataType: 'metadata'}` to indicate that any necessary metadata
+ * has been loaded so that it's okay to call `loadTile`; and with `{dataType: 'source', sourceDataType: 'content'}`
+ * to indicate that the source data has changed, so that any current caches should be flushed.
+ *
+ * @group Sources
+ */
+export interface Source {
+    readonly type: string;
+    /**
+     * The id for the source. Must not be used by any existing source.
+     */
+    id: string;
+    /**
+     * The minimum zoom level for the source.
+     */
+    minzoom: number;
+    /**
+     * The maximum zoom level for the source.
+     */
+    maxzoom: number;
+    /**
+     * The tile size for the source.
+     */
+    tileSize: number;
+    /**
+     * The attribution for the source.
+     */
+    attribution?: string;
+    /**
+     * `true` if zoom levels are rounded to the nearest integer in the source data, `false` if they are floor-ed to the nearest integer.
+     */
+    roundZoom?: boolean;
+    /**
+     * `false` if tiles can be drawn outside their boundaries, `true` if they cannot.
+     */
+    isTileClipped?: boolean;
+    tileID?: CanonicalTileID;
+    /**
+     * `true` if tiles should be sent back to the worker for each overzoomed zoom level, `false` if not.
+     */
+    reparseOverscaled?: boolean;
+    vectorLayerIds?: Array<string>;
+    /**
+     * True if the source has transition, false otherwise.
+     */
+    hasTransition(): boolean;
+    /**
+     * True if the source is loaded, false otherwise.
+     */
+    loaded(): boolean;
+    /**
+     * An ability to fire an event to all the listeners, see {@link Evented}
+     * @param event - The event to fire
+     */
+    fire(event: Event): unknown;
+    /**
+     * This method is called when the source is added to the map.
+     * @param map - The map instance
+     */
+    onAdd?(map: Map): void;
+    /**
+     * This method is called when the source is removed from the map.
+     * @param map - The map instance
+     */
+    onRemove?(map: Map): void;
+    /**
+     * This method does the heavy lifting of loading a tile.
+     * In most cases it will defer the work to the relevant worker source.
+     * @param tile - The tile to load
+     */
+    loadTile(tile: Tile): Promise<void>;
+    /**
+     * True is the tile is part of the source, false otherwise.
+     * @param tileID - The tile ID
+     */
+    hasTile?(tileID: OverscaledTileID): boolean;
+    /**
+     * Allows to abort a tile loading.
+     * @param tile - The tile to abort
+     */
+    abortTile?(tile: Tile): Promise<void>;
+    /**
+     * Allows to unload a tile.
+     * @param tile - The tile to unload
+     */
+    unloadTile?(tile: Tile): Promise<void>;
+    /**
+     * @returns A plain (stringifiable) JS object representing the current state of the source.
+     * Creating a source using the returned object as the `options` should result in a Source that is
+     * equivalent to this one.
+     */
+    serialize(): any;
+    /**
+     * Allows to execute a prepare step before the source is used.
+     */
+    prepare?(): void;
+}
+
+/**
+ * A general definition of a {@link Source} class for factory usage
+ */
+export type SourceClass = {
+    new (id: string, specification: SourceSpecification | CanvasSourceSpecification, dispatcher: Dispatcher, eventedParent: Evented): Source;
+}
+
+/**
+ * Creates a tiled data source instance given an options object.
+ *
+ * @param id - The id for the source. Must not be used by any existing source.
+ * @param specification - Source options, specific to the source type (except for `options.type`, which is always required).
+ * @param source - A source definition object compliant with
+ * [`maplibre-gl-style-spec`](https://maplibre.org/maplibre-style-spec/#sources) or, for a third-party source type,
+  * with that type's requirements.
+ * @param dispatcher - A {@link Dispatcher} instance, which can be used to send messages to the workers.
+ * @returns a newly created source
+ */
+export const create = (id: string, specification: SourceSpecification | CanvasSourceSpecification, dispatcher: Dispatcher, eventedParent: Evented): Source => {
+
+    const Class = getSourceType(specification.type);
+    const source = new Class(id, specification, dispatcher, eventedParent);
+
+    if (source.id !== id) {
+        throw new Error(`Expected Source id to be ${id} instead of ${source.id}`);
+    }
+
+    return source;
+};
+
+const getSourceType = (name: string): SourceClass => {
+    switch (name) {
+        case 'geojson':
+            return GeoJSONSource;
+        case 'image':
+            return ImageSource;
+        case 'raster':
+            return RasterTileSource;
+        case 'raster-dem':
+            return RasterDEMTileSource;
+        case 'vector':
+            return VectorTileSource;
+        case 'video':
+            return VideoSource;
+        case 'canvas':
+            return CanvasSource;
+    }
+    return registeredSources[name];
+};
+
+const setSourceType = (name: string, type: SourceClass) => {
+    registeredSources[name] = type;
+};
+
+/**
+ * Adds a custom source type, making it available for use with {@link Map#addSource}.
+ * @param name - The name of the source type; source definition objects use this name in the `{type: ...}` field.
+ * @param SourceType - A {@link SourceClass} - which is a constructor for the `Source` interface.
+ * @returns a promise that is resolved when the source type is ready or rejected with an error.
+ */
+export const addSourceType = async (name: string, SourceType: SourceClass): Promise<void> => {
+    if (getSourceType(name)) {
+        throw new Error(`A source type called "${name}" already exists.`);
+    }
+    setSourceType(name, SourceType);
+};