@loaders.gl/core 5.0.0-alpha.13 → 5.0.0-alpha.14

package/src/lib/api/parse.ts

@@ -97,8 +97,10 @@ export async function parse(
     loaders = undefined;
   }
 
+  (options?.signal || context?.signal)?.throwIfAborted();
   data = await data; // Resolve any promise
-  options = options || ({} as LoaderOptions); // Could be invalid...
+  options = options || ({} as LoaderOptions);
+  (options.signal || context?.signal)?.throwIfAborted(); // Could be invalid...
 
   // Extract a url for auto detection
   const url = getResourceUrl(data);
@@ -144,7 +146,6 @@ export async function parse(
   return await parseWithLoader(loader, data, strictOptions, context);
 }
 
-// TODO: support progress and abort
 // TODO - should accept loader.parseAsyncIterator and concatenate.
 async function parseWithLoader(
   loader: Loader,
@@ -152,6 +153,7 @@ async function parseWithLoader(
   options: StrictLoaderOptions,
   context: LoaderContext
 ): Promise<unknown> {
+  (options.signal || context.signal)?.throwIfAborted();
   validateWorkerVersion(loader);
 
   options = mergeOptions(loader.options, options);

package/src/lib/loader-utils/get-fetch-function.ts

@@ -25,7 +25,7 @@ export function getFetchFunction(
 
   // options.fetch can be a function
   if (typeof fetchOption === 'function') {
-    fetchFunction = fetchOption;
+    fetchFunction = fetchOption as FetchLike;
   } else if (isObject(fetchOption)) {
     fetchFunction = context?.fetch || fetchFile;
   } else if (context?.fetch) {
@@ -34,10 +34,12 @@ export function getFetchFunction(
     fetchFunction = fetchFile;
   }
 
+  const signal = loaderOptions.signal || context?.signal;
+  const requestOptions = isObject(fetchOption) ? (fetchOption as RequestInit) : undefined;
   return createAuthenticatedFetch({
     fetch: fetchFunction,
     credentials: loaderOptions.core?.credentials || [],
     authentications: loaderOptions.core?.authentications,
-    fetchOptions: isObject(fetchOption) ? (fetchOption as RequestInit) : undefined
+    fetchOptions: signal ? {...requestOptions, signal} : requestOptions
   });
 }

package/src/lib/loader-utils/loader-context.ts

@@ -31,6 +31,8 @@ export function getLoaderContext(
   if (parentContext) {
     return {
       ...parentContext,
+      signal: options.signal || parentContext.signal,
+      reportProgress: options.onProgress || parentContext.reportProgress,
       coreApi: parentContext.coreApi || context.coreApi || coreApi,
       _parse: parentContext._parse || context._parse,
       fetch: getFetchFunction(options, parentContext)
@@ -39,6 +41,8 @@ export function getLoaderContext(
 
   const newContext: LoaderContext = {
     ...context,
+    signal: options.signal || context.signal,
+    reportProgress: options.onProgress || context.reportProgress,
     fetch: getFetchFunction(options, context),
     coreApi: context.coreApi || coreApi
   };

package/src/lib/loader-utils/option-defaults.ts

@@ -24,6 +24,7 @@ export const DEFAULT_LOADER_OPTIONS: LoaderOptions = {
     CDN: 'https://unpkg.com/@loaders.gl',
     worker: true, // By default, use worker if provided by loader.
     workerThreshold: 0.1,
+    workerInBatches: undefined,
     maxConcurrency: 3, // How many worker instances should be created for each loader.
     maxMobileConcurrency: 1, // How many worker instances should be created for each loader on mobile devices.
     reuseWorkers: isBrowser, // By default reuse workers in browser (Node.js refuses to terminate if browsers are running)

package/src/lib/loader-utils/option-utils.ts

@@ -219,7 +219,7 @@ function validateOptionsObject(
   for (const key in options) {
     // If top level option value is an object it could options for a loader, so ignore
     const isSubOptions = !id && isObject(options[key]);
-    const isBaseUriOption = key === 'baseUri' && !id;
+    const isBaseUriOption = !id && ['baseUri', 'signal', 'onProgress'].includes(key);
     const isWorkerUrlOption = key === 'workerUrl' && id;
     // <loader>.workerUrl requires special handling as it is now auto-generated and no longer specified as a default option.
     if (!(key in defaultOptions) && !isBaseUriOption && !isWorkerUrlOption) {

package/src/loader-utils/index.ts

@@ -112,6 +112,7 @@ export {
   parseWithWorker,
   parseWithWorkerInBatches,
   canParseWithWorker,
+  canParseWithWorkerInBatches,
   shouldParseWithWorker
 } from './lib/worker-loader-utils/parse-with-worker';
 export {canEncodeWithWorker} from './lib/worker-loader-utils/encode-with-worker';

package/src/loader-utils/json-loader.ts

@@ -13,7 +13,7 @@ export type JSONLoaderOptions = LoaderOptions;
 
 /**
  * A JSON Micro loader (minimal bundle size)
- * Alternative to `@loaders.gl/json`
+ * Alternative to `@loaders.gl/tables/json`
  */
 export const JSONLoader = {
   dataType: null as unknown as Table,

package/src/loader-utils/lib/request-utils/request-credentials.ts

@@ -211,7 +211,9 @@ export class BearerTokenAuthentication extends TokenAuthentication {
   }
 }
 
-/** Wraps a fetch function with exact-origin credential application and one refresh replay. */
+/**
+ * Wraps fetch with exact-origin credentials and one refresh replay, preserving abort reasons.
+ */
 export function createAuthenticatedFetch(options: AuthenticatedFetchOptions): FetchLike {
   const suppliedFetch = options.fetch || ((url, requestOptions) => fetch(url, requestOptions));
   const existingMetadata = (
@@ -253,7 +255,7 @@ export function createAuthenticatedFetch(options: AuthenticatedFetchOptions): Fe
 
   const authenticatedFetch: FetchLike = async (url, requestOptions = {}) => {
     requestOptions = mergeFetchOptions(fetchOptions, requestOptions);
-    if (requestOptions.signal?.aborted) throw createAbortError();
+    requestOptions.signal?.throwIfAborted();
     // Request defaults alone must not normalize URLs or defer the transport invocation.
     if (!credentials.length) return baseFetch(url, requestOptions);
     const resolvedURL = parseHTTPURL(url);
@@ -283,7 +285,7 @@ export function createAuthenticatedFetch(options: AuthenticatedFetchOptions): Fe
         credential.refreshStatusCodes?.includes(response.status)
       );
     if (!refreshableCredentials.length && !shouldRetrySignature) return response;
-    if (requestOptions.signal?.aborted) throw createAbortError();
+    requestOptions.signal?.throwIfAborted();
 
     const refreshedTokens = new Map<RequestCredential, string>();
     await Promise.all(
@@ -295,7 +297,7 @@ export function createAuthenticatedFetch(options: AuthenticatedFetchOptions): Fe
     if (!refreshedTokens.size && !shouldRetrySignature) return response;
 
     await response.body?.cancel().catch(() => {});
-    if (requestOptions.signal?.aborted) throw createAbortError();
+    requestOptions.signal?.throwIfAborted();
     const replayAuthorization = resolvedURL
       ? await authorizeRequest(
           resolvedURL,
@@ -340,9 +342,10 @@ export function getAuthenticatedFetch(options: LoaderOptions = {}): FetchLike {
     fetchFunction = (url, requestOptions) => fetch(url, requestOptions);
   }
 
+  const fetchOptions = typeof fetchOption === 'object' && fetchOption ? fetchOption : undefined;
   return createAuthenticatedFetch({
     fetch: fetchFunction,
-    fetchOptions: typeof fetchOption === 'object' && fetchOption ? fetchOption : undefined,
+    fetchOptions: options.signal ? {...fetchOptions, signal: options.signal} : fetchOptions,
     credentials: options.core?.credentials || [],
     authentications: options.core?.authentications
   });
@@ -395,7 +398,7 @@ async function authenticateRequest(
   for (const credential of credentials) {
     const origin = getRequestOrigin(request.url);
     if (!origin || !normalizeRequestOrigins(credential.origins).includes(origin)) continue;
-    if (signal?.aborted) throw createAbortError();
+    signal?.throwIfAborted();
     const authenticatedRequest = await credential.authenticate({
       url: request.url,
       options: {...request.options, headers: new Headers(request.options.headers)},
@@ -418,7 +421,7 @@ async function authenticateRequest(
     };
     appliedCredentials.push(credential);
   }
-  if (signal?.aborted) throw createAbortError();
+  signal?.throwIfAborted();
   return {...request, credentials: appliedCredentials};
 }
 
@@ -569,8 +572,3 @@ function isReplayableRequest(options: RequestInit): boolean {
     options.body instanceof ReadableStream
   );
 }
-
-/** Creates the standard DOM exception used for an aborted fetch. */
-function createAbortError(): DOMException {
-  return new DOMException('The operation was aborted.', 'AbortError');
-}

package/src/loader-utils/lib/worker-loader-utils/create-loader-worker.ts

@@ -4,7 +4,14 @@
 
 /* eslint-disable no-restricted-globals */
 import type {CoreAPI} from '../sources/data-source';
-import type {LoaderWithParser, LoaderOptions, LoaderContext, Loader} from '../../loader-types';
+import type {
+  LoaderWithParser,
+  LoaderOptions,
+  StrictLoaderOptions,
+  LoaderContext,
+  Loader
+} from '../../loader-types';
+import type {WorkerContext} from '@loaders.gl/core/worker-utils';
 import {createWorker} from '@loaders.gl/core/worker-utils';
 // import {validateLoaderVersion} from './validate-loader-version';
 
@@ -43,6 +50,7 @@ export async function processLoaderWorkerData(
   input: ArrayBuffer,
   options: {[key: string]: any} = {},
   workerContext?: {
+    reportProgress?: WorkerContext['reportProgress'];
     process?: (data: any, options?: LoaderOptions, context?: Record<string, any>) => any;
   },
   loaderContext: Record<string, any> = {}
@@ -53,6 +61,7 @@ export async function processLoaderWorkerData(
     options,
     context: {
       ...loaderContext,
+      reportProgress: workerContext?.reportProgress,
       coreApi: createWorkerCoreApi(),
       _parse: createParseOnMainThread(workerContext?.process)
     } as LoaderContext
@@ -71,6 +80,7 @@ export async function* processLoaderWorkerBatches(
     | Iterable<ArrayBufferLike | ArrayBufferView>,
   options: {[key: string]: any} = {},
   workerContext?: {
+    reportProgress?: WorkerContext['reportProgress'];
     process?: (data: any, options?: LoaderOptions, context?: Record<string, any>) => any;
   },
   loaderContext: Record<string, any> = {}
@@ -79,8 +89,10 @@ export async function* processLoaderWorkerBatches(
     throw new Error(`${loader.id} loader does not support batched parsing`);
   }
 
-  const resultIterator = loader.parseInBatches(inputIterator, options, {
+  const parserOptions = getWorkerLoaderOptions(loader, options);
+  const resultIterator = loader.parseInBatches(inputIterator, parserOptions, {
     ...loaderContext,
+    reportProgress: workerContext?.reportProgress,
     coreApi: createWorkerCoreApi(),
     _parse: createParseOnMainThread(workerContext?.process)
   } as LoaderContext);
@@ -181,8 +193,17 @@ function getSerializableLoaderContext(context?: LoaderContext) {
   if (!context) {
     return undefined;
   }
-  const {fetch, loaders, coreApi, _parse, _parseSync, _parseInBatches, ...serializableContext} =
-    context;
+  const {
+    fetch,
+    loaders,
+    coreApi,
+    signal,
+    reportProgress,
+    _parse,
+    _parseSync,
+    _parseInBatches,
+    ...serializableContext
+  } = context;
   return JSON.parse(JSON.stringify(serializableContext));
 }
 
@@ -217,17 +238,19 @@ async function parseData({
   // Preserve worker-supplied module overrides (for example a caller-provided
   // Draco URL) while still applying the loader's defaults. Functions cannot be
   // structured-cloned, but URL strings and other serializable options can.
-  options = {
-    ...options,
-    modules: {
-      ...((loader && loader.options && loader.options.modules) || {}),
-      ...(options.modules || {})
-    },
-    core: {
-      ...options.core,
-      worker: false
-    }
-  };
+  options = getWorkerLoaderOptions(loader, options);
 
   return await parser(data, {...options}, context, loader);
 }
+
+/** Applies loader module defaults and prevents recursive worker dispatch inside a worker parser. */
+function getWorkerLoaderOptions(
+  loader: LoaderWithParser,
+  options: LoaderOptions
+): StrictLoaderOptions {
+  return {
+    ...options,
+    modules: {...loader.options?.modules, ...options.modules},
+    core: {...options.core, worker: false}
+  } as StrictLoaderOptions;
+}

package/src/loader-utils/lib/worker-loader-utils/parse-with-worker.ts

@@ -4,6 +4,7 @@
 
 import {
   canProcessOnWorker,
+  canProcessOnWorkerInBatches,
   isBrowser,
   processOnWorker,
   processOnWorkerInBatches
@@ -65,6 +66,27 @@ export function canParseWithWorker(loader: Loader, options?: StrictLoaderOptions
   return Boolean(canProcessOnWorker(loader, workerOptions));
 }
 
+/**
+ * Checks loader batch-parser transport capability and the selected worker's batch protocol.
+ * @param loader Loader declaring compatible batch parsing and transport.
+ * @param options Loader and worker selection options.
+ */
+export function canParseWithWorkerInBatches(
+  loader: Loader,
+  options?: StrictLoaderOptions
+): boolean {
+  // Encryption key callbacks must stay on the caller; JSON worker options omit functions.
+  const parquetOptions = options?.parquet as {keyRetriever?: unknown} | undefined;
+  if (loader.id === 'parquet' && typeof parquetOptions?.keyRetriever === 'function') {
+    return false;
+  }
+  return Boolean(
+    loader.workerInBatches &&
+      canParseWithWorker(loader, options) &&
+      canProcessOnWorkerInBatches(loader, getWorkerOptions(options))
+  );
+}
+
 /**
  * Determines whether an atomic parse should use a worker, including optional loader work estimates.
  * @param loader Loader metadata or parser-bearing loader.
@@ -118,11 +140,15 @@ export async function parseWithWorker(
   parseOnMainThread?: ParseOnMainThread,
   signal?: AbortSignal
 ) {
-  const workerSignal = signal || getWorkerAbortSignal(options);
+  const workerSignal = signal || getWorkerAbortSignal(options) || context?.signal;
   const result = await processOnWorker(
     loader,
     data,
-    {...getWorkerOptions(options, loader), signal: workerSignal},
+    {
+      ...getWorkerOptions(options, loader),
+      signal: workerSignal,
+      onProgress: options?.onProgress || context?.reportProgress
+    },
     {
       process: async (input, processOptions, _workerContext, parseContext) => {
         if (!parseOnMainThread) {
@@ -168,11 +194,15 @@ export async function* parseWithWorkerInBatches(
   parseOnMainThread?: ParseOnMainThread,
   signal?: AbortSignal
 ): AsyncIterable<unknown> {
-  const workerSignal = signal || getWorkerAbortSignal(options);
+  const workerSignal = signal || getWorkerAbortSignal(options) || context?.signal;
   const outputIterator = processOnWorkerInBatches(
     loader,
     inputIterator,
-    {...getWorkerOptions(options), signal: workerSignal},
+    {
+      ...getWorkerOptions(options, loader),
+      signal: workerSignal,
+      onProgress: options?.onProgress || context?.reportProgress
+    },
     {
       process: async (input, processOptions, _workerContext, parseContext) => {
         if (!parseOnMainThread) {
@@ -204,6 +234,7 @@ export async function* parseWithWorkerInBatches(
 
 /** Returns the loader-specific abort signal used to cancel a worker job. */
 function getWorkerAbortSignal(options?: StrictLoaderOptions): AbortSignal | undefined {
+  if (options?.signal) return options.signal;
   const parquetSignal = (options as {parquet?: {signal?: unknown}} | undefined)?.parquet?.signal;
   if (typeof AbortSignal !== 'undefined' && parquetSignal instanceof AbortSignal) {
     return parquetSignal;
@@ -278,10 +309,15 @@ function resolveWorkerLoaders(
 function getWorkerOptions(options: StrictLoaderOptions = {}, loader?: Loader) {
   const optionsToSerialize = {
     ...options,
+    signal: undefined,
+    onProgress: undefined,
     ...(options.core ? {core: {...options.core, authentications: undefined}} : {})
   };
   const serializedOptions = JSON.parse(
-    JSON.stringify(optionsToSerialize, (_key, value) => (typeof value === 'bigint' ? null : value))
+    JSON.stringify(optionsToSerialize, (_key, value) => {
+      if (typeof AbortSignal !== 'undefined' && value instanceof AbortSignal) return undefined;
+      return typeof value === 'bigint' ? null : value;
+    })
   );
   restoreBigIntOptions(optionsToSerialize, serializedOptions);
   const workerOptions: Record<string, any> = {
@@ -317,8 +353,17 @@ function getSerializableLoaderContext(context?: LoaderContext) {
   if (!context) {
     return {};
   }
-  const {fetch, loaders, coreApi, _parse, _parseSync, _parseInBatches, ...serializableContext} =
-    context;
+  const {
+    fetch,
+    loaders,
+    coreApi,
+    signal,
+    reportProgress,
+    _parse,
+    _parseSync,
+    _parseInBatches,
+    ...serializableContext
+  } = context;
   return JSON.parse(JSON.stringify(serializableContext));
 }
 

package/src/loader-utils/loader-types.ts

@@ -3,7 +3,7 @@
 // Copyright (c) vis.gl contributors
 
 import type {Format} from './format-types';
-import type {LoadWorker} from '@loaders.gl/core/worker-utils';
+import type {LoadWorker, WorkerOptions, WorkerProgress} from '@loaders.gl/core/worker-utils';
 import {DataType, FetchLike, TransformBatches} from './types';
 import {ReadableFile} from './lib/files/file';
 import type {CoreAPI} from './lib/sources/data-source';
@@ -18,7 +18,7 @@ export type SearchParams = Record<string, string | number | boolean>;
 /**
  * Core Loader Options
  */
-export type StrictLoaderOptions = {
+export type StrictLoaderOptions = Pick<WorkerOptions, 'signal' | 'onProgress'> & {
   /** Experimental common scan request. Format loaders implement the fields they support. */
   _scan?: ExperimentalScanOptions;
   /** Query parameters appended to the initial URL request. */
@@ -77,6 +77,8 @@ export type StrictLoaderOptions = {
     CDN?: string | null;
     /** Set to `false` to disable workers, or `'auto'` to use loader work estimates. */
     worker?: boolean | 'auto';
+    /** Declares batch support for a custom worker URL, or disables batch offloading. The loader must also advertise workerInBatches. */
+    workerInBatches?: boolean;
     /** Work-score threshold used by `worker: 'auto'`. */
     workerThreshold?: number;
     /** Number of concurrent workers (per loader) on desktop browser */
@@ -97,13 +99,17 @@ export type StrictLoaderOptions = {
   modules?: Record<string, unknown>;
 
   // Accept other keys (loader options objects, e.g. `options.csv`, `options.json` ...)
-  [loaderId: string]: Record<string, unknown> | undefined;
+  [loaderId: string]:
+    | Record<string, unknown>
+    | AbortSignal
+    | ((progress: WorkerProgress) => void)
+    | undefined;
 };
 
 /**
  * Core Loader Options
  */
-export type LoaderOptions = {
+export type LoaderOptions = Pick<WorkerOptions, 'signal' | 'onProgress'> & {
   /** Experimental common scan request. Format loaders implement the fields they support. */
   _scan?: ExperimentalScanOptions;
   /** Query parameters appended to the initial URL request. */
@@ -193,6 +199,8 @@ export type Loader<DataT = any, BatchT = any, LoaderOptionsT = StrictLoaderOptio
   version: string;
   /** A boolean, or a URL */
   worker?: string | boolean;
+  /** Whether the worker and its batch transport support this loader's batch parser. */
+  workerInBatches?: boolean;
   /** Browser worker filename when it differs from the loader id. */
   workerFile?: string;
   /** Optional Node.js worker filename, such as a CommonJS `.cjs` bundle. */
@@ -332,6 +340,10 @@ export type LoaderWithParser<
  *   threads back to main thread.
  */
 export type LoaderContext = {
+  /** Cancels nested asynchronous operations where supported. */
+  signal?: AbortSignal;
+  /** Reports progress within a loader-defined phase. */
+  reportProgress?: (progress: WorkerProgress) => void;
   /** Loader list provided to top-level loader call plus any sub loaders */
   loaders?: Loader[] | null;
   /** If URL is available.  */

package/src/schema-utils/lib/table/tables/convert-table.ts

@@ -112,7 +112,7 @@ export function convertToObjectRowTable(table: Table): ObjectRowTable {
 
 /**
  * Convert a table to apache arrow format
- * @note this depends on the `@loaders.gl/arrow module being imported
+ * @note this depends on the `@loaders.gl/tables/arrow module being imported
  */
 export function convertToArrowTable(table: Table): ArrowTable {
   const schema = table.schema || deduceTableSchema(table);

package/src/worker-utils/index.ts

@@ -10,6 +10,7 @@ export type {
   LoadWorker,
   WorkerObject,
   WorkerOptions,
+  WorkerProgress,
   WorkerContext,
   WorkerJobContext,
   Process,
@@ -41,7 +42,8 @@ export {
   processOnWorker,
   processOnWorkerInBatches,
   preloadWorker,
-  canProcessOnWorker
+  canProcessOnWorker,
+  canProcessOnWorkerInBatches
 } from './lib/worker-api/process-on-worker';
 export {createWorker} from './lib/worker-api/create-worker';
 

package/src/worker-utils/lib/worker-api/create-worker.ts

@@ -3,6 +3,7 @@
 // Copyright (c) vis.gl contributors
 
 import type {
+  WorkerProgress,
   WorkerMessageType,
   WorkerMessagePayload,
   WorkerContext,
@@ -42,6 +43,9 @@ export async function createWorker(
 
   // eslint-disable-next-line complexity
   WorkerBody.onmessage = async (type: WorkerMessageType, payload: WorkerMessagePayload) => {
+    const reporter =
+      type === 'process' || type === 'process-in-batches' ? createProgressReporter() : undefined;
+    const jobContext = {...context, reportProgress: reporter?.report};
     try {
       switch (type) {
         case 'preload':
@@ -55,9 +59,10 @@ export async function createWorker(
           const result = await process(
             payload.input,
             payload.options || {},
-            context,
+            jobContext,
             payload.context || {}
           );
+          reporter?.finish();
           WorkerBody.postMessage('done', {result});
           break;
 
@@ -73,13 +78,14 @@ export async function createWorker(
             const resultIterator = processInBatches(
               createDemandDrivenIterator(inputBatches),
               payload.options || {},
-              context,
+              jobContext,
               payload.context || {}
             );
             for await (const batch of resultIterator) {
               await WorkerBody.postMessage('output-batch', {result: batch});
               await outputAcknowledgements.next();
             }
+            reporter?.finish();
             await WorkerBody.postMessage('done', {});
           } finally {
             activeInputBatches = null;
@@ -111,6 +117,7 @@ export async function createWorker(
         default:
       }
     } catch (error) {
+      reporter?.finish();
       const message = error instanceof Error ? error.message : '';
       WorkerBody.postMessage('error', {error: message});
     }
@@ -164,3 +171,35 @@ function processOnMainThread(arrayBuffer: ArrayBuffer, options = {}, jobContext
     WorkerBody.postMessage('process', payload);
   });
 }
+
+/** Coalesces same-phase reports per event-loop turn and flushes before settlement. */
+function createProgressReporter() {
+  let pending: WorkerProgress | undefined;
+  let finished = false;
+  let scheduled = false;
+  /** Posts the latest pending measurement. */
+  const flush = (): void => {
+    scheduled = false;
+    if (pending) {
+      WorkerBody.postMessage('progress', {progress: pending});
+      pending = undefined;
+    }
+  };
+  return {
+    /** Records progress while retaining phase transitions. */
+    report(progress: WorkerProgress): void {
+      if (finished) return;
+      if (pending && pending.phase !== progress.phase) flush();
+      pending = {...progress};
+      if (!scheduled) {
+        scheduled = true;
+        setTimeout(flush, 0);
+      }
+    },
+    /** Flushes final progress and suppresses reports from stale callbacks. */
+    finish(): void {
+      flush();
+      finished = true;
+    }
+  };
+}

package/src/worker-utils/lib/worker-api/get-worker-url.ts

@@ -32,23 +32,10 @@ export function getCustomWorkerURL(
   worker: WorkerObject,
   options: WorkerOptions = {}
 ): string | null {
-  const workerOptions = options[worker.id] || {};
-
   const workerFile = isBrowser
     ? worker.workerFile || `${worker.id}-worker.js`
     : worker.workerNode || `${worker.id}-worker-node.js`;
-
-  let url = workerOptions.workerUrl;
-
-  // HACK: Allow for non-nested workerUrl for the CompressionWorker.
-  // For the compression worker, workerOptions is currently not nested correctly. For most loaders,
-  // you'd have options within an object, i.e. `{mvt: {coordinates: ...}}` but the CompressionWorker
-  // puts options at the top level, not within a `compression` key (its `id`). For this reason, the
-  // above `workerOptions` will always be a string (i.e. `'gzip'`) for the CompressionWorker. To not
-  // break backwards compatibility, we allow the CompressionWorker to have options at the top level.
-  if (!url && worker.id === 'compression') {
-    url = options.workerUrl;
-  }
+  let url = getConfiguredWorkerURL(worker, options);
 
   // If URL is test, generate local loaders.gl url
   // @ts-ignore _workerType
@@ -71,6 +58,18 @@ export function getCustomWorkerURL(
   return url || null;
 }
 
+/** Returns an explicit worker URL override, excluding generated local test URLs. */
+export function getConfiguredWorkerURL(
+  worker: WorkerObject,
+  options: WorkerOptions = {}
+): string | null {
+  const workerOptions = options[worker.id] || {};
+  // Compression also supports the historical non-nested URL override.
+  return (
+    workerOptions.workerUrl || (worker.id === 'compression' ? options.workerUrl : null) || null
+  );
+}
+
 /**
  * Generates a worker URL using overrides first and the published CDN artifact as a fallback.
  * @param worker Worker descriptor to resolve.