types

README

types

Library for types conversion.

go get github.com/rakunlabs/types

Usage

types.Map

Map based on map[string]any and null values stay as nil.

This type not convert to base64 when marshaling, it is directly a json string.

type Train struct {
	Details types.Map `db:"details"`
}

types.RawJSON

[]byte type behind, same as json.RawMessage with scan and value methods.

type Train struct {
	Details types.RawJSON `db:"details"`
}

types.Slice[T]

Slice based on []T and null values stay as nil.

type Train struct {
	Slice types.Slice[string] `db:"slice"`
}

types.JSON[T]

For any type of json nullable value. Useful for struct values.

type Details struct {
	Name string `json:"name"`
}

type Train struct {
	Details types.JSON[Details] `db:"details"`
}

types.Null[T]

Wrapper of sql.Null[T] with additional json marshal and unmarshal methods.
It can distinguish between an explicit null value and an empty or missing request.

types.Time and types.Null[types.Time]

Wrapper of time.Time with additional json marshal and unmarshal methods with database scan and value methods.

---

string, json.Number OR decimal.Decimal

Use decimal.Decimal always for calculations.

To use decimal.Decimal type from github.com/greatcloak/decimal package.
Use json.Number type for json number values and after that convert to decimal.Decimal.
Use string type to direct get numeric values as string and convert to decimal.Decimal.

Use with nullable sql.Null[decimal.Decimal] package or pointer or decimal.NullDecimal type.

In struct use like this:

type Train struct {
	ID          int64                     `db:"id"          goqu:"skipinsert"`
	Details     types.Map                 `db:"details"     json:"details,omitempty"`
	Additionals types.RawJSON             `db:"additionals" json:"additionals,omitempty"`
	Price       sql.Null[json.Number]     `db:"price"`
	LastPrice   decimal.NullDecimal       `db:"last_price"`
}

Development

Go to example folder and run make command and fallow usage.

Documentation

Index

• Variables
• type Decimal
• type JSON
  • func NewJSON[T any](v T) JSON[T]
  • func (s JSON[T]) MarshalJSON() ([]byte, error)
  • func (s *JSON[T]) Scan(value any) error
  • func (s *JSON[T]) UnmarshalJSON(data []byte) error
  • func (s JSON[T]) Value() (driver.Value, error)
• type Map
  • func (m *Map[T]) Scan(value any) error
  • func (m Map[T]) ToRawJSON() (RawJSON, error)
  • func (m *Map[T]) UnmarshalJSON(data []byte) error
  • func (m Map[T]) Value() (driver.Value, error)
• type Null
  • func NewNull[T any](v T) Null[T]
  • func NewNullFromPtr[T any](v *T) Null[T]
  • func NewNullWithValid[T any](v T, valid bool) Null[T]
  • func NewTimeNull(t time.Time) Null[Time]
  • func NewTimeNullFromPtr(t *time.Time) Null[Time]
  • func NewTimeNullWithValid(t time.Time, valid bool) Null[Time]
  • func (n Null[T]) MarshalJSON() ([]byte, error)
  • func (n *Null[T]) Merge(old Null[T])
  • func (n *Null[T]) Present() bool
  • func (n Null[T]) Ptr() *T
  • func (n *Null[T]) Scan(value any) error
  • func (n *Null[T]) UnmarshalJSON(data []byte) error
  • func (n Null[T]) ValueOrZero() T
• type NullDecimal
• type RawJSON
  • func (r RawJSON) MarshalJSON() ([]byte, error)
  • func (r *RawJSON) Scan(value any) error
  • func (r RawJSON) ToMap() (Map[any], error)
  • func (r *RawJSON) UnmarshalJSON(data []byte) error
  • func (r RawJSON) Value() (driver.Value, error)
• type Slice
  • func (s *Slice[T]) Scan(value any) error
  • func (s Slice[T]) Value() (driver.Value, error)
• type Time
  • func NewTime(t time.Time) Time
  • func (t Time) MarshalJSON() ([]byte, error)
  • func (t *Time) Parse(s string) error
  • func (t *Time) Scan(value any) error
  • func (t Time) String() string
  • func (t *Time) UnmarshalJSON(data []byte) error
  • func (t Time) Value() (driver.Value, error)

Variables

var ErrUnsupportedType = errors.New("unsupported type")

Types

type Decimal

type Decimal = decimal.Decimal

type JSON

type JSON[T any] struct {
	V     T
	Valid bool
}

func NewJSON

func NewJSON[T any](v T) JSON[T]

func (JSON[T]) MarshalJSON

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

func (*JSON[T]) Scan

func (s *JSON[T]) Scan(value any) error

func (*JSON[T]) UnmarshalJSON

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

func (JSON[T]) Value

func (s JSON[T]) Value() (driver.Value, error)

type Map

type Map[T any] map[string]T

func (*Map[T]) Scan

func (m *Map[T]) Scan(value any) error

func (Map[T]) ToRawJSON

func (m Map[T]) ToRawJSON() (RawJSON, error)

func (*Map[T]) UnmarshalJSON

func (m *Map[T]) UnmarshalJSON(data []byte) error

func (Map[T]) Value

func (m Map[T]) Value() (driver.Value, error)

type Null

type Null[T any] struct {
	sql.Null[T]
	// ParsedNull is a helper field to distinguish between a null value and an omitted field during JSON unmarshalling.
	//  - if the field is present in the JSON (even if it's null), ParsedNull will be true.
	ParsedNull bool `json:"-"`
}

func NewNull

func NewNull[T any](v T) Null[T]

NewNull creates a Null[T] with the given value and Valid set to true.

func NewNullFromPtr

func NewNullFromPtr[T any](v *T) Null[T]

NewNullFromPtr creates a Null[T] from a pointer to T.

• If the pointer is nil, it returns a Null[T] with Valid set to false and V set to the zero value of T.

func NewNullWithValid

func NewNullWithValid[T any](v T, valid bool) Null[T]

NewNullWithValid creates a Null[T] with the given value and Valid set to the specified boolean.

func NewTimeNull

func NewTimeNull(t time.Time) Null[Time]

func NewTimeNullFromPtr

func NewTimeNullFromPtr(t *time.Time) Null[Time]

func NewTimeNullWithValid

func NewTimeNullWithValid(t time.Time, valid bool) Null[Time]

func (Null[T]) MarshalJSON

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

func (*Null[T]) Merge

func (n *Null[T]) Merge(old Null[T])

Merge merges the current Null[T] with an old one, preserving the old value if the current one is not valid and not explicitly set to null.

This relies on types.Null's ParsedNull marker, which captures what a plain Go zero value cannot: whether the client said "leave this alone" or "make this empty".

func (*Null[T]) Present

func (n *Null[T]) Present() bool

Present reports whether the field was in the update JSON at all, with either a value or an explicit null. Use it when a merge is not a straight replacement — a secret that is kept unless explicitly cleared, say.

func (Null[T]) Ptr

func (n Null[T]) Ptr() *T

Ptr returns a pointer to the inner value if Valid is true, otherwise it returns nil.

func (*Null[T]) Scan

func (n *Null[T]) Scan(value any) error

func (*Null[T]) UnmarshalJSON

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

func (Null[T]) ValueOrZero

func (n Null[T]) ValueOrZero() T

ValueOrZero returns the inner value if valid, otherwise zero.

type NullDecimal

type NullDecimal = decimal.NullDecimal

type RawJSON

type RawJSON []byte

RawJSON same functionality with json.RawMessage and scan and value methods.

func (RawJSON) MarshalJSON

func (r RawJSON) MarshalJSON() ([]byte, error)

MarshalJSON returns m as the JSON encoding of m.

func (*RawJSON) Scan

func (r *RawJSON) Scan(value any) error

func (RawJSON) ToMap

func (r RawJSON) ToMap() (Map[any], error)

func (*RawJSON) UnmarshalJSON

func (r *RawJSON) UnmarshalJSON(data []byte) error

UnmarshalJSON sets *m to a copy of data.

func (RawJSON) Value

func (r RawJSON) Value() (driver.Value, error)

type Slice

type Slice[T any] []T

func (*Slice[T]) Scan

func (s *Slice[T]) Scan(value any) error

func (Slice[T]) Value

func (s Slice[T]) Value() (driver.Value, error)

type Time

type Time struct {
	time.Time
}

func NewTime

func NewTime(t time.Time) Time

func (Time) MarshalJSON

func (t Time) MarshalJSON() ([]byte, error)

func (*Time) Parse

func (t *Time) Parse(s string) error

func (*Time) Scan

func (t *Time) Scan(value any) error

Scan implements the [Scanner] interface.

func (Time) String

func (t Time) String() string

String returns the time in RFC3339 format.

func (*Time) UnmarshalJSON

func (t *Time) UnmarshalJSON(data []byte) error

func (Time) Value

func (t Time) Value() (driver.Value, error)

Value implements the driver.Valuer interface.