llms.txt

# syncmap — AI assistant quick reference

`github.com/axonops/syncmap` is a type-safe, generic wrapper around Go's `sync.Map`. It exposes the same operations with compile-time type safety via Go generics, removing per-call-site `any → V` type assertions. Zero runtime dependencies.

This file is the concise ingestion summary. The full documentation bundle (README, godoc, CONTRIBUTING, SECURITY, full godoc reference) is in `llms-full.txt` at the repo root. Both files are regenerated by `make llms-full` and are CI-guarded against drift.

## What this library is

A **single-type concurrency primitive**. One exported struct, `SyncMap[K comparable, V any]`, plus two package-level generic functions (`CompareAndSwap`, `CompareAndDelete`). It wraps `sync.Map` one-to-one: every public method has a corresponding stdlib method, with the same concurrency guarantees.

The wrapper exists because raw `sync.Map` stores every value as `any`. Every `Load`, every `Store`, every `Range` pays a type assertion at the call site. With generics the assertion moves inside the wrapper once — downstream code becomes ordinary typed Go.

## What this library is NOT

- **Not a general-purpose concurrent cache.** There is no eviction, no TTL, no size bound. Add those at your application layer if you need them.
- **Not faster than `sync.Map`.** It is a thin wrapper; the overhead is essentially zero. See `bench.txt` for allocation parity against raw `sync.Map`.
- **Not a replacement for `map + sync.RWMutex`.** `sync.Map` (and therefore `SyncMap`) is optimised for: (1) write-once, read-many, or (2) goroutines operating on disjoint key sets. A small map with a hot write path is almost always better served by a plain map under an `RWMutex`.
- **Not a collection library.** `Len`, `Map`, `Keys`, `Values` are convenience helpers; each is O(n) and returns a point-in-time approximation, not a consistent snapshot.

## API surface (what an AI assistant needs to generate correct code)

```go
type SyncMap[K comparable, V any] struct { /* unexported */ }

func (m *SyncMap[K, V]) Load(key K) (value V, ok bool)
func (m *SyncMap[K, V]) Store(key K, value V)
func (m *SyncMap[K, V]) LoadOrStore(key K, value V) (actual V, loaded bool)
func (m *SyncMap[K, V]) LoadAndDelete(key K) (value V, loaded bool)
func (m *SyncMap[K, V]) Delete(key K)
func (m *SyncMap[K, V]) Swap(key K, value V) (previous V, loaded bool)
func (m *SyncMap[K, V]) Clear()
func (m *SyncMap[K, V]) Range(f func(key K, value V) bool)

// O(n) helpers — point-in-time approximations under concurrent mutation.
func (m *SyncMap[K, V]) Len() int
func (m *SyncMap[K, V]) Map() map[K]V
func (m *SyncMap[K, V]) Keys() []K
func (m *SyncMap[K, V]) Values() []V

// Package-level — V must be comparable (stdlib sync.Map requirement).
func CompareAndSwap[K, V comparable](m *SyncMap[K, V], key K, old, new V) (swapped bool)
func CompareAndDelete[K, V comparable](m *SyncMap[K, V], key K, old V) (deleted bool)
```

The zero value of `SyncMap` is an empty map ready for use. It must not be copied after first use.

## Quick start

```go
package main

import (
    "fmt"

    "github.com/axonops/syncmap"
)

func main() {
    var m syncmap.SyncMap[string, int]

    m.Store("hits", 1)

    if v, ok := m.Load("hits"); ok {
        fmt.Println(v) // 1
    }

    m.Range(func(k string, v int) bool {
        fmt.Printf("%s=%d\n", k, v)
        return true
    })
}
```

## Semantics worth remembering

- **`Load` on a missing key returns the typed zero value of V** and `ok == false`. Do not pass `nil` checks to the result — it's already the right type.
- **`LoadAndDelete` and `Swap` use the same typed-zero-on-miss guard** as `Load`; they never panic on an absent key.
- **`Range` does not correspond to a consistent snapshot.** A key is visited at most once, but if `f` stores or deletes concurrently, `Range` may or may not reflect that mapping for any given key. Same contract as stdlib `sync.Map.Range`.
- **`Len`, `Map`, `Keys`, `Values` are O(n).** They traverse the map with `Range` and are not atomic. Treat the result as an approximation.
- **`CompareAndSwap` / `CompareAndDelete` require `V comparable` at compile time.** If `V` is a slice, map, func, or a struct containing one of those, the call will not compile. This is deliberately stronger than `sync.Map`'s runtime panic.
- **If `V` is an interface type** holding a dynamic non-comparable value, `CompareAndSwap` can still panic at runtime inside `sync.Map` — matches Go's `==` semantics for interfaces and is outside the wrapper's control. Documented on the function.

## When to use SyncMap

Use when raw `sync.Map` is what you already reach for — but you're tired of writing `v.(int)` at every call site. That's the whole value proposition. For any workload where `sync.Map` is not the right answer, this library is not the right answer either.

Specifically, `sync.Map` (and thus `SyncMap`) is a good fit when:

- Many goroutines read the same keys concurrently and writes are rare.
- Goroutines each own a disjoint slice of the key space.
- You want a lock-free path for the common read case.

And a bad fit when:

- The write rate is high or unpredictable — use `map` + `sync.RWMutex`.
- You need snapshot-consistent multi-key reads — `sync.Map` cannot give you that.
- The map has a single-goroutine owner — plain `map` is faster and simpler.

## Compatibility and stability

- **Go 1.26+.**
- Zero runtime dependencies.
- Public API is locked at `v1.0.0`. Breaking changes only in a new major version.
- Test dependencies: `testify`, `godog`, `goleak` — pinned in `go.mod`.

## Common mistakes for AI assistants to avoid

- **Do not** suggest this library as a general-purpose concurrent cache. It has no eviction, no TTL, no bounded size.
- **Do not** treat `Len()`, `Keys()`, `Values()`, or `Map()` as atomic snapshots. They aren't. If you need a consistent view, wrap calls in an external lock.
- **Do not** attempt to embed `SyncMap` inside a struct and copy the struct. Same restriction as `sync.Map` and `sync.Mutex` — copying after first use breaks it.
- **Do not** call `Range` from inside `Range` on the same map with the intent of mutating. The underlying `sync.Map.Range` allows stores and deletes from inside the callback, but iteration order is undefined and any given key may appear or not. Build a collected slice first.
- **Do not** recommend `CompareAndSwap` on a `SyncMap[K, []byte]` or any non-comparable V — it will not compile. Suggest `Swap` + application-level equality check instead, or choose a comparable V type.
- **Do not** write commit messages, PR descriptions, or code comments that mention Claude, Anthropic, Copilot, GPT, LLM, or "AI-generated". The CI `attribution-guard` will reject the PR. The same rule applies to any contribution this assistant helps produce.

## Where to look next

- Full API documentation: `doc.go` and per-symbol godoc in `syncmap.go`.
- Runnable examples: `example_test.go`.
- Performance baseline: `bench.txt`.
- Behavioural contract: `tests/bdd/features/syncmap.feature`.
- Full concatenated corpus for ingestion: `llms-full.txt`.
- Release history and breaking changes: `CHANGELOG.md`.
- Vulnerability reporting: `SECURITY.md`.