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.
- 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" 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