sparsefieldsgen

Overview ¶

Command sparsefieldsgen generates typed string enums and per-list containers for v3 sparse fieldsets.

It scans a Go package for struct type declarations that carry either of two markers on their doc comment:

• sparsefields:gen [=CustomTypeName] Marks an entity struct (e.g. Task, Project). Emits a named string type plus one constant per JSON-tagged field on the struct (same-package embedded structs are flattened).

• sparsefields:list [=CustomTypeName] Marks a *ListResponse struct. Emits a typed container struct (e.g. TaskListFields) whose fields mirror the response's main slice and each entry of its Included sub-struct, plus an `apply(url.Values)` method that writes the appropriate fields[entityKey]=… query parameters via twapi.ApplySparseFields.

• sparsefields:get [=CustomTypeName] Marks a *GetResponse struct — the single-entity counterpart of a list. Emits the same kind of container (e.g. TaskGetFields), with one slot for the response's entity field and one per entry of its Included sub-struct. Single-entity v3 endpoints share their query bindings with the plural endpoint, so the entity key of the main slot is the *plural* entity name rather than the response's singular envelope key ("message" decodes the payload, but the selection is fields[messages]=…). The generator takes that key from the entity's own marked *ListResponse, so a get and its list can never disagree.

Two more markers apply to individual fields of a marked response:

• sparsefields:skip Excludes the field from slot generation. Used when a response's main slice holds relationships rather than a sparse-fields-capable entity (e.g. SearchResponse.Items).

• sparsefields:key=entityName Overrides the fields[...] entity key for that slot. For list slots the key otherwise defaults to the field's json tag, which is right whenever the response envelope key matches the entity name the API recognises. A handful of endpoints break that assumption — /projects/api/v3/projects/budgets.json wraps its payload in "budgets" while the entity is "projectBudgets" — and this marker is how they declare the divergence. On the main slot of a get response it overrides the key inherited from the entity's list.

Usage (typically invoked via //go:generate from the target package):

//go:generate go run github.com/teamwork/twapi-go-sdk/internal/sparsefieldsgen

By default it scans the current working directory and writes `sparse_fields_gen.go` next to the sources. Both can be overridden with the -src and -out flags.