@loaders.gl/core 4.4.2 → 5.0.0-alpha.1

package/dist/dist.dev.js

@@ -39,10 +39,11 @@ var __exports__ = (() => {
     RequestScheduler: () => RequestScheduler,
     _BrowserFileSystem: () => BrowserFileSystem,
     _fetchProgress: () => fetchProgress,
-    _selectSource: () => selectSource2,
+    _selectSource: () => selectSource,
     _unregisterLoaders: () => _unregisterLoaders,
     assert: () => assert,
     concatenateArrayBuffersAsync: () => concatenateArrayBuffersAsync,
+    coreApi: () => coreApi,
     createDataSource: () => createDataSource,
     document: () => document_,
     encode: () => encode,
@@ -78,8 +79,11 @@ var __exports__ = (() => {
     makeTextDecoderIterator: () => makeTextDecoderIterator,
     makeTextEncoderIterator: () => makeTextEncoderIterator,
     parse: () => parse,
+    parseFile: () => parseFile,
     parseInBatches: () => parseInBatches,
     parseSync: () => parseSync,
+    preload: () => preload,
+    preloadSync: () => preloadSync,
     readArrayBuffer: () => readArrayBuffer,
     registerLoaders: () => registerLoaders,
     resolvePath: () => resolvePath,
@@ -706,16 +710,11 @@ var __exports__ = (() => {
   var NPM_TAG = "latest";
 
   // ../worker-utils/src/lib/env-utils/version.ts
-  var warningIssued = false;
   function getVersion() {
     if (!globalThis._loadersgl_?.version) {
       globalThis._loadersgl_ = globalThis._loadersgl_ || {};
-      if (typeof __VERSION__ === "undefined" && !warningIssued) {
-        console.warn(
-          "loaders.gl: The __VERSION__ variable is not injected using babel plugin. Latest unstable workers would be fetched from the CDN."
-        );
+      if (typeof __VERSION__ === "undefined") {
         globalThis._loadersgl_.version = NPM_TAG;
-        warningIssued = true;
       } else {
         globalThis._loadersgl_.version = __VERSION__;
       }
@@ -930,6 +929,18 @@ var __exports__ = (() => {
       this.worker.terminate();
       this.terminated = true;
     }
+    /** Keeps this worker from preventing Node.js process exit while idle. */
+    unref() {
+      if (!isBrowser3 && typeof this.worker.unref === "function") {
+        this.worker.unref();
+      }
+    }
+    /** Keeps this worker alive while it is actively processing a job. */
+    ref() {
+      if (!isBrowser3 && typeof this.worker.ref === "function") {
+        this.worker.ref();
+      }
+    }
     get isRunning() {
       return Boolean(this.onMessage);
     }
@@ -1000,7 +1011,7 @@ var __exports__ = (() => {
       worker.on("error", (error) => {
         this.onError(error);
       });
-      worker.on("exit", (code) => {
+      worker.on("exit", (_code) => {
       });
       return worker;
     }
@@ -1061,9 +1072,9 @@ var __exports__ = (() => {
         this.onDebug = props.onDebug;
       }
     }
-    async startJob(name, onMessage3 = (job, type, data) => job.done(data), onError = (job, error) => job.error(error)) {
+    async startJob(name, onMessage2 = (job, type, data) => job.done(data), onError = (job, error) => job.error(error)) {
       const startPromise = new Promise((onStart) => {
-        this.jobQueue.push({ name, onMessage: onMessage3, onError, onStart });
+        this.jobQueue.push({ name, onMessage: onMessage2, onError, onStart });
         return this;
       });
       this._startQueuedJob();
@@ -1091,13 +1102,13 @@ var __exports__ = (() => {
           backlog: this.jobQueue.length
         });
         const job = new WorkerJob(queuedJob.name, workerThread);
+        workerThread.ref();
         workerThread.onMessage = (data) => queuedJob.onMessage(job, data.type, data.payload);
         workerThread.onError = (error) => queuedJob.onError(job, error);
         queuedJob.onStart(job);
         try {
           await job.result;
-        } catch (error) {
-          console.error(`Worker exception: ${error}`);
+        } catch {
         } finally {
           this.returnWorkerToQueue(workerThread);
         }
@@ -1113,9 +1124,7 @@ var __exports__ = (() => {
      */
     returnWorkerToQueue(worker) {
       const shouldDestroyWorker = (
-        // Workers on Node.js prevent the process from exiting.
-        // Until we figure out how to close them before exit, we always destroy them
-        !isBrowser3 || // If the pool is destroyed, there is no reason to keep the worker around
+        // If the pool is destroyed, there is no reason to keep the worker around
         this.isDestroyed || // If the app has disabled worker reuse, any completed workers should be destroyed
         !this.reuseWorkers || // If concurrency has been lowered, this worker might be surplus to requirements
         this.count > this._getMaxConcurrency()
@@ -1124,6 +1133,7 @@ var __exports__ = (() => {
         worker.destroy();
         this.count--;
       } else {
+        worker.unref();
         this.idleQueue.push(worker);
       }
       if (!this.isDestroyed) {
@@ -1233,6 +1243,7 @@ var __exports__ = (() => {
   __publicField(WorkerFarm, "_workerFarm");
 
   // ../worker-utils/src/lib/worker-api/get-worker-url.ts
+  var warnedWorkerVersionFallbacks = /* @__PURE__ */ new Set();
   function getWorkerName(worker) {
     const warning = worker.version !== VERSION3 ? ` (worker-utils@${VERSION3})` : "";
     return `${worker.name}@${worker.version}${warning}`;
@@ -1259,13 +1270,33 @@ var __exports__ = (() => {
       }
       const versionTag = version2 ? `@${version2}` : "";
       url = `https://unpkg.com/@loaders.gl/${worker.module}${versionTag}/dist/${workerFile}`;
+      warnIfUsingNpmTagFallback(worker, url);
     }
     assert3(url);
     return url;
   }
+  function warnIfUsingNpmTagFallback(worker, url) {
+    if (worker.version !== "latest") {
+      return;
+    }
+    const workerId = `${worker.module}:${worker.id}`;
+    if (warnedWorkerVersionFallbacks.has(workerId)) {
+      return;
+    }
+    warnedWorkerVersionFallbacks.add(workerId);
+    console.warn(
+      `loaders.gl: ${worker.name} loader worker version is "latest" because __VERSION__ was not injected. Fetching ${url} from CDN.`
+    );
+  }
 
   // ../worker-utils/src/lib/worker-api/process-on-worker.ts
-  async function processOnWorker(worker, data, options = {}, context = {}) {
+  function canProcessOnWorker(worker, options) {
+    if (!WorkerFarm.isSupported()) {
+      return false;
+    }
+    return worker.worker && options?.worker;
+  }
+  async function processOnWorker(worker, data, options = {}, context = {}, jobContext = {}) {
     const name = getWorkerName(worker);
     const workerFarm = WorkerFarm.getWorkerFarm(options);
     const { source } = options;
@@ -1281,7 +1312,12 @@ var __exports__ = (() => {
       onMessage.bind(null, context)
     );
     const transferableOptions = getTransferListForWriter(options);
-    job.postMessage("process", { input: data, options: transferableOptions });
+    const transferableContext = getTransferListForWriter(jobContext);
+    job.postMessage("process", {
+      input: data,
+      options: transferableOptions,
+      context: transferableContext
+    });
     const result = await job.result;
     return result.result;
   }
@@ -1300,7 +1336,7 @@ var __exports__ = (() => {
             job.postMessage("error", { id, error: "Worker not set up to process on main thread" });
             return;
           }
-          const result = await context.process(input, options);
+          const result = await context.process(input, options, void 0, payload.context || {});
           job.postMessage("done", { id, result });
         } catch (error) {
           const message = error instanceof Error ? error.message : "unknown error";
@@ -1324,59 +1360,68 @@ var __exports__ = (() => {
 
   // ../loader-utils/src/lib/worker-loader-utils/parse-with-worker.ts
   function canParseWithWorker(loader, options) {
-    if (!WorkerFarm.isSupported()) {
+    const workerOptions = getWorkerOptions(options);
+    const nodeWorkers = workerOptions._nodeWorkers;
+    if (!isBrowser3 && !nodeWorkers) {
       return false;
     }
-    const nodeWorkers = options?._nodeWorkers ?? options?.core?._nodeWorkers;
-    if (!isBrowser3 && !nodeWorkers) {
+    if (loader.id === "excel" && options?.excel?.shape === "arrow-table" || loader.id === "ply" && options?.ply?.shape === "arrow-table") {
       return false;
     }
-    const useWorkers = options?.worker ?? options?.core?.worker;
-    return Boolean(loader.worker && useWorkers);
+    if (loader.id === "csv" && !shouldParseCSVWithWorker(options)) {
+      return false;
+    }
+    return Boolean(canProcessOnWorker(loader, workerOptions));
   }
   async function parseWithWorker(loader, data, options, context, parseOnMainThread) {
-    const name = loader.id;
-    const url = getWorkerURL(loader, options);
-    const workerFarm = WorkerFarm.getWorkerFarm(options?.core);
-    const workerPool = workerFarm.getWorkerPool({ name, url });
-    options = JSON.parse(JSON.stringify(options));
-    context = JSON.parse(JSON.stringify(context || {}));
-    const job = await workerPool.startJob(
-      "process-on-worker",
-      // @ts-expect-error
-      onMessage2.bind(null, parseOnMainThread)
-      // eslint-disable-line @typescript-eslint/no-misused-promises
+    const result = await processOnWorker(
+      loader,
+      data,
+      getWorkerOptions(options),
+      {
+        process: async (input, processOptions, _workerContext, parseContext) => {
+          if (!parseOnMainThread) {
+            throw new Error("Worker not set up to parse on main thread");
+          }
+          const mainThreadContext = context ? { ...context, ...parseContext || {} } : void 0;
+          return await callParseOnMainThread(
+            parseOnMainThread,
+            input,
+            processOptions,
+            mainThreadContext
+          );
+        }
+      },
+      getSerializableLoaderContext(context)
     );
-    job.postMessage("process", {
-      // @ts-ignore
-      input: data,
-      options,
-      context
-    });
-    const result = await job.result;
-    return await result.result;
+    return isLoaderWithWorkerResultDeserializer(loader) ? loader.deserializeWorkerResult(result, options, context) : result;
   }
-  async function onMessage2(parseOnMainThread, job, type, payload) {
-    switch (type) {
-      case "done":
-        job.done(payload);
-        break;
-      case "error":
-        job.error(new Error(payload.error));
-        break;
-      case "process":
-        const { id, input, options } = payload;
-        try {
-          const result = await parseOnMainThread(input, options);
-          job.postMessage("done", { id, result });
-        } catch (error) {
-          const message = error instanceof Error ? error.message : "unknown error";
-          job.postMessage("error", { id, error: message });
-        }
-        break;
-      default:
-        console.warn(`parse-with-worker unknown message ${type}`);
+  function callParseOnMainThread(parseOnMainThread, input, options, context) {
+    if (parseOnMainThread.length <= 2) {
+      return parseOnMainThread(input, options);
     }
+    return parseOnMainThread(input, void 0, options, context);
+  }
+  function getWorkerOptions(options = {}) {
+    const serializedOptions = JSON.parse(JSON.stringify(options));
+    return {
+      ...serializedOptions.core,
+      ...serializedOptions
+    };
+  }
+  function getSerializableLoaderContext(context) {
+    if (!context) {
+      return {};
+    }
+    const { fetch: fetch2, loaders, coreApi: coreApi2, _parse, _parseSync, _parseInBatches, ...serializableContext } = context;
+    return JSON.parse(JSON.stringify(serializableContext));
+  }
+  function shouldParseCSVWithWorker(options) {
+    const csvOptions = options;
+    return (csvOptions?.csv?.shape ?? csvOptions?.core?.shape) === "arrow-table";
+  }
+  function isLoaderWithWorkerResultDeserializer(loader) {
+    return typeof loader.deserializeWorkerResult === "function";
   }
 
   // ../loader-utils/src/lib/worker-loader-utils/encode-with-worker.ts
@@ -1442,10 +1487,12 @@ var __exports__ = (() => {
     for await (const textChunk of textIterator) {
       previous += textChunk;
       let eolIndex;
-      while ((eolIndex = previous.indexOf("\n")) >= 0) {
+      eolIndex = previous.indexOf("\n");
+      while (eolIndex >= 0) {
         const line = previous.slice(0, eolIndex + 1);
         previous = previous.slice(eolIndex + 1);
         yield line;
+        eolIndex = previous.indexOf("\n");
       }
     }
     if (previous.length > 0) {
@@ -1901,6 +1948,8 @@ var __exports__ = (() => {
     id: "json",
     module: "json",
     version: VERSION4,
+    encoding: "json",
+    format: "json",
     extensions: ["json", "geojson"],
     mimeTypes: ["application/json"],
     category: "json",
@@ -2186,6 +2235,11 @@ var __exports__ = (() => {
     }
   };
 
+  // ../loader-utils/src/source-types.ts
+  function isSourceLoader(loader) {
+    return Boolean(loader && typeof loader === "object" && "createDataSource" in loader);
+  }
+
   // src/lib/fetch/fetch-error.ts
   var FetchError = class extends Error {
     constructor(message, info) {
@@ -2337,7 +2391,7 @@ var __exports__ = (() => {
     try {
       const contentType = response.headers.get("Content-Type");
       info.reason = !response.bodyUsed && contentType?.includes("application/json") ? await response.json() : await response.text();
-    } catch (error) {
+    } catch (_error) {
     }
     return new FetchError(message, info);
   }
@@ -2413,37 +2467,64 @@ var __exports__ = (() => {
   // src/lib/loader-utils/loggers.ts
   var probeLog = new ProbeLog({ id: "loaders.gl" });
   var NullLog = class {
+    /** Drops a log message. */
     log() {
       return () => {
       };
     }
+    /** Drops an info message. */
     info() {
       return () => {
       };
     }
+    /** Logs one message once; no-op for the null logger. */
+    once() {
+      return () => {
+      };
+    }
+    /** Drops a warning message. */
     warn() {
       return () => {
       };
     }
+    /** Drops an error message. */
     error() {
       return () => {
       };
     }
   };
   var ConsoleLog = class {
+    /** Console-like object used for message output. */
     console;
+    /** Messages already emitted through `once`. */
+    onceMessages = /* @__PURE__ */ new Set();
+    /** Creates a console-backed logger. */
     constructor() {
       this.console = console;
     }
+    /** Logs a message to the console. */
     log(...args) {
       return this.console.log.bind(this.console, ...args);
     }
+    /** Logs an informational message to the console. */
     info(...args) {
       return this.console.info.bind(this.console, ...args);
     }
+    /** Logs one message once to the console. */
+    once(...args) {
+      const message = String(args[0]);
+      if (this.onceMessages.has(message)) {
+        return () => {
+        };
+      }
+      this.onceMessages.add(message);
+      return this.console.info.bind(this.console, ...args);
+    }
+    /** Logs a warning message to the console. */
     warn(...args) {
       return this.console.warn.bind(this.console, ...args);
     }
+    /** Logs an error message to the console. */
     error(...args) {
       return this.console.error.bind(this.console, ...args);
     }
@@ -2459,6 +2540,7 @@ var __exports__ = (() => {
       fallbackMimeType: void 0,
       ignoreRegisteredLoaders: void 0,
       nothrow: false,
+      shape: void 0,
       log: new ConsoleLog(),
       // A probe.gl compatible (`log.log()()` syntax) that just logs to console
       useLocalLibraries: false,
@@ -2504,6 +2586,7 @@ var __exports__ = (() => {
     _worker: "core._workerType",
     limit: "core.limit",
     _limitMB: "core._limitMB",
+    shape: "core.shape",
     batchSize: "core.batchSize",
     batchDebounceMs: "core.batchDebounceMs",
     metadata: "core.metadata",
@@ -2542,10 +2625,12 @@ var __exports__ = (() => {
     "maxConcurrency",
     "maxMobileConcurrency",
     "reuseWorkers",
+    "workerTransferBufferCopy",
     "_nodeWorkers",
     "_workerType",
     "limit",
     "_limitMB",
+    "shape",
     "batchSize",
     "batchDebounceMs",
     "metadata",
@@ -2656,10 +2741,34 @@ var __exports__ = (() => {
     mergeNestedFields(mergedOptions, normalizeLoaderOptions(getGlobalLoaderOptions()));
     const userOptions = normalizeLoaderOptions(options);
     mergeNestedFields(mergedOptions, userOptions);
+    applyCoreShapeDefault(mergedOptions, userOptions, loader);
     addUrlOptions(mergedOptions, url);
     addDeprecatedTopLevelOptions(mergedOptions);
     return mergedOptions;
   }
+  function applyCoreShapeDefault(mergedOptions, userOptions, loader) {
+    const coreShape = mergedOptions.core?.shape;
+    if (coreShape === void 0) {
+      return;
+    }
+    const loaderScopedDefaults = loader.options?.[loader.id];
+    if (!isPureObject(loaderScopedDefaults) || !("shape" in loaderScopedDefaults)) {
+      return;
+    }
+    const globalLoaderScopedOptions = getGlobalLoaderOptions()[loader.id];
+    if (isPureObject(globalLoaderScopedOptions) && "shape" in globalLoaderScopedOptions) {
+      return;
+    }
+    const userLoaderScopedOptions = userOptions[loader.id];
+    if (isPureObject(userLoaderScopedOptions) && "shape" in userLoaderScopedOptions) {
+      return;
+    }
+    const loaderScopedOptions = mergedOptions[loader.id];
+    mergedOptions[loader.id] = {
+      ...isPureObject(loaderScopedOptions) ? loaderScopedOptions : {},
+      shape: coreShape
+    };
+  }
   function mergeNestedFields(mergedOptions, options) {
     for (const key in options) {
       if (key in options) {
@@ -2701,7 +2810,8 @@ var __exports__ = (() => {
     }
     for (const key of CORE_LOADER_OPTION_KEYS) {
       if (options[key] !== void 0) {
-        const coreOptions = options.core = options.core || {};
+        options.core ||= {};
+        const coreOptions = options.core;
         const coreRecord = coreOptions;
         if (coreRecord[key] === void 0) {
           coreRecord[key] = options[key];
@@ -2861,16 +2971,27 @@ var __exports__ = (() => {
     const testUrl = stripQueryString(url) || context?.url;
     let loader = null;
     let reason = "";
+    const sourceType = options?.core && "type" in options.core ? options.core.type : void 0;
+    if (sourceType && sourceType !== "auto") {
+      loader = findSourceLoaderByType(loaders, sourceType);
+      reason = loader ? `match forced by supplied source type ${sourceType}` : "";
+    }
     if (options?.core?.mimeType) {
       loader = findLoaderByMIMEType(loaders, options?.core?.mimeType);
       reason = `match forced by supplied MIME type ${options?.core?.mimeType}`;
     }
+    loader = loader || findSourceLoaderByTestURL(loaders, testUrl);
+    reason = reason || (loader ? `matched source url ${testUrl}` : "");
     loader = loader || findLoaderByUrl(loaders, testUrl);
     reason = reason || (loader ? `matched url ${testUrl}` : "");
     loader = loader || findLoaderByMIMEType(loaders, type);
     reason = reason || (loader ? `matched MIME type ${type}` : "");
     loader = loader || findLoaderByInitialBytes(loaders, data);
     reason = reason || (loader ? `matched initial data ${getFirstCharacters(data)}` : "");
+    if (!loader && isBlob(data)) {
+      loader = findSourceLoaderByTestData(loaders, data);
+      reason = reason || (loader ? "matched source testData" : "");
+    }
     if (options?.core?.fallbackMimeType) {
       loader = loader || findLoaderByMIMEType(loaders, options?.core?.fallbackMimeType);
       reason = reason || (loader ? `matched fallback MIME type ${type}` : "");
@@ -2920,6 +3041,35 @@ var __exports__ = (() => {
     }
     return null;
   }
+  function findSourceLoaderByType(loaders, type) {
+    for (const loader of loaders) {
+      if (isSourceLoader(loader) && loader.type === type) {
+        return loader;
+      }
+    }
+    return null;
+  }
+  function findSourceLoaderByTestURL(loaders, url) {
+    if (!url) {
+      return null;
+    }
+    for (const loader of loaders) {
+      if (isSourceLoader(loader) && loader.testURL(url)) {
+        return loader;
+      }
+    }
+    return null;
+  }
+  function findSourceLoaderByTestData(loaders, data) {
+    for (const loader of loaders) {
+      if (isSourceLoader(loader)) {
+        if (loader.testData?.(data)) {
+          return loader;
+        }
+      }
+    }
+    return null;
+  }
   function findLoaderByMIMEType(loaders, mimeType) {
     for (const loader of loaders) {
       if (loader.mimeTypes?.some((mimeType1) => compareMIMETypes(mimeType, mimeType1))) {
@@ -3063,7 +3213,7 @@ var __exports__ = (() => {
         }
         yield toArrayBuffer2(value);
       }
-    } catch (error) {
+    } catch (_error) {
       reader.releaseLock();
     }
   }
@@ -3135,6 +3285,28 @@ var __exports__ = (() => {
     }
     throw new Error(ERR_DATA);
   }
+  async function getArrayBufferFromData(data, options) {
+    if (typeof data === "string") {
+      return new TextEncoder().encode(data).buffer;
+    }
+    if (isArrayBufferLike(data)) {
+      return toArrayBuffer2(toArrayBufferView(data));
+    }
+    if (isBlob(data)) {
+      data = await makeResponse(data);
+    }
+    if (isResponse(data)) {
+      await checkResponse(data);
+      return await data.arrayBuffer();
+    }
+    if (isReadableStream(data)) {
+      data = makeIterator(data, options);
+    }
+    if (isIterable(data) || isAsyncIterable(data)) {
+      return concatenateArrayBuffersAsync(data);
+    }
+    throw new Error(ERR_DATA);
+  }
   async function getAsyncIterableFromData(data, options) {
     if (isPromise(data)) {
       data = await data;
@@ -3198,91 +3370,156 @@ var __exports__ = (() => {
     return fetchFile;
   }
 
-  // src/lib/loader-utils/loader-context.ts
-  function getLoaderContext(context, options, parentContext) {
-    if (parentContext) {
-      return parentContext;
+  // src/lib/api/load-loader.ts
+  var loaderImplementationPromises = /* @__PURE__ */ new Map();
+  var loaderImplementations = /* @__PURE__ */ new Map();
+  async function getLoaderImplementation(loader, options, url) {
+    if (isLoaderWithParser(loader)) {
+      return loader;
     }
-    const newContext = {
-      fetch: getFetchFunction(options, context),
-      ...context
-    };
-    if (newContext.url) {
-      const baseUrl = stripQueryString(newContext.url);
-      newContext.baseUrl = baseUrl;
-      newContext.queryString = extractQueryString(newContext.url);
-      newContext.filename = path_exports.filename(baseUrl);
-      newContext.baseUrl = path_exports.dirname(baseUrl);
+    const implementationCacheKey = getLoaderImplementationCacheKey(loader, options);
+    const loaderImplementation = loaderImplementations.get(loader)?.get(implementationCacheKey);
+    if (loaderImplementation) {
+      return loaderImplementation;
+    }
+    let loaderImplementationPromisesForLoader = loaderImplementationPromises.get(loader);
+    if (!loaderImplementationPromisesForLoader) {
+      loaderImplementationPromisesForLoader = /* @__PURE__ */ new Map();
+      loaderImplementationPromises.set(loader, loaderImplementationPromisesForLoader);
+    }
+    let loaderImplementationPromise = loaderImplementationPromisesForLoader.get(implementationCacheKey);
+    if (!loaderImplementationPromise) {
+      loaderImplementationPromise = resolveLoaderImplementation(loader, options, url).then((implementation) => {
+        let loaderImplementationsForLoader = loaderImplementations.get(loader);
+        if (!loaderImplementationsForLoader) {
+          loaderImplementationsForLoader = /* @__PURE__ */ new Map();
+          loaderImplementations.set(loader, loaderImplementationsForLoader);
+        }
+        loaderImplementationsForLoader.set(implementationCacheKey, implementation);
+        return implementation;
+      }).catch((error) => {
+        loaderImplementationPromisesForLoader.delete(implementationCacheKey);
+        if (loaderImplementationPromisesForLoader.size === 0) {
+          loaderImplementationPromises.delete(loader);
+        }
+        throw error;
+      });
+      loaderImplementationPromisesForLoader.set(implementationCacheKey, loaderImplementationPromise);
     }
-    if (!Array.isArray(newContext.loaders)) {
-      newContext.loaders = null;
+    return await loaderImplementationPromise;
+  }
+  function getLoaderImplementationSync(loader) {
+    if (isLoaderWithParser(loader)) {
+      return loader;
     }
-    return newContext;
+    const implementationCacheKey = getLoaderImplementationCacheKey(loader);
+    return loaderImplementations.get(loader)?.get(implementationCacheKey) || null;
   }
-  function getLoadersFromContext(loaders, context) {
-    if (loaders && !Array.isArray(loaders)) {
-      return loaders;
+  function isLoaderWithParser(loader) {
+    const candidate = loader;
+    return Boolean(
+      candidate.parse || candidate.parseSync || candidate.parseInBatches || candidate.parseText || candidate.parseTextSync || candidate.parseFile || candidate.parseFileInBatches
+    );
+  }
+  async function resolveLoaderImplementation(loader, options, url) {
+    if (loader.preload) {
+      const preloadedLoader = await loader.preload(url || "", options);
+      if (isLoaderWithParser(preloadedLoader)) {
+        return preloadedLoader;
+      }
+      throw new Error(`${loader.id} loader preload() did not return a parser-bearing loader`);
     }
-    let candidateLoaders;
-    if (loaders) {
-      candidateLoaders = Array.isArray(loaders) ? loaders : [loaders];
+    const implementationSpecifier = getLoaderImplementationSpecifier(loader, options);
+    return await importLoaderImplementation(implementationSpecifier, loader.id);
+  }
+  function getLoaderImplementationSpecifier(loader, options) {
+    const workerType = options?._workerType || options?.core?._workerType;
+    if (workerType === "test") {
+      const sourcePath = `modules/${loader.module}/src/${loader.id}-loader.ts`;
+      if (typeof window !== "undefined") {
+        return `/${sourcePath}`;
+      }
+      if (typeof process !== "undefined" && process.cwd) {
+        return new URL(sourcePath, `file://${process.cwd()}/`).toString();
+      }
+      return sourcePath;
     }
-    if (context && context.loaders) {
-      const contextLoaders = Array.isArray(context.loaders) ? context.loaders : [context.loaders];
-      candidateLoaders = candidateLoaders ? [...candidateLoaders, ...contextLoaders] : contextLoaders;
+    throw new Error(
+      `${loader.id} loader does not provide a parser implementation. Import a parser-bearing loader directly, or use preload() before parse/load.`
+    );
+  }
+  function getLoaderImplementationCacheKey(loader, options) {
+    const loaderOptions = options?.[loader.id];
+    const defaultLoaderOptions = loader.options?.[loader.id];
+    return String(
+      loaderOptions?.backend || getDeprecatedImplementationBackend(loaderOptions?.implementation) || defaultLoaderOptions?.backend || ""
+    );
+  }
+  function getDeprecatedImplementationBackend(implementation) {
+    return implementation === "js" ? "typescript" : implementation;
+  }
+  async function importLoaderImplementation(implementationSpecifier, loaderId) {
+    const moduleExports = await import(
+      /* webpackIgnore: true */
+      /* @vite-ignore */
+      implementationSpecifier
+    );
+    for (const exportValue of Object.values(moduleExports)) {
+      if (exportValue && typeof exportValue === "object" && exportValue.id === loaderId && isLoaderWithParser(exportValue)) {
+        return exportValue;
+      }
     }
-    return candidateLoaders && candidateLoaders.length ? candidateLoaders : void 0;
+    throw new Error(
+      `Could not find parser implementation for ${loaderId} in ${implementationSpecifier}`
+    );
   }
 
-  // src/lib/api/parse.ts
-  async function parse(data, loaders, options, context) {
+  // src/lib/api/parse-file.ts
+  async function parseFile(file, loaders, options, context) {
     if (loaders && !Array.isArray(loaders) && !isLoaderObject(loaders)) {
       context = void 0;
       options = loaders;
       loaders = void 0;
     }
-    data = await data;
     options = options || {};
-    const url = getResourceUrl(data);
+    const url = file.url || "";
     const typedLoaders = loaders;
     const candidateLoaders = getLoadersFromContext(typedLoaders, context);
-    const loader = await selectLoader(data, candidateLoaders, options);
+    const loader = await selectLoader(url, candidateLoaders, options);
     if (!loader) {
       return null;
     }
+    if (isSourceLoader(loader)) {
+      throw new Error(
+        `${loader.id} is a SourceLoader. Use load() to create a runtime source object instead of parseFile().`
+      );
+    }
     const strictOptions = normalizeOptions(options, loader, candidateLoaders, url);
     context = getLoaderContext(
-      // @ts-expect-error
+      // @ts-expect-error candidateLoaders may be a single forced loader
       { url, _parse: parse, loaders: candidateLoaders },
       strictOptions,
       context || null
     );
-    return await parseWithLoader(loader, data, strictOptions, context);
+    return await parseFileWithLoader(loader, file, strictOptions, context);
   }
-  async function parseWithLoader(loader, data, options, context) {
+  async function parseFileWithLoader(loader, file, options, context) {
     validateWorkerVersion(loader);
     options = mergeOptions(loader.options, options);
-    if (isResponse(data)) {
-      const { ok, redirected, status, statusText, type, url } = data;
-      const headers = Object.fromEntries(data.headers.entries());
-      context.response = { headers, ok, redirected, status, statusText, type, url };
-    }
-    data = await getArrayBufferOrStringFromData(data, loader, options);
-    const loaderWithParser = loader;
-    if (loaderWithParser.parseTextSync && typeof data === "string") {
-      return loaderWithParser.parseTextSync(data, options, context);
-    }
-    if (canParseWithWorker(loader, options)) {
-      return await parseWithWorker(loader, data, options, context, parse);
-    }
-    if (loaderWithParser.parseText && typeof data === "string") {
-      return await loaderWithParser.parseText(data, options, context);
-    }
-    if (loaderWithParser.parse) {
-      return await loaderWithParser.parse(data, options, context);
+    const loaderWithParser = await getLoaderImplementation(loader, options, context.url);
+    if (loaderWithParser.parseFile) {
+      return await loaderWithParser.parseFile(file, options, context);
+    }
+    const parseFunction = loaderWithParser.parse;
+    if (parseFunction) {
+      const length = file.bigsize > 0n ? Number(file.bigsize) : file.size;
+      if (!length) {
+        throw new Error(`${loader.id} loader - cannot fall back to parse without a file size`);
+      }
+      const data = await file.read(0n, length);
+      return await parse(data, loaderWithParser, options, context);
     }
-    assert3(!loaderWithParser.parseSync);
-    throw new Error(`${loader.id} loader - no parser found and worker is disabled`);
+    throw new Error(`${loader.id} loader - no file parser found`);
   }
 
   // src/lib/api/parse-sync.ts
@@ -3299,6 +3536,11 @@ var __exports__ = (() => {
     if (!loader) {
       return null;
     }
+    if (isSourceLoader(loader)) {
+      throw new Error(
+        `${loader.id} is a SourceLoader. Use load() to create a runtime source object instead of parseSync().`
+      );
+    }
     const strictOptions = normalizeOptions(options, loader, candidateLoaders);
     const url = getResourceUrl(data);
     const parse2 = () => {
@@ -3309,7 +3551,13 @@ var __exports__ = (() => {
       strictOptions,
       context || null
     );
-    return parseWithLoaderSync(loader, data, strictOptions, context);
+    const loaderWithParser = getLoaderImplementationSync(loader);
+    return parseWithLoaderSync(
+      loaderWithParser || loader,
+      data,
+      strictOptions,
+      context
+    );
   }
   function parseWithLoaderSync(loader, data, options, context) {
     data = getArrayBufferOrStringFromDataSync(data, loader, options);
@@ -3319,6 +3567,11 @@ var __exports__ = (() => {
     if (loader.parseSync && data instanceof ArrayBuffer) {
       return loader.parseSync(data, options, context);
     }
+    if (loader.preload) {
+      throw new Error(
+        `${loader.name} loader: 'parseSync' requires a parser-bearing loader. Import the loader implementation directly, or call preload(loader) before parseSync(). ${context.url || ""}`
+      );
+    }
     throw new Error(
       `${loader.name} loader: 'parseSync' not supported by this loader, use 'parse' instead. ${context.url || ""}`
     );
@@ -3387,9 +3640,10 @@ var __exports__ = (() => {
       strictOptions,
       context || null
     );
-    return await parseWithLoaderInBatches(loader, data, strictOptions, context);
+    const loaderWithParser = await getLoaderImplementation(loader, strictOptions, context.url);
+    return await parseWithLoaderInBatches(loader, loaderWithParser, data, strictOptions, context);
   }
-  async function parseWithLoaderInBatches(loader, data, options, context) {
+  async function parseWithLoaderInBatches(originalLoader, loader, data, options, context) {
     const outputIterator = await parseToOutputIterator(loader, data, options, context);
     if (!options?.core?.metadata) {
       return outputIterator;
@@ -3398,7 +3652,7 @@ var __exports__ = (() => {
       shape: "metadata",
       batchType: "metadata",
       metadata: {
-        _loader: loader,
+        _loader: originalLoader,
         _context: context
       },
       // Populate with some default fields to avoid crashing
@@ -3452,6 +3706,34 @@ var __exports__ = (() => {
     return iteratorChain;
   }
 
+  // src/lib/api/load-in-batches.ts
+  function loadInBatches(files, loaders, options, context) {
+    let loadersArray;
+    if (!Array.isArray(loaders) && !isLoaderObject(loaders)) {
+      context = void 0;
+      options = loaders;
+      loadersArray = void 0;
+    } else {
+      loadersArray = loaders;
+    }
+    const fetch2 = getFetchFunction(options || {});
+    if (!Array.isArray(files)) {
+      return loadOneFileInBatches(files, loadersArray, options || {}, fetch2);
+    }
+    const promises = files.map(
+      (file) => loadOneFileInBatches(file, loadersArray, options || {}, fetch2)
+    );
+    return promises;
+  }
+  async function loadOneFileInBatches(file, loaders, options, fetch2) {
+    if (typeof file === "string") {
+      const url = file;
+      const response = await fetch2(url);
+      return Array.isArray(loaders) ? await parseInBatches(response, loaders, options) : await parseInBatches(response, loaders, options);
+    }
+    return Array.isArray(loaders) ? await parseInBatches(file, loaders, options) : await parseInBatches(file, loaders, options);
+  }
+
   // src/lib/api/load.ts
   async function load(url, loaders, options, context) {
     let resolvedLoaders;
@@ -3464,6 +3746,59 @@ var __exports__ = (() => {
       resolvedLoaders = loaders;
       resolvedOptions = options;
     }
+    if (!Array.isArray(resolvedLoaders) && isSourceLoader(resolvedLoaders)) {
+      const runtimeCoreApi = {
+        fetchFile,
+        parse,
+        parseFile,
+        parseSync,
+        parseInBatches,
+        load,
+        loadInBatches
+      };
+      return resolvedLoaders.createDataSource(
+        url,
+        resolvedOptions || {},
+        runtimeCoreApi
+      );
+    }
+    if (Array.isArray(resolvedLoaders) && resolvedLoaders.length === 1 && isSourceLoader(resolvedLoaders[0])) {
+      const runtimeCoreApi = {
+        fetchFile,
+        parse,
+        parseFile,
+        parseSync,
+        parseInBatches,
+        load,
+        loadInBatches
+      };
+      return resolvedLoaders[0].createDataSource(
+        url,
+        resolvedOptions || {},
+        runtimeCoreApi
+      );
+    }
+    if (typeof url === "string" || isBlob(url)) {
+      const selectedLoader = await selectLoader(url, resolvedLoaders, {
+        ...resolvedOptions,
+        core: { ...resolvedOptions?.core, nothrow: true }
+      });
+      if (selectedLoader && isSourceLoader(selectedLoader)) {
+        return selectedLoader.createDataSource(
+          url,
+          resolvedOptions || {},
+          {
+            fetchFile,
+            parse,
+            parseFile,
+            parseSync,
+            parseInBatches,
+            load,
+            loadInBatches
+          }
+        );
+      }
+    }
     const fetch2 = getFetchFunction(resolvedOptions);
     let data = url;
     if (typeof url === "string") {
@@ -3484,35 +3819,127 @@ var __exports__ = (() => {
         };
       }
     }
-    return Array.isArray(resolvedLoaders) ? await parse(data, resolvedLoaders, resolvedOptions) : await parse(data, resolvedLoaders, resolvedOptions);
+    return Array.isArray(resolvedLoaders) ? await parse(data, resolvedLoaders, resolvedOptions, context) : await parse(data, resolvedLoaders, resolvedOptions, context);
   }
 
-  // src/lib/api/load-in-batches.ts
-  function loadInBatches(files, loaders, options, context) {
-    let loadersArray;
-    if (!Array.isArray(loaders) && !isLoaderObject(loaders)) {
+  // src/lib/api/core-api.ts
+  var coreApi = Object.freeze({
+    fetchFile,
+    parse,
+    parseFile,
+    parseSync,
+    parseInBatches,
+    load,
+    loadInBatches
+  });
+
+  // src/lib/loader-utils/loader-context.ts
+  function getLoaderContext(context, options, parentContext) {
+    if (parentContext) {
+      return parentContext;
+    }
+    const newContext = {
+      ...context,
+      fetch: getFetchFunction(options, context),
+      coreApi: context.coreApi || coreApi
+    };
+    if (newContext.url) {
+      const baseUrl = stripQueryString(newContext.url);
+      newContext.baseUrl = baseUrl;
+      newContext.queryString = extractQueryString(newContext.url);
+      newContext.filename = path_exports.filename(baseUrl);
+      newContext.baseUrl = path_exports.dirname(baseUrl);
+    }
+    if (!Array.isArray(newContext.loaders)) {
+      newContext.loaders = null;
+    }
+    return newContext;
+  }
+  function getLoadersFromContext(loaders, context) {
+    if (loaders && !Array.isArray(loaders)) {
+      return loaders;
+    }
+    let candidateLoaders;
+    if (loaders) {
+      candidateLoaders = Array.isArray(loaders) ? loaders : [loaders];
+    }
+    if (context && context.loaders) {
+      const contextLoaders = Array.isArray(context.loaders) ? context.loaders : [context.loaders];
+      candidateLoaders = candidateLoaders ? [...candidateLoaders, ...contextLoaders] : contextLoaders;
+    }
+    return candidateLoaders && candidateLoaders.length ? candidateLoaders : void 0;
+  }
+
+  // src/lib/api/parse.ts
+  async function parse(data, loaders, options, context) {
+    if (loaders && !Array.isArray(loaders) && !isLoaderObject(loaders)) {
       context = void 0;
       options = loaders;
-      loadersArray = void 0;
-    } else {
-      loadersArray = loaders;
+      loaders = void 0;
     }
-    const fetch2 = getFetchFunction(options || {});
-    if (!Array.isArray(files)) {
-      return loadOneFileInBatches(files, loadersArray, options || {}, fetch2);
+    data = await data;
+    options = options || {};
+    const url = getResourceUrl(data);
+    const typedLoaders = loaders;
+    const candidateLoaders = getLoadersFromContext(typedLoaders, context);
+    const loader = await selectLoader(data, candidateLoaders, options);
+    if (!loader) {
+      return null;
     }
-    const promises = files.map(
-      (file) => loadOneFileInBatches(file, loadersArray, options || {}, fetch2)
+    if (isSourceLoader(loader)) {
+      throw new Error(
+        `${loader.id} is a SourceLoader. Use load() to create a runtime source object instead of parse().`
+      );
+    }
+    const strictOptions = normalizeOptions(options, loader, candidateLoaders, url);
+    context = getLoaderContext(
+      // @ts-expect-error
+      { url, _parse: parse, loaders: candidateLoaders },
+      strictOptions,
+      context || null
     );
-    return promises;
+    return await parseWithLoader(loader, data, strictOptions, context);
   }
-  async function loadOneFileInBatches(file, loaders, options, fetch2) {
-    if (typeof file === "string") {
-      const url = file;
-      const response = await fetch2(url);
-      return Array.isArray(loaders) ? await parseInBatches(response, loaders, options) : await parseInBatches(response, loaders, options);
+  async function parseWithLoader(loader, data, options, context) {
+    validateWorkerVersion(loader);
+    options = mergeOptions(loader.options, options);
+    if (isResponse(data)) {
+      const { ok, redirected, status, statusText, type, url } = data;
+      const headers = Object.fromEntries(data.headers.entries());
+      context.response = { headers, ok, redirected, status, statusText, type, url };
     }
-    return Array.isArray(loaders) ? await parseInBatches(file, loaders, options) : await parseInBatches(file, loaders, options);
+    const loaderWithParser = await getLoaderImplementation(loader, options, context.url);
+    if (canParseWithWorker(loaderWithParser, options)) {
+      data = await getArrayBufferFromData(data, options);
+      return await parseWithWorker(loaderWithParser, data, options, context, parse);
+    }
+    data = await getArrayBufferOrStringFromData(data, loader, options);
+    return await parseWithLoaderImplementation(loaderWithParser, data, options, context);
+  }
+  async function parseWithLoaderImplementation(loader, data, options, context) {
+    if (loader.parseText && typeof data === "string") {
+      return await loader.parseText(data, options, context);
+    }
+    if (loader.parseTextSync && typeof data === "string") {
+      return loader.parseTextSync(data, options, context);
+    }
+    if (loader.parse) {
+      return await loader.parse(data, options, context);
+    }
+    if (loader.parseSync) {
+      throw new Error(
+        `${loader.name} loader: 'parse' not available on parser-bearing sync loader. Add an async 'parse' function to this loader, or call preload(loader) before parseSync(). ${context.url || ""}`
+      );
+    }
+    throw new Error(`${loader.id} loader - no parser found and worker is disabled`);
+  }
+
+  // src/lib/api/preload.ts
+  async function preload(loader, options, url) {
+    return await getLoaderImplementation(loader, options, url);
+  }
+  function preloadSync(loader) {
+    return getLoaderImplementationSync(loader);
   }
 
   // src/lib/api/encode-table.ts
@@ -3638,20 +4065,18 @@ var __exports__ = (() => {
 
   // src/lib/api/create-data-source.ts
   function createDataSource(data, sources, options) {
-    const type = options?.core?.type || options.type || "auto";
-    const source = type === "auto" ? selectSource(data, sources) : getSourceOfType(type, sources);
+    const resolvedOptions = options || {};
+    const type = resolvedOptions?.core?.type || resolvedOptions.type || "auto";
+    const source = sources.length === 1 ? sources[0] : type === "auto" ? selectLoaderSync(data, sources, {
+      // `createDataSource` supports non-fetch inputs such as in-memory tables.
+      // Selection remains best-effort for those cases.
+      ...resolvedOptions,
+      core: { ...resolvedOptions?.core, type: "auto" }
+    }) : getSourceOfType(type, sources);
     if (!source) {
       throw new Error("Not a valid source type");
     }
-    return source.createDataSource(data, options);
-  }
-  function selectSource(url, sources) {
-    for (const service of sources) {
-      if (service.testURL && service.testURL(url)) {
-        return service;
-      }
-    }
-    return null;
+    return source.createDataSource(data, resolvedOptions, coreApi);
   }
   function getSourceOfType(type, sources) {
     for (const service of sources) {
@@ -3663,15 +4088,11 @@ var __exports__ = (() => {
   }
 
   // src/lib/api/select-source.ts
-  function selectSource2(url, sources, options) {
+  function selectSource(url, sources, options) {
     const type = options?.type || "auto";
     let selectedSource = null;
     if (type === "auto") {
-      for (const source of sources) {
-        if (typeof url === "string" && source.testURL && source.testURL(url)) {
-          return source;
-        }
-      }
+      selectedSource = selectLoaderSync(url, sources, { core: { nothrow: true } });
     } else {
       selectedSource = getSourceOfType2(type, sources);
     }