gqlfiltergen

README

gqlfiltergen

Generate filter inputs for your GraphQL schema.

Report a Bug · Request Feature

• About The Project
• Use Cases
• Documentation
  • Installation
  • Base Filter Types
  • Composition Filters
  • Extras
  • Usage
    • Generate Filters
    • Use Filters in Queries
• Contributing
• License

About The Project

gqlfiltergen is a tool designed to automate the generation of filter input types for your GraphQL schema. It simplifies the creation of complex filters such as ==, !=, EXISTS, <, >, LIKE, and more, especially when you're not using a SQL database underneath.

It works as a plugin for gqlgen library.

Use Cases

This tool is particularly useful for:

• In-memory data filtering: Create filters to narrow down results from data stored in memory.
• Key/value databases: Enable filtering by any desired fields when using data backed by a key/value database.
• API consistency: Homogenize your input API to ensure all inputs work the same way across different queries.

Documentation

Installation

To install gqlfiltergen, add it as a plugin when initializing gqlgen api:

api.Generate(cfg,
	api.AddPlugin(gqlfiltergen.NewPlugin(&gqlfiltergen.Options{
		InjectCodeAfter: queriesInject,
	})),
)

InjectCodeAfter contains all the queries and subscriptions that you want to add to the existing ones, but using the Filters that are going to be generated.

Base Filter Types

• eq [FilterString|FilterInt|FilterTime|FilterBoolean]: Check equality.
• exists [FilterString|FilterInt|FilterTime|FilterBoolean]: Check if the value exists and is not nil.
• lt [FilterInt]: Check that the value is less than the specified one on the filter.
• gt [FilterInt]: Check that the value is greater than the specified on the filter.
• like [FilterString]: Apply the provided regular expression to the field value.
• before [FilterTime]: Get elements with a date from before the specified one.
• after [FilterTime]: Get elements with a date after the specified one.

Composition Filters

• _and: Logical operator that will combine two or more conditions, returning true if all of them are true.
• _or: Logical operator that will combine two or more conditions, returning true if at least one of them is true.
• _not: Logical operator that will reverse conditions of the nested filter.

Extras

Extras are features that extract information from the provided filter objects. They might be useful for several use case, mainly to gather data that will make the filter more performant:

• MINMAX: Get the minimum and maximum value from the received filter. This is useful when you want to pre-filter data using a range.

Usage

Begin by defining your GraphQL types in a schema file, e.g., schema.graphql and add the @filterable directive to the fields you want to filter:

type User {
  id: Int! @filterable(extras:[MINMAX])
  name: String! @filterable
  age: Int @filterable
  email: String @filterable
  createdAt: Time @filterable
}

Generate Filters

Execute go generate ./.. as specified at gqlgen documentation.

After doing that, you will have a new input object, called FilterUser.

Use Filters in Queries

query {
  users(where: {
    name: { like: "John.*" },
    age: { gt: 21 }
  }) {
    id
    name
    email
  }
}

Contributing

Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

License

Distributed under the MIT license. See LICENSE for more information.

Documentation

Index

• type AstAndTemplateData
• type FieldMapping
  • func (fm *FieldMapping) CallWrapping(field string) string
  • func (fm *FieldMapping) EvalCallWrapping(code string) string
  • func (fm *FieldMapping) EvalVarWrapping(code string) string
• type Options
• type Plugin
  • func NewPlugin(opts *Options) *Plugin
  • func (f *Plugin) GenerateCode(data *codegen.Data) error
  • func (f *Plugin) InjectSourceEarly() *ast.Source
  • func (f *Plugin) InjectSourceLate(schema *ast.Schema) *ast.Source
  • func (f *Plugin) MutateConfig(cfg *config.Config) error
  • func (f *Plugin) Name() string
• type ProcessingField
• type ProcessingObject
• type TemplateData
• type TypeData

Types

type AstAndTemplateData

type AstAndTemplateData struct {
	Ast      *ast.Definition
	TypeData *TypeData
}

type FieldMapping

type FieldMapping struct {
	FilterField string // Name of the field from the struct
	Field       string // Name of the field from the schema
	TypeName    string // Type name

	IsPointer        bool // Set if the field will be a pointer or not
	IsSlice          bool // Whether the field is a slice or not
	IsSliceBasicType bool
	IsNested         bool // Whether the field is a nested struct or not
	IsMethod         bool // Check if we need to call a method instead of a var
	IsUnion          bool

	IsMinmaxeable bool
}

FieldMapping defines field mapping struct to pass data to the template

func (*FieldMapping) CallWrapping

func (fm *FieldMapping) CallWrapping(field string) string

func (*FieldMapping) EvalCallWrapping

func (fm *FieldMapping) EvalCallWrapping(code string) string

func (*FieldMapping) EvalVarWrapping

func (fm *FieldMapping) EvalVarWrapping(code string) string

type Options

type Options struct {
	InjectCodeAfter string
}

type Plugin

type Plugin struct {
	// contains filtered or unexported fields
}

func NewPlugin

func NewPlugin(opts *Options) *Plugin

func (*Plugin) GenerateCode

func (f *Plugin) GenerateCode(data *codegen.Data) error

func (*Plugin) InjectSourceEarly

func (f *Plugin) InjectSourceEarly() *ast.Source

func (*Plugin) InjectSourceLate

func (f *Plugin) InjectSourceLate(schema *ast.Schema) *ast.Source

func (*Plugin) MutateConfig

func (f *Plugin) MutateConfig(cfg *config.Config) error

func (*Plugin) Name

func (f *Plugin) Name() string

type ProcessingField

type ProcessingField struct {
	Field         *ast.FieldDefinition
	IsMinmaxeable bool
}

type ProcessingObject

type ProcessingObject struct {
	Fields     []*ProcessingField
	Definition *ast.Definition
}

type TemplateData

type TemplateData struct {
	TypeDatas []*TypeData
}

type TypeData

type TypeData struct {
	TypeName   string
	FilterName string
	IsUnion    bool // Whether the type is coming from an union or not
	Fields     []*FieldMapping
}

TypeData holds the data to be passed into the template for every type