@cloudcome/utils-browser 1.1.0 → 1.1.1

package/src/dts/global.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @file global.d.ts
+ */
+
+/**
+ * package.json name
+ */
+declare const PKG_NAME: string;
+
+/**
+ * package.json version
+ */
+declare const PKG_VERSION: string;
+
+/**
+ * package.json description
+ */
+declare const PKG_DESCRIPTION: string;
+
+declare const IS_TEST: string;
+
+interface TEST_MOCK {
+  IS_BROWSER: boolean;
+  IS_NODE: boolean;
+}
+
+declare const TEST_MOCK: TEST_MOCK;

package/src/image.ts

@@ -0,0 +1,45 @@
+import { setStyle } from './dom';
+
+/**
+ * 加载图片并返回一个包含 HTMLImageElement 的 Promise
+ * @param {string} url - 图片的 URL 地址
+ * @returns {Promise<HTMLImageElement>} 返回一个包含 HTMLImageElement 的 Promise
+ * @example
+ * const img = await imageLoad('https://example.com/image.png');
+ * @throws {Error} 如果图片加载失败，抛出错误
+ */
+export async function imageLoad(url: string) {
+  return new Promise<HTMLImageElement>((resolve, reject) => {
+    const image = new Image();
+    const onFinish = (isError?: boolean) => {
+      image.onload = image.onerror = null;
+      document.body.removeChild(image);
+      isError ? reject(new Error('图片加载失败')) : resolve(image);
+    };
+    image.onload = () => onFinish();
+    image.onerror = () => onFinish(true);
+    image.crossOrigin = 'anonymous';
+    image.src = url;
+
+    // ios 拍照产生的图片，如果没有插入的 DOM 中获取到的图片尺寸是相反的
+    setStyle(image, {
+      visibility: 'hidden',
+      position: 'absolute',
+      top: '-99999%',
+      left: '-99999%',
+      maxWidth: 'none',
+      maxHeight: 'none',
+      border: '0',
+      width: 'auto',
+      height: 'auto',
+      margin: '0',
+      padding: '0',
+      transform: '',
+    });
+    document.body.appendChild(image);
+
+    if (image.complete && image.width > 0) onFinish();
+  });
+}
+
+// 图片缩放函数

package/src/index.ts

@@ -0,0 +1 @@
+export const VERSION = PKG_VERSION;

package/src/timer.ts

@@ -0,0 +1,56 @@
+import { type TTimerHandler, type TTimerOptions, type TTimerState, makeInterval } from '@cloudcome/utils-core/timer';
+
+/**
+ * 创建一个基于 `requestAnimationFrame` 的间隔定时器
+ *
+ * @param callback - 每次间隔执行的回调函数，接收定时器状态和可选的 `next` 函数
+ * @param options - 配置选项
+ * @returns {TTimerHandler} 返回包含控制方法的对象
+ */
+export function frameInterval(
+  callback: (state: TTimerState, next?: () => void) => unknown,
+  options?: TTimerOptions,
+): TTimerHandler {
+  let rafId: number;
+  const { canStart, start, canStop, stop, canPause, pause, canResume, resume, execute } = makeInterval((call) => {
+    rafId = requestAnimationFrame(call);
+  }, callback);
+
+  return {
+    start() {
+      if (!canStart()) return;
+
+      if (options?.leading) {
+        start();
+      } else {
+        rafId = requestAnimationFrame(start);
+      }
+    },
+
+    stop() {
+      if (!canStop()) return;
+      if (options?.trailing) execute();
+
+      cancelAnimationFrame(rafId);
+      stop();
+    },
+
+    pause() {
+      if (!canPause()) return;
+      if (options?.trailing) execute();
+
+      cancelAnimationFrame(rafId);
+      pause();
+    },
+
+    resume(immediate?: boolean) {
+      if (!canResume()) return;
+
+      if (immediate || options?.leading) {
+        resume();
+      } else {
+        rafId = requestAnimationFrame(resume);
+      }
+    },
+  };
+}

package/src/video.ts

@@ -0,0 +1,19 @@
+/**
+ * 加载视频并返回一个包含 HTMLVideoElement 的 Promise
+ * @param {string} url - 视频的 URL 地址
+ * @returns {Promise<HTMLVideoElement>} 返回一个包含 HTMLVideoElement 的 Promise
+ * @example
+ * const video = await videoLoad('https://example.com/video.mp4');
+ * @throws {Error} 如果视频加载失败，抛出错误
+ */
+export async function videoLoad(url: string) {
+  return new Promise<HTMLVideoElement>((resolve, reject) => {
+    const video = document.createElement('video');
+
+    video.src = url;
+    video.crossOrigin = 'anonymous';
+    video.currentTime = 1;
+    video.onloadedmetadata = () => resolve(video);
+    video.onerror = () => reject(new Error('视频加载失败'));
+  });
+}

package/test/base64.test.ts

@@ -0,0 +1,47 @@
+import { decodeBase64, encodeBase64 } from '@/base64';
+import { describe, expect, it } from 'vitest';
+
+describe('encodeBase64', () => {
+  it('应正确编码空字符串', () => {
+    expect(encodeBase64('')).toBe('');
+  });
+
+  it('应正确编码普通字符串', () => {
+    expect(encodeBase64('hello')).toBe('aGVsbG8=');
+  });
+
+  it('应正确编码特殊字符', () => {
+    expect(encodeBase64('!@#$%^&*()')).toBe('IUAjJCVeJiooKQ==');
+  });
+
+  it('应正确编码中文字符', () => {
+    expect(encodeBase64('你好')).toBe('5L2g5aW9');
+  });
+});
+
+describe('decodeBase64', () => {
+  it('应正确解码空字符串', () => {
+    expect(decodeBase64('')).toBe('');
+  });
+
+  it('应正确解码普通字符串', () => {
+    expect(decodeBase64('aGVsbG8=')).toBe('hello');
+  });
+
+  it('应正确解码特殊字符', () => {
+    expect(decodeBase64('IUAjJCVeJiooKQ==')).toBe('!@#$%^&*()');
+  });
+
+  it('应正确解码中文字符', () => {
+    expect(decodeBase64('5L2g5aW9')).toBe('你好');
+  });
+});
+
+describe('encode/decode 互操作', () => {
+  it('应能正确编码并解码回原始字符串', () => {
+    const original = 'Hello, 世界!';
+    const encoded = encodeBase64(original);
+    const decoded = decodeBase64(encoded);
+    expect(decoded).toBe(original);
+  });
+});

package/test/cache.test.ts

@@ -0,0 +1,199 @@
+import { type Mock, afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { StorageCache, createLocalCache, createSessionCache } from '../src/cache';
+
+describe('StorageCache', () => {
+  let storage: Storage;
+  let cache: StorageCache<string>;
+
+  beforeEach(() => {
+    storage = {
+      getItem: vi.fn(),
+      setItem: vi.fn(),
+      removeItem: vi.fn(),
+      clear: vi.fn(),
+      length: 0,
+      key: vi.fn(),
+    } as unknown as Storage;
+    cache = new StorageCache(storage);
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('constructor', () => {
+    it('应该正确初始化实例', () => {
+      expect(cache).toBeInstanceOf(StorageCache);
+      expect(cache.storage).toBe(storage);
+      expect(cache.namespace).toBe('');
+    });
+
+    it('应该支持命名空间', () => {
+      const cacheWithNamespace = new StorageCache(storage, 'test');
+      expect(cacheWithNamespace.namespace).toBe('test');
+    });
+  });
+
+  describe('get()', () => {
+    it('应该返回null当缓存不存在时', () => {
+      (storage.getItem as Mock).mockReturnValue(null);
+      expect(cache.get('key')).toBeNull();
+      expect(storage.getItem).toBeCalledWith('key');
+    });
+
+    it('应该返回null当缓存过期时', () => {
+      const expiredCache = JSON.stringify({
+        id: 'key',
+        data: 'value',
+        createdAt: Date.now() - 10000,
+        maxAge: 5000,
+      });
+      (storage.getItem as Mock).mockReturnValue(expiredCache);
+      expect(cache.get('key')).toBeNull();
+      expect(storage.removeItem).toBeCalledWith('key');
+    });
+
+    it('应该返回缓存数据当缓存有效时', () => {
+      const validCache = JSON.stringify({
+        id: 'key',
+        data: 'value',
+        createdAt: Date.now(),
+        maxAge: 5000,
+      });
+      (storage.getItem as Mock).mockReturnValue(validCache);
+      const result = cache.get('key');
+      expect(result?.data).toBe('value');
+    });
+
+    it('应该返回null当缓存数据解析失败时', () => {
+      (storage.getItem as Mock).mockReturnValue('invalid json');
+      expect(cache.get('key')).toBeNull();
+    });
+  });
+
+  describe('set()', () => {
+    it('应该成功设置缓存', () => {
+      cache.set('key', 'value');
+      expect(storage.setItem).toBeCalled();
+    });
+
+    it('应该支持设置缓存过期时间', () => {
+      cache.set('key', 'value', { maxAge: 1000 });
+      const [, value] = (storage.setItem as Mock).mock.calls[0];
+      const cacheData = JSON.parse(value);
+      expect(cacheData.maxAge).toBe(1000);
+    });
+  });
+
+  describe('del()', () => {
+    it('应该成功删除缓存', () => {
+      cache.del('key');
+      expect(storage.removeItem).toBeCalledWith('key');
+    });
+
+    it('应该处理删除缓存失败的情况', () => {
+      (storage.removeItem as Mock).mockImplementation(() => {
+        throw new Error('Remove failed');
+      });
+      expect(() => cache.del('key')).not.toThrow();
+    });
+  });
+
+  describe('命名空间', () => {
+    it('应该在键前添加命名空间', () => {
+      const cacheWithNamespace = new StorageCache(storage, 'test');
+      cacheWithNamespace.set('key', 'value');
+      expect(storage.setItem).toBeCalledWith('test:key', expect.anything());
+    });
+
+    it('应该在获取缓存时使用命名空间', () => {
+      const cacheWithNamespace = new StorageCache(storage, 'test');
+      cacheWithNamespace.get('key');
+      expect(storage.getItem).toBeCalledWith('test:key');
+    });
+
+    it('应该在删除缓存时使用命名空间', () => {
+      const cacheWithNamespace = new StorageCache(storage, 'test');
+      cacheWithNamespace.del('key');
+      expect(storage.removeItem).toBeCalledWith('test:key');
+    });
+  });
+
+  describe('clear()', () => {
+    it('应该清空所有缓存', () => {
+      cache.clear();
+      expect(storage.clear).toBeCalled();
+    });
+
+    it('应该处理清空缓存失败的情况', () => {
+      (storage.clear as Mock).mockImplementation(() => {
+        throw new Error('Clear failed');
+      });
+      expect(() => cache.clear()).not.toThrow();
+    });
+  });
+
+  describe('缓存数据格式', () => {
+    it('应该正确序列化缓存数据', () => {
+      cache.set('key', 'value');
+      const [, value] = (storage.setItem as Mock).mock.calls[0];
+      const cacheData = JSON.parse(value);
+      expect(cacheData).toEqual({
+        id: 'key',
+        data: 'value',
+        createdAt: expect.any(Number),
+        maxAge: 0,
+      });
+    });
+
+    it('应该正确处理非字符串数据', () => {
+      const objCache = new StorageCache<object>(storage);
+      objCache.set('key', { foo: 'bar' });
+      const [, value] = (storage.setItem as Mock).mock.calls[0];
+      const cacheData = JSON.parse(value);
+      expect(cacheData.data).toEqual({ foo: 'bar' });
+    });
+  });
+
+  describe('存储失败', () => {
+    it('应该处理getItem失败的情况', () => {
+      (storage.getItem as Mock).mockImplementation(() => {
+        throw new Error('Get failed');
+      });
+      expect(() => cache.get('key')).not.toThrow();
+    });
+
+    it('应该处理setItem失败的情况', () => {
+      (storage.setItem as Mock).mockImplementation(() => {
+        throw new Error('Set failed');
+      });
+      expect(() => cache.set('key', 'value')).not.toThrow();
+    });
+  });
+});
+
+describe('createLocalCache', () => {
+  it('应该创建使用localStorage的缓存实例', () => {
+    const cache = createLocalCache<string>() as StorageCache<string>;
+    expect(cache).toBeInstanceOf(StorageCache);
+    expect(cache.storage).toBe(localStorage);
+  });
+
+  it('应该支持命名空间', () => {
+    const cache = createLocalCache<string>('test') as StorageCache<string>;
+    expect(cache.namespace).toBe('test');
+  });
+});
+
+describe('createSessionCache', () => {
+  it('应该创建使用sessionStorage的缓存实例', () => {
+    const cache = createSessionCache<string>() as StorageCache<string>;
+    expect(cache).toBeInstanceOf(StorageCache);
+    expect(cache.storage).toBe(sessionStorage);
+  });
+
+  it('应该支持命名空间', () => {
+    const cache = createSessionCache<string>('test') as StorageCache<string>;
+    expect(cache.namespace).toBe('test');
+  });
+});

package/test/canvas.test.ts

@@ -0,0 +1,124 @@
+import { canvasDrawImage, canvasToBase64, canvasToBlob } from '@/canvas';
+import { imageLoad } from '@/image';
+import { loadImage } from 'canvas';
+import { describe, expect, it, vi } from 'vitest';
+
+describe('canvasToBase64', () => {
+  it('应返回默认 png 格式的 base64 字符串', () => {
+    const canvas = document.createElement('canvas');
+    canvas.width = 100;
+    canvas.height = 100;
+
+    const result = canvasToBase64(canvas);
+    expect(result).toMatch(/^data:image\/png;base64,/);
+  });
+
+  it('应返回指定格式和质量的 base64 字符串', () => {
+    const canvas = document.createElement('canvas');
+    canvas.width = 100;
+    canvas.height = 100;
+
+    const result = canvasToBase64(canvas, 'image/jpeg', 0.8);
+    expect(result).toMatch(/^data:image\/jpeg;base64,/);
+  });
+});
+
+describe('canvasToBlob', () => {
+  it('应返回默认 png 格式的 Blob 对象', async () => {
+    const canvas = document.createElement('canvas');
+    canvas.width = 100;
+    canvas.height = 100;
+
+    const blob = await canvasToBlob(canvas);
+    expect(blob).toBeInstanceOf(Blob);
+    expect(blob.type).toBe('image/png');
+  });
+
+  it('应返回指定格式和质量的 Blob 对象', async () => {
+    const canvas = document.createElement('canvas');
+    canvas.width = 100;
+    canvas.height = 100;
+
+    const blob = await canvasToBlob(canvas, 'image/jpeg', 0.9);
+    expect(blob).toBeInstanceOf(Blob);
+    expect(blob.type).toBe('image/jpeg');
+  });
+
+  it('当 canvas toBlob 失败时应拒绝', async () => {
+    const canvas = document.createElement('canvas');
+    vi.spyOn(canvas, 'toBlob').mockImplementationOnce((callback) => callback(null));
+
+    await expect(canvasToBlob(canvas)).rejects.toThrow('canvas 导出二进制对象失败');
+  });
+});
+
+describe('canvasDrawImage', () => {
+  it(
+    '应使用默认选项绘制图像',
+    async () => {
+      const canvas = document.createElement('canvas');
+      canvas.width = 200;
+      canvas.height = 200;
+      const ctx = canvas.getContext('2d');
+      if (!ctx) throw new Error('Canvas context is null');
+
+      const spy = vi.spyOn(ctx, 'drawImage').mockImplementation(() => true);
+      const src = 'https://www.baidu.com/img/PCfb_5bf082d29588c07f842ccde3f97243ea.png';
+      const img = await imageLoad(src);
+
+      await canvasDrawImage(canvas, img.src);
+      expect(spy).toHaveBeenCalledWith(img, 0, 0, img.width, img.height, 0, 0, canvas.width, canvas.height);
+    },
+    { timeout: 0 },
+  );
+
+  it(
+    '应使用自定义选项绘制图像',
+    async () => {
+      const canvas = document.createElement('canvas');
+      canvas.width = 200;
+      canvas.height = 200;
+      const ctx = canvas.getContext('2d');
+      if (!ctx) throw new Error('Canvas context is null');
+
+      const spy = vi.spyOn(ctx, 'drawImage').mockImplementation(() => true);
+      const src = 'https://www.baidu.com/img/PCfb_5bf082d29588c07f842ccde3f97243ea.png';
+      const img = await imageLoad(src);
+
+      const options = {
+        srcLeft: 10,
+        srcTop: 10,
+        srcWidth: 50,
+        srcHeight: 50,
+        destLeft: 20,
+        destTop: 20,
+        destWidth: 100,
+        destHeight: 100,
+      };
+      await canvasDrawImage(canvas, img.src, options);
+      expect(spy).toHaveBeenCalledWith(
+        img,
+        options.srcLeft,
+        options.srcTop,
+        options.srcWidth,
+        options.srcHeight,
+        options.destLeft,
+        options.destTop,
+        options.destWidth,
+        options.destHeight,
+      );
+    },
+    { timeout: 0 },
+  );
+
+  it(
+    '当 canvas context 为 null 时应抛出错误',
+    async () => {
+      const canvas = document.createElement('canvas');
+      vi.spyOn(canvas, 'getContext').mockReturnValueOnce(null);
+
+      await expect(canvasDrawImage(canvas, 'https://example.com/image.png')).rejects.toThrow('canvas context is null');
+    },
+    { timeout: 0 },
+  );
+});

package/test/clipboard.test.ts

@@ -0,0 +1,18 @@
+import { copyText } from '@/clipboard';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+describe('copyText', () => {
+  beforeEach(() => {
+    vi.resetAllMocks();
+    document.body.innerHTML = '';
+  });
+
+  it('应在复制后移除 textarea 元素', () => {
+    const execCommandMock = vi.fn();
+    document.execCommand = execCommandMock;
+
+    copyText('test text');
+
+    expect(document.body.querySelector('textarea')).toBeNull();
+  });
+});

package/test/cookie.test.ts

@@ -0,0 +1,52 @@
+import { cookieDel, cookieGet, cookieSet } from '@/cookie';
+import { beforeEach, describe, expect, it } from 'vitest';
+
+describe('Cookie 工具函数', () => {
+  beforeEach(() => {
+    // 清空所有 Cookie
+    for (const cookie of document.cookie.split(';')) {
+      const eqPos = cookie.indexOf('=');
+      const name = eqPos > -1 ? cookie.slice(0, eqPos) : cookie;
+      document.cookie = `${name}=;expires=Thu, 01 Jan 1970 00:00:00 GMT`;
+    }
+  });
+
+  describe('cookieGet', () => {
+    it('应返回已存在 cookie 的值', () => {
+      document.cookie = 'testKey=testValue';
+      expect(cookieGet('testKey')).toBe('testValue');
+    });
+
+    it('对于不存在的 cookie 应返回空字符串', () => {
+      expect(cookieGet('nonExistingKey')).toBe('');
+    });
+  });
+
+  describe('cookieSet', () => {
+    it('应使用默认选项设置 cookie', () => {
+      cookieSet('defaultKey', 'defaultValue');
+      expect(document.cookie).toContain('defaultKey=defaultValue');
+    });
+
+    it('应使用自定义选项设置 cookie', () => {
+      cookieSet('customKey', 'customValue', {
+        expires: new Date('2030-01-01'),
+        path: '/',
+        domain: location.host,
+        secure: true,
+        sameSite: 'none',
+        httpOnly: false,
+        maxAge: 3600,
+      });
+      expect(document.cookie).toEqual('');
+    });
+  });
+
+  describe('cookieDel', () => {
+    it('应通过设置过期时间为过去来删除 cookie', () => {
+      document.cookie = 'deleteKey=deleteValue';
+      cookieDel('deleteKey');
+      expect(document.cookie).not.toContain('deleteKey=deleteValue');
+    });
+  });
+});

package/test/dom.test.ts

@@ -0,0 +1,67 @@
+import { getStyle, setStyle } from '@/dom';
+import { describe, expect, it, vi } from 'vitest';
+
+describe('setStyle', () => {
+  it('应该能够通过字符串设置样式', () => {
+    const el = document.createElement('div');
+    setStyle(el, 'color: red; background: blue;');
+
+    expect(el.style.color).toBe('red');
+    expect(el.style.background).toBe('blue');
+  });
+
+  it('应该能够通过对象设置样式', () => {
+    const el = document.createElement('div');
+    setStyle(el, { color: 'red', width: '16px' });
+
+    expect(el.style.color).toBe('red');
+    expect(el.style.width).toBe('16px');
+  });
+
+  it('应该能够设置自定义属性', () => {
+    const el = document.createElement('div');
+    setStyle(el, { '--custom-property': 'value' });
+
+    expect(el.style.getPropertyValue('--custom-property')).toBe('value');
+  });
+
+  it('使用字符串设置样式时应覆盖现有样式', () => {
+    const el = document.createElement('div');
+    el.style.color = 'green';
+    setStyle(el, 'color: red;');
+
+    expect(el.style.color).toBe('red');
+  });
+
+  it('使用对象设置样式时应合并样式', () => {
+    const el = document.createElement('div');
+    el.style.color = 'green';
+    setStyle(el, { width: '100px' });
+
+    expect(el.style.color).toBe('green');
+    expect(el.style.width).toBe('100px');
+  });
+});
+
+describe('getStyle', () => {
+  it('应该能够获取计算样式', () => {
+    const el = document.createElement('div');
+    el.style.color = 'red';
+
+    vi.spyOn(window, 'getComputedStyle').mockReturnValue({
+      getPropertyValue: (prop: string) => (prop === 'color' ? 'red' : ''),
+    } as CSSStyleDeclaration);
+
+    expect(getStyle(el, 'color')).toBe('red');
+  });
+
+  it('对于不存在的属性应返回空字符串', () => {
+    const el = document.createElement('div');
+
+    const mockStyle = new CSSStyleDeclaration();
+    vi.spyOn(mockStyle, 'getPropertyValue').mockReturnValue('');
+    vi.spyOn(window, 'getComputedStyle').mockReturnValue(mockStyle);
+
+    expect(getStyle(el, 'color')).toBe('');
+  });
+});

package/test/download.test.ts

@@ -0,0 +1,15 @@
+import { downloadBlob, downloadURL } from '@/download';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+it('download', () => {
+  downloadURL('/');
+  downloadURL('/', 'file');
+
+  URL.createObjectURL = vi.fn(() => '/');
+  URL.revokeObjectURL = vi.fn();
+
+  downloadBlob(new Blob());
+  downloadBlob(new Blob(), 'file');
+
+  expect(URL.createObjectURL).toBeTypeOf('function');
+});