@ntnyq/utils 0.10.0 → 0.11.0

package/dist/index.d.ts

@@ -29,9 +29,6 @@ declare function once<T extends unknown[]>(func: (...args: T) => void): (this: u
 //#endregion
 //#region src/is/dom.d.ts
 /**
-* @file is/dom.ts
-*/
-/**
 * Check if given value is an HTMLElement
 * @param value - The value to check
 * @returns True if the value is an HTMLElement, false otherwise
@@ -206,16 +203,13 @@ declare function isElementVisibleInViewport(element: HTMLElement, targetWindow?:
 //#endregion
 //#region src/env/isBrowser.d.ts
 /**
-* @file env.ts
-*/
-/**
 * Checks if the code is running in a browser
 *
-* @returns boolean - true if the code is running in a browser
+* @returns true if the code is running in a browser
 */
 declare function isBrowser(): boolean;
 //#endregion
-//#region src/file/removeExtension.d.ts
+//#region src/file/extension.d.ts
 /**
 * Removes the file extension from a filename.
 *
@@ -223,6 +217,12 @@ declare function isBrowser(): boolean;
 * @returns The filename without the extension.
 */
 declare function removeFileExtension(filename: string): string;
+/**
+* Gets the file extension from a filename.
+* @param filePath - The filePath to get the extension from.
+* @returns The file extension, or undefined if there is none.
+*/
+declare function getFileExtension(filePath?: string): string | undefined;
 //#endregion
 //#region src/html/escape.d.ts
 /**
@@ -450,6 +450,15 @@ declare function last<T>(array: readonly T[]): T | undefined;
 */
 declare function chunk<T>(array: T[], size: number): T[][];
 //#endregion
+//#region src/array/remove.d.ts
+/**
+* Remove given item from an array
+* @param array - given array
+* @param value - item to be removed
+* @returns true if item was removed, otherwise false
+*/
+declare function remove<T>(array: T[], value: T): boolean;
+//#endregion
 //#region src/array/unique.d.ts
 /**
 * Returns a new array with unique values.
@@ -465,6 +474,15 @@ declare function unique<T>(array: T[]): T[];
 */
 declare function uniqueBy<T>(array: T[], equalFn: (a: T, b: T) => boolean): T[];
 //#endregion
+//#region src/array/shuffle.d.ts
+/**
+* Fisher–Yates shuffle
+*
+* @param array - array to shuffle
+* @returns shuffled array
+*/
+declare function shuffle<T>(array: T[]): T[];
+//#endregion
 //#region src/array/toArray.d.ts
 /**
 * Converts a value to an array.
@@ -744,6 +762,17 @@ declare function cleanObject<T extends object>(obj: T, options?: CleanObjectOpti
 */
 declare function hasOwn<T>(object: T, key: PropertyKey): boolean;
 //#endregion
+//#region src/object/isKeyOf.d.ts
+/**
+* Type guard for any key, `k`
+* marks `k` as a key of `T` if `k` is a key of `T`
+*
+* @param obj - object to query for key
+* @param k - key to check for
+* @returns true if `k` is a key of `T`
+*/
+declare function isKeyOf<T extends object>(obj: T, k: keyof T): k is keyof T;
+//#endregion
 //#region src/object/sortObject.d.ts
 interface SortObjectOptions {
   /**
@@ -761,6 +790,15 @@ interface SortObjectOptions {
 */
 declare function sortObject<T extends Record<string, any>>(obj: T, options?: SortObjectOptions): T;
 //#endregion
+//#region src/object/isPlainObject.d.ts
+/**
+* Check if a value is a plain object (not an array, Date, RegExp, Map, Set, etc.)
+*
+* @param value - Checked value
+* @copyright {@link https://github.com/sindresorhus/is/blob/main/source/index.ts}
+*/
+declare function isPlainObject<Value = unknown>(value: unknown): value is Record<PropertyKey, Value>;
+//#endregion
 //#region src/string/pad.d.ts
 interface CreatePadStringOptions {
   length: number;
@@ -790,6 +828,12 @@ declare function join(array: JoinableValue[], options?: JoinOptions): string;
 */
 declare function slash(input: string): string;
 //#endregion
+//#region src/string/escape.d.ts
+/**
+* @copyright {@link https://github.com/sindresorhus/escape-string-regexp}
+*/
+declare function escapeStringRegexp(value: string): string;
+//#endregion
 //#region src/string/random.d.ts
 /**
 * randome a string useing given chars
@@ -903,4 +947,4 @@ declare const RE_LINE_COMMENT: RegExp;
 */
 declare const RE_BLOCK_COMMENT: RegExp;
 //#endregion
-export { AnyFn, Arrayable, Awaitable, Callable, CleanObjectOptions, Color, CreatePadStringOptions, DeepRequired, ElementOf, GetStringSimilarityOptions, InteropModuleDefault, JsonArray, JsonObject, JsonPrimitive, JsonValue, LiteralUnion, MayBe, Merge, NOOP, NonEmptyObject, NonEmptyString, Nullable, OpenExternalURLOptions, Overwrite, Prettify, PrettifyV2, Primitive, RE_BLOCK_COMMENT, RE_COMMENTS, RE_LINE_COMMENT, RamdomNumberOptions, ResolvedOptions, SPECIAL_CHAR, STORAGE_UNITS, SortObjectOptions, StorageUnit, TIME_UNITS, ThrottleDebounceOptions, TimeUnit, ToIntegerOptions, UrlString, ValueOf, Whitespace, at, cAF, chunk, clamp, cleanObject, convertFromBytes, convertFromMilliseconds, convertStorageUnit, convertTimeUnit, convertToBytes, convertToMilliseconds, createPadString, debounce, enhance, ensurePrefix, ensureSuffix, escapeHTML, flattenArrayable, getObjectType, getRoot, getStringLength, getStringSimilarity, hasOwn, interopDefault, intersect, isArray, isArrayEqual, isBigInt, isBlob, isBoolean, isBrowser, isDeepEqual, isElementVisibleInViewport, isEmptyArray, isEmptyMap, isEmptyObject, isEmptySet, isEmptyString, isEmptyStringOrWhitespace, isError, isFile, isFormData, isFunction, isHTMLElement, isInteger, isIterable, isMap, isNaN, isNativePromise, isNil, isNonEmptyArray, isNonEmptyString, isNull, isNullOrUndefined, isNumber, isNumbericString, isObject, isPromise, isRegExp, isSet, isString, isTruthy, isUndefined, isUrlString, isWhitespaceString, isZero, join, last, mergeArrayable, noop, omit, once, openExternalURL, pick, rAF, randomHexColor, randomNumber, randomRGBAColor, randomRGBColor, randomString, removeFileExtension, resolveSubOptions, scrollElementIntoView, slash, slugify, sortObject, throttle, toArray, toInteger, unescapeHTML, unindent, unique, uniqueBy, waitFor, warnOnce };
+export { AnyFn, Arrayable, Awaitable, Callable, CleanObjectOptions, Color, CreatePadStringOptions, DeepRequired, ElementOf, GetStringSimilarityOptions, InteropModuleDefault, JsonArray, JsonObject, JsonPrimitive, JsonValue, LiteralUnion, MayBe, Merge, NOOP, NonEmptyObject, NonEmptyString, Nullable, OpenExternalURLOptions, Overwrite, Prettify, PrettifyV2, Primitive, RE_BLOCK_COMMENT, RE_COMMENTS, RE_LINE_COMMENT, RamdomNumberOptions, ResolvedOptions, SPECIAL_CHAR, STORAGE_UNITS, SortObjectOptions, StorageUnit, TIME_UNITS, ThrottleDebounceOptions, TimeUnit, ToIntegerOptions, UrlString, ValueOf, Whitespace, at, cAF, chunk, clamp, cleanObject, convertFromBytes, convertFromMilliseconds, convertStorageUnit, convertTimeUnit, convertToBytes, convertToMilliseconds, createPadString, debounce, enhance, ensurePrefix, ensureSuffix, escapeHTML, escapeStringRegexp, flattenArrayable, getFileExtension, getObjectType, getRoot, getStringLength, getStringSimilarity, hasOwn, interopDefault, intersect, isArray, isArrayEqual, isBigInt, isBlob, isBoolean, isBrowser, isDeepEqual, isElementVisibleInViewport, isEmptyArray, isEmptyMap, isEmptyObject, isEmptySet, isEmptyString, isEmptyStringOrWhitespace, isError, isFile, isFormData, isFunction, isHTMLElement, isInteger, isIterable, isKeyOf, isMap, isNaN, isNativePromise, isNil, isNonEmptyArray, isNonEmptyString, isNull, isNullOrUndefined, isNumber, isNumbericString, isObject, isPlainObject, isPromise, isRegExp, isSet, isString, isTruthy, isUndefined, isUrlString, isWhitespaceString, isZero, join, last, mergeArrayable, noop, omit, once, openExternalURL, pick, rAF, randomHexColor, randomNumber, randomRGBAColor, randomRGBColor, randomString, remove, removeFileExtension, resolveSubOptions, scrollElementIntoView, shuffle, slash, slugify, sortObject, throttle, toArray, toInteger, unescapeHTML, unindent, unique, uniqueBy, waitFor, warnOnce };

package/dist/index.js

@@ -36,6 +36,17 @@ function once(func) {
 	};
 }
 
+//#endregion
+//#region src/env/isBrowser.ts
+/**
+* Checks if the code is running in a browser
+*
+* @returns true if the code is running in a browser
+*/
+function isBrowser() {
+	return typeof document !== "undefined" && typeof window !== "undefined" && typeof navigator !== "undefined" && window === self;
+}
+
 //#endregion
 //#region src/is/dom.ts
 /**
@@ -47,6 +58,7 @@ function once(func) {
 * @returns True if the value is an HTMLElement, false otherwise
 */
 function isHTMLElement(value) {
+	if (!isBrowser()) return false;
 	return typeof value === "object" && value !== null && "nodeType" in value && value.nodeType === Node.ELEMENT_NODE && value instanceof HTMLElement;
 }
 
@@ -241,21 +253,7 @@ function isElementVisibleInViewport(element, targetWindow = window) {
 }
 
 //#endregion
-//#region src/env/isBrowser.ts
-/**
-* @file env.ts
-*/
-/**
-* Checks if the code is running in a browser
-*
-* @returns boolean - true if the code is running in a browser
-*/
-function isBrowser() {
-	return typeof document !== "undefined";
-}
-
-//#endregion
-//#region src/file/removeExtension.ts
+//#region src/file/extension.ts
 /**
 * Removes the file extension from a filename.
 *
@@ -265,6 +263,15 @@ function isBrowser() {
 function removeFileExtension(filename) {
 	return filename.replace(/\.[^/.]+$/, "");
 }
+/**
+* Gets the file extension from a filename.
+* @param filePath - The filePath to get the extension from.
+* @returns The file extension, or undefined if there is none.
+*/
+function getFileExtension(filePath) {
+	if (!filePath) return;
+	return filePath.match(/\.([^.]+)$/)?.[1];
+}
 
 //#endregion
 //#region src/html/escape.ts
@@ -600,6 +607,24 @@ function chunk(array, size) {
 	return result;
 }
 
+//#endregion
+//#region src/array/remove.ts
+/**
+* Remove given item from an array
+* @param array - given array
+* @param value - item to be removed
+* @returns true if item was removed, otherwise false
+*/
+function remove(array, value) {
+	if (!array) return false;
+	const index = array.indexOf(value);
+	if (index !== -1) {
+		array.splice(index, 1);
+		return true;
+	}
+	return false;
+}
+
 //#endregion
 //#region src/array/unique.ts
 /**
@@ -623,6 +648,89 @@ function uniqueBy(array, equalFn) {
 	}, []);
 }
 
+//#endregion
+//#region src/number/random.ts
+/**
+* random an integer by given range
+*
+* @param min - min value
+* @param max - max value
+* @returns random integer in range
+*/
+function randomNumber(min, max = 0, options = {}) {
+	if (max === 0) {
+		max = min;
+		min = 0;
+	}
+	if (min > max) [min, max] = [max, min];
+	return Math.trunc(Math.random() * (max - min + (options.includeMax ? 1 : 0)) + min);
+}
+
+//#endregion
+//#region src/number/toInteger.ts
+/**
+* Transforms a value to an integer.
+* @param value - The value to convert to an integer.
+* @param options - Options for the conversion.
+* @returns The converted integer.
+*/
+function toInteger(value, options = {}) {
+	const { defaultValue = 0, allowDecimal = false, allowNaN = false, onError = "useDefault", min, max, outOfRange = "clamp" } = options;
+	let numberValue;
+	let result;
+	if (isNumber(value)) numberValue = value;
+	else if (isString(value)) {
+		const trimmed = value.trim();
+		if (isEmptyString(trimmed)) {
+			if (onError === "throwError") throw new TypeError("Cannot convert empty string to an integer");
+			return onError === "returnOriginal" ? value : defaultValue;
+		}
+		numberValue = Number(trimmed);
+	} else if (isNullOrUndefined(value)) {
+		if (onError === "throwError") throw new TypeError(`Cannot convert ${value} to an integer`);
+		return onError === "useDefault" ? value : defaultValue;
+	} else numberValue = Number(value);
+	if (isNaN(numberValue)) {
+		if (allowNaN) return numberValue;
+		if (onError === "throwError") throw new TypeError(`Cannot convert NaN to an integer`);
+		return onError === "returnOriginal" ? value : defaultValue;
+	}
+	if (allowDecimal) result = numberValue > 0 ? Math.floor(numberValue) : Math.ceil(numberValue);
+	else {
+		if (numberValue % 1 !== 0) {
+			if (onError === "throwError") throw new Error("Decimal values are not allowed");
+			return onError === "returnOriginal" ? value : defaultValue;
+		}
+		result = numberValue;
+	}
+	if (!isUndefined(min) || !isUndefined(max)) {
+		const minVal = min ?? -Infinity;
+		const maxVal = max ?? Infinity;
+		if (result < minVal || result > maxVal) {
+			if (outOfRange === "throwError") throw new RangeError(`Value ${result} is out of range [${minVal}, ${maxVal}]`);
+			if (outOfRange === "useDefault") return defaultValue;
+			if (outOfRange === "clamp") result = Math.max(minVal, Math.min(maxVal, numberValue));
+		}
+	}
+	return result;
+}
+
+//#endregion
+//#region src/array/shuffle.ts
+/**
+* Fisher–Yates shuffle
+*
+* @param array - array to shuffle
+* @returns shuffled array
+*/
+function shuffle(array) {
+	for (let i = array.length - 1; i > 0; i--) {
+		const j = randomNumber(0, i, { includeMax: true });
+		[array[i], array[j]] = [array[j], array[i]];
+	}
+	return array;
+}
+
 //#endregion
 //#region src/array/toArray.ts
 /**
@@ -709,70 +817,12 @@ function slash(input) {
 }
 
 //#endregion
-//#region src/number/random.ts
+//#region src/string/escape.ts
 /**
-* random an integer by given range
-*
-* @param min - min value
-* @param max - max value
-* @returns random integer in range
+* @copyright {@link https://github.com/sindresorhus/escape-string-regexp}
 */
-function randomNumber(min, max = 0, options = {}) {
-	if (max === 0) {
-		max = min;
-		min = 0;
-	}
-	if (min > max) [min, max] = [max, min];
-	return Math.trunc(Math.random() * (max - min + (options.includeMax ? 1 : 0)) + min);
-}
-
-//#endregion
-//#region src/number/toInteger.ts
-/**
-* Transforms a value to an integer.
-* @param value - The value to convert to an integer.
-* @param options - Options for the conversion.
-* @returns The converted integer.
-*/
-function toInteger(value, options = {}) {
-	const { defaultValue = 0, allowDecimal = false, allowNaN = false, onError = "useDefault", min, max, outOfRange = "clamp" } = options;
-	let numberValue;
-	let result;
-	if (isNumber(value)) numberValue = value;
-	else if (isString(value)) {
-		const trimmed = value.trim();
-		if (isEmptyString(trimmed)) {
-			if (onError === "throwError") throw new TypeError("Cannot convert empty string to an integer");
-			return onError === "returnOriginal" ? value : defaultValue;
-		}
-		numberValue = Number(trimmed);
-	} else if (isNullOrUndefined(value)) {
-		if (onError === "throwError") throw new TypeError(`Cannot convert ${value} to an integer`);
-		return onError === "useDefault" ? value : defaultValue;
-	} else numberValue = Number(value);
-	if (isNaN(numberValue)) {
-		if (allowNaN) return numberValue;
-		if (onError === "throwError") throw new TypeError(`Cannot convert NaN to an integer`);
-		return onError === "returnOriginal" ? value : defaultValue;
-	}
-	if (allowDecimal) result = numberValue > 0 ? Math.floor(numberValue) : Math.ceil(numberValue);
-	else {
-		if (numberValue % 1 !== 0) {
-			if (onError === "throwError") throw new Error("Decimal values are not allowed");
-			return onError === "returnOriginal" ? value : defaultValue;
-		}
-		result = numberValue;
-	}
-	if (!isUndefined(min) || !isUndefined(max)) {
-		const minVal = min ?? -Infinity;
-		const maxVal = max ?? Infinity;
-		if (result < minVal || result > maxVal) {
-			if (outOfRange === "throwError") throw new RangeError(`Value ${result} is out of range [${minVal}, ${maxVal}]`);
-			if (outOfRange === "useDefault") return defaultValue;
-			if (outOfRange === "clamp") result = Math.max(minVal, Math.min(maxVal, numberValue));
-		}
-	}
-	return result;
+function escapeStringRegexp(value) {
+	return value.replace(/[|\\{}()[\]^$+*?.]/g, "\\$&").replace(/-/g, "\\x2d");
 }
 
 //#endregion
@@ -1123,7 +1173,7 @@ function cleanObject(obj, options = {}) {
 		if (cleanUndefined && isUndefined(v)) delete obj[key];
 		if (cleanNull && isNull(v)) delete obj[key];
 		if (cleanZero && isZero(v)) delete obj[key];
-		if (cleanNaN && isZero(v)) delete obj[key];
+		if (cleanNaN && isNaN(v)) delete obj[key];
 		if (cleanEmptyString && isEmptyString(v)) delete obj[key];
 		if (cleanEmptyArray && isEmptyArray(v)) delete obj[key];
 		if (cleanEmptyObject && isEmptyObject(v)) delete obj[key];
@@ -1132,6 +1182,20 @@ function cleanObject(obj, options = {}) {
 	return obj;
 }
 
+//#endregion
+//#region src/object/isKeyOf.ts
+/**
+* Type guard for any key, `k`
+* marks `k` as a key of `T` if `k` is a key of `T`
+*
+* @param obj - object to query for key
+* @param k - key to check for
+* @returns true if `k` is a key of `T`
+*/
+function isKeyOf(obj, k) {
+	return k in obj;
+}
+
 //#endregion
 //#region src/object/isPlainObject.ts
 /**
@@ -1203,4 +1267,4 @@ const RE_LINE_COMMENT = /\/\/.*/;
 const RE_BLOCK_COMMENT = /\/\*[\s\S]*?\*\//g;
 
 //#endregion
-export { Color, NOOP, RE_BLOCK_COMMENT, RE_COMMENTS, RE_LINE_COMMENT, SPECIAL_CHAR, STORAGE_UNITS, TIME_UNITS, at, cAF, chunk, clamp, cleanObject, convertFromBytes, convertFromMilliseconds, convertStorageUnit, convertTimeUnit, convertToBytes, convertToMilliseconds, createPadString, debounce, enhance, ensurePrefix, ensureSuffix, escapeHTML, flattenArrayable, getObjectType, getRoot, getStringLength, getStringSimilarity, hasOwn, interopDefault, intersect, isArray, isArrayEqual, isBigInt, isBlob, isBoolean, isBrowser, isDeepEqual, isElementVisibleInViewport, isEmptyArray, isEmptyMap, isEmptyObject, isEmptySet, isEmptyString, isEmptyStringOrWhitespace, isError, isFile, isFormData, isFunction, isHTMLElement, isInteger, isIterable, isMap, isNaN, isNativePromise, isNil, isNonEmptyArray, isNonEmptyString, isNull, isNullOrUndefined, isNumber, isNumbericString, isObject, isPromise, isRegExp, isSet, isString, isTruthy, isUndefined, isUrlString, isWhitespaceString, isZero, join, last, mergeArrayable, noop, omit, once, openExternalURL, pick, rAF, randomHexColor, randomNumber, randomRGBAColor, randomRGBColor, randomString, removeFileExtension, resolveSubOptions, scrollElementIntoView, slash, slugify, sortObject, throttle, toArray, toInteger, unescapeHTML, unindent, unique, uniqueBy, waitFor, warnOnce };
+export { Color, NOOP, RE_BLOCK_COMMENT, RE_COMMENTS, RE_LINE_COMMENT, SPECIAL_CHAR, STORAGE_UNITS, TIME_UNITS, at, cAF, chunk, clamp, cleanObject, convertFromBytes, convertFromMilliseconds, convertStorageUnit, convertTimeUnit, convertToBytes, convertToMilliseconds, createPadString, debounce, enhance, ensurePrefix, ensureSuffix, escapeHTML, escapeStringRegexp, flattenArrayable, getFileExtension, getObjectType, getRoot, getStringLength, getStringSimilarity, hasOwn, interopDefault, intersect, isArray, isArrayEqual, isBigInt, isBlob, isBoolean, isBrowser, isDeepEqual, isElementVisibleInViewport, isEmptyArray, isEmptyMap, isEmptyObject, isEmptySet, isEmptyString, isEmptyStringOrWhitespace, isError, isFile, isFormData, isFunction, isHTMLElement, isInteger, isIterable, isKeyOf, isMap, isNaN, isNativePromise, isNil, isNonEmptyArray, isNonEmptyString, isNull, isNullOrUndefined, isNumber, isNumbericString, isObject, isPlainObject, isPromise, isRegExp, isSet, isString, isTruthy, isUndefined, isUrlString, isWhitespaceString, isZero, join, last, mergeArrayable, noop, omit, once, openExternalURL, pick, rAF, randomHexColor, randomNumber, randomRGBAColor, randomRGBColor, randomString, remove, removeFileExtension, resolveSubOptions, scrollElementIntoView, shuffle, slash, slugify, sortObject, throttle, toArray, toInteger, unescapeHTML, unindent, unique, uniqueBy, waitFor, warnOnce };

package/package.json

@@ -1,8 +1,7 @@
 {
   "name": "@ntnyq/utils",
   "type": "module",
-  "version": "0.10.0",
-  "packageManager": "pnpm@10.26.2",
+  "version": "0.11.0",
   "description": "Common used utils.",
   "keywords": [
     "utils"
@@ -30,22 +29,10 @@
     "dist"
   ],
   "sideEffects": false,
-  "scripts": {
-    "build": "tsdown",
-    "dev": "tsdown --watch src",
-    "lint": "eslint",
-    "prepare": "husky",
-    "prepublishOnly": "pnpm run build",
-    "release": "run-s release:check release:version",
-    "release:check": "run-s lint typecheck test",
-    "release:version": "bumpp",
-    "test": "vitest",
-    "typecheck": "tsc --noEmit"
-  },
   "devDependencies": {
-    "@ntnyq/eslint-config": "^5.8.0",
+    "@ntnyq/eslint-config": "^5.9.0",
     "@ntnyq/prettier-config": "^3.0.1",
-    "@ntnyq/tsconfig": "^3.0.0",
+    "@ntnyq/tsconfig": "^3.1.0",
     "bumpp": "^10.3.2",
     "eslint": "^9.39.2",
     "husky": "^9.1.7",
@@ -54,12 +41,22 @@
     "prettier": "^3.7.4",
     "tsdown": "^0.18.3",
     "typescript": "^5.9.3",
-    "vitest": "^4.0.15"
+    "vitest": "^4.0.16"
   },
   "engines": {
     "node": "^20.19.0 || ^22.13.0 || >=24"
   },
   "nano-staged": {
     "*.{js,ts,mjs,cjs,md,yml,yaml,toml,json}": "eslint --fix"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch src",
+    "lint": "eslint",
+    "release": "run-s release:check release:version",
+    "release:check": "run-s lint typecheck test",
+    "release:version": "bumpp",
+    "test": "vitest",
+    "typecheck": "tsc --noEmit"
   }
-}
+}