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

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Data Format Scalars

Name: tessl/npm-graphql-scalars
Author: tessl

JSON and structured data format validation. These scalars provide validation for common data interchange formats used in APIs, configuration files, and data storage.

Capabilities

JSON Scalar

Validates JSON data of any type.

/**
 * GraphQL scalar for JSON data validation
 * Accepts any valid JSON value (object, array, string, number, boolean, null)
 */
const GraphQLJSON: GraphQLScalarType;

Example Values:

{"name": "John", "age": 30} (Object)
[1, 2, 3, "hello"] (Array)
"simple string" (String)
42 (Number)
true (Boolean)
null (Null)

JSONObject Scalar

Validates JSON objects specifically (not arrays, strings, etc.).

/**
 * GraphQL scalar for JSON object validation
 * Accepts only JSON objects (key-value pairs), not arrays or primitives
 */
const GraphQLJSONObject: GraphQLScalarType;

Example Values:

{"name": "John", "age": 30}
{"settings": {"theme": "dark", "notifications": true}}
{"items": [1, 2, 3], "total": 3}
{} (Empty object)

GeoJSON Scalar

Validates GeoJSON format for geographic data.

/**
 * GraphQL scalar for GeoJSON validation
 * Accepts GeoJSON geometry objects, features, and feature collections
 */
const GraphQLGeoJSON: GraphQLScalarType;

Example Values:

Point:

{
  "type": "Point",
  "coordinates": [-73.9857, 40.7484]
}

LineString:

{
  "type": "LineString",
  "coordinates": [
    [-73.9857, 40.7484],
    [-73.9857, 40.7584]
  ]
}

Polygon:

{
  "type": "Polygon",
  "coordinates": [[
    [-73.9857, 40.7484],
    [-73.9557, 40.7484],
    [-73.9557, 40.7784],
    [-73.9857, 40.7784],
    [-73.9857, 40.7484]
  ]]
}

Feature:

{
  "type": "Feature",
  "geometry": {
    "type": "Point",
    "coordinates": [-73.9857, 40.7484]
  },
  "properties": {
    "name": "Central Park"
  }
}

Usage Examples

import { 
  GraphQLJSON,
  GraphQLJSONObject,
  GraphQLGeoJSON
} from "graphql-scalars";

// In a GraphQL schema
const UserType = new GraphQLObjectType({
  name: "User",
  fields: {
    preferences: { type: GraphQLJSONObject },
    metadata: { type: GraphQLJSON },
    location: { type: GraphQLGeoJSON },
  },
});

const ConfigType = new GraphQLObjectType({
  name: "Config",
  fields: {
    settings: { type: GraphQLJSONObject },
    data: { type: GraphQLJSON },
  },
});

// Using with type definitions
const typeDefs = `
  scalar JSON
  scalar JSONObject
  scalar GeoJSON
  
  type User {
    id: ID!
    name: String!
    preferences: JSONObject
    metadata: JSON
    location: GeoJSON
  }
  
  type Location {
    name: String!
    coordinates: GeoJSON!
    properties: JSONObject
  }
  
  type Config {
    key: String!
    settings: JSONObject
    data: JSON
  }
`;

GraphQL Operations:

query GetUserWithPreferences($userId: ID!) {
  user(id: $userId) {
    id
    name
    preferences
    metadata
    location
  }
}

mutation UpdateUserPreferences($userId: ID!, $preferences: JSONObject!) {
  updateUserPreferences(userId: $userId, preferences: $preferences) {
    id
    preferences
  }
}

mutation SaveLocation($locationData: LocationInput!) {
  saveLocation(data: $locationData) {
    id
    name
    coordinates
    properties
  }
}

Variables:

{
  "userId": "user-123",
  "preferences": {
    "theme": "dark",
    "notifications": {
      "email": true,
      "push": false
    },
    "language": "en-US"
  },
  "locationData": {
    "name": "Central Park",
    "coordinates": {
      "type": "Point", 
      "coordinates": [-73.9857, 40.7484]
    },
    "properties": {
      "city": "New York",
      "country": "USA"
    }
  }
}

Validation Behavior

Each data format scalar performs specific validation:

JSON: Validates any JSON-parseable data, maintains original type
JSONObject: Validates only JSON objects, rejects arrays and primitives
GeoJSON: Validates against GeoJSON specification including geometry types and structure

Validation Examples:

// Valid JSON data
const validJSON = {
  jsonValue: {"key": "value"},     // Valid JSON object
  jsonArray: [1, 2, "three"],     // Valid JSON array
  jsonString: "hello",             // Valid JSON string
  jsonNumber: 42,                  // Valid JSON number
  jsonBoolean: true,               // Valid JSON boolean
  jsonNull: null                   // Valid JSON null
};

// Valid JSONObject data
const validJSONObject = {
  userSettings: {
    theme: "dark",
    notifications: true,
    preferences: {
      language: "en",
      timezone: "UTC"
    }
  }
};

// Invalid JSONObject data (valid JSON but not objects)
const invalidJSONObject = {
  arrayValue: [1, 2, 3],           // Valid JSON but not object
  stringValue: "not an object",    // Valid JSON but not object
  numberValue: 42                  // Valid JSON but not object
};

// Valid GeoJSON data
const validGeoJSON = {
  point: {
    type: "Point",
    coordinates: [-73.9857, 40.7484]
  },
  feature: {
    type: "Feature",
    geometry: {
      type: "Point",
      coordinates: [-73.9857, 40.7484]
    },
    properties: {
      name: "Location"
    }
  }
};

GeoJSON Types Support

The GeoJSON scalar supports all standard GeoJSON types:

Geometry Objects:

Point - Single coordinate
LineString - Array of coordinates forming a line
Polygon - Array of coordinate arrays forming a polygon
MultiPoint - Array of Point coordinates
MultiLineString - Array of LineString coordinates
MultiPolygon - Array of Polygon coordinates
GeometryCollection - Collection of geometry objects

Feature Objects:

Feature - Geometry with properties
FeatureCollection - Array of features

Common Use Cases

JSON Scalars are commonly used for:

Configuration Data: Application settings and preferences
Metadata Storage: Flexible key-value data
API Responses: Dynamic content that doesn't fit strict schemas
User Customization: Personalization data
Legacy Data: Migration of unstructured data

GeoJSON is commonly used for:

Mapping Applications: Geographic data representation
Location Services: Points of interest, routes, boundaries
GIS Systems: Geographic information system integration
Delivery Services: Service areas and routes
Real Estate: Property boundaries and locations

Performance Considerations

JSON/JSONObject: Large JSON objects can impact query performance
GeoJSON: Complex polygons with many coordinates can be memory-intensive
Indexing: Consider database indexing for frequently queried JSON fields
Validation: Client-side pre-validation can reduce server load

Type Definitions

// String constants for schema building
const JSON: string;        // "scalar JSON"
const JSONObject: string;  // "scalar JSONObject"  
const GeoJSON: string;     // "scalar GeoJSON"

Mock Data

// Mock data generators for testing
const JSONMock: () => any;
const JSONObjectMock: () => object;
const GeoJSONMock: () => object;

Error Handling

Data format scalars provide specific error messages:

// JSON validation errors
"Value is not valid JSON: invalid-json-string"

// JSONObject validation errors
"Value must be a JSON object, not array or primitive"

// GeoJSON validation errors
"Value is not valid GeoJSON: missing required 'type' property"
"Invalid GeoJSON geometry type: InvalidType"
"Invalid coordinates format for Point geometry"

Security Considerations

When using JSON scalars:

Input Validation: Always validate JSON content beyond just format
Size Limits: Implement reasonable limits on JSON object size
Nested Depth: Consider limiting nesting depth to prevent stack overflow
Content Filtering: Sanitize JSON content for security-sensitive applications