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

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.