Repository navigation
Description
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
WriteOnlyWorksheethasappendRow,setColumnWidthandclose.WriteOnlyWorkbook.addWorksheet(title)takes no options, andWriteOnlyOptionshasmtimeandcompressionLevel. Insrc/streaming/write-only.ts,flushHeaderwrites the XML declaration,<worksheet>, an optional<cols>and<sheetData>. It writes no<sheetViews>.setFreezePanesandfreezeRowsfrom@office-kit/xlsx/worksheettake a modelledWorksheet. Using them means building the sheet withcreateWorkbook, and then memory grows with the row count.- I could write the file through the write-only writer and reopen it with
loadWorkbookto add the pane.loadWorkbookloads 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 becausesetColumnWidthworks that way.- A setter for the whole
SheetViewwould 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