https://github.com/zikwall/nullable
A generic utility for representing optional (nullable) values in Go, with full JSON serialization support.
https://github.com/zikwall/nullable
go golang nullable
Last synced: 13 days ago
JSON representation
A generic utility for representing optional (nullable) values in Go, with full JSON serialization support.
- Host: GitHub
- URL: https://github.com/zikwall/nullable
- Owner: zikwall
- Created: 2024-10-29T20:14:47.000Z (over 1 year ago)
- Default Branch: master
- Last Pushed: 2025-11-12T13:52:17.000Z (8 months ago)
- Last Synced: 2025-11-12T15:20:21.246Z (8 months ago)
- Topics: go, golang, nullable
- Language: Go
- Homepage:
- Size: 22.5 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
[](https://github.com/zikwall/nullable/actions)
Nullable
nullable provides a *type-safe and JSON-friendly way* to represent optional (nullable) values in Go.
It eliminates unsafe pointer juggling and keeps your models clean, especially when dealing with APIs or databases.
## ✨ Features
- ✅ Type-safe — no interface{} or reflection
- 🧠 Generic — works with any type (int, string, uuid.UUID, structs…)
- 🔄 JSON-aware — encodes and decodes null seamlessly
- 💾 DB-friendly — ideal for Postgres jsonb or SQL NULL values
- 🧰 Minimal API — New, Null, FromRef, Set, Unset, IsNull, Value, Ref
## 📘 Comparison
| Approach | Drawbacks | nullable advantage |
| --------------------------------- | ------------------------------------------ | --------------------------------------- |
| `*T` pointers | risk of nil dereference, not JSON-friendly | safe, JSON `null` handled automatically |
| `sql.NullString`, `sql.NullInt64` | separate type per kind | one generic type for all |
| `interface{}` | loses type safety | strongly typed generics |
## Install
- `$ go get -u github.com/zikwall/nullable`
## 🚀 Usage
Working with optional values in Go often ends up with *T, sql.NullString, or awkward omitempty tricks.
nullable fixes that — it gives you a clean, generic, and JSON-safe way to express “this field might be missing”.
```go
package main
import (
"fmt"
"time"
"github.com/google/uuid"
"yourmodule/nullable"
)
type DeviceInfo struct {
DeviceID nullable.Nullable[string] `json:"device_id"`
GUID nullable.Nullable[uuid.UUID] `json:"guid"`
DeviceType nullable.Nullable[string] `json:"device_type"`
OSName nullable.Nullable[string] `json:"os_name"`
UserID nullable.Nullable[int64] `json:"user_id"`
LastSeenAt nullable.Nullable[time.Time] `json:"last_seen_at"`
}
func main() {
var info DeviceInfo
// Set some values
info.GUID = nullable.New(uuid.New())
info.DeviceType = nullable.New("mobile")
fmt.Println(info.GUID.NotNull()) // true
fmt.Println(info.DeviceType.Value()) // "mobile"
// Create from pointer reference
val := int64(42)
num := nullable.FromRef(&val)
fmt.Println(num.Value()) // 42
// Unset values explicitly
num.Unset()
fmt.Println(num.IsNull()) // true
// Convert to/from JSON safely
data, _ := json.Marshal(info)
fmt.Println(string(data))
}
```
Output:
```json
{
"device_id": null,
"guid": "c8f8ad4a-6e21-4e6b-a8b1-fb99d5ce1d7b",
"device_type": "mobile",
"os_name": null,
"user_id": null,
"last_seen_at": null
}
```