diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml new file mode 100644 index 0000000..4b766d0 --- /dev/null +++ b/.github/workflows/publish.yml @@ -0,0 +1,18 @@ +# .github/workflows/publish.yml + +name: Publish + +on: + push: + branches: + - main + +jobs: + publish: + runs-on: ubuntu-latest + permissions: + contents: read + id-token: write + steps: + - uses: actions/checkout@v4 + - run: npx jsr publish diff --git a/README.md b/README.md index c10ef62..bb6f1e9 100644 --- a/README.md +++ b/README.md @@ -1 +1,85 @@ # pl2xl + +A lightweight library for reading and writing Excel files as Polars DataFrames. +`pl2xl` enables seamless integration between Polars and Excel, allowing you to +import data from Excel files directly into a Polars DataFrame and export +DataFrames back to Excel. + +## Installation + +This library can be imported using the `jsr` import specifier and relies on the +`nodejs-polars` package. + +### Importing the library in Deno + +```typescript +import { readExcel, writeExcel } from "jsr:@jackfiszr/pl2xl@0.0.1"; +import pl from "npm:nodejs-polars"; +``` + +### Using the library in Node.js + +Install the library in your Node project using `npx jsr`: + +```bash +npx jsr add @jackfiszr/pl2xl +``` + +Then import and use it as follows: + +```typescript +import { readExcel, writeExcel } from "@jackfiszr/pl2xl"; +import pl from "nodejs-polars"; + +// Create a sample DataFrame +const inputDf = pl.DataFrame({ + "Name": ["Alice", "Bob", "Charlie"], + "Age": [25, 30, 35], + "City": ["New York", "Los Angeles", "Chicago"], +}); + +// Write the DataFrame to an Excel file +writeExcel(inputDf, "input.xlsx"); + +// Read the DataFrame back from the Excel file +const df = readExcel("input.xlsx"); +console.log("Read DataFrame:", df); + +// Modify the DataFrame by increasing the "Age" column by 1 +const modifiedDf = df.withColumn( + pl.col("Age").add(1).alias("Age"), +); + +console.log("Modified DataFrame:", modifiedDf); + +// Write the modified DataFrame to a new Excel file +writeExcel(modifiedDf, "output.xlsx"); +console.log("Modified DataFrame written to output.xlsx"); +``` + +## API + +### `readExcel(filePath: string): pl.DataFrame` + +Reads data from the first sheet of an Excel file and returns it as a Polars +DataFrame. + +- `filePath`: The path to the Excel file to be read. + +**Returns**: A `pl.DataFrame` containing the data from the Excel file. + +### `writeExcel(df: pl.DataFrame, filePath: string): void` + +Writes a Polars DataFrame to an Excel file. + +- `df`: The Polars DataFrame to write to the file. +- `filePath`: The path to save the Excel file. + +## Requirements + +- Deno (for Deno usage) or Node.js (for Node usage) +- `nodejs-polars` and `xlsx` packages + +## License + +MIT License diff --git a/deno.json b/deno.json index cf5e34b..8cf677c 100644 --- a/deno.json +++ b/deno.json @@ -1,6 +1,6 @@ { "name": "@jackfiszr/pl2xl", - "version": "0.0.1", + "version": "0.0.2", "exports": "./mod.ts", "tasks": { "dev": "deno run --watch main.ts" diff --git a/mod.ts b/mod.ts index 7a16bbd..7017fef 100644 --- a/mod.ts +++ b/mod.ts @@ -1,6 +1,14 @@ import pl from "polars"; import xlsx from "xlsx"; +/** + * Reads an Excel file and returns its content as a Polars DataFrame. + * This function takes the first sheet of the workbook and converts it to JSON + * before loading it into a DataFrame. + * + * @param filePath - The path to the Excel file to be read. + * @returns A Polars DataFrame containing the data from the first sheet of the Excel file. + */ function readExcel(filePath: string): pl.DataFrame { const workbook = xlsx.readFile(filePath); const sheet = workbook.Sheets[workbook.SheetNames[0]]; @@ -8,6 +16,14 @@ function readExcel(filePath: string): pl.DataFrame { return pl.DataFrame(jsonData); } +/** + * Writes a Polars DataFrame to an Excel file. + * This function converts the DataFrame to JSON records and writes them to the + * specified file, with the data stored in a sheet named "Sheet1". + * + * @param df - The Polars DataFrame to write to an Excel file. + * @param filePath - The path to save the Excel file. + */ function writeExcel(df: pl.DataFrame, filePath: string): void { const rows = df.toRecords(); const newWorkbook = xlsx.utils.book_new();