@cloudcome/utils-core 1.1.0 → 1.1.1

package/test/enum.test.ts

@@ -0,0 +1,113 @@
+import { describe, expect, it } from 'vitest';
+import { declareEnum } from '../src/enum';
+
+describe('枚举定义测试', () => {
+  it('编译时测试', () => {
+    const Status = declareEnum<{ label: string; level: number }>().define({
+      Pending: { value: 0, label: '待处理', level: 11 },
+      Approved: { value: 1, label: '已批准', level: 22 },
+    });
+
+    assertType<0>(Status.Pending);
+    assertType<1>(Status.Approved);
+
+    assertType<{ key: 'Pending'; readonly value: 0; readonly label: '待处理'; level: 11 }>(Status.$Pending);
+    assertType<{ key: 'Approved'; readonly value: 1; readonly label: '已批准'; level: 22 }>(Status.$Approved);
+
+    assertType<{
+      Pending: { readonly value: 0; readonly label: '待处理'; level: 11 };
+      Approved: { readonly value: 1; readonly label: '已批准'; level: 22 };
+    }>(Status.definition);
+    assertType<{ label: string; key: 'Pending' | 'Approved' }[]>(Status.descriptions);
+
+    assertType<['Pending', 'Approved']>(Status.keys);
+    assertType<2>(Status.length);
+    assertType<[0, 1]>(Status.values);
+
+    assertType<{
+      readonly Pending: 0;
+      readonly Approved: 1;
+    }>(Status.kvRecord);
+    assertType<{
+      readonly 0: 'Pending';
+      readonly 1: 'Approved';
+    }>(Status.vkRecord);
+
+    const klr = Status.toKeyRecord('label');
+    assertType<Record<'Pending' | 'Approved', string>>(klr);
+    const vlr = Status.toValueRecord('level');
+    assertType<Record<0 | 1, number>>(vlr);
+  });
+
+  it('运行时测试', () => {
+    const Status = declareEnum<{ label: string; level: number }>().define({
+      Pending: { value: 0, label: '待处理', level: 11 },
+      Approved: { value: 1, label: '已批准', level: 22 },
+    });
+
+    expect(Status.Pending).toBe(0);
+    expect(Status.Approved).toBe(1);
+
+    expect(Status.$Pending.value).toBe(0);
+    expect(Status.$Approved.value).toBe(1);
+
+    expect(Status.$Pending.key).toBe('Pending');
+    expect(Status.$Approved.key).toBe('Approved');
+
+    expect(Status.$Pending.label).toBe('待处理');
+    expect(Status.$Pending.level).toBe(11);
+    expect(Status.$Approved.label).toBe('已批准');
+    expect(Status.$Approved.level).toBe(22);
+
+    expect(Status.keys).toEqual(['Pending', 'Approved']);
+    expect(Status.values).toEqual([0, 1]);
+    expect(Status.length).toEqual(2);
+
+    expect(Status.definition).toEqual({
+      Pending: { value: 0, label: '待处理', level: 11 },
+      Approved: { value: 1, label: '已批准', level: 22 },
+    });
+    expect(Status.descriptions).toEqual([
+      { key: 'Pending', value: 0, label: '待处理', level: 11 },
+      { key: 'Approved', value: 1, label: '已批准', level: 22 },
+    ]);
+
+    expect(Status.kvRecord).toEqual({
+      Pending: 0,
+      Approved: 1,
+    });
+    expect(Status.vkRecord).toEqual({
+      0: 'Pending',
+      1: 'Approved',
+    });
+
+    expect(Status.toKeyRecord('label')).toEqual({
+      Pending: '待处理',
+      Approved: '已批准',
+    });
+    expect(Status.toValueRecord('level')).toEqual({
+      0: 11,
+      1: 22,
+    });
+  });
+
+  it('枚举键名大写开头', () => {
+    // 测试小写键名应该报错
+    expect(() => {
+      declareEnum().define({
+        // @ts-expect-error 错误：枚举键名 active 必须以大写字母开头
+        active: { value: 1 },
+      });
+    }).toThrowError('错误：枚举键名 active 必须以大写字母开头');
+  });
+
+  it('枚举键名非 $ 开头', () => {
+    // 测试小写键名应该报错
+    expect(() => {
+      declareEnum().define({
+        // @ts-expect-error 错误：枚举键名 $active 不能以 $ 符号开头
+        $active: { value: 1 },
+      });
+    }).toThrowError('错误：枚举键名 $active 不能以 $ 符号开头');
+  });
+});

package/test/env.test.ts

@@ -0,0 +1,69 @@
+import { isBrowser, isLinux, isMacOS, isNode, isWindows, isWorker } from '@/env';
+import { beforeAll, beforeEach, describe, expect, it } from 'vitest';
+
+beforeAll(() => {
+  // @ts-ignore
+  global.TEST_MOCK = {
+    IS_BROWSER: false,
+    IS_NODE: false,
+  };
+});
+
+beforeEach(() => {
+  TEST_MOCK.IS_NODE = false;
+  TEST_MOCK.IS_NODE = false;
+});
+
+it('env', () => {
+  expect(isBrowser()).toBe(false);
+  expect(isNode()).toBe(false);
+  expect(isWorker()).toBe(false);
+});
+
+describe('isMacOS', () => {
+  it('应在 macOS 浏览器环境中返回 true', () => {
+    TEST_MOCK.IS_BROWSER = true;
+    // @ts-ignore
+    global.navigator = { platform: 'MacIntel' };
+    expect(isMacOS()).toBe(true);
+  });
+
+  it('应在 macOS Node.js 环境中返回 true', () => {
+    TEST_MOCK.IS_NODE = true;
+    // @ts-ignore
+    global.process = { platform: 'darwin' };
+    expect(isMacOS()).toBe(true);
+  });
+});
+
+describe('isLinux', () => {
+  it('应在 Linux 浏览器环境中返回 true', () => {
+    TEST_MOCK.IS_BROWSER = true;
+    // @ts-ignore
+    global.navigator = { platform: 'Linux x86_64' };
+    expect(isLinux()).toBe(true);
+  });
+
+  it('应在 Linux Node.js 环境中返回 true', () => {
+    TEST_MOCK.IS_NODE = true;
+    // @ts-ignore
+    global.process = { platform: 'linux' };
+    expect(isLinux()).toBe(true);
+  });
+});
+
+describe('isWindows', () => {
+  it('应在 Windows 浏览器环境中返回 true', () => {
+    TEST_MOCK.IS_BROWSER = true;
+    // @ts-ignore
+    global.navigator = { platform: 'Win32' };
+    expect(isWindows()).toBe(true);
+  });
+
+  it('应在 Windows Node.js 环境中返回 true', () => {
+    TEST_MOCK.IS_NODE = true;
+    // @ts-ignore
+    global.process = { platform: 'win32' };
+    expect(isWindows()).toBe(true);
+  });
+});

package/test/error.test.ts

@@ -0,0 +1,58 @@
+import { errorAssign, errorNormalize } from '@/error';
+import { isError } from '@/type';
+
+function shouldBeString(input: string) {
+  return true;
+}
+
+function shouldOptionalString(input?: string) {
+  return true;
+}
+
+function shouldBeUnknown(input: unknown) {
+  return true;
+}
+
+test('errorNormalize', () => {
+  const err1 = errorNormalize('abc');
+  expect(isError(err1)).toBe(true);
+
+  const err2 = errorNormalize(new Error('abc'));
+  expect(isError(err2)).toBe(true);
+
+  const err3 = new Error('abc');
+  expect(errorNormalize(err3)).toBe(err3);
+
+  let err4 = null;
+  try {
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-ignore
+    1();
+  } catch (cause) {
+    err4 = errorNormalize(cause);
+  }
+
+  if (err4) {
+    shouldBeString(err4.name);
+    shouldBeString(err4.message);
+    shouldOptionalString(err4.stack);
+    shouldBeUnknown(err4.cause);
+  }
+
+  expect(isError(err4)).toBe(true);
+
+  const err5 = errorNormalize(errorAssign(new Error(), { aaa: '' }));
+  shouldBeString(err5.name);
+  shouldBeString(err5.message);
+  shouldOptionalString(err5.stack);
+  shouldBeUnknown(err5.cause);
+  shouldBeString(err5.aaa);
+  expect(isError(err5)).toBe(true);
+});
+
+test('errorAssign', () => {
+  const data = { xyz: 1, abc: new Date() };
+  const error = errorAssign(new Error('abc'), data);
+  expect(error.xyz).toBe(data.xyz);
+  expect(error.abc).toBe(data.abc);
+});

package/test/exception.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from 'vitest';
+import { buildException } from '../src/exception';
+
+describe('异常构建工具', () => {
+  it('应该创建具有正确名称的自定义错误类', () => {
+    const TestError = buildException('TestError');
+    const error = new TestError('测试消息');
+
+    expect(error.name).toBe('TestError');
+    expect(error).toBeInstanceOf(Error);
+  });
+
+  it('应该使用默认格式格式化错误消息', () => {
+    const TestError = buildException('TestError');
+    const error = new TestError('测试消息');
+
+    expect(error.message).toBe('[TestError] 测试消息');
+  });
+
+  it('应该支持自定义消息格式', () => {
+    const customFormat = (name: string, message: string) => `${name}::${message}`;
+    const TestError = buildException('TestError', { format: customFormat });
+    const error = new TestError('测试消息');
+
+    expect(error.message).toBe('TestError::测试消息');
+  });
+
+  it('应该合并额外属性到错误实例', () => {
+    const TestError = buildException<{ code: number; details: string }>('TestError');
+    const error = new TestError('测试消息', { code: 404, details: '未找到' });
+
+    expect(error.code).toBe(404);
+    expect(error.details).toBe('未找到');
+  });
+
+  it('应该保留完整的堆栈跟踪', () => {
+    const TestError = buildException('TestError');
+    const error = new TestError('测试消息');
+
+    expect(error.stack).toBeDefined();
+    expect(error.stack).toContain('TestError: [TestError] 测试消息');
+  });
+});

package/test/fn.test.ts

@@ -0,0 +1,263 @@
+import { fnDebounce, fnOnce, fnThrottle } from '@/fn';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+beforeEach(() => {
+  vi.useFakeTimers();
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('fnDebounce', () => {
+  it('应正确防抖函数', async () => {
+    const mockFn = vi.fn();
+    const debouncedFn = fnDebounce(mockFn, 100);
+
+    debouncedFn();
+    debouncedFn();
+    debouncedFn();
+
+    setTimeout(() => {
+      expect(mockFn).toHaveBeenCalledTimes(1);
+    }, 150);
+
+    await vi.runAllTimersAsync();
+  });
+
+  it('应支持 leading 选项', async () => {
+    const mockFn = vi.fn();
+    const debouncedFn = fnDebounce(mockFn, { wait: 100, leading: true });
+
+    debouncedFn();
+    expect(mockFn).toHaveBeenCalledTimes(1);
+
+    debouncedFn();
+    debouncedFn();
+
+    setTimeout(() => {
+      expect(mockFn).toHaveBeenCalledTimes(2);
+    }, 150);
+
+    await vi.runAllTimersAsync();
+  });
+
+  it('应支持 cancel 方法', async () => {
+    const mockFn = vi.fn();
+    const debouncedFn = fnDebounce(mockFn, 100);
+
+    debouncedFn();
+    debouncedFn.cancel();
+
+    setTimeout(() => {
+      expect(mockFn).not.toHaveBeenCalled();
+    }, 150);
+
+    await vi.runAllTimersAsync();
+  });
+
+  it('应支持多次调用 cancel 方法', async () => {
+    const mockFn = vi.fn();
+    const debouncedFn = fnDebounce(mockFn, 100);
+
+    debouncedFn();
+    debouncedFn.cancel();
+    debouncedFn.cancel();
+
+    setTimeout(() => {
+      expect(mockFn).not.toHaveBeenCalled();
+    }, 150);
+
+    await vi.runAllTimersAsync();
+  });
+
+  it('应支持多次调用 debounced 函数', async () => {
+    const mockFn = vi.fn();
+    const debouncedFn = fnDebounce(mockFn, 100);
+
+    debouncedFn();
+    setTimeout(() => {
+      debouncedFn();
+    }, 50);
+    setTimeout(() => {
+      debouncedFn();
+    }, 100);
+    setTimeout(() => {
+      debouncedFn();
+    }, 150);
+    setTimeout(() => {
+      // 等待最后一次计时结束
+    }, 150);
+
+    await vi.runAllTimersAsync();
+    expect(mockFn).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('fnThrottle', () => {
+  it('应正确节流函数调用', async () => {
+    const mockFn = vi.fn();
+    const throttledFn = fnThrottle(mockFn, 100);
+
+    throttledFn();
+    throttledFn();
+    throttledFn();
+
+    setTimeout(() => {
+      throttledFn();
+      expect(mockFn).toHaveBeenCalledTimes(0);
+    }, 50);
+
+    setTimeout(() => {
+      throttledFn();
+      expect(mockFn).toHaveBeenCalledTimes(1);
+    }, 100);
+
+    setTimeout(() => {
+      throttledFn();
+      expect(mockFn).toHaveBeenCalledTimes(1);
+    }, 150);
+
+    setTimeout(() => {
+      throttledFn();
+      expect(mockFn).toHaveBeenCalledTimes(2);
+    }, 200);
+
+    await vi.runAllTimersAsync();
+    expect(mockFn).toHaveBeenCalledTimes(2);
+  });
+
+  it('应支持 leading 选项', async () => {
+    const mockFn = vi.fn();
+    const throttledFn = fnThrottle(mockFn, { wait: 100, leading: true });
+
+    throttledFn();
+    expect(mockFn).toHaveBeenCalledTimes(1);
+
+    throttledFn();
+    throttledFn();
+
+    setTimeout(() => {
+      throttledFn();
+      expect(mockFn).toHaveBeenCalledTimes(2);
+    }, 100);
+
+    await vi.runAllTimersAsync();
+    expect(mockFn).toHaveBeenCalledTimes(2);
+  });
+
+  it('应支持 trailing 选项', async () => {
+    const mockFn = vi.fn();
+    const throttledFn = fnThrottle(mockFn, { wait: 100, trailing: true });
+
+    throttledFn();
+    throttledFn();
+    throttledFn();
+
+    setTimeout(() => {
+      expect(mockFn).toHaveBeenCalledTimes(0);
+    }, 50);
+
+    setTimeout(() => {
+      expect(mockFn).toHaveBeenCalledTimes(1);
+    }, 100);
+
+    await vi.runAllTimersAsync();
+    expect(mockFn).toHaveBeenCalledTimes(1);
+  });
+
+  it('应支持 trailing 选项', async () => {
+    const mockFn = vi.fn();
+    const throttledFn = fnThrottle(mockFn, { wait: 100, trailing: true });
+
+    throttledFn();
+    throttledFn();
+    throttledFn();
+
+    setTimeout(() => {
+      expect(mockFn).toHaveBeenCalledTimes(0);
+    }, 50);
+
+    setTimeout(() => {
+      expect(mockFn).toHaveBeenCalledTimes(1);
+    }, 100);
+
+    await vi.runAllTimersAsync();
+    expect(mockFn).toHaveBeenCalledTimes(1);
+  });
+
+  it('应支持 leading + trailing 选项', async () => {
+    const mockFn = vi.fn();
+    const throttledFn = fnThrottle(mockFn, { wait: 100, leading: true, trailing: true });
+
+    throttledFn();
+    expect(mockFn).toHaveBeenCalledTimes(1);
+
+    throttledFn();
+    throttledFn();
+
+    setTimeout(() => {
+      expect(mockFn).toHaveBeenCalledTimes(1);
+    }, 50);
+
+    setTimeout(() => {
+      expect(mockFn).toHaveBeenCalledTimes(2);
+    }, 100);
+
+    await vi.runAllTimersAsync();
+    expect(mockFn).toHaveBeenCalledTimes(2);
+  });
+
+  it('应取消节流函数调用', async () => {
+    const mockFn = vi.fn();
+    const throttledFn = fnThrottle(mockFn, 100);
+
+    throttledFn();
+    throttledFn.cancel();
+
+    setTimeout(() => {
+      throttledFn();
+    }, 100);
+
+    await vi.runAllTimersAsync();
+    expect(mockFn).toHaveBeenCalledTimes(0);
+  });
+});
+
+describe('fnOnce', () => {
+  it('应确保函数只被调用一次', () => {
+    const mockFn = vi.fn();
+    const onceFn = fnOnce(mockFn);
+
+    onceFn();
+    onceFn();
+    onceFn();
+
+    expect(mockFn).toHaveBeenCalledTimes(1);
+  });
+
+  it('应支持多次调用，但只执行一次', () => {
+    const mockFn = vi.fn();
+    const onceFn = fnOnce(mockFn);
+
+    onceFn();
+    expect(mockFn).toHaveBeenCalledTimes(1);
+
+    onceFn();
+    expect(mockFn).toHaveBeenCalledTimes(1);
+
+    onceFn();
+    expect(mockFn).toHaveBeenCalledTimes(1);
+  });
+
+  it('应支持传递参数', () => {
+    const mockFn = vi.fn();
+    const onceFn = fnOnce(mockFn);
+
+    onceFn('arg1', 'arg2');
+    onceFn('arg3', 'arg4');
+
+    expect(mockFn).toHaveBeenCalledTimes(1);
+    expect(mockFn).toHaveBeenCalledWith('arg1', 'arg2');
+  });
+});

package/test/helpers.ts

@@ -0,0 +1,23 @@
+export function createAfn<T, R>(options: {
+  delay: number;
+  result?: T;
+  reason?: R;
+  onResolved?: (result: T) => void;
+  onRejected?: (reason: R) => void;
+  onFinally?: () => void;
+}) {
+  return () =>
+    new Promise((resolve, reject) => {
+      setTimeout(() => {
+        if (options.reason) {
+          options.onRejected?.(options.reason);
+          reject(options.reason);
+        } else {
+          options.onResolved?.(options.result as T);
+          resolve(options.result);
+        }
+
+        options.onFinally?.();
+      }, options.delay);
+    });
+}

package/test/index.test.ts

@@ -0,0 +1,6 @@
+import { VERSION } from '@/index';
+import { expect, it } from 'vitest';
+
+it('version', () => {
+  expect(VERSION).toEqual(PKG_VERSION);
+});