8000 GitHub - noormaulida/gofilt: Lightweight, type-safe filter builder for Go. · GitHub
[go: up one dir, main page]

Skip to content
noormaulidaPublic

About

Lightweight, type-safe filter builder for Go.

Topics

Resources

Stars

0 stars

Watchers

1 watching

Forks

Repository files navigation

gofilt

Lightweight, type-safe filter builder for Go.

Go Tests codecov Go Reference License

Features

  • Parse filters from Go structs via reflection (FromStruct)
  • Parse filters from url.Values / HTTP query string (FromURL)
  • Whitelist allowed fields with WithAllowedFields
  • Multi-field sorting with sort=name,-created_at
  • Whitelist sortable fields with WithAllowedSorts
  • Configurable pagination limits with WithDefaultLimit and WithMaxLimit
  • Deterministic pagination validation with ErrInvalidLimit and ErrInvalidOffset
  • Pagination metadata helper with filter.Pagination(), Page(), NextOffset(), PreviousOffset()
  • Custom struct tag name with WithTagName
  • 12 operators: =, !=, >, >=, <, <=, LIKE, ILIKE, IN, BETWEEN, IS NULL, IS NOT NULL
  • Zero dependencies for the core module
  • Optional adapters: GORM and plain SQL (PostgreSQL-style $N placeholders)

Minimum Go Version

Go 1.22 or higher.

Installation

go get github.com/noormaulida/gofilt@latest

This single command installs the core package plus the GORM adapter and SQL adapter together. No separate installs required.

Quick Start

From Struct

package main

import "github.com/noormaulida/gofilt"

type UserQuery struct {
    Name   string `filt:"col:name;op:ilike"`
    Age    int    `filt:"col:age;op:gte"`
    Status string `filt:"col:status"`
}

func main() {
    req := UserQuery{Name: "Noor", Age: 20, Status: "active"}
    filter, _ := gofilt.FromStruct(req,
        gofilt.WithAllowedFields("name", "age", "status"),
    )
    // filter.Conditions = [
    //   {Field: "name", Operator: "ILIKE", Value: "Noor"},
    //   {Field: "age",  Operator: ">=",    Value: 20},
    //   {Field: "status", Operator: "=",    Value: "active"},
    // ]
}

From URL Query Params

package main

import (
    "errors"
    "net/http"

    "github.com/noormaulida/gofilt"
)

func handler(w http.ResponseWriter, r *http.Request) {
    filter, err := gofilt.FromURL(r.URL.Query(),
        gofilt.WithAllowedFields("name", "age", "status"),
        gofilt.WithAllowedSorts("name", "created_at"),
        gofilt.WithDefaultLimit(20),
        gofilt.WithMaxLimit(100),
    )
    if errors.Is(err, gofilt.ErrInvalidLimit) {
        http.Error(w, "invalid limit parameter", http.StatusBadRequest)
        return
    }
    if errors.Is(err, gofilt.ErrInvalidOffset) {
        http.Error(w, "invalid offset parameter", http.StatusBadRequest)
        return
    }
    if err != nil {
        http.Error(w, err.Error(), http.StatusBadRequest)
        return
    }

    // Query string:
    // ?name[ilike]=Noor&age[gte]=20&sort=name,-created_at&limit=10&offset=20
    _ = filter.Limit  // 10
    _ = filter.Offset // 20
    // filter.Sorts = [
    //   {Field: "name",       Direction: "ASC"},
    //   {Field: "created_at", Direction: "DESC"},
    // ]
}

Sorting is disabled until WithAllowedSorts is configured. Unknown sort fields are ignored, preventing query parameters from becoming arbitrary SQL identifiers.

Supported URL syntax:

Syntax Operator
name=Noor = (default)
name[eq]=Noor =
name[ne]=Noor !=
age[gt]=20 >
age[gte]=21 >=
age[lt]=100 <
age[lte]=99 <=
name[like]=noo LIKE
name[ilike]=noo ILIKE
id[in]=1,2,3 IN (auto-split comma)
status=active,pending IN (auto-detect comma)
deleted_at[null]=true IS NULL (isnull, is_null, is are aliases; value is ignored)
deleted_at[is]=null IS NULL
deleted_at[notnull]=true IS NOT NULL (isnotnull, not_null, is_not_null are aliases)
or.role=admin&or.role=moderator OR group, combined with other fields using AND
or.0.role=admin&or.1.status=pending Separate indexed OR groups
and.0.status=active&and.0.age[gte]=18 Indexed AND group
q=noor or search=noor Free-text search, only after WithSearchFields
fields=id,name,email Column projection, only after WithSelectFields
sort=name Sort by name ascending
sort=name,-created_at Sort by name ascending, then created_at descending
limit=10 Pagination limit (defaults with WithDefaultLimit, capped by WithMaxLimit)
offset=20 or page=20 Pagination offset

Negative or non-integer values for limit, offset, or page return ErrInvalidLimit or ErrInvalidOffset deterministically.

Groups

Flat conditions are AND. or. and and. keys build Filter.Expr, a tree of Condition and Group values.

?status=active&age[gte]=18&or.role=admin&or.role=moderator
AND
├── status = active
├── age >= 18
└── OR
    ├── role = admin
    └── role = moderator

Indexed keys keep separate groups: or.0.role=admin&or.0.role=moderator&or.1.status=pending. The same shape can be built in Go:

filter.Expr = gofilt.And(
    gofilt.Condition{Field: "status", Operator: gofilt.OpEq, Value: "active"},
    gofilt.Condition{Field: "age", Operator: gofilt.OpGte, Value: 18},
    gofilt.Or(
        gofilt.Condition{Field: "role", Operator: gofilt.OpEq, Value: "admin"},
        gofilt.Condition{Field: "role", Operator: gofilt.OpEq, Value: "moderator"},
    ),
)

When Expr is set, adapters render that tree and ignore Conditions. Nested groups are parenthesized. A root AND group is not wrapped.

Search

q and search are normal columns until WithSearchFields lists the columns a list endpoint may search. The term is then matched with ILIKE on each of those columns, joined with OR, and combined with the rest of the filter using AND.

filter, err := gofilt.FromURL(r.URL.Query(),
    gofilt.WithSearchFields("name", "email", "phone"),
)
// ?q=noor
// WHERE (name ILIKE '%noor%' OR email ILIKE '%noor%' OR phone ILIKE '%noor%')

q wins when both q and search are set. Identifiers that are not plain column names are ignored.

Field selection

fields is a normal column until WithSelectFields lists the columns a client may request. Unknown names are dropped. The SQL adapter turns the result into a SELECT list. An empty selection returns an empty string so the caller can keep SELECT *.

filter, err := gofilt.FromURL(r.URL.Query(),
    gofilt.WithSelectFields("id", "name", "email"),
)
// ?fields=id,name,email
// filter.Fields = ["id", "name", "email"]
cols := gofiltsql.BuildSELECT(filter) // SELECT id, name, email

Filter.Fields is a flat column list. It does not describe GORM associations, preloads, joins, aliases, or computed expressions. The GORM adapter passes the same safe names to Select and leaves those other concerns to the caller.

Typed URL values

Query values are strings until WithFieldTypes says otherwise. FieldTypesFrom reads column types from a query struct so the URL parser and the struct parser agree.

type UserQuery struct {
    Age    int       `filt:"col:age;op:gte"`
    Active bool      `filt:"col:active"`
    Since  time.Time `filt:"col:created_at;op:gte"`
}

filter, err := gofilt.FromURL(r.URL.Query(),
    gofilt.WithFieldTypes(gofilt.FieldTypesFrom(UserQuery{})),
)
// ?age[gte]=20&active=true&created_at[gte]=2026-01-02T15:04:05Z
// Values are int(20), bool(true), and time.Time — not strings.

Supported types: string, int, int8, int16, int32, int64, uint, uint64, float32, float64, bool, and time.Time.

IN lists are converted element by element (id[in]=1,2,3 with an int field becomes []int). Accepted time layouts are RFC3339 (with optional fractional seconds), 2006-01-02 15:04:05, and 2006-01-02. A value that does not match its field type returns ErrInvalidValue. Fields without a registered type stay strings. IS NULL and IS NOT NULL values are not converted.

Pagination & Metadata

Filter provides a lightweight Pagination() helper to calculate page numbers and offsets:

pagination := filter.Pagination()

page := pagination.Page()           // Current 1-based page number (e.g. 3)
next := pagination.NextOffset()     // Offset for next page (e.g. 30)
prev := pagination.PreviousOffset() // Offset for previous page (e.g. 10, clamped to 0)

Note: Total record count is intentionally excluded from Filter and Pagination. Calculating total records requires a COUNT(*) database query, which is the responsibility of the repository or database layer.

Apply with GORM

import gofiltgorm "github.com/noormaulida/gofilt/adapter/gorm"

var users []User
db := gofiltgorm.Apply(tx, filter)
db.Find(&users)
// Adds ORDER BY name ASC, created_at DESC when filter.Sorts is populated.

Build SQL for database/sql

import gofiltsql "github.com/noormaulida/gofilt/adapter/sql"

cols := gofiltsql.BuildSELECT(filter)
where, args := gofiltsql.BuildWHERE(filter)
orderBy := gofiltsql.BuildORDER(filter)
if cols == "" {
    cols = "SELECT *"
}
// cols = "SELECT id, name, email" when filter.Fields is set
// where = "WHERE name ILIKE $1 AND age >= $2"
// args  = ["%Noor%", 20]
// orderBy = "ORDER BY name ASC, created_at DESC"
rows, _ := db.QueryContext(ctx,
    cols+" FROM users "+where+" "+orderBy,
    args...,
)

Options

Option Description
WithTagName(name string) Override default struct tag ("filt")
WithAllowUnknown(bool) Reserved for future URL-parser strict mode
WithAllowedFields(...string) Whitelist-only mode — drop any field not in the list
WithAllowedSorts(...string) Allow sorting only by listed fields; unknown fields are ignored
WithDefaultLimit(limit int) Fallback limit when no limit is provided in input
WithMaxLimit(max int) Cap the maximum allowed limit to guard against large queries
WithFieldTypes(map[string]reflect.Type) Parse URL values into the listed Go types; omitted fields stay strings
WithSearchFields(...string) Allow q / search to match these columns with ILIKE
WithSelectFields(...string) Allow fields to project only these columns

Struct Tag Format

Tag format: col:<column>;op:<operator> — order does not matter. op is optional and defaults to =. Use - to ignore a field.

type Query struct {
    A string `filt:"col:full_name;op:ilike"` // explicit
    B string `filt:"col:status"`              // op defaults to =
    C string `filt:"-"`                       // skip
    D string `custom:"col:x;op:ne"`           // use WithTagName("custom")
}

Project Layout

gofilt/
├── gofilt.go              # Core types: Filter, Expression, Condition, Group, Operator
├── pagination.go          # Pagination metadata helper: Page, NextOffset, PreviousOffset
├── operator.go            # Operator lookup & aliases (public)
├── options.go             # Option constructors + defaultOptions
├── parser_struct.go       # FromStruct — reflect-based struct parser
├── parser_url.go          # FromURL — url.Values parser
├── value.go               # FieldTypesFrom and URL value conversion
├── adapter/
│   ├── gorm/              # Apply filters, sorting, and pagination to GORM
│   └── sql/               # Build SELECT, WHERE, and ORDER BY clauses
├── go.mod                 # Single module — one `go get` covers all packages
└── *_test.go              # Unit tests

Note: Core and adapters are released together under the same version.

Running Tests

go test -v ./...

License

MIT License

About

Lightweight, type-safe filter builder for Go.

Topics

Resources

Stars

0 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages

0