🧭 GraphQL Directives

A library of custom GraphQL directives to give your schema super powers!

---

🚧 Under Construction

Warning: This library is still under construction! A pre-release version is available, but it is recommended not to use this in production! Use at your own risk!

Table of Contents

• Installation
• Usage
• Example
• Directives
• Currencies
  • \@formatCurrency
• Dates
  • \@formatdate
• Numbers
  • \@formatNumber
• Phone Numbers
  • \@formatPhoneNumber
• Strings
  • \@camelCase
  • \@capitalize
  • \@deburr
  • \@kebabCase
  • \@lowerCase
  • \@lowerFirst
  • \@snakeCase
  • \@toLower
  • \@toUpper
  • \@trim
  • \@upperCase
  • \@upperFirst
• Measurements
  • \@converLength
  • \@convertSurfaceArea
  • \@convertVolume
  • \@convertLiquidVolume
  • \@convertAngle
  • \@convertTime
  • \@convertMass
  • \@convertTemperature
  • \@convertForce
  • \@convertEnergy
  • \@convertPower
  • \@convertPressure
  • \@convertBinary
• Acknowledgements
• License

📦 Installation

npm install --save graphql graphql-tag @saeris/graphql-directives
# or
yarn add graphql graphql-tag @saeris/graphql-directives

🔧 Usage

To use these directives add them to your Schema Directives when you initialize your Apollo Server:

import { ApolloServer } from "apollo-server"
// Import all directives at once
import Directives from "@saeris/graphql-directives"
// Optionally, you can import individual directives or namespaced groups
// import { formatDate, Strings } from "@saeris/graphql-directives"
import { typeDefs } from "./types"
import { resolvers } from "./resolvers"

const server = new ApolloServer({
  typeDefs: [
    ...typeDefs,
    // Map over each directive and get it's type declaration to add them to your schema
    //
    // Apollo prefers not to mix and match types for graphql type definitions, so typeDefs
    // should be either string[] or DocumentNode[]. We expose two helper methods to get the
    // correct type declaration.
    //
    // - use directive#toString() when your types are plain strings
    // - use directive#toDocumentNode() when your types are defined using graphql-tag
    ...Object.values(Directives).map((directive) => directive.toDocumentNode())
    // Follow the same pattern to get type declarations for groups
    // ...Object.values(Strings).map(directive = directive.toDocumentNode())
    // Or for individual directives, just call the getter directly
    // formatDate.toDocumentNode()
  ],
  resolvers,
  // Add the directives to your schemaDirectives map
  schemaDirectives: {
    ...Directives
    // Do the same for namespaced groups
    // ...Strings
    // For individual directives just use object property shorthand
    // formatDate
    // Don't rename directives! The following will throw an error:
    // customName: formatDate
  }
})

/* eslint-disable */
server.listen(endpoint).then(({ url }) => {
  console.log(`🚀 Server ready at ${url}`)
})

Now you can use them in your schema just like you would any other Directive:

type Person {
  # ...
  birthDate: String @formatDate(defaultFormat: "MMMM D, YYYY")
  # ...
}

🏖️ Example

You can quickly take this library for a spin by running the example either locally under the example directory (just run yarn && yarn dev and open your browser to http://localhost:9000) or live inside of CodeSandbox here.

🧭 Directives

Below is a list of each available directive and it's individual usage. GraphQL schema examples include all of the available arguments for the directive and their default values. Query examples include all of the arguments the directive adds to the field on which it was applied in the schema, along with any default values for those arguments. Many of the directives included in this library will change the return type of the field they are applied to, most commonly that will be a String. The return type for each directive is noted in it's description. Additionally, example inputs and outputs are provided for each.

💵 Currencies

\@formatCurrency

Allows clients to apply custom formatting to currency values. Uses dinero.js under the hood.

import { formatCurrency } from "@saeris/graphql-directives"

Example Schema Usage:

type Example {
  # Int | Float => String
  hourlyRate: Int @formatCurrency(
    defaultFormat = "$0,0.00" # String!
    defaultRoundingMode = HALF_AWAY_FROM_ZERO # RoundingMode!
  )
}

# Included Automatically when using @formatCurrncy
enum RoundingMode {
  HALF_ODD
  HALF_EVEN
  HALF_UP
  HALF_DOWN
  HALF_TOWARD_ZERO
  HALF_AWAY_FROM_ZERO
}

Example Query Usage:

query ExampleQuery {
  getPerson {
    # Raw => Default Format => Requested Format
    # 1150 => $11.50 => EUR 11.5
    hourlyRate(format: "USD0,0.0", currency: "EUR") # => EUR 11.5
  }
}

Additional Formatting Options:

Taken from dinero.js documentation

Format	Result Example
$0,0.00	\$5,000.50
$0,0	\$5,001
$0	\$5001
$0.0	\$5000.5
USD0,0.0	USD 5,000.5
0,0.0 dollar	5,000.5 dollars

Note: $, USD, and dollar are all symbols. They will automatically be localized to fit the currency you specify. For example currency: EUR will transform $ => €, USD => EUR, and dollars => euros. The formats listed above are not tokens, but instead are pre-defined by dinero.js. Custom formatting is not currently available.

📆 Dates

\@formatDate

Allows clients to apply custom formatting to date values. Uses date-fns under the hood.

import { formatDate } from "@saeris/graphql-directives"

Example Schema Usage:

type Example {
  # Int | String => String
  date: String @formatDate(
    defaultFormat = "MMMM D, YYYY" # String!
  )
}

Example Query Usage:

query ExampleQuery {
  getPerson {
    # Raw => Default Format => Requested Format
    # 1549766240251 => February 9, 2019 => 18:37:20pm - February 9, 2019
    birthDate(format: "H:mm:ssa - MMMM D, YYYY") # => 18:37:20pm - February 9, 2019
  }
}

Additional Formatting Options:

Table taken from date-fns documentation

Unit	Token	Result Examples
Month	M	1, 2, ..., 12
	Mo	1st, 2nd, ..., 12th
	MM	01, 02, ..., 12
	MMM	Jan, Feb, ..., Dec
	MMMM	January, February, ..., December
Quarter	Q	1, 2, 3, 4
	Qo	1st, 2nd, 3rd, 4th
Day of month	D	1, 2, ..., 31
	Do	1st, 2nd, ..., 31st
	DD	01, 02, ..., 31
Day of year	DDD	1, 2, ..., 366
	DDDo	1st, 2nd, ..., 366th
	DDDD	001, 002, ..., 366
Day of week	d	0, 1, ..., 6
	do	0th, 1st, ..., 6th
	dd	Su, Mo, ..., Sa
	ddd	Sun, Mon, ..., Sat
	dddd	Sunday, Monday, ..., Saturday
Day of ISO week	E	1, 2, ..., 7
ISO week	W	1, 2, ..., 53
	Wo	1st, 2nd, ..., 53rd
	WW	01, 02, ..., 53
Year	YY	00, 01, ..., 99
	YYYY	1900, 1901, ..., 2099
ISO week-numbering year	GG	00, 01, ..., 99
	GGGG	1900, 1901, ..., 2099
AM/PM	A	AM, PM
	a	am, pm
	aa	a.m., p.m.
Hour	H	0, 1, ... 23
	HH	00, 01, ... 23
	h	1, 2, ..., 12
	hh	01, 02, ..., 12
Minute	m	0, 1, ..., 59
	mm	00, 01, ..., 59
Second	s	0, 1, ..., 59
	ss	00, 01, ..., 59
1/10 of second	S	0, 1, ..., 9
1/100 of second	SS	00, 01, ..., 99
Millisecond	SSS	000, 001, ..., 999
Timezone	Z	-01:00, +00:00, ... +12:00
	ZZ	-0100, +0000, ..., +1200
Seconds timestamp	X	512969520
Milliseconds timestamp	x	512969520900

🧮 Numbers

\@formatNumber

Allows clients to apply custom formatting to numerical values. Uses numeral under the hood.

import { formatNumber } from "@saeris/graphql-directives"

Example Schema Usage:

type Example {
  # Int | Float => String
  balance: Float @formatNumber(
    defaultFormat = "0,0.0000" # String!
  )
}

Example Query Usage:

query ExampleQuery {
  getPerson {
    # Raw => Default Format => Requested Format
    # 11075.25 => 11,075.2500 => 11.1k
    balance(format: "0.0a") # => 11.1k
  }
}

Additional Formatting Options:

Tables taken from numeral documentation

Numbers | Number | Format | String | |-------------|--------------|---------------| | 10000 | 0,0.0000 | 10,000.0000 | | 10000.23 | 0,0 | 10,000 | | 10000.23 | +0,0 | +10,000 | | -10000 | 0,0.0 | -10,000.0 | | 10000.1234 | 0.000 | 10000.123 | | 100.1234 | 00000 | 00100 | | 1000.1234 | 000000,0 | 001,000 | | 10 | 000.00 | 010.00 | | 10000.1234 | 0[.]00000 | 10000.12340 | | -10000 | (0,0.0000) | (10,000.0000) | | -0.23 | .00 | -.23 | | -0.23 | (.00) | (.23) | | 0.23 | 0.00000 | 0.23000 | | 0.23 | 0.0[0000] | 0.23 | | 1230974 | 0.0a | 1.2m | | 1460 | 0 a | 1 k | | -104000 | 0a | -104k | | 1 | 0o | 1st | | 100 | 0o | 100th |

Currency | Number | Format | String | |-----------|--------------|-------------| | 1000.234 | $0,0.00 | \$1,000.23 | | 1000.2 | 0,0[.]00 $ | 1,000.20 \$ | | 1001 | $ 0,0[.]00 | \$ 1,001 | | -1000.234 | ($0,0) | (\$1,000) | | -1000.234 | $0.00 | -\$1000.23 | | 1230974 | ($ 0.00 a) | \$ 1.23 m |

Bytes | Number | Format | String | |---------------|------------|------------| | 100 | 0b | 100B | | 1024 | 0b | 1KB | | 2048 | 0 ib | 2 KiB | | 3072 | 0.0 b | 3.1 KB | | 7884486213 | 0.00b | 7.88GB | | 3467479682787 | 0.000 ib | 3.154 TiB |

Percentages | Number | Format | String | |---------------|--------------|-----------| | 1 | 0% | 100% | | 0.974878234 | 0.000% | 97.488% | | -0.43 | 0 % | -43 % | | 0.43 | (0.000 %) | 43.000 % |

Time | Number | Format | String | |---------|------------|----------| | 25 | 00:00:00 | 0:00:25 | | 238 | 00:00:00 | 0:03:58 | | 63846 | 00:00:00 | 17:44:06 |

Exponential | Number | Format | String | |---------------|-------------|----------| | 1123456789 | 0,0e+0 | 1e+9 | | 12398734.202 | 0.00e+0 | 1.24e+7 | | 0.000123987 | 0.000e+0 | 1.240e-