Help us shape the future of Go! Take the 2026 Go Developer Survey

value

package
v0.6.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 3, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Overview

Package value distinguishes absent fields, explicit nulls, and present values. Optional[Nullable[T]] represents all three states without losing T's type.

Index

Constants

View Source 
const (
	JSONMaxBytes        = jsonwire.MaxBytes
	JSONMaxDepth        = jsonwire.MaxDepth
	JSONMaxNodes        = jsonwire.MaxNodes
	JSONMaxNumberDigits = decimal.MaxDigits
)

Variables

This section is empty.

Functions

func CheckJSONKeys 

func CheckJSONKeys[K comparable](ctx context.Context, keys []string, limits JSONKeyLimits) error

CheckJSONKeys validates object names before decoding their containing value. It preserves K, rejects noncanonical aliases and duplicate decoded identities, and shares native codec rules with typed storage snapshots. Callers keep the names unchanged until return. Codecs must be deterministic, bounded and must not retain borrowed input. Cancellation waits for active codec work to finish.

func EncodeJSON 

func EncodeJSON[T any](ctx context.Context, input T, limits JSONEncodingLimits) ([]byte, error)

EncodeJSON encodes an owned, bounded JSON document with ordinary Go field/tag semantics. It preserves transport string NULs and exact json.Number values. Optional/Nullable values share the same input inspection as typed snapshots. It returns no bytes on failure. It does not infer a DTO schema; contract.JSON adds the generated schema checks before a transport can publish these bytes. Panic and Goexit in codecs become internal faults. Cancellation never abandons a codec that is still running or retaining resources.

func IsNullableType 

func IsNullableType[T any]() bool

IsNullableType reports whether T carries Foundry's nullable-value contract. It inspects type capability without invoking methods or reading a value.

func IsOptionalType 

func IsOptionalType[T any]() bool

IsOptionalType reports whether T carries Foundry's optional-value contract. It checks type capability without invoking methods or reading a value.

func SupportsJSONKeys 

func SupportsJSONKeys[K comparable]() bool

SupportsJSONKeys checks whether K supports the framework's native map codecs. It invokes no value methods. A comparable type alone does not imply JSON object-key support; Go's JSON/text method rules still apply.

Types

type JSON 

type JSON[T any] struct {
	// contains filtered or unexported fields
}

JSON stores an immutable, typed JSON snapshot. Decode returns fresh values, including fresh maps/slices. Canonical equality matches JSONB value equality; object key order and numeric spelling are not retained. The zero value is invalid, not JSON null or SQL NULL. Use JSON[Nullable[T]] for JSON null and Nullable[JSON[T]] for a nullable SQL column.

func NewJSON 

func NewJSON[T any](input T) (JSON[T], error)

NewJSON snapshots a concrete Go value through its JSON representation. Custom JSON/text methods own their validation and must be deterministic and safe for concurrent use, preserve inputs and return owned decoded values. Construction retains only canonical text, never the input's maps or slices.

func ParseJSON 

func ParseJSON[T any](text string) (JSON[T], error)

ParseJSON validates JSON syntax, resource bounds and its concrete Go shape. Unknown/duplicate keys, missing required struct fields, invalid Unicode and nulls in non-nullable fields fail. Optional, omitempty and omitzero fields may be absent. Custom unmarshalers own the schema inside their representation.

func (JSON[T]) Decode 

func (v JSON[T]) Decode() (T, error)

Decode creates an independent T. Dynamic interface values use json.Number.

func (JSON[T]) IsJSONNull 

func (v JSON[T]) IsJSONNull() bool

IsJSONNull reports whether the stored JSON text is the null literal.

func (JSON[T]) IsZero 

func (v JSON[T]) IsZero() bool

IsZero reports whether the JSON document is uninitialized.

func (JSON[T]) MarshalJSON 

func (v JSON[T]) MarshalJSON() ([]byte, error)

MarshalJSON returns the stored JSON text as bytes, propagating Text errors.

func (JSON[T]) Text 

func (v JSON[T]) Text() (string, error)

Text returns canonical JSON for an explicit transport/codec boundary.

func (*JSON[T]) UnmarshalJSON 

func (v *JSON[T]) UnmarshalJSON(data []byte) error

UnmarshalJSON parses a bounded JSON document, replacing the receiver only on success.

type JSONEncodingLimits 

type JSONEncodingLimits struct {
	Bytes int
	Depth int
	Nodes int
	Steps int
}

JSONEncodingLimits bounds an encoded document and the native input inspection. Depth and Nodes describe JSON, with the root at depth zero. Steps separately bounds native values, indirections and declared fields visited before encoding. Bytes also bounds inspected native string/byte content, before codec execution. All limits except Depth must be positive. Depth may not exceed JSONMaxDepth. Custom codecs own their internal work and allocation; their emitted document still passes the output bounds. Callers must keep input unchanged until return.

func (JSONEncodingLimits) Validate 

func (l JSONEncodingLimits) Validate() error

Validate checks positive encoding budgets and the supported depth range.

type JSONKeyLimits 

type JSONKeyLimits struct{ Bytes, Keys int }

JSONKeyLimits bounds names supplied for one JSON object. Bytes counts decoded name bytes; Keys bounds entries. Both limits are positive. Formatting probes additionally allow only the bounded escaping overhead of a canonical name.

func (JSONKeyLimits) Validate 

func (l JSONKeyLimits) Validate() error

Validate checks that byte and key budgets are positive.

type List 

type List[T any] []T

List is a slice whose JSON form is never null: a nil or empty List encodes as [], and decoding null is rejected. Generated DTO schemas, OpenAPI and TypeScript describe it as a non-nullable array, so clients iterate it without null checks. It is an ordinary slice otherwise (len, range, append, index). Use a plain slice when null is a meaningful value.

func (List[T]) MarshalJSON 

func (l List[T]) MarshalJSON() ([]byte, error)

MarshalJSON encodes a nil List as an empty array.

func (List[T]) MarshalJSONTo 

func (l List[T]) MarshalJSONTo(encoder *jsontext.Encoder) error

MarshalJSONTo is the encoding/json/v2 form used by Foundry's encoder. It keeps the caller's options, such as rejecting invalid UTF-8, for elements.

func (*List[T]) UnmarshalJSON 

func (l *List[T]) UnmarshalJSON(data []byte) error

UnmarshalJSON rejects null and decodes elements with exact numbers.

type Nullable 

type Nullable[T any] struct {
	// contains filtered or unexported fields
}

Nullable represents database/transport null or a present T. It does not represent omission. The zero value is null; Of includes T's zero value.

func Null 

func Null[T any]() Nullable[T]

Null returns a null Nullable value.

func Of 

func Of[T any](value T) Nullable[T]

Of returns a non-null Nullable containing the supplied value, including its zero value.

func (Nullable[T]) Get 

func (v Nullable[T]) Get() (T, bool)

Get returns the stored value and whether it is non-null.

func (Nullable[T]) IsNull 

func (v Nullable[T]) IsNull() bool

IsNull reports whether the value is null.

func (Nullable[T]) MarshalJSON 

func (v Nullable[T]) MarshalJSON() ([]byte, error)

MarshalJSON encodes null or the present value as JSON.

func (*Nullable[T]) UnmarshalJSON 

func (v *Nullable[T]) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes null or a present JSON value, replacing the receiver only on success.

type Optional 

type Optional[T any] struct {
	// contains filtered or unexported fields
}

Optional represents an omitted field or a present T, including T's zero value. Its zero value is omitted. Use json:",omitzero" on enclosing DTO fields; an omitted Optional cannot serialize as a standalone JSON value.

func Set 

func Set[T any](value T) Optional[T]

Set returns a present Optional containing the supplied value, including its zero value.

func (Optional[T]) Get 

func (v Optional[T]) Get() (T, bool)

Get returns the stored value and whether it is present.

func (Optional[T]) IsSet 

func (v Optional[T]) IsSet() bool

IsSet reports whether the optional value is present.

func (Optional[T]) IsZero 

func (v Optional[T]) IsZero() bool

IsZero reports whether the optional value is omitted.

func (Optional[T]) MarshalJSON 

func (v Optional[T]) MarshalJSON() ([]byte, error)

MarshalJSON encodes a present value; an omitted value returns a missing fault and requires omitzero at its containing field.

func (*Optional[T]) UnmarshalJSON 

func (v *Optional[T]) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes a present value, rejecting null unless T supports null or is a JSON document. The receiver changes only on success.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.