golib

module

v0.2.0 Latest Latest Go to latest Published: Jul 9, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/yongjohnlee80/golib

Links

Open Source Insights

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 dao database drivers and server/ws — and, when heavy (the GCP SDK), into their own nested module (dao/bigquery).
Small, adaptable seams. Interfaces are minimal (logger.Logger is 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 dao single-declaration Schema is 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.Context first on I/O calls, io.Writer destinations, iter.Seq iteration, time.Duration means 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 ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
collections 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.
dao 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).
ingestor 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.
logger Package logger provides a small, zero-dependency, level-based logging hook.	Package logger provides a small, zero-dependency, level-based logging hook.
partial 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).
request 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.
server 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.
threadsafe Package threadsafe provides generic, thread-safe value containers for Go.	Package threadsafe provides generic, thread-safe value containers for Go.
tui Package tui is the core of golib's minimal-dependency, retained-mode terminal UI framework (ADR-0001): the driver seam (Backend, Capabilities, TestBackend), the grapheme-cluster cell buffer and render pipeline (Cell, CellAttrs, Surface), the concrete Event set, and the layout value types (Rect, Size, Constraints).	Package tui is the core of golib's minimal-dependency, retained-mode terminal UI framework (ADR-0001): the driver seam (Backend, Capabilities, TestBackend), the grapheme-cluster cell buffer and render pipeline (Cell, CellAttrs, Surface), the concrete Event set, and the layout value types (Rect, Size, Constraints).
examples/demo command Command demo is the ADR-0001 §5.3 acceptance demo for golib/tui: a split layout with focus cycling, a text input, an async-filled list (App.Go), a BufferView streaming colored output, and a status bar — running on term.Open when stdout is a terminal.	Command demo is the ADR-0001 §5.3 acceptance demo for golib/tui: a split layout with focus cycling, a text input, an async-filled list (App.Go), a BufferView streaming colored output, and a status bar — running on term.Open when stdout is a terminal.
internal/grapheme Package grapheme provides Unicode grapheme cluster segmentation (UAX #29 extended grapheme clusters) and terminal display-width measurement (UAX #11 East Asian Width plus UTS #51 emoji data) with zero dependencies, backed by generated, committed tables.	Package grapheme provides Unicode grapheme cluster segmentation (UAX #29 extended grapheme clusters) and terminal display-width measurement (UAX #11 East Asian Width plus UTS #51 emoji data) with zero dependencies, backed by generated, committed tables.
internal/grapheme/gen command Command gen regenerates the grapheme package's tables.go from Unicode Character Database (UCD) files.	Command gen regenerates the grapheme package's tables.go from Unicode Character Database (UCD) files.
style Package style provides the styling, design-token, and theming layer of golib/tui (ADR-0006): an immutable, fluent Style value, a resolvable Color sum type, a semantic Token vocabulary with a derivation-driven Theme, and the BorderStyle prefabs.	Package style provides the styling, design-token, and theming layer of golib/tui (ADR-0006): an immutable, fluent Style value, a resolvable Color sum type, a semantic Token vocabulary with a derivation-driven Theme, and the BorderStyle prefabs.
term Package term is golib/tui's concrete ANSI terminal driver (ADR-0002): the real-terminal implementation of the tui.Backend seam on unix and Windows.	Package term is golib/tui's concrete ANSI terminal driver (ADR-0002): the real-terminal implementation of the tui.Backend seam on unix and Windows.
widget Package widget is golib/tui's standard widget set v1 (ADR-0007): the Base embedding contract, the Box titled-window container, and the eleven widgets sufficient to build sqlit- and lazygit-shaped applications out of the box.	Package widget is golib/tui's standard widget set v1 (ADR-0007): the Base embedding contract, the Box titled-window container, and the eleven widgets sufficient to build sqlit- and lazygit-shaped applications out of the box.