CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-graphql-scalars

A collection of scalar types not included in base GraphQL.

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

geographic.mddocs/

Geographic and Postal Scalars

Geographic coordinate validation and postal address components. These scalars provide validation for location-based data commonly used in mapping, shipping, and localization applications.

Capabilities

CountryCode Scalar

Validates ISO 3166-1 country codes.

/**
 * GraphQL scalar for ISO 3166-1 country code validation
 * Accepts 2-letter (alpha-2) and 3-letter (alpha-3) country codes
 */
const GraphQLCountryCode: GraphQLScalarType;

Example Values:

  • "US" (United States)
  • "GB" (United Kingdom)
  • "DE" (Germany)
  • "JP" (Japan)
  • "AU" (Australia)
  • "USA" (3-letter format)
  • "GBR" (3-letter format)

CountryName Scalar

Validates country names.

/**
 * GraphQL scalar for country name validation
 * Accepts standard country names
 */
const GraphQLCountryName: GraphQLScalarType;

Example Values:

  • "United States"
  • "United Kingdom"
  • "Germany"
  • "Japan"
  • "Australia"

PostalCode Scalar

Validates postal/ZIP code formats for various countries.

/**
 * GraphQL scalar for postal code validation
 * Accepts various international postal code formats
 */
const GraphQLPostalCode: GraphQLScalarType;

Example Values:

  • "12345" (US ZIP)
  • "12345-6789" (US ZIP+4)
  • "M1A 1A1" (Canada)
  • "SW1A 1AA" (UK)
  • "10115" (Germany)

Latitude Scalar

Validates geographic latitude coordinates (-90 to 90 degrees).

/**
 * GraphQL scalar for geographic latitude validation
 * Accepts decimal degrees from -90 to 90
 */
const GraphQLLatitude: GraphQLScalarType;

Example Values:

  • 40.7128 (New York City)
  • 51.5074 (London)
  • -33.8688 (Sydney)
  • 0 (Equator)
  • 90 (North Pole)
  • -90 (South Pole)

Longitude Scalar

Validates geographic longitude coordinates (-180 to 180 degrees).

/**
 * GraphQL scalar for geographic longitude validation
 * Accepts decimal degrees from -180 to 180
 */
const GraphQLLongitude: GraphQLScalarType;

Example Values:

  • -74.0060 (New York City)
  • -0.1278 (London)
  • 151.2093 (Sydney)
  • 0 (Prime Meridian)
  • 180 (International Date Line)
  • -180 (International Date Line)

Locale Scalar

Validates IETF BCP 47 locale identifiers.

/**
 * GraphQL scalar for locale identifier validation
 * Accepts IETF BCP 47 language tags
 */
const GraphQLLocale: GraphQLScalarType;

Example Values:

  • "en" (English)
  • "en-US" (English, United States)
  • "en-GB" (English, United Kingdom)
  • "fr-FR" (French, France)
  • "de-DE" (German, Germany)
  • "ja-JP" (Japanese, Japan)
  • "zh-CN" (Chinese, China)

Usage Examples

import { 
  GraphQLCountryCode,
  GraphQLPostalCode,
  GraphQLLatitude,
  GraphQLLongitude,
  GraphQLLocale
} from "graphql-scalars";

// In a GraphQL schema
const AddressType = new GraphQLObjectType({
  name: "Address",
  fields: {
    countryCode: { type: GraphQLCountryCode },
    postalCode: { type: GraphQLPostalCode },
    latitude: { type: GraphQLLatitude },
    longitude: { type: GraphQLLongitude },
  },
});

const UserType = new GraphQLObjectType({
  name: "User",
  fields: {
    locale: { type: GraphQLLocale },
    address: { type: AddressType },
  },
});

// Using with type definitions
const typeDefs = `
  scalar CountryCode
  scalar PostalCode
  scalar Latitude
  scalar Longitude
  scalar Locale
  
  type Address {
    street: String
    city: String
    countryCode: CountryCode
    postalCode: PostalCode
    latitude: Latitude
    longitude: Longitude
  }
  
  type User {
    name: String!
    locale: Locale
    address: Address
  }
`;

GraphQL Operations:

query GetUsersNearLocation($lat: Latitude!, $lng: Longitude!, $radius: Float!) {
  usersNearLocation(latitude: $lat, longitude: $lng, radius: $radius) {
    id
    name
    address {
      countryCode
      postalCode
      latitude
      longitude
    }
  }
}

mutation UpdateUserAddress($userId: ID!, $address: AddressInput!) {
  updateUserAddress(userId: $userId, address: $address) {
    id
    address {
      countryCode
      postalCode
      latitude
      longitude
    }
  }
}

Variables:

{
  "lat": 40.7128,
  "lng": -74.0060,
  "radius": 10.0,
  "userId": "user-123",
  "address": {
    "street": "123 Main St",
    "city": "New York",
    "countryCode": "US",
    "postalCode": "10001",
    "latitude": 40.7509,
    "longitude": -73.9934
  }
}

Validation Behavior

Each geographic scalar performs specific validation:

  • CountryCode: Validates against ISO 3166-1 standard codes
  • CountryName: Validates against standard country names
  • PostalCode: Recognizes various international postal formats
  • Latitude: Ensures value is between -90 and 90 degrees
  • Longitude: Ensures value is between -180 and 180 degrees
  • Locale: Validates IETF BCP 47 language tag format

Coordinate Examples:

// Valid coordinates
const validLocations = [
  { lat: 40.7128, lng: -74.0060 },  // New York City
  { lat: 51.5074, lng: -0.1278 },   // London
  { lat: -33.8688, lng: 151.2093 }, // Sydney
  { lat: 0, lng: 0 },               // Null Island
];

// Invalid coordinates
const invalidLocations = [
  { lat: 91, lng: -74.0060 },       // Latitude > 90
  { lat: 40.7128, lng: 181 },       // Longitude > 180
  { lat: -91, lng: -74.0060 },      // Latitude < -90
  { lat: 40.7128, lng: -181 },      // Longitude < -180
];

Common Use Cases

Country Codes & Names are used for:

  • E-commerce shipping
  • User registration forms
  • Content localization
  • Analytics and reporting

Postal Codes are used for:

  • Shipping calculations
  • Tax calculations
  • Service area validation
  • Demographic analysis

Coordinates are used for:

  • Mapping applications
  • Location-based services
  • Distance calculations
  • Geofencing

Locales are used for:

  • Internationalization (i18n)
  • Content translation
  • Date/number formatting
  • Currency display

Type Definitions

// String constants for schema building
const CountryCode: string;  // "scalar CountryCode"
const CountryName: string;  // "scalar CountryName"
const PostalCode: string;   // "scalar PostalCode"
const Latitude: string;     // "scalar Latitude"
const Longitude: string;    // "scalar Longitude"
const Locale: string;       // "scalar Locale"

Mock Data

// Mock data generators for testing
const CountryCodeMock: () => string;
const CountryNameMock: () => string;
const PostalCodeMock: () => string;
const LatitudeMock: () => number;
const LongitudeMock: () => number;
const LocaleMock: () => string;

Coordinate Precision

Latitude and longitude scalars accept decimal degrees with high precision:

  • 1 decimal place: ~11 km accuracy
  • 2 decimal places: ~1.1 km accuracy
  • 3 decimal places: ~110 m accuracy
  • 4 decimal places: ~11 m accuracy
  • 5 decimal places: ~1.1 m accuracy
  • 6 decimal places: ~0.11 m accuracy

Choose appropriate precision based on your application's requirements.

docs

colors.md

data-formats.md

date-time.md

financial.md

geographic.md

identifiers.md

index.md

network.md

numeric.md

specialized.md

string-text.md

utilities.md

tile.json