util

Documentation

Overview

Package util provides utility functions for context handling, string sanitization, and reflection helpers used throughout the Relica library.

Package util provides utility functions for reflection and struct operations.

Index

• func FindPrimaryKeyField(v reflect.Value) (reflect.StructField, reflect.Value, error)
• func IsCanceled(ctx context.Context) bool
• func IsPrimaryKeyZero(v reflect.Value) bool
• func ModelToColumns(model interface{}) map[string]string
• func SanitizeIdentifier(ident string) string
• func SanitizeString(input string) string
• func SetPrimaryKeyValue(field reflect.Value, id int64) error
• func StructToMap(data interface{}) (map[string]interface{}, error)
• func WithTimeout(parent context.Context, timeout time.Duration) (context.Context, context.CancelFunc)
• type PrimaryKeyInfo
  • func FindPrimaryKeyFields(v reflect.Value) (*PrimaryKeyInfo, error)
  • func (pk *PrimaryKeyInfo) IsComposite() bool
  • func (pk *PrimaryKeyInfo) IsSingle() bool

Functions

func FindPrimaryKeyField

func FindPrimaryKeyField(v reflect.Value) (reflect.StructField, reflect.Value, error)

FindPrimaryKeyField finds the primary key field in a struct.

Priority:

1. Field with db:"pk" tag (for explicit PK marking)
2. Field named "ID"
3. Field named "Id"

Returns:

• StructField: metadata about the field
• Value: reflect.Value of the field
• error: if no PK found or composite PK detected

For composite PKs, use FindPrimaryKeyFields instead. This function returns error for composite PKs to maintain backwards compatibility.

func IsCanceled

func IsCanceled(ctx context.Context) bool

IsCanceled checks if the context has been canceled.

func IsPrimaryKeyZero

func IsPrimaryKeyZero(v reflect.Value) bool

IsPrimaryKeyZero checks if primary key value is zero (needs auto-population).

Handles:

• int types: v.Int() == 0
• uint types: v.Uint() == 0
• pointers: v.IsNil() || (deref and check)

Returns false for non-numeric types (string, UUID, etc).

func ModelToColumns

func ModelToColumns(model interface{}) map[string]string

ModelToColumns extracts database columns from struct tags. Handles composite PK syntax: db:"column_name,pk" -> column_name.

func SanitizeIdentifier

func SanitizeIdentifier(ident string) string

SanitizeIdentifier validates and sanitizes database identifiers by removing non-word characters.

func SanitizeString

func SanitizeString(input string) string

SanitizeString removes potentially dangerous SQL characters from input.

func SetPrimaryKeyValue

func SetPrimaryKeyValue(field reflect.Value, id int64) error

SetPrimaryKeyValue sets primary key value using reflection.

Handles:

• int types: int, int8, int16, int32, int64
• uint types: uint, uint8, uint16, uint32, uint64
• pointers: allocate if nil, then set

Returns error on:

• overflow (e.g., int64(1000000) → int8)
• unsupported type
• non-settable field

func StructToMap

func StructToMap(data interface{}) (map[string]interface{}, error)

StructToMap converts a struct to map[string]interface{} using db tags.

Rules:

• Unexported fields are skipped.
• db:"-" fields are skipped.
• db:"column_name" or db:"column_name,pk" maps to column_name.
• Fields without db tag use field name.
• Zero values are included.

Returns error if:

• data is not a struct or *struct.
• data is nil pointer.

func WithTimeout

func WithTimeout(parent context.Context, timeout time.Duration) (context.Context, context.CancelFunc)

WithTimeout creates a context with the specified timeout duration.

Types

type PrimaryKeyInfo

type PrimaryKeyInfo struct {
	Fields  []reflect.StructField // Struct fields in declaration order
	Values  []reflect.Value       // Field values in declaration order
	Columns []string              // DB column names in declaration order
}

PrimaryKeyInfo holds information about primary key fields. Supports both single PK and composite PK (CPK).

func FindPrimaryKeyFields

func FindPrimaryKeyFields(v reflect.Value) (*PrimaryKeyInfo, error)

FindPrimaryKeyFields finds all primary key fields in a struct.

Priority for single PK (backwards compatible):

1. Field with db:"pk" tag (explicit single PK)
2. Fields with db:"column,pk" tags (composite PK)
3. Field named "ID" (fallback)
4. Field named "Id" (last resort)

For composite PK, fields are returned in struct declaration order.

func (*PrimaryKeyInfo) IsComposite

func (pk *PrimaryKeyInfo) IsComposite() bool

IsComposite returns true if this is a composite primary key.

func (*PrimaryKeyInfo) IsSingle

func (pk *PrimaryKeyInfo) IsSingle() bool

IsSingle returns true if this is a single-column primary key.