@3dsource/utils 1.0.19 → 1.0.20

package/LICENSE

@@ -1,14 +1,14 @@
-Copyright (c) 2025 3dsource
-All Rights Reserved.
-
-This software and associated documentation files (the “Software”) are proprietary
-and confidential. Unauthorized copying, modification, distribution, or any other
-use of the Software, in whole or in part, without the prior written consent of
-the copyright holder is strictly prohibited.
-
-THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
-COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
-IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
-CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+Copyright (c) 2025 3dsource
+All Rights Reserved.
+
+This software and associated documentation files (the “Software”) are proprietary
+and confidential. Unauthorized copying, modification, distribution, or any other
+use of the Software, in whole or in part, without the prior written consent of
+the copyright holder is strictly prohibited.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,46 +1,149 @@
-# @3dsource/utils
-
-### A set of utils for using in 3dsource projects
-
-## Installation
-
-### add peer dependencies
-
-_List of peer dependencies_
-
-```json
-{
-  "rxjs": "^7.8.2",
-  "ts-md5": "^1.3.1",
-  "uuid": "^11.1.0"
-}
-```
-
-```shell
-  npx install-peerdeps @3dsource/utils
-```
-
-### add library
-
-```shell
-  npm i @3dsource/utils
-```
-
-## Usage
-
-_List of utils_
-
-- [color](src/lib/color)
-- [constants](src/lib/constants)
-- [csv](src/lib/csv)
-- [dev](src/lib/dev)
-- [filenaming](src/lib/filenaming)
-- [geom](src/lib/geom)
-- [helpers](src/lib/helpers)
-- [image](src/lib/image)
-- [interfaces](src/lib/interfaces)
-- [math](src/lib/math)
-- [mutex](src/lib/mutex)
-- [predicates](src/lib/predicates)
-- [rxjs](src/lib/rxjs)
-- [strings](src/lib/strings)
+# @3dsource/utils
+
+A comprehensive collection of utility functions and helpers for 3dsource projects. This library provides common
+functionality used across different 3dsource applications and libraries.
+
+## Overview
+
+The utils library offers a wide range of utility functions organized by category:
+
+- Color manipulation and conversion
+- Mathematical operations for 3D applications
+- Geometry utilities
+- File and image processing
+- String manipulation
+- RxJS operators and utilities
+- Development helpers
+- And more
+
+## Installation
+
+### Prerequisites
+
+- Node.js 20+
+- TypeScript 5.8+
+
+### Peer Dependencies
+
+This library requires the following peer dependencies:
+
+```json
+{
+  "rxjs": "^7.8.2",
+  "ts-md5": "^1.3.1",
+  "uuid": "^11.1.0"
+}
+```
+
+### Library Installation
+
+```shell
+  npm i @3dsource/utils
+```
+
+## Usage
+
+Import the specific utility functions you need:
+
+```typescript
+import { hexToRgb } from '@3dsource/utils/color';
+import { clamp } from '@3dsource/utils/math';
+import { generateUUID } from '@3dsource/utils/helpers';
+```
+
+## Available Utilities
+
+### Color Utilities
+
+The `color` module provides functions for working with colors:
+
+```typescript
+import { hexToRgb, rgbToHex, darken, lighten } from '@3dsource/utils/color';
+
+// Convert hex color to RGB
+const rgb = hexToRgb('#ff0000'); // { r: 255, g: 0, b: 0 }
+
+// Convert RGB to hex
+const hex = rgbToHex(255, 0, 0); // '#ff0000'
+
+// Darken a color by 20%
+const darkRed = darken('#ff0000', 0.2);
+```
+
+### Math Utilities
+
+The `math` module provides mathematical functions:
+
+```typescript
+import { clamp, lerp, degToRad } from '@3dsource/utils/math';
+
+// Clamp a value between min and max
+const clampedValue = clamp(150, 0, 100); // 100
+
+// Linear interpolation
+const interpolated = lerp(0, 100, 0.5); // 50
+
+// Convert degrees to radians
+const radians = degToRad(180); // 3.14159...
+```
+
+### Geometry Utilities
+
+The `geom` module provides geometry-related functions:
+
+```typescript
+import { calculateDistance, isPointInPolygon } from '@3dsource/utils/geom';
+
+// Calculate distance between two points
+const distance = calculateDistance({ x: 0, y: 0 }, { x: 3, y: 4 }); // 5
+```
+
+### Complete List of Utility Categories
+
+- **[color](src/lib/color)** - Color manipulation and conversion
+- **[constants](src/lib/constants)** - Common constants used across the project
+- **[csv](src/lib/csv)** - CSV parsing and generation
+- **[dev](src/lib/dev)** - Development utilities
+- **[filenaming](src/lib/filenaming)** - File naming utilities
+- **[geom](src/lib/geom)** - Geometry utilities
+- **[helpers](src/lib/helpers)** - General helper functions
+- **[image](src/lib/image)** - Image processing utilities
+- **[interfaces](src/lib/interfaces)** - Common TypeScript interfaces
+- **[math](src/lib/math)** - Mathematical functions
+- **[mutex](src/lib/mutex)** - Mutex implementation for async operations
+- **[predicates](src/lib/predicates)** - Type guards and predicates
+- **[rxjs](src/lib/rxjs)** - RxJS operators and utilities
+- **[strings](src/lib/strings)** - String manipulation functions
+
+## Examples
+
+### Working with UUIDs
+
+```typescript
+import { generateUUID, isValidUUID } from '@3dsource/utils/helpers';
+
+// Generate a new UUID
+const id = generateUUID();
+
+// Check if a string is a valid UUID
+const isValid = isValidUUID(id); // true
+```
+
+### Using RxJS Utilities
+
+```typescript
+import { retryWithBackoff } from '@3dsource/utils/rxjs';
+import { of, throwError } from 'rxjs';
+import { mergeMap } from 'rxjs/operators';
+
+// Retry an operation with exponential backoff
+function getData() {
+  return of(Math.random()).pipe(
+    mergeMap((val) => (val < 0.5 ? throwError(() => new Error('Failed')) : of(val))),
+    retryWithBackoff({
+      initialInterval: 100,
+      maxRetries: 3,
+    }),
+  );
+}
+```

package/fesm2022/3dsource-utils.mjs

@@ -2,8 +2,7 @@ import { Subject, fromEvent, startWith, map as map$1, from, switchMap, finalize,
 import { filter, map, distinctUntilChanged, tap } from 'rxjs/operators';
 import { v4 } from 'uuid';
 import { Md5 } from 'ts-md5';
-import { InjectionToken, inject } from '@angular/core';
-import { DOCUMENT } from '@angular/common';
+import { InjectionToken, inject, DOCUMENT } from '@angular/core';
 
 /**
  * RGB from each of the CMYK values to determine a return as an any[].
@@ -633,47 +632,58 @@ function textForSearch(value, caseSensitive = false) {
 }
 
 /**
- * Creates a predicate function to filter records from a collection based on specified criteria.
+ * Builds a predicate that checks whether a record matches **all** provided criteria.
  *
- * The `where` function accepts a criteria object with key-value pairs, indicating the fields
- * and their expected values for filtering. It returns a predicate function that filters a collection
- * of records. This predicate checks if records match the criteria using a case-insensitive comparison,
- * making it particularly useful in conjunction with the `textForSearch` function, which standardizes
- * strings for such comparisons.
+ * Behavior:
+ * - Only keys with **defined** values in `criteria` are considered; keys with `undefined` are ignored.
+ * - Both the criterion value and the corresponding record value are normalized using `textForSearch(value, caseSensitive)`,
+ *   then compared for **equality** (not substring/contains).
+ * - By default (`caseSensitive = false`), comparisons are case-insensitive and tolerant to extra spacing
+ *   (per `textForSearch`). When `caseSensitive = true`, comparisons preserve original casing.
+ * - If **no** criteria have defined values, the resulting predicate always returns **false**.
  *
- * Each criterion value is first processed with `textForSearch` to normalize spacing and case,
- * ensuring consistent and predictable filtering. The comparison between each record's field value
- * and the criterion value is thus case-insensitive and ignores extra spaces.
+ * @remarks
+ * **Nested object stringification (runtime edge case):**
+ * Although the TypeScript types constrain comparisons to primitive fields via `ISearchable<T>`,
+ * at runtime any non-primitive value that slips through (e.g., due to loose typing) will be coerced to a string
+ * before normalization. For example:
  *
- * @param {Partial<Record<K, T[K]>>} criteria - An object representing the filtering criteria.
- * Keys correspond to the record's fields to be filtered, and values are the expected values for those fields,
- * processed in a case-insensitive manner. Undefined values are ignored.
+ * ```ts
+ * // Runtime behavior with nested objects (typing omitted for brevity)
+ * const record = { age: 20, test: { hello: 'world' } } as any;
+ * // textForSearch(record.test, false) => "[object_object]" (e.g., "[object Object]" normalized)
+ * const criteria = { age: 20, test: "[object_object]" } as any;
+ * const matches = where<any>(criteria)(record);
+ * // matches === true
+ * ```
  *
- * @param {boolean} caseSensitive - A flag indicating whether the comparison should be case-sensitive.
- * If set to true, the function will perform case-sensitive comparisons, preserving the original casing of input strings.
- * If set to false (default), the function will convert the input strings to lowercase for case-insensitive comparisons
+ * In other words, `{ hello: 'world' }` is interpreted as the string `"[object_object]"` after normalization,
+ * so a criterion with `test: "[object_object]"` will successfully match.
  *
- * @returns {(record: T) => boolean} A predicate function that takes a record of type `T`
- * and returns `true` if the record's field values match all criteria, otherwise `false`.
+ * @typeParam T - The object type whose **primitive** fields are comparable via `ISearchable<T>`.
+ *
+ * @param criteria - A partial set of key–value pairs over `ISearchable<T>` to match against.
+ *   Only keys with defined values participate in the comparison.
+ * @param caseSensitive - Whether comparisons should be case-sensitive. Defaults to `false`.
+ *
+ * @returns A predicate `(record: ISearchable<T>) => boolean` that is `true` iff the record matches **all** criteria.
  *
  * @example
- * // Define a collection of items
- * const items = [
- *   { name: "Apple", category: "Fruit" },
+ * type Item = { name: string; category: string; note?: string };
+ * const items: Item[] = [
+ *   { name: "Apple",  category: "Fruit" },
  *   { name: "Carrot", category: "Vegetable" },
  *   { name: "Banana", category: "Fruit" }
  * ];
  *
- * // Create a predicate to find fruits, using a case-insensitive comparison
- * const isFruit = where({ category: "fruit" }); // 'fruit' will match 'Fruit' in items
- *
- * // Filter the collection with the predicate
+ * // Case-insensitive equality match on category ("fruit" matches "Fruit")
+ * const isFruit = where<Item>({ category: "fruit" });
  * const fruits = items.filter(isFruit);
- * // Output: [{ name: "Apple", category: "Fruit" }, { name: "Banana", category: "Fruit" }]
+ * // → [{ name: "Apple", category: "Fruit" }, { name: "Banana", category: "Fruit" }]
  *
- * @typeparam T - Specifies the type of records in the collection to be filtered. It extends `object`,
- * ensuring the function is only used with object types. This generic approach allows for flexible usage
- * with various record structures.
+ * // Empty criteria → predicate always false
+ * const matchNothing = where<Item>({});
+ * items.filter(matchNothing); // → []
  */
 function where(criteria, caseSensitive = false) {
     const preComputedEntries = Object.entries(criteria)
@@ -682,11 +692,38 @@ function where(criteria, caseSensitive = false) {
     return (record) => {
         return (preComputedEntries.length > 0 &&
             preComputedEntries.every(([key, criterionValue]) => {
-                return (textForSearch(record[key] ?? '', caseSensitive) ===
-                    criterionValue);
+                return (textForSearch(record[key] ?? '', caseSensitive) === criterionValue);
             }));
     };
 }
+/**
+ * Builds a predicate that is the logical **negation** of `where`.
+ *
+ * Behavior mirrors `where(criteria, caseSensitive)` but returns `true` when a record **does not**
+ * satisfy all criteria. Notable edge cases:
+ * - If `criteria` has no defined values (i.e., `where` would always return `false`), this negated predicate
+ *   will always return **true**.
+ * - **Nested object stringification (runtime edge case):** If a nested object is compared against a criterion
+ *   like `"[object_object]"` (after normalization), the original `where` would return `true`, so `whereNot` will return `false`.
+ *
+ * @typeParam T - The object type whose **primitive** fields are comparable via `ISearchable<T>`.
+ *
+ * @param criteria - Same as in `where`.
+ * @param caseSensitive - Same as in `where`. Defaults to `false`.
+ *
+ * @returns A predicate `(record: ISearchable<T>) => boolean` that is `true` iff the record **fails** the `where` check.
+ *
+ * @example
+ * type Item = { name: string; category: string };
+ * const items: Item[] = [
+ *   { name: "Apple",  category: "Fruit" },
+ *   { name: "Carrot", category: "Vegetable" }
+ * ];
+ *
+ * const isNotFruit = whereNot<Item>({ category: "fruit" });
+ * items.filter(isNotFruit);
+ * // → [{ name: "Carrot", category: "Vegetable" }]
+ */
 function whereNot(criteria, caseSensitive = false) {
     const whereFunc = where(criteria, caseSensitive);
     return (record) => {