GORMX - GORM Utils

Functions

package gormx // import "github.com/go-zoox/gormx"

var Version = "1.0.0"
func Create[T any](one *T) (*T, error)
func Delete[T any, W WhereCondition](where W) (err error)
func DeleteOneByID[T any](id uint) (err error)
func Exists[T any, W WhereCondition](where W) (bool, error)
func Find[T any](page, pageSize uint, where *Where, orderBy *OrderBy) (data []*T, total int64, err error)
func FindAll[T any](where *Where, orderBy *OrderBy) (data []*T, err error)
func FindByID[T any](id uint) (*T, error)
func FindOne[T any, W WhereCondition](where W) (*T, error)
func FindOneAndDelete[T any, W WhereCondition](where W) (*T, error)
func FindOneAndUpdate[T any, W WhereCondition](where W, callback func(*T)) (*T, error)
func FindOneByIDAndDelete[T any](id uint) (*T, error)
func FindOneByIDAndUpdate[T any](id uint, callback func(*T)) (*T, error)
func FindOneByIDOrCreate[T any](id uint, callback func(*T)) (*T, error)
func FindOneOrCreate[T any, W WhereCondition](where W, callback func(*T)) (*T, error)
func GetDB() *gorm.DB
func GetMany[T any](ids []uint) (data []*T, err error)
func GetOrCreate[T any, W WhereCondition](where W, callback func(*T)) (*T, error)
func Has[T any](where map[string]any) bool
func List[T any](page, pageSize uint, where *Where, orderBy *OrderBy) (data []*T, total int64, err error)
func ListALL[T any](where *Where, orderBy *OrderBy) (data []*T, err error)
func LoadDB(engine string, dsn string) (err error)
func Retrieve[T any](id uint) (*T, error)
func Save[T any](one *T) error
func Update[T any](id uint, uc func(*T)) (err error)

// Aggregate Functions
func Sum[T any](field string, where *Where) (float64, error)
func Avg[T any](field string, where *Where) (float64, error)
func Min[T any](field string, where *Where) (interface{}, error)
func Max[T any](field string, where *Where) (interface{}, error)
func CountDistinct[T any](field string, where *Where) (int64, error)
func GroupBy[T any](fields []string, where *Where, aggregates []string) ([]GroupByResult, error)
func Aggregate[T any](field string, where *Where, operations []string) (map[string]interface{}, error)

// Types
type WhereCondition interface{ map[any]any | *Where }  // Generic type constraint for where conditions
type OrderBy []OrderByOne
type OrderByOne struct{ ... }
type Page struct{ ... }
type SetWhereOptions struct{ ... }
type Where []WhereOne
type WhereOne struct{ ... }
type GroupByResult struct{ ... }
type AggregateResult struct{ ... }

Generic Where Support

GORMX now supports both map[any]any and *Where types for where conditions using Go generics. This provides flexibility while maintaining type safety.

Using map[any]any (Simple Queries)

// Find one
user, err := gormx.FindOne[User](map[any]any{"name": "Alice"})

// Check existence
exists, err := gormx.Exists[User](map[any]any{"email": "alice@example.com"})

// Delete
err := gormx.Delete[User](map[any]any{"id": 1})

Using *Where (Complex Queries)

// Fuzzy search
where := gormx.NewWhere()
where.Set("name", "Alice", &gormx.SetWhereOptions{IsFuzzy: true})
user, err := gormx.FindOne[User](where)

// NOT equal
where := gormx.NewWhere()
where.Set("age", 25, &gormx.SetWhereOptions{IsNotEqual: true})
users, err := gormx.FindOne[User](where)

// IN query
where := gormx.NewWhere()
where.Set("status", []string{"active", "pending"}, &gormx.SetWhereOptions{IsIn: true})
user, err := gormx.FindOne[User](where)

// Multiple conditions
where := gormx.NewWhere()
where.Set("category", "electronics")
where.Set("price", 1000, &gormx.SetWhereOptions{IsNotEqual: true})
where.Set("name", "Pro", &gormx.SetWhereOptions{IsFuzzy: true})
product, err := gormx.FindOne[Product](where)

Supported Methods

The following methods support both map[any]any and *Where:

• FindOne[T, W]
• FindOneAndDelete[T, W]
• FindOneAndUpdate[T, W]
• FindOneOrCreate[T, W]
• GetOrCreate[T, W]
• Delete[T, W]
• Exists[T, W]

See WHERE_GENERIC.md for complete documentation.

Aggregate Query Examples

Basic Aggregate Functions

// Sum
total, err := gormx.Sum[Product](&gormx.Where{}, "price")

// Average
avgPrice, err := gormx.Avg[Product](&gormx.Where{}, "price")

// Min/Max
minPrice, err := gormx.Min[Product](&gormx.Where{}, "price")
maxPrice, err := gormx.Max[Product](&gormx.Where{}, "price")

// Count Distinct
uniqueCategories, err := gormx.CountDistinct[Product](&gormx.Where{}, "category")

Group By Queries

// Group by category with count
results, err := gormx.GroupBy[Product](
    []string{"category"}, 
    &gormx.Where{}, 
    []string{"COUNT(*) as count", "SUM(price) as sum"}
)

// Multiple aggregations in one query
aggregates, err := gormx.Aggregate[Product](
    "price", 
    &gormx.Where{}, 
    []string{"sum", "avg", "min", "max", "count"}
)

With Where Conditions

where := &gormx.Where{}
where.Set("category", "electronics")
where.Set("price", 100, &gormx.SetWhereOptions{IsFuzzy: true})

// Sum with conditions
total, err := gormx.Sum[Product](where, "price")

Chain Query Builder

GORMX provides a fluent chain query builder for constructing complex queries:

// Simple query
products, err := gormx.NewQuery[Product]().
    Where("category", "Electronics").
    OrderByDesc("price").
    Limit(10).
    Find()

// Complex query with multiple conditions
products, total, err := gormx.NewQuery[Product]().
    WhereIn("category", []string{"Electronics", "Books"}).
    Where("in_stock", true).
    WhereLike("name", "Pro").
    OrderByDesc("price").
    OrderByAsc("name").
    Paginate(1, 20)

// Aggregate queries
totalValue, err := gormx.NewQuery[Product]().
    Where("category", "Electronics").
    Sum("price")

avgPrice, err := gormx.NewQuery[Product]().
    Where("in_stock", true).
    Avg("price")

// Transactions
err := gormx.NewQuery[Product]().Transaction(func(tx *gormx.QueryBuilder[Product]) error {
    if err := tx.Create(&product); err != nil {
        return err
    }
    return tx.Where("quantity", 0).Update(updates)
})

See CHAIN.md for complete documentation on the chain query builder.