@bitfiber/utils 1.0.2 → 1.0.4

package/dist/types/str/to-hash/to-hash.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Generates a hash value for a given input string for insecure purposes
+ * Hash functions are commonly used to convert input data into a fixed-length string of characters,
+ * providing a unique representation of the input
+ * @param str - The input string to be hashed
+ */
+export declare function toHash(str: string): string;
+//# sourceMappingURL=to-hash.d.ts.map

package/dist/types/str/to-hash/to-hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"to-hash.d.ts","sourceRoot":"","sources":["../../../../src/str/to-hash/to-hash.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAc1C"}

package/dist/types/str/with-capital/with-capital.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Takes a string as input and returns a new string with the initial letter in uppercase,
+ * while preserving the rest of the string
+ * @param str - The input string whose first letter needs to be capitalized
+ */
+export declare function withCapital(str: string): string;
+//# sourceMappingURL=with-capital.d.ts.map

package/dist/types/str/with-capital/with-capital.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-capital.d.ts","sourceRoot":"","sources":["../../../../src/str/with-capital/with-capital.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE/C"}

package/package.json

@@ -1,73 +1,92 @@
-{
-  "name": "@bitfiber/utils",
-  "description": "Collection of versatile utility functions for Javascript",
-  "version": "1.0.2",
-  "type": "module",
-  "module": "./src/index.js",
-  "main": "./index.js",
-  "types": "./index.d.ts",
-  "typesVersions": {
-    ">=4.8.2": {
-      "*": [
-        "*.d.ts"
-      ]
-    }
-  },
-  "sideEffects": false,
-  "exports": {
-    ".": {
-      "types": "./index.d.ts",
-      "default": "./index.js"
-    },
-    "./arr": {
-      "types": "./arr/index.d.ts",
-      "default": "./arr/index.js"
-    },
-    "./obj": {
-      "types": "./obj/index.d.ts",
-      "default": "./obj/index.js"
-    },
-    "./str": {
-      "types": "./str/index.d.ts",
-      "default": "./str/index.js"
-    },
-    "./num": {
-      "types": "./num/index.d.ts",
-      "default": "./num/index.js"
-    },
-    "./dom": {
-      "types": "./dom/index.d.ts",
-      "default": "./dom/index.js"
-    },
-    "./env": {
-      "types": "./env/index.d.ts",
-      "default": "./env/index.js"
-    },
-    "./package.json": "./package.json"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/bitfiber/utils.git",
-    "directory": "utils"
-  },
-  "keywords": [
-    "Javascript",
-    "Typescript",
-    "Utils",
-    "Utilities",
-    "Helpers"
-  ],
-  "author": {
-    "name": "Zmanovskyi Oleksandr",
-    "email": "bitfiber.web@gmail.com"
-  },
-  "license": "Apache 2.0",
-  "bugs": {
-    "url": "https://github.com/bitfiber/utils/issues"
-  },
-  "homepage": "https://github.com/bitfiber/utils",
-  "dependencies": {
-    "tslib": "^2.3.0"
-  },
-  "peerDependencies": {}
-}
+{
+  "name": "@bitfiber/utils",
+  "description": "Collection of versatile utility functions for Javascript",
+  "version": "1.0.4",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "es2015": "./dist/esm/index.js",
+  "types": "index.d.ts",
+  "typesVersions": {
+    ">=4.8.2": {
+      "*": ["dist/types/*"]
+    }
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "node": "./dist/cjs/index.js",
+      "require": "./dist/cjs/index.js",
+      "es2015": "./dist/esm/index.js",
+      "default": "./dist/esm/index.js"
+    },
+    "./arr": {
+      "types": "./dist/types/arr/index.d.ts",
+      "node": "./dist/cjs/arr/index.js",
+      "require": "./dist/cjs/arr/index.js",
+      "es2015": "./dist/esm/arr/index.js",
+      "default": "./dist/esm/arr/index.js"
+    },
+    "./obj": {
+      "types": "./dist/types/obj/index.d.ts",
+      "node": "./dist/cjs/obj/index.js",
+      "require": "./dist/cjs/obj/index.js",
+      "es2015": "./dist/esm/obj/index.js",
+      "default": "./dist/esm/obj/index.js"
+    },
+    "./str": {
+      "types": "./dist/types/str/index.d.ts",
+      "node": "./dist/cjs/str/index.js",
+      "require": "./dist/cjs/str/index.js",
+      "es2015": "./dist/esm/str/index.js",
+      "default": "./dist/esm/str/index.js"
+    },
+    "./num": {
+      "types": "./dist/types/num/index.d.ts",
+      "node": "./dist/cjs/num/index.js",
+      "require": "./dist/cjs/num/index.js",
+      "es2015": "./dist/esm/num/index.js",
+      "default": "./dist/esm/num/index.js"
+    },
+    "./dom": {
+      "types": "./dist/types/dom/index.d.ts",
+      "node": "./dist/cjs/dom/index.js",
+      "require": "./dist/cjs/dom/index.js",
+      "es2015": "./dist/esm/dom/index.js",
+      "default": "./dist/esm/dom/index.js"
+    },
+    "./env": {
+      "types": "./dist/types/env/index.d.ts",
+      "node": "./dist/cjs/env/index.js",
+      "require": "./dist/cjs/env/index.js",
+      "es2015": "./dist/esm/env/index.js",
+      "default": "./dist/esm/env/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bitfiber/utils.git",
+    "directory": "utils"
+  },
+  "keywords": [
+    "Javascript",
+    "Typescript",
+    "Utils",
+    "Utilities",
+    "Helpers"
+  ],
+  "author": {
+    "name": "Oleksandr Zmanovskyi",
+    "email": "bitfiber.web@gmail.com"
+  },
+  "license": "Apache 2.0",
+  "bugs": {
+    "url": "https://github.com/bitfiber/utils/issues"
+  },
+  "homepage": "https://github.com/bitfiber/utils",
+  "dependencies": {
+    "tslib": "^2.3.0"
+  },
+  "peerDependencies": {}
+}

package/src/arr/at/at.ts

@@ -0,0 +1,10 @@
+/**
+ * Returns the array item at index, or undefined if there is no index.
+ * For negative indexes, returns items from the end
+ * @param arr - any array
+ * @param index - item index
+ */
+export function at<T>(arr: T[], index: number): T | undefined {
+  // todo: change on 'Array.at' with ES2022
+  return index < 0 ? arr[arr.length + index] : arr[index];
+}

package/src/arr/cnd/cnd.ts

@@ -0,0 +1,188 @@
+import {BfError, isFunction, isObject, isRegExp, isString, same, equals, isArray} from '../../common';
+import {hasOwn} from '../../obj';
+
+/**
+ * Represents a condition that is true if the function returns true
+ * Used for the cnd function
+ */
+export type MatchConditionFn = (value: any) => boolean;
+
+/**
+ * Represents a condition that is true if the value is the same as the condition
+ * Used for the cnd function
+ */
+export type MatchConditionIs = {is: any};
+
+/**
+ * Represents a condition that is true if the value is the same for at least one part of the condition
+ * Used for the cnd function
+ */
+export type MatchConditionOr = {or: any[]};
+
+/**
+ * Represents a condition that is true if the value is not the same for each part of the condition
+ * Used for the cnd function
+ */
+export type MatchConditionNot = {not: any[]};
+
+/**
+ * Represents a condition that is true if the value is equal to the condition
+ * Used for the cnd function
+ */
+export type MatchConditionEqual = {equal: any};
+
+/**
+ * Represents a condition that is true if the value is equal to at least one part of the condition
+ * Used for the cnd function
+ */
+export type MatchConditionOrEqual = {orEqual: any[]};
+
+/**
+ * Represents a condition that is true if the value is not equal to each part of the condition
+ * Used for the cnd function
+ */
+export type MatchConditionNotEqual = {notEqual: any[]};
+
+/**
+ * Represents a group of all object condition types
+ * Used for the cnd function
+ */
+export type MatchConditionObj = MatchConditionIs | MatchConditionOr | MatchConditionNot | MatchConditionEqual
+  | MatchConditionOrEqual | MatchConditionNotEqual;
+
+/**
+ * Represents a condition that is true if the value of each field matches each field condition
+ * Used for the cnd function
+ */
+export type MatchConditionsByFields = {
+  [field: string]: MatchConditionObj | RegExp;
+};
+
+/**
+ * Represents all condition types for the cnd function
+ */
+export type MatchConditions = MatchConditionFn | MatchConditionObj | MatchConditionsByFields;
+
+/**
+ * Returns a function that checks if a value matches the conditions
+ * @example
+ * import {cnd} from '@bitfiber/utils/arr';
+ *
+ * const obj1 = {name: 'Alex'};
+ * const obj2 = {name: 'Mary'};
+ * const obj3 = {name: 'Jack'};
+ * const arr = [obj1, obj2, obj3];
+ * const strArr = ['Alex', 'Mary', 'Jack'];
+ *
+ * // Handler for comparison
+ * arr.filter(cnd(obj => obj.name === 'Alex')); // [{name: 'Alex'}]
+ *
+ * // Strict value comparison
+ * arr.filter(cnd({is: obj1})); // [{name: 'Alex'}]
+ * arr.filter(cnd({is: {name: 'Alex'}})); // []
+ * arr.filter(cnd({or: [obj1, obj2]})); // [{name: 'Alex'}, {name: 'Mary'}]
+ * arr.filter(cnd({or: [{name: 'Alex'}, obj2]})); // [{name: 'Mary'}]
+ * arr.filter(cnd({not: [obj1, obj2]})); // [{name: 'Jack'}]
+ * arr.filter(cnd({not: [{name: 'Alex'}, obj2]})); // [{name: 'Alex'}, {name: 'Jack'}]
+ *
+ * // Value equivalence comparison
+ * arr.filter(cnd({equal: obj1})); // [{name: 'Alex'}]
+ * arr.filter(cnd({equal: {name: 'Alex'}})); // [{name: 'Alex'}]
+ * arr.filter(cnd({orEqual: [obj1, obj2]})); // [{name: 'Alex'}, {name: 'Mary'}]
+ * arr.filter(cnd({orEqual: [{name: 'Alex'}, obj2]})); // [{name: 'Alex'}, {name: 'Mary'}]
+ * arr.filter(cnd({notEqual: [obj1, obj2]})); // [{name: 'Jack'}]
+ * arr.filter(cnd({notEqual: [{name: 'Alex'}, obj2]})); // [{name: 'Jack'}]
+ *
+ * // String value RegExp comparison
+ * strArr.filter(cnd({equal: /^Alex$/})); // ['Alex']
+ * strArr.filter(cnd({orEqual: [/^Alex$/, /^Mary$/]})); // ['Alex', 'Mary']
+ * strArr.filter(cnd({notEqual: [/^Alex$/, /^Mary$/]})); // ['Jack']
+ *
+ * // Strict comparison of field value in objects
+ * arr.filter(cnd({name: {is: 'Alex'}})); // [{name: 'Alex'}]
+ * arr.filter(cnd({name: {or: ['Alex', 'Mary']}})); // [{name: 'Alex'}, {name: 'Mary'}]
+ * arr.filter(cnd({name: {not: ['Alex', 'Mary']}})); // [{name: 'Jack'}]
+ *
+ * // Comparison of field value equivalence in objects
+ * arr.filter(cnd({name: {equal: 'Alex'}})); // [{name: 'Alex'}]
+ * arr.filter(cnd({name: {orEqual: ['Alex', 'Mary']}})); // [{name: 'Alex'}, {name: 'Mary'}]
+ * arr.filter(cnd({name: {notEqual: ['Alex', 'Mary']}})); // [{name: 'Jack'}]
+ *
+ * // Comparing string fields in objects using RegExp
+ * arr.filter(cnd({name: /^Alex$/})); // [{name: 'Alex'}]
+ * arr.filter(cnd({name: {equal: /^Alex$/}})); // [{name: 'Alex'}]
+ * arr.filter(cnd({name: {orEqual: [/^Alex$/, /^Mary$/]}})); // [{name: 'Alex'}, {name: 'Mary'}]
+ * arr.filter(cnd({name: {notEqual: [/^Alex$/, /^Mary$/]}})); // [{name: 'Jack'}]
+ *
+ * @param conditions
+ */
+export function cnd(conditions: MatchConditions): MatchConditionFn {
+  if (isFunction(conditions)) {
+    return conditions;
+  } else if ('is' in conditions) {
+    return value => same(conditions.is, value);
+  } else if ('or' in conditions) {
+    return value => (isArray(conditions.or) ? conditions.or.some(item => same(item, value)) : cndErr());
+  } else if ('not' in conditions) {
+    return value => (isArray(conditions.not) ? !conditions.not.some(item => same(item, value)) : cndErr());
+  } else if ('equal' in conditions) {
+    return value => fit(conditions.equal, value);
+  } else if ('orEqual' in conditions) {
+    return value => (isArray(conditions.orEqual) ? conditions.orEqual.some(item => fit(item, value)) : cndErr());
+  } else if ('notEqual' in conditions) {
+    return value => (isArray(conditions.notEqual) ? !conditions.notEqual.some(item => fit(item, value)) : cndErr());
+  } else {
+    return obj => {
+      if (isObject(obj)) {
+        for (const key in conditions) {
+          if (hasOwn(conditions, key)) {
+            const value = obj[key];
+            const condition = conditions[key];
+
+            if (isRegExp(condition)) {
+              if (!fit(condition, value)) {
+                return false;
+              }
+            } else if ('is' in condition) {
+              if (!same(condition.is, value)) {
+                return false;
+              }
+            } else if ('or' in condition) {
+              if (!condition.or.some(item => same(item, value))) {
+                return false;
+              }
+            } else if ('not' in condition) {
+              if (condition.not.some(item => same(item, value))) {
+                return false;
+              }
+            } else if ('equal' in condition) {
+              if (!fit(condition.equal, value)) {
+                return false;
+              }
+            } else if ('orEqual' in condition) {
+              if (!condition.orEqual.some(item => fit(item, value))) {
+                return false;
+              }
+            } else if ('notEqual' in condition) {
+              if (condition.notEqual.some(item => fit(item, value))) {
+                return false;
+              }
+            }
+          }
+        }
+
+        return true;
+      } else {
+        return false;
+      }
+    };
+  }
+}
+
+function fit(condition: any, value: any): boolean {
+  return isRegExp(condition) ? isString(value) && condition.test(value) : equals(condition, value);
+}
+
+function cndErr(): never {
+  throw new BfError('"or", "not", "orEqual" and "notEqual" must be an array', {code: 'bf_utils_arr_cnd_1'});
+}

package/src/arr/diff-arr/diff-arr.ts

@@ -0,0 +1,66 @@
+import {NumStr} from '../../common';
+
+/**
+ * Represents response of the diffArr function
+ */
+export interface ArrDiff<T> {
+
+  /**
+   * Contains items that are only in array 1
+   */
+  only1: T[];
+
+  /**
+   * Contains items that are only in array 2
+   */
+  only2: T[];
+
+  /**
+   * Contains items that are in both arrays
+   */
+  equal: T[];
+
+  /**
+   * True if only1 and only2 are empty, otherwise false
+   */
+  isEqual: boolean;
+}
+
+/**
+ * Returns the difference between two arrays
+ * Strict comparison of array items is applied
+ * The order doesn't matter
+ * @param arr1 - array 1
+ * @param arr2 - array 2
+ */
+export function diffArr<T extends NumStr>(arr1: T[], arr2: T[]): ArrDiff<T> {
+  let isEqual = true;
+  const only1: T[] = [];
+  const only2: T[] = [];
+  const equal: T[] = [];
+  const map1 = new Map(arr1.map(value => [value, true]));
+  const map2 = new Map(arr2.map(value => [value, true]));
+
+  for (const value of map1.keys()) {
+    if (!map2.has(value)) {
+      isEqual = false;
+      only1.push(value);
+    } else {
+      equal.push(value);
+    }
+  }
+
+  for (const value of map2.keys()) {
+    if (!map1.has(value)) {
+      isEqual = false;
+      only2.push(value);
+    }
+  }
+
+  return {
+    only1,
+    only2,
+    equal,
+    isEqual,
+  };
+}

package/src/arr/fill/fill.ts

@@ -0,0 +1,10 @@
+/**
+ * Fills a new array with items that will be returned by the handler,
+ * which will be called a certain number of times
+ * @param quantity - number of array items
+ * @param handler - a function that should return a new array item
+ * @param offset - offset for the index, which is passed to the handler
+ */
+export function fill<T>(quantity: number, handler: (offsetIndex: number, index: number) => T, offset = 1): T[] {
+  return Array(quantity).fill(null).map((item, index) => handler(index + offset, index));
+}

package/src/arr/for-each-arr/for-each-arr.ts

@@ -0,0 +1,25 @@
+import {Arr, INTERRUPT, ValueUnion} from '../../common';
+
+/**
+ * Iterates through all the items of an array and calls a handler for each item
+ * If the handler returns INTERRUPT, the loop will be interrupted
+ * @param arr - an array or any typed array
+ * @param handler - function called for each item
+ * @param reverse - iterates in reverse order if true
+ */
+export function forEachArr<T extends Arr, V extends ValueUnion<T>>(arr: T,
+  handler: (value: V, index: number, arr: T) => any, reverse?: boolean): void {
+  if (reverse) {
+    for (let i = arr.length - 1; i >= 0; i--) {
+      if (handler(arr[i], i, arr) === INTERRUPT) {
+        return;
+      }
+    }
+  } else {
+    for (let i = 0; i < arr.length; i++) {
+      if (handler(arr[i], i, arr) === INTERRUPT) {
+        return;
+      }
+    }
+  }
+}

package/src/arr/index-by/index-by.ts

@@ -0,0 +1,19 @@
+import {isFunction, Obj, Index} from '../../common';
+
+/**
+ * Returns an object indexed by the values from a specific field of each item
+ * or from a function that is executed on each item
+ * @param arr - array of objects
+ * @param fieldOrFn - the name of the field from which the index value should be taken,
+ * or the function that should return the index value
+ */
+export function indexBy<T extends Obj>(arr: T[], fieldOrFn: string | ((item: T) => string)): Index<T> {
+  const result: Index<T> = {};
+  arr.forEach(item => {
+    const key = isFunction(fieldOrFn) ? fieldOrFn(item) : item[fieldOrFn];
+    if (key) {
+      result[key] = item;
+    }
+  });
+  return result;
+}

package/src/arr/index.ts

@@ -0,0 +1,11 @@
+export {at} from './at/at';
+export {within} from './within/within';
+export {pluck} from './pluck/pluck';
+export {indexBy} from './index-by/index-by';
+export {fill} from './fill/fill';
+export {diffArr, ArrDiff} from './diff-arr/diff-arr';
+export {forEachArr} from './for-each-arr/for-each-arr';
+export {
+  cnd, MatchConditionFn, MatchConditionIs, MatchConditionOr, MatchConditionNot, MatchConditionEqual,
+  MatchConditionOrEqual, MatchConditionNotEqual, MatchConditionObj, MatchConditionsByFields, MatchConditions,
+} from './cnd/cnd';

package/src/arr/pluck/pluck.ts

@@ -0,0 +1,14 @@
+import {Obj} from '../../common';
+
+/**
+ * Returns an array with values, each of which corresponds to the value of a certain array item field
+ * @param arr - array of objects
+ * @param fieldName - name of the array item field from which the value is to be taken
+ */
+export function pluck<T extends Obj, F extends keyof T>(arr: T[], fieldName: F): (T[F])[] {
+  const result: (T[F])[] = [];
+  arr.forEach(item => {
+    result.push(item[fieldName]);
+  });
+  return result;
+}

package/src/arr/within/within.ts

@@ -0,0 +1,14 @@
+import {at} from '../';
+
+/**
+ * Returns an array item by index.
+ * If the index is greater than the array length,
+ * then the array item will be obtained like remainder of division the index by the array length.
+ * For negative indexes, returns items from the end
+ * @param arr - any array
+ * @param index - an array item index
+ */
+export function within<T>(arr: T[], index: number): T | undefined {
+  const max = arr.length;
+  return at(arr, ((index + 1) % max || max) - 1);
+}

package/src/common/copy/copy.ts

@@ -0,0 +1,89 @@
+import {
+  isNumber, isBigInt, isBoolean, isString, isDate, isRegExp, isFunction, isMap, isSet, isObject, isArray, isTypedArray,
+  isBlob, isArrayBuffer, isWindow, isDocument, isFile, isFormData, isPromise, isObservable,
+} from '../';
+import {forEachObj} from '../../obj';
+
+/**
+ * Creates a deep copy of a value of any type
+ * Objects, arrays, sets, maps etc. will be ignored if they have been visited to prevent looping
+ * @param value - anything
+ */
+export function copy<T>(value: T): T {
+  return _copy(value, new Map());
+}
+
+function _copy(value: any, visited: Map<any, any>): any {
+  if (!value || isString(value) || isNumber(value) || isBigInt(value) || isBoolean(value) || isFunction(value)) {
+    return value;
+  } else if (isDate(value)) {
+    return new Date(value.getTime());
+  } else if (isArray(value)) {
+    if (visited.has(value)) {
+      return visited.get(value);
+    }
+
+    const arr: any[] = [];
+    visited.set(value, arr);
+    value.forEach(item => arr.push(_copy(item, visited)));
+
+    return arr;
+  } else if (isSet(value)) {
+    if (visited.has(value)) {
+      return visited.get(value);
+    }
+
+    const newSet = new Set();
+    visited.set(value, newSet);
+    value.forEach(item => newSet.add(_copy(item, visited)));
+
+    return newSet;
+  } else if (isMap(value)) {
+    if (visited.has(value)) {
+      return visited.get(value);
+    }
+
+    const newMap = new Map();
+    visited.set(value, newMap);
+
+    value.forEach((item, key) => newMap.set(_copy(key, visited), _copy(item, visited)));
+
+    return newMap;
+  } else if (isRegExp(value)) {
+    // @ts-ignore
+    const reg = new RegExp(value.source, value.toString().match(/[^/]*$/)[0]);
+    reg.lastIndex = value.lastIndex;
+    return reg;
+  } else if (isBlob(value)) {
+    return new Blob([value], {type: value.type});
+  } else if (isArrayBuffer(value)) {
+    return value.slice(0);
+  } else if (isTypedArray(value)) {
+    // @ts-ignore
+    return new value.constructor(value.buffer.slice(0), value.byteOffset, value.length);
+  } else if (isWindow(value) || isDocument(value) || isFile(value) || isFormData(value) || isPromise(value)
+    || isObservable(value)) {
+    return value;
+  } else if (isObject(value)) {
+    if (visited.has(value)) {
+      return visited.get(value);
+    }
+
+    const obj = Object.create(Object.getPrototypeOf(value));
+    visited.set(value, obj);
+
+    forEachObj(value, (val, key) => {
+      const descriptor = Object.getOwnPropertyDescriptor(value, key);
+
+      if (descriptor?.get || descriptor?.set) {
+        Object.defineProperty(obj, key, descriptor);
+      } else {
+        obj[key] = _copy(val, visited);
+      }
+    });
+
+    return obj;
+  } else {
+    return value;
+  }
+}