@loaders.gl/core 4.2.0-alpha.4 → 4.2.0-alpha.5

package/dist/lib/api/select-loader.js

@@ -1,3 +1,6 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
 import { compareArrayBuffers, path } from '@loaders.gl/loader-utils';
 import { normalizeLoader } from "../loader-utils/normalize-loader.js";
 import { log } from "../utils/log.js";
@@ -6,198 +9,248 @@ import { getRegisteredLoaders } from "./register-loaders.js";
 import { isBlob } from "../../javascript-utils/is-type.js";
 import { stripQueryString } from "../utils/url-utils.js";
 const EXT_PATTERN = /\.([^.]+)$/;
-export async function selectLoader(data) {
-  let loaders = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : [];
-  let options = arguments.length > 2 ? arguments[2] : undefined;
-  let context = arguments.length > 3 ? arguments[3] : undefined;
-  if (!validHTTPResponse(data)) {
-    return null;
-  }
-  let loader = selectLoaderSync(data, loaders, {
-    ...options,
-    nothrow: true
-  }, context);
-  if (loader) {
+// TODO - Need a variant that peeks at streams for parseInBatches
+// TODO - Detect multiple matching loaders? Use heuristics to grade matches?
+// TODO - Allow apps to pass context to disambiguate between multiple matches (e.g. multiple .json formats)?
+/**
+ * Find a loader that matches file extension and/or initial file content
+ * Search the loaders array argument for a loader that matches url extension or initial data
+ * Returns: a normalized loader
+ * @param data data to assist
+ * @param loaders
+ * @param options
+ * @param context used internally, applications should not provide this parameter
+ */
+export async function selectLoader(data, loaders = [], options, context) {
+    if (!validHTTPResponse(data)) {
+        return null;
+    }
+    // First make a sync attempt, disabling exceptions
+    let loader = selectLoaderSync(data, loaders, { ...options, nothrow: true }, context);
+    if (loader) {
+        return loader;
+    }
+    // For Blobs and Files, try to asynchronously read a small initial slice and test again with that
+    // to see if we can detect by initial content
+    if (isBlob(data)) {
+        data = await data.slice(0, 10).arrayBuffer();
+        loader = selectLoaderSync(data, loaders, options, context);
+    }
+    // no loader available
+    if (!loader && !options?.nothrow) {
+        throw new Error(getNoValidLoaderMessage(data));
+    }
     return loader;
-  }
-  if (isBlob(data)) {
-    data = await data.slice(0, 10).arrayBuffer();
-    loader = selectLoaderSync(data, loaders, options, context);
-  }
-  if (!loader && !(options !== null && options !== void 0 && options.nothrow)) {
-    throw new Error(getNoValidLoaderMessage(data));
-  }
-  return loader;
 }
-export function selectLoaderSync(data) {
-  let loaders = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : [];
-  let options = arguments.length > 2 ? arguments[2] : undefined;
-  let context = arguments.length > 3 ? arguments[3] : undefined;
-  if (!validHTTPResponse(data)) {
-    return null;
-  }
-  if (loaders && !Array.isArray(loaders)) {
-    return normalizeLoader(loaders);
-  }
-  let candidateLoaders = [];
-  if (loaders) {
-    candidateLoaders = candidateLoaders.concat(loaders);
-  }
-  if (!(options !== null && options !== void 0 && options.ignoreRegisteredLoaders)) {
-    candidateLoaders.push(...getRegisteredLoaders());
-  }
-  normalizeLoaders(candidateLoaders);
-  const loader = selectLoaderInternal(data, candidateLoaders, options, context);
-  if (!loader && !(options !== null && options !== void 0 && options.nothrow)) {
-    throw new Error(getNoValidLoaderMessage(data));
-  }
-  return loader;
+/**
+ * Find a loader that matches file extension and/or initial file content
+ * Search the loaders array argument for a loader that matches url extension or initial data
+ * Returns: a normalized loader
+ * @param data data to assist
+ * @param loaders
+ * @param options
+ * @param context used internally, applications should not provide this parameter
+ */
+export function selectLoaderSync(data, loaders = [], options, context) {
+    if (!validHTTPResponse(data)) {
+        return null;
+    }
+    // eslint-disable-next-line complexity
+    // if only a single loader was provided (not as array), force its use
+    // TODO - Should this behavior be kept and documented?
+    if (loaders && !Array.isArray(loaders)) {
+        // TODO - remove support for legacy loaders
+        return normalizeLoader(loaders);
+    }
+    // Build list of candidate loaders that will be searched in order for a match
+    let candidateLoaders = [];
+    // First search supplied loaders
+    if (loaders) {
+        candidateLoaders = candidateLoaders.concat(loaders);
+    }
+    // Then fall back to registered loaders
+    if (!options?.ignoreRegisteredLoaders) {
+        candidateLoaders.push(...getRegisteredLoaders());
+    }
+    // TODO - remove support for legacy loaders
+    normalizeLoaders(candidateLoaders);
+    const loader = selectLoaderInternal(data, candidateLoaders, options, context);
+    // no loader available
+    if (!loader && !options?.nothrow) {
+        throw new Error(getNoValidLoaderMessage(data));
+    }
+    return loader;
 }
+/** Implements loaders selection logic */
+// eslint-disable-next-line complexity
 function selectLoaderInternal(data, loaders, options, context) {
-  const url = getResourceUrl(data);
-  const type = getResourceMIMEType(data);
-  const testUrl = stripQueryString(url) || (context === null || context === void 0 ? void 0 : context.url);
-  let loader = null;
-  let reason = '';
-  if (options !== null && options !== void 0 && options.mimeType) {
-    loader = findLoaderByMIMEType(loaders, options === null || options === void 0 ? void 0 : options.mimeType);
-    reason = `match forced by supplied MIME type ${options === null || options === void 0 ? void 0 : options.mimeType}`;
-  }
-  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 (options !== null && options !== void 0 && options.fallbackMimeType) {
-    loader = loader || findLoaderByMIMEType(loaders, options === null || options === void 0 ? void 0 : options.fallbackMimeType);
-    reason = reason || (loader ? `matched fallback MIME type ${type}` : '');
-  }
-  if (reason) {
-    var _loader;
-    log.log(1, `selectLoader selected ${(_loader = loader) === null || _loader === void 0 ? void 0 : _loader.name}: ${reason}.`);
-  }
-  return loader;
+    const url = getResourceUrl(data);
+    const type = getResourceMIMEType(data);
+    const testUrl = stripQueryString(url) || context?.url;
+    let loader = null;
+    let reason = '';
+    // if options.mimeType is supplied, it takes precedence
+    if (options?.mimeType) {
+        loader = findLoaderByMIMEType(loaders, options?.mimeType);
+        reason = `match forced by supplied MIME type ${options?.mimeType}`;
+    }
+    // Look up loader by url
+    loader = loader || findLoaderByUrl(loaders, testUrl);
+    reason = reason || (loader ? `matched url ${testUrl}` : '');
+    // Look up loader by mime type
+    loader = loader || findLoaderByMIMEType(loaders, type);
+    reason = reason || (loader ? `matched MIME type ${type}` : '');
+    // Look for loader via initial bytes (Note: not always accessible (e.g. Response, stream, async iterator)
+    // @ts-ignore Blob | Response
+    loader = loader || findLoaderByInitialBytes(loaders, data);
+    // @ts-ignore Blob | Response
+    reason = reason || (loader ? `matched initial data ${getFirstCharacters(data)}` : '');
+    // Look up loader by fallback mime type
+    if (options?.fallbackMimeType) {
+        loader = loader || findLoaderByMIMEType(loaders, options?.fallbackMimeType);
+        reason = reason || (loader ? `matched fallback MIME type ${type}` : '');
+    }
+    if (reason) {
+        log.log(1, `selectLoader selected ${loader?.name}: ${reason}.`);
+    }
+    return loader;
 }
+/** Check HTTP Response */
 function validHTTPResponse(data) {
-  if (data instanceof Response) {
-    if (data.status === 204) {
-      return false;
+    // HANDLE HTTP status
+    if (data instanceof Response) {
+        // 204 - NO CONTENT. This handles cases where e.g. a tile server responds with 204 for a missing tile
+        if (data.status === 204) {
+            return false;
+        }
     }
-  }
-  return true;
+    return true;
 }
+/** Generate a helpful message to help explain why loader selection failed. */
 function getNoValidLoaderMessage(data) {
-  const url = getResourceUrl(data);
-  const type = getResourceMIMEType(data);
-  let message = 'No valid loader found (';
-  message += url ? `${path.filename(url)}, ` : 'no url provided, ';
-  message += `MIME type: ${type ? `"${type}"` : 'not provided'}, `;
-  const firstCharacters = data ? getFirstCharacters(data) : '';
-  message += firstCharacters ? ` first bytes: "${firstCharacters}"` : 'first bytes: not available';
-  message += ')';
-  return message;
+    const url = getResourceUrl(data);
+    const type = getResourceMIMEType(data);
+    let message = 'No valid loader found (';
+    message += url ? `${path.filename(url)}, ` : 'no url provided, ';
+    message += `MIME type: ${type ? `"${type}"` : 'not provided'}, `;
+    // First characters are only accessible when called on data (string or arrayBuffer).
+    // @ts-ignore Blob | Response
+    const firstCharacters = data ? getFirstCharacters(data) : '';
+    message += firstCharacters ? ` first bytes: "${firstCharacters}"` : 'first bytes: not available';
+    message += ')';
+    return message;
 }
 function normalizeLoaders(loaders) {
-  for (const loader of loaders) {
-    normalizeLoader(loader);
-  }
+    for (const loader of loaders) {
+        normalizeLoader(loader);
+    }
 }
+// TODO - Would be nice to support http://example.com/file.glb?parameter=1
+// E.g: x = new URL('http://example.com/file.glb?load=1'; x.pathname
 function findLoaderByUrl(loaders, url) {
-  const match = url && EXT_PATTERN.exec(url);
-  const extension = match && match[1];
-  return extension ? findLoaderByExtension(loaders, extension) : null;
+    // Get extension
+    const match = url && EXT_PATTERN.exec(url);
+    const extension = match && match[1];
+    return extension ? findLoaderByExtension(loaders, extension) : null;
 }
 function findLoaderByExtension(loaders, extension) {
-  extension = extension.toLowerCase();
-  for (const loader of loaders) {
-    for (const loaderExtension of loader.extensions) {
-      if (loaderExtension.toLowerCase() === extension) {
-        return loader;
-      }
+    extension = extension.toLowerCase();
+    for (const loader of loaders) {
+        for (const loaderExtension of loader.extensions) {
+            if (loaderExtension.toLowerCase() === extension) {
+                return loader;
+            }
+        }
     }
-  }
-  return null;
+    return null;
 }
 function findLoaderByMIMEType(loaders, mimeType) {
-  for (const loader of loaders) {
-    if (loader.mimeTypes && loader.mimeTypes.includes(mimeType)) {
-      return loader;
+    for (const loader of loaders) {
+        if (loader.mimeTypes && loader.mimeTypes.includes(mimeType)) {
+            return loader;
+        }
+        // Support referring to loaders using the "unregistered tree"
+        // https://en.wikipedia.org/wiki/Media_type#Unregistered_tree
+        if (mimeType === `application/x.${loader.id}`) {
+            return loader;
+        }
     }
-    if (mimeType === `application/x.${loader.id}`) {
-      return loader;
-    }
-  }
-  return null;
+    return null;
 }
 function findLoaderByInitialBytes(loaders, data) {
-  if (!data) {
-    return null;
-  }
-  for (const loader of loaders) {
-    if (typeof data === 'string') {
-      if (testDataAgainstText(data, loader)) {
-        return loader;
-      }
-    } else if (ArrayBuffer.isView(data)) {
-      if (testDataAgainstBinary(data.buffer, data.byteOffset, loader)) {
-        return loader;
-      }
-    } else if (data instanceof ArrayBuffer) {
-      const byteOffset = 0;
-      if (testDataAgainstBinary(data, byteOffset, loader)) {
-        return loader;
-      }
+    if (!data) {
+        return null;
+    }
+    for (const loader of loaders) {
+        if (typeof data === 'string') {
+            if (testDataAgainstText(data, loader)) {
+                return loader;
+            }
+        }
+        else if (ArrayBuffer.isView(data)) {
+            // Typed Arrays can have offsets into underlying buffer
+            if (testDataAgainstBinary(data.buffer, data.byteOffset, loader)) {
+                return loader;
+            }
+        }
+        else if (data instanceof ArrayBuffer) {
+            const byteOffset = 0;
+            if (testDataAgainstBinary(data, byteOffset, loader)) {
+                return loader;
+            }
+        }
+        // TODO Handle streaming case (requires creating a new AsyncIterator)
     }
-  }
-  return null;
+    return null;
 }
 function testDataAgainstText(data, loader) {
-  if (loader.testText) {
-    return loader.testText(data);
-  }
-  const tests = Array.isArray(loader.tests) ? loader.tests : [loader.tests];
-  return tests.some(test => data.startsWith(test));
+    if (loader.testText) {
+        return loader.testText(data);
+    }
+    const tests = Array.isArray(loader.tests) ? loader.tests : [loader.tests];
+    return tests.some((test) => data.startsWith(test));
 }
 function testDataAgainstBinary(data, byteOffset, loader) {
-  const tests = Array.isArray(loader.tests) ? loader.tests : [loader.tests];
-  return tests.some(test => testBinary(data, byteOffset, loader, test));
+    const tests = Array.isArray(loader.tests) ? loader.tests : [loader.tests];
+    return tests.some((test) => testBinary(data, byteOffset, loader, test));
 }
 function testBinary(data, byteOffset, loader, test) {
-  if (test instanceof ArrayBuffer) {
-    return compareArrayBuffers(test, data, test.byteLength);
-  }
-  switch (typeof test) {
-    case 'function':
-      return test(data);
-    case 'string':
-      const magic = getMagicString(data, byteOffset, test.length);
-      return test === magic;
-    default:
-      return false;
-  }
+    if (test instanceof ArrayBuffer) {
+        return compareArrayBuffers(test, data, test.byteLength);
+    }
+    switch (typeof test) {
+        case 'function':
+            return test(data);
+        case 'string':
+            // Magic bytes check: If `test` is a string, check if binary data starts with that strings
+            const magic = getMagicString(data, byteOffset, test.length);
+            return test === magic;
+        default:
+            return false;
+    }
 }
-function getFirstCharacters(data) {
-  let length = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 5;
-  if (typeof data === 'string') {
-    return data.slice(0, length);
-  } else if (ArrayBuffer.isView(data)) {
-    return getMagicString(data.buffer, data.byteOffset, length);
-  } else if (data instanceof ArrayBuffer) {
-    const byteOffset = 0;
-    return getMagicString(data, byteOffset, length);
-  }
-  return '';
+function getFirstCharacters(data, length = 5) {
+    if (typeof data === 'string') {
+        return data.slice(0, length);
+    }
+    else if (ArrayBuffer.isView(data)) {
+        // Typed Arrays can have offsets into underlying buffer
+        return getMagicString(data.buffer, data.byteOffset, length);
+    }
+    else if (data instanceof ArrayBuffer) {
+        const byteOffset = 0;
+        return getMagicString(data, byteOffset, length);
+    }
+    return '';
 }
 function getMagicString(arrayBuffer, byteOffset, length) {
-  if (arrayBuffer.byteLength < byteOffset + length) {
-    return '';
-  }
-  const dataView = new DataView(arrayBuffer);
-  let magic = '';
-  for (let i = 0; i < length; i++) {
-    magic += String.fromCharCode(dataView.getUint8(byteOffset + i));
-  }
-  return magic;
+    if (arrayBuffer.byteLength < byteOffset + length) {
+        return '';
+    }
+    const dataView = new DataView(arrayBuffer);
+    let magic = '';
+    for (let i = 0; i < length; i++) {
+        magic += String.fromCharCode(dataView.getUint8(byteOffset + i));
+    }
+    return magic;
 }
-//# sourceMappingURL=select-loader.js.map

package/dist/lib/common.js

@@ -1,2 +1,4 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
 export {};
-//# sourceMappingURL=common.js.map

package/dist/lib/fetch/fetch-error-message.js

@@ -1,18 +1,23 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
 export function getErrorMessageFromResponseSync(response) {
-  return `Failed to fetch resource ${response.url}(${response.status}): ${response.statusText} `;
+    return `Failed to fetch resource ${response.url}(${response.status}): ${response.statusText} `;
 }
 export async function getErrorMessageFromResponse(response) {
-  let message = `Failed to fetch resource ${response.url} (${response.status}): `;
-  try {
-    const contentType = response.headers.get('Content-Type') || '';
-    if (contentType.includes('application/json')) {
-      message += await response.text();
-    } else {
-      message += response.statusText;
+    let message = `Failed to fetch resource ${response.url} (${response.status}): `;
+    try {
+        const contentType = response.headers.get('Content-Type') || '';
+        if (contentType.includes('application/json')) {
+            message += await response.text();
+        }
+        else {
+            message += response.statusText;
+        }
+    }
+    catch (error) {
+        // eslint forbids return in finally statement
+        return message;
     }
-  } catch (error) {
     return message;
-  }
-  return message;
 }
-//# sourceMappingURL=fetch-error-message.js.map

package/dist/lib/fetch/fetch-file.js

@@ -1,26 +1,37 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
 import { resolvePath } from '@loaders.gl/loader-utils';
 import { makeResponse } from "../utils/response-utils.js";
 export function isNodePath(url) {
-  return !isRequestURL(url) && !isDataURL(url);
+    return !isRequestURL(url) && !isDataURL(url);
 }
 export function isRequestURL(url) {
-  return url.startsWith('http:') || url.startsWith('https:');
+    return url.startsWith('http:') || url.startsWith('https:');
 }
 export function isDataURL(url) {
-  return url.startsWith('data:');
+    return url.startsWith('data:');
 }
+/**
+ * fetch API compatible function
+ * - Supports fetching from Node.js local file system paths
+ * - Respects pathPrefix and file aliases
+ */
 export async function fetchFile(urlOrData, fetchOptions) {
-  if (typeof urlOrData === 'string') {
-    const url = resolvePath(urlOrData);
-    if (isNodePath(url)) {
-      var _globalThis$loaders;
-      if ((_globalThis$loaders = globalThis.loaders) !== null && _globalThis$loaders !== void 0 && _globalThis$loaders.fetchNode) {
-        var _globalThis$loaders2;
-        return (_globalThis$loaders2 = globalThis.loaders) === null || _globalThis$loaders2 === void 0 ? void 0 : _globalThis$loaders2.fetchNode(url, fetchOptions);
-      }
+    if (typeof urlOrData === 'string') {
+        const url = resolvePath(urlOrData);
+        // Support fetching from local file system
+        if (isNodePath(url)) {
+            if (globalThis.loaders?.fetchNode) {
+                return globalThis.loaders?.fetchNode(url, fetchOptions);
+            }
+            // throw new Error(
+            //   'fetchFile: globalThis.loaders.fetchNode not defined. Install @loaders.gl/polyfills'
+            // );
+        }
+        // Call global fetch
+        return await fetch(url, fetchOptions);
     }
-    return await fetch(url, fetchOptions);
-  }
-  return await makeResponse(urlOrData);
+    // TODO - should we still call fetch on non-URL inputs?
+    return await makeResponse(urlOrData);
 }
-//# sourceMappingURL=fetch-file.js.map

package/dist/lib/fetch/read-array-buffer.js

@@ -1,19 +1,34 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+/**
+ * Reads a chunk from a random access file
+ * @param file
+ * @param start
+ * @param length
+ * @returns
+ */
 export async function readArrayBuffer(file, start, length) {
-  if (!(file instanceof Blob)) {
-    file = new Blob([file]);
-  }
-  const slice = file.slice(start, start + length);
-  return await readBlob(slice);
+    // TODO - we can do better for ArrayBuffer and string
+    if (!(file instanceof Blob)) {
+        file = new Blob([file]);
+    }
+    const slice = file.slice(start, start + length);
+    return await readBlob(slice);
 }
+/**
+ * Read a slice of a Blob or File, without loading the entire file into memory
+ * The trick when reading File objects is to read successive "slices" of the File
+ * Per spec https://w3c.github.io/FileAPI/, slicing a File only updates the start and end fields
+ * Actually reading from file happens in `readAsArrayBuffer`
+ * @param blob to read
+ */
 export async function readBlob(blob) {
-  return await new Promise((resolve, reject) => {
-    const fileReader = new FileReader();
-    fileReader.onload = event => {
-      var _event$target;
-      return resolve(event === null || event === void 0 ? void 0 : (_event$target = event.target) === null || _event$target === void 0 ? void 0 : _event$target.result);
-    };
-    fileReader.onerror = error => reject(error);
-    fileReader.readAsArrayBuffer(blob);
-  });
+    return await new Promise((resolve, reject) => {
+        const fileReader = new FileReader();
+        fileReader.onload = (event) => resolve(event?.target?.result);
+        // TODO - reject with a proper Error
+        fileReader.onerror = (error) => reject(error);
+        fileReader.readAsArrayBuffer(blob);
+    });
 }
-//# sourceMappingURL=read-array-buffer.js.map