or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

colors.mddata-formats.mddate-time.mdfinancial.mdgeographic.mdidentifiers.mdindex.mdnetwork.mdnumeric.mdspecialized.mdstring-text.mdutilities.md
tile.json

index.mddocs/

GraphQL Scalars

GraphQL Scalars is a comprehensive collection of custom GraphQL scalar types that provide precise type-safe validation for GraphQL schemas. It includes over 69 scalar types covering dates, numbers, strings, networking, geographic data, colors, financial data, identifiers, and many other specialized data formats.

Package Information

  • Package Name: graphql-scalars
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install graphql-scalars
  • Peer Dependencies: graphql ^0.8.0 || ^0.9.0 || ^0.10.0 || ^0.11.0 || ^0.12.0 || ^0.13.0 || ^14.0.0 || ^15.0.0 || ^16.0.0

Core Imports

Individual Scalar Import:

import { GraphQLEmailAddress, GraphQLURL, GraphQLDate } from "graphql-scalars";

Resolver Collection Import:

import { resolvers } from "graphql-scalars";

Type Definitions Import:

import { typeDefs } from "graphql-scalars";

Mock Data Import:

import { EmailAddressMock, URLMock, DateMock } from "graphql-scalars";

For CommonJS:

const { GraphQLEmailAddress, resolvers, typeDefs } = require("graphql-scalars");

Basic Usage

import { GraphQLObjectType, GraphQLSchema, buildSchema } from "graphql";
import { GraphQLEmailAddress, GraphQLURL, resolvers, typeDefs } from "graphql-scalars";

// Method 1: Individual scalars in schema building
const UserType = new GraphQLObjectType({
  name: "User",
  fields: {
    email: { type: GraphQLEmailAddress },
    website: { type: GraphQLURL },
  },
});

// Method 2: Using resolver collection
const schema = buildSchema(`
  type User {
    email: EmailAddress
    website: URL
  }
  
  ${typeDefs.join('\n')}
`);

// Apply resolvers
Object.assign(schema.getTypeMap(), resolvers);

// Method 3: Using individual type definitions
const schemaSDL = `
  scalar EmailAddress
  scalar URL
  
  type User {
    email: EmailAddress
    website: URL
  }
`;

Architecture

GraphQL Scalars is built around several key components:

  • Scalar Resolvers: GraphQLScalarType instances that handle validation, serialization, and parsing
  • Type Definitions: String constants for GraphQL schema definitions
  • Mock Data Generators: Functions that generate valid test data for each scalar type
  • Validation Engine: Robust validation with descriptive error messages and spec compliance
  • RegularExpression Utility: Base class for creating custom regex-based scalar validators

Each scalar type implements the complete GraphQL scalar interface with three core methods:

  • serialize: Convert internal value to transport format
  • parseValue: Parse value from variables
  • parseLiteral: Parse value from AST literals

Capabilities

Date and Time Scalars

Date, time, and timestamp validation with ISO 8601 compliance and timezone support. Includes local time variants and duration types.

// Core date/time scalars
const GraphQLDate: GraphQLScalarType;          // ISO 8601 date (YYYY-MM-DD)
const GraphQLTime: GraphQLScalarType;          // ISO 8601 time (HH:MM:SS[.sss])
const GraphQLDateTime: GraphQLScalarType;      // ISO 8601 date-time
const GraphQLDateTimeISO: GraphQLScalarType;   // Strict ISO 8601 with timezone
const GraphQLTimestamp: GraphQLScalarType;     // Unix timestamp
const GraphQLTimeZone: GraphQLScalarType;      // IANA timezone identifiers
const GraphQLUtcOffset: GraphQLScalarType;     // UTC offset (+/-HH:MM)
const GraphQLDuration: GraphQLScalarType;      // Duration strings
const GraphQLISO8601Duration: GraphQLScalarType; // ISO 8601 duration format

Date and Time Scalars

Numeric Scalars

Numeric validation including constrained integers, floating point numbers, and specialized numeric types like BigInt.

// Integer scalars
const GraphQLPositiveInt: GraphQLScalarType;    // Positive integers (> 0)
const GraphQLNegativeInt: GraphQLScalarType;    // Negative integers (< 0)
const GraphQLNonNegativeInt: GraphQLScalarType; // Non-negative integers (>= 0)
const GraphQLNonPositiveInt: GraphQLScalarType; // Non-positive integers (<= 0)
const GraphQLUnsignedInt: GraphQLScalarType;    // Unsigned integers
const GraphQLSafeInt: GraphQLScalarType;        // Safe JavaScript integer range
const GraphQLByte: GraphQLScalarType;           // 8-bit unsigned integer (0-255)

// Floating point scalars
const GraphQLPositiveFloat: GraphQLScalarType;    // Positive floats (> 0)
const GraphQLNegativeFloat: GraphQLScalarType;    // Negative floats (< 0)
const GraphQLNonNegativeFloat: GraphQLScalarType; // Non-negative floats (>= 0)
const GraphQLNonPositiveFloat: GraphQLScalarType; // Non-positive floats (<= 0)
const GraphQLUnsignedFloat: GraphQLScalarType;    // Unsigned floats

// Specialized numeric types
const GraphQLBigInt: GraphQLScalarType;  // JavaScript BigInt values
const GraphQLLong: GraphQLScalarType;    // 64-bit signed integer

Numeric Scalars

String and Text Scalars

String validation for common text formats including emails, URLs, and text with constraints.

const GraphQLEmailAddress: GraphQLScalarType; // Valid email format
const GraphQLURL: GraphQLScalarType;         // Valid URL format  
const GraphQLNonEmptyString: GraphQLScalarType; // String with at least one character
const GraphQLPhoneNumber: GraphQLScalarType; // Phone number validation

String and Text Scalars

Identifier Scalars

Unique identifier validation including UUIDs, ObjectIDs, JWTs, and other ID formats.

const GraphQLUUID: GraphQLScalarType;     // UUID format validation
const GraphQLGUID: GraphQLScalarType;     // GUID format (alias for UUID)
const GraphQLObjectID: GraphQLScalarType; // MongoDB ObjectID format
const GraphQLCuid: GraphQLScalarType;     // Collision-resistant unique identifier
const GraphQLJWT: GraphQLScalarType;      // JSON Web Token format
const GraphQLDID: GraphQLScalarType;      // Decentralized Identifier format

Identifier Scalars

Network and Address Scalars

Network-related validation including IP addresses, MAC addresses, and port numbers.

const GraphQLIP: GraphQLScalarType;   // IP address (v4 or v6)
const GraphQLIPv4: GraphQLScalarType; // IPv4 address format
const GraphQLIPv6: GraphQLScalarType; // IPv6 address format
const GraphQLMAC: GraphQLScalarType;  // MAC address format
const GraphQLPort: GraphQLScalarType; // Network port number (1-65535)

Network and Address Scalars

Geographic and Postal Scalars

Geographic coordinate validation and postal address components.

const GraphQLCountryCode: GraphQLScalarType; // ISO 3166-1 country codes
const GraphQLCountryName: GraphQLScalarType; // Country name validation
const GraphQLPostalCode: GraphQLScalarType;  // Postal/ZIP code validation  
const GraphQLLatitude: GraphQLScalarType;    // Geographic latitude (-90 to 90)
const GraphQLLongitude: GraphQLScalarType;   // Geographic longitude (-180 to 180)
const GraphQLLocale: GraphQLScalarType;      // IETF BCP 47 locale identifiers

Geographic and Postal Scalars

Color Scalars

Color format validation for various color representation systems.

const GraphQLRGB: GraphQLScalarType;           // RGB color format
const GraphQLRGBA: GraphQLScalarType;          // RGBA color format with alpha
const GraphQLHSL: GraphQLScalarType;           // HSL color format
const GraphQLHSLA: GraphQLScalarType;          // HSLA color format with alpha
const GraphQLHexColorCode: GraphQLScalarType;  // Hexadecimal color code (#RRGGBB)
const GraphQLHexadecimal: GraphQLScalarType;   // Hexadecimal string format

Color Scalars

Financial Scalars

Financial data validation including currencies, bank account numbers, and routing information.

const GraphQLCurrency: GraphQLScalarType;        // ISO 4217 currency codes
const GraphQLUSCurrency: GraphQLScalarType;      // US currency validation
const GraphQLIBAN: GraphQLScalarType;            // International Bank Account Number
const GraphQLRoutingNumber: GraphQLScalarType;   // US bank routing number
const GraphQLAccountNumber: GraphQLScalarType;   // Bank account number

Financial Scalars

Data Format Scalars

JSON and structured data format validation.

const GraphQLJSON: GraphQLScalarType;       // JSON data validation
const GraphQLJSONObject: GraphQLScalarType; // JSON object validation
const GraphQLGeoJSON: GraphQLScalarType;    // GeoJSON format validation

Data Format Scalars

Specialized Scalars

Specialized validation for books, classifications, versions, and other domain-specific formats.

// Library and classification
const GraphQLISBN: GraphQLScalarType;            // International Standard Book Number
const GraphQLDeweyDecimal: GraphQLScalarType;    // Dewey Decimal Classification
const GraphQLLCCSubclass: GraphQLScalarType;     // Library of Congress Classification
const GraphQLIPCPatent: GraphQLScalarType;       // International Patent Classification

// Version and identification
const GraphQLSemVer: GraphQLScalarType;   // Semantic version format
const GraphQLSESSN: GraphQLScalarType;    // Swedish Social Security Number
const GraphQLVoid: GraphQLScalarType;     // Void/null type

Specialized Scalars

Utility Classes

Custom scalar creation utilities for advanced use cases.

class RegularExpression extends GraphQLScalarType {
  constructor(name: string, regex: RegExp, options?: RegularExpressionOptions);
}

interface RegularExpressionOptions {
  errorMessage?: RegularExpressionErrorMessageFn;
  description?: string;
  stringOnly?: boolean;
}

type RegularExpressionErrorMessageFn = (r: RegExp, v: any) => string;

Utility Classes

Global Exports

Resolver Collection

const resolvers: Record<string, GraphQLScalarType>;

Object mapping scalar names to their resolver instances for easy schema integration.

Type Definitions

const typeDefs: string[];

Array of GraphQL scalar type definition strings for schema building.

Mock Data

const mocks: Record<string, () => any>;

Collection of mock data generators for testing, with each scalar providing a corresponding mock function.