Skip to content

feat: freeze panes on a write-only worksheet #320

Open

Description

@hrldmitryd

Problem

An HTTP endpoint streams a log export to the response as .xlsx. Rows come from a database cursor and their count has no upper bound, so the export uses the write-only writer. The first row holds the column names and has to stay visible while the user scrolls, so the sheet needs a frozen pane over that row.

The export runs on exceljs today. Its streaming writer takes the pane as a worksheet option, views: [{ state: 'frozen', ySplit: 1 }]. I am moving the export to @office-kit/xlsx 0.27.0, and the frozen pane is the one part of that sheet the write-only writer cannot produce.

Existing paths considered

  • WriteOnlyWorksheet has appendRow, setColumnWidth and close. WriteOnlyWorkbook.addWorksheet(title) takes no options, and WriteOnlyOptions has mtime and compressionLevel. In src/streaming/write-only.ts, flushHeader writes the XML declaration, <worksheet>, an optional <cols> and <sheetData>. It writes no <sheetViews>.
  • setFreezePanes and freezeRows from @office-kit/xlsx/worksheet take a modelled Worksheet. Using them means building the sheet with createWorkbook, and then memory grows with the row count.
  • I could write the file through the write-only writer and reopen it with loadWorkbook to add the pane. loadWorkbook loads the whole sheet too.

Proposed solution

I propose one method on the write-only worksheet that takes the same argument as the modelled setFreezePanes:

import type { FreezeCounts } from '@office-kit/xlsx/worksheet';

export interface WriteOnlyWorksheet {
  readonly title: string;
  appendRow(row: WriteOnlyRowItem[]): Promise<void>;
  setColumnWidth(col: number, width: number): void;
  /** Call before the first `appendRow`. */
  setFreezePanes(topLeft: string | FreezeCounts): void;
  close(): Promise<void>;
}

The export would call it once, before the first row:

const ws = await wb.addWorksheet('Logs');
ws.setFreezePanes({ rows: 1, cols: 0 });
await ws.appendRow(headers);

The method would follow the setColumnWidth rule. It keeps the value until flushHeader runs, and a call after the first appendRow throws OpenXmlIoError. <sheetViews> comes before <cols> in the worksheet part, so flushHeader can write it before <cols>.

The modelled writer builds this element in serializeSheetViews in src/worksheet/writer.ts, which that module does not export today. The write-only writer could call it the way it has called serializeCols since #316, so both writers would share one implementation of the pane XML.

openpyxl's write-only worksheet has the same setter. openpyxl/worksheet/_write_only.py declares freeze_panes = Worksheet.freeze_panes.

Alternatives

  • addWorksheet(title, { freeze }) could take the pane as an option. That covers my case too. I proposed the method because setColumnWidth works that way.
  • A setter for the whole SheetView would cover more than the pane. I only have a use case for the pane.
  • I could post-process the worksheet XML inside the archive after finalize(). That requires buffering the whole archive, which the export uses the write-only writer to avoid.

Scope and compatibility

The change adds one method to WriteOnlyWorksheet. A sheet that never calls it gets no <sheetViews> element, so its output stays as it is today.

Today only the modelled writer can produce a frozen pane. This adds the write-only counterpart, the way setColumnWidth exists for both writers. Neither writer gets a second way to freeze a pane.

Confirmation

  • I have read the project's "one way to do one thing" policy and confirmed
    this proposal is not a parallel path to an existing capability.
  • I have searched existing issues (open and closed) and confirmed this is
    not a duplicate.
  • I have a real, specific use case for this — not a hypothetical "could be
    useful."
  • If I used an LLM to draft this issue, I have read and verified every
    claim, including the "existing paths" section, and am willing to defend
    the proposal in follow-up.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions