feat(xlsxgen): generate spreadsheets from a declarative spec and structured data
メンテナーはふだん 1 日以内に返信
@sthanikan2000 がすでに取り組んでいます。
2026年9月17日 から。
評価
この issue はまだ評価されていません。
説明
1. Problem
Core does not support generating spreadsheets. A single window system has to hand people tabular
output — a sales schedule, a line-item listing, a reconciliation — and there is no supported way to
produce a workbook from data the system already holds. archive/zip is used nowhere in the repo,
so this is greenfield.
Writing .xlsx by hand is not realistic. It is a ZIP of interdependent OOXML parts, and getting
the content types, relationships or cell encoding wrong produces a file Excel silently refuses to
open, usually with no useful diagnostic.
2. Proposed approach
A standalone module xlsxgen, stdlib-only (archive/zip + encoding/xml), mirroring
xmlgen's shape and dependency profile.
The template is a JSON spec, not a binary workbook. A spec describes the sheet, where the rows
come from, and how each column is headed and formatted:
{
"sheet": "Auction Report",
"rows": "sales.sheet",
"columns": [
{ "header": "Date of Sale", "from": "Sale_date" },
{ "header": "Garden Mark", "from": "Garden_mark" },
{ "header": "Rate per KG", "from": "Sale_rate", "type": "number", "format": "#,##0.00" },
{ "header": "Qty in KG", "from": "Sale_quantity", "type": "number" },
{ "header": "Total Value", "from": "Sale_value", "type": "number", "format": "#,##0.00" }
]
}
At its smallest the spec is two fields — a sheet name and where the rows are:
{ "sheet": "Sales Data", "rows": "sales.sheet" }
Two row shapes
Tabular data reaches a generator in one of two forms, and the spec has to serve both:
// a matrix — row 1 is already the header
[["Date", "Item", "Qty"], ["01/06/2026", "Widget A", 500]]
// records — one object per row
[{ "Date": "01/06/2026", "Item": "Widget A", "Qty": 500 }]
They are told apart by whether the first element is an array.
- Matrix, no
columnsgiven — written verbatim, header row included. This is the common case
and needs no column spec at all. - Records —
columnsis required, supplying both the order and the header text. Not optional
sugar: a decoded JSON object is a Go map, which has no iteration order, so without an explicit
list the column order would vary between runs. - Matrix with
columnsgiven — columns select and re-order by position ("index": 2) rather
than by field name, which also lets a caller drop or reorder columns of a matrix it does not own.
Interface
Deliberately the same shape as xmlgen, so the two read as siblings:
// Generate renders spec against data and returns the .xlsx bytes.
func Generate(ctx context.Context, spec []byte, data any, opts ...Option) ([]byte, error)
// GenerateTo is Generate writing to w. Like xmlgen's, it does not stream: a ZIP
// central directory can only be written once the whole archive is known, so w
// receives nothing unless the whole workbook is valid.
func GenerateTo(ctx context.Context, w io.Writer, spec []byte, data any, opts ...Option) error
// Validate checks a spec without data, for load-time and CI checks.
func Validate(spec []byte) error
func WithMaxOutputBytes(n int64) Option
func WithStrictKeys() Option // a column whose `from` is absent becomes an error
data accepts the same inputs as xmlgen: []byte/json.RawMessage decoded internally with
UseNumber, or an already-decoded map[string]any. Output is bytes, never a file — the caller
streams it to a download or hands it to storage.
What it emits
Six OOXML parts, the minimum for a workbook that opens everywhere:
[Content_Types].xml, _rels/.rels, xl/workbook.xml, xl/_rels/workbook.xml.rels,
xl/worksheets/sheet1.xml, and xl/styles.xml only when a column declares a format.
Three decisions inside that, each of which is a trap if taken the other way:
- Inline strings (
<c t="inlineStr"><is><t>…</t></is></c>) rather than a shared-strings table.
Marginally larger files, but it removes a whole part and its index-consistency failure mode. - Cell text is XML-escaped and control characters replaced, the same rule
xmlgenenforces — a
value containing&must not produce a workbook Excel refuses to open. archive/ziprecords modification times, which would make output non-reproducible. Zeroing
FileHeader.Modifiedkeeps byte-stability, the propertyxmlgenalready advertises so a
generated artefact can be hashed or signed.
Values, not formulas
Aggregates are written as computed numbers rather than as =SUM(...). Common spreadsheet parsers
read a formula cell's cached value rather than its formula text, so a workbook carrying formulas
without cached results reads back empty — and computing the cache correctly means reimplementing a
formula engine. The cost is that a recipient editing a row in Excel sees no recalculation, which is
acceptable for a document that is a record rather than a working model.
Properties the output must hold
Worth pinning with tests, because each is easy to get subtly wrong and hard to notice:
- one sheet, since many readers take the first and ignore the rest
- the header in row 1, so the table is addressable as
A1:… - blank cells omitted entirely rather than written as empty strings, so a reader can distinguish
"no value" from"" - numbers written as numbers, not as text that looks numeric
- the file unzips, every declared part exists, and the sheet XML parses
Not in scope
Styling beyond number formats, charts, images, merged cells, frozen panes, multiple sheets,
formulas, and .xlsm. Each of those is a reason to reach for github.com/xuri/excelize/v2 — which
would make xlsxgen the first pure-computation module in core carrying a large third-party
dependency, against the precedent of xmlgen, httputil and shared, all of which have none. If
a styled workbook is ever genuinely required, adding an excelize-backed path behind the same
interface is the follow-up, not a reason to start there.
3. Open decisions
- Aggregates. A table often arrives alongside computed totals. Should the spec place them — as
a trailing totals row, a separate block below the table, or left to the caller to fold into the
rows first? A trailing row is the obvious default but complicates the "rows come from one path"
model. - Dates. Write them as strings, or as real Excel date serials with a
numFmt? Serials are
what makes a date sortable and formattable in Excel; strings are simpler and survive any reader
unchanged. This changes what downstream code has to handle, so it is worth deciding once. - Transposed output. A "wide" table puts labels in column A and one record per subsequent
column. Worth supporting on the write side, or is row-per-record enough? - Where the spec lives.
artifact.Loaderreturns raw[]byte, so a spec could be a registry
artifact with its own adapter — the same follow-up pending for XML templates. - CSV. Is a CSV writer wanted from the same module, or is that a separate concern?
- 主要言語
- Go
- スター
- 6
- フォーク
- 8
- 平均マージ
- 21時間 36分
- マージ済み PR(30日)
- 42
環境構築
- Dockerfile・Docker Compose ファイルなし
- プルリクエストのテンプレートあり
- コントリビューションガイドを読む
はじめの一歩
- issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
- 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
- リポジトリをフォークし、ブランチを切って変更します。
- issue 番号を参照したプルリクエストを送ります。
OpenNSW/core のほかの issue
-
難易度 2/5 1〜3時間 初心者へのやさしさ 74/100
メンテナーはふだん 1 日以内に返信
-
payment: test fixtures hardcode real gateway names (govpay/lankapay) instead of generic placeholdersオープン
難易度 2/5 1〜3時間 初心者へのやさしさ 88/100
メンテナーはふだん 1 日以内に返信
-
難易度 2/5 1〜3時間 初心者へのやさしさ 72/100
メンテナーはふだん 1 日以内に返信
-
nsw-sl cleanup Type/Improvement
難易度 3/5 1〜2日 初心者へのやさしさ 48/100
メンテナーはふだん 1 日以内に返信
-
remote: let the host inject a logger, and log with one consistent policy対応中かも @mushrafmim が 5 日前に担当しました。 オープンType/Improvement
難易度 4/5 3〜5日 初心者へのやさしさ 22/100
メンテナーはふだん 1 日以内に返信
似ている issue
-
agent-research-finding chore
難易度 2/5 1〜3時間 初心者へのやさしさ 78/100
jordansmall/spindrift#7370 ·
メンテナーはふだん 1 日以内に返信
-
☢️ Bug v3
難易度 2/5 1〜3時間 初心者へのやさしさ 82/100
メンテナーはふだん 1 日以内に返信
-
The repo's gates check is clean and runs need no swaps対応中かも @turbot-agent-fleet が今日担当しました。 オープンagent:ready
難易度 2/5 1〜3時間 初心者へのやさしさ 64/100
turbot/tailpipe#677 · コメント 2 件 ·
メンテナーはふだん 1 日以内に返信
-
needs-kind needs-triage
難易度 2/5 1〜3時間 初心者へのやさしさ 72/100
メンテナーはふだん 2 日以内に返信
-
enhancement
難易度 2/5 1〜3時間 初心者へのやさしさ 70/100
crossplane-contrib/provider-keycloak#806 ·
メンテナーはふだん 1 日以内に返信