Getting Started

Get up and running with Souuup in just a few minutes. This guide will walk you through installation, basic setup, and your first validation.

Installation

Souuup requires Go 1.21 or later for generics support.

go get

go get github.com/cachesdev/souuup

go.mod

Add to your go.mod file:

require github.com/cachesdev/souuup latest

Then run:

go mod tidy

Quick Start

Let’s create your first validator to see Souuup in action:

package main

import (
    "fmt"
    "log"

    "github.com/cachesdev/souuup/r"
    "github.com/cachesdev/souuup/u"
)

func main() {
    // Data to validate
    username := "john"
    email := "[email protected]"
    age := 25

    // Create a validation schema
    schema := u.Schema{
        "username": u.Field(username, r.MinS(3), r.MaxS(20)),
        "email":    u.Field(email, r.NotZero, r.ContainsS("@")),
        "age":      u.Field(age, r.MinN(18), r.MaxN(120)),
    }

    // Create validator and validate
    s := u.NewSouuup(schema)
    if err := s.Validate(); err != nil {
        log.Fatal("Validation failed:", err)
    }

    fmt.Println("✅ All data is valid!")
}

Core Concepts

Understanding these key concepts will help you get the most out of Souuup:

Fields

Fields are the basic building blocks. Create them with u.Field(value, rules...)

nameField := u.Field("John", r.MinS(2))

Rules

Rules define what makes data valid. They’re functions that take a field state and return an error if invalid.

// Built-in rules
r.MinS(3)    // String min length
r.MaxN(100)  // Number max value
r.NotZero    // Required field

Schemas

Schemas group fields together and can be nested for complex data structures.

schema := u.Schema{
    "user": u.Schema{
        "name": u.Field(name, r.MinS(2)),
    },
}

Validators

Validators execute the validation process and return detailed errors.

s := u.NewSouuup(schema)
err := s.Validate()

Understanding Packages

Souuup is organized into two main packages:

u Package - Core Utilities

The u package contains the core validation framework:

• u.Field() - Create validatable fields
• u.Schema{} - Define validation schemas
• u.NewSouuup() - Create validators
• u.ValidationError - Error handling

r Package - Built-in Rules

The r package provides ready-to-use validation rules:

• String rules: r.MinS(), r.MaxS(), r.ContainsS()
• Numeric rules: r.MinN(), r.MaxN(), r.Gt()
• Slice rules: r.MinLen(), r.Every(), r.Some()
• General rules: r.NotZero, r.SameAs()

Real-World Example

Let’s validate a user registration form:

package main

import (
    "fmt"
    "strings"

    "github.com/cachesdev/souuup/r"
    "github.com/cachesdev/souuup/u"
)

type UserRegistration struct {
    Username        string
    Email           string
    Password        string
    ConfirmPassword string
    Age             int
    Interests       []string
}

// Custom email validation rule
func ValidEmail(fs u.FieldState[string]) error {
    email := fs.Value
    if !strings.Contains(email, "@") || !strings.Contains(email, ".") {
        return fmt.Errorf("must be a valid email address")
    }
    return nil
}

// Password confirmation rule
func PasswordsMatch(password, confirm string) u.Rule[string] {
    return func(fs u.FieldState[string]) error {
        if password != confirm {
            return fmt.Errorf("passwords do not match")
        }
        return nil
    }
}

func main() {
    user := UserRegistration{
        Username:        "johndoe",
        Email:           "[email protected]",
        Password:        "SecurePass123",
        ConfirmPassword: "SecurePass123",
        Age:             25,
        Interests:       []string{"coding", "reading", "gaming"},
    }

    schema := u.Schema{
        "username": u.Field(user.Username,
            r.NotZero,
            r.MinS(3),
            r.MaxS(20),
        ),
        "email": u.Field(user.Email,
            r.NotZero,
            ValidEmail,
        ),
        "password": u.Field(user.Password,
            r.NotZero,
            r.MinS(8),
            PasswordsMatch(user.Password, user.ConfirmPassword),
        ),
        "age": u.Field(user.Age,
            r.MinN(13),
            r.MaxN(120),
        ),
        "interests": u.Field(user.Interests,
            r.MinLen[string](1),              // At least one interest
            r.MaxLen[string](10),             // At most 10 interests
            r.Every(r.MinS(2)),               // Each interest >= 2 chars
        ),
    }

    s := u.NewSouuup(schema)
    if err := s.Validate(); err != nil {
        fmt.Printf("Validation failed: %s\n", err)
        return
    }

    fmt.Println("✅ User registration is valid!")
}

Error Handling

When validation fails, Souuup provides detailed, structured errors:

// Example error output (JSON format)
{
  "username": {
    "errors": ["length is 2, but needs to be at least 3"]
  },
  "interests": {
    "errors": ["1 elements failed validation\n  [0]: length is 1, but needs to be at least 2"]
  }
}

Next Steps

Now that you have the basics down, explore more advanced features:

Basic Usage Guide

Learn about all the built-in validation rules and how to combine them effectively.

Basic Usage →

Nested Validation

Discover how to validate complex, nested data structures.

Nested Validation →

Custom Rules

Create your own validation rules for domain-specific requirements.

Custom Rules →

API Reference

Complete reference of all available functions and rules.

API Reference →