@d-matrix/utils 1.27.1 → 1.28.0

package/dist/react/useMediaQuery.js

@@ -1,42 +1,42 @@
-import { useState } from 'react';
-import { useIsomorphicLayoutEffect } from './useIsomorphicLayoutEffect';
-const IS_SERVER = typeof window === 'undefined';
-export function useMediaQuery(query, { defaultValue = false, initializeWithValue = true } = {}) {
-    const getMatches = (query) => {
-        if (IS_SERVER) {
-            return defaultValue;
-        }
-        return window.matchMedia(query).matches;
-    };
-    const [matches, setMatches] = useState(() => {
-        if (initializeWithValue) {
-            return getMatches(query);
-        }
-        return defaultValue;
-    });
-    // Handles the change event of the media query.
-    function handleChange() {
-        setMatches(getMatches(query));
-    }
-    useIsomorphicLayoutEffect(() => {
-        const matchMedia = window.matchMedia(query);
-        // Triggered at the first client-side load and if query changes
-        handleChange();
-        // Use deprecated `addListener` and `removeListener` to support Safari < 14 (#135)
-        if (matchMedia.addListener) {
-            matchMedia.addListener(handleChange);
-        }
-        else {
-            matchMedia.addEventListener('change', handleChange);
-        }
-        return () => {
-            if (matchMedia.removeListener) {
-                matchMedia.removeListener(handleChange);
-            }
-            else {
-                matchMedia.removeEventListener('change', handleChange);
-            }
-        };
-    }, [query]);
-    return matches;
-}
+import { useState } from 'react';
+import { useIsomorphicLayoutEffect } from './useIsomorphicLayoutEffect';
+const IS_SERVER = typeof window === 'undefined';
+export function useMediaQuery(query, { defaultValue = false, initializeWithValue = true } = {}) {
+    const getMatches = (query) => {
+        if (IS_SERVER) {
+            return defaultValue;
+        }
+        return window.matchMedia(query).matches;
+    };
+    const [matches, setMatches] = useState(() => {
+        if (initializeWithValue) {
+            return getMatches(query);
+        }
+        return defaultValue;
+    });
+    // Handles the change event of the media query.
+    function handleChange() {
+        setMatches(getMatches(query));
+    }
+    useIsomorphicLayoutEffect(() => {
+        const matchMedia = window.matchMedia(query);
+        // Triggered at the first client-side load and if query changes
+        handleChange();
+        // Use deprecated `addListener` and `removeListener` to support Safari < 14 (#135)
+        if (matchMedia.addListener) {
+            matchMedia.addListener(handleChange);
+        }
+        else {
+            matchMedia.addEventListener('change', handleChange);
+        }
+        return () => {
+            if (matchMedia.removeListener) {
+                matchMedia.removeListener(handleChange);
+            }
+            else {
+                matchMedia.removeEventListener('change', handleChange);
+            }
+        };
+    }, [query]);
+    return matches;
+}

package/dist/react/useSafeTimeout.d.ts

@@ -0,0 +1,12 @@
+declare type SetTimeout = (handler: TimerHandler, timeout?: number, ...args: unknown[]) => number;
+declare type ClearTimeout = (id: number) => void;
+/**
+ * Safely call `setTimeout` and `clearTimeout` within a component.
+ *
+ * This hook ensures that all timeouts are cleared when the component unmounts.
+ */
+export declare function useSafeTimeout(): {
+    safeSetTimeout: SetTimeout;
+    safeClearTimeout: ClearTimeout;
+};
+export {};

package/dist/react/useSafeTimeout.js

@@ -0,0 +1,28 @@
+import { useCallback, useEffect, useRef } from 'react';
+/**
+ * Safely call `setTimeout` and `clearTimeout` within a component.
+ *
+ * This hook ensures that all timeouts are cleared when the component unmounts.
+ */
+export function useSafeTimeout() {
+    const timers = useRef(new Set());
+    const safeSetTimeout = useCallback((handler, timeout, ...args) => {
+        const id = window.setTimeout(handler, timeout, ...args);
+        timers.current.add(id);
+        return id;
+    }, []);
+    const safeClearTimeout = useCallback((id) => {
+        clearTimeout(id);
+        timers.current.delete(id);
+    }, []);
+    useEffect(() => {
+        return () => {
+            // eslint-disable-next-line react-compiler/react-compiler
+            // eslint-disable-next-line react-hooks/exhaustive-deps
+            for (const id of timers.current) {
+                clearTimeout(id);
+            }
+        };
+    }, []);
+    return { safeSetTimeout, safeClearTimeout };
+}

package/dist/react/useStateCallback.d.ts

@@ -1,2 +1,2 @@
-/** 等价与类组件 setState(updater[, callback]) */
-export declare function useStateCallback<T>(initialState: T): [T, (state: T, cb?: (state: T) => void) => void];
+/** 等价与类组件 setState(updater[, callback]) */
+export declare function useStateCallback<T>(initialState: T): [T, (state: T, cb?: (state: T) => void) => void];

package/dist/react/useStateCallback.js

@@ -1,17 +1,17 @@
-import { useCallback, useEffect, useRef, useState } from 'react';
-/** 等价与类组件 setState(updater[, callback]) */
-export function useStateCallback(initialState) {
-    const [state, setState] = useState(initialState);
-    const cbRef = useRef(undefined);
-    const setStateCallback = useCallback((state, cb) => {
-        cbRef.current = cb;
-        setState(state);
-    }, []);
-    useEffect(() => {
-        if (cbRef.current) {
-            cbRef.current(state);
-            cbRef.current = undefined;
-        }
-    }, [state]);
-    return [state, setStateCallback];
-}
+import { useCallback, useEffect, useRef, useState } from 'react';
+/** 等价与类组件 setState(updater[, callback]) */
+export function useStateCallback(initialState) {
+    const [state, setState] = useState(initialState);
+    const cbRef = useRef(undefined);
+    const setStateCallback = useCallback((state, cb) => {
+        cbRef.current = cb;
+        setState(state);
+    }, []);
+    useEffect(() => {
+        if (cbRef.current) {
+            cbRef.current(state);
+            cbRef.current = undefined;
+        }
+    }, [state]);
+    return [state, setStateCallback];
+}

package/dist/support.d.ts

@@ -1,12 +1,12 @@
-/**
- * 是否是浏览器环境
- */
-export declare const isBrowserEnv: () => boolean;
-/**
- * 是否支持WebSocket
- */
-export declare const isWebSocket: () => boolean;
-/**
- * 是否支持SharedWorker
- */
-export declare const isSharedWorker: () => boolean;
+/**
+ * 是否是浏览器环境
+ */
+export declare const isBrowserEnv: () => boolean;
+/**
+ * 是否支持WebSocket
+ */
+export declare const isWebSocket: () => boolean;
+/**
+ * 是否支持SharedWorker
+ */
+export declare const isSharedWorker: () => boolean;

package/dist/support.js

@@ -1,12 +1,12 @@
-/**
- * 是否是浏览器环境
- */
-export const isBrowserEnv = () => typeof window !== 'undefined';
-/**
- * 是否支持WebSocket
- */
-export const isWebSocket = () => typeof WebSocket !== 'undefined';
-/**
- * 是否支持SharedWorker
- */
-export const isSharedWorker = () => typeof SharedWorker !== 'undefined';
+/**
+ * 是否是浏览器环境
+ */
+export const isBrowserEnv = () => typeof window !== 'undefined';
+/**
+ * 是否支持WebSocket
+ */
+export const isWebSocket = () => typeof WebSocket !== 'undefined';
+/**
+ * 是否支持SharedWorker
+ */
+export const isSharedWorker = () => typeof SharedWorker !== 'undefined';

package/dist/timer.d.ts

@@ -1,5 +1,5 @@
-/**
- * 睡眠
- * @param time 睡眠时间
- */
-export declare const sleep: (ms?: number) => Promise<unknown>;
+/**
+ * 睡眠
+ * @param time 睡眠时间
+ */
+export declare const sleep: (ms?: number) => Promise<unknown>;

package/dist/timer.js

@@ -1,5 +1,5 @@
-/**
- * 睡眠
- * @param time 睡眠时间
- */
-export const sleep = (ms = 0) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * 睡眠
+ * @param time 睡眠时间
+ */
+export const sleep = (ms = 0) => new Promise((resolve) => setTimeout(resolve, ms));

package/dist/types.d.ts

@@ -1,21 +1,128 @@
-/** 指定的属性变为可选 */
-export declare type WithOptional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
-/** 除了 K 的其他属性变成可选 */
-export declare type ExcludePickPartial<T, K extends keyof T> = Partial<Omit<T, K>> & Pick<T, K>;
-export declare type Undefinable<T> = {
-    [K in keyof T]: T[K] | undefined;
-};
-/** 获取对象中的方法名称，返回union type */
-export declare type FunctionPropertyNames<T> = {
-    [P in keyof T]-?: T[P] extends Function ? P : never;
-}[keyof T];
-/** 获取对象中非函数属性名称，返回union type */
-export declare type NonFunctionPropertyNames<T> = {
-    [P in keyof T]-?: T[P] extends Function ? never : P;
-}[keyof T];
-/** 获取对象中key的值，返回由这些值组成的union type */
-export declare type ValueOf<T> = T[keyof T];
-/** 指定属性变为必选 */
-export declare type WithRequired<T, K extends keyof T> = T & {
-    [P in K]-?: T[P];
-};
+/**
+ * 创建一个新类型，将指定属性设为可选
+ *
+ * @template T - 原始对象类型
+ * @template K - 要设为可选的属性键名联合类型，必须是T的键的子集
+ *
+ * @example
+ * ```typescript
+ * type User = {
+ *   id: number;
+ *   name: string;
+ *   email: string;
+ * };
+ *
+ * // 将email属性设为可选
+ * type UserWithOptionalEmail = WithOptional<User, 'email'>;
+ * // 等价于: { id: number; name: string; email?: string | undefined; }
+ * ```
+ */
+export declare type WithOptional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+/**
+ * 创建一个新类型，该类型包含原类型T的部分属性和指定属性K的完整属性
+ *
+ * @template T - 原始对象类型
+ * @template K - 需要保持完整的属性键名，必须是T的键名的子集
+ *
+ * @description
+ * 该类型工具首先使用Omit排除类型T中的属性K，然后对剩余属性应用Partial使其变为可选，
+ * 同时使用Pick提取属性K并保持其完整性，最后将两部分进行交叉合并。
+ * 结果类型中，除了K指定的属性保持必需外，其他所有属性都变为可选。
+ */
+export declare type ExcludePickPartial<T, K extends keyof T> = Partial<Omit<T, K>> & Pick<T, K>;
+/**
+ * 定义一个工具类型Undefinable，用于将传入类型的每个属性都变为可选（即允许undefined）
+ *
+ * @template T - 需要处理的原始类型
+ * @returns 返回一个新的类型，该类型的每个属性都是原类型对应属性的联合类型加上undefined
+ */
+export declare type Undefinable<T> = {
+    [K in keyof T]: T[K] | undefined;
+};
+/**
+ * 获取对象类型中所有函数类型的属性名
+ *
+ * @template T - 要检查的对象类型
+ * @returns 返回T类型中所有值为函数的属性名组成的联合类型
+ *
+ * @example
+ * ```typescript
+ * type Example = {
+ *   name: string;
+ *   age: number;
+ *   getName(): string;
+ *   getAge: () => number;
+ * };
+ *
+ * // 结果为 "getName" | "getAge"
+ * type FunctionProps = FunctionPropertyNames<Example>;
+ * ```
+ */
+export declare type FunctionPropertyNames<T> = {
+    [P in keyof T]-?: T[P] extends Function ? P : never;
+}[keyof T];
+/**
+ * 获取对象类型中所有非函数属性的属性名联合类型
+ *
+ * @template T - 要处理的对象类型
+ *
+ * @example
+ * ```typescript
+ * type Example = {
+ *   name: string;
+ *   age: number;
+ *   getName(): string;
+ * };
+ *
+ * // 结果为 "name" | "age"
+ * type Result = NonFunctionPropertyNames<Example>;
+ * ```
+ *
+ * @returns 返回T类型中所有非函数属性的属性名组成的联合类型
+ */
+export declare type NonFunctionPropertyNames<T> = {
+    [P in keyof T]-?: T[P] extends Function ? never : P;
+}[keyof T];
+/**
+ * 获取对象类型T的所有值类型的联合类型
+ *
+ * 该工具类型通过 keyof T 获取对象T的所有键名，然后使用索引访问操作符 [keyof T]
+ * 来获取所有键对应的值类型，最终得到一个联合类型包含所有可能的值类型
+ *
+ * @example
+ * ```typescript
+ * type Person = {
+ *   name: string;
+ *   age: number;
+ *   active: boolean;
+ * };
+ *
+ * // 结果类型为 string | number | boolean
+ * type PersonValues = ValueOf<Person>;
+ * ```
+ */
+export declare type ValueOf<T> = T[keyof T];
+/**
+ * 创建一个新类型，将指定属性设为必需
+ *
+ * @template T 原始对象类型
+ * @template K 需要设为必需的属性名联合类型，必须是T的键的子集
+ * @returns 返回一个新的交叉类型，包含原始类型T和将K中属性设为必需后的类型
+ *
+ * @example
+ * type User = { name?: string; age?: number; email?: string };
+ * type UserWithRequiredName = WithRequired<User, 'name'>;
+ * // 结果: { name: string; age?: number; email?: string }
+ */
+export declare type WithRequired<T, K extends keyof T> = T & {
+    [P in K]-?: T[P];
+};
+/**
+ * 定义一个工具类型 Nullable，用于将传入类型的每个属性都变为可为空的联合类型
+ *
+ * @template T - 需要处理的原始类型
+ * @returns 返回一个新的类型，该类型的所有属性都与原始类型相同，但每个属性的值类型都扩展了 null 类型
+ */
+export declare type Nullable<T> = {
+    [K in keyof T]: T[K] | null;
+};

package/dist/types.js

@@ -1 +1 @@
-export {};
+export {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@d-matrix/utils",
   "sideEffects": false,
-  "version": "1.27.1",
+  "version": "1.28.0",
   "description": "A dozen of utils for Front-End Development",
   "main": "dist/index.js",
   "scripts": {

package/readme.md

@@ -622,12 +622,16 @@ const newList = array.moveToStart(list, (item) => item.id === 4);
 
 - `moveMulti<T extends unknown>(arr: T[], indexes: number[], start: number): T[]`
 
-移动多个元素到数组中指定的位置,用法,见[测试用例](tests/algorithm.cy.ts)
+移动多个元素到数组中指定的位置,用法,见[测试用例](tests/array.cy.ts)
 
 - `getArrayOrUndefined<T>(array?: T[] | undefined | null): T[] | undefined`
 
 如果`array`是数组且不为空,返回该数组，否则返回`undefined`,见[测试用例](tests/array.cy.ts)
 
+- `calcUnusedMinSerialNumber = <T extends Record<string, unknown>>(list: T[],options: { fieldName: keyof T; prefix: string; defaultNo?: number }): number`
+
+通用序号计算工具：从指定列表中提取「前缀+数字」格式的值，找到未被使用的最小正整数序号，用法见[测试用例](tests/array.cy.ts)
+
 ## number
 
 - `randomInt(min: number, max: number): number`