Merge pull request #66 from PandaTechAM/development

v5

Author: HaikAsatryan

FileExporter.sln

@@ -5,8 +5,6 @@ VisualStudioVersion = 17.6.33723.286
 MinimumVisualStudioVersion = 10.0.40219.1
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "FileExporter", "src\FileExporter\FileExporter.csproj", "{37F75643-3F86-437F-9C88-21AD8C84E6B1}"
 EndProject
-Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "FileExporter.Tests", "test\FileExporter.Tests\FileExporter.Tests.csproj", "{9828695B-4FB0-4D29-9F19-469A369DA131}"
-EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "FileExporter.Demo", "test\FileExporter.Demo\FileExporter.Demo.csproj", "{4EBD2CC6-CA15-495C-AE54-337B23152710}"
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution Items", "{1E6E6EA8-2623-46DA-8A61-53429EBCFE0D}"
@@ -32,10 +30,6 @@ Global
 		{37F75643-3F86-437F-9C88-21AD8C84E6B1}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{37F75643-3F86-437F-9C88-21AD8C84E6B1}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{37F75643-3F86-437F-9C88-21AD8C84E6B1}.Release|Any CPU.Build.0 = Release|Any CPU
-		{9828695B-4FB0-4D29-9F19-469A369DA131}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
-		{9828695B-4FB0-4D29-9F19-469A369DA131}.Debug|Any CPU.Build.0 = Debug|Any CPU
-		{9828695B-4FB0-4D29-9F19-469A369DA131}.Release|Any CPU.ActiveCfg = Release|Any CPU
-		{9828695B-4FB0-4D29-9F19-469A369DA131}.Release|Any CPU.Build.0 = Release|Any CPU
 		{4EBD2CC6-CA15-495C-AE54-337B23152710}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
 		{4EBD2CC6-CA15-495C-AE54-337B23152710}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{4EBD2CC6-CA15-495C-AE54-337B23152710}.Release|Any CPU.ActiveCfg = Release|Any CPU
@@ -50,6 +44,5 @@ Global
 	GlobalSection(NestedProjects) = preSolution
 		{37F75643-3F86-437F-9C88-21AD8C84E6B1} = {4459D40A-17C0-4B8D-9F8A-5CBD596EB80E}
 		{4EBD2CC6-CA15-495C-AE54-337B23152710} = {72F33894-D89A-4D2F-B897-58F7CD1F381E}
-		{9828695B-4FB0-4D29-9F19-469A369DA131} = {72F33894-D89A-4D2F-B897-58F7CD1F381E}
 	EndGlobalSection
 EndGlobal

README.md

@@ -1,143 +1,200 @@
-# FileExporter
+# PandaTech.FileExporter
 
-FileExporter is a lightweight C# library that simplifies file export operations in .NET applications. With support for
-exporting data to CSV, Excel (XLSX), and PDF formats, FileExporter provides an intuitive interface for developers to
-quickly generate and download files.
+**Blazing‑fast, flexible, convention‑first CSV/XLSX exporter for .NET 9+**\
+Powered internally by two battle‑tested libraries:\
 
-## Features
+- **CsvHelper** --- industry‑standard CSV writer\
+- **SpreadCheetah** --- extremely fast, fully streaming XLSX generator
 
-- **Easy Exporting**: Simply call ToCsv(), ToXlsx(), or ToPdf() on your data collection to export to the desired format.
-- **Automatic Splitting**: Handles large datasets by automatically splitting files if the maximum line count or file
-  size is exceeded, then zipping them for easy download.
-- **Flexible Configuration**: Customize export settings such as column headers, delimiter, and more to suit your needs.
-- **Effortless Integration**: Seamlessly integrate FileExporter into your existing .NET projects with minimal setup.
-- **Helper Extension Methods**: Use ToFileFormat(ExportType.Excel) as an alternative to directly calling ToCsv(),
-  ToXlsx(), or ToPdf().
+`PandaTech.FileExporter` focuses on **performance**, **stability**, and
+**developer happiness**.\
+Version **5.x is a complete redesign** of 4.x --- simpler, safer,
+faster. API is fully modernized (minimal APIs, DI‑friendly,
+async‑ready).
 
-## Installation
+> ⚠️ **Breaking Change Notice**\
+> v5 breaks compatibility with v4. Migration is straightforward: - enums
+> changed values --- **do not reuse v4 enum values** - PDF support
+> removed (too slow, not worth maintaining) - All exporters rebuilt
+> around a simpler, more predictable format system
 
-You can install FileExporter via NuGet Package Manager by running the following command:
+------------------------------------------------------------------------
 
-```bash
-Install-Package FileExporter
-```
+## ✨ Features
 
-## Usage
+- **Convention‑based export** (zero config)\
+- **Fluent export rules** via `ExportRule<T>`\
+- **Super‑fast XLSX via SpreadCheetah** (safe for millions of rows)\
+- **CSV export** using CsvHelper\
+- **Automatic ZIP compression** when file size is large\
+- **Multi‑sheet XLSX** for datasets \> 1M rows\
+- **Async streaming support** (`IAsyncEnumerable<T>`)\
+- **Custom formatting & transforms**\
+- **Minimal API ready**\
+- **Simple DI registration**\
+- **No controllers required**
 
-Here's a quick example of how to use FileExporter to export data to a CSV file with old way which is still supported:
+------------------------------------------------------------------------
 
-```csharp
-using FileExporter;
+## 🚀 Installation
 
-// Define your data
-var data = new List<MyDataClass>
-{
-    new MyDataClass { Name = "John Doe", Age = 30, Email = "[email protected]" },
-    new MyDataClass { Name = "Jane Smith", Age = 25, Email = "[email protected]" }
-};
+``` bash
+dotnet add package PandaTech.FileExporter
+```
 
-// Export data to CSV
-var exportedFile = data.ToCsv().ToFile();
+------------------------------------------------------------------------
 
-// Return the exported file to the caller
-return exportedFile;
-```
+## ⚙️ Quick Start
 
-Starting from release 3.3.0, FileExporter supports exporting data using fluent rules.
+### 1. Configure in `Program.cs`
 
-### Fluent Rules Example
+``` csharp
+var builder = WebApplication.CreateBuilder(args);
 
-First, create an ExportRule for your model. In the constructor, call GenerateRules() to automatically create default
-rules based on the model. To customize the setup, use the RuleFor() method to configure specific rules for your model's
-properties. Here's a quick demonstration:
+builder.AddFileExporter(); // scans entry assembly for ExportRule<T>
+```
 
-### Model Example:
+### 2. Export from your endpoint
 
-```csharp
-public class FileData
+``` csharp
+app.MapGet("/export", async () =>
 {
-    public long Id { get; set; }
-    public string Name { get; set; }
-    public string Description { get; set; }
-    public DateTime CreatedAt { get; set; }
-    public string? Comment { get; set; }
-}
+    var data = new List<MyRow>
+    {
+        new() { Id = 1, Name = "Alice" },
+        new() { Id = 2, Name = "Bob" }
+    };
+
+    var file = await data.ToFileFormatAsync(ExportFormat.Xlsx);
+    return file.ToFileResult();
+});
 ```
 
-### Export Rule Example:
+Done. Zero configuration required.
+
+------------------------------------------------------------------------
 
-This sample includes two constructors, one with a default name and one with a custom name.
+## 📄 Defining Custom Rules (Optional)
 
-```csharp
-namespace FileExporter.Tests.ExportRuleTests;
+``` csharp
+using FileExporter.Rules;
 
-public class FileDataExportRule : ExportRule<FileData>
+public sealed class MyRowExportRule : ExportRule<MyRow>
 {
-    public FileDataExportRule()
+    public MyRowExportRule()
     {
-        GenerateRules();
+        WithName("My Custom Export");
 
-        // Custom rules
-        RuleFor(x => x.Description)
-            .WriteToColumn("Description")
-            .WithDefaultValue("Default text here");
+        RuleFor(x => x.Id)
+            .HasOrder(0)
+            .HasFormat(ColumnFormatType.Integer);
 
-        RuleFor(x => x.CreatedAt)
-            .WriteToColumn("Creation date")
-            .WithDefaultValue("22/08/2024");
-    }
-    
-    // OR with custom name
-    public FileDataExportRule() : base("File Data")
-    {
-        GenerateRules();
-        
-        // Custom rules
-        RuleFor(x => x.Description)
-            .WriteToColumn("Description")
-            .WithDefaultValue("Default text here");
-
-        RuleFor(x => x.CreatedAt)
-            .WriteToColumn("Creation date")
-            .WithDefaultValue("22/08/2024");
+        RuleFor(x => x.Name)
+            .HasOrder(1)
+            .WriteToColumn("Full Name");
     }
 }
 ```
 
-If a property is incorrectly set up, an InvalidPropertyNameException will be thrown with a relevant message.
+Just add this class; it will be auto‑discovered.
+
+------------------------------------------------------------------------
+
+## 🔍 Supported Formats
+
+ExportFormat Description
+  -------------- -------------------------------------------------
+**Csv**        UTF‑8 CSV, auto‑quote, stable for huge datasets
+**Xlsx**       Multi‑sheet, streaming, low memory usage
+
+------------------------------------------------------------------------
+
+## 📦 File Naming
+
+Every file receives a timestamp:
+
+    Orders 2025-01-01 10:33:00.xlsx
+
+Automatically sanitized for safety.
+
+------------------------------------------------------------------------
+
+## 🔧 Property Rule Options
+
+  -----------------------------------------------------------------------
+Option Description
+  --------------------------- -------------------------------------------
+`WriteToColumn("Name")`     Override header text
+
+`HasOrder(1)`               Column ordering
 
-### Controller Example:
+`Ignore()`                  Exclude property
 
-Here is an example of how to integrate FileExporter into a web API controller:
+`HasFormat(...)`            Text, Integer, Decimal, Currency,
+Percentage, Boolean, Date, DateTime
 
-```csharp
-namespace FileExporter.Demo.Controllers
+`HasPrecision(2)`           Decimal digit precision (not rounding, for rounding refer `.Transform()`)
+
+`HasWidth(20)`              XLSX column width override
+
+`WithDefaultValue("N/A")`   Replaces null values
+
+`Transform(v => ...)`       Custom transformation
+
+
+------------------------------------------------------------------------
+
+## 🧬 Enum Formatting
+
+Rules support:
+
+- `MixedIntAndName` *(default)* → `"1 - Active"`
+- `Int` → `"1"`
+- `Name` → `"Active"`
+
+------------------------------------------------------------------------
+
+## 🔥 Performance Notes
+
+- Handles **millions of rows** with **constant memory** usage\
+- XLSX splits automatically into multiple sheets\
+- ZIP is only applied when final file exceeds threshold\
+- Async pipelines (`IAsyncEnumerable<T>`) supported
+
+------------------------------------------------------------------------
+
+## 🪄 Tips
+
+- Keep DTOs simple; exporters use reflection only once\
+- Add custom rules **only for overrides** --- conventions already
+  cover:
+    - ordering\
+    - decimal precision\
+    - date formatting\
+    - booleans\
+- For extremely large exports: prefer `IAsyncEnumerable<T>`
+
+------------------------------------------------------------------------
+
+## 🧭 Demo
+
+``` csharp
+app.MapGet("/export/orders", async (ExportFormat format) =>
 {
-    [ApiController]
-    [Route("api/")]
-    public class FileDataExportController(ApiDbContext context) : Controller
-    {
-        [HttpGet("export-xlsx-via-rules")]
-        public IActionResult ExportXlsxViaRules()
-        {
-            var exportData = context.FileData.ToList();
-
-            var rule = new FileDataExportRule();
-            
-            return rule.ToCsv(exportData).ToFile();
-            // OR alternative solution with extension method
-            return rule.ToFileFormat(exportData, ExportType.Xlsx).ToFile();
-        }
-    }
-}
-```
+    var orders = Enumerable.Range(1, 2000000)
+        .Select(i => new OrderDto { Id = i, Total = i * 1.25m });
 
-You can also export data to Excel (XLSX) or PDF formats by calling ToXlsx() or ToPdf() respectively.
+    var file = await orders.ToFileFormatAsync(format);
+    return file.ToFileResult();
+});
+```
 
-## Contributing
+Exports 2M rows in under a few seconds (depending on disk/CPU).
 
-Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests.
+------------------------------------------------------------------------
 
-## License
+## 🏁 Conclusion
 
-This project is licensed under the MIT License.
+`PandaTech.FileExporter` is built to stay small, clean, and blazing
+fast.\
+If you need CSV/XLSX export without pain --- you're covered.

src/FileExporter/Dtos/ExportColumn.cs

@@ -0,0 +1,10 @@
+using System.Reflection;
+using FileExporter.Rules;
+
+namespace FileExporter.Dtos;
+
+internal sealed class ExportColumn
+{
+   public required PropertyInfo Property { get; init; }
+   public required IPropertyRule Rule { get; init; }
+}

src/FileExporter/Dtos/ExportFile.cs

@@ -1,18 +1,8 @@
-using Microsoft.AspNetCore.Mvc;
-
 namespace FileExporter.Dtos;
 
-public class ExportFile(string name, MimeTypes mimeType, byte[] data)
+public sealed class ExportFile(string name, MimeTypes mimeType, byte[] content)
 {
-   public string Name { get; set; } = name + mimeType.Extension;
-   public MimeTypes Type { get; set; } = mimeType;
-   public byte[] Data { get; set; } = data;
-
-   public FileContentResult ToFile()
-   {
-      return new FileContentResult(Data, Type)
-      {
-         FileDownloadName = Name
-      };
-   }
+   public string Name { get; } = name;
+   public MimeTypes MimeType { get; } = mimeType;
+   public byte[] Content { get; } = content;
 }