null

package
v1.0.0 Latest Latest
Warning

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

 Go to latest Published: May 17, 2026 License: MIT Imports: 8 Imported by: 1

README

null — SQL-nullable, JSON-friendly types

import "github.com/downsized-devs/sdk-go/null"

Stability: Stable — see STABILITY.md

Nullable wrappers for bool, int64, float64, string, time.Time that round-trip cleanly between database/sql and JSON. Mirrors the shape of sql.NullX but adds an explicit SqlNull flag for "set to NULL in UPDATE" intent.

Features

  • Types: Bool, Int64, Float64, String, Time
  • New<T> and <T>From(v) constructors
  • database/sql Scan/Value implementations
  • encoding/json MarshalJSON/UnmarshalJSON implementations
  • SqlNull field on Int64, String, Time lets you distinguish "leave unchanged" from "set to NULL" in updates

Installation

go get github.com/downsized-devs/sdk-go/null

Quick Start

import "github.com/downsized-devs/sdk-go/null"

u := User{
    Name:  null.StringFrom("Alice"),   // valid
    Email: null.NewString("", false),  // null
}

// JSON: {"Name":"Alice","Email":null}
// SQL:  Name='Alice', Email=NULL

API Reference

Type Constructors Special
Bool NewBool(b, valid), BoolFrom(b)
Int64 NewInt64(i, valid), Int64From(i) SqlNull bool
Float64 NewFloat64(f, valid), Float64From(f)
String NewString(s, valid), StringFrom(s) SqlNull bool
Time NewTime(t, valid), TimeFrom(t) SqlNull bool

All types implement driver.Valuer, sql.Scanner, json.Marshaler, json.Unmarshaler.

Examples

SQL UPDATE that nulls a column explicitly
u.Email = null.String{SqlNull: true}
_, _ = db.Exec(ctx, "UPDATE users SET email = ? WHERE id = ?", u.Email, u.ID)

Dependencies

stdlib only.

Testing

go test ./null/...

Five test files (one per type).

Contributing

See CONTRIBUTING.md.

  • sql, query — primary consumers.
  • parser — JSON unmarshalling round-trips through these types.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Bool 

type Bool struct {
	Bool  bool
	Valid bool
}

nullable boolean type. null will set valid value to false. any boolean value will be considered null when valid is set to false

func BoolFrom 

func BoolFrom(b bool) Bool

create valid nullable boolean

func NewBool 

func NewBool(b bool, valid bool) Bool

create new nullable boolean

func (Bool) Equal 

func (bo Bool) Equal(other Bool) bool

returns true if both invalid or both have same value

func (Bool) Is 

func (bo Bool) Is(other bool) bool

returns true if valid and both have same value

func (Bool) IsNullOrZero 

func (bo Bool) IsNullOrZero() bool

will return true if invalid or value is empty

func (*Bool) MarshalJSON 

func (bo *Bool) MarshalJSON() ([]byte, error)

func (*Bool) Scan 

func (bo *Bool) Scan(value interface{}) error

func (*Bool) UnmarshalJSON 

func (bo *Bool) UnmarshalJSON(b []byte) error

func (Bool) Value 

func (bo Bool) Value() (driver.Value, error)

type Date 

type Date struct {
	Time    time.Time
	Valid   bool
	SqlNull bool
}

Date is nullable time.Time for parsing DATE type in SQL to golang time.Time. SqlNull is for updating SQL DB value to null

func DateFrom 

func DateFrom(t time.Time) Date

create valid nullable time.Time

func NewDate 

func NewDate(t time.Time, valid bool) Date

create new nullable time.time

func (Date) Equal 

func (d Date) Equal(other Date) bool

returns true if both invalid or both have same value

func (Date) Is 

func (d Date) Is(other time.Time) bool

return true if valid and both have same value

func (Date) IsAfter 

func (d Date) IsAfter(other time.Time) bool

return true if valid and the argument is after the origin

func (Date) IsBefore 

func (d Date) IsBefore(other time.Time) bool

return true if valid and the argument is before the origin

func (Date) IsNullOrZero 

func (d Date) IsNullOrZero() bool

will return true if invalid or value is empty

func (*Date) MarshalJSON 

func (d *Date) MarshalJSON() ([]byte, error)

func (*Date) Scan 

func (d *Date) Scan(value interface{}) error

func (*Date) UnmarshalJSON 

func (d *Date) UnmarshalJSON(b []byte) error

func (Date) Value 

func (d Date) Value() (driver.Value, error)

type Float64 

type Float64 struct {
	Float64 float64
	Valid   bool
}

nullable float64 type. null will set valid value to false. any float64 value will be considered null when valid is set to false

func Float64From 

func Float64From(f float64) Float64

create valid nullable float64

func NewFloat64 

func NewFloat64(f float64, valid bool) Float64

create new nullable float64

func (Float64) Equal 

func (f Float64) Equal(other Float64) bool

returns true if both invalid or both have same value

func (Float64) Is 

func (f Float64) Is(other float64) bool

returns true if valid and both have same value

func (Float64) IsNullOrZero 

func (f Float64) IsNullOrZero() bool

will return true if invalid or value is empty

func (*Float64) MarshalJSON 

func (f *Float64) MarshalJSON() ([]byte, error)

func (*Float64) Scan 

func (f *Float64) Scan(value interface{}) error

func (*Float64) UnmarshalJSON 

func (f *Float64) UnmarshalJSON(b []byte) error

func (Float64) Value 

func (f Float64) Value() (driver.Value, error)

type Int64 

type Int64 struct {
	Int64   int64
	Valid   bool
	SqlNull bool
}

nullable int64 type. null will set valid value to false. any int64 value will be considered null when valid is set to false SqlNull is for updating SQL DB value to null

func Int64From 

func Int64From(i int64) Int64

create valid nullable int64

func NewInt64 

func NewInt64(i int64, valid bool) Int64

create new nullable int64

func (Int64) Equal 

func (i Int64) Equal(other Int64) bool

returns true if both invalid or both have same value

func (Int64) Is 

func (i Int64) Is(other int64) bool

returns true if valid and both have same value

func (Int64) IsNullOrZero 

func (i Int64) IsNullOrZero() bool

will return true if invalid or value is zero

func (*Int64) MarshalJSON 

func (i *Int64) MarshalJSON() ([]byte, error)

func (*Int64) Scan 

func (i *Int64) Scan(value interface{}) error

func (*Int64) UnmarshalJSON 

func (i *Int64) UnmarshalJSON(b []byte) error

func (Int64) Value 

func (i Int64) Value() (driver.Value, error)

type String 

type String struct {
	String  string
	Valid   bool
	SqlNull bool
}

nullable string type. null will set valid value to false. any string value will be considered null when valid is set to false SqlNull is for updating SQL DB value to null

func NewString 

func NewString(s string, valid bool) String

create new nullable string

func StringFrom 

func StringFrom(s string) String

create valid nullable string

func (String) Equal 

func (s String) Equal(other String) bool

returns true if both invalid or both have same value

func (String) Is 

func (s String) Is(other string) bool

returns true if valid and both have same value

func (String) IsNullOrZero 

func (s String) IsNullOrZero() bool

will return true if invalid or value is empty

func (*String) MarshalJSON 

func (s *String) MarshalJSON() ([]byte, error)

func (*String) Scan 

func (s *String) Scan(value interface{}) error

func (*String) UnmarshalJSON 

func (s *String) UnmarshalJSON(b []byte) error

func (String) Value 

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

type Time 

type Time struct {
	Time    time.Time
	Valid   bool
	SqlNull bool
}

nullable time.Time type. null will set valid value to false. any time.Time value will be considered null when valid is set to false. SqlNull is for updating SQL DB value to null

func NewTime 

func NewTime(t time.Time, valid bool) Time

create new nullable time.time

func TimeFrom 

func TimeFrom(t time.Time) Time

create valid nullable time.Time

func (Time) Equal 

func (t Time) Equal(other Time) bool

returns true if both invalid or both have same value

func (Time) Is 

func (t Time) Is(other time.Time) bool

return true if valid and both have same value

func (Time) IsAfter 

func (t Time) IsAfter(other time.Time) bool

return true if valid and the argument is after the origin

func (Time) IsBefore 

func (t Time) IsBefore(other time.Time) bool

return true if valid and the argument is before the origin

func (Time) IsNullOrZero 

func (t Time) IsNullOrZero() bool

will return true if invalid or value is empty

func (*Time) MarshalJSON 

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

func (*Time) Scan 

func (t *Time) Scan(value interface{}) error

func (*Time) UnmarshalJSON 

func (nt *Time) UnmarshalJSON(b []byte) error

func (Time) Value 

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

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.