Skip to content

Commit

Permalink
Update documentation with new UUID scalar
Browse files Browse the repository at this point in the history
  • Loading branch information
x80486 committed Aug 8, 2023
1 parent 316f9c2 commit d479268
Show file tree
Hide file tree
Showing 2 changed files with 26 additions and 13 deletions.
3 changes: 3 additions & 0 deletions docs/content/config.md
Original file line number Diff line number Diff line change
Expand Up @@ -113,6 +113,9 @@ models:
- github.com/99designs/gqlgen/graphql.Int
- github.com/99designs/gqlgen/graphql.Int64
- github.com/99designs/gqlgen/graphql.Int32
UUID:
model:
- github.com/99designs/gqlgen/graphql.UUID
```
Everything has defaults, so add things as you need.
Expand Down
36 changes: 23 additions & 13 deletions docs/content/reference/scalars.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,15 +7,25 @@ menu: { main: { parent: "reference", weight: 10 } }

## Built-in helpers

gqlgen ships with some built-in helpers for common custom scalar use-cases, `Time`, `Any`, `Upload` and `Map`. Adding any of these to a schema will automatically add the marshalling behaviour to Go types.
gqlgen ships with some built-in helpers for common custom scalar use-cases, `Time`, `Any`, `Upload` and `Map`.
Adding any of these to a schema will automatically add the marshalling behaviour to Go types.

### Time

```graphql
scalar Time
```

Maps a `Time` GraphQL scalar to a Go `time.Time` struct. This scalar adheres to the [time.RFC3339Nano](https://pkg.go.dev/time#pkg-constants) format.
Maps a `Time` GraphQL scalar to a Go `time.Time` struct.
This scalar adheres to the [time.RFC3339Nano](https://pkg.go.dev/time#pkg-constants) format.

### Universally Unique Identifier (UUID)

```graphql
scalar UUID
```

Maps a `UUID` scalar value to a `uuid.UUID` type.

### Map

Expand Down Expand Up @@ -131,7 +141,7 @@ func ParseLength(string) (Length, error)
func (l Length) FormatContext(ctx context.Context) (string, error)
```

and then wire up the type in .gqlgen.yml or via directives like normal:
and then wire up the type in `.gqlgen.yml` or via directives like normal:

```yaml
models:
Expand All @@ -141,8 +151,8 @@ models:

## Custom scalars with third party types

Sometimes you are unable to add add methods to a type - perhaps you don't own the type, or it is part of the standard
library (eg string or time.Time). To support this we can build an external marshaler:
Sometimes you are unable to add add methods to a type perhaps you don't own the type, or it is part of the standard library (eg `string` or `time.Time`).
To support this we can build an external marshaler:

```go
package mypkg
Expand Down Expand Up @@ -180,26 +190,24 @@ func UnmarshalMyCustomBooleanScalar(v interface{}) (bool, error) {
}
```

Then in .gqlgen.yml point to the name without the Marshal|Unmarshal in front:
Then in `.gqlgen.yml` point to the name without the Marshal|Unmarshal in front:

```yaml
models:
MyCustomBooleanScalar:
model: github.com/me/mypkg.MyCustomBooleanScalar
```
**Note:** you also can un/marshal to pointer types via this approach, simply accept a pointer in your
`Marshal...` func and return one in your `Unmarshal...` func.
**Note:** You also can (un)marshal to pointer types via this approach, simply accept a pointer in your `Marshal...` func and return one in your `Unmarshal...` func.

**Note:** you can also un/marshal with a context by having your custom marshal function return a
`graphql.ContextMarshaler` _and_ your unmarshal function take a `context.Context` as the first argument.
**Note:** You can also un/marshal with a context by having your custom marshal function return a `graphql.ContextMarshaler` _and_ your unmarshal function take a `context.Context` as the first argument.

See the [_examples/scalars](https://github.com/99designs/gqlgen/tree/master/_examples/scalars) package for more examples.

## Marshaling/Unmarshaling Errors

The errors that occur as part of custom scalar marshaling/unmarshaling will return a full path to the field.
For example, given the following schema ...
For example, given the following schema:

```graphql
extend type Mutation{
Expand All @@ -213,6 +221,7 @@ input UserInput {
}
scalar Email
input ContactDetailsInput {
email: Email!
}
Expand All @@ -221,7 +230,6 @@ input ContactDetailsInput {
... and the following variables:

```json
{
"userInput": {
"name": "George",
Expand All @@ -235,7 +243,9 @@ input ContactDetailsInput {
}
```

... and an unmarshal function that returns an error if the email is invalid. The mutation will return an error containing the full path:
... and an unmarshal function that returns an error if the email is invalid.
The mutation will return an error containing the full path:

```json
{
"message": "email invalid",
Expand Down

0 comments on commit d479268

Please sign in to comment.