Documentation
¶
Index ¶
- Constants
- func IsNull[T any](v T) bool
- func IsOmitted(v any) bool
- func MarshalObject[T ParamStruct](f T, underlying any) ([]byte, error)
- func MarshalUnion[T ParamStruct](metadata T, variants ...any) ([]byte, error)
- func MarshalWithExtras[T ParamStruct, R any](f T, underlying any, extras map[string]R) ([]byte, error)
- func NullMap[MapT ~map[string]T, T any]() MapT
- func NullSlice[SliceT ~[]T, T any]() SliceT
- func NullStruct[T ParamStruct, PtrT InferPtr[T]]() T
- func Override[T ParamStruct, PtrT InferPtr[T]](v any) T
- type APIObject
- type APIUnion
- type EncodedAsDate
- type InferPtr
- type Opt
- type Optional
- type ParamNullable
- type ParamStruct
Constants ¶
const Omit forceOmit = -1
Omit can be used with [metadata.SetExtraFields] to ensure that a required field is omitted. This is useful as an escape hatch for when a required is unwanted for some unexpected reason.
Variables ¶
This section is empty.
Functions ¶
func IsNull ¶
IsNull returns true if v was set to the JSON value null.
To set a param to null use NullStruct, Null, NullMap, or NullSlice depending on the type of v.
IsNull returns false if the value is omitted.
func IsOmitted ¶
IsOmitted returns true if v is the zero value of its type.
If IsOmitted is true, and the field uses a `json:"...,omitzero"` tag, the field will be omitted from the request.
If v is set explicitly to the JSON value "null", IsOmitted returns false.
func MarshalObject ¶
func MarshalObject[T ParamStruct](f T, underlying any) ([]byte, error)
MarshalObject uses a shimmed 'encoding/json' from Go 1.24, to support the 'omitzero' tag
Stability for the API of MarshalObject is not guaranteed.
func MarshalUnion ¶
func MarshalUnion[T ParamStruct](metadata T, variants ...any) ([]byte, error)
MarshalUnion uses a shimmed 'encoding/json' from Go 1.24, to support the 'omitzero' tag
Stability for the API of MarshalUnion is not guaranteed.
func MarshalWithExtras ¶
func MarshalWithExtras[T ParamStruct, R any](f T, underlying any, extras map[string]R) ([]byte, error)
MarshalWithExtras is used to marshal a struct with additional properties.
Stability for the API of MarshalWithExtras is not guaranteed.
func NullMap ¶ added in v1.7.0
NullMap returns a non-nil map with a length of 0. When used with MarshalObject or MarshalUnion, it will be marshaled as null.
It is unspecified behavior to mutate the map returned by NullMap.
func NullSlice ¶ added in v1.7.0
func NullSlice[SliceT ~[]T, T any]() SliceT
NullSlice returns a non-nil slice with a length of 0. When used with MarshalObject or MarshalUnion, it will be marshaled as null.
It is unspecified behavior to mutate the slice returned by NullSlice.
func NullStruct ¶
func NullStruct[T ParamStruct, PtrT InferPtr[T]]() T
NullStruct is used to set a struct to the JSON value null. Check for null structs with IsNull.
Only the first type parameter should be provided, the type PtrT will be inferred.
json.Marshal(param.NullStruct[MyStruct]()) -> 'null'
func Override ¶
func Override[T ParamStruct, PtrT InferPtr[T]](v any) T
Override replaces the value of a struct with any type.
Only the first type parameter should be provided, the type PtrT will be inferred.
It's often useful for providing raw JSON
param.Override[MyStruct](json.RawMessage(`{"foo": "bar"}`))
The public fields of the returned struct T will be unset.
To override a specific field in a struct, use its [SetExtraFields] method.
Types ¶
type APIObject ¶
type APIObject struct {
// contains filtered or unexported fields
}
APIObject should be embedded in api object fields, preferably using an alias to make private
func (APIObject) ExtraFields ¶
ExtraFields returns the extra fields added to the JSON object.
func (APIObject) Overrides ¶
Overrides returns the value of the struct when it is created with Override, the second argument helps differentiate an explicit null.
func (*APIObject) SetExtraFields ¶
SetExtraFields adds extra fields to the JSON object.
SetExtraFields will override any existing fields with the same key. For security reasons, ensure this is only used with trusted input data.
To intentionally omit a required field, use Omit.
foo.SetExtraFields(map[string]any{"bar": Omit})
If the struct already contains the field ExtraFields, then this method will have no effect.
type APIUnion ¶
type APIUnion struct {
// contains filtered or unexported fields
}
APIUnion should be embedded in all api unions fields, preferably using an alias to make private
func (APIUnion) ExtraFields ¶
ExtraFields returns the extra fields added to the JSON object.
func (APIUnion) Overrides ¶
Overrides returns the value of the struct when it is created with Override, the second argument helps differentiate an explicit null.
func (*APIUnion) SetExtraFields ¶
SetExtraFields adds extra fields to the JSON object.
SetExtraFields will override any existing fields with the same key. For security reasons, ensure this is only used with trusted input data.
To intentionally omit a required field, use Omit.
foo.SetExtraFields(map[string]any{"bar": Omit})
If the struct already contains the field ExtraFields, then this method will have no effect.
type EncodedAsDate ¶
EncodedAsDate is not be stable and shouldn't be relied upon
func (EncodedAsDate) MarshalJSON ¶
func (m EncodedAsDate) MarshalJSON() ([]byte, error)
type InferPtr ¶
type InferPtr[T ParamStruct] interface { *T // contains filtered or unexported methods }
This is an implementation detail and should never be explicitly set.
type Opt ¶
type Opt[T comparable] struct { Value T // contains filtered or unexported fields }
Opt represents an optional parameter of type T. Use the Opt.Valid method to confirm.
func NewOpt ¶
func NewOpt[T comparable](v T) Opt[T]
func Null ¶
func Null[T comparable]() Opt[T]
Null creates optional field with the JSON value "null".
To set a struct to null, use NullStruct.
func (Opt[T]) MarshalJSON ¶
func (Opt[T]) MarshalJSONWithTimeLayout ¶
MarshalJSONWithTimeLayout is necessary to bypass the internal caching performed by json.Marshal. Prefer to use Opt.MarshalJSON instead.
This function requires that the generic type parameter of Opt is not time.Time.
func (*Opt[T]) UnmarshalJSON ¶
type Optional ¶
type Optional interface {
Valid() bool
// contains filtered or unexported methods
}
This interface is useful for internal purposes.
type ParamNullable ¶
type ParamNullable interface {
// contains filtered or unexported methods
}
ParamNullable encapsulates all structs in parameters, and all Opt types in parameters.
type ParamStruct ¶
ParamStruct represents the set of all structs that are used in API parameters, by convention these usually end in "Params" or "Param".
Source Files