Documentation
¶
Index ¶
Constants ¶
const ( DefaultPageNumber = 0 DefaultPageSize = 10 DefaultSortDesc = false )
Variables ¶
var ErrInvalidPageSize = errors.New("invalid page size")
ErrInvalidPageSize is returned when a page size parameter is not a positive number. This error indicates that the requested page size is invalid for pagination operations.
Functions ¶
This section is empty.
Types ¶
type CRUD ¶
type CRUD[T any, I comparable] interface { // GetAll retrieves all entities of type T from the database. GetAll(ctx context.Context) ([]T, error) // GetByID retrieves a single entity by its ID. // Returns the zero value of T and an error if the entity is not found. GetByID(ctx context.Context, id I) (T, error) // GetByIDs retrieves multiple entities by their IDs. // The returned slice maintains the same order as the input IDs. GetByIDs(ctx context.Context, ids []I) ([]T, error) // Create inserts a new entity into the database. // The entity pointer must not be nil. Create(ctx context.Context, e *T) (sql.Result, error) // DeleteAll removes all entities of type T from the database. DeleteAll(ctx context.Context) (sql.Result, error) // Delete removes a single entity by its ID. Delete(ctx context.Context, id I) (sql.Result, error) // Update modifies an existing entity identified by its ID. // The entity pointer must not be nil. Update(ctx context.Context, id I, e *T) (sql.Result, error) }
CRUD defines a generic interface for basic database operations. Type parameters:
- T: the entity type being managed
- I: the type of the entity's ID field (must be comparable)
type DebugFunc ¶
DebugFunc is a function type used for SQL query debugging and logging. It receives the SQL query string and its arguments before execution.
Parameters:
- sql: The SQL query string to be executed
- args: Variable number of query arguments of any type
type Page ¶
type Page[T any] struct { Number uint // Current page number (0-based) Size uint // Number of items in the current page Total uint64 // Total number of items across all pages TotalPages uint // Total number of pages Content []T // Slice containing the page's items }
Page represents a paginated result set containing items of type T. It includes metadata about the current page, total items, and the actual content.
func NewEmptyPage ¶ added in v0.7.0
NewEmptyPage creates a page with no content and zero counters.
type PageOpt ¶
type PageOpt func(*PageParams)
PageOpt is a function type that modifies PageParams. It follows the functional options pattern for configuring pagination parameters.
func WithPageNumber ¶
WithPageNumber sets the page number. The page number is 0-based, meaning the first page is 0.
func WithPageSize ¶
WithPageSize sets the number of items per page. The page size must be greater than 0.
func WithSortBy ¶
WithSortBy adds a column to sort by. Multiple calls will append to the list of sort columns. If no sort columns are specified, the default is to sort by ID.
func WithSortDesc ¶
WithSortDesc sets the sort order to descending. By default, the sort order is ascending.
type PageParams ¶
type PageParams struct {
PageNumber uint // The current page number (0-based)
PageSize uint // Number of items per page
SortBy []string // List of columns to sort by
SortDesc bool // If true, sort in descending order
}
PageParams defines the parameters for pagination and sorting.
func NewPageParams ¶ added in v0.7.0
func NewPageParams(idColumn string, opts ...PageOpt) (PageParams, error)
NewPageParams creates a new PageParams with the given options and validate it. If no SortBy specified the idColumn will be used for sorting.
func (PageParams) Validate ¶
func (p PageParams) Validate() error
type PageResolver ¶
type PageResolver[T any] interface { // GetPage retrieves a single page of results based on the provided pagination options. GetPage(ctx context.Context, opts ...PageOpt) (Page[T], error) // Count returns the total number of items available across all pages. // This is useful for calculating total pages and displaying pagination metadata. Count(ctx context.Context) (uint64, error) }
PageResolver is an interface for retrieving paginated results of type T.
type SQLExecutor ¶
type SQLExecutor interface {
// SelectOne executes a query that is expected to return at most one row.
// It scans the resulting row into the dest parameter, which must be a pointer.
// Returns an error if the query fails or if scanning into dest fails.
SelectOne(ctx context.Context, dest any, query string, args ...any) error
// SelectMany executes a query that can return multiple rows.
// It scans all resulting rows into the dest parameter, which must be a pointer to a slice.
// Returns an error if the query fails or if scanning into dest fails.
SelectMany(ctx context.Context, dest any, query string, args ...any) error
// Exec executes a query that doesn't return rows (like INSERT, UPDATE, DELETE).
// Returns a Result object summarizing the effect of the query and any error encountered.
Exec(ctx context.Context, query string, args ...any) (sql.Result, error)
// BeginTx starts a new transaction with the given options.
// Returns the transaction object and any error encountered during transaction creation.
BeginTx(ctx context.Context, opts *sql.TxOptions) (*sql.Tx, error)
}
SQLExecutor defines an interface for executing SQL operations. It provides a high-level abstraction for common database operations like selecting single/multiple rows, executing statements, and managing transactions.
Source Files