Go Depth Chart

package main

import "fmt"

type User struct {
	ID        int
	Name      string
	Email     string
	Active    bool
	tokenSalt string // unexported: only this package can touch it
}

func main() {
	// 1. Zero value — every field gets its type's zero. No nil, no garbage.
	var u User
	fmt.Printf("%+v\n", u) // {ID:0 Name: Email: Active:false tokenSalt:}

	// 2. Keyed literal — the only form you should write. Order-independent,
	//    survives new fields being added to the struct later.
	a := User{ID: 1, Name: "Ada", Email: "ada@example.com", Active: true}

	// 3. Positional literal — brittle. Must list every field, in order.
	b := User{2, "Grace", "grace@example.com", true, ""}

	// 4. Pointer to a struct. &User{...} is the idiomatic constructor form.
	p := &User{ID: 3, Name: "Alan"}

	// Field access is the same through a pointer — Go auto-dereferences.
	p.Name = "Alan Turing" // shorthand for (*p).Name

	fmt.Println(a.Name, b.Name, p.Name)
}

type Address struct {
	City string
	Zip  string
}

type Customer struct {
	Name    string
	Billing Address  // stored inline
	Shipping *Address // optional — nil means "same as billing"
}

c := Customer{
	Name:    "Ada",
	Billing: Address{City: "London", Zip: "EC1"},
}
c.Billing.City = "Cambridge" // reach straight through

// Structs are comparable with == when all their fields are comparable.
fmt.Println(Address{"London", "EC1"} == Address{"London", "EC1"}) // true

type Counter struct {
	n int
}

// Value receiver: c is a COPY. Mutations are thrown away.
func (c Counter) IncBroken() { c.n++ }

// Pointer receiver: c points at the original. Mutations stick.
func (c *Counter) Inc() { c.n++ }

// Value receiver is right for read-only methods on small structs.
func (c Counter) Value() int { return c.n }

func main() {
	var c Counter
	c.IncBroken()
	fmt.Println(c.Value()) // 0  ← the classic beginner bug

	c.Inc()                // Go rewrites this as (&c).Inc()
	fmt.Println(c.Value()) // 1
}

type Server struct {
	addr    string
	timeout time.Duration
	maxConn int
	logger  *slog.Logger
}

// Plain constructor: required args as parameters, invariants enforced here.
func NewServer(addr string) (*Server, error) {
	if addr == "" {
		return nil, errors.New("server: addr is required")
	}
	return &Server{
		addr:    addr,
		timeout: 30 * time.Second, // sensible defaults
		maxConn: 100,
		logger:  slog.Default(),
	}, nil
}

// Functional options: the Go answer to optional/named parameters.
type Option func(*Server)

func WithTimeout(d time.Duration) Option { return func(s *Server) { s.timeout = d } }
func WithMaxConn(n int) Option           { return func(s *Server) { s.maxConn = n } }

func New(addr string, opts ...Option) (*Server, error) {
	s, err := NewServer(addr)
	if err != nil {
		return nil, err
	}
	for _, opt := range opts {
		opt(s)
	}
	return s, nil
}

// Call site reads like prose and stays source-compatible as options are added.
srv, err := New(":8080", WithTimeout(5*time.Second), WithMaxConn(500))

type Product struct {
	ID        int       `json:"id"`
	Name      string    `json:"name"`
	Price     float64   `json:"price,string"`      // encode number as a JSON string
	Discount  *float64  `json:"discount,omitempty"` // omit when nil
	CreatedAt time.Time `json:"created_at"`
	internal  string    `json:"-"`                  // never encoded (also unexported)
	Secret    string    `json:"-"`                  // exported but explicitly skipped
}

b, _ := json.Marshal(Product{ID: 1, Name: "Cable", Price: 9.99})
// {"id":1,"name":"Cable","price":"9.99","created_at":"0001-01-01T00:00:00Z"}

// Anonymous struct: a one-off shape, most often a table-driven test case
// or a response body that deserves no package-level name.
tests := []struct {
	name string
	in   string
	want int
}{
	{"empty", "", 0},
	{"one", "a", 1},
}
for _, tt := range tests {
	t.Run(tt.name, func(t *testing.T) { /* ... */ })
}

// struct{} occupies ZERO bytes. Two uses dominate:
seen := map[string]struct{}{}   // a set: values cost nothing
seen["a"] = struct{}{}
_, ok := seen["a"]

done := make(chan struct{})     // a pure signal channel: "an event happened"
close(done)                     // broadcast to every receiver

type Config struct {
	Name  string
	Tags  []string          // slice header: ptr, len, cap
	Extra map[string]string // map: a pointer to a runtime hmap
}

a := Config{Name: "a", Tags: []string{"x"}, Extra: map[string]string{"k": "v"}}
b := a // copies 3 fields — NOT the backing array or the map

b.Name = "b"          // independent: string header copied
b.Tags[0] = "MUTATED" // shared backing array → a.Tags[0] is now "MUTATED"
b.Extra["k"] = "boom" // shared map      → a.Extra["k"] is now "boom"

// A real deep copy has to be written by hand (or generated).
func (c Config) Clone() Config {
	out := c
	out.Tags = slices.Clone(c.Tags)
	out.Extra = maps.Clone(c.Extra)
	return out
}

type Bad struct {
	a bool  // 1 byte  + 7 padding
	b int64 // 8 bytes
	c bool  // 1 byte  + 7 padding
} // unsafe.Sizeof(Bad{}) == 24 on a 64-bit platform

type Good struct {
	b int64 // 8
	a bool  // 1
	c bool  // 1 + 6 padding
} // unsafe.Sizeof(Good{}) == 16

// Measure, don't guess:
fmt.Println(unsafe.Sizeof(Bad{}), unsafe.Sizeof(Good{})) // 24 16
// `go vet -fieldalignment` / the fieldalignment analyzer flags these for you.

// go build -gcflags='-m' ./...
//   ./main.go:12:9: &User{...} escapes to heap
//   ./main.go:20:2: moved to heap: buf

func stackAllocated() int {
	u := User{ID: 1} // never escapes → stack, zero GC cost
	return u.ID
}

func heapAllocated() *User {
	return &User{ID: 1} // escapes via the return → heap
}

type Base struct {
	ID        int
	CreatedAt time.Time
}

func (b Base) Age() time.Duration { return time.Since(b.CreatedAt) }

// EMBEDDED: no field name, just the type.
type Article struct {
	Base          // ← embedded
	Title string
}

// NAMED: ordinary field. Nothing is promoted.
type Comment struct {
	Base  Base // ← named field
	Body  string
}

func main() {
	a := Article{Base: Base{ID: 1, CreatedAt: time.Now()}, Title: "Hello"}
	fmt.Println(a.ID)       // promoted field  — no a.Base.ID needed
	fmt.Println(a.Age())    // promoted method
	fmt.Println(a.Base.ID)  // the long form still works; "Base" is the implicit field name

	c := Comment{Base: Base{ID: 2}, Body: "hi"}
	fmt.Println(c.Base.ID)  // required
	// fmt.Println(c.ID)    // compile error: c.ID undefined
}

type SafeCounter struct {
	sync.Mutex // promoted: c.Lock() / c.Unlock() work directly
	counts map[string]int
}

func (c *SafeCounter) Inc(key string) {
	c.Lock()
	defer c.Unlock()
	c.counts[key]++
}

// Note: embedding sync.Mutex EXPORTS Lock/Unlock on SafeCounter, letting callers
// lock your internals. For a public API, prefer an unexported named field:
type SafeCounter2 struct {
	mu     sync.Mutex
	counts map[string]int
}

// Capture the status code of an http.ResponseWriter without reimplementing
// the ~4 methods of the interface: embed it and shadow the one you care about.
type statusRecorder struct {
	http.ResponseWriter // everything else is forwarded for free
	status int
}

func (r *statusRecorder) WriteHeader(code int) {
	r.status = code
	r.ResponseWriter.WriteHeader(code) // explicit delegation to the inner value
}

func LogStatus(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
		rec := &statusRecorder{ResponseWriter: w, status: http.StatusOK}
		next.ServeHTTP(rec, req)
		slog.Info("request", "path", req.URL.Path, "status", rec.status)
	})
}

type Model struct {
	ID        uuid.UUID
	CreatedAt time.Time
	UpdatedAt time.Time
}

func (m *Model) Touch() { m.UpdatedAt = time.Now() }
func (m Model) IsNew() bool { return m.ID == uuid.Nil }

type Order struct {
	Model            // every entity gets ID/CreatedAt/UpdatedAt + Touch/IsNew
	Total  int64
	Status Status
}

type Invoice struct {
	Model
	OrderID uuid.UUID
}

o := &Order{Total: 1999}
o.Touch()            // promoted pointer method — requires o to be addressable
fmt.Println(o.IsNew()) // true

type Meta struct {
	ID      int    `json:"id"`
	Version int    `json:"version"`
}

type Doc struct {
	Meta          // no json tag → fields are FLATTENED into the parent object
	Body string `json:"body"`
}
// {"id":1,"version":2,"body":"..."}

type Doc2 struct {
	Meta Meta   `json:"meta"` // named field → NESTED
	Body string `json:"body"`
}
// {"meta":{"id":1,"version":2},"body":"..."}

type Doc3 struct {
	Meta `json:"meta"` // embedded WITH a tag → also nested
	Body string `json:"body"`
}

type A struct{ Name string }
type B struct{ Name string }

type Outer struct {
	A
	B
	Name string // depth 0 — shadows BOTH
}

o := Outer{}
o.Name = "outer"   // fine: shallowest wins
o.A.Name = "a"     // explicit path always available

type Ambiguous struct {
	A
	B
	// no Name here
}
x := Ambiguous{}
// x.Name = "?"    // compile error: ambiguous selector x.Name
x.A.Name = "ok"    // must disambiguate explicitly

type Animal struct{ Name string }

func (a Animal) Speak() string    { return "..." }
func (a Animal) Describe() string { return a.Name + " says " + a.Speak() }

type Dog struct{ Animal }

func (d Dog) Speak() string { return "Woof" } // "overrides" Speak on Dog

d := Dog{Animal{Name: "Rex"}}
fmt.Println(d.Speak())    // "Woof"   ← outer method, as expected
fmt.Println(d.Describe()) // "Rex says ..."  ← NOT "Woof"!
// Describe is Animal's method; inside it, the receiver IS an Animal.
// It has no idea a Dog exists.

// The Go fix: pass the behaviour in as an interface, don't inherit it.
type Speaker interface{ Speak() string }

func Describe(s Speaker, name string) string { return name + " says " + s.Speak() }

type Shape interface {
	Area() float64
	Perimeter() float64
}

type Rect struct{ W, H float64 }

func (r Rect) Area() float64      { return r.W * r.H }
func (r Rect) Perimeter() float64 { return 2 * (r.W + r.H) }

type Circle struct{ R float64 }

func (c Circle) Area() float64      { return math.Pi * c.R * c.R }
func (c Circle) Perimeter() float64 { return 2 * math.Pi * c.R }

// Rect and Circle never mention Shape. Satisfaction is structural.
func TotalArea(shapes []Shape) float64 {
	var total float64
	for _, s := range shapes {
		total += s.Area() // dynamic dispatch to the concrete method
	}
	return total
}

TotalArea([]Shape{Rect{3, 4}, Circle{1}})

var s Shape = Circle{R: 2}

c := s.(Circle)      // panics if s is not a Circle
c, ok := s.(Circle)  // ok is false instead of panicking — prefer this

// A type switch handles many cases at once.
func describe(v any) string {
	switch x := v.(type) {
	case nil:
		return "nil"
	case int:
		return fmt.Sprintf("int %d", x)      // x is an int here
	case string:
		return fmt.Sprintf("string %q", x)   // x is a string here
	case Shape:
		return fmt.Sprintf("shape area %.2f", x.Area())
	case error:
		return "error: " + x.Error()
	default:
		return fmt.Sprintf("unhandled %T", x)
	}
}

// package billing — declares only what IT needs.
type UserStore interface {
	GetUser(ctx context.Context, id int64) (User, error)
}

type Service struct{ users UserStore }

func NewService(u UserStore) *Service { return &Service{users: u} }

func (s *Service) Charge(ctx context.Context, id int64, cents int64) error {
	u, err := s.users.GetUser(ctx, id)
	if err != nil {
		return fmt.Errorf("charge %d: %w", id, err)
	}
	...
}

// package postgres — returns a concrete type; it never imports billing.
type DB struct{ pool *pgxpool.Pool }
func New(pool *pgxpool.Pool) *DB { return &DB{pool: pool} }
func (d *DB) GetUser(ctx context.Context, id int64) (billing.User, error) { ... }

// package billing_test — a fake is now three lines.
type fakeStore struct{ u User; err error }
func (f fakeStore) GetUser(context.Context, int64) (User, error) { return f.u, f.err }

type error interface{ Error() string }

// Sentinel errors: compared by identity.
var ErrNotFound = errors.New("not found")

// Typed errors: carry structured data.
type ValidationError struct {
	Field  string
	Reason string
}

func (e *ValidationError) Error() string {
	return fmt.Sprintf("validation: %s %s", e.Field, e.Reason)
}

func load(id int) error {
	if id == 0 {
		// %w wraps: the chain is preserved for errors.Is / errors.As.
		return fmt.Errorf("load user %d: %w", id, ErrNotFound)
	}
	return nil
}

err := load(0)
if errors.Is(err, ErrNotFound) {          // unwraps the chain, compares identity
	return http.StatusNotFound, nil
}

var ve *ValidationError
if errors.As(err, &ve) {                  // unwraps and type-asserts into ve
	log.Println("bad field:", ve.Field)
}

// %w wraps (callers can inspect). %v formats (the chain ends here — an
// intentional choice when the underlying error is an implementation detail).

// Costs nothing at runtime, fails the build the moment the type drifts.
// Put it next to the implementation.
var (
	_ io.ReadWriter = (*Buffer)(nil)
	_ UserStore     = (*DB)(nil)
	_ error         = (*ValidationError)(nil)
)

type Reader interface{ Read(p []byte) (n int, err error) }
type Writer interface{ Write(p []byte) (n int, err error) }
type Closer interface{ Close() error }

type ReadWriter interface {
	Reader
	Writer
}

type ReadWriteCloser interface {
	ReadWriter
	Closer
}

// Optional-behaviour probing: ask at runtime whether a value can do more.
func flushIfPossible(w io.Writer) error {
	if f, ok := w.(interface{ Flush() error }); ok { // anonymous interface, inline
		return f.Flush()
	}
	return nil
}

type MyError struct{ Code int }

func (e *MyError) Error() string { return fmt.Sprintf("code %d", e.Code) }

// BROKEN: the return type is the concrete pointer.
func doBroken() error {
	var e *MyError = nil // (*MyError, nil)
	return e             // wrapped into an interface: type=*MyError, value=nil
}

func main() {
	err := doBroken()
	fmt.Println(err == nil) // false !!  — type word is non-nil
	fmt.Printf("%T %v\n", err, err) // *main.MyError <nil>
	if err != nil {
		// this branch runs, then err.Error() dereferences nil → panic
	}
}

// CORRECT: only assign to the interface on the failure path.
func doFixed(fail bool) error {
	if fail {
		return &MyError{Code: 500}
	}
	return nil // an untyped nil — both words nil
}

type Stringer interface{ String() string }

type P struct{ n int }
func (p *P) String() string { return strconv.Itoa(p.n) } // POINTER receiver

var _ Stringer = &P{} // ok:  *P has String
// var _ Stringer = P{} // compile error: P does not implement Stringer
                        // (method String has pointer receiver)

p := P{1}
_ = p.String() // still fine: Go rewrites to (&p).String() — p is addressable

// And the reverse case, which trips people up in maps and slices:
m := map[string]P{"a": {1}}
// m["a"].String() // compile error: m["a"] is not addressable

// Give it its own TYPE. `int` alone gives you no safety at all.
type Status int

const (
	StatusPending  Status = iota // 0
	StatusActive                 // 1  — the expression `Status = iota` repeats
	StatusSuspended              // 2
	StatusClosed                 // 3
)

func main() {
	s := StatusActive
	fmt.Println(s)       // 1  — prints the number until we add String()
	fmt.Println(s == 1)  // true: untyped constant 1 converts to Status

	var n int = 5
	// s = n            // compile error: cannot use n (int) as Status
	s = Status(n)       // explicit conversion is allowed — see the Depth level
}

package order

import (
	"database/sql/driver"
	"encoding/json"
	"fmt"
)

type Status int

const (
	StatusUnknown Status = iota // reserved: an unset Status is invalid
	StatusPending
	StatusPaid
	StatusShipped
	StatusCancelled
)

var statusNames = map[Status]string{
	StatusPending:   "pending",
	StatusPaid:      "paid",
	StatusShipped:   "shipped",
	StatusCancelled: "cancelled",
}

// String makes it print nicely everywhere: fmt, logs, %v, %s.
func (s Status) String() string {
	if name, ok := statusNames[s]; ok {
		return name
	}
	return fmt.Sprintf("Status(%d)", int(s)) // never lie about a bad value
}

func (s Status) Valid() bool { _, ok := statusNames[s]; return ok }

func ParseStatus(s string) (Status, error) {
	for k, v := range statusNames {
		if v == s {
			return k, nil
		}
	}
	return StatusUnknown, fmt.Errorf("order: unknown status %q", s)
}

// Cross the wire as a string, not a fragile integer.
func (s Status) MarshalJSON() ([]byte, error) {
	if !s.Valid() {
		return nil, fmt.Errorf("order: cannot marshal %v", s)
	}
	return json.Marshal(s.String())
}

func (s *Status) UnmarshalJSON(b []byte) error {
	var raw string
	if err := json.Unmarshal(b, &raw); err != nil {
		return err
	}
	parsed, err := ParseStatus(raw)
	if err != nil {
		return err
	}
	*s = parsed
	return nil
}

// Same idea for SQL, if the column is text.
func (s Status) Value() (driver.Value, error) { return s.String(), nil }

type Env string

const (
	EnvDev     Env = "dev"
	EnvStaging Env = "staging"
	EnvProd    Env = "prod"
)

func (e Env) Valid() bool {
	switch e {
	case EnvDev, EnvStaging, EnvProd:
		return true
	}
	return false
}
// Trade-off: JSON and SQL work with zero extra code, and values are
// self-describing; you lose ordering and compact storage.

type Perm uint8

const (
	PermRead  Perm = 1 << iota // 1  (0b001)
	PermWrite                  // 2  (0b010)
	PermExec                   // 4  (0b100)
)

const PermAll = PermRead | PermWrite | PermExec

func (p Perm) Has(q Perm) bool { return p&q == q }   // test
func (p Perm) Set(q Perm) Perm { return p | q }      // add
func (p Perm) Clear(q Perm) Perm { return p &^ q }   // remove (AND NOT)

p := PermRead.Set(PermWrite)
fmt.Println(p.Has(PermWrite), p.Has(PermExec)) // true false

const (
	_  = iota             // 0 discarded: start the enum at 1
	KB = 1 << (10 * iota) // 1 << 10
	MB                    // 1 << 20
	GB                    // 1 << 30
	TB                    // 1 << 40
)

const (
	A = iota // 0
	B        // 1
	_        // 2 skipped — a removed value, kept as a placeholder for wire compat
	D        // 3
)

const (
	// Multiple constants on one line share the same iota.
	X, XX = iota, iota * 10 // X=0, XX=0
	Y, YY                   // Y=1, YY=10
	Z, ZZ                   // Z=2, ZZ=20
)

const (
	C1 = iota + 100 // 100 — offsets work
	C2              // 101
)

// iota RESETS to 0 in every new const block. Splitting a block renumbers it —
// a silent, wire-breaking change if those numbers are persisted anywhere.

func (s Status) NextAction() string {
	switch s {
	case StatusPending:
		return "await payment"
	case StatusPaid:
		return "pick and pack"
	case StatusShipped:
		return "await delivery"
	case StatusCancelled:
		return "none"
	case StatusUnknown:
		return "none"
	default:
		// Fails immediately and identifies the value, instead of returning "".
		panic(fmt.Sprintf("order: unhandled status %v", s))
	}
}

// Compile-time guard against reordering. A negative untyped constant cannot
// convert to uint, so one of these two lines fails the build if the value moves.
const (
	_ = uint(StatusCancelled - 4)
	_ = uint(4 - StatusCancelled)
)

// A "sealed" interface: the unexported method means only this package can
// add implementations, which is as close to a closed sum type as Go gets.
type Payment interface {
	Total() int64
	isPayment()
}

type Card struct{ Cents int64; Last4 string }
func (c Card) Total() int64 { return c.Cents }
func (Card) isPayment()     {}

type Credit struct{ Cents int64; Reason string }
func (c Credit) Total() int64 { return -c.Cents }
func (Credit) isPayment()     {}

// [T any]  → one type parameter named T, constrained to "any type"
func Map[T, U any](in []T, f func(T) U) []U {
	out := make([]U, 0, len(in))
	for _, v := range in {
		out = append(out, f(v))
	}
	return out
}

names := Map([]int{1, 2, 3}, func(n int) string { // T and U are INFERRED
	return strconv.Itoa(n)
})                                                 // []string{"1","2","3"}

lens := Map[string, int](names, func(s string) int { return len(s) }) // explicit

import "cmp" // Go 1.21+

func Max[T cmp.Ordered](a, b T) T {
	if a > b { // legal ONLY because the constraint permits >
		return a
	}
	return b
}

func Keys[K comparable, V any](m map[K]V) []K {
	out := make([]K, 0, len(m))
	for k := range m {
		out = append(out, k)
	}
	return out
}

func Contains[T comparable](s []T, want T) bool {
	for _, v := range s {
		if v == want { // legal because of `comparable`
			return true
		}
	}
	return false
}

type Number interface {
	~int | ~int8 | ~int16 | ~int32 | ~int64 |
		~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64 |
		~float32 | ~float64
}

func Sum[T Number](xs []T) T {
	var total T // zero value of whatever T is
	for _, x := range xs {
		total += x
	}
	return total
}

type Celsius float64
Sum([]Celsius{1.5, 2.5}) // works: underlying type of Celsius is float64
                         // without ~, `| float64` would reject Celsius

// A constraint can mix a type set with methods.
type StringableNumber interface {
	~int | ~int64
	String() string
}

type Set[T comparable] struct {
	items map[T]struct{}
}

func NewSet[T comparable](vals ...T) *Set[T] {
	s := &Set[T]{items: make(map[T]struct{}, len(vals))}
	for _, v := range vals {
		s.items[v] = struct{}{}
	}
	return s
}

func (s *Set[T]) Add(v T)          { s.items[v] = struct{}{} }
func (s *Set[T]) Has(v T) bool     { _, ok := s.items[v]; return ok }
func (s *Set[T]) Len() int         { return len(s.items) }
func (s *Set[T]) Slice() []T {
	out := make([]T, 0, len(s.items))
	for v := range s.items {
		out = append(out, v)
	}
	return out
}

// ILLEGAL — a method may not declare its own type parameter:
// func (s *Set[T]) Map[U any](f func(T) U) *Set[U] { ... }
// Write it as a free function instead:
func MapSet[T, U comparable](s *Set[T], f func(T) U) *Set[U] {
	out := NewSet[U]()
	for v := range s.items {
		out.Add(f(v))
	}
	return out
}

ids := NewSet(1, 2, 3)     // T inferred as int
fmt.Println(ids.Has(2))    // true

// 1. A typed cache/registry — previously map[string]any plus assertions.
type Cache[K comparable, V any] struct {
	mu    sync.RWMutex
	items map[K]V
}

func NewCache[K comparable, V any]() *Cache[K, V] {
	return &Cache[K, V]{items: make(map[K]V)}
}

func (c *Cache[K, V]) Get(k K) (V, bool) {
	c.mu.RLock()
	defer c.mu.RUnlock()
	v, ok := c.items[k]
	return v, ok // returns the zero V when absent — no assertion needed
}

func (c *Cache[K, V]) Set(k K, v V) {
	c.mu.Lock()
	defer c.mu.Unlock()
	c.items[k] = v
}

// 2. Pointer-to-value helpers, the death of a hundred copy-pasted funcs.
func Ptr[T any](v T) *T { return &v }
func Deref[T any](p *T, fallback T) T {
	if p == nil {
		return fallback
	}
	return *p
}
req := Request{Timeout: Ptr(30), Label: Ptr("beta")}

// 3. Grouping / indexing, once instead of per type.
func GroupBy[T any, K comparable](in []T, key func(T) K) map[K][]T {
	out := make(map[K][]T)
	for _, v := range in {
		k := key(v)
		out[k] = append(out[k], v)
	}
	return out
}
byStatus := GroupBy(orders, func(o Order) Status { return o.Status })

func Zero[T any]() T { var z T; return z }

// z := Zero()      // compile error: cannot infer T
z := Zero[int]()    // explicit instantiation required

// Constraints do not flow "backwards" either. This is a common surprise:
func Reduce[T, U any](in []T, init U, f func(U, T) U) U { ... }

// Inference succeeds because init pins U:
total := Reduce([]int{1, 2, 3}, 0, func(acc, n int) int { return acc + n })

// Partial instantiation is allowed — supply the leading params, infer the rest.
parse := Map[string, int]

func main() {
	go fmt.Println("hello from a goroutine")
	// main returns immediately → the whole program exits → that line may
	// never print. When main ends, every goroutine is killed, no cleanup,
	// no deferred functions.
}

// Fix #1 (correct): wait for it explicitly.
func main() {
	done := make(chan struct{})
	go func() {
		defer close(done)
		fmt.Println("hello")
	}()
	<-done
}

// Fix #2 (NEVER in real code): time.Sleep. It is a race, not a synchronisation
// primitive. Every "flaky test" story starts here.

x := 1
go fmt.Println(x) // captures the value 1 right here
x = 2             // does not affect the line above

// Whereas a closure captures the VARIABLE:
y := 1
go func() { fmt.Println(y) }() // may print 1 or 2 — a data race
y = 2

func poll(ctx context.Context, interval time.Duration, do func(context.Context) error) {
	t := time.NewTicker(interval)
	defer t.Stop() // tickers must be stopped or they keep firing

	for {
		select {
		case <-ctx.Done():
			return // the ONLY exit — cooperative cancellation
		case <-t.C:
			if err := do(ctx); err != nil {
				slog.Error("poll", "err", err)
			}
		}
	}
}

func main() {
	ctx, cancel := context.WithCancel(context.Background())
	defer cancel() // always defer cancel, even when you also call it explicitly

	go poll(ctx, time.Second, refreshCache)

	// Shut down cleanly on SIGINT/SIGTERM.
	sig, stop := signal.NotifyContext(context.Background(),
		os.Interrupt, syscall.SIGTERM)
	defer stop()
	<-sig.Done()
	cancel()
}

// Deadlines and timeouts are the same mechanism:
ctx, cancel := context.WithTimeout(parent, 5*time.Second)
defer cancel()

func Go(fn func()) {
	go func() {
		defer func() {
			if r := recover(); r != nil {
				slog.Error("goroutine panic",
					"panic", r,
					"stack", string(debug.Stack()))
			}
		}()
		fn()
	}()
}

// Note: net/http already does this per request — a handler panic returns 500
// and kills only that connection. Goroutines YOU start from a handler do not
// inherit that protection.

func fetchAll(ctx context.Context, urls []string, limit int) error {
	sem := make(chan struct{}, limit) // `limit` permits
	g, ctx := errgroup.WithContext(ctx)

	for _, url := range urls {
		select {
		case sem <- struct{}{}: // acquire (blocks when all permits are out)
		case <-ctx.Done():
			return ctx.Err()
		}

		g.Go(func() error {
			defer func() { <-sem }() // release
			return fetch(ctx, url)
		})
	}
	return g.Wait()
}
// golang.org/x/sync/errgroup also has g.SetLimit(n), which does this for you.

for _, u := range users {
	go func() {
		process(u) // Go ≥1.22: correct.  Go <1.22: all goroutines see the last u.
	}()
}

// Portable fix #1 — pass it as an argument (evaluated at `go` time):
for _, u := range users {
	go func(u User) { process(u) }(u)
}

// Portable fix #2 — shadow it inside the loop:
for _, u := range users {
	u := u
	go func() { process(u) }()
}

// Check your module's language version — this is a per-module setting:
//   head -1 go.mod  →  module x ; go 1.22

// 1. Send on a channel nobody will read.
func leak1() {
	ch := make(chan int) // unbuffered
	go func() { ch <- expensive() }() // blocks forever if we return early
	if quick() {
		return // ← the goroutine and everything it references leak
	}
	fmt.Println(<-ch)
}
// Fix: make(chan int, 1) so the send always completes, or use context.

// 2. Receive from a channel nobody will close or send to.
func leak2(ch <-chan int) {
	go func() {
		for v := range ch { // blocks forever if the producer never closes ch
			_ = v
		}
	}()
}
// Fix: the SENDER closes the channel, always.

// 3. No cancellation path at all.
func leak3() {
	go func() {
		for {
			work() // nothing can ever stop this
		}
	}()
}
// Fix: select on ctx.Done() (see the Working level).

ch := make(chan int)     // unbuffered
buf := make(chan int, 3) // buffered, capacity 3
var nilCh chan int       // nil — usable only in select (see Depth)

ch <- 42        // send   (blocks until a receiver takes it)
v := <-ch       // receive
v, ok := <-ch   // ok == false means: channel closed AND drained
close(ch)       // no more sends; receivers drain then get zero values
len(buf), cap(buf) // items currently queued, capacity

func main() {
	nums := make(chan int)

	// The SENDER owns the channel and is the one that closes it.
	go func() {
		defer close(nums) // signals "no more values" exactly once
		for i := 1; i <= 5; i++ {
			nums <- i * i
		}
	}()

	// range receives until the channel is closed AND drained.
	for n := range nums {
		fmt.Println(n) // 1 4 9 16 25
	}

	// Without close(), range would block forever → deadlock panic.
}

func produce(out chan<- int)  { out <- 1; close(out) } // send-only: cannot receive or range
func consume(in <-chan int)   { for v := range in { _ = v } } // receive-only: cannot send or close

ch := make(chan int)  // bidirectional
go produce(ch)        // converts implicitly to chan<- int
consume(ch)           // converts implicitly to <-chan int

select {
case v := <-in:
	handle(v)
case out <- result:      // sends can be selected too
	sent++
case <-ctx.Done():       // cancellation — put this in every long-lived select
	return ctx.Err()
case <-time.After(2 * time.Second): // per-iteration timeout
	return errors.New("timed out")
}

// Non-blocking receive: take a value if one is waiting, otherwise move on.
select {
case v := <-in:
	handle(v)
default:
	// nothing ready
}

// Non-blocking send: drop the value rather than block — the right shape for
// metrics, telemetry, and any "best effort" fan-out.
select {
case events <- e:
default:
	dropped.Add(1)
}

type Job struct{ ID int; URL string }
type Result struct{ ID int; Bytes int; Err error }

func pool(ctx context.Context, jobs <-chan Job, workers int) <-chan Result {
	results := make(chan Result)
	var wg sync.WaitGroup

	for i := 0; i < workers; i++ {
		wg.Add(1)
		go func() {
			defer wg.Done()
			for j := range jobs { // every worker pulls from the SAME channel
				n, err := fetch(ctx, j.URL)
				select {
				case results <- Result{ID: j.ID, Bytes: n, Err: err}:
				case <-ctx.Done():
					return // never block forever on a send
				}
			}
		}()
	}

	// One closer, after all senders are done. This is the standard shape.
	go func() {
		wg.Wait()
		close(results)
	}()

	return results
}

func gen(ctx context.Context, nums ...int) <-chan int {
	out := make(chan int)
	go func() {
		defer close(out)
		for _, n := range nums {
			select {
			case out <- n:
			case <-ctx.Done():
				return
			}
		}
	}()
	return out
}

func square(ctx context.Context, in <-chan int) <-chan int {
	out := make(chan int)
	go func() {
		defer close(out)
		for n := range in {
			select {
			case out <- n * n:
			case <-ctx.Done():
				return
			}
		}
	}()
	return out
}

ctx, cancel := context.WithCancel(context.Background())
defer cancel() // cancelling tears down every stage — no leaked goroutines
for v := range square(ctx, gen(ctx, 1, 2, 3)) {
	fmt.Println(v)
}

func merge[T any](chans ...<-chan T) <-chan T {
	out := make(chan T)
	var wg sync.WaitGroup
	wg.Add(len(chans))

	for _, c := range chans {
		go func(c <-chan T) {
			defer wg.Done()
			for v := range c {
				out <- v
			}
		}(c)
	}

	go func() { wg.Wait(); close(out) }()
	return out
}

func first(ctx context.Context, replicas []string) (string, error) {
	// BUFFERED with room for every sender: losers must never block, or they leak.
	out := make(chan string, len(replicas))
	errs := make(chan error, len(replicas))

	ctx, cancel := context.WithCancel(ctx)
	defer cancel() // tell the losers to stop as soon as we have a winner

	for _, r := range replicas {
		go func(r string) {
			v, err := query(ctx, r)
			if err != nil {
				errs <- err
				return
			}
			out <- v
		}(r)
	}

	for i := 0; i < len(replicas); i++ {
		select {
		case v := <-out:
			return v, nil
		case <-errs:
			continue // all failed → fall out of the loop
		case <-ctx.Done():
			return "", ctx.Err()
		}
	}
	return "", errors.New("all replicas failed")
}

func drain(a, b <-chan int) {
	for a != nil || b != nil {
		select {
		case v, ok := <-a:
			if !ok {
				a = nil // ← disable this case; a closed channel is ALWAYS ready,
				continue //   so without this the select spins at 100% CPU
			}
			fmt.Println("a:", v)
		case v, ok := <-b:
			if !ok {
				b = nil
				continue
			}
			fmt.Println("b:", v)
		}
	}
}

// BROKEN: counter++ is read-modify-write, three steps, not atomic.
var counter int
for i := 0; i < 1000; i++ {
	go func() { counter++ }()
}
// Result is < 1000, non-deterministically. `go run -race` reports it.

// FIXED
type Counter struct {
	mu sync.Mutex // zero value is ready to use — no initialisation
	n  int
}

func (c *Counter) Inc() {
	c.mu.Lock()
	defer c.mu.Unlock() // runs even if the body panics — always defer
	c.n++
}

func (c *Counter) Value() int {
	c.mu.Lock()
	defer c.mu.Unlock()
	return c.n // reads need the lock too, or they can see a torn/stale value
}

type Registry struct {
	mu    sync.RWMutex // guards services
	services map[string]string
}

func (r *Registry) Get(name string) (string, bool) {
	r.mu.RLock()          // many goroutines may hold RLock simultaneously
	defer r.mu.RUnlock()
	addr, ok := r.services[name]
	return addr, ok
}

func (r *Registry) Set(name, addr string) {
	r.mu.Lock()           // exclusive: waits for all readers to finish
	defer r.mu.Unlock()
	if r.services == nil {
		r.services = make(map[string]string)
	}
	r.services[name] = addr
}

var (
	once sync.Once
	conn *sql.DB
)

func DB() *sql.DB {
	once.Do(func() { // runs exactly once, and every caller waits for it
		conn = mustConnect()
	})
	return conn
}

// Go 1.21+ has typed helpers that remove the package-level variable:
var db = sync.OnceValue(func() *sql.DB { return mustConnect() })
var cfg = sync.OnceValues(func() (Config, error) { return loadConfig() })

use(db())          // initialised on first call, cached after

import "sync/atomic"

type Stats struct {
	requests atomic.Int64
	errors   atomic.Int64
	shutdown atomic.Bool
	config   atomic.Pointer[Config] // lock-free hot-swappable config
}

func (s *Stats) Record(err error) {
	s.requests.Add(1)
	if err != nil {
		s.errors.Add(1)
	}
}

func (s *Stats) Snapshot() (int64, int64) {
	return s.requests.Load(), s.errors.Load()
}

// Compare-and-swap: the building block of lock-free algorithms.
for {
	old := s.requests.Load()
	if s.requests.CompareAndSwap(old, old*2) {
		break
	}
	// someone else won the race — retry with the new value
}

// Publishing a new config: readers never block, and never see a half-written one.
s.config.Store(&newCfg)
cfg := s.config.Load()

type Store struct {
	mu sync.Mutex
	m  map[string]int
}

// BROKEN: value receiver copies mu on every call → each call locks its own copy.
func (s Store) BadGet(k string) int { s.mu.Lock(); defer s.mu.Unlock(); return s.m[k] }
//     go vet: BadGet passes lock by value: Store contains sync.Mutex

// BROKEN: self-deadlock.
func (s *Store) Reset() {
	s.mu.Lock()
	defer s.mu.Unlock()
	s.clear() // clear() locks again → deadlock
}
func (s *Store) clear() { s.mu.Lock(); defer s.mu.Unlock(); s.m = map[string]int{} }

// CORRECT: the "already locked" convention.
func (s *Store) Reset2() {
	s.mu.Lock()
	defer s.mu.Unlock()
	s.clearLocked()
}
// clearLocked requires s.mu to be held by the caller.
func (s *Store) clearLocked() { s.m = map[string]int{} }

// sync.Map is untyped (any/any) and beats map+RWMutex in exactly two cases:
//   1. an entry is written once and read many times (a cache that only grows)
//   2. goroutines operate on disjoint sets of keys (sharded by goroutine)
// Otherwise it is SLOWER and loses all type safety. Default to map + RWMutex,
// or shard your own map by hash if you are contended.

var cache sync.Map

cache.Store("k", &Value{})
if v, ok := cache.Load("k"); ok {
	val := v.(*Value) // type assertion required — no generics here
	_ = val
}
actual, loaded := cache.LoadOrStore("k", &Value{}) // atomic get-or-create
cache.Delete("k")
cache.Range(func(k, v any) bool { return true })   // snapshot-ish iteration

// Typed alternative: a generic wrapper around map + RWMutex (see T5 · Cache).

func main() {
	var wg sync.WaitGroup // zero value is ready; do NOT copy it afterwards

	for _, url := range urls {
		wg.Add(1) // BEFORE `go` — never inside the goroutine
		go func() {
			defer wg.Done() // first line of the body, so panics still decrement
			fetch(url)
		}()
	}

	wg.Wait() // blocks until the counter hits 0
	fmt.Println("all done")
}

// BROKEN — wg is a copy; the caller's Wait() never returns.
func worker(wg sync.WaitGroup, id int) { defer wg.Done(); work(id) }

// CORRECT
func worker(wg *sync.WaitGroup, id int) { defer wg.Done(); work(id) }

var wg sync.WaitGroup
wg.Add(3)
for i := 0; i < 3; i++ {
	go worker(&wg, i)
}
wg.Wait()

// Go 1.25+ removes the footgun entirely:
//   wg.Go(func() { work(id) })   // Add(1) + go + defer Done(), in one call

func fetchAll(urls []string) []Result {
	results := make([]Result, len(urls)) // pre-sized: index i is owned by goroutine i
	var wg sync.WaitGroup

	for i, u := range urls {
		wg.Add(1)
		go func() {
			defer wg.Done()
			body, err := fetch(u)
			results[i] = Result{Body: body, Err: err} // distinct index → no race
		}()
	}

	wg.Wait()
	return results // order matches the input, which a channel would not give you
}

func stream(urls []string) <-chan Result {
	out := make(chan Result)
	var wg sync.WaitGroup

	for _, u := range urls {
		wg.Add(1)
		go func() {
			defer wg.Done()
			out <- fetch(u)
		}()
	}

	// The canonical closer goroutine: nobody else knows when all senders are done.
	go func() {
		wg.Wait()
		close(out)
	}()

	return out // caller can `range` it and will terminate correctly
}

import "golang.org/x/sync/errgroup"

func loadPage(ctx context.Context, userID int64) (*Page, error) {
	var (
		page Page
		g    *errgroup.Group
	)
	// WithContext derives a ctx that is CANCELLED as soon as any task errors.
	g, ctx = errgroup.WithContext(ctx)
	g.SetLimit(8) // bound concurrency; 0 or negative means unlimited

	g.Go(func() error {
		u, err := getUser(ctx, userID)
		page.User = u
		return err // the FIRST non-nil error is what g.Wait() returns
	})
	g.Go(func() error {
		f, err := getFeed(ctx, userID)
		page.Feed = f
		return err
	})
	g.Go(func() error {
		n, err := getNotifications(ctx, userID)
		page.Notifications = n
		return err
	})

	if err := g.Wait(); err != nil { // waits for ALL, returns the first error
		return nil, fmt.Errorf("load page %d: %w", userID, err)
	}
	return &page, nil
}
// Each goroutine writes a DIFFERENT field of page, so no lock is needed.
// Writing the same field, or appending to a shared slice, would need one.

// Wait() cannot be used in a select. Convert it into a channel.
func waitTimeout(wg *sync.WaitGroup, d time.Duration) bool {
	done := make(chan struct{})
	go func() {
		wg.Wait()
		close(done)
	}()

	select {
	case <-done:
		return true // finished in time
	case <-time.After(d):
		return false // timed out — NOTE: the goroutines are still running.
		             // A WaitGroup cannot cancel; you need a context for that.
	}
}

func processAll(ctx context.Context, items []Item) error {
	var (
		wg   sync.WaitGroup
		mu   sync.Mutex
		errs []error
	)

	for _, it := range items {
		wg.Add(1)
		go func() {
			defer wg.Done()
			if err := process(ctx, it); err != nil {
				mu.Lock()
				errs = append(errs, fmt.Errorf("item %s: %w", it.ID, err))
				mu.Unlock() // append is NOT concurrency-safe — the lock is required
			}
		}()
	}
	wg.Wait()

	return errors.Join(errs...) // Go 1.20+: nil if empty; errors.Is works
	                            // against every joined error
}

func run(ctx context.Context, cfg Config) error {
	ctx, cancel := signal.NotifyContext(ctx, os.Interrupt, syscall.SIGTERM)
	defer cancel()

	g, ctx := errgroup.WithContext(ctx)

	srv := &http.Server{Addr: cfg.Addr, Handler: newRouter()}

	// 1. serve
	g.Go(func() error {
		if err := srv.ListenAndServe(); !errors.Is(err, http.ErrServerClosed) {
			return err
		}
		return nil
	})

	// 2. shut down when the context is cancelled (signal, or a sibling failing)
	g.Go(func() error {
		<-ctx.Done()
		shutdownCtx, done := context.WithTimeout(context.Background(), 20*time.Second)
		defer done()
		return srv.Shutdown(shutdownCtx) // drains in-flight requests
	})

	// 3. background worker on the same lifecycle
	g.Go(func() error {
		return runReconciler(ctx)
	})

	return g.Wait() // returns once every task has returned
}