@mlightcad/common 1.2.3 → 1.2.4

package/lib/loader/AcCmLoadingManager.d.ts

@@ -0,0 +1,166 @@
+/**
+ * @fileoverview Loading management system for the AutoCAD Common library.
+ *
+ * This module provides a centralized loading manager that tracks and coordinates
+ * multiple file loading operations with progress reporting, error handling, and
+ * URL modification capabilities.
+ *
+ * @module AcCmLoadingManager
+ * @version 1.0.0
+ */
+import { AcCmLoader } from './AcCmLoader';
+/**
+ * Callback function that is called when loading starts.
+ *
+ * @param {string} url - The URL of the item that just started loading.
+ * @param {number} itemsLoaded - The number of items already loaded so far.
+ * @param {number} itemsTotal - The total number of items to be loaded.
+ */
+export type AcCmOnStartCallback = (url: string, itemsLoaded: number, itemsTotal: number) => void;
+/**
+ * Callback function that is called when all loading operations are completed successfully.
+ */
+export type AcCmOnLoadCallback = () => void;
+/**
+ * Callback function that is called when an individual item completes loading.
+ *
+ * @param {string} url - The URL of the item that just finished loading.
+ * @param {number} itemsLoaded - The number of items loaded so far.
+ * @param {number} itemsTotal - The total number of items to be loaded.
+ */
+export type AcCmOnProgressCallback = (url: string, itemsLoaded: number, itemsTotal: number) => void;
+/**
+ * Callback function that is called when any loading operation encounters an error.
+ *
+ * @param {string} url - The URL of the item that failed to load.
+ */
+export type AcCmOnErrorCallback = (url: string) => void;
+/**
+ * Function that modifies URLs before loading requests are sent.
+ *
+ * This callback allows intercepting and modifying URLs to implement custom loading
+ * behavior, such as adding authentication tokens or redirecting to different servers.
+ *
+ * @param {string} url - The original URL.
+ * @returns {string} The modified URL or the original URL if no changes are needed.
+ */
+export type AcCmUrlModifier = (url: string) => string;
+/**
+ * Centralized loading manager that handles and tracks multiple loading operations.
+ *
+ * This class manages the loading state across multiple file operations, providing
+ * progress tracking, error handling, and URL modification capabilities. A default
+ * global instance is created and used by loaders if not supplied manually.
+ *
+ * Separate loading managers can be useful when you need independent loading progress
+ * tracking (e.g., separate progress bars for different types of resources).
+ *
+ * @example
+ * ```typescript
+ * import { AcCmLoadingManager } from './AcCmLoadingManager'
+ *
+ * // Create a custom loading manager
+ * const manager = new AcCmLoadingManager()
+ *
+ * // Set up callbacks
+ * manager.onStart = (url, loaded, total) => {
+ *   console.log(`Started loading: ${url} (${loaded}/${total})`)
+ * }
+ *
+ * manager.onProgress = (url, loaded, total) => {
+ *   console.log(`Progress: ${url} (${loaded}/${total})`)
+ * }
+ *
+ * manager.onLoad = () => {
+ *   console.log('All loading completed!')
+ * }
+ *
+ * manager.onError = (url) => {
+ *   console.error(`Failed to load: ${url}`)
+ * }
+ * ```
+ */
+export declare class AcCmLoadingManager {
+    /**
+     * This function will be called when loading starts.
+     */
+    onStart?: AcCmOnStartCallback;
+    /**
+     * This function will be called when all loading is completed. By default this is undefined, unless
+     * passed in the constructor.
+     */
+    onLoad?: AcCmOnLoadCallback;
+    /**
+     * This function will be called when an item is complete.
+     */
+    onProgress?: AcCmOnProgressCallback;
+    /**
+     * This function will be called when any item errors.
+     */
+    onError?: AcCmOnErrorCallback;
+    private isLoading;
+    private itemsLoaded;
+    private itemsTotal;
+    private handlers;
+    private urlModifier?;
+    /**
+     * Create a new AcCmLoadingManager instance
+     * @param onLoad this function will be called when all loaders are done.
+     * @param onProgress this function will be called when an item is complete.
+     * @param onError this function will be called a loader encounters errors.
+     */
+    constructor(onLoad?: AcCmOnLoadCallback, onProgress?: AcCmOnProgressCallback, onError?: AcCmOnErrorCallback);
+    /**
+     * This should be called by any loader using the manager when the loader starts loading an url.
+     * @param url The loaded url
+     */
+    itemStart(url: string): void;
+    /**
+     * This should be called by any loader using the manager when the loader ended loading an url.
+     * @param url The loaded url
+     */
+    itemEnd(url: string): void;
+    /**
+     * This should be called by any loader using the manager when the loader errors loading an url.
+     * @param url The loaded url
+     */
+    itemError(url: string): void;
+    /**
+     * Given a URL, uses the URL modifier callback (if any) and returns a resolved URL. If no URL
+     * modifier is set, returns the original URL.
+     * @param url The url to load
+     * @returns Return resolved URL
+     */
+    resolveURL(url: string): string;
+    /**
+     * If provided, the callback will be passed each resource URL before a request is sent. The callback
+     * may return the original URL, or a new URL to override loading behavior. This behavior can be used
+     * to load assets from .ZIP files, drag-and-drop APIs, and Data URIs.
+     * @param transform URL modifier callback. Called with url argument, and must return resolvedURL.
+     * @returns Return this object
+     */
+    setURLModifier(transform: AcCmUrlModifier): this;
+    /**
+     * Register a loader with the given regular expression. Can be used to define what loader should
+     * be used in order to load specific files. A typical use case is to overwrite the default loader
+     * for textures.
+     * @param regex A regular expression.
+     * @param loader The loader.
+     * @returns Return this object
+     */
+    addHandler(regex: RegExp, loader: AcCmLoader): this;
+    /**
+     * Remove the loader for the given regular expression.
+     * @param regex A regular expression.
+     * @returns Return this object
+     */
+    removeHandler(regex: RegExp): this;
+    /**
+     * Retrieve the registered loader for the given file path.
+     * @param file The file path.
+     * @returns Return the registered loader for the given file path.
+     */
+    getHandler(file: string): RegExp | AcCmLoader | null;
+}
+export declare const DefaultLoadingManager: AcCmLoadingManager;
+//# sourceMappingURL=AcCmLoadingManager.d.ts.map

package/lib/loader/AcCmLoadingManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AcCmLoadingManager.d.ts","sourceRoot":"","sources":["../../src/loader/AcCmLoadingManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAEzC;;;;;;GAMG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAChC,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,KACf,IAAI,CAAA;AAET;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,IAAI,CAAA;AAE3C;;;;;;GAMG;AACH,MAAM,MAAM,sBAAsB,GAAG,CACnC,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,KACf,IAAI,CAAA;AAET;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;AAEvD;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAA;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,qBAAa,kBAAkB;IAC7B;;OAEG;IACI,OAAO,CAAC,EAAE,mBAAmB,CAAA;IACpC;;;OAGG;IACI,MAAM,CAAC,EAAE,kBAAkB,CAAA;IAClC;;OAEG;IACI,UAAU,CAAC,EAAE,sBAAsB,CAAA;IAC1C;;OAEG;IACI,OAAO,CAAC,EAAE,mBAAmB,CAAA;IACpC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,WAAW,CAAQ;IAC3B,OAAO,CAAC,UAAU,CAAQ;IAC1B,OAAO,CAAC,QAAQ,CAAyB;IACzC,OAAO,CAAC,WAAW,CAAC,CAAiB;IAErC;;;;;OAKG;gBAED,MAAM,CAAC,EAAE,kBAAkB,EAC3B,UAAU,CAAC,EAAE,sBAAsB,EACnC,OAAO,CAAC,EAAE,mBAAmB;IAiB/B;;;OAGG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM;IAYrB;;;OAGG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM;IAgBnB;;;OAGG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM;IAMrB;;;;;OAKG;IACH,UAAU,CAAC,GAAG,EAAE,MAAM;IAQtB;;;;;;OAMG;IACH,cAAc,CAAC,SAAS,EAAE,eAAe;IAMzC;;;;;;;OAOG;IACH,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU;IAK5C;;;;OAIG;IACH,aAAa,CAAC,KAAK,EAAE,MAAM;IAU3B;;;;OAIG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM;CAcxB;AAED,eAAO,MAAM,qBAAqB,oBAAyC,CAAA"}

package/lib/loader/AcCmLoadingManager.js

@@ -0,0 +1,172 @@
+/**
+ * @fileoverview Loading management system for the AutoCAD Common library.
+ *
+ * This module provides a centralized loading manager that tracks and coordinates
+ * multiple file loading operations with progress reporting, error handling, and
+ * URL modification capabilities.
+ *
+ * @module AcCmLoadingManager
+ * @version 1.0.0
+ */
+/**
+ * Centralized loading manager that handles and tracks multiple loading operations.
+ *
+ * This class manages the loading state across multiple file operations, providing
+ * progress tracking, error handling, and URL modification capabilities. A default
+ * global instance is created and used by loaders if not supplied manually.
+ *
+ * Separate loading managers can be useful when you need independent loading progress
+ * tracking (e.g., separate progress bars for different types of resources).
+ *
+ * @example
+ * ```typescript
+ * import { AcCmLoadingManager } from './AcCmLoadingManager'
+ *
+ * // Create a custom loading manager
+ * const manager = new AcCmLoadingManager()
+ *
+ * // Set up callbacks
+ * manager.onStart = (url, loaded, total) => {
+ *   console.log(`Started loading: ${url} (${loaded}/${total})`)
+ * }
+ *
+ * manager.onProgress = (url, loaded, total) => {
+ *   console.log(`Progress: ${url} (${loaded}/${total})`)
+ * }
+ *
+ * manager.onLoad = () => {
+ *   console.log('All loading completed!')
+ * }
+ *
+ * manager.onError = (url) => {
+ *   console.error(`Failed to load: ${url}`)
+ * }
+ * ```
+ */
+var AcCmLoadingManager = /** @class */ (function () {
+    /**
+     * Create a new AcCmLoadingManager instance
+     * @param onLoad this function will be called when all loaders are done.
+     * @param onProgress this function will be called when an item is complete.
+     * @param onError this function will be called a loader encounters errors.
+     */
+    function AcCmLoadingManager(onLoad, onProgress, onError) {
+        this.isLoading = false;
+        this.itemsLoaded = 0;
+        this.itemsTotal = 0;
+        this.urlModifier = undefined;
+        this.handlers = [];
+        // Refer to #5689 for the reason why we don't set .onStart
+        // in the constructor
+        this.onStart = undefined;
+        this.onLoad = onLoad;
+        this.onProgress = onProgress;
+        this.onError = onError;
+    }
+    /**
+     * This should be called by any loader using the manager when the loader starts loading an url.
+     * @param url The loaded url
+     */
+    AcCmLoadingManager.prototype.itemStart = function (url) {
+        this.itemsTotal++;
+        if (this.isLoading === false) {
+            if (this.onStart !== undefined) {
+                this.onStart(url, this.itemsLoaded, this.itemsTotal);
+            }
+        }
+        this.isLoading = true;
+    };
+    /**
+     * This should be called by any loader using the manager when the loader ended loading an url.
+     * @param url The loaded url
+     */
+    AcCmLoadingManager.prototype.itemEnd = function (url) {
+        this.itemsLoaded++;
+        if (this.onProgress !== undefined) {
+            this.onProgress(url, this.itemsLoaded, this.itemsTotal);
+        }
+        if (this.itemsLoaded === this.itemsTotal) {
+            this.isLoading = false;
+            if (this.onLoad !== undefined) {
+                this.onLoad();
+            }
+        }
+    };
+    /**
+     * This should be called by any loader using the manager when the loader errors loading an url.
+     * @param url The loaded url
+     */
+    AcCmLoadingManager.prototype.itemError = function (url) {
+        if (this.onError !== undefined) {
+            this.onError(url);
+        }
+    };
+    /**
+     * Given a URL, uses the URL modifier callback (if any) and returns a resolved URL. If no URL
+     * modifier is set, returns the original URL.
+     * @param url The url to load
+     * @returns Return resolved URL
+     */
+    AcCmLoadingManager.prototype.resolveURL = function (url) {
+        if (this.urlModifier) {
+            return this.urlModifier(url);
+        }
+        return url;
+    };
+    /**
+     * If provided, the callback will be passed each resource URL before a request is sent. The callback
+     * may return the original URL, or a new URL to override loading behavior. This behavior can be used
+     * to load assets from .ZIP files, drag-and-drop APIs, and Data URIs.
+     * @param transform URL modifier callback. Called with url argument, and must return resolvedURL.
+     * @returns Return this object
+     */
+    AcCmLoadingManager.prototype.setURLModifier = function (transform) {
+        this.urlModifier = transform;
+        return this;
+    };
+    /**
+     * Register a loader with the given regular expression. Can be used to define what loader should
+     * be used in order to load specific files. A typical use case is to overwrite the default loader
+     * for textures.
+     * @param regex A regular expression.
+     * @param loader The loader.
+     * @returns Return this object
+     */
+    AcCmLoadingManager.prototype.addHandler = function (regex, loader) {
+        this.handlers.push(regex, loader);
+        return this;
+    };
+    /**
+     * Remove the loader for the given regular expression.
+     * @param regex A regular expression.
+     * @returns Return this object
+     */
+    AcCmLoadingManager.prototype.removeHandler = function (regex) {
+        var index = this.handlers.indexOf(regex);
+        if (index !== -1) {
+            this.handlers.splice(index, 2);
+        }
+        return this;
+    };
+    /**
+     * Retrieve the registered loader for the given file path.
+     * @param file The file path.
+     * @returns Return the registered loader for the given file path.
+     */
+    AcCmLoadingManager.prototype.getHandler = function (file) {
+        for (var i = 0, l = this.handlers.length; i < l; i += 2) {
+            var regex = this.handlers[i];
+            var loader = this.handlers[i + 1];
+            if (regex.global)
+                regex.lastIndex = 0; // see #17920
+            if (regex.test(file)) {
+                return loader;
+            }
+        }
+        return null;
+    };
+    return AcCmLoadingManager;
+}());
+export { AcCmLoadingManager };
+export var DefaultLoadingManager = /*@__PURE__*/ new AcCmLoadingManager();
+//# sourceMappingURL=AcCmLoadingManager.js.map

package/lib/loader/AcCmLoadingManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AcCmLoadingManager.js","sourceRoot":"","sources":["../../src/loader/AcCmLoadingManager.ts"],"names":[],"mappings":"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"}

package/lib/loader/index.d.ts

@@ -0,0 +1,3 @@
+export * from './AcCmLoadingManager';
+export * from './AcCmLoader';
+//# sourceMappingURL=index.d.ts.map

package/lib/loader/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/loader/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAA;AACpC,cAAc,cAAc,CAAA"}

package/lib/loader/index.js

@@ -0,0 +1,3 @@
+export * from './AcCmLoadingManager';
+export * from './AcCmLoader';
+//# sourceMappingURL=index.js.map

package/lib/loader/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/loader/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAA;AACpC,cAAc,cAAc,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mlightcad/common",
-  "version": "1.2.3",
+  "version": "1.2.4",
   "license": "MIT",
   "type": "module",
   "repository": {