@saeris/graphql-directives v0.5.0

🚧 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
  }
}

Taken from dinero.js documentation

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
  }
}

Table taken from date-fns documentation

🧮 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
  }
}

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-4 |

📞 Phone Numbers

\@formatPhoneNumber

Allows clients to apply various standard formatting to phone numbers. Uses libphonenumber-js under the hood.

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

Example Schema Usage:

type Example {
  # String => String
  phoneNumber: String @formatPhoneNumber(
    defaultFormat = International # PhoneFormats!
  )
}

# Included Automatically when using @formatPhoneNumber
enum PhoneFormats {
  National
  International
  E164
  RFC3966
}

Example Query Usage:

query ExampleQuery {
  getPerson {
    # Raw => Default Format => Requested Format
    # +17895551234 => +1 789 555 1234 => (789) 555-1234
    phoneNumber(format: National) # => (789) 555-1234
  }
}

Table taken from libphonenumber-js documentation

📝 Strings

String Formatting

The following directives all apply various basic string formats and are designed such that they can be combined with other directives to transform strings without adding extra arguments to a field. They all use lodash under the hood. Descriptions and examples are taken from the lodash documentation.

\@camelCase

Converts string to camel case.

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

Example Schema Usage:

type Example {
  # String => String
  message: String @camelCase
}

Example Query Usage:

query ExampleQuery {
  getMessage {
    # Raw => Formatted String
    # Foo Bar => fooBar
    # --foo-bar-- => fooBar
    # __FOO_BAR__ => fooBar
    message # => fooBar
  }
}

\@capitalize

Converts the first character of string to upper case and the remaining to lower case.

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

Example Schema Usage:

type Example {
  # String => String
  message: String @capitalize
}

Example Query Usage:

query ExampleQuery {
  getMessage {
    # Raw => Formatted String
    # FRED => Fred
    message # => Fred
  }
}

\@deburr

Deburrs string by converting Latin-1 Supplement and Latin Extended-A letters to basic Latin letters and removing combining diacritical marks.

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

Example Schema Usage:

type Example {
  # String => String
  message: String @deburr
}

Example Query Usage:

query ExampleQuery {
  getMessage {
    # Raw => Formatted String
    # déjà vu => deja vu
    message # => deja vu
  }
}

\@kebabCase

Converts string to kebab case.

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

Example Schema Usage:

type Example {
  # String => String
  message: String @kebabCase
}

Example Query Usage:

query ExampleQuery {
  getMessage {
    # Raw => Formatted String
    # Foo Bar => foo-bar
    # fooBar => foo-bar
    # __FOO_BAR__ => foo-bar
    message # => foo-bar
  }
}

\@lowerCase

Converts string, as space separated words, to lower case.

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

Example Schema Usage:

type Example {
  # String => String
  message: String @lowerCase
}

Example Query Usage:

query ExampleQuery {
  getMessage {
    # Raw => Formatted String
    # --Foo-Bar-- => foo bar
    # fooBar => foo bar
    # __FOO_BAR__ => foo bar
    message # => foo bar
  }
}

\@lowerFirst

Converts the first character of string to lower case.

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

Example Schema Usage:

type Example {
  # String => String
  message: String @lowerFirst
}

Example Query Usage:

query ExampleQuery {
  getMessage {
    # Raw => Formatted String
    # Fred => fred
    # FRED => fRED
    message # => fRED
  }
}

\@snakeCase

Converts string to snake case.

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

Example Schema Usage:

type Example {
  # String => String
  message: String @snakeCase
}

Example Query Usage:

query ExampleQuery {
  getMessage {
    # Raw => Formatted String
    # Foo Bar => foo_bar
    # fooBar => foo_bar
    # --FOO-BAR-- => foo_bar
    message # => foo_bar
  }
}

\@toLower

Converts string, as a whole, to lower case.

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

Example Schema Usage:

type Example {
  # String => String
  message: String @toLower
}

Example Query Usage:

query ExampleQuery {
  getMessage {
    # Raw => Formatted String
    # --Foo-Bar-- => --foo-bar--
    # fooBar => foobar
    # __FOO_BAR__ => __foo_bar__
    message # => foobar
  }
}

\@toUpper

Converts string, as a whole, to upper case.

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

Example Schema Usage:

type Example {
  # String => String
  message: String @toUpper
}

Example Query Usage:

query ExampleQuery {
  getMessage {
    # Raw => Formatted String
    # --foo-bar-- => --FOO-BAR--
    # fooBar => FOOBAR
    # __foo_bar__ => __FOO_BAR__
    message # => FOOBAR
  }
}

\@trim

Removes leading and trailing whitespace from string.

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

Example Schema Usage:

type Example {
  # String => String
  message: String @trim
}

Example Query Usage:

query ExampleQuery {
  getMessage {
    # Raw => Formatted String
    # '  abc  ' => 'abc'
    message # => abc
  }
}

\@upperCase

Converts string, as space separated words, to upper case.

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

Example Schema Usage:

type Example {
  # String => String
  message: String @upperCase
}

Example Query Usage:

query ExampleQuery {
  getMessage {
    # Raw => Formatted String
    # --foo-bar-- => FOO BAR
    # fooBar => FOO BAR
    # __foo_bar__ => FOO BAR
    message # => FOO BAR
  }
}

\@upperFirst

Converts the first character of string to upper case.

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

Example Schema Usage:

type Example {
  # String => String
  message: String @upperFirst
}

Example Query Usage:

query ExampleQuery {
  getMessage {
    # Raw => Formatted String
    # fred => Fred
    # fRED => FRED
    message # => Fred
  }
}

📐 Measurements

Measurement Conversions

The following directives all convert a category of measurement from one unit to another, for example feet to meters, gallons to fluid ounces, etc. They all use mathjs under the hood.

Each conversion directive includes a GraphQL Enum with all of the valid values that directive can process. Included are singular, plural, and abbreviated forms of each unit, with SI prefixes where applicable.

Tables taken from mathjs documentation

Note: Frequency, Electric Current, Amount of Substance, and Luminous Intensity are not currently included as they have only a single unit of measurement inside of mathjs.

Prefixes The following decimal prefixes are available.

The following binary prefixes are available. They can be used with units bit (b) and byte (B).

\@convertLength

Converts length measurements from one unit to another.

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

Example Schema Usage:

type Example {
  # Int | Float => String
  height: Float @convertLength(
    # Note: There is no pre-configured default, you must specify
    # the originalUnit in your schema!
    originalUnit = inches # LengthTypesEnum!
    # When true, only the value will be returned
    defaultRaw = false # Boolean!
  )
}

Example Query Usage:

query ExampleQuery {
  getPerson {
    # Raw => Original Unit => Requested Unit
    # 70.5 => 70.5 inches => 5.875 feet
    height(convertTo: feet) # => 5.875 feet
  }
}

\@convertSurfaceArea

Converts surface area measurements from one unit to another.

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

Example Schema Usage:

type Example {
  # Int | Float => String
  roomDimensions: Float @convertSurfaceArea(
    # Note: There is no pre-configured default, you must specify
    # the originalUnit in your schema!
    originalUnit = sqft # SurfaceAreaTypesEnum!
    # When true, only the value will be returned
    defaultRaw = false # Boolean!
  )
}

Example Query Usage:

query ExampleQuery {
  getPerson {
    # Raw => Original Unit => Requested Unit
    # 25.75 => 25.75 sqft => 2.3922532800000003 m2
    roomDimensions(convertTo: m2) # => 2.3922532800000003 m2
  }
}

\@convertVolume

Converts volume measurements from one unit to another.

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

Example Schema Usage:

type Example {
  # Int | Float => String
  bagSize: Float @convertVolume(
    # Note: There is no pre-configured default, you must specify
    # the originalUnit in your schema!
    originalUnit = cuin # VolumeTypesEnum!
    # When true, only the value will be returned
    defaultRaw = false # Boolean!
  )
}

Example Query Usage:

query ExampleQuery {
  getPerson {
    # Raw => Original Unit => Requested Unit
    # 2772 => 2772 cuin => 45.424941407999995 litre
    bagSize(convertTo: litre) # => 45.424941407999995 litre
  }
}

\@convertLiquidVolume

Converts liquid volume measurements from one unit to another.

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

Example Schema Usage:

type Example {
  # Int | Float => String
  coffeeConsumed: Float @convertLiquidVolume(
    # Note: There is no pre-configured default, you must specify
    # the originalUnit in your schema!
    originalUnit = fluidounce # LiquidVolumeTypesEnum!
    # When true, only the value will be returned
    defaultRaw = false # Boolean!
  )
}

Example Query Usage:

query ExampleQuery {
  getPerson {
    # Raw => Original Unit => Requested Unit
    # 21.125 => 21.125 fluidounce => 2.6406254464508376 cup
    coffeeConsumed(convertTo: cup) # => 2.6406254464508376 cup
  }
}

\@convertAngle

Converts angle measurements from one unit to another.

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

Example Schema Usage:

type Example {
  # Int | Float => String
  trajectory: Float @convertAngle(
    # Note: There is no pre-configured default, you must specify
    # the originalUnit in your schema!
    originalUnit = deg # AngleTypesEnum!
    # When true, only the value will be returned
    defaultRaw = false # Boolean!
  )
}

Example Query Usage:

query ExampleQuery {
  getPerson {
    # Raw => Original Unit => Requested Unit
    # 21.125 => 21.125 fluidounce => 2.6406254464508376 cup
    trajectory(convertTo: rad) # => 2.6406254464508376 cup
  }
}

\@convertTime

Converts time measurements from one unit to another.

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

Example Schema Usage:

type Example {
  # Int | Float => String
  age: Int @convertTime(
    # Note: There is no pre-configured default, you must specify
    # the originalUnit in your schema!
    originalUnit = years # TimeTypesEnum!
    # When true, only the value will be returned
    defaultRaw = false # Boolean!
  )
}

Example Query Usage:

query ExampleQuery {
  getPerson {
    # Raw => Original Unit => Requested Unit
    # 21 => 21 years => 7670.25 days
    age(convertTo: days) # => 7670.25 days
  }
}

\@convertMass

Converts mass/weight measurements from one unit to another.

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

Example Schema Usage:

type Example {
  # Int | Float => String
  weight: Int @convertTime(
    # Note: There is no pre-configured default, you must specify
    # the originalUnit in your schema!
    originalUnit = poundmass # TimeTypesEnum!
    # When true, only the value will be returned
    defaultRaw = false # Boolean!
  )
}

Example Query Usage:

query ExampleQuery {
  getPerson {
    # Raw => Original Unit => Requested Unit
    # 21 => 21 years => 7670.25 days
    weight(convertTo: gram) # => 7670.25 days
  }
}

\@convertTemperature

Converts temperature measurements from one unit to another.

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

Example Schema Usage:

type Example {
  # Int | Float => String
  temperature: Float @convertTemperature(
    # Note: There is no pre-configured default, you must specify
    # the originalUnit in your schema!
    originalUnit = degF # TemperatureTypesEnum!
    # When true, only the value will be returned
    defaultRaw = false # Boolean!
  )
}

Example Query Usage:

query ExampleQuery {
  getPerson {
    # Raw => Original Unit => Requested Unit
    # 21 => 21 years => 7670.25 days
    temperature(convertTo: degC) # => 7670.25 days
  }
}

\@convertForce

Converts force measurements from one unit to another.

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

Example Schema Usage:

type Example {
  # Int | Float => String
  temperature: Float @convertForce(
    # Note: There is no pre-configured default, you must specify
    # the originalUnit in your schema!
    originalUnit = degF # ForceTypesEnum!
    # When true, only the value will be returned
    defaultRaw = false # Boolean!
  )
}

Example Query Usage:

query ExampleQuery {
  getPerson {
    # Raw => Original Unit => Requested Unit
    # 21 => 21 years => 7670.25 days
    temperature(convertTo: degC) # => 7670.25 days
  }
}

\@convertEnergy

Converts energy measurements from one unit to another.

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

Example Schema Usage:

type Example {
  # Int | Float => String
  temperature: Float @convertEnergy(
    # Note: There is no pre-configured default, you must specify
    # the originalUnit in your schema!
    originalUnit = degF # EnergyTypesEnum!
    # When true, only the value will be returned
    defaultRaw = false # Boolean!
  )
}

Example Query Usage:

query ExampleQuery {
  getPerson {
    # Raw => Original Unit => Requested Unit
    # 21 => 21 years => 7670.25 days
    temperature(convertTo: degC) # => 7670.25 days
  }
}

\@convertPower

Converts power measurements from one unit to another.

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

Example Schema Usage:

type Example {
  # Int | Float => String
  temperature: Float @convertPower(
    # Note: There is no pre-configured default, you must specify
    # the originalUnit in your schema!
    originalUnit = degF # PowerTypesEnum!
    # When true, only the value will be returned
    defaultRaw = false # Boolean!
  )
}

Example Query Usage:

query ExampleQuery {
  getPerson {
    # Raw => Original Unit => Requested Unit
    # 21 => 21 years => 7670.25 days
    temperature(convertTo: degC) # => 7670.25 days
  }
}

\@convertPressure

Converts pressure measurements from one unit to another.

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

Example Schema Usage:

type Example {
  # Int | Float => String
  temperature: Float @convertPressure(
    # Note: There is no pre-configured default, you must specify
    # the originalUnit in your schema!
    originalUnit = degF # PressureTypesEnum!
    # When true, only the value will be returned
    defaultRaw = false # Boolean!
  )
}

Example Query Usage:

query ExampleQuery {
  getPerson {
    # Raw => Original Unit => Requested Unit
    # 21 => 21 years => 7670.25 days
    temperature(convertTo: degC) # => 7670.25 days
  }
}

\@convertBinary

Converts binary measurements from one unit to another.

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

Example Schema Usage:

type Example {
  # Int => String
  diskSpace: Int @convertBinary(
    # Note: There is no pre-configured default, you must specify
    # the originalUnit in your schema!
    originalUnit = bytes # BinaryTypesEnum!
    # When true, only the value will be returned
    defaultRaw = false # Boolean!
  )
}

Example Query Usage:

query ExampleQuery {
  getPerson {
    # Raw => Original Unit => Requested Unit
    # 1024 => 1024 bytes => 78192 bits
    diskSpace(convertTo: bits) # => 8192 bits
  }
}

📣 Acknowledgements

This library was inspired by @lirown/graphql-custom-directives. It is an Apollo Server implementation based on their Schema Directives documentation.

🥂 License

Released under the MIT license.