feat: add Must/Maybe generic utilities for error handling

Add Must[T] and Maybe[T] generic functions following common Go patterns:

- Must[T](value T, err error) T - panics with PanicError if err \!= nil,
  returns value unchanged if err == nil. Useful for tests, config loading,
  and cases where errors should never occur.

- Maybe[T](value T, err error) T - always returns value, ignoring error.
  Useful when proceeding with defaults/zero values regardless of errors.

Both functions work with any type T and include comprehensive test coverage
using TESTING.md compliant patterns with named test types, constructor
functions, and generic test helpers.

Also updates README.md with documentation and examples, and adds required
words to cspell dictionary.

Signed-off-by: Alejandro Mery <amery@apply.co>

Author: Alejandro Mery

README.md

@@ -290,6 +290,27 @@ defer func() {
 }()
 ```
 
+### Must/Maybe Utilities
+
+Convenience functions for common error-handling patterns:
+
+* `Must[T](value T, err error) T` - returns value or panics with `PanicError` if
+  err is not nil. Follows the common Go pattern of Must* functions for cases
+  where errors should never occur.
+* `Maybe[T](value T, err error) T` - always returns the value, ignoring any
+  error. Useful when you want to proceed with a default or zero value regardless
+  of error status.
+
+```go
+// Must - panic on error (use in tests, config loading, etc.)
+config := Must(loadConfig("config.json"))  // panics if loadConfig fails
+conn := Must(net.Dial("tcp", "localhost:8080"))  // panics if dial fails
+
+// Maybe - ignore errors, proceed with values
+content := Maybe(os.ReadFile("optional.txt"))  // empty string if file missing
+count := Maybe(strconv.Atoi(userInput))  // zero if parsing fails
+```
+
 ### Unreachable Conditions
 
 For indicating impossible code paths:

internal/build/cspell.json

@@ -6,6 +6,7 @@
     "addrport",
     "addrs",
     "analyser",
+    "Atoi",
     "AppendError",
     "AsError",
     "AsRecovered",
@@ -14,6 +15,7 @@
     "carryforward",
     "Codecov",
     "compounderror",
+    "conn",
     "CompoundError",
     "ContextKey",
     "covermode",
@@ -72,6 +74,7 @@
     "SpinLock",
     "SplitName",
     "splithostport",
+    "strconv",
     "strs",
     "Strs",
     "subpackages",

panic.go

@@ -79,3 +79,39 @@ func Catch(fn func() error) error {
 	var p Catcher
 	return p.Do(fn)
 }
+
+// Must panics if err is not nil, otherwise returns value.
+// This is useful for situations where errors should never occur, such as
+// test setup or configuration loading. It follows the common Go pattern
+// of Must* functions that panic on error. The panic includes proper stack
+// traces pointing to the caller.
+//
+// Example usage:
+//
+//	config := Must(loadConfig("config.json"))  // panics if loadConfig returns error
+//	conn := Must(net.Dial("tcp", "localhost:8080"))  // panics if dial fails
+//	data := Must(json.Marshal(obj))  // panics if marshal fails
+func Must[T any](value T, err error) T {
+	if err != nil {
+		panic(NewPanicWrap(1, err, "core.Must"))
+	}
+	return value
+}
+
+// Maybe returns the value, ignoring any error.
+// This is useful when you want to proceed with a default or zero value
+// regardless of whether an error occurred. Unlike Must, it never panics.
+//
+// Example usage:
+//
+//	// Use empty string if ReadFile fails
+//	content := Maybe(os.ReadFile("optional.txt"))
+//
+//	// Use zero value if parsing fails
+//	count := Maybe(strconv.Atoi(userInput))
+//
+//	// Chain operations where errors are non-critical
+//	data := Maybe(json.Marshal(obj))
+func Maybe[T any](value T, _ error) T {
+	return value
+}

panic_test.go

@@ -2,6 +2,7 @@ package core
 
 import (
 	"errors"
+	"fmt"
 	"testing"
 )
 
@@ -441,3 +442,221 @@ func TestCatchWithPanicRecovery(t *testing.T) {
 		t.Run(tc.name, tc.test)
 	}
 }
+
+// testMust is a helper to test Must function by catching panics.
+// It wraps Must calls in panic recovery to allow testing both success
+// and panic scenarios. Returns the value and any recovered panic as an error.
+func testMust[T any](v0 T, e0 error) (v1 T, e1 error) {
+	defer func() {
+		if e2 := AsRecovered(recover()); e2 != nil {
+			e1 = e2
+		}
+	}()
+
+	v1 = Must(v0, e0)
+	return v1, nil
+}
+
+// mustSuccessTestCase tests Must function success scenarios where no panic should occur.
+type mustSuccessTestCase struct {
+	// Large fields first - interfaces (8 bytes on 64-bit)
+	value any
+	err   error
+
+	// Small fields last - strings (16 bytes on 64-bit)
+	name string
+}
+
+// newMustSuccessTestCase creates a new mustSuccessTestCase with the given parameters.
+// For success cases, err is always nil.
+func newMustSuccessTestCase(name string, value any) mustSuccessTestCase {
+	return mustSuccessTestCase{
+		value: value,
+		err:   nil,
+		name:  name,
+	}
+}
+
+// test validates that Must returns the value unchanged when err is nil.
+func (tc mustSuccessTestCase) test(t *testing.T) {
+	t.Helper()
+
+	tc.testMustWithValue(t)
+}
+
+// testMustT is a generic test helper for Must function with comparable types.
+// It handles the common pattern of testing Must with a value and verifying
+// the result matches expectations.
+func testMustT[V comparable](t *testing.T, tc mustSuccessTestCase, value V) {
+	t.Helper()
+
+	got, err := testMust(value, tc.err)
+	AssertNoError(t, err, "Must success")
+	AssertEqual(t, value, got, "Must value")
+}
+
+// testMustSlice is a specialized test helper for Must function with slice types.
+func testMustSlice[V any](t *testing.T, tc mustSuccessTestCase, value []V) {
+	t.Helper()
+
+	got, err := testMust(value, tc.err)
+	AssertNoError(t, err, "Must success")
+	AssertSliceEqual(t, value, got, "Must slice")
+}
+
+// testMustWithValue dispatches to the appropriate test helper.
+func (tc mustSuccessTestCase) testMustWithValue(t *testing.T) {
+	t.Helper()
+
+	// Test with different types using type switches
+	switch v := tc.value.(type) {
+	case string:
+		testMustT(t, tc, v)
+	case int:
+		testMustT(t, tc, v)
+	case bool:
+		testMustT(t, tc, v)
+	case []int:
+		testMustSlice(t, tc, v)
+	case *int:
+		testMustT(t, tc, v)
+	case struct{ Name string }:
+		testMustT(t, tc, v)
+	default:
+		t.Fatalf("unsupported test value type: %T", tc.value)
+	}
+}
+
+func TestMustSuccess(t *testing.T) {
+	testCases := []mustSuccessTestCase{
+		newMustSuccessTestCase("string success", "hello"),
+		newMustSuccessTestCase("int success", 42),
+		newMustSuccessTestCase("bool success", true),
+		newMustSuccessTestCase("slice success", S(1, 2, 3)),
+		newMustSuccessTestCase("nil pointer success", (*int)(nil)),
+		newMustSuccessTestCase("struct success", struct{ Name string }{"test"}),
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, tc.test)
+	}
+}
+
+// mustPanicTestCase tests Must function panic scenarios where Must should panic.
+type mustPanicTestCase struct {
+	// Large fields first - error interface (8 bytes)
+	err error
+
+	// Small fields last - string (16 bytes)
+	name string
+}
+
+// test validates that Must panics with proper PanicError when err is not nil.
+func (tc mustPanicTestCase) test(t *testing.T) {
+	t.Helper()
+
+	_, err := testMust("value", tc.err)
+	AssertError(t, err, "Must panic")
+
+	// Verify the panic contains our original error
+	AssertTrue(t, errors.Is(err, tc.err), "panic wraps original")
+
+	// Verify it's a proper PanicError
+	panicErr, ok := AssertTypeIs[*PanicError](t, err, "panic type")
+	if ok {
+		// Verify stack trace exists
+		stack := panicErr.CallStack()
+		AssertTrue(t, len(stack) > 0, "has stack trace")
+	}
+}
+
+func TestMustPanic(t *testing.T) {
+	testCases := []mustPanicTestCase{
+		{
+			name: "simple error",
+			err:  errors.New("test error"),
+		},
+		{
+			name: "formatted error",
+			err:  fmt.Errorf("formatted error: %d", 42),
+		},
+		{
+			name: "wrapped error",
+			err:  fmt.Errorf("wrapped: %w", errors.New("inner")),
+		},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, tc.test)
+	}
+}
+
+type maybeTestCase struct {
+	// Large fields first - interfaces (8 bytes)
+	value any
+	err   error
+
+	// Small fields last - string (16 bytes)
+	name string
+}
+
+func (tc maybeTestCase) test(t *testing.T) {
+	t.Helper()
+
+	// Test with different types using type switches
+	switch v := tc.value.(type) {
+	case string:
+		got := Maybe(v, tc.err)
+		AssertEqual(t, v, got, "Maybe string")
+	case int:
+		got := Maybe(v, tc.err)
+		AssertEqual(t, v, got, "Maybe int")
+	case *int:
+		got := Maybe(v, tc.err)
+		AssertEqual(t, v, got, "Maybe pointer")
+	case struct{ Name string }:
+		got := Maybe(v, tc.err)
+		AssertEqual(t, v, got, "Maybe struct")
+	default:
+		t.Fatalf("unsupported test value type: %T", tc.value)
+	}
+}
+
+func TestMaybe(t *testing.T) {
+	testCases := []maybeTestCase{
+		{
+			name:  "string with nil error",
+			value: "hello",
+			err:   nil,
+		},
+		{
+			name:  "string with error",
+			value: "world",
+			err:   errors.New("ignored error"),
+		},
+		{
+			name:  "int with nil error",
+			value: 42,
+			err:   nil,
+		},
+		{
+			name:  "int with error",
+			value: 0,
+			err:   errors.New("another ignored error"),
+		},
+		{
+			name:  "nil pointer with error",
+			value: (*int)(nil),
+			err:   errors.New("pointer error"),
+		},
+		{
+			name:  "struct with error",
+			value: struct{ Name string }{"test"},
+			err:   fmt.Errorf("formatted: %d", 123),
+		},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, tc.test)
+	}
+}