optionalnullable

Documentation

Index

• type OptionalNullable
  • func From[T any](value *T) OptionalNullable[T]
  • func (n OptionalNullable[T]) Get() (*T, bool)
  • func (n OptionalNullable[T]) GetOrZero() (T, bool)
  • func (n OptionalNullable[T]) GetUntyped() (interface{}, bool)
  • func (n OptionalNullable[T]) IsNull() bool
  • func (n OptionalNullable[T]) IsSet() bool
  • func (n OptionalNullable[T]) MarshalJSON() ([]byte, error)
  • func (n *OptionalNullable[T]) Set(value *T)
  • func (n *OptionalNullable[T]) UnmarshalJSON(data []byte) error
  • func (n *OptionalNullable[T]) Unset()
• type OptionalNullableInterface
  • func AsOptionalNullable(v reflect.Value) (OptionalNullableInterface, bool)

Types

type OptionalNullable

type OptionalNullable[T any] map[bool]*T

OptionalNullable represents a field that can distinguish between three states: 1. Set to a value: field is present with a non-nil value 2. Set to nil: field is present but explicitly set to null in JSON 3. Unset: field is omitted from JSON entirely

This type is designed to work with JSON marshaling/unmarshaling and supports the `omitempty` struct tag to properly omit unset fields from JSON output.

Usage:

type User struct {
    Name  OptionalNullable[string] `json:"name,omitempty"`
    Age   OptionalNullable[int]    `json:"age,omitempty"`
    Tags  OptionalNullable[[]string] `json:"tags,omitempty"`
}

// Set to value
name := "John"
user.Name = From(&name)

// Set to nil (will appear as "name": null in JSON)
user.Name = From[string](nil)

// Leave unset (will be omitted from JSON with omitempty)
user := User{}

WARNING: Do NOT use *OptionalNullable[T] as a field type. Always use OptionalNullable[T] directly. Using *OptionalNullable[T] will break the omitempty behavior and JSON marshaling.

The type is implemented as a map[bool]*T where: - nil map represents unset state - Map with true key represents set state (value may be nil)

func From

func From[T any](value *T) OptionalNullable[T]

From creates a new OptionalNullable with the given value. Pass nil to create a OptionalNullable that is set to null. Pass a pointer to a value to create a OptionalNullable with that value.

Examples:

hello := "hello"
From(&hello)  // set to "hello"
From[string](nil)       // set to null

func (OptionalNullable[T]) Get

func (n OptionalNullable[T]) Get() (*T, bool)

Get returns the internal pointer and whether the field was set.

Return values: - (ptr, true): field was set (ptr may be nil if set to null) - (nil, false): field was unset/omitted

This method provides direct access to the internal pointer representation.

func (OptionalNullable[T]) GetOrZero

func (n OptionalNullable[T]) GetOrZero() (T, bool)

GetOrZero returns the value and whether it was set.

Return values: - (value, true): field was set to a non-nil value - (zero, true): field was explicitly set to nil - (zero, false): field was unset/omitted

Examples:

val, ok := nullable.GetOrZero()
if !ok {
    // Field was unset/omitted
} else if nullable.IsNull() {
    // Field was explicitly set to null
} else {
    // Field has a value: val
}

func (OptionalNullable[T]) GetUntyped

func (n OptionalNullable[T]) GetUntyped() (interface{}, bool)

GetUntyped returns the value as interface{} and whether it was set. This is useful for reflection-based code that needs to work with the value without knowing the specific type T.

Return values: - (value, true): field was set to a non-nil value - (nil, true): field was explicitly set to nil - (nil, false): field was unset/omitted

func (OptionalNullable[T]) IsNull

func (n OptionalNullable[T]) IsNull() bool

IsNull returns true if the OptionalNullable is explicitly set to nil. Returns false if the OptionalNullable is unset or has a value.

Note: This differs from traditional null checks because unset fields return false, not true. Use IsSet() to check if a field was provided.

func (OptionalNullable[T]) IsSet

func (n OptionalNullable[T]) IsSet() bool

IsSet returns true if the OptionalNullable has been explicitly set (to either a value or nil). Returns false if the OptionalNullable is unset (omitted from JSON).

This is the key method for distinguishing between: - Set to nil: IsSet() = true, IsNull() = true - Unset: IsSet() = false, IsNull() = false

func (OptionalNullable[T]) MarshalJSON

func (n OptionalNullable[T]) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

Behavior: - Unset fields: omitted from JSON when struct field has omitempty tag - Null fields: serialized as "null" - Value fields: serialized as the actual value

The omitempty behavior works because an empty map is considered a zero value by Go's JSON package.

func (*OptionalNullable[T]) Set

func (n *OptionalNullable[T]) Set(value *T)

Set sets the OptionalNullable to the given value pointer. Pass nil to set the field to null. Pass a pointer to a value to set the field to that value.

Examples:

nullable.Set(ptrFrom("hello"))  // set to "hello"
nullable.Set(nil)               // set to null

func (*OptionalNullable[T]) UnmarshalJSON

func (n *OptionalNullable[T]) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler.

Behavior: - "null" in JSON: sets the field to null (IsSet=true, IsNull=true) - Any other value: sets the field to that value (IsSet=true, IsNull=false) - Missing from JSON: field remains unset (IsSet=false, IsNull=false)

func (*OptionalNullable[T]) Unset

func (n *OptionalNullable[T]) Unset()

Unset removes the value, making the field unset/omitted. After calling Unset(), IsSet() will return false and the field will be omitted from JSON output when using omitempty.

type OptionalNullableInterface

type OptionalNullableInterface interface {
	GetUntyped() (interface{}, bool)
}

NullableInterface defines the interface that all OptionalNullable[T] types implement. This interface provides untyped access to optional nullable values for reflection-based code.

func AsOptionalNullable

func AsOptionalNullable(v reflect.Value) (OptionalNullableInterface, bool)

AsOptionalNullable attempts to convert a reflect.Value to a OptionalNullableInterface. This is a helper function for reflection-based code that needs to check if a value implements the optional nullable interface pattern.

Returns: - (nullable, true): if the value implements OptionalNullableInterface - (nil, false): if the value does not implement OptionalNullableInterface

Example usage:

if nullable, ok := AsOptionalNullable(reflectValue); ok {
    if value, isSet := nullable.GetUntyped(); isSet {
        // Handle the nullable value
    }
}