🧭 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!

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

Additional Formatting Options:

Table taken from libphonenumber-js documentation

Format	Example
`National`	(213) 373-4253
`International`	+1 213 373 4253
`E164`	+12133734253
`RFC3966`	tel:+12133734253;ext=123

📝 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.

Comprehensive list of supported units:

Tables taken from mathjs documentation

Base	Unit
Length	meter (m), inch (in), foot (ft), yard (yd), mile (mi), link (li), rod (rd), chain (ch), angstrom, mil
Surface area	m2, sqin, sqft, sqyd, sqmi, sqrd, sqch, sqmil, acre, hectare
Volume	m3, litre (l, L, lt, liter), cc, cuin, cuft, cuyd, teaspoon, tablespoon
Liquid volume	minim (min), fluiddram (fldr), fluidounce (floz), gill (gi), cup (cp), pint (pt), quart (qt), gallon (gal), beerbarrel (bbl), oilbarrel (obl), hogshead, drop (gtt)
Angles	rad (radian), deg (degree), grad (gradian), cycle, arcsec (arcsecond), arcmin (arcminute)
Time	second (s, secs, seconds), minute (mins, minutes), hour (h, hr, hrs, hours), day (days), week (weeks), month (months), year (years), decade (decades), century (centuries), millennium (millennia)
Mass	gram(g), tonne, ton, grain (gr), dram (dr), ounce (oz), poundmass (lbm, lb, lbs), hundredweight (cwt), stick, stone
Temperature	kelvin (K), celsius (degC), fahrenheit (degF), rankine (degR)
Force	newton (N), dyne (dyn), poundforce (lbf), kip
Energy	joule (J), erg, Wh, BTU, electronvolt (eV)
Power	watt (W), hp
Pressure	Pa, psi, atm, torr, bar, mmHg, mmH2O, cmH2O
Binary	bit (b), byte (B)

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.

Name	Abbreviation	Value
deca	da	1e1
hecto	h	1e2
kilo	k	1e3
mega	M	1e6
giga	G	1e9
tera	T	1e12
peta	P	1e15
exa	E	1e18
zetta	Z	1e21
yotta	Y	1e24

Name	Abbreviation	Value
deci	d	1e-1
centi	c	1e-2
milli	m	1e-3
micro	u	1e-6
nano	n	1e-9
pico	p	1e-12
femto	f	1e-15
atto	a	1e-18
zepto	z	1e-21
yocto	y	1e-24

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

Name	Abbreviation	Value
kibi	Ki	1024
mebi	Mi	1024^2
gibi	Gi	1024^3
tebi	Ti	1024^4
pebi	Pi	1024^5
exi	Ei	1024^6
zebi	Zi	1024^7
yobi	Yi	1024^8

Name	Abbreviation	Value
kilo	k	1e3
mega	M	1e6
giga	G	1e9
tera	T	1e12
peta	P	1e15
exa	E	1e18
zetta	Z	1e21
yotta	Y	1e24

@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.

Files

README.md

Latest commit

History

README.md

File metadata and controls

🧭 GraphQL Directives

🚧 Under Construction

Table of Contents

📦 Installation

🔧 Usage

🏖️ Example

🧭 Directives

💵 Currencies

@formatCurrency

📆 Dates

@formatDate

🧮 Numbers

@formatNumber

📞 Phone Numbers

@formatPhoneNumber

📝 Strings

String Formatting

@camelCase

@capitalize

@deburr

@kebabCase

@lowerCase

@lowerFirst

@snakeCase

@toLower

@toUpper

@trim

@upperCase

@upperFirst

📐 Measurements

Measurement Conversions

@convertLength

@convertSurfaceArea

@convertVolume

@convertLiquidVolume

@convertAngle

@convertTime

@convertMass

@convertTemperature

@convertForce

@convertEnergy

@convertPower

@convertPressure

@convertBinary

📣 Acknowledgements

🥂 License