npm package: @flowkscai/luckyexcel
Description: A high-performance excel import and export library for Luckysheet and Univer, optimized for significantly faster processing speed and lower memory usage compared to the original.
Author: kesi_tsai@163.com
Latest version: 1.2.1

English| [简体中文](./README-zh.md)

> [!IMPORTANT]
> This project is a refined fork of the following repositories:
> 1. [zwight/Luckyexcel](https://github.com/zwight/Luckyexcel) (v1.1.6, commit [88a44f9](https://github.com/zwight/Luckyexcel/commit/88a44f93c481d9432ba27986901a76f5c09100f5))
> 2. [dream-num/Luckyexcel](https://github.com/dream-num/Luckyexcel) (base commit [5a0be42](https://github.com/dream-num/Luckyexcel/commit/5a0be428b9fead1479a0890d19fb26ae0a291a1c) dated 2022-06-10)

## Introduction
This project is based on the import of [Luckyexcel](https://github.com/dream-num/Luckyexcel), and adds the conversion of [Luckysheet](https://github.com/mengshukeji/Luckysheet) data structure into [Univer](https://github.com/dream-num/univer) data structure. It can directly import and return the data structure required by Univer. In addition, this project also implements the export function based on Univer, supporting the export of .xlsx and .csv format files

## Features
Support Univer import excel and export excel/csv adapter list

- Cell style
- Cell border
- Cell format, such as number format, date, percentage, etc.
- Formula
- Conditional Formatting
- Sort
- Filter
- Cell image, floating image
- **Performance**: Up to 70% speedup in XML parsing and highly optimized Luckysheet to Univer conversion
- **Build**: Support tree-shaking for ESM build (lazy loading `exceljs`)

### Plan
The goal is to support all features supported by Univer

- Pivot table
- Chart
- Annotation

## Usage

### CDN
```html
<script src="https://unpkg.com/@univerjs/core/lib/umd/index.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@flowkscai/luckyexcel/dist/luckyexcel.umd.min.js"></script>
<script>
    // Univer import Excel file
    LuckyExcel.transformExcelToUniver(
        file,
        async (exportJson: any) => {
            // After obtaining the converted table data, use univer to initialize, or update the existing univer workbook
            // Note: Univer needs to introduce dependent packages and initialize the table container before it can be used
            univer.createUnit<IWorkbookData, Workbook>(
                UniverInstanceType.UNIVER_SHEET,
                exportJson || {}
            );
        },
        (error: any) => {
            console.log(error);
        }
    );
    // Univer import CSV file
    LuckyExcel.transformCsvToUniver(
        file,
        async (data: any) => {
            // After obtaining the converted table data, use univer to initialize, or update the existing univer workbook
            // Note: Univer needs to introduce dependent packages and initialize the table container before it can be used
            univer.createUnit<IWorkbookData, Workbook>(
                UniverInstanceType.UNIVER_SHEET,
                data || {}
            );
        },
        (error: any) => {
            console.log(error);
        }
    );
    // Export Univer to CSV file
    // snapshot is the Univer snapshot data, getBuffer: true will not download the file, only return the csv content, false will download directly
    // sheetName: Because Univer may have multiple sheets, csv does not have sheets, if sheetName has a value, only the data of the specified sheet name will be downloaded. If it is not passed, all sheets will be downloaded. The file name is ${fileName}_${sheet.name}
    LuckyExcel.transformUniverToCsv({
        snapshot,
        fileName,
        getBuffer: true,
        sheetName: snapshot.sheetOrder[0],
        success: (buffer: string | { [key: string]: string }) => {
            console.log('success');
        },
        error: (error: Error) => {
            console.log('error', error);
        },
    });
    // Export Univer to XLSX file
    // getBuffer: true will not download the file, only return the file's buffer data, false will download directly
    LuckyExcel.transformUniverToExcel({
        snapshot,
        fileName,
        getBuffer: true,
        success: (buffer: Buffer) => {
            console.log('success');
        },
        error: (error: Error) => {
            console.log('error', error);
        },
    });
</script>
```
> Case [univer-import-export](https://stackblitz.com/edit/vitejs-vite-phdnaxdt) shows the detailed usage

### ES and Node.js

#### Installation
```shell
npm install @flowkscai/luckyexcel
```

#### ES import
```js
import LuckyExcel from '@flowkscai/luckyexcel'

// After getting the xlsx file
LuckyExcel.transformExcelToUniver(
    file,
    async (exportJson: any) => {
        // Get the worksheet data after conversion
    },
    (error: any) => {
        // handle error if any thrown
    }
);
```

## Development

### Requirements
[Node.js](https://nodejs.org/en/) Version >= 6 

### Installation
```
npm install -g gulp-cli
npm install
```
### Development
```
npm run dev
```
### Package
```
npm run build
```

A third-party plug-in is used in the project: [JSZip](https://github.com/Stuk/jszip), thanks!

## Authors and acknowledgment
- [@dream-num](https://github.com/dream-num)

## License
[MIT](http://opensource.org/licenses/MIT)

Copyright (c) 2020-present, flowkscai