README
¶
golib
A collection of reusable, modular Go packages — general-purpose building blocks for personal and work projects. The design goal is packages with light, adaptable interfaces that drop into existing applications for easy migration and give new applications good patterns to start from.
go get github.com/yongjohnlee80/golib
Design principles
- Zero-dependency core. Every package imports only the standard library and
other golib packages. Third-party dependencies are pushed to leaf subpackages
— the
daodatabase drivers andserver/ws— and, when heavy (the GCP SDK), into their own nested module (dao/bigquery). - Small, adaptable seams. Interfaces are minimal (
logger.Loggeris one method); consumers bridge their own backends rather than adopting a framework. - Data over code. Per-entity/per-use differences are declarations, not
boilerplate — the
daosingle-declarationSchemais the archetype. - Explicit over magic. No struct-tag-driven behavior in core paths, no hidden global state.
- Fail loud, fail typed. Sentinel/typed errors compared with
errors.Is/As; misconfiguration fails at construction; documented behavior claims (thread-safety, capabilities) are true or removed. - Ecosystem-normal shapes.
context.Contextfirst on I/O calls,io.Writerdestinations,iter.Seqiteration,time.Durationmeans a duration.
Packages
| Package | Purpose | Docs |
|---|---|---|
threadsafe |
Generic thread-safe value containers (mutex, RWMutex, lock-free) behind one Value[T] interface |
README |
collections |
Generic Set[T] and stdlib-shaped Map/Filter/Reduce slice ops |
README |
logger |
Small level-based logging seam; Fields/Entry, Adapt, and both slog bridges |
README |
request |
HTTP client: typed error decoding, functional options, multipart, history | README |
ingestor |
Thread-safe buffer-and-flush pipelines to CSV/JSON with bounded background writes | README |
dao |
Generic, driver-agnostic data-access layer — declare an entity once | README · USAGE |
partial |
Three-state (value/absent/null) PATCH payloads, projecting onto dao updates |
README |
server |
Transport-agnostic server core: router, middleware chain, lifecycle, scaffold, session registry | README |
server/http |
HTTP transport: chi-style routing, middleware, JSON helpers, mock server | README |
server/ws |
WebSocket transport — endpoints as ordinary routes on the HTTP core | README |
threadsafe
SynchronizedValue[T] (mutex), MultiReadSyncValue[T] (RWMutex),
AtomicValue[T] (lock-free) — all satisfy Value[T], so you can swap the
locking strategy without changing call sites. The Do/RDo closure discipline
makes compound access race-free by construction.
→ threadsafe/README.md
collections
Set[T] with the full algebra (union, intersect, diff, subset) plus iter.Seq
iteration, and Map/Filter/Reduce (+ -Indexed variants) shaped like the
stdlib slices conventions.
→ collections/README.md
logger
A one-method Logger seam (Log(Severity, any)) that golib packages accept for
optional logging. Fields for structured payloads, Entry that keeps error
chains errors.Is-able, Adapt to bridge any external logger without importing
it, and FromSlog/NewSlogHandler for both log/slog directions.
→ logger/README.md
request
Request/Do(ctx, …) run an HTTP cycle into a Params carrier — transport
errors only, status codes are data. DecodeResponse[T] maps a response into
typed success/error, FormWriter builds multipart, Histories keeps a debug
trail.
→ request/README.md
ingestor
Buffer items in memory and flush them in batches to CSV/JSON files (or any
io.Writer you supply) with bounded, drain-aware background writes.
Ingestor[T] is context-first; embed MemoryLoader[T] to build a custom
backend.
→ ingestor/README.md
dao
A generic, driver-agnostic data-access layer. Declare each entity once (fields, columns, scan targets, joins, sort, search) and that drives column-aware reads, scanning, query building, auto-chunked batch writes, multi-database transactions (incl. two-phase commit), query-time hooks (tenant scoping, soft delete, metrics), and partial (PATCH) updates. Not an ORM — explicit columns, explicit joins, no struct-tag magic.
- Core: zero external dependencies.
- Drivers:
dao/postgres(pgx, native COPY, 2PC),dao/sqlite(pure-Go modernc; the new-driver template),dao/bigquery(read-mostly OLAP, separate module).
→ dao/README.md for the reference, dao/USAGE.md for a worked cookbook (hooks, partial updates, transactions).
partial
Turns a three-state JSON PATCH body (a field carries a value / is absent / is
null) into a Write/Skip/Clear disposition that dao applies directly — with
zero per-entity code. Bind a Patch[T], shape it server-side, and
partial.ApplyRules(dao, patch).
→ partial/README.md
server
A transport-agnostic core (net/http-free) shared by every transport: a
generic tree router, an immutable middleware chain, a lifecycle contract, an
accept-loop Scaffold, and a drain-aware session Registry.
server/http and server/ws
build on it; gRPC/SFTP/raw-TCP adapters slot in the same way.
→ server/README.md
Conventions
Development conventions and the project philosophy are maintained alongside the
codebase; new code follows the zero-dep, small-seam, fail-loud-and-typed rules
above. Structural changes are ADR-first — design records live under docs/.
License
See LICENSE.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package collections provides generic collection types and functional slice operations: an unordered Set with the standard algebra (union, intersect, diff, subset) plus iter.Seq iteration, and Map/Filter/Reduce helpers whose shapes mirror the stdlib slices package conventions.
|
Package collections provides generic collection types and functional slice operations: an unordered Set with the standard algebra (union, intersect, diff, subset) plus iter.Seq iteration, and Map/Filter/Reduce helpers whose shapes mirror the stdlib slices package conventions. |
|
Package dao is a generic, driver-agnostic data-access layer (DAL) for Go.
|
Package dao is a generic, driver-agnostic data-access layer (DAL) for Go. |
|
postgres
Package postgres is the reference Postgres driver for golib/dao, implemented over github.com/jackc/pgx/v5.
|
Package postgres is the reference Postgres driver for golib/dao, implemented over github.com/jackc/pgx/v5. |
|
sqlite
Package sqlite is a SQLite driver for golib/dao, implemented over the standard library database/sql and backed by the pure-Go modernc.org/sqlite driver (no cgo).
|
Package sqlite is a SQLite driver for golib/dao, implemented over the standard library database/sql and backed by the pure-Go modernc.org/sqlite driver (no cgo). |
|
Package ingestor provides generic, thread-safe data ingestion pipelines that buffer items in memory and flush them to various backends.
|
Package ingestor provides generic, thread-safe data ingestion pipelines that buffer items in memory and flush them to various backends. |
|
Package logger provides a small, zero-dependency, level-based logging hook.
|
Package logger provides a small, zero-dependency, level-based logging hook. |
|
Package partial models an HTTP PATCH body as a presence-aware, three-state payload for a model type T (ADR-0001).
|
Package partial models an HTTP PATCH body as a presence-aware, three-state payload for a model type T (ADR-0001). |
|
Package request is a small HTTP client: Request/Do execute a request/response cycle into a Params carrier (transport errors only — status codes are data), DecodeResponse maps the result into typed success or error values, FormWriter builds multipart payloads, and Histories keeps a bounded debug trail of recent request/response pairs.
|
Package request is a small HTTP client: Request/Do execute a request/response cycle into a Params carrier (transport errors only — status codes are data), DecodeResponse maps the result into typed success or error values, FormWriter builds multipart payloads, and Histories keeps a bounded debug trail of recent request/response pairs. |
|
Package server is the shared, transport-agnostic core of golib's server subsystem.
|
Package server is the shared, transport-agnostic core of golib's server subsystem. |
|
http
Package httpserver is the HTTP transport for golib's server subsystem.
|
Package httpserver is the HTTP transport for golib's server subsystem. |
|
ws
Package ws is golib's WebSocket transport (golib-server ADR-0007): endpoints are ordinary routes on the golib/server/http router, wrapped by the same middleware as any handler, with a ctx-first Session API.
|
Package ws is golib's WebSocket transport (golib-server ADR-0007): endpoints are ordinary routes on the golib/server/http router, wrapped by the same middleware as any handler, with a ctx-first Session API. |
|
Package threadsafe provides generic, thread-safe value containers for Go.
|
Package threadsafe provides generic, thread-safe value containers for Go. |