The typeutil package provides general-purpose type conversion utilities for working with heterogeneous any values, particularly those arising from JSON and YAML parsing.

JSON and YAML parsers produce any values whose concrete type varies at runtime (int, float64, string, etc.). This package provides safe, well-documented conversion functions that handle the common cases without requiring callers to write their own type switches.

Strictly parses numeric types (int, int64, uint64, float64) to int. Returns (value, true) on success and (0, false) for any unrecognized or non-numeric type.

Use this when the caller must distinguish a missing or invalid value from a legitimate zero (e.g. YAML config field parsing where the YAML library has already produced a typed numeric value).

v, ok := typeutil.ParseIntValue(someYAMLField)
if !ok {
    return errors.New("field is missing or not an integer")
}

Extracts a boolean value from a map[string]any by key. Returns false if the map is nil, the key is absent, or the value is not a bool.

enabled := typeutil.ParseBool(config, "enabled")

Converts uint64 to int, returning 0 if the value would overflow int.

Converts uint to int, returning 0 if the value would overflow int. Thin wrapper around SafeUint64ToInt.

Leniently converts any value to int, returning 0 on failure. Unlike ParseIntValue, this function also handles string inputs via strconv.Atoi, making it suitable for heterogeneous sources such as JSON metrics, log-parsed data, or user-provided configuration where a zero default on failure is acceptable.

// Works with int, int64, float64, and string inputs
count := typeutil.ConvertToInt(jsonData["count"])

Safely converts any value (float64, int, int64, string) to float64, returning 0 on failure.

ratio := typeutil.ConvertToFloat(jsonData["ratio"])

• All debug output uses logger.New("typeutil:convert") and is only emitted when DEBUG=typeutil:*.
• float64 → int truncation is logged at debug level when the fractional part is lost.
• uint64 → int overflow returns 0 rather than panicking, following the defensive convention used elsewhere in the codebase.

This specification is automatically maintained by the spec-extractor workflow.