arm

README

arm

Small, generic utility library for Go 1.18+. The core package has no external dependencies.

Installation

go get -u github.com/mono83/arm

Design principles

1. The core package github.com/mono83/arm has no external dependencies.
2. The core package keeps standard-library imports to a minimum.
3. Sub-packages are prefixed with arm (armhash, armsql, …) so they are visually distinct from standard packages without import aliasing.
4. Sub-packages may pull in external dependencies where appropriate.

---

Core package — arm

import "github.com/mono83/arm"

Control flow

Function	Signature	Description
If	If[T any](cond bool, a, b T) T	Ternary operator
Must	Must[T any](t T, err error) T	Returns t; panics if err != nil
Try	Try(f func() error) error	Calls f in a protected mode, converting panics into errors (with stack trace)

val := arm.If(x > 0, "positive", "non-positive")

data := arm.Must(os.ReadFile("config.json"))

err := arm.Try(func() error {
    riskyOperation()
    return nil
})

Defaults and fallbacks

Function	Signature	Description
Or	Or[T comparable](candidates ...T) T	Returns the first non-zero value
OrUnref	OrUnref[T any](v *T, def T) T	Dereferences v, or returns def if v is nil
OrProvide	OrProvide[T comparable](t T, provide func() T) T	Returns t if non-zero, otherwise calls provide()
Ref	Ref[T any](t T) *T	Returns a pointer to the given value

port := arm.Or(os.Getenv("PORT"), "8080")

timeout := arm.OrUnref(cfg.Timeout, 30*time.Second)

t := arm.OrProvide(req.CreatedAt, time.Now)

ptr := arm.Ref("hello") // *string

Provider combinators — AllOfProvided

Call multiple typed provider functions in order. Returns early on the first nil provider or the first error. All return values are populated on success.

Function	Providers
AllOfProvided2[T1, T2]	2
AllOfProvided3[T1, T2, T3]	3
AllOfProvided4[T1, T2, T3, T4]	4
AllOfProvided5[T1, T2, T3, T4, T5]	5

user, account, err := arm.AllOfProvided2(
    func() (*User, error)    { return db.FindUser(id) },
    func() (*Account, error) { return db.FindAccount(id) },
)

Development stubs — Todo / Todoe

Placeholder functions for code paths that are not yet implemented. The code compiles, but any execution panics (or returns an error) with a descriptive message that includes the expected type.

Function	Behaviour
Todo[T any]() T	Panics with an ErrTodo describing the type
Todoe[T any]() (T, error)	Returns zero value + ErrTodo

func newHandler() http.Handler {
    return arm.Todo[http.Handler]()
    // panics: accessing not implemented value of type "http.Handler"
}

---

Uber Fx integration — armfx

import "github.com/mono83/arm/armfx"

Function	Description
ProvideStruct(x any, anno ...fx.Annotation) fx.Option	Builds an fx.Provide constructor for the given struct, injecting each field from the DI container in declaration order

app := fx.New(
    fx.Provide(newDB, newLogger),
    armfx.ProvideStruct(Service{}),
)

---

Hashing — armhash

import "github.com/mono83/arm/armhash"

Hasher[T] type

type Hasher[T any] func(io.Reader) (T, error)

A function type that reads from an io.Reader and produces a hash value. All built-in hash functions satisfy this type, enabling a uniform API across different algorithms and input forms.

Convenience wrappers

Function	Description
Bytes[T](hash Hasher[T], b []byte) (T, error)	Hash a byte slice
String[T](hash Hasher[T], s string) (T, error)	Hash a string

Built-in hashers

Function	Output	Notes
CRC32(r io.Reader) (uint32, error)	uint32	IEEE polynomial; compatible with MySQL, PHP, gzip, zip, PNG
SHA256(r io.Reader) ([]byte, error)	[]byte	Standard SHA-256

Both stream data through the hash without buffering the full input into memory.

checksum, err := armhash.String(armhash.CRC32, "hello")

digest, err := armhash.Bytes(armhash.SHA256, fileBytes)

BCrypt — armhash/armbcrypt

import "github.com/mono83/arm/armhash/armbcrypt"

Function	Description
NewHasher(cost int) armhash.Hasher[string]	BCrypt hasher with the given cost (≤ 0 falls back to default cost 10)
NewDefaultHasher() armhash.Hasher[string]	BCrypt hasher with default cost
Verify(hash string, password []byte) error	Compares hash against plaintext; returns an error on mismatch
IsValid(hash string, password []byte) bool	Like Verify but returns a bool

hasher := armbcrypt.NewDefaultHasher()
hash, err := armhash.String(hasher, "s3cr3t")

ok := armbcrypt.IsValid(hash, []byte("s3cr3t")) // true

---

SQL helpers — armsql

import "github.com/mono83/arm/armsql"

Function	Description
One[T any](slice []T, err error) (*T, error)	Asserts exactly one row: propagates an incoming error, returns sql.ErrNoRows for an empty slice, and a descriptive error when more than one row is present

row, err := armsql.One(repo.QueryByFilter(ctx, filter))
// err == sql.ErrNoRows → no match
// err != nil           → too many rows or query failed
// row != nil           → exactly one result

---

String utilities — armstr

import "github.com/mono83/arm/armstr"

Function	Description
Len(s string) int	UTF-8 rune count — more correct than len(s), but does not handle multi-codepoint grapheme clusters such as composite emoji

For full grapheme-cluster accuracy use rivo/uniseg.

armstr.Len("héllo") // 5, not 6

Documentation

Index

• func AllOfProvided2[T1, T2 any](f1 func() (T1, error), f2 func() (T2, error)) (t1 T1, t2 T2, err error)
• func AllOfProvided3[T1, T2, T3 any](f1 func() (T1, error), f2 func() (T2, error), f3 func() (T3, error)) (t1 T1, t2 T2, t3 T3, err error)
• func AllOfProvided4[T1, T2, T3, T4 any](f1 func() (T1, error), f2 func() (T2, error), f3 func() (T3, error), ...) (t1 T1, t2 T2, t3 T3, t4 T4, err error)
• func AllOfProvided5[T1, T2, T3, T4, T5 any](f1 func() (T1, error), f2 func() (T2, error), f3 func() (T3, error), ...) (t1 T1, t2 T2, t3 T3, t4 T4, t5 T5, err error)
• func If[T any](condition bool, a T, b T) T
• func Must[T any](t T, err error) T
• func Or[T comparable](candidates ...T) (out T)
• func OrProvide[T comparable](t T, provide func() T) (out T)
• func OrUnref[T any](v *T, def T) T
• func Ref[T any](t T) *T
• func Todo[a any]() a
• func Todoe[a any]() (val a, err error)
• func Try(f func() error) (err error)
• type ErrTodo
  • func (e ErrTodo) Error() string

Functions

func AllOfProvided2

func AllOfProvided2[T1, T2 any](f1 func() (T1, error), f2 func() (T2, error)) (t1 T1, t2 T2, err error)

AllOfProvided2 calls each provider in order, returning early on the first nil provider or the first error. On success all return values are populated.

func AllOfProvided3

func AllOfProvided3[T1, T2, T3 any](f1 func() (T1, error), f2 func() (T2, error), f3 func() (T3, error)) (t1 T1, t2 T2, t3 T3, err error)

AllOfProvided3 calls each provider in order, returning early on the first nil provider or the first error. On success all return values are populated.

func AllOfProvided4

func AllOfProvided4[T1, T2, T3, T4 any](f1 func() (T1, error), f2 func() (T2, error), f3 func() (T3, error), f4 func() (T4, error)) (t1 T1, t2 T2, t3 T3, t4 T4, err error)

AllOfProvided4 calls each provider in order, returning early on the first nil provider or the first error. On success all return values are populated.

func AllOfProvided5

func AllOfProvided5[T1, T2, T3, T4, T5 any](f1 func() (T1, error), f2 func() (T2, error), f3 func() (T3, error), f4 func() (T4, error), f5 func() (T5, error)) (t1 T1, t2 T2, t3 T3, t4 T4, t5 T5, err error)

AllOfProvided5 calls each provider in order, returning early on the first nil provider or the first error. On success all return values are populated.

func If

func If[T any](condition bool, a T, b T) T

If is simple generic ternary operator implementation

func Must

func Must[T any](t T, err error) T

Must takes tuple of value with error and returns only value if error is nil. If error not nil - panics it.

func Or

func Or[T comparable](candidates ...T) (out T)

Or returns first not-default value among all given candidates. If candidates slice is empty it returns default value for T.

func OrProvide

func OrProvide[T comparable](t T, provide func() T) (out T)

OrProvide returns t if it is not the zero value for T, otherwise it calls provide and returns its result.

func OrUnref

func OrUnref[T any](v *T, def T) T

OrUnref returns value of first argument if it's not nil otherwise returns second argument.

func Ref

func Ref[T any](t T) *T

Ref returns reference to given value

func Todo

func Todo[a any]() a

Todo is a temporary stubber function to use for places when some value/component is expected but yet not implemented. Any invocation of this function will produce panic.

func Todoe

func Todoe[a any]() (val a, err error)

Todoe is a temporary stubber function to use for places when some value/component is expected but yet not implemented. Any invocation of this function will produce an error response.

func Try

func Try(f func() error) (err error)

Try runs given function in "protected mode", catching panics if they are thrown within it.

Types

type ErrTodo

type ErrTodo string

ErrTodo is an error returned on TODO assertions

func (ErrTodo) Error

func (e ErrTodo) Error() string