refactor: split dbx package into domain files

Reorganize monolithic dbx.go and utility.go into focused files by
concern, add package doc.go, and gitignore coverage.out.

Co-authored-by: Cursor <cursoragent@cursor.com>

ptr.go

@@ -0,0 +1,65 @@
+package dbx
+
+import (
+	"reflect"
+	"strings"
+	"time"
+)
+
+// NowPtr returns a pointer to the current time.
+func NowPtr() *time.Time {
+	now := time.Now()
+	return &now
+}
+
+// Ptr returns a pointer to the given value of any scalar type. Returns nil if the value is a zero value.
+func Ptr[T any](val T) *T {
+	if reflect.ValueOf(val).IsZero() {
+		return nil
+	}
+	return &val
+}
+
+// Val returns the value of the pointer to a scalar type, or the zero value if the pointer is nil.
+func Val[T any](ptr *T) T {
+	if ptr == nil {
+		var zero T
+		return zero
+	}
+	return *ptr
+}
+
+// TrimPtr trims the whitespace from a pointer to a string and returns nil only if the pointer is nil.
+func TrimPtr(s *string) *string {
+	if s == nil {
+		return nil
+	}
+	trimmed := strings.TrimSpace(*s)
+	return &trimmed
+}
+
+// TrimPtrToNil trims the whitespace from a pointer to a string and returns nil
+// if the resulting string is empty or if the pointer is nil.
+func TrimPtrToNil(s *string) *string {
+	if s == nil {
+		return nil
+	}
+	trimmed := strings.TrimSpace(*s)
+	if trimmed == "" {
+		return nil
+	}
+	return &trimmed
+}
+
+// IsZero checks if a pointer references the zero value of a given type and
+// returns an error if this condition is met, otherwise returns nil if the
+// pointer is nil or the value is not zero.
+func IsZero[T any](ptr *T) error {
+	if ptr == nil {
+		return nil
+	}
+	if reflect.ValueOf(*ptr).IsZero() {
+		return ErrValueIsZero
+	}
+	return nil
+}