Documentation
¶
Overview ¶
Package field is the canonical logical field vocabulary shared by the resource generator, the admin data plane, and (as later issues land) OpenAPI, the TypeScript client, and generated forms.
A Kind is a domain type, not a SQL column and not a wire string. Two projections hang off each kind:
- CLI tokens accepted by `gombit make resource` (resourcegen). Historical tokens stay valid: `int`, `bool`, and `time` parse as integer, boolean, and datetime. `time` is a datetime alias. Clock time is the `time_of_day` token, so existing resources keep generating time.Time.
- Admin meta strings (`integer`, `boolean`, `datetime`, `relation`, …). Finer kinds share a widget when the admin UI does not distinguish them yet: integer64 and unsigned both emit `integer`.
Adding a kind ¶
- Add a Kind constant and one catalog entry in this file.
- Set GoType, CLI tokens, AdminWire, and the capability flags.
- Set GeneratorReady only when resourcegen emits the kind. Until then `gombit make resource` rejects the token with a "not generated yet" error.
- If the admin widget string is new, the admin SPA must learn it in the same change. Reusing an existing AdminWire needs no SPA change. An empty AdminWire means no widget yet: the admin leaves such columns out of its resources.
- Extend the doc table in docs/fields.md.
A relation cardinality is not a new Kind. Add a RelationKind, a relationCaps row, and that token on the Relation catalog entry. Resourcegen still has a switch arm per cardinality when it emits the association; a catalog row alone does not.
Do not add a parallel type list in resourcegen or admin. Those packages project this catalog. Capability flags on the spec are the filter, search, sort, and aggregate policy both generators run.
Index ¶
- func AdminWires() []string
- func AllowsAggregate(k Kind, rel RelationKind) bool
- func AllowsFilter(k Kind, rel RelationKind) bool
- func AllowsSearch(k Kind, rel RelationKind) bool
- func AllowsSort(k Kind, rel RelationKind) bool
- func FormatConstraints(c Constraints) string
- func FormatRejects(format, s string) bool
- func IsAdminWire(s string) bool
- func ParseCLI(token string) (Kind, RelationKind, bool)
- func PreferredGeneratorTokens() []string
- type Constraints
- type Kind
- type RelationKind
- type Spec
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AdminWires ¶
func AdminWires() []string
AdminWires returns the closed admin meta type set, in first-seen catalog order.
func AllowsAggregate ¶
func AllowsAggregate(k Kind, rel RelationKind) bool
AllowsAggregate reports whether SUM/AVG/MIN/MAX apply to this column.
func AllowsFilter ¶
func AllowsFilter(k Kind, rel RelationKind) bool
AllowsFilter reports whether an exact-match list filter can target this field.
func AllowsSearch ¶
func AllowsSearch(k Kind, rel RelationKind) bool
AllowsSearch reports whether ?search= can LIKE this field.
func AllowsSort ¶
func AllowsSort(k Kind, rel RelationKind) bool
AllowsSort reports whether the field maps to one orderable column.
func FormatConstraints ¶
func FormatConstraints(c Constraints) string
FormatConstraints renders c as a validate tag value. Empty c is "".
func FormatRejects ¶
FormatRejects reports whether Huma 2.39.1 validateFormat rejects s for format. An unrecognized format is a no-op. uri-reference, iri-reference, uri-template, json-pointer, and regex accept "".
func IsAdminWire ¶
IsAdminWire reports whether s is an admin meta type string.
func ParseCLI ¶
func ParseCLI(token string) (Kind, RelationKind, bool)
ParseCLI parses a resource-grammar type token (no arguments). The bool is false when the token is not in the vocabulary. A recognized kind may still have GeneratorReady false; callers that emit code must check that.
Relation tokens (`belongs_to`, `has_many`, `many_to_many`) return KindRelation and the relation kind.
func PreferredGeneratorTokens ¶
func PreferredGeneratorTokens() []string
PreferredGeneratorTokens is the historical scalar grammar printed when a type token is unknown. Relation tokens are a separate grammar production.
Types ¶
type Constraints ¶
type Constraints struct {
Min string
Max string
MaxLength int
Pattern string
Default string
// Enum is the allowed stored values for a string column. The GORM schema
// stores an enum as a varchar, so this tag is how gombit generate recovers
// them. Label is the display text for each value, in the same order.
// Empty means each label equals its stored value.
Enum []string
Label []string
}
Constraints is the declarative validation carried on a model field, separate from the gombit policy tag. The generator writes it as a `validate` struct tag (semicolon-separated, so a pattern may contain commas). gombit generate and the admin meta reader both parse that tag.
func ParseConstraints ¶
func ParseConstraints(tag string) (Constraints, error)
ParseConstraints parses a validate tag value. An empty tag is an empty Constraints. Unknown keys and empty values are errors.
type Kind ¶
type Kind string
Kind is one logical field kind.
const ( String Kind = "string" Text Kind = "text" Integer Kind = "integer" Integer64 Kind = "integer64" Unsigned Kind = "unsigned" Float Kind = "float" Decimal Kind = "decimal" Boolean Kind = "boolean" Date Kind = "date" DateTime Kind = "datetime" // TimeOfDay is a clock time. It is not the `time` CLI token; that token // remains a datetime alias so existing resources keep generating time.Time. TimeOfDay Kind = "time" Duration Kind = "duration" UUID Kind = "uuid" JSON Kind = "json" Email Kind = "email" URL Kind = "url" Slug Kind = "slug" IP Kind = "ip" Enum Kind = "enum" // File and Image are storage-backed: the column holds an object key // (types.File, types.Image), the bytes live in App.Storage(). Their // admin widgets upload, preview, and remove files. File Kind = "file" Image Kind = "image" Relation Kind = "relation" )
func KindFromGo ¶
KindFromGo infers a kind from a Go field type. dataType is the GORM data type name (used to tell string columns from text columns). Pointers are unwrapped. This is the registration-time inference the admin uses; the returned kind's AdminWire is the meta type.
func SemanticKind ¶
SemanticKind recovers email, url, ip, or slug from model tags. format is the format struct tag. tagPattern is the pattern struct tag make resource writes for a slug. validatePattern is a user regex and is not a kind: a string whose regex happens to be the slug alphabet stays a string.
type RelationKind ¶
type RelationKind string
RelationKind is the cardinality of a KindRelation field.
const ( RelBelongsTo RelationKind = "belongs_to" RelHasMany RelationKind = "has_many" RelManyToMany RelationKind = "many_to_many" RelOneToOne RelationKind = "one_to_one" )
type Spec ¶
type Spec struct {
Kind Kind
// GoType is the generated Go type for a scalar the generator emits.
// Empty for relations and for kinds that are not generated yet.
GoType string
// GeneratorReady is true when `gombit make resource` emits this kind.
GeneratorReady bool
// CLITokens are accepted by the resource grammar. The first entry is the
// token printed in "supported types" errors. Empty means the kind is in
// the vocabulary but has no grammar token yet.
CLITokens []string
// AdminWire is the admin meta `type` string. Empty means the kind has no
// admin widget yet. Several kinds may share one wire.
AdminWire string
Filterable bool
Searchable bool
Sortable bool
Aggregatable bool
}
Spec is the single definition of a kind: storage, generator readiness, and the two projections.
Source Files