Quickstart

Get started with atom in 5 minutes.

Installation

go get github.com/zoobz-io/atom

Basic Usage

1. Define Your Struct

type User struct {
    ID        int64
    Name      string
    Email     string
    Age       int64
    Active    bool
    CreatedAt time.Time
}

2. Register the Type

atomizer, err := atom.Use[User]()
if err != nil {
    log.Fatal(err)
}

The first call to Use[T]() builds an execution plan using reflection. Subsequent calls return the cached atomizer instantly.

3. Atomize (Struct → Atom)

user := &User{
    ID:        1,
    Name:      "Alice",
    Email:     "alice@example.com",
    Age:       30,
    Active:    true,
    CreatedAt: time.Now(),
}

atom := atomizer.Atomize(user)

4. Access Fields by Type

// Each type has its own map
fmt.Println(atom.Ints["ID"])       // 1
fmt.Println(atom.Ints["Age"])      // 30
fmt.Println(atom.Strings["Name"])  // Alice
fmt.Println(atom.Strings["Email"]) // alice@example.com
fmt.Println(atom.Bools["Active"])  // true
fmt.Println(atom.Times["CreatedAt"]) // 2024-...

5. Deatomize (Atom → Struct)

restored, err := atomizer.Deatomize(atom)
if err != nil {
    log.Fatal(err)
}

fmt.Println(restored.Name) // Alice

Complete Example

package main

import (
    "fmt"
    "log"
    "time"

    "github.com/zoobz-io/atom"
)

type User struct {
    ID        int64
    Name      string
    Email     string
    Age       int64
    Active    bool
    CreatedAt time.Time
}

func main() {
    // Register type
    atomizer, err := atom.Use[User]()
    if err != nil {
        log.Fatal(err)
    }

    // Create and atomize
    user := &User{
        ID:        1,
        Name:      "Alice",
        Email:     "alice@example.com",
        Age:       30,
        Active:    true,
        CreatedAt: time.Now(),
    }
    a := atomizer.Atomize(user)

    // Inspect the atom
    fmt.Printf("Strings: %v\n", a.Strings)
    fmt.Printf("Ints: %v\n", a.Ints)
    fmt.Printf("Bools: %v\n", a.Bools)

    // Reconstruct
    restored, err := atomizer.Deatomize(a)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Restored: %+v\n", restored)
}

Output:

Strings: map[Email:alice@example.com Name:Alice]
Ints: map[Age:30 ID:1]
Bools: map[Active:true]
Restored: &{ID:1 Name:Alice Email:alice@example.com Age:30 Active:true CreatedAt:...}

What's Next?

• Concepts - Understand atoms, tables, and specs
• Architecture - How atom works internally
• Basic Usage Guide - More detailed usage patterns