GraphQL Scalars

https://the-guild.dev/graphql/scalars/docs
Admin
GraphQL Scalars is a collection of custom scalar types for GraphQL that provides extended validation...
Tokens:10,991
Snippets:133
Trust Score:10
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install graphql-scalars with npm

Source: https://the-guild.dev/graphql/scalars/docs/quick-start

Installs the graphql-scalars package using npm. Run this in your project root before integrating scalars into your schema.

```sh
npm i graphql-scalars
```

--------------------------------

### Apollo Server setup with graphql-scalars

Source: https://the-guild.dev/graphql/scalars/docs/usage/apollo-server

Use this snippet to configure an Apollo Server with graphql-scalars. It imports all scalar type definitions and resolvers, or individual ones like DateTime, and combines them with your own typeDefs and resolvers. The server listens and logs the URL.

```javascript
import { ApolloServer } from 'apollo-server'
// import all scalars and resolvers from graphql-scalars
import { resolvers as scalarResolvers, typeDefs as scalarTypeDefs } from 'graphql-scalars'
// Alternatively, import individual scalars and resolvers
// import { DateTimeResolver, DateTimeTypeDefinition, ... } from "graphql-scalars"
// Example import of your own defined resolvers
import { resolvers } from './src/resolvers'

// Example importing of your own defined type definitions
const typeDefs = fs.readFileSync(path.join(path.resolve(), './src/schema.graphql'), 'utf-8')

const server = new ApolloServer({
  typeDefs: [
    // use spread syntax(since typeDefs from `graphql-scalars` come as an array) to add all `grahql-scalars` scalar definitions to your typeDefs array
    ...scalarTypeDefs,
    //Or you can add individual scalar definitions to your typeDefs array like this
    DateTimeTypeDefinition,
    // then add your own defined type definitions to your typeDefs array like this(without using spread syntax since this is usually a single string, unless otherwise)
    typeDefs
  ],
  resolvers: {
    // use spread syntax to add all scalar resolvers(from grahql-scalars) to your resolver map
    ...scalarResolvers,
    // Or you can add individual scalar resolvers to your resolver map like this
    DateTimeResolver,
    // then use spread syntax to add your own defined resolvers to your resolver map like this
    ...resolvers
  }
})

server.listen().then(({ url }) => {
  console.log(`🚀 Server ready at ${url}`)
})
```

--------------------------------

### Integrate graphql-scalars with GraphQL-Yoga

Source: https://the-guild.dev/graphql/scalars/docs/usage/yoga

Add the desired scalar type definition and resolver to the schema, then pass the schema to createYoga. No additional setup is required.

```javascript
import { DateTimeResolver, DateTimeTypeDefinition } from 'graphql-scalars'
import { createSchema, createYoga } from 'graphql-yoga'

export const schema = createSchema({
  typeDefs: /* GraphQL */ `
    ${DateTimeTypeDefinition}
    type Query {
      time: DateTime
    }
  `,
  resolvers: {
    DateTime: DateTimeResolver
  }
})

// Create a Yoga instance with a GraphQL schema.
const yoga = createYoga({ schema })
```

--------------------------------

### Result Coercion Examples

Source: https://the-guild.dev/graphql/scalars/docs/scalars/date

Shows how JavaScript Date instances are coerced to RFC 3339 date strings in UTC. Invalid Date instances raise a field error.

```javascript
new Date('2023-02-03T01:00:00Z') // 2023-02-03
new Date('2023-02-03T01:00:00+0500') // 2023-02-02
```

--------------------------------

### Import ready-to-use scalar type definitions

Source: https://the-guild.dev/graphql/scalars/docs/quick-start

Shows how to import ready-to-use type definitions for scalars, either all at once or specific ones, using ES6 imports or CommonJS require.

```ts
// or import specific typeDefs only with ES6 Import
// or import all typeDefs once with ES6 Import
import { ScalarNameTypeDefinition, typeDefs as scalarTypeDefs } from 'graphql-scalars'

// or import specific typeDefs only with CommonJS
const { ScalarNameTypeDefinition } = require('graphql-scalars')

// or import all typeDefs once with CommonJS
const { typeDefs: scalarTypeDefs } = require('graphql-scalars')

const typeDefs = [
  ...scalarTypeDefs
  // other typeDefs
]
// or
const typeDefs = [
  ScalarNameTypeDefinition
  // other typeDefs
]
```

--------------------------------

### Using mocks with Apollo Server

Source: https://the-guild.dev/graphql/scalars/docs/usage/mocks

Use this snippet to configure Apollo Server with mocks from graphql-scalars. It imports all scalars, resolvers, and mocks, and spreads them into the server's typeDefs, resolvers, and mocks options. Comments show how to import individual scalars instead.

```ts
import { ApolloServer } from 'apollo-server'
// import all scalars and resolvers
import { mocks, resolvers, typeDefs } from 'graphql-scalars'
import { makeExecutableSchema } from '@graphql-tools/schema'

// Alternatively, import individual scalars and resolvers
// import { DateTimeResolver, DateTimeTypeDefinition, DateTimeMock, ... } from 'graphql-scalars'

const server = new ApolloServer({
  typeDefs: [
    // use spread syntax to add scalar definitions to your schema
    ...typeDefs
    // DateTimeTypeDefinition,
    // ... other type definitions
  ],
  resolvers: {
    // use spread syntax to add scalar resolvers to your resolver map
    ...resolvers
    // DateTimeResolver,
    // ... the remainder of the resolver map
  },
  mocks: {
    // use spread syntax to add scalar resolvers to your resolver map
    ...mocks
    // DateTimeMock,
    // ... other mocks
  }
})
```

--------------------------------

### Import individual scalars with their mocks

Source: https://the-guild.dev/graphql/scalars/docs/usage/mocks

Use this snippet to add mocks for individual scalars, such as DateTime, by importing their specific type definition, resolver, and mock from graphql-scalars. It shows how to include them in your schema and resolver maps.

```ts
import { addMocksToSchema } from '@graphql-tools/mock'
import { DateTimeTypeDefinition, DateTimeResolver, DateTimeMock } from 'graphql-scalars'
const schema = makeExecutableSchema({
  typeDefs: [
    DateTimeTypeDefinition
    // all others typeDefs
  ],
  resolvers: {
    DateTime: DateTimeResolver
    // all others resolvers
  }
})
const mockedSchema = addMocksToSchema({
  schema,
  mocks: {
    DateTime: DateTimeMock
    // others mocks
  }
})
```

--------------------------------

### Import all scalars with all mocks

Source: https://the-guild.dev/graphql/scalars/docs/usage/mocks

Use this snippet to add mocks for all scalars from graphql-scalars to your GraphQL schema using addMocksToSchema from @graphql-tools/mock. It spreads the scalarsTypeDefs, scalarsResolvers, and scalarsMocks into your schema and resolver maps.

```ts
import { addMocksToSchema } from '@graphql-tools/mock'
import { typeDefs as scalarsTypeDefs, resolvers as scalarsResolvers, mocks as scalarsMocks } from 'graphql-scalars'
const schema = makeExecutableSchema({
  typeDefs: [
    ...scalarsTypeDefs
    // all others typeDefs
  ],
  resolvers: {
    ...scalarsResolvers
    // all others resolvers
  }
})
const mockedSchema = addMocksToSchema({
  schema,
  mocks: {
    ...scalarsMocks
    // others mocks
  }
})
```

--------------------------------

### Import ScalarNameResolver from graphql-scalars

Source: https://the-guild.dev/graphql/scalars/docs/usage

Import the resolver for the scalar. Supports both ES6 import and CommonJS require.

```ts
// or import specific resolvers only with ES6 Import
import { ScalarNameResolver } from 'graphql-scalars'

// or import specific resolvers only with CommonJS
const { ScalarNameResolver } = require('graphql-scalars')
```

--------------------------------

### new RegularExpression(name, regex, options?)

Source: https://the-guild.dev/graphql/scalars/docs/usage/regex

Creates a new GraphQLScalarType that validates values against a given regular expression. The constructor takes a name, a regex, and an optional options object with a custom errorMessage function.

```APIDOC
## new RegularExpression(name, regex, options?)

### Description
Creates a new GraphQL scalar type that enforces a value matching the provided regular expression. The returned type can be used in a GraphQL schema and resolver map.

### Constructor
`new RegularExpression(name, regex, options?)`

### Parameters
- **name** (string) - Required - The name of the new scalar type.
- **regex** (RegExp) - Required - The regular expression that values must match.
- **options** (object) - Optional - An object with an `errorMessage` function to customize validation error messages.

#### options.errorMessage(regex, value)
- **regex** (RegExp) - The regular expression used for validation.
- **value** (any) - The value that failed validation.
- Returns a string message to use as the error.

### Usage Example
```ts
const MyRegexType = new RegularExpression('MyRegexType', /^ABC$/)
```

### With Options Example
```ts
const options = {
  errorMessage(regex, value) {
    return process.env.NODE_ENV === 'production'
      ? `Value is invalid format: ${value}`
      : `Value does not match the regular expression ${regex}: ${value}`
  }
}

const MyRegexType = new RegularExpression('MyRegexType', /^ABC$/, options)
```

### Adding to Resolver Map
```ts
export default {
  MyRegexType
  // ...
}
```

### Adding to Schema
```graphql
scalar MyRegexType
```

```

--------------------------------

### Create a GraphQLScalarType with serialize, parseValue, and parseLiteral

Source: https://the-guild.dev/graphql/scalars/docs/usage/regex

Defines a custom scalar by implementing the required GraphQLScalarType methods: serialize, parseValue, and parseLiteral.

```ts
const MyScalar = new GraphQLScalarType({
  name: 'MyScalar',
  description: 'A description of my scalar',
  serialize(value) {
    // ...
    return value
  },
  parseValue(value) {
    // ...
    return value
  },
  parseLiteral(ast) {
    // ...
    return ast.value
  }
})
```

--------------------------------

### Coerce JavaScript Date to ISO 8601 string

Source: https://the-guild.dev/graphql/scalars/docs/scalars/date-time-iso

Shows how a JavaScript Date instance is coerced to an ISO 8601 string. The output is '2023-02-03T01:00:00.000Z'. Invalid Date instances raise a field error.

```javascript
const date = new Date('2023-02-03T01:00:00Z')
// Outputs: "2023-02-03T01:00:00.000Z"
```

--------------------------------

### Provide custom errorMessage option to RegularExpression

Source: https://the-guild.dev/graphql/scalars/docs/usage/regex

Passes an optional third options argument to customize the error message. The message differs based on the NODE_ENV environment variable.

```ts
const options = {
  errorMessage(regex, value) {
    return process.env.NODE_ENV === 'production'
      ? `Value is invalid format: ${value}`
      : `Value does not match the regular expression ${regex}: ${value}`
  }
}

const MyRegexType = new RegularExpression('MyRegexType', /^ABC$/, options)
```

--------------------------------

### Add scalar definition to SDL type definitions (schema.graphql)

Source: https://the-guild.dev/graphql/scalars/docs/quick-start

Adds a scalar definition to your SDL type definitions. Place this in your schema.graphql file.

```graphql
scalar ScalarName
```

--------------------------------

### new RegularExpression(name, regex)

Source: https://the-guild.dev/graphql/scalars/docs/scalars/regular-expression

Creates a new GraphQL scalar type that validates values against the given regular expression. The name is used as the type name in the GraphQL schema.

```APIDOC
## new RegularExpression(name, regex)

### Description
Creates a new GraphQL scalar type that validates values against the given regular expression. The name is used as the type name in the GraphQL schema.

### Parameters
- **name** (string) - Required - The name of the custom scalar type.
- **regex** (RegExp) - Required - The regular expression used to validate values.

### Example
```ts
const MyRegexType = new RegularExpression('MyRegexType', /^ABC$/)
```
```

--------------------------------

### Create a RegularExpression scalar type

Source: https://the-guild.dev/graphql/scalars/docs/scalars/regular-expression

Creates a new GraphQL scalar type named 'MyRegexType' that validates values against the regular expression /^ABC$/. Use this to enforce a specific pattern for fields of this type.

```TypeScript
const MyRegexType = new RegularExpression('MyRegexType', /^ABC$/)
```

--------------------------------

### Declare RegularExpression scalar in schema

Source: https://the-guild.dev/graphql/scalars/docs/usage/regex

Declares the custom scalar in the GraphQL schema so it can be used as a type.

```graphql
scalar MyRegexType
```

--------------------------------

### Register RegularExpression scalar in resolver map

Source: https://the-guild.dev/graphql/scalars/docs/usage/regex

Adds the generated scalar type to the resolver map so it can be used in GraphQL operations.

```ts
export default {
  MyRegexType
  // ...
}
```
Tokens:
Raw