core — package reference

zapp

application lifecycle toolkit. tracks resources and tears them down in LIFO order on close. handles signal-based context cancellation for graceful shutdown.

key exports

New(opts ...Option) *App — create an app with functional options
App.Track(c io.Closer) error — register a resource for cleanup
App.Close() error — tear down all tracked resources in LIFO order
SignalContext(parent context.Context) (context.Context, context.CancelFunc) — context canceled on SIGINT/SIGTERM
CloserFunc — adapts a func() error into an io.Closer
ErrClosed — returned by Track when the app has already been closed

app := zapp.New()

ctx, cancel := zapp.SignalContext(context.Background())
defer cancel()

db := openDB()
app.Track(db)

srv := startServer(ctx, db)
app.Track(zapp.CloserFunc(func() error {
    return srv.Shutdown(context.Background())
}))

<-ctx.Done()

if err := app.Close(); err != nil {
    slog.Error("shutdown", "err", err)
    os.Exit(1)
}

zcache

generic caching with pluggable backends. provides memory, file, and redis implementations behind a common interface. all operations are thread-safe and context-aware.

key exports

Cache[K, V] — complete cache interface (Get, Set, Delete, Clear, Len, Healthy)
Reader[K, V] — read-only interface (Get, Len)
Writer[K, V] — write-only interface (Set, Delete, Clear)
NewMemoryCache[K, V](opts ...MemoryOption) *MemoryCache — in-memory cache with optional TTL
NewFileCache[K, V](opts ...Option) *FileCache — file-backed persistent cache
NewRedisCache[K, V](opts ...RedisOption) *RedisCache — redis-backed distributed cache
WithMemoryTTL[K, V](ttl time.Duration) — set expiry for memory cache entries
ErrNotFound — returned when a key does not exist

ctx := context.Background()
c := zcache.NewMemoryCache[string, int]()
c.Set(ctx, "key", 42)

value, err := c.Get(ctx, "key")
if err != nil {
    // handle ErrNotFound or context.Canceled
}

existed, err := c.Delete(ctx, "key")

zcrypto

encryption primitives for zarlcorp privacy tools. composes proven Go stdlib and x/crypto primitives — no custom cryptography. supports AES-256-GCM, argon2id key derivation, HKDF expansion, age-compatible encryption, and secure memory erasure.

key exports

Encrypt(key, plaintext []byte) ([]byte, error) — AES-256-GCM encryption with random nonce
Decrypt(key, ciphertext []byte) ([]byte, error) — AES-256-GCM decryption
DeriveKey(password, salt []byte) (key, salt []byte, error) — argon2id key derivation
ExpandKey(secret, salt, info []byte) ([]byte, error) — HKDF-SHA256 key expansion
EncryptFile(key []byte, src io.Reader, dst io.Writer) error — encrypt a stream
DecryptFile(key []byte, src io.Reader, dst io.Writer) error — decrypt a stream
EncryptAge(password string, src io.Reader, dst io.Writer) error — age password encryption
DecryptAge(password string, src io.Reader, dst io.Writer) error — age password decryption
EncryptAgeKey(recipients []string, src, dst) error — age X25519 key encryption
DecryptAgeKey(identity string, src, dst) error — age X25519 key decryption
Erase(b []byte) — zero out sensitive data in memory
RandBytes(n int) ([]byte, error) — cryptographic random bytes
RandHex(n int) (string, error) — hex-encoded random string

key, salt, err := zcrypto.DeriveKey([]byte("passphrase"), nil)
if err != nil {
    // handle error
}

ciphertext, err := zcrypto.Encrypt(key, []byte("secret"))
if err != nil {
    // handle error
}

plaintext, err := zcrypto.Decrypt(key, ciphertext)
if err != nil {
    // handle error
}

defer zcrypto.Erase(key)

zfilesystem

filesystem abstraction with OS and in-memory implementations. enables dependency injection for testing while supporting production use cases with real file operations.

key exports

ReadWriteFileFS — complete filesystem interface (read, write, remove, mkdir, open, walkdir)
NewMemFS() *MemFS — in-memory filesystem for testing, thread-safe
NewOSFileSystem(baseDir string) *OSFileSystem — OS-backed filesystem rooted at a base directory
ReadFileFS — read-only file interface
WriteFileFS — write-only file interface
RemoveFS — file removal interface
MkdirFS — directory creation interface
OpenFileFS — file open with flags interface
WalkDirFS — directory tree walking interface

// in-memory filesystem for testing
memfs := zfilesystem.NewMemFS()
memfs.WriteFile("test.txt", []byte("data"), 0644)

data, err := memfs.ReadFile("test.txt")

// OS filesystem for production
osfs := zfilesystem.NewOSFileSystem("/path/to/data")
osfs.WriteFile("config.json", []byte("{}"), 0644)

zoptions

generic functional options pattern. a single type used across all zarlcorp packages to configure structs consistently.

key exports

Option[T any] func(*T) — generic functional option type

type Config struct {
    Name    string
    Timeout time.Duration
}

func WithName(name string) zoptions.Option[Config] {
    return func(cfg *Config) {
        cfg.Name = name
    }
}

cfg := NewConfig(
    WithName("production"),
    WithTimeout(60 * time.Second),
)

zstyle

catppuccin mocha palette, lipgloss style presets, and standard keybindings for TUI applications. every zarlcorp tool imports zstyle to share the same visual identity.

key exports

Base, Mantle, Crust, Surface0..2, Overlay0..2, Text — base colors
Rosewater, Flamingo, Pink, Mauve, Red, Peach, Yellow, Green, Teal, Sky, Blue, Lavender — accent colors
Success, Error, Warning, Info — semantic color aliases
ZburnAccent, ZvaultAccent, ZshieldAccent — per-tool accent colors
Title, Subtitle, Highlight, MutedText — text styles
StatusOK, StatusErr, StatusWarn — status indicator styles
Border, ActiveBorder — structural styles with rounded borders
Logo — zarlcorp ASCII art wordmark
StyledLogo(s lipgloss.Style) string — render logo with a given style
KeyQuit, KeyHelp, KeyUp, KeyDown, KeyEnter, KeyBack, KeyTab, KeyFilter — standard keybindings
CSSVariables — full palette as CSS custom properties

import "github.com/zarlcorp/core/pkg/zstyle"

fmt.Println(zstyle.Title.Render("my tool"))
fmt.Println(zstyle.StatusOK.Render("done"))
fmt.Println(zstyle.StyledLogo(
    lipgloss.NewStyle().Foreground(zstyle.Lavender),
))

zsync

thread-safe concurrent data structures. provides generic map, set, and blocking FIFO queue with read-write locking for optimal performance.

key exports

NewZMap[K, V]() *ZMap — thread-safe generic map (Set, Get, Delete, Keys, Len, Clear)
NewZSet[T]() *ZSet — thread-safe generic set (Add, Contains, Remove, Values, Len, Clear)
Ordered[T cmp.Ordered](s *ZSet[T]) []T — sorted set values for ordered types
ZSet.Ordered(compare func(a, b T) int) []T — sorted set values with custom comparator
NewZQueue[T]() *ZQueue — thread-safe blocking FIFO queue
ZQueue.Push(item T) error — add item to back of queue
ZQueue.Pop() (T, error) — blocking pop from front
ZQueue.PopContext(ctx context.Context) (T, error) — blocking pop with context cancellation
ZQueue.TryPop() (T, error) — non-blocking pop
ZQueue.Close() error — signal shutdown to waiting consumers
ErrQueueClosed, ErrQueueEmpty, ErrCanceled — sentinel errors

m := zsync.NewZMap[string, int]()
m.Set("key", 42)
value, ok := m.Get("key")

s := zsync.NewZSet[string]()
s.Add("value")
if s.Contains("value") {
    s.Remove("value")
}

q := zsync.NewZQueue[string]()
q.Push("item")
item, err := q.Pop() // blocks until item available
q.Close()            // wake waiting consumers