@loaders.gl/core 3.1.0-alpha.2 → 3.1.0-beta.1

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

@@ -1,232 +1,239 @@
-import { compareArrayBuffers } from '@loaders.gl/loader-utils';
-import { normalizeLoader } from '../loader-utils/normalize-loader';
-import { getResourceUrlAndType } from '../utils/resource-utils';
-import { getRegisteredLoaders } from './register-loaders';
-import { isBlob } from '../../javascript-utils/is-type';
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.selectLoaderSync = exports.selectLoader = void 0;
+const loader_utils_1 = require("@loaders.gl/loader-utils");
+const normalize_loader_1 = require("../loader-utils/normalize-loader");
+const resource_utils_1 = require("../utils/resource-utils");
+const register_loaders_1 = require("./register-loaders");
+const is_type_1 = require("../../javascript-utils/is-type");
 const EXT_PATTERN = /\.([^.]+)$/;
-export async function selectLoader(data, loaders = [], options, context) {
-  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
+ */
+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 ((0, is_type_1.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, loaders = [], options, context) {
-  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;
+exports.selectLoader = selectLoader;
+/**
+ * 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
+ */
+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 (0, normalize_loader_1.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(...(0, register_loaders_1.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;
 }
-
+exports.selectLoaderSync = selectLoaderSync;
+/** Implements loaders selection logic */
 function selectLoaderInternal(data, loaders, options, context) {
-  const {
-    url,
-    type
-  } = getResourceUrlAndType(data);
-  const testUrl = url || (context === null || context === void 0 ? void 0 : context.url);
-  let loader = null;
-
-  if (options !== null && options !== void 0 && options.mimeType) {
-    loader = findLoaderByMIMEType(loaders, options === null || options === void 0 ? void 0 : options.mimeType);
-  }
-
-  loader = loader || findLoaderByUrl(loaders, testUrl);
-  loader = loader || findLoaderByMIMEType(loaders, type);
-  loader = loader || findLoaderByInitialBytes(loaders, data);
-  loader = loader || findLoaderByMIMEType(loaders, options === null || options === void 0 ? void 0 : options.fallbackMimeType);
-  return loader;
+    const { url, type } = (0, resource_utils_1.getResourceUrlAndType)(data);
+    const testUrl = url || context?.url;
+    let loader = null;
+    // if options.mimeType is supplied, it takes precedence
+    if (options?.mimeType) {
+        loader = findLoaderByMIMEType(loaders, options?.mimeType);
+    }
+    // Look up loader by url
+    loader = loader || findLoaderByUrl(loaders, testUrl);
+    // Look up loader by mime type
+    loader = loader || findLoaderByMIMEType(loaders, type);
+    // Look for loader via initial bytes (Note: not always accessible (e.g. Response, stream, async iterator)
+    loader = loader || findLoaderByInitialBytes(loaders, data);
+    // Look up loader by fallback mime type
+    loader = loader || findLoaderByMIMEType(loaders, options?.fallbackMimeType);
+    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,
-    type
-  } = getResourceUrlAndType(data);
-  let message = 'No valid loader found';
-
-  if (data) {
-    message += ` data: "${getFirstCharacters(data)}", contentType: "${type}"`;
-  }
-
-  if (url) {
-    message += ` url: ${url}`;
-  }
-
-  return message;
+    const { url, type } = (0, resource_utils_1.getResourceUrlAndType)(data);
+    let message = 'No valid loader found (';
+    message += url ? `${loader_utils_1.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).
+    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) {
+        (0, normalize_loader_1.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;
-    }
-
-    if (mimeType === `application/x.${loader.id}`) {
-      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;
+        }
     }
-  }
-
-  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, loader);
-
-    case 'string':
-      const magic = getMagicString(data, byteOffset, test.length);
-      return test === magic;
-
-    default:
-      return false;
-  }
+    if (test instanceof ArrayBuffer) {
+        return (0, loader_utils_1.compareArrayBuffers)(test, data, test.byteLength);
+    }
+    switch (typeof test) {
+        case 'function':
+            return test(data, loader);
+        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, length = 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 '';
+    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/api/set-loader-options.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Set global loader options
+ * @param options
+ */
+export declare function setLoaderOptions(options: object): void;
+//# sourceMappingURL=set-loader-options.d.ts.map

package/dist/lib/api/set-loader-options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"set-loader-options.d.ts","sourceRoot":"","sources":["../../../src/lib/api/set-loader-options.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAEtD"}

package/dist/lib/api/set-loader-options.js

@@ -1,5 +1,12 @@
-import { setGlobalOptions } from '../loader-utils/option-utils';
-export function setLoaderOptions(options) {
-  setGlobalOptions(options);
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setLoaderOptions = void 0;
+const option_utils_1 = require("../loader-utils/option-utils");
+/**
+ * Set global loader options
+ * @param options
+ */
+function setLoaderOptions(options) {
+    (0, option_utils_1.setGlobalOptions)(options);
 }
-//# sourceMappingURL=set-loader-options.js.map
+exports.setLoaderOptions = setLoaderOptions;

package/dist/lib/common.d.ts

@@ -0,0 +1,2 @@
+export type { LoaderWithParser } from '@loaders.gl/loader-utils';
+//# sourceMappingURL=common.d.ts.map

package/dist/lib/common.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../src/lib/common.ts"],"names":[],"mappings":"AAAA,YAAY,EAAC,gBAAgB,EAAC,MAAM,0BAA0B,CAAC"}

package/dist/lib/common.js

@@ -1,2 +1,2 @@
-export {};
-//# sourceMappingURL=common.js.map
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/lib/fetch/fetch-error-message.d.ts

@@ -0,0 +1,3 @@
+export declare function getErrorMessageFromResponseSync(response: Response): string;
+export declare function getErrorMessageFromResponse(response: Response): Promise<string>;
+//# sourceMappingURL=fetch-error-message.d.ts.map

package/dist/lib/fetch/fetch-error-message.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-error-message.d.ts","sourceRoot":"","sources":["../../../src/lib/fetch/fetch-error-message.ts"],"names":[],"mappings":"AAAA,wBAAgB,+BAA+B,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAE1E;AAED,wBAAsB,2BAA2B,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CAcrF"}

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

@@ -1,21 +1,25 @@
-export function getErrorMessageFromResponseSync(response) {
-  return `Failed to fetch resource ${response.url}(${response.status}): ${response.statusText} `;
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getErrorMessageFromResponse = exports.getErrorMessageFromResponseSync = void 0;
+function getErrorMessageFromResponseSync(response) {
+    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;
+exports.getErrorMessageFromResponseSync = getErrorMessageFromResponseSync;
+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;
+        }
+    }
+    catch (error) {
+        // eslint forbids return in finally statement
+        return message;
     }
-  } catch (error) {
     return message;
-  }
-
-  return message;
 }
-//# sourceMappingURL=fetch-error-message.js.map
+exports.getErrorMessageFromResponse = getErrorMessageFromResponse;

package/dist/lib/fetch/fetch-file.d.ts

@@ -0,0 +1,13 @@
+/**
+ * fetch compatible function
+ * Reads file data from:
+ * - http/http urls
+ * - data urls
+ * - File/Blob objects
+ * Leverages `@loaders.gl/polyfills` for Node.js support
+ * Respects pathPrefix and file aliases
+ */
+export declare function fetchFile(url: string | Blob, options?: RequestInit & {
+    fetch?: RequestInit | Function;
+}): Promise<Response>;
+//# sourceMappingURL=fetch-file.d.ts.map

package/dist/lib/fetch/fetch-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-file.d.ts","sourceRoot":"","sources":["../../../src/lib/fetch/fetch-file.ts"],"names":[],"mappings":"AAIA;;;;;;;;GAQG;AACH,wBAAsB,SAAS,CAC7B,GAAG,EAAE,MAAM,GAAG,IAAI,EAClB,OAAO,CAAC,EAAE,WAAW,GAAG;IAAC,KAAK,CAAC,EAAE,WAAW,GAAG,QAAQ,CAAA;CAAC,GACvD,OAAO,CAAC,QAAQ,CAAC,CAanB"}

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

@@ -1,17 +1,27 @@
-import { resolvePath } from '@loaders.gl/loader-utils';
-import { makeResponse } from '../utils/response-utils';
-export async function fetchFile(url, options) {
-  if (typeof url === 'string') {
-    url = resolvePath(url);
-    let fetchOptions = options;
-
-    if (options !== null && options !== void 0 && options.fetch && typeof (options === null || options === void 0 ? void 0 : options.fetch) !== 'function') {
-      fetchOptions = options.fetch;
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchFile = void 0;
+const loader_utils_1 = require("@loaders.gl/loader-utils");
+const response_utils_1 = require("../utils/response-utils");
+// import {getErrorMessageFromResponse} from './fetch-error-message.js';
+/**
+ * fetch compatible function
+ * Reads file data from:
+ * - http/http urls
+ * - data urls
+ * - File/Blob objects
+ * Leverages `@loaders.gl/polyfills` for Node.js support
+ * Respects pathPrefix and file aliases
+ */
+async function fetchFile(url, options) {
+    if (typeof url === 'string') {
+        url = (0, loader_utils_1.resolvePath)(url);
+        let fetchOptions = options;
+        if (options?.fetch && typeof options?.fetch !== 'function') {
+            fetchOptions = options.fetch;
+        }
+        return await fetch(url, fetchOptions);
     }
-
-    return await fetch(url, fetchOptions);
-  }
-
-  return await makeResponse(url);
+    return await (0, response_utils_1.makeResponse)(url);
 }
-//# sourceMappingURL=fetch-file.js.map
+exports.fetchFile = fetchFile;

package/dist/lib/fetch/read-array-buffer.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Reads a chunk from a random access file
+ * @param file
+ * @param start
+ * @param length
+ * @returns
+ */
+export declare function readArrayBuffer(file: Blob | ArrayBuffer | string | number, start: number, length: number): Promise<ArrayBuffer>;
+/**
+ * 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 declare function readBlob(blob: Blob): Promise<ArrayBuffer>;
+//# sourceMappingURL=read-array-buffer.d.ts.map

package/dist/lib/fetch/read-array-buffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-array-buffer.d.ts","sourceRoot":"","sources":["../../../src/lib/fetch/read-array-buffer.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,IAAI,GAAG,WAAW,GAAG,MAAM,GAAG,MAAM,EAC1C,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,WAAW,CAAC,CAUtB;AAED;;;;;;GAMG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,WAAW,CAAC,CAS/D"}