golib

README

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

Documentation

Overview

Package golib is a thin, stable façade over stable/alpha versioned packages.

The package is split into three pieces:

• golib (this package) — thin façade exposing New. Stable surface for application code.
• github.com/cnuss/golib/v1 — the stable Builder[T] interface and Result type. Application code that wants to declare types against the interface imports this.
• github.com/cnuss/golib/v1alpha1 — the current implementation. Internals (BuilderImpl, helpers) may change between alpha revisions; pin only if you need direct access to the struct.

New[T]() returns a Builder[T] you configure with With* methods and finalize with Build().

Index

• func New[T any]() v1.Builder[T]

Functions

func New

func New[T any]() v1.Builder[T]

New returns an unconfigured Builder for values of type T. Configure it with the With* methods, then call Build.

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