{"id":16487613,"url":"https://github.com/saeris/graphql-scalars","last_synced_at":"2025-08-01T22:33:08.360Z","repository":{"id":40813311,"uuid":"146964153","full_name":"Saeris/graphql-scalars","owner":"Saeris","description":"📐 A library of custom GraphQL scalar types for creating precise type-safe GraphQL schemas, with validation powered by Yup.","archived":false,"fork":false,"pushed_at":"2023-01-06T01:49:35.000Z","size":3091,"stargazers_count":68,"open_issues_count":24,"forks_count":4,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-12-01T01:35:24.730Z","etag":null,"topics":["apollo-server","graphql","graphql-scalars"],"latest_commit_sha":null,"homepage":"https://codesandbox.io/s/github/Saeris/graphql-scalars/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Saeris.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-09-01T03:30:36.000Z","updated_at":"2024-06-04T00:13:40.000Z","dependencies_parsed_at":"2023-02-05T02:00:13.792Z","dependency_job_id":null,"html_url":"https://github.com/Saeris/graphql-scalars","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Saeris%2Fgraphql-scalars","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Saeris%2Fgraphql-scalars/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Saeris%2Fgraphql-scalars/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Saeris%2Fgraphql-scalars/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Saeris","download_url":"https://codeload.github.com/Saeris/graphql-scalars/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228413945,"owners_count":17915919,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apollo-server","graphql","graphql-scalars"],"created_at":"2024-10-11T13:35:25.548Z","updated_at":"2024-12-06T05:01:21.611Z","avatar_url":"https://github.com/Saeris.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\" style=\"display: block; text-align: center;\"\u003e📐 GraphQL Scalars\u003c/h1\u003e\n\u003cp align=\"center\"\u003e\u003ca href=\"https://www.npmjs.org/package/@saeris/graphql-scalars\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/@saeris/graphql-scalars.svg?style=flat\" alt=\"npm\"\u003e\u003c/a\u003e\u003ca href=\"https://travis-ci.com/Saeris/graphql-scalars\"\u003e\u003cimg src=\"https://travis-ci.com/Saeris/graphql-scalars.svg?branch=master\" alt=\"travis\"\u003e\u003c/a\u003e\u003ca href=\"https://codecov.io/gh/Saeris/graphql-scalars\"\u003e\u003cimg src=\"https://codecov.io/gh/Saeris/graphql-scalars/branch/master/graph/badge.svg\" alt=\"codecov\"/\u003e\u003c/a\u003e\u003c/p\u003e\n\u003cp align=\"center\"\u003eA library of custom \u003ca href=\"http://graphql.org/learn/schema/#scalar-types\"\u003eGraphQL scalar types\u003c/a\u003e for creating precise type-safe GraphQL schemas, with validation powered by \u003ca href=\"https://github.com/jquense/yup\"\u003eYup\u003c/a\u003e.\u003c/p\u003e\n\n---\n\n## 📦 Installation\n\n```bash\nnpm install --save graphql @saeris/graphql-scalars\n# or\nyarn add graphql @saeris/graphql-scalars\n```\n\n## 🔧 Usage\n\nTo use these scalars you'll need to add them in two places, your schema and your resolvers map. Here is an example of how to use them with [Apollo Server](https://github.com/apollographql/apollo-server):\n\n```js\nimport { ApolloServer } from \"apollo-server\"\nimport { makeExecutableSchema } from \"graphql-tools\"\nimport CustomScalars, { RegularExpressionFactory } from \"@saeris/graphql-scalars\"\n// Alternatively, import individual scalars and resolvers:\n// import { DateTimeScalar, DateTime } from \"@saeris/graphql-scalars\"\n\nconst { scalar: MyRegexScalar, resolver: MyRegex } = RegularExpressionFactory(`MyRegex`, /^abc$/)\n\nconst server = new ApolloServer({\n  schema: makeExecutableSchema({\n    typeDefs: [\n      ...CustomScalars.keys(),\n      // DateTimeScalar,\n      MyRegexScalar\n    ],\n    resolvers: {\n      ...CustomScalars.values(),\n      // DateTime,\n      MyRegex\n    }\n  })\n})\n\nserver.listen().then(({ url }) =\u003e {\n  console.log(`🚀 Server ready at ${url}`)\n})\n```\n\nNow you can use them in your schema just like you would any other Type/Scalar:\n\n```graphql\ntype Person {\n  birthDate: DateTime\n  ageInYears: PositiveInt\n\n  heightInInches: PositiveFloat\n\n  minimumHourlyRate: UnsignedFloat\n\n  currentlyActiveProjects: UnsignedInt\n\n  email: EmailAddress\n  homePage: URL\n\n  phoneNumber: PhoneNumber\n  homePostalCode: PostalCode\n}\n```\n\n## 🏖️ Example\n\nYou can quickly take this library for a spin by running the example either locally under the `example` directory (just run `yarn \u0026\u0026 yarn start` and open your browser to http://localhost:4000) or live inside of CodeSandbox [here](https://codesandbox.io/s/github/Saeris/graphql-scalars/).\n\n## 📐 Scalars\n\n### DateTime\n\n```js\nimport { DateTimeScalar, DateTime } from \"@saeris/graphql-scalars\"\n```\n\nUse real JavaScript Dates for GraphQL fields. Currently you can use a String or an Int (e.g., a\ntimestamp in milliseconds) to represent a date/time. This scalar makes it easy to be explicit about\nthe type and have a real JavaScript Date returned that the client can use _without_ doing the\ninevitable parsing or conversion themselves.\n\n### EmailAddress\n\n```js\nimport { EmailAddressScalar, EmailAddress } from \"@saeris/graphql-scalars\"\n```\n\nA field whose value conforms to the standard internet email address format as specified in\n[RFC822](https://www.w3.org/Protocols/rfc822/).\n\n### GUID\n```js\nimport { GUIDScalar, GUID } from \"@saeris/graphql-scalars\"\n```\n\nA field whose value is a generic [Globally Unique Identifier](https://en.wikipedia.org/wiki/Universally_unique_identifier).\n\n### Hexadecimal\n```js\nimport { HexadecimalScalar, Hexadecimal } from \"@saeris/graphql-scalars\"\n```\n\nA field whose value is a [hexadecimal](https://en.wikipedia.org/wiki/Hexadecimal).\n\n### HexColorCode\n```js\nimport { HexColorCodeScalar, HexColorCode } from \"@saeris/graphql-scalars\"\n```\n\nA field whose value is a [hex color code](https://en.wikipedia.org/wiki/Web_colors).\n\n### HSL\n```js\nimport { HSLScalar, HSL } from \"@saeris/graphql-scalars\"\n```\n\nA field whose value is a [CSS HSL color](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#hsl()_and_hsla()).\n\n### HSLA\n```js\nimport { HSLAScalar, HSLA } from \"@saeris/graphql-scalars\"\n```\n\nA field whose value is a [CSS HSLA color](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#hsl()_and_hsla()).\n\n### IPv4\n```js\nimport { IPv4Scalar, IPv4 } from \"@saeris/graphql-scalars\"\n```\n\nA field whose value is a [IPv4 address](https://en.wikipedia.org/wiki/IPv4).\n\n### IPv6\n```js\nimport { IPv6Scalar, IPv6 } from \"@saeris/graphql-scalars\"\n```\n\nA field whose value is a [IPv6 address](https://en.wikipedia.org/wiki/IPv6).\n\n### ISBN\n```js\nimport { ISBNScalar, ISBN } from \"@saeris/graphql-scalars\"\n```\n\nA field whose value is a [ISBN-10 or ISBN-13 number](https://en.wikipedia.org/wiki/International_Standard_Book_Number).\n\n### MAC\n```js\nimport { MACScalar, MAC } from \"@saeris/graphql-scalars\"\n```\n\nA field whose value is a IEEE 802 48-bit [MAC address](https://en.wikipedia.org/wiki/MAC_address).\n\n### NegativeFloat\n\n```js\nimport { NegativeFloatScalar, NegativeFloat } from \"@saeris/graphql-scalars\"\n```\n\nFloats that will have a value less than 0. Uses [`parseFloat()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/parseFloat).\n\n### NegativeInt\n\n```js\nimport { NegativeIntScalar, NegativeInt } from \"@saeris/graphql-scalars\"\n```\n\nIntegers that will have a value less than 0. Uses [`parseInt()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/parseInt).\n\n### NonPositiveFloat\n\n```js\nimport { NonPositiveFloatScalar, NonPositiveFloat } from \"@saeris/graphql-scalars\"\n```\n\nFloats that will have a value of 0 or less. Uses [`parseFloat()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/parseFloat).\n\n### NonPositiveInt\n\n```js\nimport { NonPositiveIntScalar, NonPositiveInt } from \"@saeris/graphql-scalars\"\n```\n\nIntegers that will have a value of 0 or less. Uses [`parseInt()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/parseInt).\n\n### PhoneNumber\n\n```js\nimport { PhoneNumberScalar, PhoneNumber } from \"@saeris/graphql-scalars\"\n```\n\nA field whose value conforms to the standard E.164 format as specified in\n[E.164 specification](https://en.wikipedia.org/wiki/E.164). Basically this is `+17895551234`.\nThe very powerful\n[`libphonenumber` library](https://github.com/googlei18n/libphonenumber) is available to take\n_that_ format, parse and display it in whatever display format you want. It can also be used to\nparse user input and _get_ the E.164 format to pass _into_ a schema.\n\n### Port\n\n```js\nimport { PortScalar, Port } from \"@saeris/graphql-scalars\"\n```\n\nA field whose value is a valid [TCP port](https://en.wikipedia.org/wiki/Transmission_Control_Protocol#TCP_ports) within the range of 0 to 65535.\n\n### PositiveFloat\n\n```js\nimport { PositiveFloatScalar, PositiveFloat } from \"@saeris/graphql-scalars\"\n```\n\nFloats that will have a value greater than 0. Uses [`parseFloat()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/parseFloat).\n\n### PositiveInt\n\n```js\nimport { PositiveIntScalar, PositiveInt } from \"@saeris/graphql-scalars\"\n```\n\nIntegers that will have a value greater than 0. Uses [`parseInt()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/parseInt).\n\n### PostalCode\n\n```js\nimport { PostalCodeScalar, PostalCode } from \"@saeris/graphql-scalars\"\n```\n\nA field whose value conforms to the standard Portal Code format of any of the following countries:\n\n* US - United States\n* GB - United Kingdom\n* DE - Germany\n* CA - Canada\n* FR - France\n* IT - Italy\n* AU - Australia\n* NL - Netherlands\n* ES - Spain\n* DK - Denmark\n* SE - Sweden\n* BE - Belgium\n* IN - India\n\nUses [`joi-postalcode`](https://github.com/abythell/joi-postalcode) for validation, which uses [`postal-codes-js`](https://github.com/Cimpress-MCP/postal-codes-js) under the hood.\n\n### RGB\n```js\nimport { RGBScalar, RGB } from \"@saeris/graphql-scalars\"\n```\n\nA field whose value is a [CSS RGB color](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#rgb()_and_rgba()).\n\n### RGBA\n```js\nimport { RGBAScalar, RGBA } from \"@saeris/graphql-scalars\"\n```\n\nA field whose value is a [CSS RGBA color](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#rgb()_and_rgba()).\n\n### UnsignedFloat\n\n```js\nimport { UnsignedFloatScalar, UnsignedFloat } from \"@saeris/graphql-scalars\"\n```\n\nFloats that will have a value of 0 or more. Uses [`parseFloat()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/parseFloat).\n\n### UnsignedInt\n\n```js\nimport { UnsignedIntScalar, UnsignedInt } from \"@saeris/graphql-scalars\"\n```\n\nIntegers that will have a value of 0 or more. Uses [`parseInt()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/parseInt).\n\n### URL\n\n```js\nimport { URLScalar, URL } from \"@saeris/graphql-scalars\"\n```\n\nA field whose value conforms to the standard URL format as specified in\n[RFC3986](https://www.ietf.org/rfc/rfc3986.txt).\n\n## 🏭 Factories\n\n### rangeFactory\n\n```js\nimport { rangeFactory } from \"@saeris/graphql-scalars\"\n```\n\nA `GraphQLScalarType` factory that takes the following config:\n\n* `name` - The name of your custom scalar\n* `start` - Minimum value this scalar will accept\n* `end` - Maximum value this scalar will accept\n* `float` - Set to `true` to accept Floats, `false` to accept Integers (Optional, default: `false`)\n\nThe following will create a scalar that accepts any Float between 1 and 1000 as a valid value\n```js\nconst { scalar: RangeScalar, resolver: Range } = new RegularExpressionFactory({\n  name: 'Range',\n  start: 1,\n  end: 1000,\n  float: true\n});\n```\n\n### regularExpressionFactory\n\n```js\nimport { regularExpressionFactory } from \"@saeris/graphql-scalars\"\n```\n\nA `GraphQLScalarType` factory that takes the following config:\n\n* `name` - The name of your custom scalar\n* `regex` - The regex to be used to check against any values for fields with this new type\n\nThe following will create a scalar that accepts only Strings that match `ABC` as a valid value\n```js\nconst { scalar: RegexScalar, resolver: Regex } = new RegularExpressionFactory({\n  name: 'Regex',\n  regex: /^ABC$/\n});\n```\n\n## 📣 Acknowledgements\n\nThis library was forked from [@okgrow/graphql-scalars](https://github.com/okgrow/graphql-scalars) and uses [Yup](https://github.com/jquense/yup) for validation.\n\n## 🥂 License\n\nReleased under the [MIT license](https://github.com/Saeris/graphql-scalars/blob/master/LICENSE.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsaeris%2Fgraphql-scalars","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsaeris%2Fgraphql-scalars","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsaeris%2Fgraphql-scalars/lists"}