Home
go-composites
A collection of pure-Go composites for Composition-Oriented
Programming: small, interface-first building blocks — a null sentinel, an
error interface, a result wrapper, boxed boolean/number/string values,
an array and a dictionary, a compose pipeline, a one-import meta-package,
and a typed generics track. No cgo, no third-party runtime dependencies (only
go-spew in a demo main).
The design is deliberately composition-oriented: each package exposes an
Interface and a private data struct constructed through a New(...)
function (several use functional options such as WithPayload / WithGoString).
Composites are assembled by composing and delegating to smaller composites, never
by inheritance. Fallible methods return a result value
rather than the Go idiom of multiple return values, so the packages compose with
one another, and the Null-Object pattern runs throughout — a fresh Result,
Error or Null is a real, non-nil value, so callers branch on HasError()
instead of nil checks.
Module paths
Org and module path
These projects live in the GitHub organisation go-composites, and their
Go module paths match it — github.com/go-composites/<name>. For example
the array repository declares module github.com/go-composites/array. The
importable package lives under the src/ sub-directory (e.g.
github.com/go-composites/array/src, package Array).
The one exception is the composites
meta-package, which is imported at the module root —
import "github.com/go-composites/composites".
Components
| Module | Import path | What it does |
|---|---|---|
base | github.com/go-composites/base/src | The reflective root every composite embeds: Kind()/RespondTo()/Methods() via reflection, so each repo’s surface stays small. |
null | github.com/go-composites/null/src | A minimal null-object sentinel used as the default result payload. |
error | github.com/go-composites/error/src | The error interface (Message/IsNull) plus null and method-not-implemented sentinels. |
result | github.com/go-composites/result/src | Wraps a payload plus an error built with functional options; HasError() is true only on a real error. |
boolean | github.com/go-composites/boolean/src | A boxed boolean (IsTrue/IsFalse/Equal); its structural IsTrue() is what array’s combinators treat as truthy. |
number | github.com/go-composites/number/src | A boxed numeric value (int/float); arithmetic returns a result, so division by zero is an error value, not a panic. |
bignumber | github.com/go-composites/bignumber/src | An arbitrary-precision integer over math/big.Int (no overflow); unbounded-precision complement to number, arithmetic returns a result. |
rational | github.com/go-composites/rational/src | An exact rational number over math/big.Rat (Ruby’s Rational); fractions stay in lowest terms, arithmetic returns a result. |
complex | github.com/go-composites/complex/src | A complex number a+bi over complex128 (Ruby’s Complex); arithmetic returns a result, with Abs/Conjugate. |
bigfloat | github.com/go-composites/bigfloat/src | An arbitrary-precision float over math/big.Float (256-bit mantissa, Ruby’s BigDecimal); exact decimals, arithmetic returns a result. |
string | github.com/go-composites/string/src | A boxed string value with Set/ToGoString/Split. |
buffer | github.com/go-composites/buffer/src | A mutable text buffer (StringBuilder); Append/AppendRune/Reset mutate in place and chain — the mutable counterpart to string. |
symbol | github.com/go-composites/symbol/src | An interned, immutable identifier (Ruby’s :name); New("x") == New("x"). |
time | github.com/go-composites/time/src | A deterministic instant (no Now()) with embedded-tzdata IANA zone support (In/Zone/UTC) plus a Duration sub-package; fallible Parse/Add/In return a result. |
date | github.com/go-composites/date/src | A deterministic calendar date (year/month/day, no time-of-day; no Today()), the pure-calendar complement to time; fallible FromYMD/Parse/AddDays return a result. |
array | github.com/go-composites/array/src | Interface-first slice with Push/Pop/First/Fetch/Each plus combinators Map/Filter/Reduce/Find/Any/All; every method returns a result. |
dictionary | github.com/go-composites/dictionary/src | An interface-first key/value map; Get of a missing key returns a result error, not a panic. |
set | github.com/go-composites/set/src | An unordered collection of unique items with Union/Intersection/Difference. |
orderedset | github.com/go-composites/orderedset/src | The insertion-ordered sibling of set: same API, but iteration is in first-insertion order. |
sortedset | github.com/go-composites/sortedset/src | The comparator-sorted sibling of set: items kept in ascending less-comparator order (TreeSet-like). |
bag | github.com/go-composites/bag/src | A counted collection (multiset): items carry a multiplicity, with Count/Len/DistinctLen and multiset Sum/Union/Intersection/Difference. |
range | github.com/go-composites/range/src | An integer interval (inclusive/exclusive end, non-zero step); a zero step is a result error, not a panic. |
pair | github.com/go-composites/pair/src | A fixed two-element heterogeneous grouping (First/Second/ToArray). |
proc | github.com/go-composites/proc/src | A first-class callable; Then chains steps railway-style, short-circuiting on an error result. |
enumerator | github.com/go-composites/enumerator/src | A lazy sequence (Ruby Enumerator::Lazy): lazy Map/Filter/Take over a finite or infinite source; result-based terminals. |
compose | github.com/go-composites/compose/src | Pipe/Run compose result-returning steps into one left-to-right, short-circuiting pipeline. |
composites | github.com/go-composites/composites | Meta-package: one import re-exporting the whole vocabulary as type aliases + constructors. |
typed | github.com/go-composites/typed/src/... | A generics parallel track: Result[T], Optional[T], Slice[T] with compile-time type safety. |
Analyzers
| Tool | What it enforces |
|---|---|
nonnil | A go vet-style analyzer that fails the build when an interface carrying IsNull() is returned, assigned, or stored as a bare nil — the Null-Object invariant. |
respondto | A go vet-style analyzer that flags RespondTo reflective sends to a method that does not exist. |
Dependency shape
compose ─┐
string ──┼▶ array ──▶ result ──▶ error
number ──┤ └─────▶ null
boolean ─┘
dictionary ─▶ resulterror and null are leaf packages with no intra-org dependencies; result
composes them; the value and collection composites build on result. The
composites meta-package imports them all and
re-exports them; typed is standalone with zero
dependencies.
Quality bar
Every library (src) package is held to 100% statement coverage (an org
hard rule, gated in CI) and is built and tested across a native + emulated
six-architecture matrix (amd64, arm64, riscv64, loong64, ppc64le, s390x).
Two static analyzers enforce the org’s invariants on every repo:
nonnil for the Null-Object rule and
respondto for reflective dispatch. Everything is pure
Go (CGO_ENABLED=0) and BSD-3-Clause.