gods

GoDS (Go Data Structures) implements a full set of data structures and algorithms for Go using the language’s generics, giving every container compile-time type safety without falling back to interface{}. It covers lists (array and linked), sets, stacks, maps (hash, tree, linked-hash, and bidirectional), trees (Red-Black, AVL, B-Tree, binary heap), and queues (array, linked-list, circular buffer, priority queue).

Every structure implements the same base Container interface, and ordered structures additionally expose stateful iterators (including reverse variants) and Ruby-inspired enumerable methods (Each, Select, Map, Find, Any, All), so code written against one container type can often swap to another with minimal changes. All containers also support JSON serialization out of the box.

What You Get

• Generic, type-safe implementations of lists, sets, stacks, maps, trees, and queues, all built on Go’s comparable/cmp.Ordered generics
• A uniform Container interface (Empty, Size, Clear, Values, String) implemented consistently across every structure
• Stateful Iterator and Enumerable protocols (Each, Select, Map, Find, Any, All) with reverse-iteration support on ordered structures
• Built-in JSON serialization and deserialization for every container via JSONSerializer/JSONDeserializer
• 28 runnable example programs, one per data structure, under the examples/ directory
• Balanced-tree and heap coverage (Red-Black Tree, AVL Tree, B-Tree, Binary Heap) alongside simpler array- and linked-list-backed structures

Common Use Cases

• Replacing an ad-hoc sorted-slice pattern with a RedBlackTree or AVLTree to keep insert/lookup at O(log n) as a dataset grows
• Building a task scheduler with PriorityQueue (binary-heap backed) so the highest-priority item is always popped first
• Preserving insertion order in an in-memory cache or config store using LinkedHashMap instead of Go’s unordered built-in map
• Looking up values by either key or value with HashBidiMap/TreeBidiMap instead of maintaining two parallel maps by hand
• Persisting in-memory structured state (a TreeMap or ArrayList) to disk between CLI runs using the built-in JSON serializer

Under The Hood

Architecture GoDS organizes data structures by category (lists, sets, stacks, maps, trees, queues), each implementing shared interfaces defined in a top-level containers package (Container[T]) plus per-category interfaces (e.g. lists.List[T]). The structure is modular: each data structure lives in its own package (e.g. lists/arraylist, trees/redblacktree) with a consistent shape — a struct holding backing state, a New() constructor, and methods satisfying the shared interface, asserted at compile time via a var _ Interface[T] = (*Type[T])(nil) pattern. Cross-cutting concerns (comparators, iterators, enumerables, serialization) are factored into shared utils and containers packages that individual structures compose rather than inherit from. Data flow is entirely in-process — callers construct a container, mutate it through typed methods, and read back typed values, with no I/O, concurrency, or network layers involved. Because every structure implements and asserts against the shared Container interface, a breaking change to that interface would ripple across all roughly twenty data-structure packages, though the blast radius stays contained within this one repository.

Tech Stack GoDS is pure Go with zero external runtime dependencies, relying entirely on the standard library’s slices and cmp packages for sorting and comparison, and on native Go generics (type parameters with comparable/cmp.Ordered constraints) for type safety. The module targets Go 1.21+. Build and test tooling is stock go build/go test; CI runs on CircleCI across multiple Go versions with go test -race, publishes coverage to Codecov, and runs golint, while a separate GitHub Actions workflow runs CodeQL static analysis. There is no database, web framework, or deployment target — this is a library consumed via go get, not a running service.

Code Quality Each data structure ships with a co-located _test.go file using idiomatic, table-driven tests against the standard testing package, giving broad structural coverage across the library. Error handling favors explicit boolean returns (e.g. Get(index) (T, bool)) over panics or silently swallowed failures, keeping error states type-safe. Naming is consistent and idiomatic Go (PascalCase exported, camelCase unexported, package names matching directories), and the generics-based API avoids the interface{} casting that its pre-generics v1 required. CI enforces race-detector test runs and CodeQL scanning, though there is no configured modern linter such as golangci-lint beyond CI-invoked golint.

API Design The library’s core ergonomic strength is a uniform contract: every container implements the same base Container interface plus optional Iterator, ReverseIterator, and Enumerable protocols, so switching a program’s underlying structure (say, from ArrayList to a linked-list variant) typically requires no call-site changes. Getting started requires only a New() call per structure with no configuration boilerplate, and documentation is unusually thorough for a library this size — a single README with a full table of contents, a comparison table of every structure’s properties, and a code sample for each one, backed by 28 standalone runnable examples.