feat(xlsxgen): generate spreadsheets from a declarative spec and structured data
Los mantenedores suelen responder en 1 día
@sthanikan2000 ya está trabajando en esto.
Desde el 17/9/2026.
Evaluación
Este issue todavía no se ha evaluado.
Descripción
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?
- Lenguaje dominante
- Go
- Estrellas
- 6
- Forks
- 8
- Merge medio
- 21 h 36 min
- PR fusionados (30 d)
- 42
Preparar el entorno
- Sin Dockerfile ni archivo de Docker Compose
- Tiene una plantilla de pull request
- Leer la guía de contribución
Primeros pasos
- Lee el issue completo y luego la guía de contribución del proyecto.
- Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
- Haz un fork del repositorio y trabaja en una rama.
- Abre un pull request que haga referencia al número del issue.
Más de OpenNSW/core
-
Dificultad 2/5 1-3 horas Aptitud para principiantes 74/100
Los mantenedores suelen responder en 1 día
-
payment: test fixtures hardcode real gateway names (govpay/lankapay) instead of generic placeholdersAbierto
Dificultad 2/5 1-3 horas Aptitud para principiantes 88/100
Los mantenedores suelen responder en 1 día
-
Dificultad 2/5 1-3 horas Aptitud para principiantes 72/100
Los mantenedores suelen responder en 1 día
-
nsw-sl cleanup Type/Improvement
Dificultad 3/5 1-2 días Aptitud para principiantes 48/100
Los mantenedores suelen responder en 1 día
-
remote: let the host inject a logger, and log with one consistent policyPosiblemente ocupada @mushrafmim la tomó hace 5 días. AbiertoType/Improvement
Dificultad 4/5 3-5 días Aptitud para principiantes 22/100
Los mantenedores suelen responder en 1 día
Todos los issues de OpenNSW/core
Issues similares
-
agent-research-finding chore
Dificultad 2/5 1-3 horas Aptitud para principiantes 78/100
jordansmall/spindrift#7370 ·
Los mantenedores suelen responder en 1 día
-
☢️ Bug v3
Dificultad 2/5 1-3 horas Aptitud para principiantes 82/100
Los mantenedores suelen responder en 1 día
-
The repo's gates check is clean and runs need no swapsPosiblemente ocupada @turbot-agent-fleet la tomó hoy. Abiertoagent:ready
Dificultad 2/5 1-3 horas Aptitud para principiantes 64/100
turbot/tailpipe#677 · 2 comentarios ·
Los mantenedores suelen responder en 1 día
-
needs-kind needs-triage
Dificultad 2/5 1-3 horas Aptitud para principiantes 72/100
Los mantenedores suelen responder en 2 días
-
enhancement
Dificultad 2/5 1-3 horas Aptitud para principiantes 70/100
crossplane-contrib/provider-keycloak#806 ·
Los mantenedores suelen responder en 1 día