gormquery

Documentation

Overview

Package gormquery provides utilities to construct GORM scopes based on query parameters defined in github.com/jkaveri/goflexstore/query. This package allows for flexible and reusable query building for GORM, enhancing code modularity and reusability.

The package is mainly utilized in the github.com/jkaveri/flexstore/store/gorm package to create a generic, reusable store that interfaces with GORM for database operations.

Package gormquery provides an extension for GORM, utilizing github.com/jkaveri/goflexstore/query. It facilitates the creation of GORM's scope functions, enhancing flexibility and reusability.

The primary goal of gormquery is to seamlessly integrate complex query functionalities with GORM, allowing for dynamic query building based on various parameters. This integration simplifies the process of constructing sophisticated queries while maintaining clean and maintainable code.

Key features include:

• Dynamic query generation: Based on parameters provided, it dynamically constructs GORM scope functions.
• Enhanced reusability: Encourages code reuse by abstracting common query patterns.
• Flexibility: Easily adapt to various querying requirements without changing the underlying database interactions.

gormquery is especially useful in conjunction with the github.com/jkaveri/flexstore/store/gorm package, providing the necessary tools to create a generic, reusable store that leverages the power of GORM with enhanced query capabilities.

package gormquery

Index

• type Option
  • func WithBuilder(name string, builder ScopeBuilderFunc) Option
  • func WithCustomFilters(customFilters map[string]ScopeBuilderFunc) Option
  • func WithFieldToColMap(fieldToColMap map[string]string) Option
• type ScopeBuilder
  • func NewBuilder(options ...Option) *ScopeBuilder
  • func (b *ScopeBuilder) Build(params query.Params) []ScopeFunc
  • func (b *ScopeBuilder) ClauseLockUpdate(param query.Param) ScopeFunc
  • func (b *ScopeBuilder) Filter(param query.Param) ScopeFunc
  • func (b *ScopeBuilder) GroupBy(param query.Param) ScopeFunc
  • func (b *ScopeBuilder) OR(param query.Param) ScopeFunc
  • func (b *ScopeBuilder) OrderBy(param query.Param) ScopeFunc
  • func (b *ScopeBuilder) Paginate(param query.Param) ScopeFunc
  • func (b *ScopeBuilder) Preload(param query.Param) ScopeFunc
  • func (b *ScopeBuilder) Select(param query.Param) ScopeFunc
• type ScopeBuilderFunc
• type ScopeBuilderRegistry
• type ScopeFunc

Types

type Option

type Option func(*ScopeBuilder)

Option defines a function signature for options that can be applied to ScopeBuilder.

func WithBuilder

func WithBuilder(name string, builder ScopeBuilderFunc) Option

WithBuilder registers a new ScopeBuilderFunc under a specified name. This function is used to add new filter building capabilities to a ScopeBuilder.

Parameters:

• name - The name under which the ScopeBuilderFunc will be registered.
• builder - The ScopeBuilderFunc to be registered.

Example:

gormquery.WithBuilder("customFilterName", customScopeBuilderFunc)

This example demonstrates how to register a custom filter function named "customFilterName".

func WithCustomFilters

func WithCustomFilters(customFilters map[string]ScopeBuilderFunc) Option

WithCustomFilters applies custom filter functions to a ScopeBuilder. This function allows overriding default filter builders for specific filter parameters.

Parameters:

• customFilters - A map of filter names to their corresponding custom filter functions.

Example:

gormquery.WithCustomFilters(map[string]gormquery.ScopeBuilderFunc{
    "name": func(param query.Param) gormquery.ScopeFunc {
        return func(tx *gorm.DB) *gorm.DB {
            p := param.(query.FilterParam)
            return tx.Join("INNER JOIN `user_profiles` ON `user_profiles`.`user_id` = `users`.`id`").
                    Where("`user_profiles`.`first_name` = ?", p.Value)
        }
    },
})

Usage of this function enables custom behavior for specific filter names, such as "name" in this example.

func WithFieldToColMap

func WithFieldToColMap(fieldToColMap map[string]string) Option

WithFieldToColMap configures a mapping from struct field names to database column names in ScopeBuilder. This function is useful when the field names in Go structs differ from the column names in the database.

Parameters:

• fieldToColMap - A map where keys are struct field names and values are the corresponding database column names.

Example:

gormquery.WithFieldToColMap(map[string]string{
    "FieldName": "db_column_name",
})

This example maps the struct field "FieldName" to the database column "db_column_name".

type ScopeBuilder

type ScopeBuilder struct {
	// FieldToColMap holds a mapping from struct field names to database column names.
	FieldToColMap map[string]string
	// Registry maps query parameter types to their corresponding scope builder functions.
	Registry ScopeBuilderRegistry
	// CustomFilters allows for the registration of custom filter functions.
	CustomFilters map[string]ScopeBuilderFunc
}

ScopeBuilder is a utility that constructs GORM scopes based on query parameters. It allows for mapping between field names and database column names, custom handling of query parameters, and registration of custom filter functions.

func NewBuilder

func NewBuilder(options ...Option) *ScopeBuilder

NewBuilder creates a new ScopeBuilder. It accepts various options that can modify the behavior of the scope builder, such as custom mappings between fields and database columns. This function initializes the ScopeBuilder with default handlers for different types of query parameters and applies any provided options to customize its behavior.

func (*ScopeBuilder) Build

func (b *ScopeBuilder) Build(params query.Params) []ScopeFunc

Build constructs a slice of GORM scopes from the provided query parameters. It iterates through the query parameters and uses the registered scope builder functions to create corresponding GORM scopes.

func (*ScopeBuilder) ClauseLockUpdate

func (b *ScopeBuilder) ClauseLockUpdate(param query.Param) ScopeFunc

ClauseLockUpdate constructs a GORM scope for a locking clause query parameter. It adds a locking clause to the main query.

func (*ScopeBuilder) Filter

func (b *ScopeBuilder) Filter(param query.Param) ScopeFunc

Filter constructs a GORM scope for a filter query parameter. It supports custom filters and converts the parameter into a GORM 'Where' clause.

func (*ScopeBuilder) GroupBy

func (b *ScopeBuilder) GroupBy(param query.Param) ScopeFunc

GroupBy constructs a GORM scope for a group by query parameter. It groups query results by specified columns and optionally applies 'Having' clauses.

func (*ScopeBuilder) OR

func (b *ScopeBuilder) OR(param query.Param) ScopeFunc

OR constructs a GORM scope for an OR query parameter. It creates a new GORM DB session and applies a series of 'Or' clauses based on the provided filters.

func (*ScopeBuilder) OrderBy

func (b *ScopeBuilder) OrderBy(param query.Param) ScopeFunc

OrderBy constructs a GORM scope for an order by query parameter. It orders query results by a specified column in ascending or descending order.

func (*ScopeBuilder) Paginate

func (b *ScopeBuilder) Paginate(param query.Param) ScopeFunc

Paginate constructs a GORM scope for a paginate query parameter. It applies an offset and limit to the query based on the paginate parameters.

func (*ScopeBuilder) Preload

func (b *ScopeBuilder) Preload(param query.Param) ScopeFunc

Preload constructs a GORM scope for a preload query parameter. It preloads associations of the main query based on the provided field names and nested scopes.

func (*ScopeBuilder) Select

func (b *ScopeBuilder) Select(param query.Param) ScopeFunc

Select constructs a GORM scope for a select query parameter. It selects specific columns in the query based on the provided field names.

type ScopeBuilderFunc

type ScopeBuilderFunc = func(query.Param) ScopeFunc

ScopeBuilderFunc is a type for functions that build a GORM's scope function from a query parameter. This allows for dynamic creation of query scopes based on different types of query parameters.

type ScopeBuilderRegistry

type ScopeBuilderRegistry = map[string]ScopeBuilderFunc

ScopeBuilderRegistry is a map that acts as a registry for ScopeBuilderFuncs. It maps a query parameter type to its corresponding scope builder function. This registry is used to dynamically select the correct scope builder function based on the query parameter type.

type ScopeFunc

type ScopeFunc = func(*gorm.DB) *gorm.DB

ScopeFunc defines the type for GORM's scope function. It is a function that takes a GORM DB instance and returns a modified instance. It's used for applying query parameters to a GORM database query.