golib

golib is a thin, stable façade over stable/alpha versioned packages (v1 stable contract, v1alpha1 mutable implementation), with CI, CodeQL, OpenSSF Scorecard, cosign-signed releases, Dependabot, examples, and an e2e harness.

The API is a generic builder: New[T]() configures with With* methods and finalizes with Build().

Quick Start

go get github.com/cnuss/golib

package main

import (
	"fmt"

	"github.com/cnuss/golib"
)

func main() {
	res := golib.New[string]().
		WithName("greeting").
		WithValue("hello world").
		Build()

	fmt.Printf("%s: %s\n", res.Name, res.Value) // greeting: hello world
}

(Full source: examples/basic/main.go.)

Layout

Three packages, stable/alpha versioning:

github.com/cnuss/golib           — root façade. Stable surface (New).
github.com/cnuss/golib/v1        — stable Builder[T] interface + Result[T].
github.com/cnuss/golib/v1alpha1  — current implementation. May change
                                   between alpha revisions.

Application code imports the root (golib.New[T]()…). Code that needs to declare types against the interface imports v1. Direct access to the BuilderImpl[T] struct lives in v1alpha1.

For the file-by-file map, see CONTRIBUTING.md → Where to find things.

API at a glance

type Builder[T any] interface {
    WithName(name string) Builder[T]   // display name carried into the Result
    WithValue(v T) Builder[T]          // the payload Build produces
    Build() Result[T]                  // terminal: assembles and returns
    Name() string                      // configured name (empty if unset)
}

type Result[T any] struct {
    Name  string `json:"name,omitempty"`
    Value T      `json:"value"`
}

func New[T any]() Builder[T]   // unconfigured builder

Examples

Self-contained programs in ./examples:

Example	Demonstrates
basic	Smallest wiring — New + WithValue + Build.
named	A typed struct payload carried through WithValue.

Run one locally:

make run basic
make run named

Testing

make test   # library unit + fuzz tests (fast, in-package)
make e2e    # builds and runs every example binary, asserts its output

make e2e runs go test -count=1 -v ./e2e. The -count=1 defeats the test cache, since the harness builds the example binaries at runtime and the cache key wouldn't otherwise pick up example source changes.

Contributing

See CONTRIBUTING.md for the local dev loop, release process, and what makes a good example.

License

MIT