@react-hive/honey-utils 3.3.3 → 3.5.0

package/dist/index.dev.cjs

@@ -419,11 +419,15 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony export */   getDOMRectIntersectionRatio: () => (/* binding */ getDOMRectIntersectionRatio),
 /* harmony export */   getElementOffsetRect: () => (/* binding */ getElementOffsetRect),
 /* harmony export */   getFocusableHtmlElements: () => (/* binding */ getFocusableHtmlElements),
+/* harmony export */   getLocalStorageCapabilities: () => (/* binding */ getLocalStorageCapabilities),
 /* harmony export */   isAnchorHtmlElement: () => (/* binding */ isAnchorHtmlElement),
 /* harmony export */   isContentEditableHtmlElement: () => (/* binding */ isContentEditableHtmlElement),
 /* harmony export */   isHtmlElementFocusable: () => (/* binding */ isHtmlElementFocusable),
+/* harmony export */   isLocalStorageReadable: () => (/* binding */ isLocalStorageReadable),
 /* harmony export */   parse2DMatrix: () => (/* binding */ parse2DMatrix)
 /* harmony export */ });
+/* harmony import */ var _function__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(/*! ./function */ "./src/function.ts");
+
 const FOCUSABLE_HTML_TAGS = ['INPUT', 'SELECT', 'TEXTAREA', 'BUTTON', 'A'];
 /**
  * Extracts transformation values (translate, scale, skew) from the 2D transformation matrix of a given HTML element.
@@ -584,6 +588,72 @@ const isHtmlElementFocusable = (element) => {
  * @returns An array of focusable HTMLElements in DOM order.
  */
 const getFocusableHtmlElements = (container) => Array.from(container.querySelectorAll('*')).filter(isHtmlElementFocusable);
+/**
+ * Determines whether the browser environment allows safe read access to
+ * `localStorage`. Some platforms (e.g., Safari Private Mode, sandboxed iframes)
+ * expose `localStorage` but still throw when accessed.
+ *
+ * This function **only tests read access**, making it safe even when write
+ * operations would fail due to `QuotaExceededError` or storage restrictions.
+ *
+ * @returns `true` if `localStorage` exists and calling `getItem()` does not
+ *          throw; otherwise `false`.
+ */
+const isLocalStorageReadable = () => {
+    if (typeof window === 'undefined' || !window.localStorage) {
+        return false;
+    }
+    try {
+        window.localStorage.getItem('__non_existing_key__');
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const localStorageCapabilities = {
+    readable: false,
+    writable: false,
+};
+/**
+ * Detects and returns the browser's `localStorage` read and write capabilities.
+ * The function is wrapped in `once()`, so capability detection is performed
+ * only on the first invocation and cached for all future calls.
+ *
+ * Detection logic:
+ * - **Readable**: Successfully calling `getItem()` without exceptions.
+ * - **Writable**: Successfully calling `setItem()` and `removeItem()` without
+ *   triggering `QuotaExceededError` or other security restrictions.
+ *
+ * Edge-case behavior:
+ * - In some environments, storage may be readable but not writable (e.g.,
+ *   Safari Private Mode or quota-full situations).
+ * - In SSR contexts or restricted frames, both capabilities will be `false`.
+ *
+ * @returns An object describing the available capabilities.
+ */
+const getLocalStorageCapabilities = (0,_function__WEBPACK_IMPORTED_MODULE_0__.once)(() => {
+    if (typeof window === 'undefined' || !window.localStorage) {
+        return localStorageCapabilities;
+    }
+    try {
+        window.localStorage.getItem('__test_read__');
+        localStorageCapabilities.readable = true;
+    }
+    catch {
+        return localStorageCapabilities;
+    }
+    try {
+        const key = '__test_write__';
+        window.localStorage.setItem(key, '1');
+        window.localStorage.removeItem(key);
+        localStorageCapabilities.writable = true;
+    }
+    catch {
+        // Readable but not writable (QuotaExceededError or some restrictions)
+    }
+    return localStorageCapabilities;
+});
 
 
 /***/ }),
@@ -708,13 +778,8 @@ const readFileSystemDirectoryEntries = async (directoryEntry) => {
  * Directories themselves are not returned. To avoid unnecessary noise, certain system or
  * OS-generated files can be excluded via the `skipFiles` option.
  *
- * A progress callback (`onProgress`) may be provided to receive updates each time a file
- * is discovered. This is useful when working with large folders or deeply nested structures.
- *
  * @param directoryEntry - The starting directory entry to traverse.
  * @param options - Optional settings that control traversal behavior.
- * @param processed - Internal counter used to track the number of processed files
- *   during recursive traversal. Not intended to be provided manually.
  *
  * @returns A promise resolving to a flat array of all collected `File` objects.
  */
@@ -727,28 +792,19 @@ const traverseFileSystemDirectory = async (directoryEntry, { skipFiles = [
     '.Trashes',
     '.fseventsd',
     '__MACOSX',
-], onProgress, } = {}, processed = 0) => {
+], } = {}) => {
     const skipFilesSet = new Set(skipFiles);
     const entries = await readFileSystemDirectoryEntries(directoryEntry);
     const filePromises = await (0,_async__WEBPACK_IMPORTED_MODULE_0__.runParallel)(entries, async (entry) => {
         if (entry.isDirectory) {
             return traverseFileSystemDirectory(entry, {
                 skipFiles,
-                onProgress,
-            }, processed);
+            });
         }
         else if (!skipFilesSet.has(entry.name)) {
             const file = await new Promise((resolve, reject) => {
                 entry.file(resolve, reject);
             });
-            if (onProgress) {
-                processed++;
-                onProgress({
-                    processed,
-                    path: `${directoryEntry.fullPath}/${entry.name}`,
-                    currentFile: file,
-                });
-            }
             return [file];
         }
         return [];
@@ -764,13 +820,9 @@ const traverseFileSystemDirectory = async (directoryEntry, { skipFiles = [
  * they are traversed recursively using `traverseFileSystemDirectory`, returning a
  * fully flattened list of nested files.
  *
- * The `traverseOptions` parameter can be used to skip system files or receive
- * progress updates during directory traversal.
- *
  * @param dataTransfer - The `DataTransfer` instance from a drop or paste event.
  *   If `null` or missing items, an empty array is returned.
  * @param traverseOptions - Optional settings passed to directory traversal.
- *   Useful for skipping unwanted files or enabling `onProgress` callbacks.
  *
  * @returns A promise that resolves to a flat array of all extracted `File` objects.
  *   This includes:
@@ -783,7 +835,6 @@ const readFilesFromDataTransfer = async (dataTransfer, traverseOptions = {}) =>
     if (!items) {
         return [];
     }
-    let processed = 0;
     const tasks = [];
     for (let itemIndex = 0; itemIndex < items.length; itemIndex++) {
         const item = items[itemIndex];
@@ -793,35 +844,11 @@ const readFilesFromDataTransfer = async (dataTransfer, traverseOptions = {}) =>
             // ?.() -> avoids throwing on Safari weirdness
             const entry = item.webkitGetAsEntry?.();
             if (entry?.isDirectory) {
-                tasks.push(traverseFileSystemDirectory(entry, {
-                    ...traverseOptions,
-                    onProgress: progress => {
-                        if (traverseOptions.onProgress) {
-                            processed = progress.processed;
-                            traverseOptions.onProgress({
-                                ...progress,
-                                processed,
-                            });
-                        }
-                    },
-                }, processed));
+                tasks.push(traverseFileSystemDirectory(entry, traverseOptions));
                 continue;
             }
             if (entry?.isFile) {
-                tasks.push(new Promise((resolve, reject) => {
-                    const fileEntry = entry;
-                    fileEntry.file(file => {
-                        resolve([file]);
-                        if (traverseOptions.onProgress) {
-                            processed++;
-                            traverseOptions.onProgress({
-                                processed,
-                                path: `${fileEntry.fullPath}/${fileEntry.name}`,
-                                currentFile: file,
-                            });
-                        }
-                    }, reject);
-                }));
+                tasks.push(new Promise((resolve, reject) => entry.file(file => resolve([file]), reject)));
                 continue;
             }
         }
@@ -850,6 +877,7 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony export */   isFunction: () => (/* binding */ isFunction),
 /* harmony export */   noop: () => (/* binding */ noop),
 /* harmony export */   not: () => (/* binding */ not),
+/* harmony export */   once: () => (/* binding */ once),
 /* harmony export */   retry: () => (/* binding */ retry),
 /* harmony export */   timeout: () => (/* binding */ timeout)
 /* harmony export */ });
@@ -1016,6 +1044,35 @@ const retry = (task, { maxAttempts = 3, delayMs = 300, backoff = true, onRetry }
         throw lastError;
     };
 };
+/**
+ * Wraps a function so that it can only be executed once.
+ * The wrapped function remembers (caches) the result of the first invocation
+ * and returns that same result for all subsequent calls, regardless of the arguments provided.
+ *
+ * Common use cases include:
+ * - initializing singletons
+ * - running setup logic only once
+ * - avoiding repeated expensive computations
+ *
+ * @template T - A function type whose return value should be cached.
+ *
+ * @param fn - The function to execute at most once.
+ *
+ * @returns A new function with the same signature as `fn`, but guaranteed to
+ *          execute `fn` only on the first call and return the cached result
+ *          thereafter.
+ */
+const once = (fn) => {
+    let called = false;
+    let result;
+    return function (...args) {
+        if (!called) {
+            called = true;
+            result = fn.apply(this, args);
+        }
+        return result;
+    };
+};
 
 
 /***/ }),
@@ -1029,10 +1086,12 @@ const retry = (task, { maxAttempts = 3, delayMs = 300, backoff = true, onRetry }
 __webpack_require__.r(__webpack_exports__);
 /* harmony export */ __webpack_require__.d(__webpack_exports__, {
 /* harmony export */   assert: () => (/* binding */ assert),
+/* harmony export */   isBlob: () => (/* binding */ isBlob),
 /* harmony export */   isBool: () => (/* binding */ isBool),
 /* harmony export */   isDate: () => (/* binding */ isDate),
 /* harmony export */   isDefined: () => (/* binding */ isDefined),
 /* harmony export */   isEmptyObject: () => (/* binding */ isEmptyObject),
+/* harmony export */   isError: () => (/* binding */ isError),
 /* harmony export */   isFiniteNumber: () => (/* binding */ isFiniteNumber),
 /* harmony export */   isInteger: () => (/* binding */ isInteger),
 /* harmony export */   isMap: () => (/* binding */ isMap),
@@ -1075,6 +1134,14 @@ const isNil = (value) => value === undefined || value === null;
  * @returns `true` if the value is defined (not `null` or `undefined`); otherwise, `false`.
  */
 const isDefined = (value) => value !== null && value !== undefined;
+/**
+ * Checks if a value is undefined.
+ *
+ * @param value - The value to check.
+ *
+ * @returns `true` if the value is undefined; otherwise, `false`.
+ */
+const isUndefined = (value) => value === undefined;
 /**
  * Checks if a value is a number.
  *
@@ -1115,6 +1182,22 @@ const isEmptyObject = (value) => isObject(value) && !isNull(value) && Object.key
  * @returns `true` if the value is a Date object; otherwise, `false`.
  */
 const isDate = (value) => value instanceof Date;
+/**
+ * Checks if a value is a `Blob`.
+ *
+ * @param value - The value to check.
+ *
+ * @returns `true` if the value is a Blob object; otherwise, `false`.
+ */
+const isBlob = (value) => value instanceof Blob;
+/**
+ * Checks if a value is an `Error` object.
+ *
+ * @param value - The value to check.
+ *
+ * @returns `true` if the value is an Error instance; otherwise, `false`.
+ */
+const isError = (value) => value instanceof Error;
 /**
  * Checks if a value is a valid Date object (not Invalid Date).
  *
@@ -1155,14 +1238,6 @@ const isSet = (value) => value instanceof Set;
  * @returns `true` if the value is a Symbol; otherwise, `false`.
  */
 const isSymbol = (value) => typeof value === 'symbol';
-/**
- * Checks if a value is undefined.
- *
- * @param value - The value to check.
- *
- * @returns `true` if the value is undefined; otherwise, `false`.
- */
-const isUndefined = (value) => value === undefined;
 /**
  * Checks if a value is a finite number.
  *
@@ -1468,22 +1543,26 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony export */   getDOMRectIntersectionRatio: () => (/* reexport safe */ _dom__WEBPACK_IMPORTED_MODULE_6__.getDOMRectIntersectionRatio),
 /* harmony export */   getElementOffsetRect: () => (/* reexport safe */ _dom__WEBPACK_IMPORTED_MODULE_6__.getElementOffsetRect),
 /* harmony export */   getFocusableHtmlElements: () => (/* reexport safe */ _dom__WEBPACK_IMPORTED_MODULE_6__.getFocusableHtmlElements),
+/* harmony export */   getLocalStorageCapabilities: () => (/* reexport safe */ _dom__WEBPACK_IMPORTED_MODULE_6__.getLocalStorageCapabilities),
 /* harmony export */   hashString: () => (/* reexport safe */ _string__WEBPACK_IMPORTED_MODULE_1__.hashString),
 /* harmony export */   intersection: () => (/* reexport safe */ _array__WEBPACK_IMPORTED_MODULE_2__.intersection),
 /* harmony export */   invokeIfFunction: () => (/* reexport safe */ _function__WEBPACK_IMPORTED_MODULE_3__.invokeIfFunction),
 /* harmony export */   isAnchorHtmlElement: () => (/* reexport safe */ _dom__WEBPACK_IMPORTED_MODULE_6__.isAnchorHtmlElement),
 /* harmony export */   isArray: () => (/* reexport safe */ _array__WEBPACK_IMPORTED_MODULE_2__.isArray),
+/* harmony export */   isBlob: () => (/* reexport safe */ _guards__WEBPACK_IMPORTED_MODULE_4__.isBlob),
 /* harmony export */   isBool: () => (/* reexport safe */ _guards__WEBPACK_IMPORTED_MODULE_4__.isBool),
 /* harmony export */   isContentEditableHtmlElement: () => (/* reexport safe */ _dom__WEBPACK_IMPORTED_MODULE_6__.isContentEditableHtmlElement),
 /* harmony export */   isDate: () => (/* reexport safe */ _guards__WEBPACK_IMPORTED_MODULE_4__.isDate),
 /* harmony export */   isDefined: () => (/* reexport safe */ _guards__WEBPACK_IMPORTED_MODULE_4__.isDefined),
 /* harmony export */   isEmptyArray: () => (/* reexport safe */ _array__WEBPACK_IMPORTED_MODULE_2__.isEmptyArray),
 /* harmony export */   isEmptyObject: () => (/* reexport safe */ _guards__WEBPACK_IMPORTED_MODULE_4__.isEmptyObject),
+/* harmony export */   isError: () => (/* reexport safe */ _guards__WEBPACK_IMPORTED_MODULE_4__.isError),
 /* harmony export */   isFile: () => (/* reexport safe */ _file__WEBPACK_IMPORTED_MODULE_7__.isFile),
 /* harmony export */   isFiniteNumber: () => (/* reexport safe */ _guards__WEBPACK_IMPORTED_MODULE_4__.isFiniteNumber),
 /* harmony export */   isFunction: () => (/* reexport safe */ _function__WEBPACK_IMPORTED_MODULE_3__.isFunction),
 /* harmony export */   isHtmlElementFocusable: () => (/* reexport safe */ _dom__WEBPACK_IMPORTED_MODULE_6__.isHtmlElementFocusable),
 /* harmony export */   isInteger: () => (/* reexport safe */ _guards__WEBPACK_IMPORTED_MODULE_4__.isInteger),
+/* harmony export */   isLocalStorageReadable: () => (/* reexport safe */ _dom__WEBPACK_IMPORTED_MODULE_6__.isLocalStorageReadable),
 /* harmony export */   isMap: () => (/* reexport safe */ _guards__WEBPACK_IMPORTED_MODULE_4__.isMap),
 /* harmony export */   isNil: () => (/* reexport safe */ _guards__WEBPACK_IMPORTED_MODULE_4__.isNil),
 /* harmony export */   isNilOrEmptyString: () => (/* reexport safe */ _string__WEBPACK_IMPORTED_MODULE_1__.isNilOrEmptyString),
@@ -1499,6 +1578,7 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony export */   isValidDate: () => (/* reexport safe */ _guards__WEBPACK_IMPORTED_MODULE_4__.isValidDate),
 /* harmony export */   noop: () => (/* reexport safe */ _function__WEBPACK_IMPORTED_MODULE_3__.noop),
 /* harmony export */   not: () => (/* reexport safe */ _function__WEBPACK_IMPORTED_MODULE_3__.not),
+/* harmony export */   once: () => (/* reexport safe */ _function__WEBPACK_IMPORTED_MODULE_3__.once),
 /* harmony export */   parse2DMatrix: () => (/* reexport safe */ _dom__WEBPACK_IMPORTED_MODULE_6__.parse2DMatrix),
 /* harmony export */   parseFileName: () => (/* reexport safe */ _file__WEBPACK_IMPORTED_MODULE_7__.parseFileName),
 /* harmony export */   pipe: () => (/* reexport safe */ _array__WEBPACK_IMPORTED_MODULE_2__.pipe),