Quickstart

Installation

go get github.com/zoobz-io/sentinel@latest

Requires Go 1.24 or later.

Basic Usage

package main

import (
    "fmt"
    "github.com/zoobz-io/sentinel"
)

type User struct {
    ID    string `json:"id" db:"user_id"`
    Name  string `json:"name" validate:"required"`
    Email string `json:"email" validate:"email"`
}

func main() {
    metadata := sentinel.Inspect[User]()

    fmt.Printf("Type: %s\n", metadata.TypeName)
    fmt.Printf("Fields: %d\n", len(metadata.Fields))

    for _, field := range metadata.Fields {
        fmt.Printf("  %s: %s\n", field.Name, field.Type)
        for tag, value := range field.Tags {
            fmt.Printf("    @%s = %s\n", tag, value)
        }
    }
}

Scanning

Inspect extracts a single type. Scan recursively discovers all related types within your module, following struct fields to build a complete type graph.

type User struct {
    ID      string   `json:"id"`
    Profile *Profile `json:"profile"` // reference
    Orders  []Order  `json:"orders"`  // collection
}

type Profile struct { Bio string `json:"bio"` }
type Order struct { ID string `json:"id"` }

metadata := sentinel.Scan[User]()

Sentinel detects four relationship kinds: references (struct or pointer fields), collections (slices and arrays), embeddings (anonymous fields), and maps (map values). After scanning, all discovered types are cached.

// List all cached type names
fqdns := sentinel.Browse()
// ["github.com/you/app.User", "github.com/you/app.Profile", "github.com/you/app.Order"]

// Retrieve by fully qualified name
profile, ok := sentinel.Lookup("github.com/you/app.Profile")

// Export complete schema
schema := sentinel.Schema()

See the scanning guide for module boundary behaviour and when to use each mode.

Custom Tags

Sentinel extracts common tags (json, db, validate) by default. Register additional tags before extraction:

sentinel.Tag("graphql")

See custom tags for the full list of built-in tags and usage patterns.

Testing

The global cache persists across tests. For isolation, use the testing helpers with -tags testing:

sentineltest.ResetCache(t)

See testing for patterns and benchmarks.

Next Steps

• Concepts — metadata structures, relationships, and caching
• Architecture — internal design and component interactions
• API Reference — complete function documentation