CKN Technology Data · Excel File Utilities

CKN Technology Data
ExcelFile & ExcelSheet

This page documents the ExcelFile and ExcelSheet classes built on top of ExcelJS and the core File abstraction. Each function includes description, signature, and example for consistent Excel workbook handling across the CKN ecosystem.

Import

The Excel utilities are exposed via @ckn-technology/data and are backed by ExcelJS and the base File class.

ExcelFile (default export) 

import ExcelFile from "@ckn-technology/data";

From implementation file

import { ExcelFile, ExcelSheet } from "./ExcelFile.js";

The examples below assume the default export pattern where ExcelFile exposes static helpers like ExcelFile.Workbook and ExcelFile.ExcelSheet.

1. ExcelSheet

1.1 Overview

ExcelSheet is a thin wrapper around an ExcelJS.Worksheet that provides:

  • Convenience methods for adding single or multiple rows.
  • Styling helpers (border, font, fill, alignment, generic style).
  • Merging cells and freezing panes.
  • Exporting the sheet to JSON where the first row is treated as the header for object keys.
import ExcelFile from "@ckn-technology/data";

const wb = new ExcelFile.Workbook();
const ws = wb.addWorksheet("Data");
const sheet = new ExcelFile.ExcelSheet(ws);

1.2 Constructor

constructor(worksheet)

Description
Wraps an existing ExcelJS.Worksheet instance inside an ExcelSheet.

Signature

constructor(worksheet: ExcelJS.Worksheet)

Example

import ExcelFile from "@ckn-technology/data";

const wb = new ExcelFile.Workbook();
const ws = wb.addWorksheet("Data");
const sheet = new ExcelFile.ExcelSheet(ws);

1.3 Row, Cell & Style Helpers

addRow(row)

Description
Adds a single row (array of values) to the worksheet using worksheet.addRow. Returns this to allow method chaining.

Signature

addRow(row: any[]): this

Example

sheet
  .addRow(["ID", "Name", "Age"])
  .addRow([1, "Alice", 30]);

addRows(rows)

Description
Adds multiple rows to the worksheet using worksheet.addRows. Each element in rows is an array representing a row. Returns this for chaining.

Signature

addRows(rows: any[][]): this

Example

sheet.addRows([
  ["ID", "Name"],
  [1, "Alice"],
  [2, "Bob"]
]);

freezePane(row, column)

Description
Freezes the top row rows and left column columns by setting the worksheet views property.

Signature

freezePane(row: number, column: number): this

Example

// Freeze first row and first column
sheet.freezePane(1, 1);

mergeCells(from, to)

Description
Merges a rectangular range of cells. Uses the ExcelJS mergeCells(from, to) signature where from and to are cell addresses like "A1" and "C3".

Signature

mergeCells(from: string, to: string): this

Example

// Merge cells A1 to C1 into one cell
sheet.mergeCells("A1", "C1");

setColumnWidth(column, width)

Description
Sets the width of a column (1-based index) in number of characters as expected by ExcelJS.

Signature

setColumnWidth(column: number, width: number): this

Example

// Set column A (1) width to 25
sheet.setColumnWidth(1, 25);

setRowHeight(row, height)

Description
Sets the height of a row (1-based index) in points.

Signature

setRowHeight(row: number, height: number): this

Example

// Set row 1 height to 30 points
sheet.setRowHeight(1, 30);

setCell(row, column, value)

Description
Sets the value of a single cell at (row, column). Both row and column are 1-based.

Signature

setCell(row: number, column: number, value: any): this

Example

sheet.setCell(1, 1, "Header");
sheet.setCell(2, 1, 123);

setCells(cells)

Description
Batch version of setCell that accepts an array of [row, column, value] tuples and sets each cell.

Signature

setCells(cells: any[]): this

Example

sheet.setCells([
  [1, 1, "ID"],
  [1, 2, "Name"],
  [2, 1, 1],
  [2, 2, "Alice"]
]);

setStyle(style, rowNumber, columnNumber)

Description
Applies a full style object to a specific cell. The style object should match ExcelJS cell style format (e.g. includes font, fill, border, alignment).

Signature

setStyle(style: any, rowNumber: number, columnNumber: number): this

Example

sheet.setStyle(
  { font: { bold: true, color: { argb: "FF0000FF" } } },
  1,
  1
);

setBorder(border, rowNumber, columnNumber)

Description
Applies a border to a specific cell. The border object must match an ExcelJS.Border definition.

Signature

setBorder(border: any, rowNumber: number, columnNumber: number): this

Example

sheet.setBorder(
  {
    top: { style: "thin" },
    bottom: { style: "thin" },
    left: { style: "thin" },
    right: { style: "thin" }
  },
  2,
  1
);

setFont(font, rowNumber, columnNumber)

Description
Sets the font of a specific cell. The font object must match an ExcelJS.Font.

Signature

setFont(font: any, rowNumber: number, columnNumber: number): this

Example

sheet.setFont(
  { name: "Arial", size: 12, bold: true },
  1,
  1
);

setFill(fill, rowNumber, columnNumber)

Description
Sets the fill (background) style of a specific cell. The fill object must match an ExcelJS.Fill.

Signature

setFill(fill: any, rowNumber: number, columnNumber: number): this

Example

sheet.setFill(
  {
    type: "pattern",
    pattern: "solid",
    fgColor: { argb: "FFFFFF00" } // yellow
  },
  1,
  1
);

setAlignment(alignment, rowNumber, columnNumber)

Description
Sets the alignment of a specific cell. The alignment object must match an ExcelJS.Alignment.

Signature

setAlignment(alignment: any, rowNumber: number, columnNumber: number): this

Example

sheet.setAlignment(
  { vertical: "middle", horizontal: "center" },
  1,
  1
);

toJSON()

Description
Converts the entire worksheet into an array of objects.

  • Assumes row 1 is the header row.
  • Uses the values from row 1 as object keys.
  • For each subsequent row (2..rowCount), builds: obj[keys[j]] = sheet.getCell(i, j).value.
  • Returns Array<object>.

Signature

toJSON(): Array<object>

Example

// Suppose the sheet content is:
// Row 1: ["id", "name"]
// Row 2: [1, "Alice"]
// Row 3: [2, "Bob"]

const data = sheet.toJSON();
// [
//   { id: 1, name: "Alice" },
//   { id: 2, name: "Bob" }
// ]

2. ExcelFile

2.1 Overview

ExcelFile extends the core File class to work with Excel workbooks (ExcelJS.Workbook):

  • Create a new workbook via create().
  • Add sheets that are automatically wrapped in ExcelSheet.
  • Write the workbook to disk as .xlsx using write(). 
import { File } from "./File.js";
import ExcelJS from "exceljs";

class ExcelFile extends File {
  // ...
}

2.2 Constructor

constructor(filePath)

Description
Creates a new ExcelFile bound to a file path.

  • Calls super(filePath) to initialize the base File.
  • Keeps an internal #workbook (ExcelJS.Workbook) which is lazily created.

Signature

constructor(filePath: string)

Example

import { ExcelFile } from "./ExcelFile.js";

const excelFile = new ExcelFile("./reports/sales.xlsx");

2.3 create()

Description
Initializes a new ExcelJS.Workbook and sets workbook properties:

  • this.#workbook = new ExcelJS.Workbook()
  • this.#workbook.created = new Date()
  • this.#workbook.properties.date1904 = true
  • this.#workbook.calcProperties.fullCalcOnLoad = true

Returns this for chaining.

Signature

create(): this

Example

excelFile.create();

2.4 write()

Description
Writes the workbook to disk as an .xlsx file.

Behavior:

  • If no workbook has been created (#workbook == null):
    • Calls this.create().
    • Adds a default sheet "Sheet1" via this.addSheet("Sheet1").
    • Recursively calls await this.write() again.
  • Finally writes the workbook to this.fullPath using: await this.#workbook.xlsx.writeFile(this.fullPath).

Returns this.

Signature

write(): Promise<this>

Example

const excelFile = new ExcelFile("./reports/sales.xlsx");

const sheet = excelFile
  .create()
  .addSheet("Sales");

sheet.addRow(["id", "name", "amount"]);
sheet.addRow([1, "Alice", 1000]);
sheet.addRow([2, "Bob", 1500]);

await excelFile.write();

2.5 addSheet(name)

Description
Adds a new worksheet to the workbook and wraps it in an ExcelSheet.

  • If the workbook is not yet created, it calls this.create() first.
  • Uses this.#workbook.addWorksheet(name) to create the sheet.
  • Returns a new ExcelSheet instance wrapping that worksheet.

Signature

addSheet(name: string): ExcelSheet

Example

const excelFile = new ExcelFile("./reports/users.xlsx");
const sheet = excelFile.addSheet("Users");

sheet
  .addRow(["id", "name"])
  .addRow([1, "Alice"])
  .addRow([2, "Bob"]);

await excelFile.write();

3. Summary

The ExcelSheet and ExcelFile classes are designed to simplify working with Excel workbooks using ExcelJS inside the CKN ecosystem.

  • ExcelSheet wraps an ExcelJS.Worksheet and provides helpers for:
    • Cell Manipulation: setting individual and multiple cell values, adding rows.
    • Styling: column width, row height, borders, fonts, fills, and alignment.
    • Layout: merging cells, freezing panes.
    • Data Export: converting sheet data to JSON (toJSON()) using the first row as headers.
  • ExcelFile extends File to manage an ExcelJS.Workbook:
    • Workbook Management via create() and addSheet().
    • File Operations via write() to persist the workbook as .xlsx.

Together, these abstractions provide a clean, fluent API for generating and exporting Excel reports, dashboards, and data extracts in Node.js applications built on top of @ckn-technology/data.