pl2xl Extended Polars Library with Excel Support

This is a wrapper library around the nodejs-polars package that adds convenient readExcel and writeExcel methods for working with Excel files.

For Excel operations, this library uses ExcelJS.

pl.readExcel

pl.readExcel(
    filePath: string,
    options?: {
        sheetName?: string | null,
        inferSchemaLength?: number,
    },
) → ExtendedDataFrame

Reads an Excel file and converts the specified worksheet into an ExtendedDataFrame (a DataFrame that has the writeExcel method).

Parameters

• filePath (string):
  The path to the Excel file to be read.

• options (object, optional):
  A dictionary containing additional options:

  • sheetName (string | null, optional):
    The name of the worksheet to read. Defaults to the first worksheet if not specified.
  • inferSchemaLength (number, optional):
    The number of rows to infer the schema from. Defaults to 100.

Returns

• ExtendedDataFrame:
  A DataFrame containing the data from the specified worksheet.

Example

import pl from "jsr:@jackfiszr/pl2xl@0.1.4";

const df = await pl.readExcel("data.xlsx", { sheetName: "Sheet1" });
console.log(df.toString());

---

pl.DataFrame.writeExcel

pl.DataFrame.writeExcel(
    filePath: string,
    options?: {
        sheetName?: string | string[],
        includeHeader?: boolean,
        autofitColumns?: boolean,
        tableStyle?: string,
        header?: string,
        footer?: string,
        withWorkbook?: (workbook: ExcelJS.Workbook) => void,
    },
) → Promise<void>

Writes the dataframe to an Excel xlsx file.

Parameters

• filePath (string):
  The path where the Excel file will be saved.

• options (object, optional):
  A dictionary containing additional options:

  • sheetName (string | string[], optional):
    Name(s) of the worksheet(s). Defaults to Sheet1, Sheet2, etc.
  • includeHeader (boolean, optional):
    Whether to include column headers in the Excel file. Defaults to true.
  • autofitColumns (boolean, optional):
    Whether to auto-fit the columns based on content. Defaults to true.
  • tableStyle (string, optional):
    The style to apply to the table(s) in the Excel file.
  • header (string, optional):
    The header text to add at the top of each worksheet.
  • footer (string, optional):
    The footer text to add at the bottom of each worksheet.
  • withWorkbook (function, optional):
    A callback function that receives the ExcelJS.Workbook instance for additional customization.

Returns

• Promise:
  A promise that resolves when the Excel file has been written.

Example

import pl from "jsr:@jackfiszr/pl2xl@0.1.4";

const df = pl.DataFrame({
  Name: ["Alice", "Bob"],
  Age: [25, 30],
});

await df.writeExcel("output.xlsx", {
  sheetName: "People",
  includeHeader: true,
  autofitColumns: true,
});

pl.writeExcel (for writing multiple dataframes to separate worksheets)

pl.writeExcel(
    df: ExtendedDataFrame | ExtendedDataFrame[],
    filePath: string,
    options?: {
        sheetName?: string | string[],
        includeHeader?: boolean,
        autofitColumns?: boolean,
        tableStyle?: string,
        header?: string,
        footer?: string,
        withWorkbook?: (workbook: ExcelJS.Workbook) => void,
    },
) → Promise<void>

Writes one or more Polars ExtendedDataFrame objects to an Excel file.

Parameters

Has one additional parameter that is the first parameter:

• df (ExtendedDataFrame | ExtendedDataFrame[]):
  The DataFrame(s) to write to the Excel file.

Returns

• Promise:
  A promise that resolves when the Excel file has been written.

Example

import pl from "jsr:@jackfiszr/pl2xl@0.1.4";

const df1 = pl.DataFrame({
  Name: ["Alice", "Bob"],
  Age: [25, 30],
});

const df2 = pl.DataFrame({
  Name: ["Cat", "Dog"],
  Age: [14, 10],
});

await pl.writeExcel([df1, df2], "output.xlsx", {
  sheetName: ["People", "Animals"],
});

---

nodejs-polars

For the core functionality of the library, please refer to the official nodejs-polars documentation.

License

This library is open-source and distributed under the GNU GENERAL PUBLIC LICENSE 3.0.