Documentation
¶
Overview ¶
Package types holds framework value types that are shared by generated models, handler DTOs, and the admin data plane. They exist so a single Go type flows through the model, the Huma contract (OpenAPI/TS client), and GORM persistence without the DTO drifting from the model (see #222 / #218).
Index ¶
- Constants
- func DecimalWithin(d Decimal, min, max string) error
- type Date
- func (Date) GormDataType() string
- func (d Date) IsZero() bool
- func (d Date) MarshalJSON() ([]byte, error)
- func (d Date) MarshalText() ([]byte, error)
- func (d *Date) Scan(src any) error
- func (d Date) String() string
- func (d Date) Time() time.Time
- func (d *Date) UnmarshalJSON(b []byte) error
- func (d *Date) UnmarshalText(b []byte) error
- func (d Date) Value() (driver.Value, error)
- type Decimal
- type Duration
- func (d Duration) Duration() time.Duration
- func (Duration) GormDataType() string
- func (d Duration) MarshalJSON() ([]byte, error)
- func (d Duration) MarshalText() ([]byte, error)
- func (d *Duration) Scan(src any) error
- func (d Duration) String() string
- func (d *Duration) UnmarshalJSON(b []byte) error
- func (d *Duration) UnmarshalText(b []byte) error
- func (d Duration) Value() (driver.Value, error)
- type JSON
- type NullJSON
- type TimeOfDay
- func (TimeOfDay) GormDataType() string
- func (t TimeOfDay) MarshalJSON() ([]byte, error)
- func (t TimeOfDay) MarshalText() ([]byte, error)
- func (t *TimeOfDay) Scan(src any) error
- func (t TimeOfDay) String() string
- func (t *TimeOfDay) UnmarshalJSON(b []byte) error
- func (t *TimeOfDay) UnmarshalText(b []byte) error
- func (t TimeOfDay) Value() (driver.Value, error)
Constants ¶
const DecimalPattern = `^-?[0-9]+(\.[0-9]+)?$`
DecimalPattern is the create-body spelling of a decimal. Huma enforces it on the string schema. Bounds and defaults must use the same token so the form, the magnitude check, and the request accept one spelling.
const TimeOfDayPattern = `^([01][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9](Z|[+-]([01][0-9]|2[0-3]):[0-5][0-9])?)?$`
TimeOfDayPattern is the one clock grammar. Huma's format "time" accepts HH:MM:SS and a numeric offset, and rejects HH:MM. This pattern accepts all three, which is what UnmarshalText parses and stores as HH:MM:SS. The generator, the admin write, and the type all use it. Format "time" is not that grammar.
Variables ¶
This section is empty.
Functions ¶
func DecimalWithin ¶ added in v0.3.0
DecimalWithin reports whether d is inside the optional bounds. Empty min or max is unbounded on that side. Bounds are decimal magnitudes: Huma's minimum/maximum apply only to number and integer schemas, and Decimal's schema is a string.
Types ¶
type Date ¶ added in v0.3.0
type Date struct {
// contains filtered or unexported fields
}
Date is a calendar date. It is not a timestamp and not a time of day.
JSON and text are "YYYY-MM-DD". GORM's default column type is "date" (Postgres DATE, MySQL DATE, SQLite TEXT affinity). Value returns that calendar day as UTC midnight so PostgreSQL can encode it as a binary date. The zero Date is not a stored value: Value and MarshalJSON reject it. JSON null is a nil *Date.
func NewDate ¶ added in v0.3.0
NewDate returns the calendar date of t in UTC, dropping the clock time.
func (Date) GormDataType ¶ added in v0.3.0
GormDataType tells GORM the column family when a model field omits an explicit type tag. Generated models also set gorm:"type:date".
func (Date) MarshalJSON ¶ added in v0.3.0
MarshalJSON encodes the date as "YYYY-MM-DD". The zero date has no JSON form: "0001-01-01" is that zero value, and publishing it would round-trip through Value as an error. JSON null is a nil *Date.
func (Date) MarshalText ¶ added in v0.3.0
MarshalText implements encoding.TextMarshaler.
func (*Date) Scan ¶ added in v0.3.0
Scan implements sql.Scanner. Drivers return a time.Time, a date string, or nil.
func (*Date) UnmarshalJSON ¶ added in v0.3.0
UnmarshalJSON accepts null, "YYYY-MM-DD", or an RFC3339 timestamp (the date part is kept). The timestamp form is what admin coercion produces when it JSON-encodes a time.Time.
func (*Date) UnmarshalText ¶ added in v0.3.0
UnmarshalText implements encoding.TextUnmarshaler.
func (Date) Value ¶ added in v0.3.0
Value implements driver.Valuer. The stored value is UTC midnight on the calendar day, which is what PostgreSQL's binary date codec accepts. A zero Date is not SQL NULL: NULL is a nil *Date, and the zero value is refused so a required column does not silently insert NULL.
type Decimal ¶
Decimal is a fixed-point decimal for money and other exact numeric values.
It wraps shopspring/decimal.Decimal, so it inherits exact arithmetic, JSON (a quoted string — no float rounding), text (un)marshaling, and the database sql.Scanner / driver.Valuer used by GORM. On top of that it advertises an OpenAPI schema (a string with format "decimal") via huma.SchemaProvider, so the generated OpenAPI document and TypeScript client see a string instead of an opaque object. Use the gorm tag `type:decimal(p,s)` on the model field to pin precision/scale for the migration (gombit make resource emits decimal(19,4) by default).
func MustDecimal ¶ added in v0.3.0
MustDecimal parses s and panics if it is not a decimal. Generated mappers use it for a default the generator already validated.
func NewDecimalFromString ¶
NewDecimalFromString parses a decimal string (e.g. "19.99").
func (Decimal) GormDataType ¶
GormDataType tells GORM the default column family when a model field omits an explicit `type:` tag. Generated models pin exact precision with `gorm:"type:decimal(19,4)"`, which takes precedence over this default.
type Duration ¶ added in v0.3.0
type Duration struct {
// contains filtered or unexported fields
}
Duration is a span of time. JSON and text use Go's duration syntax ("1h30m", "300ms", "0s", "-1s"), which is what Huma's format "duration" accepts. The stored column is a signed bigint of nanoseconds so SQLite, PostgreSQL, and MySQL sort the same integer. A zero Duration is "0s" and is stored. SQL NULL is a nil *Duration.
func MustDuration ¶ added in v0.3.0
MustDuration parses s and panics if it is not a duration. Generated mappers use it for a default the generator already validated.
func ParseDuration ¶ added in v0.3.0
ParseDuration parses a Go duration string.
func (Duration) GormDataType ¶ added in v0.3.0
GormDataType tells GORM the column family when a model field omits an explicit type tag. Generated models also set gorm:"type:bigint".
func (Duration) MarshalJSON ¶ added in v0.3.0
MarshalJSON encodes the canonical duration string. Zero is "0s".
func (Duration) MarshalText ¶ added in v0.3.0
MarshalText implements encoding.TextMarshaler.
func (*Duration) Scan ¶ added in v0.3.0
Scan implements sql.Scanner. Drivers return an integer nanosecond count, or the duration text.
func (Duration) String ¶ added in v0.3.0
String returns the canonical Go duration spelling. "1h30m" becomes "1h30m0s".
func (*Duration) UnmarshalJSON ¶ added in v0.3.0
UnmarshalJSON accepts null or a duration string.
func (*Duration) UnmarshalText ¶ added in v0.3.0
UnmarshalText implements encoding.TextUnmarshaler. An empty string is rejected: zero is "0s", and "" is not that span.
type JSON ¶ added in v0.3.0
type JSON json.RawMessage
JSON is a JSON object or array stored as text. Null is not a document: UnmarshalJSON and Schema reject it. Optional columns use NullJSON, because Huma validates anyOf before it honors a nullable tag, so one schema cannot both reject null (required) and allow it (optional).
func (JSON) GormDataType ¶ added in v0.3.0
GormDataType tells GORM the column family when a model field omits an explicit type tag. Generated models also set gorm:"type:text".
func (JSON) MarshalJSON ¶ added in v0.3.0
MarshalJSON returns null for a nil document and the raw document otherwise.
func (JSON) Schema ¶ added in v0.3.0
Schema implements huma.SchemaProvider. Null is not a member: a required field rejects JSON null. Optional fields use NullJSON.
func (*JSON) UnmarshalJSON ¶ added in v0.3.0
UnmarshalJSON stores a JSON object or array. Null is rejected.
type NullJSON ¶ added in v0.3.0
type NullJSON JSON
NullJSON is a JSON object, a JSON array, or null. Generated optional json columns use it so a stored NULL validates against the published contract.
func (NullJSON) GormDataType ¶ added in v0.3.0
GormDataType tells GORM the column family when a model field omits an explicit type tag. Generated models also set gorm:"type:text".
func (NullJSON) MarshalJSON ¶ added in v0.3.0
MarshalJSON returns null for a nil document and the raw document otherwise.
func (NullJSON) Schema ¶ added in v0.3.0
Schema implements huma.SchemaProvider. Object, array, and null are members.
func (*NullJSON) UnmarshalJSON ¶ added in v0.3.0
UnmarshalJSON stores a JSON object or array. Null clears the value.
type TimeOfDay ¶ added in v0.3.0
type TimeOfDay struct {
// contains filtered or unexported fields
}
TimeOfDay is a clock time with no date and no zone. JSON and text are "HH:MM:SS". "HH:MM" and a time with a numeric offset ("15:04:05+07:00", the second form Huma's format "time" accepts) are read as that clock and stored as "HH:MM:SS". The offset is not applied: a time of day has no date to convert.
The zero TimeOfDay is midnight, which is a real clock time, and Value stores it. SQL NULL is a nil *TimeOfDay. The column is char(8) so SQLite, PostgreSQL, and MySQL share one sortable text form.
func MustTimeOfDay ¶ added in v0.3.0
MustTimeOfDay parses s and panics if it is not a clock time. Generated mappers use it for a default the generator already validated.
func ParseTimeOfDay ¶ added in v0.3.0
ParseTimeOfDay parses a clock time.
func (TimeOfDay) GormDataType ¶ added in v0.3.0
GormDataType tells GORM the column family when a model field omits an explicit type tag. Generated models also set gorm:"type:char(8)".
func (TimeOfDay) MarshalJSON ¶ added in v0.3.0
MarshalJSON encodes the clock as "HH:MM:SS".
func (TimeOfDay) MarshalText ¶ added in v0.3.0
MarshalText implements encoding.TextMarshaler.
func (*TimeOfDay) UnmarshalJSON ¶ added in v0.3.0
UnmarshalJSON accepts null, "HH:MM:SS", "HH:MM", or a clock with a numeric offset.
func (*TimeOfDay) UnmarshalText ¶ added in v0.3.0
UnmarshalText implements encoding.TextUnmarshaler. An empty string is rejected: midnight is "00:00:00", and "" is not that clock. The accepted spellings are TimeOfDayPattern, the same pattern the request and the admin write enforce.
Source Files