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

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

@@ -0,0 +1,28 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {Log} from 'probe.gl/log';
+
+// Version constant cannot be imported, it needs to correspond to the build version of **this** module.
+// __VERSION__ is injected by babel-plugin-version-inline
+// @ts-ignore TS2304: Cannot find name '__VERSION__'.
+export const VERSION = typeof __VERSION__ !== 'undefined' ? __VERSION__ : 'latest';
+
+const version = VERSION[0] >= '0' && VERSION[0] <= '9' ? `v${VERSION}` : '';
+
+// Make sure we set the global variable
+function createLog() {
+  const log = new Log({id: 'loaders.gl'});
+
+  globalThis.loaders ||= {};
+  globalThis.loaders.log = log;
+  globalThis.loaders.version = version;
+
+  globalThis.probe ||= {};
+  globalThis.probe.loaders = log;
+
+  return log;
+}
+
+export const log = createLog();

package/src/loader-utils/lib/module-utils/initialize-wasm-module.ts

@@ -0,0 +1,51 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+/**
+ * Initializes a WASM factory that reports readiness through a callback, a thenable, or both.
+ * @param initialize - Starts initialization and forwards any available ready/error callbacks.
+ * @param extractExports - Initializes the module and returns a plain, non-thenable export object.
+ * @returns Extracted exports, or a rejection with the original initialization/setup error.
+ * @remarks Never resolve with the raw Emscripten module: its thenable can recurse during assimilation.
+ * Dependencies must expose a rejection or abort hook for asynchronous failures to be observable.
+ */
+export function initializeWasmModule<Module, ModuleExports>(
+  initialize: (
+    onInitialized: (module: Module) => void,
+    onError: (error: unknown) => void
+  ) => PromiseLike<Module> | void,
+  extractExports: (module: Module) => ModuleExports
+): Promise<ModuleExports> {
+  return new Promise((resolve, reject) => {
+    let isSettled = false;
+
+    /** Rejects once and prevents a late ready callback from running module setup. */
+    function rejectInitialization(error: unknown): void {
+      if (!isSettled) {
+        isSettled = true;
+        reject(error);
+      }
+    }
+
+    /** Extracts safe exports once, even when the factory uses both completion mechanisms. */
+    function resolveInitialization(module: Module): void {
+      if (isSettled) {
+        return;
+      }
+      isSettled = true;
+      try {
+        resolve(extractExports(module));
+      } catch (error) {
+        reject(error);
+      }
+    }
+
+    try {
+      const modulePromise = initialize(resolveInitialization, rejectInitialization);
+      modulePromise?.then(resolveInitialization, rejectInitialization);
+    } catch (error) {
+      rejectInitialization(error);
+    }
+  });
+}

package/src/loader-utils/lib/module-utils/js-module-utils.ts

@@ -0,0 +1,44 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {log} from '../log-utils/log';
+
+/**
+ * Register application-imported modules
+ * These modules are typically to big to bundle, or may have issues on some bundlers/environments
+ */
+export function registerJSModules(modules?: Record<string, any>): void {
+  globalThis.loaders ||= {};
+  globalThis.loaders.modules ||= {};
+  Object.assign(globalThis.loaders.modules, modules);
+}
+
+/**
+ * Get a pre-registered application-imported module, warn if not present
+ */
+export function checkJSModule(name: string, caller: string): void {
+  const module = globalThis.loaders?.modules?.[name];
+  if (!module) {
+    log.warn(`${caller}: ${name} library not installed`)();
+  }
+}
+
+/**
+ * Get a pre-registered application-imported module, throw if not present
+ */
+export function getJSModule<ModuleT = any>(name: string, caller: string): ModuleT {
+  const module = globalThis.loaders?.modules?.[name];
+  if (!module) {
+    throw new Error(`${caller}: ${name} library not installed`);
+  }
+  return module;
+}
+
+/**
+ * Get a pre-registered application-imported module, return null if not present
+ */
+export function getJSModuleOrNull<ModuleT = any>(name: string): ModuleT | null {
+  const module = globalThis.loaders?.modules?.[name];
+  return module || null;
+}

package/src/loader-utils/lib/node/buffer.browser.ts

@@ -0,0 +1,22 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+// Isolates Buffer references to ensure they are only bundled under Node.js (avoids big webpack polyfill)
+// this file is selected by the package.json "browser" field).
+
+/**
+ * Convert Buffer to ArrayBuffer
+ * Converts Node.js `Buffer` to `ArrayBuffer` (without triggering bundler to include Buffer polyfill on browser)
+ * @todo better data type
+ */
+export function toArrayBuffer(buffer) {
+  return buffer;
+}
+
+/**
+ * Convert (copy) ArrayBuffer to Buffer
+ */
+export function toBuffer(binaryData: ArrayBuffer | Buffer): Buffer {
+  throw new Error('Buffer not supported in browser');
+}

package/src/loader-utils/lib/node/buffer.ts

@@ -0,0 +1,40 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+// Isolates Buffer references to ensure they are only bundled under Node.js (avoids big webpack polyfill)
+// this file is selected by the package.json "browser" field).
+
+/**
+ * Convert Buffer to ArrayBuffer
+ * Converts Node.js `Buffer` to `ArrayBuffer` (without triggering bundler to include Buffer polyfill on browser)
+ * @todo better data type
+ */
+export function toArrayBuffer(buffer) {
+  // TODO - per docs we should just be able to call buffer.buffer, but there are issues
+  if (Buffer.isBuffer(buffer)) {
+    const typedArray = new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.length);
+    return typedArray.slice().buffer;
+  }
+  return buffer;
+}
+
+/**
+ * Convert (copy) ArrayBuffer to Buffer
+ */
+export function toBuffer(binaryData: ArrayBuffer | Buffer): Buffer {
+  if (Buffer.isBuffer(binaryData)) {
+    return binaryData;
+  }
+
+  if (ArrayBuffer.isView(binaryData)) {
+    binaryData = binaryData.buffer as ArrayBuffer;
+  }
+
+  // TODO - move to loaders.gl/polyfills
+  if (typeof Buffer !== 'undefined' && binaryData instanceof ArrayBuffer) {
+    return Buffer.from(binaryData);
+  }
+
+  throw new Error('toBuffer');
+}

package/src/loader-utils/lib/node/fs.browser.ts

@@ -0,0 +1,5 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+export const isSupported = false;

package/src/loader-utils/lib/node/promisify.ts

@@ -0,0 +1,72 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+// type Parameter1<T extends (arg1: any, ...args: unknown[]) => unknown> = T extends (
+//   arg1: infer P,
+//   ...args: unknown[]
+// ) => unknown
+//   ? P
+//   : never;
+
+//   type Parameter2<T extends (arg1: unknown, arg2: any, ...args: unknown[]) => unknown> = T extends (
+//   arg1: unknown,
+//   arg2: infer P,
+//   ...args: unknown[]
+// ) => unknown
+//   ? P
+//   : never;
+
+// type CallbackParameter2<
+//   T extends (arg: unknown, cb: (error: any, value: any) => void) => unknown
+// > = T extends (arg: unknown, cb: (error: any, value: infer P) => void) => unknown ? P : never;
+
+// type CallbackParameter3<
+//   T extends (arg: unknown, arg2: unknown, cb: (error: any, value: any) => void) => unknown
+// > = T extends (arg: unknown, arg2: unknown, cb: (error: any, value: infer P) => void) => unknown
+//   ? P
+//   : never;
+
+// /** Extract the parameters of a function type in a tuple */
+// export type Promisified<F extends (arg1, cb: (error: unknown, value: any) => void) => any> = (
+//   arg1: Parameter1<F>
+// ) => Promise<CallbackParameter2<F>>;
+// /** Extract the parameters of a function type in a tuple */
+// export type Promisified2<F extends (arg1, arg2, cb: (error: unknown, value: any) => void) => any> = (
+//   arg1: Parameter1<F>,
+//   arg2: Parameter2<F>
+// ) => Promise<CallbackParameter3<F>>;
+
+/** Wrapper for Node.js promisify */
+type Callback<A> = (error: unknown, args: A) => void;
+
+/**
+ * Typesafe promisify implementation
+ * @link https://dev.to/_gdelgado/implement-a-type-safe-version-of-node-s-promisify-in-7-lines-of-code-in-typescript-2j34
+ * @param fn
+ * @returns
+ */
+export function promisify1<T, A>(fn: (args: T, cb: Callback<A>) => void): (args: T) => Promise<A> {
+  return (args: T) =>
+    new Promise((resolve, reject) =>
+      fn(args, (error, callbackArgs) => (error ? reject(error) : resolve(callbackArgs)))
+    );
+}
+
+export function promisify2<T1, T2, A>(
+  fn: (arg1: T1, arg2: T2, cb: Callback<A>) => void
+): (arg1: T1, arg2: T2) => Promise<A> {
+  return (arg1: T1, arg2: T2) =>
+    new Promise((resolve, reject) =>
+      fn(arg1, arg2, (error, callbackArgs) => (error ? reject(error) : resolve(callbackArgs)))
+    );
+}
+
+export function promisify3<T1, T2, T3, A>(
+  fn: (arg1: T1, arg2: T2, arg3: T3, cb: Callback<A>) => void
+): (arg1: T1, arg2: T2, arg3: T3) => Promise<A> {
+  return (arg1: T1, arg2: T2, arg3: T3) =>
+    new Promise((resolve, reject) =>
+      fn(arg1, arg2, arg3, (error, callbackArgs) => (error ? reject(error) : resolve(callbackArgs)))
+    );
+}

package/src/loader-utils/lib/node/stream.browser.ts

@@ -0,0 +1,5 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+export const isSupported = false;

package/src/loader-utils/lib/node/stream.ts

@@ -0,0 +1,12 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import * as stream from 'stream';
+
+export type {Writable} from 'stream';
+
+/** Wrapper for Node.js stream method */
+export const Transform = stream.Transform;
+
+export const isSupported = Boolean(stream);

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

@@ -0,0 +1,50 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {isPureObject} from '../javascript-utils/is-type';
+
+export type RequiredOptions<T> = Required<{[K in keyof T]: Required<T[K]>}>;
+
+export function getRequiredOptions<T>(options: T): RequiredOptions<T> {
+  return options as RequiredOptions<T>;
+}
+
+/**
+ *
+ * @param baseOptions Can be undefined, in which case a fresh options object will be minted
+ * @param newOptions
+ * @returns
+ */
+export function mergeOptions<OptionsT extends Record<string, unknown>>(
+  baseOptions: OptionsT | undefined,
+  newOptions: OptionsT
+): OptionsT {
+  return mergeOptionsRecursively(baseOptions || {}, newOptions) as OptionsT;
+}
+
+function mergeOptionsRecursively(
+  baseOptions: Record<string, unknown>,
+  newOptions: Record<string, unknown>,
+  level = 0
+): Record<string, unknown> {
+  // Sanity check (jest test runner overwrites the console object which can lead to infinite recursion)
+  if (level > 3) {
+    return newOptions;
+  }
+
+  const options = {...baseOptions};
+  for (const [key, newValue] of Object.entries(newOptions)) {
+    if (isPureObject(newValue)) {
+      options[key] = mergeOptionsRecursively(
+        (options[key] as Record<string, unknown>) || {},
+        newOptions[key] as Record<string, unknown>,
+        level + 1
+      );
+      // Object.assign(options[key] as object, newOptions[key]);
+    } else {
+      options[key] = newOptions[key];
+    }
+  }
+  return options as Record<string, unknown>;
+}

package/src/loader-utils/lib/parser-utils/parse-json.ts

@@ -0,0 +1,16 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {getFirstCharacters} from '../binary-utils/get-first-characters';
+
+/**
+ * Minimal JSON parser that throws more meaningful error messages
+ */
+export function parseJSON(string: string): any {
+  try {
+    return JSON.parse(string);
+  } catch (_) {
+    throw new Error(`Failed to parse JSON from data starting with "${getFirstCharacters(string)}"`);
+  }
+}

package/src/loader-utils/lib/path-utils/cached-uri-resolver.ts

@@ -0,0 +1,69 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright vis.gl contributors
+
+import * as path from './path';
+
+const URI_SCHEME_PATTERN = /^[a-z][0-9a-z+.-]*:/i;
+
+/**
+ * Resolves resource URIs against one stable base while caching repeated derivations.
+ *
+ * The base URL is parsed once. Resolved strings are cached for the lifetime of the resolver, which
+ * is intended to match one source or metadata parse. This avoids repeated base parsing for large
+ * resource trees without introducing a process-wide cache or retaining unrelated datasets.
+ */
+export class CachedUriResolver {
+  /** Original filesystem path or URI base used for non-URL resolution. */
+  private readonly basePath: string;
+  /** Parsed URL base, retained when the base uses an RFC 3986 scheme. */
+  private readonly baseUrl?: URL;
+  /** Resolved URI strings keyed by their source-relative spelling. */
+  private readonly resolvedUris: Map<string, string> = new Map();
+
+  /**
+   * Creates a resolver scoped to one resource hierarchy.
+   *
+   * @param basePath - Directory path or absolute base URI.
+   */
+  constructor(basePath: string) {
+    this.basePath = basePath;
+    if (URI_SCHEME_PATTERN.test(basePath)) {
+      this.baseUrl = new URL(basePath.endsWith('/') ? basePath : `${basePath}/`);
+    }
+  }
+
+  /**
+   * Resolves a relative or absolute resource identifier.
+   *
+   * URL bases follow the platform `URL` implementation and are decoded to preserve the existing
+   * loaders.gl 3D Tiles behavior. Filesystem-like bases continue to use loaders.gl path semantics.
+   * Repeated calls with the same source string return the previously resolved string.
+   *
+   * @param uri - Relative path, absolute path, data URL, or absolute URI.
+   * @returns Absolute or base-relative resource identifier.
+   */
+  resolve(uri: string): string {
+    const cachedUri = this.resolvedUris.get(uri);
+    if (cachedUri) {
+      return cachedUri;
+    }
+
+    let resolvedUri: string;
+    if (this.baseUrl) {
+      resolvedUri = decodeURI(new URL(uri, this.baseUrl).toString());
+    } else if (uri.startsWith('/') || URI_SCHEME_PATTERN.test(uri)) {
+      resolvedUri = uri;
+    } else {
+      resolvedUri = path.resolve(this.basePath, uri);
+    }
+
+    this.resolvedUris.set(uri, resolvedUri);
+    return resolvedUri;
+  }
+
+  /** Clears derived URI strings while retaining the parsed base URL. */
+  clear(): void {
+    this.resolvedUris.clear();
+  }
+}

package/src/loader-utils/lib/path-utils/file-aliases.ts

@@ -0,0 +1,49 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+// Simple file alias mechanisms for tests.
+
+let pathPrefix = '';
+const fileAliases: {[aliasPath: string]: string} = {};
+
+/*
+ * Set a relative path prefix
+ */
+export function setPathPrefix(prefix: string): void {
+  pathPrefix = prefix;
+}
+
+/*
+ * Get the relative path prefix
+ */
+export function getPathPrefix(): string {
+  return pathPrefix;
+}
+
+/**
+ *
+ * @param aliases
+ *
+ * Note: addAliases are an experimental export, they are only for testing of loaders.gl loaders
+ * not intended as a generic aliasing mechanism
+ */
+export function addAliases(aliases: {[aliasPath: string]: string}): void {
+  Object.assign(fileAliases, aliases);
+}
+
+/**
+ * Resolves aliases and adds path-prefix to paths
+ */
+export function resolvePath(filename: string): string {
+  for (const alias in fileAliases) {
+    if (filename.startsWith(alias)) {
+      const replacement = fileAliases[alias];
+      filename = filename.replace(alias, replacement);
+    }
+  }
+  if (!filename.startsWith('http://') && !filename.startsWith('https://')) {
+    filename = `${pathPrefix}${filename}`;
+  }
+  return filename;
+}

package/src/loader-utils/lib/path-utils/get-cwd.ts

@@ -0,0 +1,12 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+/** Returns the Node working directory or the window/worker script directory. */
+export function getCWD(): string {
+  if (typeof process !== 'undefined' && typeof process.cwd !== 'undefined') {
+    return process.cwd();
+  }
+  const pathname = globalThis.location?.pathname;
+  return pathname?.slice(0, pathname.lastIndexOf('/') + 1) || '';
+}

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

@@ -0,0 +1,173 @@
+// SPDX-License-Identifier: MIT
+
+// Beginning of a minimal implementation of the Node.js path API, that doesn't pull in big polyfills.
+
+import {getCWD} from './get-cwd';
+
+/**
+ * Replacement for Node.js path.filename
+ * @param url
+ */
+export function filename(url: string): string {
+  const slashIndex = url ? url.lastIndexOf('/') : -1;
+  return slashIndex >= 0 ? url.substr(slashIndex + 1) : url;
+}
+
+/**
+ * Replacement for Node.js path.dirname
+ * @param url
+ */
+export function dirname(url: string): string {
+  const slashIndex = url ? url.lastIndexOf('/') : -1;
+  return slashIndex >= 0 ? url.substr(0, slashIndex) : '';
+}
+
+/**
+ * Replacement for Node.js path.join
+ * @param parts
+ */
+export function join(...parts: string[]): string {
+  const separator = '/';
+  parts = parts.map((part, index) => {
+    if (index) {
+      part = part.replace(new RegExp(`^${separator}`), '');
+    }
+    if (index !== parts.length - 1) {
+      part = part.replace(new RegExp(`${separator}$`), '');
+    }
+    return part;
+  });
+  return parts.join(separator);
+}
+
+/* eslint-disable no-continue */
+
+/**
+ * https://nodejs.org/api/path.html#path_path_resolve_paths
+ * @param paths A sequence of paths or path segments.
+ * @return resolved path
+ * Forked from BTOdell/path-resolve under MIT license
+ * @see https://github.com/BTOdell/path-resolve/blob/master/LICENSE
+ */
+export function resolve(...components: string[]): string {
+  const paths: string[] = [];
+  for (let _i = 0; _i < components.length; _i++) {
+    paths[_i] = components[_i];
+  }
+  let resolvedPath = '';
+  let resolvedAbsolute = false;
+  let cwd: string | undefined;
+  for (let i = paths.length - 1; i >= -1 && !resolvedAbsolute; i--) {
+    let path: string | undefined;
+    if (i >= 0) {
+      path = paths[i];
+    } else {
+      if (cwd === undefined) {
+        cwd = getCWD();
+      }
+      path = cwd;
+    }
+    // Skip empty entries
+    if (path.length === 0) {
+      continue;
+    }
+    resolvedPath = `${path}/${resolvedPath}`;
+    resolvedAbsolute = path.charCodeAt(0) === SLASH;
+  }
+  // At this point the path should be resolved to a full absolute path, but
+  // handle relative paths to be safe (might happen when process.cwd() fails)
+  // Normalize the path (removes leading slash)
+  resolvedPath = normalizeStringPosix(resolvedPath, !resolvedAbsolute);
+  if (resolvedAbsolute) {
+    return `/${resolvedPath}`;
+  } else if (resolvedPath.length > 0) {
+    return resolvedPath;
+  }
+  return '.';
+}
+
+const SLASH = 47;
+const DOT = 46;
+
+/**
+ * Resolves . and .. elements in a path with directory names
+ * Forked from BTOdell/path-resolve under MIT license
+ * @see https://github.com/BTOdell/path-resolve/blob/master/LICENSE
+ */
+/* eslint-disable max-depth */
+// eslint-disable-next-line complexity, max-statements
+function normalizeStringPosix(path: string, allowAboveRoot: boolean): string {
+  let res = '';
+  let lastSlash = -1;
+  let dots = 0;
+  let code: number | undefined;
+  let isAboveRoot = false;
+
+  for (let i = 0; i <= path.length; ++i) {
+    if (i < path.length) {
+      code = path.charCodeAt(i);
+    } else if (code === SLASH) {
+      break;
+    } else {
+      code = SLASH;
+    }
+    if (code === SLASH) {
+      if (lastSlash === i - 1 || dots === 1) {
+        // NOOP
+      } else if (lastSlash !== i - 1 && dots === 2) {
+        if (
+          res.length < 2 ||
+          !isAboveRoot ||
+          res.charCodeAt(res.length - 1) !== DOT ||
+          res.charCodeAt(res.length - 2) !== DOT
+        ) {
+          if (res.length > 2) {
+            const start = res.length - 1;
+            let j = start;
+            for (; j >= 0; --j) {
+              if (res.charCodeAt(j) === SLASH) {
+                break;
+              }
+            }
+            if (j !== start) {
+              res = j === -1 ? '' : res.slice(0, j);
+              lastSlash = i;
+              dots = 0;
+              isAboveRoot = false;
+              continue;
+            }
+          } else if (res.length === 2 || res.length === 1) {
+            res = '';
+            lastSlash = i;
+            dots = 0;
+            isAboveRoot = false;
+            continue;
+          }
+        }
+        if (allowAboveRoot) {
+          if (res.length > 0) {
+            res += '/..';
+          } else {
+            res = '..';
+          }
+          isAboveRoot = true;
+        }
+      } else {
+        const slice = path.slice(lastSlash + 1, i);
+        if (res.length > 0) {
+          res += `/${slice}`;
+        } else {
+          res = slice;
+        }
+        isAboveRoot = false;
+      }
+      lastSlash = i;
+      dots = 0;
+    } else if (code === DOT && dots !== -1) {
+      ++dots;
+    } else {
+      dots = -1;
+    }
+  }
+  return res;
+}