@cloudcome/utils-core 1.1.0 → 1.1.1

package/src/object/merge.ts

@@ -0,0 +1,180 @@
+import { isArray, isObject, typeIs } from '@/type';
+import type { AnyArray, AnyObject } from '@/types';
+import { objectEach } from './each';
+
+export type TObjectMergeRule = {
+  /**
+   * 处理冲突
+   * @param target - 目标对象
+   * @param source - 源对象
+   * @param key - 键名
+   * @returns 返回 true 表示继续处理，否则返回 false
+   */
+  next: (info: {
+    target: AnyObject | AnyArray;
+    source: AnyObject | AnyArray;
+    key: string | number;
+  }) => boolean;
+
+  /**
+   * 处理赋值
+   * @param target - 目标对象
+   * @param source - 源对象
+   * @param key - 键名
+   * @returns 返回处理后的值
+   */
+  assign: (info: {
+    target: AnyObject | AnyArray;
+    source: AnyObject | AnyArray;
+    key: string | number;
+    // biome-ignore lint/suspicious/noExplicitAny: <explanation>
+    merge: () => any;
+    // biome-ignore lint/suspicious/noExplicitAny: <explanation>
+  }) => any;
+};
+
+function _objectMerge(mergeRule: TObjectMergeRule, target: AnyObject | AnyArray, ...sources: (AnyObject | AnyArray)[]) {
+  const seen = new WeakMap<AnyObject | AnyArray, AnyObject | AnyArray>();
+  const { assign, next } = mergeRule;
+  const align = (target: AnyObject | AnyArray, source: AnyObject | AnyArray) => {
+    const targetType = typeIs(target);
+    const sourceType = typeIs(source);
+
+    if (targetType === sourceType) {
+      return target;
+    }
+
+    return sourceType === 'array' ? [] : {};
+  };
+  // biome-ignore lint/suspicious/noExplicitAny: <explanation>
+  const each = (source: AnyObject | AnyArray, iterator: (val: any, key: string | number) => void) => {
+    if (isObject(source)) {
+      objectEach(source, iterator);
+    } else {
+      source.forEach(iterator);
+    }
+  };
+
+  const merge = (target: AnyObject | AnyArray, source: AnyObject | AnyArray): AnyObject | AnyArray => {
+    // 如果循环引用了，则直接返回目标对象
+    if (seen.has(source)) {
+      // biome-ignore lint/style/noNonNullAssertion: <explanation>
+      return seen.get(source)!;
+    }
+
+    // 对齐目标对象和源对象
+    const merged = align(target, source);
+
+    // 存储循环引用
+    seen.set(source, merged);
+
+    // 遍历源对象
+    each(source, (value, key) => {
+      if (!next({ target: merged, source, key })) {
+        return;
+      }
+
+      if (isObject(value) || isArray(value)) {
+        // @ts-expect-error
+        merged[key] = assign({
+          target: merged,
+          source,
+          key,
+          // @ts-expect-error
+          merge: () => merge(merged[key], value),
+        });
+      } else {
+        // @ts-expect-error
+        merged[key] = assign({
+          target: merged,
+          source,
+          key,
+          merge: () => value,
+        });
+      }
+    });
+
+    return merged;
+  };
+
+  let returnTarget = target;
+
+  for (const source of sources) {
+    returnTarget = merge(target, source);
+  }
+
+  return returnTarget;
+}
+
+/**
+ * 合并多个对象或数组。如果遇到循环引用，则直接返回目标对象。
+ *
+ * @param target - 目标对象或数组。
+ * @param sources - 要合并的源对象或数组。
+ * @returns 合并后的对象或数组。
+ *
+ * @example
+ * ```typescript
+ * const obj1 = { a: 1, b: { x: 10 } };
+ * const obj2 = { b: { y: 20 }, c: 3 };
+ * const merged = objectMerge(obj1, obj2);
+ * console.log(merged); // { a: 1, b: { x: 10, y: 20 }, c: 3 }
+ * ```
+ */
+export function objectMerge(target: AnyObject | AnyArray, ...sources: (AnyObject | AnyArray)[]) {
+  return _objectMerge(
+    {
+      next() {
+        return true;
+      },
+      assign({ merge }) {
+        return merge();
+      },
+    },
+    target,
+    ...sources,
+  );
+}
+
+/**
+ * 为对象设置默认值。如果目标对象中的属性为 `undefined`，则使用默认对象中的属性值。
+ * 支持多个默认对象，优先级从左到右依次降低。
+ * 如果目标对象中的属性已经是对象或数组，则递归地设置默认值。
+ *
+ * @param target - 目标对象或数组。
+ * @param defaults - 默认对象或数组。
+ * @returns 合并后的对象或数组。
+ *
+ * @example
+ * ```typescript
+ * const obj = { a: 1, b: undefined };
+ * const defaults = { a: 4, b: 2, c: 3 };
+ * const result = objectDefaults(obj, defaults);
+ * console.log(result); // { a: 1, b: 2, c: 3 }
+ *
+ * const obj2 = { a: 1, b: 2 };
+ * const defaults2 = { a: 5, b: 3, c: 4 };
+ * const result2 = objectDefaults(obj2, defaults2);
+ * console.log(result2); // { a: 1, b: 2, c: 4 }
+ *
+ * const obj3 = { a: { x: 1 }, b: undefined };
+ * const defaults3 = { a: { x: 4, z: 3 }, b: { y: 2 } };
+ * const result3 = objectDefaults(obj3, defaults3);
+ * console.log(result3); // { a: { x: 1, z: 3 }, b: { y: 2 } }
+ * ```
+ */
+export function objectDefaults<T extends AnyObject | AnyArray>(target: T, defaults: T): T {
+  return _objectMerge(
+    {
+      next({ target, source, key }) {
+        // @ts-expect-error
+        return target[key] === undefined || isObject(target[key]) || isArray(target[key]);
+      },
+      assign({ merge }) {
+        return merge();
+      },
+    },
+    target,
+    defaults,
+  ) as T;
+}

package/{dist/object/process.d.ts → src/object/process.ts}

@@ -1,4 +1,5 @@
-import { AnyObject } from '../types';
+import type { AnyObject } from '@/types';
+
 /**
  * 从对象中选择指定键的属性，返回一个新的对象。
  *
@@ -13,7 +14,16 @@ import { AnyObject } from '../types';
  * console.log(result); // { a: 1, c: 3 }
  * ```
  */
-export declare function objectPick<T extends AnyObject, K extends keyof T>(object: T, keys: K[]): Pick<T, K>;
+export function objectPick<T extends AnyObject, K extends keyof T>(object: T, keys: K[]): Pick<T, K> {
+  const result = {} as Pick<T, K>;
+  for (const key of keys) {
+    if (key in object) {
+      result[key] = object[key];
+    }
+  }
+  return result;
+}
+
 /**
  * 从对象中排除指定键的属性，返回一个新的对象。
  *
@@ -28,7 +38,17 @@ export declare function objectPick<T extends AnyObject, K extends keyof T>(objec
  * console.log(result); // { b: 2, c: 3 }
  * ```
  */
-export declare function objectOmit<T extends AnyObject, K extends keyof T>(object: T, keys: K[]): Omit<T, K>;
+export function objectOmit<T extends AnyObject, K extends keyof T>(object: T, keys: K[]): Omit<T, K> {
+  const result = {} as Omit<T, K>;
+  for (const key in object) {
+    if (!keys.includes(key as unknown as K)) {
+      // @ts-expect-error
+      result[key] = object[key];
+    }
+  }
+  return result;
+}
+
 /**
  * 遍历对象的每个键值对，并对每个键值对执行提供的映射函数，返回一个新的对象。
  *
@@ -43,4 +63,18 @@ export declare function objectOmit<T extends AnyObject, K extends keyof T>(objec
  * console.log(result); // { a: '2', b: '4', c: '6' }
  * ```
  */
-export declare function objectMap<T extends AnyObject, V>(object: T, mapper: (value: T[keyof T], key: keyof T) => V): Record<keyof T, V>;
+export function objectMap<T extends AnyObject, V>(
+  object: T,
+  mapper: (value: T[keyof T], key: keyof T) => V,
+): Record<keyof T, V> {
+  return Object.fromEntries(
+    Object.entries(object).map(([key, value]) => [
+      key,
+      mapper(
+        // @ts-expect-error
+        value,
+        key as keyof T,
+      ),
+    ]),
+  ) as Record<keyof T, V>;
+}

package/src/path.ts

@@ -0,0 +1,188 @@
+import { arrayEach } from './array';
+
+/**
+ * 判断是否是当前目录标记
+ * @param {string} slice - 路径片段
+ * @returns {boolean} - 如果是当前目录标记'.'则返回true，否则返回false
+ */
+function _isCurrentSlice(slice: string): boolean {
+  return slice === '.';
+}
+
+/**
+ * 判断是否是上级目录标记
+ * @param {string} slice - 路径片段
+ * @returns {boolean} - 如果是上级目录标记'..'则返回true，否则返回false
+ */
+function _isParentSlice(slice: string): boolean {
+  return slice === '..';
+}
+
+/**
+ * 判断是否是绝对路径
+ * @param {string} path - 路径字符串
+ * @returns {boolean} - 如果是绝对路径则返回true，否则返回false
+ * @example
+ * ```typescript
+ * const isAbs = isAbsolutePath('/path/to/file');
+ * console.log(isAbs); // 输出: true
+ * ```
+ */
+export function isAbsolutePath(path: string): boolean {
+  return path.startsWith('/');
+}
+
+/**
+ * 判断是否是相对路径
+ * @param {string} path - 路径字符串
+ * @returns {boolean} - 如果是相对路径则返回true，否则返回false
+ * @example
+ * ```typescript
+ * const isRel = isRelativePath('path/to/file');
+ * console.log(isRel); // 输出: true
+ * ```
+ */
+export function isRelativePath(path: string): boolean {
+  return !isAbsolutePath(path);
+}
+
+/**
+ * 标准化路径
+ * @param {string} path - 要标准化的路径字符串。
+ * @returns {string} - 标准化后的路径字符串。
+ * @example
+ * ```typescript
+ * const normalizedPath = pathNormalize('/path///to///file');
+ * console.log(normalizedPath); // 输出: '/path/to/file'
+ * ```
+ */
+export function pathNormalize(path: string): string {
+  const slices = path
+    .replace(/\\/g, '/')
+    .replace(/\/{2,}/g, '/')
+    .replace(/\.{3,}/g, '..')
+    .replace(/\/\.\//g, '/')
+    .split('/')
+    .map((point) => point.trim());
+  const points: string[] = [];
+  const isAbs = slices[0] === '';
+
+  const push = (point: string) => {
+    points.push(point);
+  };
+
+  const back = () => {
+    // 绝对路径不能退到根目录
+    if (points.length === 1 && isAbs) return;
+
+    //
+    if (points.length === 0 || points.at(-1) === '..') {
+      points.push('..');
+    } else {
+      points.pop();
+    }
+  };
+
+  for (const slice of slices) {
+    const isCurrent = _isCurrentSlice(slice);
+    const isParent = _isParentSlice(slice);
+
+    // // 未进入实际路径
+    // if (!inPoints) {
+    //   push(slice);
+    //   inPoints = !isCurrent && !isParent;
+    //   continue;
+    // }
+
+    if (isCurrent) {
+      continue;
+    }
+
+    if (isParent) {
+      back();
+      continue;
+    }
+
+    push(slice);
+  }
+
+  return points.join('/');
+}
+
+/**
+ * 路径合并
+ * @param {string} from - 起始路径。
+ * @param {...string[]} to - 要合并的路径片段。
+ * @returns {string} - 合并后的路径字符串。
+ * @example
+ * ```typescript
+ * const fullPath = pathJoin('/path', '/to', 'file');
+ * console.log(fullPath); // 输出: '/path/to/file'
+ * ```
+ */
+export function pathJoin(from: string, ...to: string[]): string {
+  return pathNormalize([from, ...to].join('/'));
+}
+
+/**
+ * 解析路径
+ * @param {string} from - 起始路径
+ * @param {...string[]} to - 要解析的路径片段
+ * @returns {string} - 解析后的绝对路径
+ * @example
+ * ```typescript
+ * const resolvedPath = pathResolve('/path', '/to', 'file');
+ * console.log(resolvedPath); // 输出: '/to/file'
+ * ```
+ */
+export function pathResolve(from: string, ...to: string[]): string {
+  const paths = [from, ...to].map(pathNormalize);
+
+  let lastStartPath = from;
+  let lastStartIndex = 0;
+
+  arrayEach(
+    paths,
+    (path, index) => {
+      if (isAbsolutePath(path)) {
+        lastStartPath = path;
+        lastStartIndex = index;
+        return false;
+      }
+    },
+    true,
+  );
+
+  return pathJoin(lastStartPath, ...paths.slice(lastStartIndex + 1));
+}
+
+/**
+ * 将相对路径转换为标准的相对路径格式(添加'./'前缀)
+ *
+ * @param {string} path - 要处理的路径字符串
+ * @returns {string} 处理后的路径字符串
+ *
+ * @example <caption>处理绝对路径</caption>
+ * ```typescript
+ * const result = pathRelativize('/path/to/file');
+ * console.log(result); // 输出: '/path/to/file'
+ * ```
+ *
+ * @example <caption>处理已带'./'前缀的相对路径</caption>
+ * ```typescript
+ * const result = pathRelativize('./path/to/file');
+ * console.log(result); // 输出: './path/to/file'
+ * ```
+ *
+ * @example <caption>处理不带'./'前缀的相对路径</caption>
+ * ```typescript
+ * const result = pathRelativize('path/to/file');
+ * console.log(result); // 输出: './path/to/file'
+ * ```
+ */
+export function pathRelativize(path: string): string {
+  if (isAbsolutePath(path)) return path;
+  if (path.startsWith('./')) return path;
+  if (path.startsWith('../')) return path;
+  return `./${path}`;
+}

package/{dist/promise.d.ts → src/promise.ts}

@@ -1,16 +1,33 @@
+import { isObject, isPromise } from './type';
+
 /**
  * 检查给定的值是否为 Promise 类似对象。
  * @param unknown - 要检查的值。
  * @returns 如果值是 Promise 类似对象，则返回 `true`，否则返回 `false`。
  */
-export declare function isPromiseLike<T>(unknown: unknown): unknown is Promise<T>;
+export function isPromiseLike<T>(unknown: unknown): unknown is Promise<T> {
+  return isPromise(unknown) || (isObject(unknown) && typeof (unknown as unknown as Promise<T>).then === 'function');
+}
+
 /**
  * 等待一定时间后解决 Promise
  * @param ms - 等待的毫秒数，默认为 0
  * @param ctrl - 可选的 AbortController，用于提前终止等待
  * @returns 一个 Promise，等待指定时间后解决
  */
-export declare function promiseDelay(ms?: number, ctrl?: AbortController): Promise<void>;
+export async function promiseDelay(ms = 0, ctrl?: AbortController) {
+  return new Promise<void>((resolve) => {
+    const t = setTimeout(resolve, ms);
+
+    if (ctrl) {
+      ctrl.signal.addEventListener('abort', () => {
+        clearTimeout(t);
+        resolve();
+      });
+    }
+  });
+}
+
 /**
  * 使 Promise 在指定时间内执行，超时则拒绝
  * @param promise - 要执行的 Promise
@@ -18,14 +35,38 @@ export declare function promiseDelay(ms?: number, ctrl?: AbortController): Promi
  * @returns 如果 Promise 在指定时间内解决，则返回其结果；否则抛出 "timeout" 错误
  * @throws {Error} 如果 Promise 超时，抛出 "timeout" 错误
  */
-export declare function promiseTimeout<T>(promise: Promise<T>, ms: number): Promise<T>;
+export async function promiseTimeout<T>(promise: Promise<T>, ms: number) {
+  const ctrl = new AbortController();
+  const result = await Promise.race([
+    promise,
+    promiseDelay(ms, ctrl).then(() => {
+      throw new Error('timeout');
+    }),
+  ]);
+  ctrl.abort();
+  return result;
+}
+
 /**
  * 在指定条件满足时解决 Promise
  * @param condition - 一个返回布尔值的函数，用于检查条件是否满足
  * @param ms - 检查条件的时间间隔（毫秒），默认为 10
  * @returns 一个 Promise，在条件满足时解决
  */
-export declare function promiseWhen(condition: () => boolean, ms?: number): Promise<void>;
+export function promiseWhen(condition: () => boolean, ms = 10) {
+  return new Promise<void>((resolve, reject) => {
+    const check = () => {
+      if (condition()) {
+        resolve();
+      } else {
+        setTimeout(check, ms);
+      }
+    };
+
+    check();
+  });
+}
+
 /**
  * 创建一个与给定 Promise 共享状态的新 Promise。
  * 新的 Promise 不具备 resolve 或 reject 的能力，它仅反映原始 Promise 的状态。
@@ -37,7 +78,12 @@ export declare function promiseWhen(condition: () => boolean, ms?: number): Prom
  * const sp2 = sharedPromise(p1);
  * // 此时 sp1、sp2 完全共享 p1 的状态，自身并不具备 resolve 或 reject 的能力
  */
-export declare function promiseShared<T>(promise: Promise<T>): Promise<T>;
+export function promiseShared<T>(promise: Promise<T>) {
+  return new Promise<T>((resolve, reject) => {
+    promise.then(resolve, reject);
+  });
+}
+
 /**
  * 创建一个最小等待时间的函数
  * @param {number} ms - 最小等待时间（毫秒）
@@ -47,4 +93,19 @@ export declare function promiseShared<T>(promise: Promise<T>): Promise<T>;
  * // 执行一些操作
  * await end(); // 确保从 createMinDelayPromise 调用到这里的总时间至少为 1000 毫秒
  */
-export declare function createMinDelayPromise(ms: number): () => Promise<void>;
+export function createMinDelayPromise(ms: number) {
+  const startTime = Date.now();
+  /**
+   * 确保最小等待时间的结束函数
+   * @async
+   * @function end
+   * @returns {Promise<void>} 在达到最小等待时间后解决
+   */
+  return async function end() {
+    const endTime = Date.now();
+    const waitTime = ms - (endTime - startTime);
+    if (waitTime > 0) {
+      await promiseDelay(waitTime);
+    }
+  };
+}

package/{dist/qs.d.ts → src/qs.ts}

@@ -1,4 +1,7 @@
-import { AnyObject } from './types';
+import { objectEach } from './object';
+import { isArray, isBoolean, isDate, isNull, isNullish, isNumber, isString, isUndefined } from './type';
+import type { AnyObject } from './types';
+
 /**
  * 查询字符串解析函数
  * @template T - 解析后返回的对象类型
@@ -14,6 +17,7 @@ import { AnyObject } from './types';
  * };
  */
 export type QSReader<T extends AnyObject> = (value: string, key: string, qsObject: T) => unknown;
+
 /**
  * 解析查询字符串为对象
  * @template T - 返回的对象类型
@@ -30,7 +34,30 @@ export type QSReader<T extends AnyObject> = (value: string, key: string, qsObjec
  * });
  * // { date: Date('2023-01-01') }
  */
-export declare function qsParse<T extends AnyObject>(queryString: string, parser?: QSReader<T>): T;
+export function qsParse<T extends AnyObject>(queryString: string, parser?: QSReader<T>): T {
+  // 添加 globalThis 是便于对接外部环境 URL 的自行实现
+  // 例如在 uni-app、微信小程序等运行环境。
+  const sp = new globalThis.URLSearchParams(queryString.replace(/^.*\?/, ''));
+  const qsObject = {} as T;
+
+  for (const [key, val] of sp.entries()) {
+    const valFinal = parser ? parser(val, key, qsObject) : val;
+
+    if (isNullish(valFinal)) continue;
+
+    if (Object.hasOwn(qsObject, key)) {
+      // @ts-expect-error
+      if (!isArray(qsObject[key])) qsObject[key] = [qsObject[key]];
+      (qsObject[key] as unknown[]).push(val);
+    } else {
+      // @ts-expect-error
+      qsObject[key] = valFinal;
+    }
+  }
+
+  return qsObject;
+}
+
 /**
  * 查询字符串序列化函数
  * @template T - 要序列化的对象类型
@@ -46,6 +73,14 @@ export declare function qsParse<T extends AnyObject>(queryString: string, parser
  * };
  */
 export type QSWriter<T extends AnyObject = AnyObject> = (value: unknown, key: string, query: T) => string | null;
+const defaultWriter: QSWriter<AnyObject> = (val: unknown) => {
+  if (isString(val)) return val;
+  if (isNumber(val)) return String(val);
+  if (isBoolean(val)) return val ? 'true' : 'false';
+  if (isDate(val)) return val.toISOString();
+  return null;
+};
+
 /**
  * 将对象序列化为查询字符串
  * @template T - 要序列化的对象类型
@@ -59,4 +94,26 @@ export type QSWriter<T extends AnyObject = AnyObject> = (value: unknown, key: st
  * const str2 = qsStringify({ date: new Date('2023-01-01') });
  * // 'date=2023-01-01T00:00:00.000Z'
  */
-export declare function qsStringify<T extends AnyObject>(qsObject: T, stringify?: QSWriter<T>): string;
+export function qsStringify<T extends AnyObject>(qsObject: T, stringify: QSWriter<T> = defaultWriter): string {
+  // 添加 globalThis 是便于对接外部环境 URL 的自行实现
+  // 例如在 uni-app、微信小程序等运行环境。
+  const sp = new globalThis.URLSearchParams();
+  const pushPairs = (val: unknown, key: string) => {
+    const valFinal = stringify(val, String(key), qsObject);
+    if (isNullish(valFinal)) return;
+
+    sp.append(key, valFinal);
+  };
+
+  objectEach(qsObject, (val, key: string) => {
+    if (isArray(val)) {
+      for (const it of val) {
+        pushPairs(it, key);
+      }
+    } else {
+      pushPairs(val, key);
+    }
+  });
+
+  return sp.toString();
+}