fields

Documentation

Overview

Package fields provides [tidal.Model] column types for JSON, string arrays, and normalized timestamps.

Use them as fields on [tidal.Model] structs. They implement database/sql.Scanner and database/sql/driver.Valuer, so [tidal.CRUD] queries read and write them without extra conversion code. Backing columns should store JSON (JSONB, BYTEA, BLOB, or TEXT depending on your database).

Example:

type Document struct {
	tidal.BaseModel
	Metadata fields.JSONB
	Tags     fields.StringArray
	SeenAt   fields.Timestamp
}

Index

• Constants
• Variables
• type JSONB
  • func (j JSONB) Equal(other JSONB) bool
  • func (j JSONB) IsNull() bool
  • func (j *JSONB) MarshalFrom(src any) (err error)
  • func (j JSONB) Normalize() []byte
  • func (j *JSONB) Scan(src any) error
  • func (j JSONB) UnmarshalTo(dst any) error
  • func (j JSONB) Value() (driver.Value, error)
• type NullJSONB
  • func (j NullJSONB) Equal(other NullJSONB) bool
  • func (j *NullJSONB) MarshalFrom(src any) (err error)
  • func (n *NullJSONB) Scan(src any) (err error)
  • func (j NullJSONB) UnmarshalTo(dst any) error
  • func (n NullJSONB) Value() (driver.Value, error)
• type NullStringArray
  • func (n NullStringArray) Equal(other NullStringArray) bool
  • func (n *NullStringArray) Scan(src any) (err error)
  • func (n NullStringArray) Value() (driver.Value, error)
• type StringArray
  • func (s StringArray) Equal(other StringArray) bool
  • func (s *StringArray) Scan(src any) (err error)
  • func (s StringArray) Value() (driver.Value, error)
• type Timestamp
  • func Time(ts time.Time) Timestamp
  • func TimeNow() Timestamp
  • func TimeParse(layout, value string) (Timestamp, error)
  • func (t Timestamp) Add(d time.Duration) Timestamp
  • func (t Timestamp) After(other Timestamp) bool
  • func (t Timestamp) Before(other Timestamp) bool
  • func (t Timestamp) Compare(other Timestamp) int
  • func (t Timestamp) Equal(other Timestamp) bool
  • func (t Timestamp) Format(layout string) string
  • func (t Timestamp) IsZero() bool
  • func (t Timestamp) MarshalJSON() ([]byte, error)
  • func (t *Timestamp) Now()
  • func (t *Timestamp) Scan(src any) (err error)
  • func (t *Timestamp) Set(ts time.Time)
  • func (t Timestamp) Since(other Timestamp) time.Duration
  • func (t Timestamp) String() string
  • func (t Timestamp) Sub(other Timestamp) time.Duration
  • func (t Timestamp) Time() time.Time
  • func (t Timestamp) UTC() time.Time
  • func (t Timestamp) Unix() int64
  • func (t Timestamp) UnixMilli() int64
  • func (t *Timestamp) UnmarshalJSON(data []byte) (err error)
  • func (t Timestamp) Until(other Timestamp) time.Duration
  • func (t Timestamp) Value() (driver.Value, error)

Constants

const ISO8601Milli = "2006-01-02T15:04:05.000Z07:00"

Variables

var JSONNull = []byte("null")

JSONNull is the JSON literal null as bytes.

Types

type JSONB

type JSONB json.RawMessage

JSONB stores raw JSON in a NOT NULL column. SQL NULL and JSON "null" scan as nil.

func (JSONB) Equal

func (j JSONB) Equal(other JSONB) bool

Equal compares JSON values after normalization so key order differences do not matter.

func (JSONB) IsNull

func (j JSONB) IsNull() bool

IsNull reports whether the value is empty or the JSON literal null.

func (*JSONB) MarshalFrom

func (j *JSONB) MarshalFrom(src any) (err error)

MarshalFrom JSON-encodes src into the field. A nil src clears the field.

func (JSONB) Normalize

func (j JSONB) Normalize() []byte

Normalizes the JSON bytes for hashing: values round-trip through encoding/json so object keys are emitted in sorted order. Invalid JSON is returned unchanged (copy). Numbers become float64 when decoded as any; empty input returns nil.

func (*JSONB) Scan

func (j *JSONB) Scan(src any) error

Scan implements database/sql.Scanner.

func (JSONB) UnmarshalTo

func (j JSONB) UnmarshalTo(dst any) error

UnmarshalTo decodes the JSON into dst. A nil or empty value is a no-op.

func (JSONB) Value

func (j JSONB) Value() (driver.Value, error)

Value implements database/sql/driver.Valuer.

type NullJSONB

type NullJSONB struct {
	Valid bool
	JSONB JSONB
}

NullJSONB stores JSON in a nullable column. Check Valid after scanning.

func (NullJSONB) Equal

func (j NullJSONB) Equal(other NullJSONB) bool

Equal compares nullable JSON values with SQL NULL normalization.

func (*NullJSONB) MarshalFrom

func (j *NullJSONB) MarshalFrom(src any) (err error)

MarshalFrom JSON-encodes src and sets Valid. Nil or JSON null becomes SQL NULL.

func (*NullJSONB) Scan

func (n *NullJSONB) Scan(src any) (err error)

Scan implements database/sql.Scanner.

func (NullJSONB) UnmarshalTo

func (j NullJSONB) UnmarshalTo(dst any) error

UnmarshalTo decodes the JSON when Valid is true.

func (NullJSONB) Value

func (n NullJSONB) Value() (driver.Value, error)

Value implements database/sql/driver.Valuer.

type NullStringArray

type NullStringArray struct {
	Valid       bool
	StringArray StringArray
}

NullStringArray stores a list of strings in a nullable column. Check Valid after scanning.

func (NullStringArray) Equal

func (n NullStringArray) Equal(other NullStringArray) bool

Equal compares nullable arrays, normalizing empty arrays to SQL NULL semantics.

func (*NullStringArray) Scan

func (n *NullStringArray) Scan(src any) (err error)

Scan implements database/sql.Scanner.

func (NullStringArray) Value

func (n NullStringArray) Value() (driver.Value, error)

Value implements database/sql/driver.Valuer.

type StringArray

type StringArray []string

StringArray stores a list of strings as a JSON array in a NOT NULL column.

func (StringArray) Equal

func (s StringArray) Equal(other StringArray) bool

Equal compares two arrays, treating nil and empty arrays as equivalent.

func (*StringArray) Scan

func (s *StringArray) Scan(src any) (err error)

Scan implements database/sql.Scanner.

func (StringArray) Value

func (s StringArray) Value() (driver.Value, error)

Value implements database/sql/driver.Valuer.

type Timestamp

type Timestamp struct {
	// contains filtered or unexported fields
}

Timestamp wraps a time.Time value in order to ensure that the underlying database always has a timestamp stored in the UTC timezone and truncated to millisecond precision. It also treats zero valued timestamps as NULL values so there is no need for a NullTime type. This timestamp is not well suited for all use cases, but generally can unify timestamp behavior across different databases.

func Time

func Time(ts time.Time) Timestamp

Creates a new Timestamp with the given time.Time value.

func TimeNow

func TimeNow() Timestamp

Returns a new Timestamp with the current time.

func TimeParse

func TimeParse(layout, value string) (Timestamp, error)

Parses a time string in the given layout into a Timestamp.

func (Timestamp) Add

func (t Timestamp) Add(d time.Duration) Timestamp

Returns a new normalized Timestamp by adding the given duration.

func (Timestamp) After

func (t Timestamp) After(other Timestamp) bool

Returns true if the timestamp is after the other timestamp.

func (Timestamp) Before

func (t Timestamp) Before(other Timestamp) bool

Returns true if the timestamp is before the other timestamp.

func (Timestamp) Compare

func (t Timestamp) Compare(other Timestamp) int

Returns the result of comparing the two timestamps (0 if equal, -1 if less, 1 if greater).

func (Timestamp) Equal

func (t Timestamp) Equal(other Timestamp) bool

Returns true if the timestamp is equal to the other timestamp.

func (Timestamp) Format

func (t Timestamp) Format(layout string) string

Returns the timestamp as a formatted string.

func (Timestamp) IsZero

func (t Timestamp) IsZero() bool

Returns true if the timestamp is zero (considered null).

func (Timestamp) MarshalJSON

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

func (*Timestamp) Now

func (t *Timestamp) Now()

Sets the timestamp to the current UTC time.

func (*Timestamp) Scan

func (t *Timestamp) Scan(src any) (err error)

func (*Timestamp) Set

func (t *Timestamp) Set(ts time.Time)

Set the timestamp to the given time in the UTC timezone, truncated to millisecond precision.

func (Timestamp) Since

func (t Timestamp) Since(other Timestamp) time.Duration

Returns the duration since the other timestamp. Equivalent to Timestamp.Sub.

func (Timestamp) String

func (t Timestamp) String() string

Returns the timestamp as a string in the RFC3339 format.

func (Timestamp) Sub

func (t Timestamp) Sub(other Timestamp) time.Duration

Returns the duration between the two timestamps.

func (Timestamp) Time

func (t Timestamp) Time() time.Time

Returns the underlying time.Time value (already normalized when set).

func (Timestamp) UTC

func (t Timestamp) UTC() time.Time

Returns the underlying time.Time value in the UTC timezone.

func (Timestamp) Unix

func (t Timestamp) Unix() int64

Returns the unix epoch seconds of the timestamp.

func (Timestamp) UnixMilli

func (t Timestamp) UnixMilli() int64

Returns the unix milliseconds of the timestamp.

func (*Timestamp) UnmarshalJSON

func (t *Timestamp) UnmarshalJSON(data []byte) (err error)

func (Timestamp) Until

func (t Timestamp) Until(other Timestamp) time.Duration

Returns the duration until the other timestamp. Equivalent to argument-inverted Timestamp.Sub.

func (Timestamp) Value

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