@3dsource/utils 0.0.1

package/src/lib/predicates/textForSearch.ts

@@ -0,0 +1,34 @@
+const cache: Record<string, unknown> = {};
+
+/**
+ * Converts a given value to a string suitable for search comparisons.
+ * The resulting string is in lowercase, with consecutive spaces replaced by underscores.
+ * The function uses a cache to improve performance by storing and reusing the results of previous conversions.
+ *
+ * @param {any} value - The value to be converted to a search-friendly string.
+ * It can be of any type, but it will be coerced to a string if not already one.
+ *
+ * @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
+ *
+ * @returns {string} The processed string, which is trimmed, converted to lowercase (unless caseSensitive is true),
+ * and has all sequences of spaces replaced with underscores. This string is either
+ * retrieved from the cache or freshly computed and then cached.
+ *
+ */
+export function textForSearch(value: unknown, caseSensitive = false): string {
+  const key = `${value}_${caseSensitive}`;
+  return (cache[key] ||
+    (() => {
+      let result = String(value).trim().replace(/ +/gi, '_');
+
+      if (!caseSensitive) {
+        result = result.toLowerCase();
+      }
+
+      cache[key] = result;
+
+      return result;
+    })()) as string;
+}

package/src/lib/predicates/where.ts

@@ -0,0 +1,76 @@
+import { textForSearch } from './textForSearch';
+import type { TruthyTypesOf } from 'rxjs';
+
+/**
+ * Creates a predicate function to filter records from a collection based on specified 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.
+ *
+ * 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.
+ *
+ * @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.
+ *
+ * @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
+ *
+ * @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`.
+ *
+ * @example
+ * // Define a collection of items
+ * const items = [
+ *   { 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
+ * const fruits = items.filter(isFruit);
+ * // Output: [{ 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.
+ */
+
+export function where<T extends object>(
+  criteria: Partial<TruthyTypesOf<T>>,
+  caseSensitive = false,
+): (record: T) => boolean {
+  const preComputedEntries = Object.entries(criteria)
+    .filter(([, value]) => value !== undefined)
+    .map(([key, value]) => [key, textForSearch(value, caseSensitive)] as const);
+
+  return (record: T): boolean => {
+    return (
+      preComputedEntries.length > 0 &&
+      preComputedEntries.every(([key, criterionValue]) => {
+        return (
+          textForSearch(record[key as keyof T] ?? '', caseSensitive) ===
+          criterionValue
+        );
+      })
+    );
+  };
+}
+export function whereNot<T extends object>(
+  criteria: Partial<TruthyTypesOf<T>>,
+  caseSensitive = false,
+): (record: T) => boolean {
+  const whereFunc = where(criteria, caseSensitive);
+  return (record: T) => {
+    return !whereFunc(record);
+  };
+}

package/src/lib/rxjs/index.ts

@@ -0,0 +1,3 @@
+export * from './leadingTrailingDebounceTime';
+export * from './smoothTransition';
+export * from './tapLog';

package/src/lib/rxjs/leadingTrailingDebounceTime.ts

@@ -0,0 +1,86 @@
+import type { SchedulerLike, Subscriber, Subscription } from 'rxjs';
+import { asyncScheduler, Observable, timer } from 'rxjs';
+
+/**
+ * Emits the most recent value emitted by the source Observable after a
+ * specified time span has passed without another source emission.
+ *
+ * This is a combination of `debounceTime` and `auditTime` operators.
+ *
+ * The leading value is emitted immediately, and trailing values are debounced.
+ *
+ * @param dueTime The time to wait before emitting the last value.
+ * @param scheduler The scheduler to use for the timeout.
+ * @returns A function that returns an Observable that mirrors the source Observable, but applies the specified debouncing.
+ */
+export function leadingTrailingDebounceTime<T>(
+  dueTime: number,
+  scheduler: SchedulerLike = asyncScheduler,
+): (source: Observable<T>) => Observable<T> {
+  return (source: Observable<T>) =>
+    new Observable<T>((subscriber: Subscriber<T>) => {
+      let hasValue = false;
+      let lastValue: T | null = null;
+      let timerSubscription: Subscription | null = null;
+      let leading = true; // Controls whether we emit immediately.
+
+      const clearTimer = () => {
+        if (timerSubscription) {
+          timerSubscription.unsubscribe();
+          timerSubscription = null;
+        }
+      };
+
+      const resetValues = () => {
+        hasValue = false;
+        lastValue = null;
+        leading = true; // Reset so the next new value is immediate.
+      };
+
+      const emitLastValue = () => {
+        if (hasValue && lastValue !== null) {
+          subscriber.next(lastValue);
+          resetValues();
+        }
+      };
+
+      const sourceSubscription = source.subscribe({
+        next: (value) => {
+          // If we are "leading", emit immediately and switch leading off
+          if (leading) {
+            subscriber.next(value);
+            leading = false;
+            timerSubscription = timer(dueTime, scheduler).subscribe(() => {
+              resetValues();
+              clearTimer();
+            });
+            return;
+          }
+
+          // Otherwise, save the value and start (or restart) timer
+          hasValue = true;
+          lastValue = value;
+          clearTimer();
+          timerSubscription = timer(dueTime, scheduler).subscribe(() => {
+            emitLastValue();
+          });
+        },
+        error: (err: unknown) => {
+          clearTimer();
+          subscriber.error(err);
+        },
+        complete: () => {
+          // If there is a pending emission, emit it before completing
+          clearTimer();
+          emitLastValue();
+          subscriber.complete();
+        },
+      });
+
+      // Cleanup logic
+      return () => {
+        clearTimer();
+        sourceSubscription.unsubscribe();
+      };
+    });
+}

package/src/lib/rxjs/smoothTransition.ts

@@ -0,0 +1,29 @@
+import type { Observable } from 'rxjs';
+import { animationFrameScheduler, interval } from 'rxjs';
+import { distinctUntilChanged, map } from 'rxjs/operators';
+import { clampf, lerp } from '../math';
+
+/**
+ * Creates an observable that emits values transitioning smoothly from the start value to the end value over a specified duration.
+ * The transition is performed using linear interpolation (lerp) and clamped to the range [0, 1].
+ *
+ * @param {number} start - The starting value of the transition.
+ * @param {number} end - The ending value of the transition.
+ * @param {number} duration - The duration of the transition in milliseconds.
+ * @returns {Observable<number>} An observable that emits the interpolated values from start to end over the specified duration.
+ */
+export const smoothTransition = (
+  start: number,
+  end: number,
+  duration: number,
+): Observable<number> => {
+  const startTime = animationFrameScheduler.now();
+  return interval(0, animationFrameScheduler).pipe(
+    map(() => {
+      const elapsed = (animationFrameScheduler.now() - startTime) / duration;
+      return clampf(0, 1, elapsed);
+    }),
+    distinctUntilChanged(),
+    map((fraction) => lerp(start, end, fraction)),
+  );
+};

package/src/lib/rxjs/tapLog.ts

@@ -0,0 +1,13 @@
+import { tap } from 'rxjs/operators';
+import type { Observable } from 'rxjs';
+import { Logger } from '../dev';
+import { COLOR_CODES } from '../constants';
+
+export const tapLog =
+  <T>(text: string, ...args: any): ((source: Observable<T>) => Observable<T>) =>
+  (source: Observable<T>) =>
+    source.pipe(
+      tap((data) => {
+        Logger.colored(...COLOR_CODES.TAP_LOG, text, data, ...args);
+      }),
+    );

package/src/lib/strings/index.ts

@@ -0,0 +1 @@
+export * from './pad';

package/src/lib/strings/pad.ts

@@ -0,0 +1,18 @@
+/**
+ * Adds required number of symbols before input
+ * @param input input string
+ * @param size amount of total symbols
+ * @param symbol filler
+ * @returns string
+ */
+export function pad(
+  input: number | string,
+  size: number,
+  symbol = '0',
+): string {
+  let s = input + '';
+  while (s.length < size) {
+    s = symbol + s;
+  }
+  return s.slice(-size);
+}

package/src/public-api.ts

@@ -0,0 +1,14 @@
+export * from './lib/color';
+export * from './lib/constants';
+export * from './lib/csv';
+export * from './lib/dev';
+export * from './lib/filenaming';
+export * from './lib/geom';
+export * from './lib/helpers';
+export * from './lib/image';
+export * from './lib/interfaces';
+export * from './lib/math';
+export * from './lib/mutex';
+export * from './lib/predicates';
+export * from './lib/rxjs';
+export * from './lib/strings';

package/tsconfig.lib.json

@@ -0,0 +1,13 @@
+/* To learn more about Typescript configuration file: https://www.typescriptlang.org/docs/handbook/tsconfig-json.html. */
+/* To learn more about Angular compiler options: https://angular.dev/reference/configs/angular-compiler-options. */
+{
+  "extends": "../../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../../out-tsc/lib",
+    "declaration": true,
+    "declarationMap": true,
+    "inlineSources": true,
+    "types": []
+  },
+  "exclude": ["**/*.spec.ts"]
+}

package/tsconfig.lib.prod.json

@@ -0,0 +1,11 @@
+/* To learn more about Typescript configuration file: https://www.typescriptlang.org/docs/handbook/tsconfig-json.html. */
+/* To learn more about Angular compiler options: https://angular.dev/reference/configs/angular-compiler-options. */
+{
+  "extends": "./tsconfig.lib.json",
+  "compilerOptions": {
+    "declarationMap": false
+  },
+  "angularCompilerOptions": {
+    "compilationMode": "partial"
+  }
+}