Skip to content
A set of RFC 3339 compliant date/time GraphQL scalar types.
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
examples Improvement to the inline docs. Jan 29, 2017
flow-typed/npm
resources Lint the code (#77) Feb 3, 2018
src Upgrade to graphql-14 (#101) Sep 16, 2018
.babelrc
.flowconfig
.gitignore Publish scripts for deployment to npm via travis. (#14) Jan 29, 2017
.travis.yml Add new token Sep 16, 2018
CONTRIBUTING.md
LICENSE
README.md Replaced launchpad for codesandbox Jan 28, 2019
package.json 3.6.1 Sep 16, 2018
rfc3339.txt
yarn.lock

README.md

GraphQL ISO Date

npm version Build Status codecov

GraphQL ISO Date is a set of RFC 3339 compliant date/time scalar types to be used with graphQL.js.

RFC 3339 "defines a date and time format for use in Internet protocols that is a profile of the ISO 8601 standard for representation of dates and times using the Gregorian calendar."

Date and Time on the Internet: Timestamps, July 2002.

A basic understanding of GraphQL and of the graphQL.js implementation is needed to provide context for this library.

This library contains the following scalars:

  • Date: A date string, such as 2007-12-03.
  • Time: A time string at UTC, such as 10:15:30Z
  • DateTime: A date-time string at UTC, such as 2007-12-03T10:15:30Z.

Getting started

Install graphql-iso-date using yarn

yarn add graphql-iso-date

Or using npm

npm install --save graphql-iso-date

GraphQL ISO Date exposes 3 different date/time scalars that can be used in combination with graphQL.js. Let's build a simple schema using the scalars included in this library and execute a query:

import {
  graphql,
  GraphQLObjectType,
  GraphQLSchema,
} from 'graphql';

import {
  GraphQLDate,
  GraphQLTime,
  GraphQLDateTime
} from 'graphql-iso-date';

const schema = new GraphQLSchema({
  query: new GraphQLObjectType({
    name: 'Query',
    fields: {
      birthdate: {
        type: GraphQLDate,
        //resolver can take a Date or date string.
        resolve: () => new Date(1991, 11, 24)
      },
      openingNYSE: {
        type: GraphQLTime,
        //resolver can take a Date or time string.
        resolve: () => new Date(Date.UTC(2017, 0, 10, 14, 30))
      },
      instant: {
        type: GraphQLDateTime,
        // resolver can take Date, date-time string or Unix timestamp (number).
        resolve: () => new Date(Date.UTC(2017, 0, 10, 21, 33, 15, 233))
      }
    }
  })
});

const query = `
  {
    birthdate
    openingNYSE
    instant
  }
`;

graphql(schema, query).then(result => {

    // Prints
    // {
    //   data: {
    //     birthdate: '1991-12-24',
    //     openingNYSE: '14:30:00.000Z',
    //     instant: '2017-01-10T21:33:15.233Z'
    //   }
    // }
    console.log(result);
});

Examples

This project includes several examples in the folder /examples explaining how to use the various scalars. You can also see some live editable examples on Launchpad:

Run the examples by downloading this project and running the following commands:

Install dependencies using yarn

yarn

Or npm

npm install

Run the examples

npm run examples

Scalars

This section provides a detailed description of each of the scalars.

A reference is made to coercion in the description below. For further clarification on the meaning of this term, please refer to the GraphQL spec.

Date

A date string, such as 2007-12-03, compliant with the full-date format outlined in section 5.6 of the RFC 3339 profile of the ISO 8601 standard for representation of dates and times using the Gregorian calendar.

This scalar is a description of the date, as used for birthdays for example. It cannot represent an instant on the time-line.

Result Coercion

Javascript Date instances are coerced to an RFC 3339 compliant date string. Invalid Date instances raise a field error.

Input Coercion

When expected as an input type, only RFC 3339 compliant date strings are accepted. All other input values raise a query error indicating an incorrect type.

Time

A time string at UTC, such as 10:15:30Z, compliant with the full-time format outlined in section 5.6 of the RFC 3339 profile of the ISO 8601 standard for representation of dates and times using the Gregorian calendar.

This scalar is a description of a time instant such as the opening bell of the New York Stock Exchange for example. It cannot represent an exact instant on the time-line.

This scalar ignores leap seconds (thereby assuming that a minute constitutes of 59 seconds), in this respect it diverges from the RFC 3339 profile.

Where an RFC 3339 compliant time string has a time-zone other than UTC, it is shifted to UTC. For example, the time string "14:10:20+01:00" is shifted to "13:10:20Z".

Result Coercion

Javascript Date instances are coerced to an RFC 3339 compliant time string by extracting the UTC time part. Invalid Date instances raise a field error.

Input Coercion

When expected as an input type, only RFC 3339 compliant time strings are accepted. All other input values raise a query error indicating an incorrect type.

DateTime

A date-time string at UTC, such as 2007-12-03T10:15:30Z, compliant with the date-time format outlined in section 5.6 of the RFC 3339 profile of the ISO 8601 standard for representation of dates and times using the Gregorian calendar.

This scalar is a description of an exact instant on the time-line such as the instant that a user account was created.

This scalar ignores leap seconds (thereby assuming that a minute constitutes of 59 seconds). In this respect it diverges from the RFC 3339 profile.

Where an RFC 3339 compliant date-time string has a time-zone other than UTC, it is shifted to UTC. For example, the date-time string "2016-01-01T14:10:20+01:00" is shifted to "2016-01-01T13:10:20Z".

Result Coercion

JavaScript Date instances and Unix timestamps (represented as 32-bit signed integers) are coerced to RFC 3339 compliant date-time strings. Invalid Date instances raise a field error.

Input Coercion

When expected as an input type, only RFC 3339 compliant date-time strings are accepted. All other input values raise a query error indicating an incorrect type.

You can’t perform that action at this time.