model

func AddSensitiveFieldPattern ¶

func AddSensitiveFieldPattern(pattern string)

AddSensitiveFieldPattern adds a pattern to the sensitive field patterns in a thread-safe manner. The pattern is matched case-insensitively as a substring of field names.

func ClearValidationCache ¶

func ClearValidationCache()

ClearValidationCache clears the cached validation metadata for all types. This is useful when you register new custom validators and want to ensure they are applied to types that have already been parsed. In normal operation, you should not need to call this function.

func CoerceValue ¶

func CoerceValue(value interface{}, targetType reflect.Type, fieldName string) (interface{}, error)

CoerceValue attempts to coerce a value to the target type with intelligent type conversion. Uses JSON format assumptions by default. Supports conversion between strings, numbers, booleans, time.Time, slices, arrays, and nested structs.

Example:

result, err := model.CoerceValue("123", reflect.TypeOf(0), "user_id")
// result will be int(123)

func CoerceValueWithFormat ¶

func CoerceValueWithFormat(value interface{}, targetType reflect.Type, fieldName string, format Format) (interface{}, error)

CoerceValueWithFormat attempts to coerce a value to the target type with format-specific awareness. Different formats may have different type coercion rules and conventions. This is the core type coercion function used by all parsing operations.

Supported conversions include: - String <-> numeric types (int, float, etc.) - String <-> bool (true/false, 1/0, yes/no, etc.) - String/numeric -> time.Time (various formats) - Array/slice element coercion - Map -> struct conversion with nested coercion

func GetMaxCacheSize ¶

func GetMaxCacheSize() int

GetMaxCacheSize returns the maximum cache size in a thread-safe manner. Default: 1000 types.

func GetMaxInputSize ¶

func GetMaxInputSize() int

GetMaxInputSize returns the maximum input size in a thread-safe manner. Default: 10MB (10 * 1024 * 1024 bytes). Set to 0 to disable size checking.

func GetMaxStructureDepth ¶

func GetMaxStructureDepth() int

GetMaxStructureDepth returns the maximum structure nesting depth in a thread-safe manner. Default: 64 levels. Set to 0 to disable depth checking.

func GetMaxValidationDepth ¶

func GetMaxValidationDepth() int

GetMaxValidationDepth returns the maximum validation depth in a thread-safe manner. Default: 32 levels.

func GetSensitiveFieldPatterns ¶

func GetSensitiveFieldPatterns() []string

GetSensitiveFieldPatterns returns the current sensitive field patterns in a thread-safe manner. Returns a copy of the patterns slice to prevent external modification.

func IsSensitiveField ¶

func IsSensitiveField(fieldName string) bool

IsSensitiveField checks if a field name matches any sensitive field pattern. Matching is case-insensitive and checks if the pattern is a substring of the field name. Returns true if the field should be considered sensitive and its value redacted.

Example:

IsSensitiveField("Password")     // true (matches "password")
IsSensitiveField("user_api_key") // true (matches "api_key")
IsSensitiveField("username")     // false

func ParseInto ¶

func ParseInto[T any](raw []byte) (T, error)

ParseInto parses raw data into a struct of type T with automatic format detection, type coercion, and validation. The format is automatically detected (JSON or YAML) based on the content structure. This is the main entry point for parsing operations in gopantic.

The function checks input size against MaxInputSize (default 10MB) to prevent resource exhaustion. Set MaxInputSize to 0 to disable size checking.

Example:

type User struct {
    ID   int    `json:"id" validate:"required,min=1"`
    Name string `json:"name" validate:"required,min=2"`
}

user, err := model.ParseInto[User](jsonData)
if err != nil {
    log.Fatal(err)
}

func ParseIntoWithFormat ¶

func ParseIntoWithFormat[T any](raw []byte, format Format) (T, error)

ParseIntoWithFormat parses raw data of a specific format into a struct of type T with type coercion and validation. Use this when you know the exact format or want to enforce a specific format. Supports JSON and YAML formats.

The function checks input size against MaxInputSize (default 10MB) to prevent resource exhaustion. Set MaxInputSize to 0 to disable size checking.

Example:

user, err := model.ParseIntoWithFormat[User](yamlData, model.FormatYAML)
if err != nil {
    log.Fatal(err)
}

func RegisterGlobalCrossFieldFunc ¶

func RegisterGlobalCrossFieldFunc(name string, validatorFunc CrossFieldValidatorFunc)

RegisterGlobalCrossFieldFunc is a convenience function to register a cross-field validation function to the default global registry.

Note: If you register custom validators after types have been parsed, you should call ClearValidationCache() to ensure new validators are used for all subsequent parses.

Example usage:

model.RegisterGlobalCrossFieldFunc("password_match", func(fieldName string, fieldValue interface{}, structValue reflect.Value, params map[string]interface{}) error {
    passwordField := structValue.FieldByName("Password")
    if !passwordField.IsValid() {
        return model.NewValidationError(fieldName, fieldValue, "password_match", "Password field not found")
    }

    password := passwordField.Interface().(string)
    confirmPassword, ok := fieldValue.(string)
    if !ok {
        return model.NewValidationError(fieldName, fieldValue, "password_match", "value must be a string")
    }

    if password != confirmPassword {
        return model.NewValidationError(fieldName, fieldValue, "password_match", "passwords do not match")
    }

    return nil
})

func RegisterGlobalFunc ¶

func RegisterGlobalFunc(name string, validatorFunc ValidatorFunc)

RegisterGlobalFunc is a convenience function to register a custom validation function to the default global registry.

Note: If you register custom validators after types have been parsed, you should call ClearValidationCache() to ensure new validators are used for all subsequent parses.

Example usage:

model.RegisterGlobalFunc("password_strength", func(fieldName string, value interface{}, params map[string]interface{}) error {
    password, ok := value.(string)
    if !ok || password == "" {
        return nil // handled by required validator
    }

    if len(password) < 8 {
        return model.NewValidationError(fieldName, value, "password_strength", "password must be at least 8 characters")
    }

    hasUpper := strings.ContainsAny(password, "ABCDEFGHIJKLMNOPQRSTUVWXYZ")
    hasLower := strings.ContainsAny(password, "abcdefghijklmnopqrstuvwxyz")
    hasDigit := strings.ContainsAny(password, "0123456789")

    if !hasUpper || !hasLower || !hasDigit {
        return model.NewValidationError(fieldName, value, "password_strength", "password must contain uppercase, lowercase, and numeric characters")
    }

    return nil
})

func SetMaxCacheSize ¶

func SetMaxCacheSize(size int)

SetMaxCacheSize sets the maximum cache size in a thread-safe manner. Set to 0 for unlimited caching (not recommended for long-running services).

Note: This also updates the exported MaxCacheSize variable for compatibility, but that update is not atomic with respect to direct variable reads.

func SetMaxInputSize ¶

func SetMaxInputSize(size int)

SetMaxInputSize sets the maximum input size in a thread-safe manner. Set to 0 to disable size checking.

Note: This also updates the exported MaxInputSize variable for compatibility, but that update is not atomic with respect to direct variable reads.

func SetMaxStructureDepth ¶

func SetMaxStructureDepth(depth int)

SetMaxStructureDepth sets the maximum structure nesting depth in a thread-safe manner. This prevents resource exhaustion from deeply nested JSON/YAML structures.

Note: This also updates the exported MaxStructureDepth variable for compatibility, but that update is not atomic with respect to direct variable reads.

func SetMaxValidationDepth ¶

func SetMaxValidationDepth(depth int)

SetMaxValidationDepth sets the maximum validation depth in a thread-safe manner. This prevents stack overflow and DoS attacks from deeply nested structures.

Note: This also updates the exported MaxValidationDepth variable for compatibility, but that update is not atomic with respect to direct variable reads.

func SetSensitiveFieldPatterns ¶

func SetSensitiveFieldPatterns(patterns []string)

SetSensitiveFieldPatterns sets the sensitive field patterns in a thread-safe manner. Pass nil or empty slice to disable sensitive field detection. Pass custom patterns to override the defaults.

Example:

model.SetSensitiveFieldPatterns([]string{"password", "secret", "ssn", "credit_card"})

func Validate ¶

func Validate[T any](v *T) error

Validate validates a struct using gopantic validation rules defined in struct tags. This function can be used independently of parsing, allowing you to validate structs that were populated from any source (JSON, YAML, database, environment variables, etc.).

Example:

type User struct {
    ID   int    `json:"id" validate:"required,min=1"`
    Name string `json:"name" validate:"required,min=2"`
}

user := User{ID: 42, Name: "Alice"}
if err := model.Validate(&user); err != nil {
    log.Fatal(err)
}

func ValidateValue ¶

func ValidateValue(fieldName string, value interface{}, rules []ValidationRule) error

ValidateValue applies validation rules to a single value. This function runs all validation rules and aggregates any errors. Use this for simple field validation without cross-field dependencies.

func ValidateValueWithStruct ¶

func ValidateValueWithStruct(fieldName string, value interface{}, rules []ValidationRule, structValue reflect.Value) error

ValidateValueWithStruct applies validation rules to a single value with access to the full struct. This function supports both regular and cross-field validators, making it suitable for complex validation scenarios that require access to other fields in the struct.