@giszhc/file-utils 0.0.1

package/types/read.d.ts

@@ -0,0 +1,70 @@
+/**
+ * 文件读取相关方法
+ */
+import type { ReadFileType } from './types';
+/**
+ * 读取文件内容
+ *
+ * @param file - File 或 Blob 对象
+ * @param type - 读取类型，可选值：'text' | 'arrayBuffer' | 'dataURL' | 'binaryString'
+ *              默认值：'text'
+ * @returns Promise<string | ArrayBuffer> - 返回读取后的内容
+ *
+ * @example
+ * // 读取文本文件
+ * const content = await readFile(file, 'text');
+ *
+ * @example
+ * // 读取为 ArrayBuffer（二进制数据）
+ * const buffer = await readFile(file, 'arrayBuffer');
+ *
+ * @example
+ * // 读取为 Data URL（Base64 编码）
+ * const dataUrl = await readFile(file, 'dataURL');
+ */
+export declare function readFile(file: File | Blob, type?: ReadFileType): Promise<string | ArrayBuffer>;
+/**
+ * 读取 TXT 文件
+ *
+ * @param file - File 或 Blob 对象
+ * @param encoding - 字符编码，默认 'utf-8'
+ * @returns Promise<string> - 返回文本内容
+ *
+ * @example
+ * const content = await readTxtFile(file);
+ *
+ * @example
+ * // 指定编码
+ * const content = await readTxtFile(file, 'gbk');
+ */
+export declare function readTxtFile(file: File | Blob, encoding?: string): Promise<string>;
+/**
+ * 读取 CSV 文件
+ *
+ * @param file - File 或 Blob 对象
+ * @param options - CSV 解析选项
+ *                - separator: 字段分隔符，默认 ','
+ *                - hasHeader: 是否包含表头，默认 true
+ * @returns Promise<any[]> - 解析后的数据数组
+ *
+ * @example
+ * // 读取 CSV 文件
+ * const data = await readCsvFile(file);
+ * console.log(data); // [{name: '张三', age: '25'}, ...]
+ */
+export declare function readCsvFile(file: File | Blob, options?: {
+    separator?: string;
+    hasHeader?: boolean;
+}): Promise<any[]>;
+/**
+ * 读取 JSON 文件
+ *
+ * @param file - File 或 Blob 对象
+ * @returns Promise<T> - 解析后的 JSON 数据
+ *
+ * @example
+ * // 读取 JSON 文件
+ * const data = await readJsonFile<{ name: string; age: number }>(file);
+ * console.log(data.name);
+ */
+export declare function readJsonFile<T = any>(file: File | Blob): Promise<T>;

package/types/utils.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 工具函数相关方法
+ */
+import type { IFileInfo } from './types';
+/**
+ * 获取文件扩展名（后缀）
+ *
+ * @param file - File 对象或文件名
+ * @returns string - 文件扩展名（包含点号，如 '.jpg'）
+ *
+ * @example
+ * const file = new File(['content'], 'test.txt', { type: 'text/plain' });
+ * const ext = getFileExtension(file); // ".txt"
+ *
+ * @example
+ * const ext = getFileExtension('image.png'); // ".png"
+ */
+export declare function getFileExtension(file: File | string): string;
+/**
+ * 获取文件名（不含扩展名）
+ *
+ * @param file - File 对象或文件名
+ * @returns string - 不含扩展名的文件名
+ *
+ * @example
+ * const file = new File(['content'], 'test.txt', { type: 'text/plain' });
+ * const name = getFileNameWithoutExtension(file); // "test"
+ *
+ * @example
+ * const name = getFileNameWithoutExtension('archive.tar.gz'); // "archive.tar"
+ */
+export declare function getFileNameWithoutExtension(file: File | string): string;
+/**
+ * 获取文件信息
+ *
+ * @param file - File 对象
+ * @returns IFileInfo - 包含文件基本信息的对象
+ *
+ * @example
+ * const fileInfo = getFileInfo(file);
+ * console.log(`文件名：${fileInfo.name}, 大小：${(fileInfo.size / 1024).toFixed(2)} KB`);
+ */
+export declare function getFileInfo(file: File): IFileInfo;

package/types/validators.d.ts

@@ -0,0 +1,107 @@
+/**
+ * 文件验证相关方法
+ */
+/**
+ * 检查文件类型是否匹配
+ *
+ * @param file - File 对象
+ * @param acceptTypes - 接受的类型数组，支持：
+ *                     - MIME 类型：'image/jpeg', 'application/pdf'
+ *                     - 通配符：'image/*', 'audio/*', 'video/*'
+ *                     - 扩展名：'.jpg', '.png', '.pdf'
+ * @returns boolean - 如果文件类型匹配返回 true
+ *
+ * @example
+ * // 检查是否为 JPEG 图片
+ * checkFileType(file, ['image/jpeg']);
+ *
+ * @example
+ * // 检查是否为图片或 PDF
+ * checkFileType(file, ['image/*', 'application/pdf']);
+ *
+ * @example
+ * // 使用扩展名检查
+ * checkFileType(file, ['.jpg', '.png', '.gif']);
+ */
+export declare function checkFileType(file: File, acceptTypes: string[]): boolean;
+/**
+ * 检查文件大小是否符合要求
+ *
+ * @param file - File 对象
+ * @param maxSize - 最大文件大小（字节）
+ * @returns boolean - 如果文件大小符合要求返回 true
+ *
+ * @example
+ * // 限制不超过 2MB
+ * checkFileSize(file, 2 * 1024 * 1024);
+ *
+ * @example
+ * // 限制不超过 500KB
+ * checkFileSize(file, 500 * 1024);
+ */
+export declare function checkFileSize(file: File, maxSize: number): boolean;
+/**
+ * 快速判断文件是否为图片格式
+ *
+ * @param file - File 对象
+ * @returns boolean - 如果是图片返回 true
+ *
+ * @example
+ * if (isImage(file)) {
+ *   console.log('这是一个图片文件');
+ * }
+ */
+export declare function isImage(file: File): boolean;
+/**
+ * 获取图片的原始尺寸（宽度和高度）
+ *
+ * @param file - File 对象（必须是图片文件）
+ * @returns Promise<{ width: number, height: number }> - 图片的宽度和高度
+ *
+ * @example
+ * const dimensions = await getImageDimensions(file);
+ * console.log(`图片尺寸：${dimensions.width} x ${dimensions.height}`);
+ *
+ * @throws 如果文件不是图片格式，会抛出错误
+ */
+export declare function getImageDimensions(file: File): Promise<{
+    width: number;
+    height: number;
+}>;
+/**
+ * 综合文件验证
+ *
+ * @param file - File 对象
+ * @param options - 验证选项配置
+ * @returns Promise<IValidationResult> - 验证结果
+ *
+ * @example
+ * // 验证文件：类型、大小、图片尺寸
+ * const result = await validateFile(file, {
+ *   acceptTypes: ['image/jpeg', 'image/png'],
+ *   maxSize: 2 * 1024 * 1024, // 2MB
+ *   mustBeImage: true,
+ *   minWidth: 800,
+ *   maxWidth: 4096,
+ *   minHeight: 600,
+ *   maxHeight: 4096
+ * });
+ *
+ * if (!result.valid) {
+ *   console.log('验证失败:', result.errors);
+ * }
+ */
+export declare function validateFile(file: File, options?: import('./types').IFileValidationOptions): Promise<import('./types').IValidationResult>;
+/**
+ * 格式化文件大小
+ *
+ * @param bytes - 文件大小（字节）
+ * @param decimal - 小数位数，默认 2
+ * @returns string - 格式化后的大小字符串（如：1.5 MB）
+ *
+ * @example
+ * formatFileSize(1024); // "1.00 KB"
+ * formatFileSize(1048576); // "1.00 MB"
+ * formatFileSize(1073741824); // "1.00 GB"
+ */
+export declare function formatFileSize(bytes: number, decimal?: number): string;