@ntnyq/utils 0.9.1 → 0.10.0

package/dist/index.d.ts

@@ -9,6 +9,22 @@ declare function noop(): void;
 declare const NOOP: typeof noop;
 //#endregion
 //#region src/fn/once.d.ts
+/**
+* Creates a function that is restricted to invoking `func` once. Repeat calls to the function return `false`.
+*
+* @param func - The function to restrict.
+* @returns A new function that returns `true` when `func` is invoked for the first time and `false` on subsequent calls.
+*
+* @example
+*
+* ```ts
+* const initialize = once(() => {
+*   console.log('Initialized')
+* })
+*
+* initialize() // Logs: 'Initialized', returns true
+* ```
+*/
 declare function once<T extends unknown[]>(func: (...args: T) => void): (this: unknown, ...args: T) => boolean;
 //#endregion
 //#region src/is/dom.d.ts
@@ -65,6 +81,13 @@ declare function isError(value: unknown): value is Error;
 declare function isNativePromise<T = unknown>(value: unknown): value is Promise<T>;
 declare function isPromise<T = unknown>(value: unknown): value is Promise<T>;
 declare function isIterable<T = unknown>(value: unknown): value is Iterable<T>;
+declare function isBlob(value: unknown): value is Blob;
+declare function isFormData(value: unknown): value is FormData;
+declare function isFile(value: unknown): value is File;
+type UrlString = string & {
+  readonly __brand: "UrlString";
+};
+declare function isUrlString(value: unknown): value is UrlString;
 //#endregion
 //#region src/is/isDeepEqual.d.ts
 /**
@@ -97,7 +120,7 @@ type Nullable<T> = T | null;
 /**
 * Overwrite some keys type
 */
-type Overwrite<T, U> = Pick<T, Exclude<keyof T, keyof U>> & U;
+type Overwrite<T, U$1> = Pick<T, Exclude<keyof T, keyof U$1>> & U$1;
 /**
 * Prettify object type
 */
@@ -129,7 +152,7 @@ type LiteralUnion<Union extends Base, Base = string> = Union | (Base & {
 /**
 * @see {@link TODO:}
 */
-type Merge<T, U> = keyof T & keyof U extends never ? T & U : Omit<T, keyof T & keyof U> & U;
+type Merge<T, U$1> = keyof T & keyof U$1 extends never ? T & U$1 : Omit<T, keyof T & keyof U$1> & U$1;
 /**
 * Non empty object `{}`
 */
@@ -586,7 +609,7 @@ declare function interopDefault<T>(mod: Awaitable<T>): Promise<InteropModuleDefa
 * // => {}
 * ```
 */
-declare function resolveSubOptions<T extends Record<string, any>, K extends keyof T>(options: T, key: K): Partial<ResolvedOptions<T[K]>>;
+declare function resolveSubOptions<T extends Record<string, any>, K$1 extends keyof T>(options: T, key: K$1): Partial<ResolvedOptions<T[K$1]>>;
 //#endregion
 //#region src/number/random.d.ts
 interface RamdomNumberOptions {
@@ -648,10 +671,10 @@ interface ToIntegerOptions {
 declare function toInteger(value: unknown, options?: ToIntegerOptions): number;
 //#endregion
 //#region src/object/omit.d.ts
-declare function omit<T, K extends keyof T>(object: T, ...keys: K[]): Omit<T, K>;
+declare function omit<T, K$1 extends keyof T>(object: T, ...keys: K$1[]): Omit<T, K$1>;
 //#endregion
 //#region src/object/pick.d.ts
-declare function pick<T, K extends keyof T>(object: T, keys: K[]): Pick<T, K>;
+declare function pick<T, K$1 extends keyof T>(object: T, keys: K$1[]): Pick<T, K$1>;
 //#endregion
 //#region src/object/clean.d.ts
 interface CleanObjectOptions {
@@ -838,7 +861,30 @@ declare function getStringSimilarity(str1: string, str2: string, options?: GetSt
 * Special chars
 */
 declare const SPECIAL_CHAR: {
+  /**
+  * 中文顿号
+  */
+  chineseComma: string;
+  /**
+  * 英文逗号
+  */
+  englishComma: string;
+  /**
+  * 英文句号
+  */
+  englishPeriod: string;
+  /**
+  * 连接符
+  */
+  hyphen: string;
+  /**
+  * 换行
+  */
   newline: string;
+  /**
+  * 空格
+  */
+  whitespace: string;
 };
 //#endregion
 //#region src/constants/regexp.d.ts
@@ -857,4 +903,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, 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, isBoolean, isBrowser, isDeepEqual, isElementVisibleInViewport, isEmptyArray, isEmptyMap, isEmptyObject, isEmptySet, isEmptyString, isEmptyStringOrWhitespace, isError, isFunction, isHTMLElement, isInteger, isIterable, isMap, isNaN, isNativePromise, isNil, isNonEmptyArray, isNonEmptyString, isNull, isNullOrUndefined, isNumber, isNumbericString, isObject, isPromise, isRegExp, isSet, isString, isTruthy, isUndefined, 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, 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 };

package/dist/index.js

@@ -10,6 +10,22 @@ const NOOP = noop;
 
 //#endregion
 //#region src/fn/once.ts
+/**
+* Creates a function that is restricted to invoking `func` once. Repeat calls to the function return `false`.
+*
+* @param func - The function to restrict.
+* @returns A new function that returns `true` when `func` is invoked for the first time and `false` on subsequent calls.
+*
+* @example
+*
+* ```ts
+* const initialize = once(() => {
+*   console.log('Initialized')
+* })
+*
+* initialize() // Logs: 'Initialized', returns true
+* ```
+*/
 function once(func) {
 	let called = false;
 	return function(...args) {
@@ -139,6 +155,24 @@ function isPromise(value) {
 function isIterable(value) {
 	return isFunction(value?.[Symbol.iterator]);
 }
+function isBlob(value) {
+	return getObjectType(value) === "Blob";
+}
+function isFormData(value) {
+	return getObjectType(value) === "FormData";
+}
+function isFile(value) {
+	return getObjectType(value) === "File";
+}
+function isUrlString(value) {
+	if (!isString(value)) return false;
+	try {
+		new URL(value);
+		return true;
+	} catch {
+		return false;
+	}
+}
 
 //#endregion
 //#region src/is/isDeepEqual.ts
@@ -146,9 +180,7 @@ function isIterable(value) {
 * check if two values are deeply equal
 */
 function isDeepEqual(value1, value2) {
-	const type1 = getObjectType(value1);
-	const type2 = getObjectType(value2);
-	if (type1 !== type2) return false;
+	if (getObjectType(value1) !== getObjectType(value2)) return false;
 	if (isArray(value1) && isArray(value2)) {
 		if (value1.length !== value2.length) return false;
 		return value1.every((item, index) => isDeepEqual(item, value2[index]));
@@ -171,16 +203,14 @@ function isDeepEqual(value1, value2) {
 */
 function scrollElementIntoView(element, options = {}) {
 	const body = document.body;
-	const { parent = body,...scrollIntoViewOptions } = options;
+	const { parent = body, ...scrollIntoViewOptions } = options;
 	if (parent === body) {
 		parent.scrollIntoView(scrollIntoViewOptions);
 		return;
 	}
 	const parentRect = parent.getBoundingClientRect();
 	const elementRect = element.getBoundingClientRect();
-	const isHorizontal = parent.scrollWidth > parent.scrollHeight;
-	const isOutOfView = isHorizontal ? elementRect.left < parentRect.left || elementRect.right > parentRect.right : elementRect.top < parentRect.top || elementRect.bottom > parentRect.bottom;
-	if (isOutOfView) parent.scrollIntoView(scrollIntoViewOptions);
+	if (parent.scrollWidth > parent.scrollHeight ? elementRect.left < parentRect.left || elementRect.right > parentRect.right : elementRect.top < parentRect.top || elementRect.bottom > parentRect.bottom) parent.scrollIntoView(scrollIntoViewOptions);
 }
 
 //#endregion
@@ -193,8 +223,7 @@ function scrollElementIntoView(element, options = {}) {
 */
 function openExternalURL(url, options = {}) {
 	const { target = "_blank" } = options;
-	const proxy = window.open(url, target);
-	return proxy;
+	return window.open(url, target);
 }
 
 //#endregion
@@ -276,6 +305,9 @@ function unescapeHTML(str) {
 //#endregion
 //#region src/misc/raf.ts
 /**
+* @file raf.ts
+*/
+/**
 * Gets the global root object.
 * @returns the global root object
 */
@@ -290,8 +322,7 @@ function getRoot() {
 */
 function rAF(fn) {
 	const root = getRoot();
-	const raf = root.requestAnimationFrame;
-	return raf.call(root, fn);
+	return root.requestAnimationFrame.call(root, fn);
 }
 /**
 * Cancel animation frame
@@ -301,8 +332,7 @@ function rAF(fn) {
 */
 function cAF(id) {
 	const root = getRoot();
-	const caf = root.cancelAnimationFrame;
-	return caf.call(root, id);
+	return root.cancelAnimationFrame.call(root, id);
 }
 
 //#endregion
@@ -467,8 +497,7 @@ function convertFromMilliseconds(milliseconds, toUnit = "SECOND") {
 * ```
 */
 function convertTimeUnit(value, fromUnit, toUnit) {
-	const milliseconds = convertToMilliseconds(value, fromUnit);
-	return convertFromMilliseconds(milliseconds, toUnit);
+	return convertFromMilliseconds(convertToMilliseconds(value, fromUnit), toUnit);
 }
 
 //#endregion
@@ -531,8 +560,7 @@ function convertFromBytes(bytes, toUnit = "MB") {
 * ```
 */
 function convertStorageUnit(value, fromUnit, toUnit) {
-	const bytes = convertToBytes(value, fromUnit);
-	return convertFromBytes(bytes, toUnit);
+	return convertFromBytes(convertToBytes(value, fromUnit), toUnit);
 }
 
 //#endregion
@@ -545,7 +573,7 @@ function convertStorageUnit(value, fromUnit, toUnit) {
 */
 function at(array, index) {
 	const length = array.length;
-	if (!length) return void 0;
+	if (!length) return;
 	if (index < 0) index += length;
 	return array[index];
 }
@@ -590,8 +618,7 @@ function unique(array) {
 */
 function uniqueBy(array, equalFn) {
 	return array.reduce((acc, cur) => {
-		const idx = acc.findIndex((item) => equalFn(item, cur));
-		if (idx === -1) acc.push(cur);
+		if (acc.findIndex((item) => equalFn(item, cur)) === -1) acc.push(cur);
 		return acc;
 	}, []);
 }
@@ -759,7 +786,10 @@ function toInteger(value, options = {}) {
 */
 function randomString(length = 16, chars = "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ") {
 	const result = [];
-	for (let i = length; i > 0; --i) result.push(chars[randomNumber(chars.length)]);
+	for (let i = length; i > 0; --i) {
+		const matchedChar = chars[randomNumber(chars.length)];
+		if (matchedChar) result.push(matchedChar);
+	}
 	return result.join("");
 }
 
@@ -794,7 +824,7 @@ const _RE_FULL_WS = /^\s*$/;
 * ```
 */
 function unindent(input) {
-	const lines = (typeof input === "string" ? input : input[0]).split("\n");
+	const lines = (isString(input) ? input : input[0])?.split("\n") ?? [];
 	const whitespaceLines = lines.map((line) => _RE_FULL_WS.test(line));
 	const commonIndent = lines.reduce((min, line, idx) => {
 		if (whitespaceLines[idx]) return min;
@@ -1072,9 +1102,10 @@ function hasOwn(object, key) {
 //#endregion
 //#region src/object/pick.ts
 function pick(object, keys) {
-	return Object.assign({}, ...keys.map((key) => {
-		if (object && hasOwn(object, key)) return { [key]: object[key] };
-	}));
+	return keys.reduce((result, key) => {
+		if (object && hasOwn(object, key)) result[key] = object[key];
+		return result;
+	}, {});
 }
 
 //#endregion
@@ -1145,7 +1176,14 @@ function sortObject(obj, options = {}) {
 /**
 * Special chars
 */
-const SPECIAL_CHAR = { newline: "\n" };
+const SPECIAL_CHAR = {
+	chineseComma: "、",
+	englishComma: ",",
+	englishPeriod: ".",
+	hyphen: "-",
+	newline: "\n",
+	whitespace: " "
+};
 
 //#endregion
 //#region src/constants/regexp.ts
@@ -1165,4 +1203,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, isBoolean, isBrowser, isDeepEqual, isElementVisibleInViewport, isEmptyArray, isEmptyMap, isEmptyObject, isEmptySet, isEmptyString, isEmptyStringOrWhitespace, isError, isFunction, isHTMLElement, isInteger, isIterable, isMap, isNaN, isNativePromise, isNil, isNonEmptyArray, isNonEmptyString, isNull, isNullOrUndefined, isNumber, isNumbericString, isObject, isPromise, isRegExp, isSet, isString, isTruthy, isUndefined, 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, 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 };

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@ntnyq/utils",
   "type": "module",
-  "version": "0.9.1",
-  "packageManager": "pnpm@10.14.0",
+  "version": "0.10.0",
+  "packageManager": "pnpm@10.26.2",
   "description": "Common used utils.",
   "keywords": [
     "utils"
@@ -43,20 +43,21 @@
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {
-    "@ntnyq/eslint-config": "^5.3.1",
+    "@ntnyq/eslint-config": "^5.8.0",
     "@ntnyq/prettier-config": "^3.0.1",
-    "bumpp": "^10.2.3",
-    "eslint": "^9.33.0",
+    "@ntnyq/tsconfig": "^3.0.0",
+    "bumpp": "^10.3.2",
+    "eslint": "^9.39.2",
     "husky": "^9.1.7",
-    "nano-staged": "^0.8.0",
+    "nano-staged": "^0.9.0",
     "npm-run-all2": "^8.0.4",
-    "prettier": "^3.6.2",
-    "tsdown": "^0.14.1",
-    "typescript": "^5.9.2",
-    "vitest": "^3.2.4"
+    "prettier": "^3.7.4",
+    "tsdown": "^0.18.3",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.15"
   },
   "engines": {
-    "node": ">=18.18.0"
+    "node": "^20.19.0 || ^22.13.0 || >=24"
   },
   "nano-staged": {
     "*.{js,ts,mjs,cjs,md,yml,yaml,toml,json}": "eslint --fix"