Merge pull request #4 from Caknoooo/task/restructuring-clean-explanation

Task/restructuring clean explanation

Author: Caknoooo

README.md

@@ -91,11 +91,33 @@ curl "http://localhost:8080/users?search=admin&sort=id,desc&page=2&per_page=5"
 
 ## 🗂️ Advanced Filtering
 
-### Custom Filter Pattern with Validation
+Use this constructor in every implemented builder.
+```go
+type XQuery struct {
+  db *gorm.DB
+}
 
+func NewXQuery(db *gorm.DB) *XQuery {
+  return &XQuery{
+    db: db,
+  }
+}
+```
+
+### Custom Filter Pattern with Validation
 Create powerful, reusable filters with automatic validation:
 
 ```go
+type UserQuery struct {
+  db *gorm.DB
+}
+
+func NewUserQuery(db *gorm.DB) *UserQuery {
+  return &UserQuery{
+    db: db,
+  }
+}
+
 type UserFilter struct {
     pagination.BaseFilter
     ID       int    `json:"id" form:"id"`
@@ -190,6 +212,16 @@ curl "http://localhost:8080/users?role=user&is_active=true&min_age=25&search=dev
 ### Basic Relationship Loading with Security
 
 ```go
+type UserQuery struct {
+  db *gorm.DB
+}
+
+func NewUserQuery(db *gorm.DB) *UserQuery {
+  return &UserQuery{
+    db: db,
+  }
+}
+
 type User struct {
     ID      uint    `json:"id" gorm:"primaryKey"`
     Name    string  `json:"name"`

examples/athlete.go

@@ -5,6 +5,16 @@ import (
 	"gorm.io/gorm"
 )
 
+type AthleteQuery struct {
+	db *gorm.DB
+}
+
+func NewAthleteQuery(db *gorm.DB) *AthleteQuery {
+	return &AthleteQuery{
+		db: db,
+	}
+}
+
 type Athlete struct {
 	ID            int             `json:"id"`
 	ProvinceID    int             `json:"province_id"`

examples/event.go

@@ -7,6 +7,16 @@ import (
 	"gorm.io/gorm"
 )
 
+type EventQuery struct {
+	db *gorm.DB
+}
+
+func NewEventQuery(db *gorm.DB) *EventQuery {
+	return &EventQuery{
+		db: db,
+	}
+}
+
 type Event struct {
 	ID          uint      `json:"id" gorm:"primaryKey"`
 	Name        string    `json:"name" gorm:"column:name"`

examples/province.go

@@ -5,6 +5,16 @@ import (
 	"gorm.io/gorm"
 )
 
+type ProvinceQuery struct {
+	db *gorm.DB
+}
+
+func NewProvinceQuery(db *gorm.DB) *ProvinceQuery {
+	return &ProvinceQuery{
+		db: db,
+	}
+}
+
 type Province struct {
 	ID       uint      `json:"id" gorm:"primaryKey"`
 	Name     string    `json:"name" gorm:"column:name"`

examples/sport.go

@@ -5,6 +5,16 @@ import (
 	"gorm.io/gorm"
 )
 
+type SportQuery struct {
+	db *gorm.DB
+}
+
+func NewSportQuery(db *gorm.DB) *SportQuery {
+	return &SportQuery{
+		db: db,
+	}
+}
+
 type Sport struct {
 	ID          uint      `json:"id" gorm:"primaryKey"`
 	Name        string    `json:"name" gorm:"column:name"`

helpers.go

@@ -197,3 +197,65 @@ func PaginatedAPIResponseWithIncludes[T any](
 
 	return NewPaginatedResponse(200, message, data, paginationResponse)
 }
+
+// PaginatedQueryWithQueryLayer provides pagination using query layer pattern
+// This function separates the database logic from the handler
+func PaginatedQueryWithQueryLayer[T any](
+	filter IncludableQueryBuilder,
+	queryFunc func(IncludableQueryBuilder) ([]T, int64, error),
+) ([]T, int64, error) {
+	// Validate includes before processing
+	if validator, ok := filter.(interface{ Validate() }); ok {
+		validator.Validate()
+	}
+
+	// Execute query through query layer
+	return queryFunc(filter)
+}
+
+// PaginatedAPIResponseWithQueryLayer creates a complete API response using query layer pattern
+func PaginatedAPIResponseWithQueryLayer[T any](
+	ctx *gin.Context,
+	filter IncludableQueryBuilder,
+	message string,
+	queryFunc func(IncludableQueryBuilder) ([]T, int64, error),
+) PaginatedResponse {
+	// Bind pagination from context
+	if baseFilter, ok := filter.(interface{ BindPagination(*gin.Context) }); ok {
+		baseFilter.BindPagination(ctx)
+	}
+
+	// Bind custom filter parameters
+	if err := ctx.ShouldBindQuery(filter); err != nil {
+		return NewPaginatedResponse(400, "Invalid query parameters: "+err.Error(), nil, PaginationResponse{})
+	}
+
+	// Execute query through query layer
+	data, total, err := PaginatedQueryWithQueryLayer(filter, queryFunc)
+	if err != nil {
+		return NewPaginatedResponse(500, "Internal Server Error: "+err.Error(), nil, PaginationResponse{})
+	}
+
+	paginationResponse := CalculatePagination(filter.GetPagination(), total)
+	return NewPaginatedResponse(200, message, data, paginationResponse)
+}
+
+// BindAndValidateFilter binds pagination and query parameters, then validates the filter
+func BindAndValidateFilter(ctx *gin.Context, filter IncludableQueryBuilder) error {
+	// Bind pagination from context
+	if baseFilter, ok := filter.(interface{ BindPagination(*gin.Context) }); ok {
+		baseFilter.BindPagination(ctx)
+	}
+
+	// Bind custom filter parameters
+	if err := ctx.ShouldBindQuery(filter); err != nil {
+		return err
+	}
+
+	// Validate includes
+	if validator, ok := filter.(interface{ Validate() }); ok {
+		validator.Validate()
+	}
+
+	return nil
+}

query_builder.go

@@ -25,6 +25,17 @@ type AllowedIncludesProvider interface {
 	GetAllowedIncludes() map[string]bool
 }
 
+// DatabaseProvider interface for query builders that need database access
+type DatabaseProvider interface {
+	GetDB() *gorm.DB
+}
+
+// QueryLayerBuilder interface that combines query building with database access
+type QueryLayerBuilder interface {
+	IncludableQueryBuilder
+	DatabaseProvider
+}
+
 // applyAutoSearch applies search automatically based on provided search fields
 func applyAutoSearch(query *gorm.DB, searchTerm string, searchFields []string, dialect DatabaseDialect) *gorm.DB {
 	if len(searchFields) == 0 || searchTerm == "" {
@@ -94,6 +105,15 @@ func PaginatedQueryWithIncludable[T any](
 	db *gorm.DB,
 	builder IncludableQueryBuilder,
 ) ([]T, int64, error) {
+	// If db is nil, try to get it from the builder (for query layer pattern)
+	if db == nil {
+		if dbProvider, ok := builder.(DatabaseProvider); ok {
+			db = dbProvider.GetDB()
+		} else {
+			return nil, 0, fmt.Errorf("database connection not provided")
+		}
+	}
+
 	// Validate the builder
 	builder.Validate()