@giszhc/file-utils 0.0.1

package/dist/file-utils.js

@@ -0,0 +1,349 @@
+function p(e, t = "text") {
+  return new Promise((n, r) => {
+    const o = new FileReader();
+    switch (t) {
+      case "text":
+        o.readAsText(e);
+        break;
+      case "arrayBuffer":
+        o.readAsArrayBuffer(e);
+        break;
+      case "dataURL":
+        o.readAsDataURL(e);
+        break;
+      case "binaryString":
+        o.readAsBinaryString(e);
+        break;
+      default:
+        o.readAsText(e);
+    }
+    o.onload = (i) => {
+      const a = i.target?.result;
+      a !== void 0 ? n(a) : r(new Error("文件读取失败"));
+    }, o.onerror = () => {
+      r(new Error("文件读取错误"));
+    }, o.onabort = () => {
+      r(new Error("文件读取被中止"));
+    };
+  });
+}
+async function S(e, t = "utf-8") {
+  return new Promise((n, r) => {
+    const o = new FileReader();
+    o.readAsText(e, t), o.onload = (i) => {
+      const a = i.target?.result;
+      a !== void 0 ? n(a) : r(new Error("文件读取失败"));
+    }, o.onerror = () => {
+      r(new Error("文件读取错误"));
+    }, o.onabort = () => {
+      r(new Error("文件读取被中止"));
+    };
+  });
+}
+async function W(e, t = {}) {
+  const { separator: n = ",", hasHeader: r = !0 } = t, o = await p(e, "text");
+  if (!o.trim())
+    return [];
+  const i = o.split(/\r?\n/).filter((h) => h.trim() !== "");
+  if (i.length === 0)
+    return [];
+  let a = [], s = 0;
+  r && (a = b(i[0], n), s = 1);
+  const d = [];
+  for (let h = s; h < i.length; h++) {
+    const l = b(i[h], n);
+    if (r && a.length > 0) {
+      const u = {};
+      a.forEach((c, f) => {
+        u[c] = l[f] || "";
+      }), d.push(u);
+    } else
+      d.push(l);
+  }
+  return d;
+}
+function b(e, t) {
+  const n = [];
+  let r = "", o = !1;
+  for (let i = 0; i < e.length; i++) {
+    const a = e[i], s = e[i + 1];
+    a === '"' ? o && s === '"' ? (r += '"', i++) : o = !o : a === t && !o ? (n.push(r.trim()), r = "") : r += a;
+  }
+  return n.push(r.trim()), n;
+}
+async function k(e) {
+  const t = await p(e, "text");
+  try {
+    return JSON.parse(t);
+  } catch (n) {
+    throw new Error(`JSON 解析失败：${n instanceof Error ? n.message : "未知错误"}`);
+  }
+}
+async function F(e, t, n) {
+  try {
+    const r = await fetch(e, n?.fetchOptions);
+    if (!r.ok)
+      throw new Error(`下载失败：${r.status} ${r.statusText}`);
+    const o = await r.blob();
+    let i = t;
+    if (!i) {
+      const a = r.headers.get("Content-Disposition");
+      if (a) {
+        const s = /filename[^;=\n]*=((['"]).*?\2|[^;\n]*)/.exec(a);
+        s && s[1] && (i = decodeURIComponent(s[1].replace(/['"]/g, "")));
+      }
+      i || (i = e.split("/").pop() || "download");
+    }
+    g(o, i, n);
+  } catch (r) {
+    throw console.error("文件下载失败:", r), r;
+  }
+}
+function g(e, t, n) {
+  const r = URL.createObjectURL(e), o = document.createElement("a");
+  o.href = r, o.download = t, n?.newWindow && (o.target = "_blank"), document.body.appendChild(o), o.click(), document.body.removeChild(o), URL.revokeObjectURL(r);
+}
+function $(e, t, n) {
+  e.startsWith("data:") ? (n = e.split(",")[0].split(":")[1].split(";")[0], e = e.split(",")[1]) : n || (n = "application/octet-stream");
+  const o = atob(e), i = new Array(o.length);
+  for (let d = 0; d < o.length; d++)
+    i[d] = o.charCodeAt(d);
+  const a = new Uint8Array(i), s = new Blob([a], { type: n });
+  g(s, t);
+}
+async function I(e, t = 500) {
+  for (let n = 0; n < e.length; n++)
+    try {
+      await F(e[n]), n < e.length - 1 && await new Promise((r) => setTimeout(r, t));
+    } catch (r) {
+      console.error(`第 ${n + 1} 个文件下载失败:`, r);
+    }
+}
+function L(e) {
+  return p(e, "dataURL");
+}
+function O(e, t) {
+  e.startsWith("data:") ? (t = e.split(",")[0].split(":")[1].split(";")[0], e = e.split(",")[1]) : t || (t = "application/octet-stream");
+  const r = atob(e), o = new Array(r.length);
+  for (let a = 0; a < r.length; a++)
+    o[a] = r.charCodeAt(a);
+  const i = new Uint8Array(o);
+  return new Blob([i], { type: t });
+}
+function R(e, t, n = "utf-8") {
+  const r = new Blob([e], { type: `text/plain;charset=${n}` });
+  g(r, t);
+}
+function w(e, t) {
+  if (e == null)
+    return "";
+  const n = String(e);
+  return n.includes(t) || n.includes('"') || n.includes(`
+`) || n.includes("\r") ? `"${n.replace(/"/g, '""')}"` : n;
+}
+function T(e, t, n = {}) {
+  const {
+    separator: r = ",",
+    includeHeader: o = !0,
+    encoding: i = "utf-8"
+  } = n;
+  if (e.length === 0)
+    throw new Error("数据不能为空");
+  let a = "";
+  if (typeof e[0] == "object" && !Array.isArray(e[0])) {
+    const l = e, u = Array.from(
+      new Set(l.flatMap((c) => Object.keys(c)))
+    );
+    o && (a += u.join(r) + `
+`), l.forEach((c) => {
+      const f = u.map((x) => {
+        const C = c[x];
+        return w(C, r);
+      });
+      a += f.join(r) + `
+`;
+    });
+  } else {
+    const l = e;
+    if (o && l.length > 0) {
+      const u = l[0].map(
+        (c) => w(c, r)
+      );
+      a += u.join(r) + `
+`;
+      for (let c = 1; c < l.length; c++) {
+        const f = l[c].map(
+          (x) => w(x, r)
+        );
+        a += f.join(r) + `
+`;
+      }
+    } else o || l.forEach((u) => {
+      const c = u.map(
+        (f) => w(f, r)
+      );
+      a += c.join(r) + `
+`;
+    });
+  }
+  a = a.trimEnd();
+  const d = "\uFEFF", h = new Blob([d + a], {
+    type: `text/csv;charset=${i}`
+  });
+  g(h, t);
+}
+function z(e, t, n = {}) {
+  const {
+    pretty: r = !0,
+    spaces: o = 2,
+    encoding: i = "utf-8"
+  } = n;
+  try {
+    const a = r ? JSON.stringify(e, null, o) : JSON.stringify(e), s = new Blob([a], {
+      type: `application/json;charset=${i}`
+    });
+    g(s, t);
+  } catch (a) {
+    throw console.error("JSON 序列化失败:", a), new Error("数据无法序列化为 JSON");
+  }
+}
+function y(e) {
+  const t = typeof e == "string" ? e : e.name, n = t.lastIndexOf(".");
+  return n === -1 || n === t.length - 1 ? "" : t.slice(n).toLowerCase();
+}
+function U(e) {
+  const t = typeof e == "string" ? e : e.name, n = t.lastIndexOf(".");
+  return n === -1 ? t : t.slice(0, n);
+}
+function j(e) {
+  return {
+    name: e.name,
+    size: e.size,
+    type: e.type,
+    lastModified: e.lastModified
+  };
+}
+function v(e, t) {
+  if (!e || !t || t.length === 0)
+    return !1;
+  const n = e.type.toLowerCase(), r = y(e).toLowerCase();
+  return t.some((o) => {
+    const i = o.toLowerCase();
+    if (i.endsWith("/*")) {
+      const a = i.split("/")[0];
+      return n.startsWith(`${a}/`);
+    }
+    return i.startsWith(".") ? r === i : n === i;
+  });
+}
+function E(e, t) {
+  return e ? e.size <= t : !1;
+}
+function m(e) {
+  if (!e)
+    return !1;
+  if (e.type.startsWith("image/"))
+    return !0;
+  const t = [".jpg", ".jpeg", ".png", ".gif", ".bmp", ".webp", ".svg", ".ico"], n = y(e);
+  return t.includes(n);
+}
+function B(e) {
+  return new Promise((t, n) => {
+    if (!m(e)) {
+      n(new Error("文件不是有效的图片格式"));
+      return;
+    }
+    const r = new FileReader();
+    r.onload = (o) => {
+      const i = new Image();
+      i.onload = () => {
+        t({
+          width: i.width,
+          height: i.height
+        });
+      }, i.onerror = () => {
+        n(new Error("图片加载失败"));
+      }, i.src = o.target?.result;
+    }, r.onerror = () => {
+      n(new Error("文件读取失败"));
+    }, r.readAsDataURL(e);
+  });
+}
+async function H(e, t = {}) {
+  const n = [];
+  if (t.acceptTypes && t.acceptTypes.length > 0 && (v(e, t.acceptTypes) || n.push(`不支持的文件类型。接受：${t.acceptTypes.join(", ")}`)), t.maxSize !== void 0 && !E(e, t.maxSize)) {
+    const r = A(t.maxSize);
+    n.push(`文件过大。最大允许：${r}`);
+  }
+  if (t.mustBeImage && !m(e) && n.push("文件必须是图片格式"), m(e) && (t.minWidth !== void 0 || t.maxWidth !== void 0 || t.minHeight !== void 0 || t.maxHeight !== void 0))
+    try {
+      const r = await B(e);
+      t.minWidth !== void 0 && r.width < t.minWidth && n.push(`图片宽度过小。最小宽度：${t.minWidth}px`), t.maxWidth !== void 0 && r.width > t.maxWidth && n.push(`图片宽度过大。最大宽度：${t.maxWidth}px`), t.minHeight !== void 0 && r.height < t.minHeight && n.push(`图片高度过小。最小高度：${t.minHeight}px`), t.maxHeight !== void 0 && r.height > t.maxHeight && n.push(`图片高度过大。最大高度：${t.maxHeight}px`);
+    } catch {
+      n.push("无法获取图片尺寸");
+    }
+  return {
+    valid: n.length === 0,
+    errors: n
+  };
+}
+function A(e, t = 2) {
+  if (e === 0) return "0 B";
+  const n = ["B", "KB", "MB", "GB", "TB"], r = 1024, o = Math.floor(Math.log(e) / Math.log(r));
+  return parseFloat((e / Math.pow(r, o)).toFixed(t)) + " " + n[o];
+}
+const J = {
+  // 读取
+  readFile: p,
+  readTxtFile: S,
+  readCsvFile: W,
+  readJsonFile: k,
+  // 下载
+  downloadFile: F,
+  downloadBlob: g,
+  downloadBase64: $,
+  downloadMultiple: I,
+  // 转换
+  fileToBase64: L,
+  base64ToBlob: O,
+  // 生成
+  generateTxtFile: R,
+  generateCsvFile: T,
+  generateJsonFile: z,
+  // 验证
+  checkFileType: v,
+  checkFileSize: E,
+  isImage: m,
+  getImageDimensions: B,
+  validateFile: H,
+  formatFileSize: A,
+  // 工具
+  getFileExtension: y,
+  getFileNameWithoutExtension: U,
+  getFileInfo: j
+};
+export {
+  O as base64ToBlob,
+  E as checkFileSize,
+  v as checkFileType,
+  J as default,
+  $ as downloadBase64,
+  g as downloadBlob,
+  F as downloadFile,
+  I as downloadMultiple,
+  L as fileToBase64,
+  A as formatFileSize,
+  T as generateCsvFile,
+  z as generateJsonFile,
+  R as generateTxtFile,
+  y as getFileExtension,
+  j as getFileInfo,
+  U as getFileNameWithoutExtension,
+  B as getImageDimensions,
+  m as isImage,
+  W as readCsvFile,
+  p as readFile,
+  k as readJsonFile,
+  S as readTxtFile,
+  H as validateFile
+};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@giszhc/file-utils",
+  "version": "0.0.1",
+  "type": "module",
+  "files": [
+    "dist",
+    "types"
+  ],
+  "module": "dist/file-utils.js",
+  "types": "types/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/giszhc/file-utils.git"
+  },
+  "bugs": {
+    "url": "https://github.com/giszhc/file-utils/issues"
+  },
+  "keywords": [
+    "file",
+    "download"
+  ],
+  "homepage": "https://github.com/giszhc/file-utils#readme",
+  "devDependencies": {
+    "typescript": "~5.9.3",
+    "vite": "^7.2.4"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build:types": "tsc -p tsconfig.build.json",
+    "build": "pnpm run build:types && vite build",
+    "preview": "vite preview"
+  }
+}

package/types/convert.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 文件转换相关方法
+ */
+/**
+ * 将 File 或 Blob 对象转换为 Base64 编码
+ *
+ * @param file - File 或 Blob 对象
+ * @returns Promise<string> - Base64 编码的字符串（包含 data URL 前缀）
+ *
+ * @example
+ * // 在文件上传前预览
+ * const input = document.querySelector('input[type="file"]');
+ * input.addEventListener('change', async (e) => {
+ *   const file = e.target.files[0];
+ *   const base64 = await fileToBase64(file);
+ *   console.log(base64); // data:image/jpeg;base64,/9j/4AAQSkZJRg...
+ * });
+ */
+export declare function fileToBase64(file: File | Blob): Promise<string>;
+/**
+ * 将 Base64 编码转换为 Blob 对象
+ *
+ * @param base64 - Base64 编码的字符串（可以包含或不包含 data URL 前缀）
+ * @param mimeType - MIME 类型（可选），如果未指定且 base64 不包含前缀，默认为 'application/octet-stream'
+ * @returns Blob - 转换后的 Blob 对象
+ *
+ * @example
+ * // 转换带前缀的 Base64
+ * const base64 = 'data:image/png;base64,iVBORw0KGgoAAAANS...';
+ * const blob = base64ToBlob(base64);
+ *
+ * @example
+ * // 转换不带前缀的 Base64
+ * const base64 = 'iVBORw0KGgoAAAANS...';
+ * const blob = base64ToBlob(base64, 'image/png');
+ */
+export declare function base64ToBlob(base64: string, mimeType?: string): Blob;

package/types/download.d.ts

@@ -0,0 +1,96 @@
+/**
+ * 文件下载相关方法
+ */
+import type { DownloadOptions } from './types';
+/**
+ * 从 URL 下载文件
+ *
+ * @param url - 文件的 URL 地址
+ * @param filename - 保存的文件名（可选），如果不指定则尝试从 URL 中提取
+ * @param options - 下载选项配置（可选）
+ *
+ * @returns Promise<void>
+ *
+ * @example
+ * // 下载文件并指定文件名
+ * await downloadFile('https://example.com/file.pdf', 'my-file.pdf');
+ *
+ * @example
+ * // 使用默认文件名
+ * await downloadFile('https://example.com/image.jpg');
+ *
+ * @example
+ * // 设置授权请求头
+ * await downloadFile('https://api.example.com/file/123', undefined, {
+ *   fetchOptions: {
+ *     headers: {
+ *       'Authorization': 'Bearer token123'
+ *     }
+ *   }
+ * });
+ *
+ * @example
+ * // 使用 POST 请求下载
+ * await downloadFile('https://api.example.com/download', 'file.pdf', {
+ *   fetchOptions: {
+ *     method: 'POST',
+ *     body: JSON.stringify({ fileId: 123 })
+ *   }
+ * });
+ *
+ * @remarks
+ * - 需要目标服务器支持 CORS（跨域资源共享）
+ * - 会自动清理临时创建的 Blob URL
+ * - 可以通过 fetchOptions 传入自定义的 fetch 配置
+ */
+export declare function downloadFile(url: string, filename?: string, options?: DownloadOptions): Promise<void>;
+/**
+ * 下载 Blob 对象
+ *
+ * @param blob - Blob 对象
+ * @param filename - 保存的文件名（包含扩展名）
+ * @param options - 下载选项配置（可选）
+ *
+ * @example
+ * // 下载文本文件
+ * const blob = new Blob(['Hello World'], { type: 'text/plain' });
+ * downloadBlob(blob, 'hello.txt');
+ *
+ * @example
+ * // 下载图片
+ * const blob = await fetch('https://example.com/image.jpg').then(r => r.blob());
+ * downloadBlob(blob, 'image.jpg');
+ */
+export declare function downloadBlob(blob: Blob, filename: string, options?: DownloadOptions): void;
+/**
+ * 下载 Base64 编码的文件
+ *
+ * @param base64 - Base64 编码的字符串（可以包含或不包含 data:image/png;base64, 前缀）
+ * @param filename - 保存的文件名（包含扩展名）
+ * @param mimeType - MIME 类型（可选），如果 base64 不包含前缀且未指定此参数，默认为 'application/octet-stream'
+ *
+ * @example
+ * // 下载 PNG 图片
+ * const base64Data = 'data:image/png;base64,iVBORw0KGgoAAAANS...';
+ * downloadBase64(base64Data, 'image.png');
+ *
+ * @example
+ * // 下载不带前缀的 Base64 数据
+ * const base64Data = 'iVBORw0KGgoAAAANS...';
+ * downloadBase64(base64Data, 'image.png', 'image/png');
+ */
+export declare function downloadBase64(base64: string, filename: string, mimeType?: string): void;
+/**
+ * 批量下载文件
+ *
+ * @param urls - URL 数组
+ * @param delay - 下载间隔时间（毫秒），默认 500ms，避免浏览器拦截
+ *
+ * @example
+ * const urls = [
+ *   'https://example.com/image1.jpg',
+ *   'https://example.com/image2.jpg'
+ * ];
+ * downloadMultiple(urls, 1000); // 每隔 1 秒下载一个
+ */
+export declare function downloadMultiple(urls: string[], delay?: number): Promise<void>;

package/types/generate.d.ts

@@ -0,0 +1,93 @@
+/**
+ * 文件生成相关方法
+ */
+/**
+ * 生成并下载 TXT 文件
+ *
+ * @param content - 文本内容
+ * @param filename - 文件名（包含 .txt 扩展名）
+ * @param encoding - 字符编码，默认 'utf-8'
+ *
+ * @example
+ * // 生成简单的文本文件
+ * generateTxtFile('Hello World!', 'hello.txt');
+ *
+ * @example
+ * // 生成多行文本
+ * const lines = ['第一行', '第二行', '第三行'].join('\n');
+ * generateTxtFile(lines, 'multiline.txt');
+ */
+export declare function generateTxtFile(content: string, filename: string, encoding?: string): void;
+/**
+ * 生成并下载 CSV 文件
+ *
+ * @param data - 数据数组（对象数组或二维数组）
+ * @param filename - 文件名（包含 .csv 扩展名）
+ * @param options - CSV 选项配置（可选）
+ *                - separator: 字段分隔符，默认 ','
+ *                - includeHeader: 是否包含表头，默认 true
+ *                - encoding: 字符编码，默认 'utf-8'
+ *
+ * @example
+ * // 使用对象数组生成 CSV
+ * const users = [
+ *   { name: '张三', age: 25, city: '北京' },
+ *   { name: '李四', age: 30, city: '上海' },
+ *   { name: '王五', age: 28, city: '广州' }
+ * ];
+ * generateCsvFile(users, 'users.csv');
+ *
+ * @example
+ * // 使用二维数组生成 CSV
+ * const data = [
+ *   ['姓名', '年龄', '城市'],
+ *   ['张三', 25, '北京'],
+ *   ['李四', 30, '上海']
+ * ];
+ * generateCsvFile(data, 'data.csv');
+ *
+ * @example
+ * // 自定义分隔符（制表符）
+ * generateCsvFile(data, 'data.tsv', { separator: '\t' });
+ */
+export declare function generateCsvFile(data: Record<string, any>[] | any[][], filename: string, options?: {
+    separator?: string;
+    includeHeader?: boolean;
+    encoding?: string;
+}): void;
+/**
+ * 生成并下载 JSON 文件
+ *
+ * @param data - JavaScript 对象或数组
+ * @param filename - 文件名（包含 .json 扩展名）
+ * @param options - JSON 选项配置（可选）
+ *                - pretty: 是否格式化输出，默认 true
+ *                - spaces: 缩进空格数，默认 2
+ *                - encoding: 字符编码，默认 'utf-8'
+ *
+ * @example
+ * // 生成简单的 JSON 文件
+ * const data = { name: '张三', age: 25 };
+ * generateJsonFile(data, 'user.json');
+ *
+ * @example
+ * // 生成格式化的 JSON 数组
+ * const users = [
+ *   { name: '张三', age: 25 },
+ *   { name: '李四', age: 30 }
+ * ];
+ * generateJsonFile(users, 'users.json');
+ *
+ * @example
+ * // 压缩输出（不格式化）
+ * generateJsonFile(data, 'data.min.json', { pretty: false });
+ *
+ * @example
+ * // 自定义缩进
+ * generateJsonFile(data, 'data.json', { spaces: 4 });
+ */
+export declare function generateJsonFile(data: any, filename: string, options?: {
+    pretty?: boolean;
+    spaces?: number;
+    encoding?: string;
+}): void;

package/types/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * file-utils 文件操作工具库
+ *
+ * 提供常用的文件处理功能：读取、下载、转换、生成、验证等
+ * 支持 Tree Shaking，按需引入
+ */
+export type { ReadFileType, CompressOptions, DownloadOptions, IFileInfo, IValidationResult, IFileValidationOptions } from './types';
+export { readFile, readTxtFile, readCsvFile, readJsonFile } from './read';
+export { downloadFile, downloadBlob, downloadBase64, downloadMultiple } from './download';
+export { fileToBase64, base64ToBlob } from './convert';
+export { generateTxtFile, generateCsvFile, generateJsonFile } from './generate';
+export { checkFileType, checkFileSize, isImage, getImageDimensions, validateFile, formatFileSize } from './validators';
+export { getFileExtension, getFileNameWithoutExtension, getFileInfo } from './utils';
+import { readFile, readTxtFile, readCsvFile, readJsonFile } from './read';
+import { downloadFile, downloadBlob, downloadBase64, downloadMultiple } from './download';
+import { fileToBase64, base64ToBlob } from './convert';
+import { generateTxtFile, generateCsvFile, generateJsonFile } from './generate';
+import { checkFileType, checkFileSize, isImage, getImageDimensions, validateFile, formatFileSize } from './validators';
+import { getFileExtension, getFileNameWithoutExtension, getFileInfo } from './utils';
+declare const _default: {
+    readFile: typeof readFile;
+    readTxtFile: typeof readTxtFile;
+    readCsvFile: typeof readCsvFile;
+    readJsonFile: typeof readJsonFile;
+    downloadFile: typeof downloadFile;
+    downloadBlob: typeof downloadBlob;
+    downloadBase64: typeof downloadBase64;
+    downloadMultiple: typeof downloadMultiple;
+    fileToBase64: typeof fileToBase64;
+    base64ToBlob: typeof base64ToBlob;
+    generateTxtFile: typeof generateTxtFile;
+    generateCsvFile: typeof generateCsvFile;
+    generateJsonFile: typeof generateJsonFile;
+    checkFileType: typeof checkFileType;
+    checkFileSize: typeof checkFileSize;
+    isImage: typeof isImage;
+    getImageDimensions: typeof getImageDimensions;
+    validateFile: typeof validateFile;
+    formatFileSize: typeof formatFileSize;
+    getFileExtension: typeof getFileExtension;
+    getFileNameWithoutExtension: typeof getFileNameWithoutExtension;
+    getFileInfo: typeof getFileInfo;
+};
+export default _default;