lib-go

module
v0.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 11, 2026 License: MIT

README

lib-go

A library of reusable code for my personal Golang projects.

🎯 Motivation

Golang is my primary language of choice when developing personal projects that requires a backend.

There are some common patterns and code that I find myself repeating across all my projects, such as setting up logging, database migrations, various utilities to work with time, pointers, etc.

The purpose of this library is to have those common code in one place, so I can easily reuse it across all my projects. Having this library also forces me to think about creating reusable code and abstractions, which is a good practice in software development.

📋 What is included

Utilities
  • cache: Key-value cache abstraction with pluggable backends.
  • env: Typed environment variable helpers.
  • errs: Structured, transport-agnostic application error type.
  • events: Synchronous, in-process event bus.
  • nullable: Generic nullable value type for database-friendly code.
  • pagination: Offset-based and cursor-based pagination types.
  • ptr: Generic pointer utilities.
  • sorting: Validated sort order types for repository queries.
  • timeutil: Testable time abstractions (Clock, Sleeper, Ticker).
  • uow: Unit of Work interfaces for cross-repository transactions.
  • validator: Composable field validator.
HTTP
  • apidoc: HTTP handler for serving an OpenAPI spec and Scalar UI.
  • httpapi: Helpers for building JSON HTTP APIs.
  • httpserver: HTTP server with sane defaults and graceful shutdown.
  • middleware: Common HTTP middleware.
  • spa: HTTP handler for serving single-page applications.
Observability
  • logging: Structured logger built on log/slog.
  • mailer: Email abstraction with pluggable backends.
Testing
  • openapitest: Validate HTTP requests and responses against an OpenAPI spec.
Sub-modules

The following packages are distributed as separate Go modules to keep heavy dependencies opt-in:

Module Import path Description
tracing github.com/brpaz/lib-go/tracing OpenTelemetry tracing: Provider (OTLP/gRPC TracerProvider), StartSpan/EndSpan helpers, and HTTP/test helpers in tracing/middleware and tracing/tracingtest.
db github.com/brpaz/lib-go/db Driver-agnostic database connectivity helpers built on GORM, with migrator (goose schema migrations), uow (GORM-backed unit of work), gormlog (GORM logger adapters) and dbtest (Postgres testcontainers / SQLite test helpers).

🚀 Getting started

Installation
go get github.com/brpaz/lib-go

For sub-modules, install them separately:

go get github.com/brpaz/lib-go/tracing
go get github.com/brpaz/lib-go/db
Usage

Each package includes a README.md file generated by Gomarkdoc, with documentation and examples for that package.

🧑‍💻 Development Quick start

This project uses Devenv as the development environment. Devenv provides an isolated development environment with all the necessary tools and dependencies, without polluting the host machine.

Prerequisites
Quick start
  • Clone the repository:
git clone https://github.com/brpaz/lib-go
cd lib-go
  • Enter the development environment:
direnv allow
  • Run tests:
task test

📦 Adding a new sub-module

Most packages belong in the root module (github.com/brpaz/lib-go). Create a separate Go module only when a package would force heavy dependencies on all consumers — for example, a full SDK, a gRPC stack, or a large framework.

When to create a sub-module
  • The package imports a dependency that is significantly heavier than what the rest of the library pulls in (e.g. gRPC, a database driver, a full observability SDK).
  • Consumers of the package are a subset of the library's users and should be able to opt into the extra weight explicitly.
  • The package is otherwise self-contained and does not need to import the root module.
Steps
  1. Create the package directory and add a go.mod with the sub-module path:
mkdir -p mypackage
cd mypackage
go mod init github.com/brpaz/lib-go/mypackage
  1. Add a go.work entry so the workspace recognises the new module:
go work use ./mypackage

  1. Write the package following the same conventions as the root module.

  2. Run go mod tidy inside the sub-module directory to populate go.sum.

  3. Update this README — add a row to the sub-modules table and an entry in the relevant section above.

  4. Add a release-drafter config at .github/release-drafter-<name>-config.yml (copy an existing one and update name-template and tag-template to use the mypackage/v$RESOLVED_VERSION prefix).

  5. Update the release-drafter workflow (.github/workflows/release-drafter.yml) to add a step for the new config.

The Taskfile and CI matrix pick up new modules automatically via git ls-files, so no changes are needed there.

A note for potential users

[!WARNING]
This library is intended for my personal use and it´s heavily opinionated based on how I like to write Go code. You are free to use it in your projects, but please keep in mind that I won´t be providing any support or guarantees regarding backwards compatibility. Use it at your own risk. The surface of this library is small enough that you can fork it or copy only the parts you need without much hassle.

LICENSE

This project is licensed under the MIT License - see the LICENSE file for details.

Directories

Path Synopsis
Package apidoc provides an HTTP handler for serving OpenAPI documentation.
 Package apidoc provides an HTTP handler for serving OpenAPI documentation.
Package cache provides a key-value Cache abstraction with per-entry expiration, plus implementations for common scenarios.
 Package cache provides a key-value Cache abstraction with per-entry expiration, plus implementations for common scenarios.
db module
Package env provides helpers for reading typed values from environment variables.
 Package env provides helpers for reading typed values from environment variables.
Package errs provides a structured, transport-agnostic error type for domain and application layers.
 Package errs provides a structured, transport-agnostic error type for domain and application layers.
Package events provides a synchronous, in-process event bus for decoupled communication between components.
 Package events provides a synchronous, in-process event bus for decoupled communication between components.
Package httpapi provides helpers for building JSON HTTP APIs.
 Package httpapi provides helpers for building JSON HTTP APIs.
httpapitest
Package httpapitest provides test helpers for the httpapi package.
 Package httpapitest provides test helpers for the httpapi package.
Package httpserver provides a Server that wraps net/http.Server with sane defaults and graceful shutdown support.
 Package httpserver provides a Server that wraps net/http.Server with sane defaults and graceful shutdown support.
Package logging provides a structured logger built on log/slog with support for OpenTelemetry trace/span injection, runtime level control, and a middleware chain for application-specific attribute injection.
 Package logging provides a structured logger built on log/slog with support for OpenTelemetry trace/span injection, runtime level control, and a middleware chain for application-specific attribute injection.
logtest
Package logtest provides test helpers for the log package.
 Package logtest provides test helpers for the log package.
Package mailer provides a Mailer abstraction for sending email, plus implementations for common scenarios.
 Package mailer provides a Mailer abstraction for sending email, plus implementations for common scenarios.
Package nullable provides a generic Value type that represents a value that may or may not be present — like sql.NullString but for any type T.
 Package nullable provides a generic Value type that represents a value that may or may not be present — like sql.NullString but for any type T.
Package openapitest provides utilities for validating HTTP requests and responses against an OpenAPI spec in tests.
 Package openapitest provides utilities for validating HTTP requests and responses against an OpenAPI spec in tests.
Package pagination provides types and helpers for offset-based and cursor-based pagination.
 Package pagination provides types and helpers for offset-based and cursor-based pagination.
Package ptr provides generic helper functions for working with pointer values.
 Package ptr provides generic helper functions for working with pointer values.
Package sorting provides types for validated ORDER BY clauses in repository queries.
 Package sorting provides types for validated ORDER BY clauses in repository queries.
Package spa provides an http.Handler that serves single-page applications.
 Package spa provides an http.Handler that serves single-page applications.
Package timeutil provides utilities for working with time.
 Package timeutil provides utilities for working with time.
tracing module
Package uow defines the Unit of Work interfaces for managing cross-repository transactions without exposing database implementation details to the service layer.
 Package uow defines the Unit of Work interfaces for managing cross-repository transactions without exposing database implementation details to the service layer.
Package validator provides a lightweight, composable field validator.
 Package validator provides a lightweight, composable field validator.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.