Sheetz

Read and write Excel & CSV files in Java with a single line of code.

// The entire API, right here:
List<Product> products = Sheetz.read("data.xlsx", Product.class);
Sheetz.write(products, "output.xlsx");

No Workbook objects. No Cell iteration. No boilerplate. Just data.

---

⚡ Why Sheetz?

Apache POI requires 45+ lines to do what Sheetz does in 1. Here's the proof:

| | Sheetz | Apache POI | EasyExcel | FastExcel | |---|---|---|---|---| | Lines to read 100K rows | 1 | 20+ | 12+ (listener) | 15+ | | Lines to write 100K rows | 1 | 25+ | 3 | 18+ | | Write speed (100K rows) | 423ms | 2,453ms | 542ms | 309ms | | Memory (streaming) | ~10MB | ~340MB | ~85MB | ~40MB | | Annotation mapping | ✅ | ❌ | ✅ | ❌ | | Built-in validation | ✅ | ❌ | ❌ | ❌ | | Auto type conversion | ✅ 19 types | ❌ | ⚠️ basic | ❌ | | Multi-format (xlsx/xls/csv) | ✅ | ✅ | ⚠️ xlsx only | ⚠️ xlsx only |

📊 Full JMH benchmark results & methodology →

---

🚀 Quick Start

Add dependency

Maven:

<dependency>
    <groupId>io.github.chitralabs.sheetz</groupId>
    <artifactId>sheetz-core</artifactId>
    <version>1.0.2</version>
</dependency>

Gradle:

implementation 'io.github.chitralabs.sheetz:sheetz-core:1.0.2'

Define your model

public class Product {
    public String name;
    public Double price;
    public Boolean inStock;
    public LocalDate releaseDate;

    public Product() {} // Required no-arg constructor
}

Read → Process → Write

// Read from Excel
List<Product> products = Sheetz.read("products.xlsx", Product.class);

// Read from CSV
List<Product> products = Sheetz.read("products.csv", Product.class);

// Write to Excel
Sheetz.write(products, "output.xlsx");

// Stream 1M rows with ~10MB memory
Sheetz.stream("huge.xlsx", Product.class)
      .forEach(product -> process(product));

⭐ If this just saved you time, please star this repo — it helps other Java developers find Sheetz.

---

✨ Features

• 🚀 One-liner API — Sheetz.read(), Sheetz.write(), Sheetz.stream(), Sheetz.validate()
• 📊 True SAX Streaming — constant ~10MB memory for files of any size
• 🔄 19 Auto Converters — LocalDate, LocalDateTime, BigDecimal, UUID, Enum, Boolean (yes/true/1/on), and more
• 🧵 Thread-Safe — safe for concurrent use without synchronization
• ✅ Row-Level Validation — per-row errors with column name, value, and root cause
• 📝 @Column Annotation — map to any header name, index, required, default, date format, custom converter
• 📑 Multi-Sheet Workbook — write different model types to different sheets in one call
• 📁 Multi-Format — XLSX, XLS (legacy 97-2003), and CSV from one unified API
• ⚙️ Builder API — fine-grained control via Sheetz.reader() and Sheetz.writer() builders
• 🔌 Extensible — implement Converter<T> interface for custom types

---

📖 Usage Examples

Annotation Mapping

public class Invoice {
    @Column("Invoice #")              // Custom header name
    public String invoiceNumber;

    @Column(index = 1)                // Map by column index
    public Double amount;

    @Column(required = true)          // Fail validation if empty
    public String customerId;

    @Column(defaultValue = "pending") // Default for empty cells
    public String status;

    @Column(format = "dd/MM/yyyy")    // Custom date format
    public LocalDate dueDate;

    @Column(converter = MoneyConverter.class) // Custom converter
    public BigDecimal total;

    @Column(ignore = true)            // Skip this field
    public String internalId;
}

Streaming Large Files

// Row-by-row — constant memory regardless of file size
try (StreamingReader<Product> reader = Sheetz.stream("huge.xlsx", Product.class)) {
    for (Product p : reader) {
        database.save(p);
    }
}

// Batch processing — 1000 rows at a time
Sheetz.stream("huge.xlsx", Product.class)
      .batch(1000)
      .forEach(batch -> database.bulkInsert(batch));

// Java Streams integration
long expensiveCount = Sheetz.stream("products.xlsx", Product.class)
      .stream()
      .filter(p -> p.price > 1000)
      .count();

Validation

ValidationResult<Product> result = Sheetz.validate("data.xlsx", Product.class);

System.out.printf("Valid: %d | Errors: %d | Rate: %.1f%%%n",
    result.validCount(), result.errorCount(), result.successRate());

result.errors().forEach(error ->
    System.out.printf("Row %d [%s]: %s%n",
        error.row(), error.column(), error.message()));

List<Product> validOnly = result.validRows();

Multi-Sheet Workbook

Sheetz.workbook()
      .sheet("Products", products)
      .sheet("Employees", employees)
      .sheet("Orders", orders)
      .write("monthly-report.xlsx");

Builder API

// Fine-grained reader control
List<Product> data = Sheetz.reader(Product.class)
    .file("report.xlsx")
    .sheet("Inventory")
    .headerRow(1)
    .read();

// Fine-grained writer control
Sheetz.writer(Product.class)
    .data(products)
    .file("output.xlsx")
    .sheet("Products")
    .autoSize(true)
    .freezeHeader(true)
    .write();

---

📊 Supported Types

| Type | Example Input | Notes | |------|--------------|-------| | String | Any text | Trimmed by default | | Integer / Long / Double | 42, 3.14 | Standard numeric | | BigDecimal | 99.99 | Precise decimals | | Boolean | true, yes, y, 1, on | Case-insensitive | | LocalDate | 2024-01-15 | Configurable format | | LocalDateTime | 2024-01-15 10:30:00 | Configurable format | | LocalTime | 10:30:00 | ISO format | | Instant | 2024-01-15T10:30:00Z | UTC | | ZonedDateTime | 2024-01-15T10:30:00+05:30 | With timezone | | UUID | 550e8400-... | Standard UUID | | Enum | ACTIVE, active | Case-insensitive | | Custom | Anything | Implement Converter<T> |

---

🗺️ Roadmap

Contributions welcome for any of these! See CONTRIBUTING.md.

• [ ] ODS (LibreOffice Calc) format support — [#help-wanted]
• [ ] Async/reactive streaming API (Sheetz.streamAsync())
• [ ] Google Sheets native reader via API
• [ ] Excel formula write support
• [ ] Password-protected file support
• [ ] Spring Boot auto-configuration starter
• [ ] Quarkus extension
• [ ] Excel chart generation API

Full roadmap and ideas →

---

🏢 Used By

Are you using Sheetz in production? Open a PR to add your project here — it helps other developers discover the library.

Be the first! 🚀

---

🤝 Contributing

Contributions are very welcome! Please read CONTRIBUTING.md.

Looking for a good first issue? Browse issues labelled good first issue.

---

📚 More Resources

| Resource | Description | |----------|-------------| | sheetz-examples | 8 runnable demos covering every feature | | sheetz-benchmarks | JMH benchmarks vs Apache POI, EasyExcel, FastExcel, Poiji | | Maven Central | Latest release | | GitHub Discussions | Q&A and community | | Issues | Bug reports and feature requests |

---

📄 License

Apache License 2.0 — free for commercial and personal use.

---

Sheetz is built with ❤️ by chitralabs