gonull

README

Go Nullable with Generics

Go package simplifies nullable fields handling with Go Generics.

Package gonull provides a generic Nullable type for handling nullable values in a convenient way. This is useful when working with databases and JSON, where nullable values are common. Unlike other nullable libraries, gonull leverages Go's generics feature, enabling it to work seamlessly with any data type, making it more versatile and efficient.

Why gonull

• Use of Go's generics allows for a single implementation that works with any data type.
• Seamless integration with database/sql and JSON marshalling/unmarshalling.
• Reduces boilerplate code and improves code readability.

Usage

go get github.com/LukaGiorgadze/gonull

Example

package main

import (
    "encoding/json"
    "fmt"

    "github.com/LukaGiorgadze/gonull"
)

type MyCustomInt int
type MyCustomFloat32 float32

type Person struct {
    Name    string
    Age     gonull.Nullable[MyCustomInt]
    Address gonull.Nullable[string]
    Height  gonull.Nullable[MyCustomFloat32]
}

func main() {
    jsonData := []byte(`{"Name":"Alice","Age":15,"Address":null,"Height":null}`)

    var person Person
    err := json.Unmarshal(jsonData, &person)
    if err != nil {
        panic(err)
    }
    fmt.Printf("Unmarshalled Person: %+v\n", person)

    marshalledData, err := json.Marshal(person)
    if err != nil {
        panic(err)
    }
    fmt.Printf("Marshalled JSON: %s\n", string(marshalledData))
}

Database example

type User struct {
    Name     gonull.Nullable[string]
    Age      gonull.Nullable[int]
}

func main() {
    // ...
    rows, err := db.Query("SELECT id, name, age FROM users")
    if err != nil {
        log.Fatal(err)
    }
    defer rows.Close()

    for rows.Next() {
        var user User
        err := rows.Scan(&user.Name, &user.Age)
        if err != nil {
            log.Fatal(err)
        }
        fmt.Printf("ID: %d, Name: %v, Age: %v\n", user.Name.Val, user.Age.Val)
    }
    // ...
}

Documentation

Overview

Package gonull provides a generic Nullable type for handling nullable values in a convenient way. This is useful when working with databases and JSON, where nullable values are common.

Index

• Variables
• type Nullable
  • func NewNullable[T any](value T) Nullable[T]
  • func (n Nullable[T]) MarshalJSON() ([]byte, error)
  • func (n Nullable[T]) OrElse(defaultVal T) T
  • func (n *Nullable[T]) Scan(value any) error
  • func (n *Nullable[T]) UnmarshalJSON(data []byte) error
  • func (n Nullable[T]) Value() (driver.Value, error)

Variables

var (
	// ErrUnsupportedConversion is an error that occurs when attempting to convert a value to an unsupported type.
	// This typically happens when Scan is called with a value that cannot be converted to the target type T.
	ErrUnsupportedConversion = errors.New("unsupported type conversion")
)

Types

type Nullable

type Nullable[T any] struct {
	Val     T
	Valid   bool
	Present bool
}

Nullable is a generic struct that holds a nullable value of any type T. It keeps track of the value (Val), a flag (Valid) indicating whether the value has been set and a flag (Present) indicating if the value is in the struct. This allows for better handling of nullable and undefined values, ensuring proper value management and serialization.

func NewNullable

func NewNullable[T any](value T) Nullable[T]

NewNullable creates a new Nullable with the given value and sets Valid to true. This is useful when you want to create a Nullable with an initial value, explicitly marking it as set.

func (Nullable[T]) MarshalJSON

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

MarshalJSON implements the json.Marshaler interface for Nullable, enabling it to be used as a nullable field in JSON operations. This method ensures proper marshalling of Nullable values into JSON data, representing unset values as null in the serialized output.

func (Nullable[T]) OrElse

func (n Nullable[T]) OrElse(defaultVal T) T

OrElse returns the underlying Val if valid otherwise returns the provided defaultVal

func (*Nullable[T]) Scan

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

Scan implements the sql.Scanner interface for Nullable, allowing it to be used as a nullable field in database operations. It is responsible for properly setting the Valid flag and converting the scanned value to the target type T. This enables seamless integration with database/sql when working with nullable values.

func (*Nullable[T]) UnmarshalJSON

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

UnmarshalJSON implements the json.Unmarshaler interface for Nullable, allowing it to be used as a nullable field in JSON operations. This method ensures proper unmarshalling of JSON data into the Nullable value, correctly setting the Valid flag based on the JSON data.

func (Nullable[T]) Value

func (n Nullable[T]) Value() (driver.Value, error)

Value implements the driver.Valuer interface for Nullable, enabling it to be used as a nullable field in database operations. This method ensures that the correct value is returned for serialization, handling unset Nullable values by returning nil.