utils

这是一个独立的工具函数模块，与大文件上传功能没有耦合。该模块主要封装了一些常用的通用函数，如文件哈希值生成等实用方法，用于提高代码的复用性和可维护性

使用方式

import { utils } from "enlarge-file-upload";
const { computeFileHashDirect } = utils;

ts 类型

declare namespace utils {
  /**
   * @description
   * 使用单线程（主线程）以增量方式读取文件并计算 SHA256 哈希值。
   * 适用于中大型文件场景，逻辑简单且稳定。
   *
   * @param file - 要计算哈希的文件对象
   *
   * @param options - 可选配置项
   * @param options.chunkSize - 每次读取的文件分片大小（默认 5MB）
   * @param options.callback - 进度回调函数，回调参数包含当前百分比
   *
   * @callback options.callback
   * @param options.callback.params - 回调参数对象
   * @param options.callback.params.percentage - 当前进度百分比（字符串，如 "25.18"）
   *
   * @returns 返回 Promise，resolve 为最终 SHA256 哈希字符串
   */
  function computeFileHashDirect(
    file: File,
    options?: {
      chunkSize?: number;
      callback?: (params: { percentage: string }) => void;
    }
  ): Promise<string>;

  /**
   * @description
   * 使用多线程（Web Workers）并行读取文件分片，并在主线程按顺序计算文件的 SHA256 哈希值。
   * 适用于超大文件场景，加速读取阶段的性能。
   *
   * @param file - 要计算哈希值的文件对象
   *
   * @param options - 可选配置项
   * @param options.chunkSize - 每个文件分片的大小（默认 5MB）
   * @param options.workerCount - 启动的 Web Worker 数量，默认根据 CPU 核心数决定
   * @param options.callback - 回调函数，可用于获取进度信息
   *
   * @callback options.callback
   * @param options.callback.params - 回调参数对象
   * @param options.callback.params.currentWorker - 当前已完成读取的 worker 数量
   * @param options.callback.params.totalWorker - worker 总数
   * @param options.callback.params.percentage - 当前进度百分比（字符串形式，如 "25.00"）
   * @param options.callback.params.stage - 当前阶段："reading"（正在读取）或 "hashing"（正在计算哈希）
   *
   * @returns 返回 Promise，resolve 为最终的 SHA256 哈希字符串
   */
  function computeFileHashParallel(
    file: File,
    options?: {
      chunkSize?: number;
      workerCount?: number;
      callback?: (params: {
        currentWorker: number;
        totalWorker: number;
        percentage: string;
        stage: "reading" | "hashing";
      }) => void;
    }
  ): Promise<string>;
}

函数使用方式

computeFileHashDirect （2.3.10+）

使用单线程（主线程）以增量方式读取文件并计算 SHA256 哈希值

const { computeFileHashDirect } = utils;

async function handleFileChange(event: Event) {
  const input = event.target as HTMLInputElement;
  const file = input.files?.[0];
  if (!file) return;

  console.log(`开始计算文件哈希：${file.name}`);

  try {
    const hash = await computeFileHashDirect(file, {
      chunkSize: 5 * 1024 * 1024, // 可省略，默认 5MB
      callback: ({ percentage }) => {
        console.log(`进度：${percentage}%`);
      },
    });
    console.log(`文件哈希计算完成：${hash}`);
  } catch (error) {
    console.error("计算文件哈希失败：", error);
  }
}

computeFileHashParallel （2.4.0+）

使用多线程（Web Workers）并行读取文件分片，并在主线程按顺序计算文件的 SHA256 哈希值

const { computeFileHashParallel } = utils;

async function handleFileChange(event: Event) {
  const input = event.target as HTMLInputElement;
  const file = input.files?.[0];
  if (!file) return;

  console.log("开始计算 hash（Parallel 多线程）...");

  try {
    const hash = await computeFileHashParallel(file, {
      chunkSize: 5 * 1024 * 1024, // 可省略
      workerCount: 4, // 可选，不写时自动使用 CPU 核心数
      callback: ({ currentWorker, totalWorker, percentage, stage }) => {
        console.log(
          `阶段：${stage} | 进度：${percentage}% | Worker ${currentWorker}/${totalWorker}`
        );
      },
    });
    console.log(`文件哈希计算完成：${hash}`);
  } catch (error) {
    console.error("计算文件哈希失败：", error);
  }
}