api-fu

A drop-in query language for any database schema.

[![Go Reference](https://pkg.go.dev/badge/github.com/seldonio/goven.svg)](https://pkg.go.dev/github.com/seldonio/goven)
[![Go Report Card](https://goreportcard.com/badge/github.com/seldonio/goven)](https://goreportcard.com/report/github.com/seldonio/goven)
[![codecov](https://codecov.io/gh/seldonio/goven/branch/master/graph/badge.svg?token=ZBCTOI896Y)](https://codecov.io/gh/seldonio/goven)
[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go)  

# Goven 🧑‍🍳

Goven (go-oven) is a go library that allows you to have a drop-in query language for your database schema. 

* Take any gorm database object and with a few lines of code you can make it searchable.
* [Safe query language not exposing SQL to your users](https://imgs.xkcd.com/comics/exploits_of_a_mom.png).
* Easily extensible to support more advanced queries for your own schema.
* Basic grammar that allows for powerful queries.

Like a real life oven, it takes something raw (your database struct + a query input) and produces something specific (the schema specific parser + SQL output). We call the adaptors "recipes" that Goven can make. Currently Goven only supports a SQL adaptor, but the AST produced by the lexer/parser can easily be extended to other query languages.

## Recipes

### Basic Example

You can make a basic query using gorm against your database, something like this: 

```go
reflection := reflect.ValueOf(&User{})
queryAdaptor, err := sql_adaptor.NewDefaultAdaptorFromStruct(reflection)
if err != nil {
    return nil, err
}

dbQuery := db.WithContext(ctx)
parsedQuery, err := queryAdaptor.Parse("(name=james AND age > 11) OR email=fred@gmail.com")
if err != nil {
	return nil, err
}
dbQuery = query.Model(User{}).Where(parsedQuery.Raw, sql_adaptor.StringSliceToInterfaceSlice(parsedQuery.Values)...)
err = dbQuery.Find(&users).Error
```

The values are interpolated to prevent injection attacks.

### Extension Example

You can also extend the basic query language with regex matchers. An example would be having a Tag struct on your User schema.

```go
type User struct {
	gorm.Model
	name string
	tags []Tag
}

type Tag struct {
	gorm.Model
	Key string
	Value string
}
```

You can make this searchable my defining a regex and a custom matcher.

e.g if we want `tags[key]=value` to work then we can add the following matcher when creating the adaptor.

```go
KeyValueRegex = `(tags)\[(.+)\]`

// keyValueMatcher is a custom matcher for and tags[y].
func keyValueMatcher(ex *goven_parser.Expression) (*goven_sql.SqlResponse, error) {
	reg, err := regexp.Compile(KeyValueRegex)
	if err != nil {
		return nil, err
	}
	slice := reg.FindStringSubmatch(ex.Field)
	if slice == nil {
		return nil, errors.New("didn't match regex expression")
	}
	if len(slice) < 3 {
		return nil, errors.New("regex match slice is too short")
	}
	sq := goven_sql.SqlResponse{
		Raw:    fmt.Sprintf("id IN (SELECT user_id FROM %s WHERE key=? AND value%s?)", slice[1], ex.Comparator),
		Values: []string{slice[2], ex.Value},
	}
	return &sq, nil
}
```

### Protecting Fields

Sometimes we may not want particular fields to be searchable by end users. You can protect them by removing them from the fields mapping when creating your adaptor.

```go
defaultFields := goven_sql.FieldParseValidatorFromStruct(gorm)
delete(defaultFields, "fieldname")
```

## Grammar

Goven has a simple syntax that allows for powerful queries.

Fields can be compared using the following operators: 

`=`, `!=`, `>=`, `<=`, `<`, `>`, `%`

The `%` operator allows you to do partial string matching using LIKE.

Multiple queries can be combined using `AND`, `OR`.

Together this means you can build up a  query like this:

`model_name=iris AND version>=2.0`

More advanced queries can be built up using bracketed expressions:

`(model_name=iris AND version>=2.0) OR artifact_type=TENSORFLOW`


goven

go generate based graphql server library.

![gqlgen](https://user-images.githubusercontent.com/980499/133180111-d064b38c-6eb9-444b-a60f-7005a6e68222.png)


# gqlgen [![Integration](https://github.com/99designs/gqlgen/actions/workflows/integration.yml/badge.svg)](https://github.com/99designs/gqlgen/actions) [![Coverage Status](https://coveralls.io/repos/github/99designs/gqlgen/badge.svg?branch=master)](https://coveralls.io/github/99designs/gqlgen?branch=master) [![Go Report Card](https://goreportcard.com/badge/github.com/99designs/gqlgen)](https://goreportcard.com/report/github.com/99designs/gqlgen) [![Go Reference](https://pkg.go.dev/badge/github.com/99designs/gqlgen.svg)](https://pkg.go.dev/github.com/99designs/gqlgen) [![Read the Docs](https://badgen.net/badge/docs/available/green)](http://gqlgen.com/)

## What is gqlgen?

[gqlgen](https://github.com/99designs/gqlgen) is a Go library for building GraphQL servers without any fuss.<br/>

- **gqlgen is based on a Schema first approach** — You get to Define your API using the GraphQL [Schema Definition Language](http://graphql.org/learn/schema/).
- **gqlgen prioritizes Type safety** — You should never see `map[string]interface{}` here.
- **gqlgen enables Codegen** — We generate the boring bits, so you can focus on building your app quickly.

Still not convinced enough to use **gqlgen**? Compare **gqlgen** with other Go graphql [implementations](https://gqlgen.com/feature-comparison/)

## Quick start
1. [Initialise a new go module](https://golang.org/doc/tutorial/create-module)

       mkdir example
       cd example
       go mod init example

2. Add `github.com/99designs/gqlgen` to your [project's tools.go](https://go.dev/wiki/Modules#how-can-i-track-tool-dependencies-for-a-module)

       printf '//go:build tools\npackage tools\nimport (_ "github.com/99designs/gqlgen"\n _ "github.com/99designs/gqlgen/graphql/introspection")' | gofmt > tools.go

       go mod tidy

3. Initialise gqlgen config and generate models

       go run github.com/99designs/gqlgen init

       go mod tidy

4. Start the graphql server

       go run server.go

More help to get started:
 - [Getting started tutorial](https://gqlgen.com/getting-started/) - a comprehensive guide to help you get started
 - [Real-world examples](https://github.com/99designs/gqlgen/tree/master/_examples) show how to create GraphQL applications
 - [Reference docs](https://pkg.go.dev/github.com/99designs/gqlgen) for the APIs

## Reporting Issues

If you think you've found a bug, or something isn't behaving the way you think it should, please raise an [issue](https://github.com/99designs/gqlgen/issues) on GitHub.

## Contributing

We welcome contributions, Read our [Contribution Guidelines](https://github.com/99designs/gqlgen/blob/master/CONTRIBUTING.md) to learn more about contributing to **gqlgen**
## Frequently asked questions

### How do I prevent fetching child objects that might not be used?

When you have nested or recursive schema like this:

```graphql
type User {
  id: ID!
  name: String!
  friends: [User!]!
}
```

You need to tell gqlgen that it should only fetch friends if the user requested it. There are two ways to do this;

- #### Using Custom Models

Write a custom model that omits the friends field:

```go
type User struct {
  ID int
  Name string
}
```

And reference the model in `gqlgen.yml`:

```yaml
# gqlgen.yml
models:
  User:
    model: github.com/you/pkg/model.User # go import path to the User struct above
```

- #### Using Explicit Resolvers

If you want to keep using the generated model, mark the field as requiring a resolver explicitly in `gqlgen.yml` like this:

```yaml
# gqlgen.yml
models:
  User:
    fields:
      friends:
        resolver: true # force a resolver to be generated
```

After doing either of the above and running generate we will need to provide a resolver for friends:

```go
func (r *userResolver) Friends(ctx context.Context, obj *User) ([]*User, error) {
  // select * from user where friendid = obj.ID
  return friends,  nil
}
```

You can also use inline config with directives to achieve the same result

```graphql
directive @goModel(model: String, models: [String!]) on OBJECT
    | INPUT_OBJECT
    | SCALAR
    | ENUM
    | INTERFACE
    | UNION

directive @goField(forceResolver: Boolean, name: String, omittable: Boolean) on INPUT_FIELD_DEFINITION
    | FIELD_DEFINITION

type User @goModel(model: "github.com/you/pkg/model.User") {
    id: ID!         @goField(name: "todoId")
    friends: [User!]!   @goField(forceResolver: true)
}
```

### Can I change the type of the ID from type String to Type Int?

Yes! You can by remapping it in config as seen below:

```yaml
models:
  ID: # The GraphQL type ID is backed by
    model:
      - github.com/99designs/gqlgen/graphql.IntID # a go integer
      - github.com/99designs/gqlgen/graphql.ID # or a go string
      - github.com/99designs/gqlgen/graphql.UintID # or a go uint
```

This means gqlgen will be able to automatically bind to strings or ints for models you have written yourself, but the
first model in this list is used as the default type and it will always be used when:

- Generating models based on schema
- As arguments in resolvers

There isn't any way around this, gqlgen has no way to know what you want in a given context.

### Why do my interfaces have getters? Can I disable these?
These were added in v0.17.14 to allow accessing common interface fields without casting to a concrete type.
However, certain fields, like Relay-style Connections, cannot be implemented with simple getters.

If you'd prefer to not have getters generated in your interfaces, you can add the following in your `gqlgen.yml`:
```yaml
# gqlgen.yml
omit_getters: true
```

## Other Resources

- [Christopher Biscardi @ Gophercon UK 2018](https://youtu.be/FdURVezcdcw)
- [Introducing gqlgen: a GraphQL Server Generator for Go](https://99designs.com.au/blog/engineering/gqlgen-a-graphql-server-generator-for-go/)
- [Dive into GraphQL by Iván Corrales Solera](https://medium.com/@ivan.corrales.solera/dive-into-graphql-9bfedf22e1a)
- [Sample Project built on gqlgen with Postgres by Oleg Shalygin](https://github.com/oshalygin/gqlgen-pg-todo-example)
- [Hackernews GraphQL Server with gqlgen by Shayegan Hooshyari](https://www.howtographql.com/graphql-go/0-introduction/)


gqlgen

A GraphQL field builder utilizing Go generics with extra utilities and features.

# grapher [![Go Reference](https://pkg.go.dev/badge/github.com/reaganiwadha/grapher.svg)](https://pkg.go.dev/github.com/reaganiwadha/grapher) [![Go Report Card](https://goreportcard.com/badge/github.com/reaganiwadha/grapher)](https://goreportcard.com/report/github.com/reaganiwadha/grapher) [![codecov](https://codecov.io/gh/reaganiwadha/grapher/branch/trunk/graph/badge.svg)](https://codecov.io/gh/reaganiwadha/grapher)

A GraphQL field builder utilizing Go generics with extra utilities and features.
Depends on [graphql-go](https://github.com/graphql-go/graphql).

## Examples
### Without grapher
```go
type PostsQuery struct {
	Limit int         `json:"limit"`
	Query null.String `json:"query"`
	Tags  []string    `json:"tags"`
}

type Post struct {
	ID   int    `json:"id"`
	Body string `json:"body"`
}

func buildField() graphql.Fields {
	return graphql.Fields{
		"GetPosts": &graphql.Field{
			Description : "Returns posts",
			Type: graphql.NewList(graphql.NewObject(
				graphql.ObjectConfig{
					Name:        "Post",
					Fields:      graphql.Fields{
						"id" : &graphql.Field{
							Type: graphql.Int,
						},
						"body" : &graphql.Field{
							Type: graphql.String,
						},
					},
				},
			)),
			Args: map[string]*graphql.ArgumentConfig{
				"limit": {
					Type: graphql.NewNonNull(graphql.Int),
				},
				"query": {
					Type: graphql.String,
				},
				"tags": {
					Type: graphql.NewList(graphql.String),
				},
			},
			Resolve: func(p graphql.ResolveParams) (ret interface{}, err error) {
				var q PostsQuery
				if err = mapstructure.Decode(p.Args, &q); err != nil {
					return
				}

				/// resolver logic
				return
			},
		},
	}
}
```

### With grapher
```go
type PostsQuery struct {
	Limit int         `json:"limit"`
	Query null.String `json:"query"`
	Tags  []string    `json:"tags"`
}

type Post struct {
	ID   int    `json:"id"`
	Body string `json:"body"`
}

func buildFieldGrapher() graphql.Fields{
	return graphql.Fields{
		"GetPosts" : grapher.NewFieldBuilder[PostsQuery, []Post]().
			WithDescription("Returns posts").
			WithResolver(func(p graphql.ResolveParams, query PostsQuery) (ret []Post, err error) {
				// resolver logic
				return 
			}).
			MustBuild(),
	}
}
```

## v1 Development
This package is still a work-in-progress. The feature candidates for the v1 release is :
- [x] Struct to `graphql.Object`/`graphql.InputObject` translator utilizing struct tags
- [x] Struct to `map[string]*graphql.ArgumentConfig{}`
- [x] Configurable struct tags translator
- [x] Schema field builder utilizing go 1.18 Generics feature ensuring type safety
- [x] Resolver middlewares
- [x] Resolver arg validator
- [x] Mux-like schema building with `MutationQueryCollector`

Most features are done, but needs a little bit of polishing.

If you have any feature ideas, do not hesitate to tell and open a new issue in the Issues tab!

## Contributing
Contributions in any way, shape, or form is super welcomed! If you have any issues, ideas or even a question just open a new issue, or make a pull request. 

## License
MIT


The Best Go Libraries For Query Language (4)

api-fu

goven

gqlgen

grapher