sa2kit 1.0.0

package/dist/universalExport/server/index.d.ts

@@ -0,0 +1,429 @@
+import { d as ExportFormat, E as ExportConfig, k as ExportStatus, m as ExportField, i as FieldType } from '../../types-BINlP9MK.js';
+
+/**
+ * UniversalExport Server 端类型定义
+ */
+
+/** 导出服务配置 */
+interface UniversalExportServiceConfig {
+    /** 数据库连接（可选） */
+    db?: any;
+    /** 导出文件存储目录 */
+    exportDir?: string;
+    /** 临时文件目录 */
+    tempDir?: string;
+    /** 最大导出行数 */
+    maxRows?: number;
+    /** 是否启用流式导出 */
+    enableStreaming?: boolean;
+    /** 导出超时时间（毫秒） */
+    timeout?: number;
+}
+/** 导出引擎接口 */
+interface IExportEngine {
+    /** 引擎格式 */
+    readonly format: ExportFormat;
+    /** 导出数据 */
+    export(data: any[], config: ExportConfig): Promise<ExportResult>;
+    /** 流式导出 */
+    exportStream?(data: AsyncIterable<any>, config: ExportConfig): Promise<ExportResult>;
+    /** 验证配置 */
+    validateConfig(config: ExportConfig): boolean;
+    /** 获取引擎信息 */
+    getInfo(): EngineInfo;
+}
+/** 引擎信息 */
+interface EngineInfo {
+    /** 引擎名称 */
+    name: string;
+    /** 支持的格式 */
+    format: ExportFormat;
+    /** 支持流式导出 */
+    supportsStreaming: boolean;
+    /** 最大行数限制 */
+    maxRows?: number;
+}
+/** 导出结果 */
+interface ExportResult {
+    /** 是否成功 */
+    success: boolean;
+    /** 文件路径 */
+    filePath?: string;
+    /** 文件大小（字节） */
+    fileSize?: number;
+    /** 导出行数 */
+    rowCount: number;
+    /** 导出时长（毫秒） */
+    duration: number;
+    /** 错误信息 */
+    error?: string;
+    /** 元数据 */
+    metadata?: Record<string, any>;
+}
+/** 导出进度 */
+interface ExportProgress {
+    /** 任务 ID */
+    taskId: string;
+    /** 当前状态 */
+    status: ExportStatus;
+    /** 已处理行数 */
+    processedRows: number;
+    /** 总行数 */
+    totalRows: number;
+    /** 进度百分比 */
+    percentage: number;
+    /** 剩余时间（秒） */
+    estimatedTime?: number;
+    /** 错误信息 */
+    error?: string;
+}
+/** 数据转换器 */
+interface DataTransformer {
+    /** 转换数据行 */
+    transform(row: any, config: ExportConfig): any;
+    /** 批量转换 */
+    transformBatch?(rows: any[], config: ExportConfig): any[];
+}
+/** 字段映射器 */
+interface FieldMapper {
+    /** 映射字段 */
+    map(value: any, field: ExportField): any;
+}
+/** 数据验证器 */
+interface Validator {
+    /** 验证数据 */
+    validate(data: any[], config: ExportConfig): ValidationResult;
+}
+/** 验证结果 */
+interface ValidationResult {
+    /** 是否有效 */
+    valid: boolean;
+    /** 错误列表 */
+    errors: ValidationError[];
+}
+/** 验证错误 */
+interface ValidationError {
+    /** 行号 */
+    row: number;
+    /** 字段 */
+    field: string;
+    /** 错误消息 */
+    message: string;
+}
+/** 数据源接口 */
+interface IDataSource {
+    /** 获取数据 */
+    getData(query: any, options?: DataQueryOptions): Promise<any[]>;
+    /** 获取数据流 */
+    getDataStream?(query: any, options?: DataQueryOptions): AsyncIterable<any>;
+    /** 获取总数 */
+    getCount(query: any): Promise<number>;
+}
+/** 数据查询选项 */
+interface DataQueryOptions {
+    /** 分页 */
+    page?: number;
+    pageSize?: number;
+    /** 排序 */
+    orderBy?: string;
+    orderDirection?: 'asc' | 'desc';
+    /** 过滤 */
+    filters?: Record<string, any>;
+}
+/** 任务创建选项 */
+interface TaskCreateOptions {
+    /** 配置 ID */
+    configId: string;
+    /** 导出格式 */
+    format: ExportFormat;
+    /** 查询条件 */
+    query?: any;
+    /** 创建者 ID */
+    creatorId?: string;
+    /** 任务名称 */
+    name?: string;
+    /** 任务描述 */
+    description?: string;
+}
+/** 任务更新选项 */
+interface TaskUpdateOptions {
+    /** 任务状态 */
+    status?: ExportStatus;
+    /** 进度 */
+    progress?: number;
+    /** 文件路径 */
+    filePath?: string;
+    /** 文件大小 */
+    fileSize?: number;
+    /** 导出行数 */
+    rowCount?: number;
+    /** 错误信息 */
+    error?: string;
+}
+/** 导出配置记录 */
+interface ExportConfigRecord {
+    /** 配置 ID */
+    id: string;
+    /** 配置名称 */
+    name: string;
+    /** 配置描述 */
+    description?: string;
+    /** 导出格式 */
+    format: ExportFormat;
+    /** 字段定义 */
+    fields: ExportField[];
+    /** 创建时间 */
+    createdAt: Date | string;
+    /** 更新时间 */
+    updatedAt: Date | string;
+    /** 创建者 ID */
+    creatorId?: string;
+}
+/** 导出任务记录 */
+interface ExportTaskRecord {
+    /** 任务 ID */
+    id: string;
+    /** 配置 ID */
+    configId: string;
+    /** 任务状态 */
+    status: ExportStatus;
+    /** 文件路径 */
+    filePath?: string;
+    /** 导出进度 */
+    progress?: number;
+    /** 创建时间 */
+    createdAt: Date | string;
+    /** 更新时间 */
+    updatedAt: Date | string;
+    /** 完成时间 */
+    completedAt?: Date | string;
+}
+/** 导出历史记录 */
+interface ExportHistoryRecord {
+    /** 历史 ID */
+    id: string;
+    /** 任务 ID */
+    taskId: string;
+    /** 配置 ID */
+    configId: string;
+    /** 导出格式 */
+    format: ExportFormat;
+    /** 导出状态 */
+    status: ExportStatus;
+    /** 文件路径 */
+    filePath?: string;
+    /** 文件大小 */
+    fileSize?: number;
+    /** 导出行数 */
+    rowCount: number;
+    /** 导出时长 */
+    duration: number;
+    /** 创建者 ID */
+    creatorId?: string;
+    /** 创建时间 */
+    createdAt: Date | string;
+    /** 错误信息 */
+    error?: string;
+}
+/** 导出事件类型 */
+type ExportEventType = 'task:created' | 'task:started' | 'task:progress' | 'task:completed' | 'task:failed' | 'task:cancelled' | 'config:created' | 'config:updated' | 'config:deleted';
+/** 导出事件 */
+interface ExportEvent {
+    /** 事件类型 */
+    type: ExportEventType;
+    /** 任务 ID */
+    taskId?: string;
+    /** 配置 ID */
+    configId?: string;
+    /** 事件数据 */
+    data?: any;
+    /** 时间戳 */
+    timestamp: Date;
+}
+/** 事件监听器 */
+type ExportEventListener = (event: ExportEvent) => void | Promise<void>;
+/** 格式化器函数 */
+type FormatterFunction = (value: any) => string;
+/** 聚合函数 */
+type AggregateFunction = (values: any[]) => any;
+/** 自定义处理函数 */
+type CustomProcessor = (values: any[]) => any;
+
+/**
+ * UniversalExport Service 工厂函数
+ * 提供简化的服务初始化方式
+ */
+
+/**
+ * 创建导出服务配置（带智能默认值）
+ */
+declare function createExportServiceConfig(options?: Partial<UniversalExportServiceConfig>): UniversalExportServiceConfig;
+/**
+ * 创建导出服务实例（简化版）
+ *
+ * @example
+ * ```typescript
+ * // 最简配置
+ * const service = createUniversalExportService();
+ *
+ * // 标准配置
+ * const service = createUniversalExportService({
+ *   db: drizzleDb,
+ *   exportDir: './exports',
+ *   maxRows: 50000,
+ * });
+ * ```
+ */
+declare function createUniversalExportService(options?: Partial<UniversalExportServiceConfig>): {
+    config: UniversalExportServiceConfig;
+    export(): Promise<never>;
+    createTask(): Promise<never>;
+};
+/**
+ * 从环境变量创建配置（便利函数）
+ *
+ * @example
+ * ```typescript
+ * // .env
+ * // EXPORT_DIR=./exports
+ * // EXPORT_MAX_ROWS=50000
+ *
+ * const service = createExportServiceFromEnv();
+ * ```
+ */
+declare function createExportServiceFromEnv(db?: any): {
+    config: UniversalExportServiceConfig;
+    export(): Promise<never>;
+    createTask(): Promise<never>;
+};
+
+/**
+ * UniversalExport 预设配置
+ * 提供常见场景的开箱即用配置
+ */
+
+/**
+ * 小型应用预设（数据量小）
+ */
+declare function createSmallAppPreset(): Partial<UniversalExportServiceConfig>;
+/**
+ * 中型应用预设（默认配置）
+ */
+declare function createMediumAppPreset(): Partial<UniversalExportServiceConfig>;
+/**
+ * 大型应用预设（数据量大）
+ */
+declare function createLargeAppPreset(): Partial<UniversalExportServiceConfig>;
+/**
+ * 实时导出预设（快速响应）
+ */
+declare function createRealtimeExportPreset(): Partial<UniversalExportServiceConfig>;
+/**
+ * 批量导出预设（大批量、离线处理）
+ */
+declare function createBatchExportPreset(): Partial<UniversalExportServiceConfig>;
+/**
+ * 智能预设：根据环境自动选择
+ */
+declare function createSmartExportPreset(): Partial<UniversalExportServiceConfig>;
+
+/**
+ * UniversalExport 配置验证
+ */
+
+declare class ConfigValidationError extends Error {
+    field: string;
+    constructor(message: string, field: string);
+}
+/**
+ * 验证导出服务配置
+ */
+declare function validateExportConfig(config: UniversalExportServiceConfig): void;
+/**
+ * 验证环境变量
+ */
+declare function validateEnvironment(requiredVars: string[]): void;
+
+/**
+ * UniversalExport Server 工具函数
+ */
+
+/**
+ * 格式化字段值
+ *
+ * @param value 原始值
+ * @param field 字段定义
+ * @returns 格式化后的值
+ */
+declare function formatFieldValue(value: any, field: ExportField): string;
+/**
+ * 验证字段值
+ *
+ * @param value 字段值
+ * @param field 字段定义
+ * @returns 是否有效
+ */
+declare function validateFieldValue(value: any, field: ExportField): boolean;
+/**
+ * 转换字段类型
+ *
+ * @param value 原始值
+ * @param targetType 目标类型
+ * @returns 转换后的值
+ */
+declare function convertFieldType(value: any, targetType: FieldType): any;
+/**
+ * 安全获取嵌套属性值
+ *
+ * @param obj 对象
+ * @param path 属性路径（支持点号分隔）
+ * @returns 属性值
+ *
+ * @example
+ * ```typescript
+ * const obj = { user: { name: 'John', age: 30 } };
+ * getNestedValue(obj, 'user.name')  // 'John'
+ * getNestedValue(obj, 'user.email') // undefined
+ * ```
+ */
+declare function getNestedValue(obj: any, path: string): any;
+/**
+ * 转义 CSV 字段值
+ *
+ * @param value 字段值
+ * @returns 转义后的值
+ */
+declare function escapeCsvValue(value: string): string;
+/**
+ * 生成唯一的文件名
+ *
+ * @param prefix 前缀
+ * @param extension 扩展名
+ * @returns 唯一文件名
+ *
+ * @example
+ * ```typescript
+ * generateUniqueFilename('export', 'xlsx')
+ * // 'export_20231111_123456_abc123.xlsx'
+ * ```
+ */
+declare function generateUniqueFilename(prefix: string, extension: string): string;
+/**
+ * 计算导出进度百分比
+ *
+ * @param processed 已处理行数
+ * @param total 总行数
+ * @returns 百分比（0-100）
+ */
+declare function calculateProgress(processed: number, total: number): number;
+/**
+ * 估算剩余时间（秒）
+ *
+ * @param processed 已处理行数
+ * @param total 总行数
+ * @param elapsedMs 已用时间（毫秒）
+ * @returns 剩余时间（秒）
+ */
+declare function estimateRemainingTime(processed: number, total: number, elapsedMs: number): number;
+
+export { type AggregateFunction, type CustomProcessor, type DataQueryOptions, type DataTransformer, type EngineInfo, type ExportConfigRecord, ConfigValidationError as ExportConfigValidationError, type ExportEvent, type ExportEventListener, type ExportEventType, type ExportHistoryRecord, type ExportProgress, type ExportResult, type ExportTaskRecord, type FieldMapper, type FormatterFunction, type IDataSource, type IExportEngine, type TaskCreateOptions, type TaskUpdateOptions, type UniversalExportServiceConfig, type ValidationError, type ValidationResult, type Validator, calculateProgress, convertFieldType, createBatchExportPreset, createExportServiceConfig, createExportServiceFromEnv, createLargeAppPreset, createMediumAppPreset, createRealtimeExportPreset, createSmallAppPreset, createSmartExportPreset, createUniversalExportService, escapeCsvValue, estimateRemainingTime, formatFieldValue, generateUniqueFilename, getNestedValue, validateExportConfig, validateEnvironment as validateExportEnvironment, validateFieldValue };

package/dist/universalExport/server/index.js

@@ -0,0 +1,263 @@
+'use strict';
+
+require('../../chunk-DGUM43GV.js');
+
+// src/universalExport/server/factory.ts
+function createExportServiceConfig(options = {}) {
+  return {
+    db: options.db,
+    exportDir: options.exportDir || process.env.EXPORT_DIR || "./exports",
+    tempDir: options.tempDir || process.env.TEMP_DIR || "./temp",
+    maxRows: options.maxRows || 1e5,
+    // 默认最多导出 10 万行
+    enableStreaming: options.enableStreaming !== false,
+    // 默认启用流式导出
+    timeout: options.timeout || 3e5
+    // 默认超时 5 分钟
+  };
+}
+function createUniversalExportService(options = {}) {
+  const config = createExportServiceConfig(options);
+  console.warn(
+    "\u26A0\uFE0F  UniversalExportService \u7684\u5B8C\u6574\u5B9E\u73B0\u5C06\u5728\u540E\u7EED Phase \u4E2D\u8FC1\u79FB\u5230 Sa2kit\u3002\n    \u5F53\u524D\u7248\u672C\u4EC5\u5305\u542B\u7C7B\u578B\u5B9A\u4E49\u548C\u914D\u7F6E\u5DE5\u5382\u51FD\u6570\u3002\n    \u8BF7\u6682\u65F6\u7EE7\u7EED\u4ECE LyricNote \u7684 lib/universalExport \u5BFC\u5165\u670D\u52A1\u7C7B\u3002"
+  );
+  return {
+    config,
+    // 占位方法
+    async export() {
+      throw new Error("UniversalExportService \u5C1A\u672A\u5B8C\u5168\u8FC1\u79FB\uFF0C\u8BF7\u4ECE LyricNote \u5BFC\u5165");
+    },
+    async createTask() {
+      throw new Error("UniversalExportService \u5C1A\u672A\u5B8C\u5168\u8FC1\u79FB\uFF0C\u8BF7\u4ECE LyricNote \u5BFC\u5165");
+    }
+  };
+}
+function createExportServiceFromEnv(db) {
+  return createUniversalExportService({
+    db,
+    exportDir: process.env.EXPORT_DIR,
+    tempDir: process.env.TEMP_DIR,
+    maxRows: process.env.EXPORT_MAX_ROWS ? parseInt(process.env.EXPORT_MAX_ROWS) : void 0
+  });
+}
+
+// src/universalExport/server/presets.ts
+function createSmallAppPreset() {
+  return {
+    maxRows: 1e4,
+    // 1万行
+    timeout: 6e4,
+    // 1分钟
+    enableStreaming: false
+    // 小数据量不需要流式导出
+  };
+}
+function createMediumAppPreset() {
+  return {
+    maxRows: 1e5,
+    // 10万行
+    timeout: 3e5,
+    // 5分钟
+    enableStreaming: true
+  };
+}
+function createLargeAppPreset() {
+  return {
+    maxRows: 1e6,
+    // 100万行
+    timeout: 6e5,
+    // 10分钟
+    enableStreaming: true
+  };
+}
+function createRealtimeExportPreset() {
+  return {
+    maxRows: 5e3,
+    // 5千行
+    timeout: 3e4,
+    // 30秒
+    enableStreaming: false
+  };
+}
+function createBatchExportPreset() {
+  return {
+    maxRows: Number.MAX_SAFE_INTEGER,
+    // 不限制
+    timeout: 18e5,
+    // 30分钟
+    enableStreaming: true
+  };
+}
+function createSmartExportPreset() {
+  const envMaxRows = process.env.EXPORT_MAX_ROWS;
+  if (envMaxRows) {
+    const maxRows = parseInt(envMaxRows);
+    if (maxRows <= 1e4) {
+      return createSmallAppPreset();
+    } else if (maxRows <= 1e5) {
+      return createMediumAppPreset();
+    } else {
+      return createLargeAppPreset();
+    }
+  }
+  return createMediumAppPreset();
+}
+
+// src/universalExport/server/validation.ts
+var ConfigValidationError = class extends Error {
+  constructor(message, field) {
+    super(message);
+    this.field = field;
+    this.name = "ConfigValidationError";
+  }
+};
+function validateExportConfig(config) {
+  if (!config.exportDir) {
+    throw new ConfigValidationError("exportDir is required", "exportDir");
+  }
+  if (!config.tempDir) {
+    throw new ConfigValidationError("tempDir is required", "tempDir");
+  }
+  if (config.maxRows && config.maxRows <= 0) {
+    throw new ConfigValidationError(
+      "maxRows must be greater than 0",
+      "maxRows"
+    );
+  }
+  if (config.timeout && config.timeout <= 0) {
+    throw new ConfigValidationError(
+      "timeout must be greater than 0",
+      "timeout"
+    );
+  }
+  if (config.maxRows && config.maxRows > 1e6) {
+    console.warn(
+      `\u26A0\uFE0F  Warning: maxRows (${config.maxRows}) is very large. Consider using pagination or streaming for better performance.`
+    );
+  }
+}
+function validateEnvironment(requiredVars) {
+  const missing = [];
+  for (const varName of requiredVars) {
+    if (!process.env[varName]) {
+      missing.push(varName);
+    }
+  }
+  if (missing.length > 0) {
+    throw new ConfigValidationError(
+      `Missing required environment variables: ${missing.join(", ")}`,
+      "environment"
+    );
+  }
+}
+
+// src/universalExport/server/utils/index.ts
+function formatFieldValue(value, field) {
+  if (field.formatter) {
+    return field.formatter(value);
+  }
+  if (value === null || value === void 0) {
+    return "";
+  }
+  switch (field.type) {
+    case "date":
+      return value instanceof Date ? value.toISOString().split("T")[0] || "" : String(value);
+    case "boolean":
+      return value ? "\u662F" : "\u5426";
+    case "array":
+      return Array.isArray(value) ? value.join(", ") : String(value);
+    case "object":
+      return typeof value === "object" ? JSON.stringify(value) : String(value);
+    case "number":
+      return typeof value === "number" ? value.toLocaleString() : String(value);
+    default:
+      return String(value);
+  }
+}
+function validateFieldValue(value, field) {
+  if (field.required && (value === null || value === void 0 || value === "")) {
+    return false;
+  }
+  switch (field.type) {
+    case "number":
+      return typeof value === "number" || !isNaN(Number(value));
+    case "boolean":
+      return typeof value === "boolean";
+    case "array":
+      return Array.isArray(value);
+    case "object":
+      return typeof value === "object";
+    case "date":
+      return value instanceof Date || !isNaN(Date.parse(value));
+    default:
+      return true;
+  }
+}
+function convertFieldType(value, targetType) {
+  if (value === null || value === void 0) {
+    return value;
+  }
+  switch (targetType) {
+    case "string":
+      return String(value);
+    case "number":
+      return Number(value);
+    case "boolean":
+      return Boolean(value);
+    case "date":
+      return value instanceof Date ? value : new Date(value);
+    case "array":
+      return Array.isArray(value) ? value : [value];
+    case "object":
+      return typeof value === "object" ? value : { value };
+    default:
+      return value;
+  }
+}
+function getNestedValue(obj, path) {
+  return path.split(".").reduce((current, key) => current?.[key], obj);
+}
+function escapeCsvValue(value) {
+  if (value.includes(",") || value.includes('"') || value.includes("\n")) {
+    return `"${value.replace(/"/g, '""')}"`;
+  }
+  return value;
+}
+function generateUniqueFilename(prefix, extension) {
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-").slice(0, -5);
+  const random = Math.random().toString(36).substring(2, 8);
+  return `${prefix}_${timestamp}_${random}.${extension}`;
+}
+function calculateProgress(processed, total) {
+  if (total === 0) return 0;
+  return Math.min(Math.round(processed / total * 100), 100);
+}
+function estimateRemainingTime(processed, total, elapsedMs) {
+  if (processed === 0) return 0;
+  const avgTimePerRow = elapsedMs / processed;
+  const remainingRows = total - processed;
+  return Math.round(remainingRows * avgTimePerRow / 1e3);
+}
+
+exports.ExportConfigValidationError = ConfigValidationError;
+exports.calculateProgress = calculateProgress;
+exports.convertFieldType = convertFieldType;
+exports.createBatchExportPreset = createBatchExportPreset;
+exports.createExportServiceConfig = createExportServiceConfig;
+exports.createExportServiceFromEnv = createExportServiceFromEnv;
+exports.createLargeAppPreset = createLargeAppPreset;
+exports.createMediumAppPreset = createMediumAppPreset;
+exports.createRealtimeExportPreset = createRealtimeExportPreset;
+exports.createSmallAppPreset = createSmallAppPreset;
+exports.createSmartExportPreset = createSmartExportPreset;
+exports.createUniversalExportService = createUniversalExportService;
+exports.escapeCsvValue = escapeCsvValue;
+exports.estimateRemainingTime = estimateRemainingTime;
+exports.formatFieldValue = formatFieldValue;
+exports.generateUniqueFilename = generateUniqueFilename;
+exports.getNestedValue = getNestedValue;
+exports.validateExportConfig = validateExportConfig;
+exports.validateExportEnvironment = validateEnvironment;
+exports.validateFieldValue = validateFieldValue;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map