Add missing documentation for scalar types & feat(scalars): add GeoJSON scalar (#2621)

* Add missing documentation for scalar types

- Added .mdx documentation for scalar types: GUID, HSLA, ISO8601Duration, LCCSubclass, Long, SESSN, UnsignedFloat, and UnsignedInt.
- Resolves issue #2019 regarding missing scalar type documentation.

* feat(scalars): add GeoJSON scalar

- Introduced a custom GeoJSON scalar type.
- Added unit tests to ensure proper validation and functionality of the GeoJSON scalar.
- Updated documentation website to reflect the new scalar type and usage.
- Resolves issue #2061.

Author: ifeanyi-ugwu

bundle-test/package.json

@@ -15,7 +15,7 @@
   "bundlesize": [
     {
       "path": "./dist/index.js",
-      "maxSize": "100 kB",
+      "maxSize": "120 kB",
       "compression": "none"
     }
   ]

src/index.ts

@@ -14,6 +14,7 @@ import {
   GraphQLDID,
   GraphQLDuration,
   GraphQLEmailAddress,
+  GraphQLGeoJSON,
   GraphQLGUID,
   GraphQLHexadecimal,
   GraphQLHexColorCode,
@@ -211,73 +212,74 @@ export {
 };
 
 export const resolvers: Record<string, GraphQLScalarType> = {
+  AccountNumber: GraphQLAccountNumber,
+  BigInt: GraphQLBigInt,
+  Byte: GraphQLByte,
+  CountryCode: GraphQLCountryCode,
+  Cuid: GraphQLCuid,
+  Currency: GraphQLCurrency,
   Date: GraphQLDate,
-  Time: GraphQLTime,
   DateTime: GraphQLDateTime,
   DateTimeISO: GraphQLDateTimeISO,
-  Timestamp: GraphQLTimestamp,
-  TimeZone: GraphQLTimeZone,
-  UtcOffset: GraphQLUtcOffset,
+  DeweyDecimal: GraphQLDeweyDecimal,
+  DID: GraphQLDID,
   Duration: GraphQLDuration,
-  ISO8601Duration: GraphQLISO8601Duration,
-  LocalDate: GraphQLLocalDate,
-  LocalTime: GraphQLLocalTime,
-  LocalDateTime: GraphQLLocalDateTime,
-  LocalEndTime: GraphQLLocalEndTime,
   EmailAddress: GraphQLEmailAddress,
-  NegativeFloat: GraphQLNegativeFloat,
-  NegativeInt: GraphQLNegativeInt,
-  NonEmptyString: GraphQLNonEmptyString,
-  NonNegativeFloat: GraphQLNonNegativeFloat,
-  NonNegativeInt: GraphQLNonNegativeInt,
-  NonPositiveFloat: GraphQLNonPositiveFloat,
-  NonPositiveInt: GraphQLNonPositiveInt,
-  PhoneNumber: GraphQLPhoneNumber,
-  PositiveFloat: GraphQLPositiveFloat,
-  PositiveInt: GraphQLPositiveInt,
-  PostalCode: GraphQLPostalCode,
-  UnsignedFloat: GraphQLUnsignedFloat,
-  UnsignedInt: GraphQLUnsignedInt,
-  URL: GraphQLURL,
-  BigInt: GraphQLBigInt,
-  Byte: GraphQLByte,
-  Long: GraphQLLong,
-  SafeInt: GraphQLSafeInt,
-  UUID: GraphQLUUID,
+  GeoJSON: GraphQLGeoJSON,
   GUID: GraphQLGUID,
   Hexadecimal: GraphQLHexadecimal,
   HexColorCode: GraphQLHexColorCode,
   HSL: GraphQLHSL,
   HSLA: GraphQLHSLA,
+  IBAN: GraphQLIBAN,
   IP: GraphQLIP,
+  IPCPatent: GraphQLIPCPatent,
   IPv4: GraphQLIPv4,
   IPv6: GraphQLIPv6,
   ISBN: GraphQLISBN,
+  ISO8601Duration: GraphQLISO8601Duration,
+  JSON: GraphQLJSON,
+  JSONObject: GraphQLJSONObject,
   JWT: GraphQLJWT,
   Latitude: GraphQLLatitude,
+  LCCSubclass: GraphQLLCCSubclass,
+  LocalDate: GraphQLLocalDate,
+  LocalDateTime: GraphQLLocalDateTime,
+  Locale: GraphQLLocale,
+  LocalEndTime: GraphQLLocalEndTime,
+  LocalTime: GraphQLLocalTime,
+  Long: GraphQLLong,
   Longitude: GraphQLLongitude,
   MAC: GraphQLMAC,
+  NegativeFloat: GraphQLNegativeFloat,
+  NegativeInt: GraphQLNegativeInt,
+  NonEmptyString: GraphQLNonEmptyString,
+  NonNegativeFloat: GraphQLNonNegativeFloat,
+  NonNegativeInt: GraphQLNonNegativeInt,
+  NonPositiveFloat: GraphQLNonPositiveFloat,
+  NonPositiveInt: GraphQLNonPositiveInt,
+  ObjectID: GraphQLObjectID,
+  PhoneNumber: GraphQLPhoneNumber,
   Port: GraphQLPort,
+  PositiveFloat: GraphQLPositiveFloat,
+  PositiveInt: GraphQLPositiveInt,
+  PostalCode: GraphQLPostalCode,
   RGB: GraphQLRGB,
   RGBA: GraphQLRGBA,
-  USCurrency: GraphQLUSCurrency,
-  Currency: GraphQLCurrency,
-  JSON: GraphQLJSON,
-  JSONObject: GraphQLJSONObject,
-  IBAN: GraphQLIBAN,
-  ObjectID: GraphQLObjectID,
-  Void: GraphQLVoid,
-  DID: GraphQLDID,
-  CountryCode: GraphQLCountryCode,
-  Locale: GraphQLLocale,
   RoutingNumber: GraphQLRoutingNumber,
-  AccountNumber: GraphQLAccountNumber,
-  Cuid: GraphQLCuid,
+  SafeInt: GraphQLSafeInt,
   SemVer: GraphQLSemVer,
   SESSN: GraphQLSESSN,
-  DeweyDecimal: GraphQLDeweyDecimal,
-  LCCSubclass: GraphQLLCCSubclass,
-  IPCPatent: GraphQLIPCPatent,
+  Time: GraphQLTime,
+  Timestamp: GraphQLTimestamp,
+  TimeZone: GraphQLTimeZone,
+  UnsignedFloat: GraphQLUnsignedFloat,
+  UnsignedInt: GraphQLUnsignedInt,
+  URL: GraphQLURL,
+  USCurrency: GraphQLUSCurrency,
+  UtcOffset: GraphQLUtcOffset,
+  UUID: GraphQLUUID,
+  Void: GraphQLVoid,
 };
 
 export {
@@ -427,3 +429,8 @@ export {
   GraphQLLCCSubclass,
   GraphQLIPCPatent,
 };
+
+export { GeoJSON as GeoJSONTypeDefinition } from './typeDefs.js';
+export { GraphQLGeoJSON as GeoJSONResolver };
+export { GraphQLGeoJSON };
+export { GeoJSON as GeoJSONMock } from './mocks.js';

src/mocks.ts

@@ -1,3 +1,4 @@
+export const GeoJSON = () => 'Example GeoJSON';
 const BigIntMock = () => BigInt(Number.MAX_SAFE_INTEGER);
 const ByteMock = () => new Uint8Array([1988, 1981, 1965, 1963, 1959, 1955]);
 const DateMock = () => '2007-12-03';

src/scalars/GeoJSON/GeoJSON.ts

@@ -0,0 +1,116 @@
+import { GraphQLScalarType, Kind, ValueNode } from 'graphql';
+import { createGraphQLError } from '../../error.js';
+import { generateGeoJSONType } from './codegenScalarType.js';
+import { geojsonSchema } from './jsonSchema.js';
+import { GeoJSONObject } from './types.js';
+import {
+  isValidBBox,
+  isValidFeature,
+  isValidFeatureCollection,
+  isValidGeometry,
+} from './validators.js';
+
+const validate = (value: any, ast?: ValueNode): GeoJSONObject => {
+  let parsed: unknown;
+
+  if (typeof value === 'string') {
+    try {
+      parsed = JSON.parse(value);
+    } catch {
+      throw createGraphQLError(
+        'Invalid GeoJSON: Failed to parse JSON string',
+        ast ? { nodes: ast } : undefined,
+      );
+    }
+  } else {
+    parsed = value;
+  }
+
+  if (!parsed || typeof parsed !== 'object') {
+    throw createGraphQLError(
+      'Invalid GeoJSON: Must be an object',
+      ast ? { nodes: ast } : undefined,
+    );
+  }
+
+  if (!('type' in parsed)) {
+    throw createGraphQLError(
+      'Invalid GeoJSON: Missing type property',
+      ast ? { nodes: ast } : undefined,
+    );
+  }
+
+  // Validate bbox if present
+  if ('bbox' in parsed && parsed.bbox !== undefined) {
+    if (!isValidBBox(parsed.bbox)) {
+      throw createGraphQLError(
+        'Invalid GeoJSON: Invalid bbox format',
+        ast ? { nodes: ast } : undefined,
+      );
+    }
+  }
+
+  // Validate based on type
+  /*if (parsed.type === 'Feature') {
+    if (!isValidFeature(parsed)) {
+      throw createGraphQLError(
+        'Invalid GeoJSON: Invalid Feature object',
+        ast ? { nodes: ast } : undefined,
+      );
+    }
+  } else if (parsed.type === 'FeatureCollection') {
+    if (!isValidFeatureCollection(parsed)) {
+      throw createGraphQLError(
+        'Invalid GeoJSON: Invalid FeatureCollection object',
+        ast ? { nodes: ast } : undefined,
+      );
+    }
+  } else if (!isValidGeometry(parsed)) {
+    throw createGraphQLError(
+      'Invalid GeoJSON: Invalid Geometry object',
+      ast ? { nodes: ast } : undefined,
+    );
+  }*/
+  if (isValidFeature(parsed)) {
+    return parsed;
+  } else if (isValidFeatureCollection(parsed)) {
+    return parsed;
+  } else if (isValidGeometry(parsed)) {
+    return parsed;
+  }
+
+  // return parsed as GeoJSONObject;
+  throw createGraphQLError(
+    'Invalid GeoJSON: Object does not match any valid GeoJSON type',
+    ast ? { nodes: ast } : undefined,
+  );
+};
+
+export const GraphQLGeoJSON = /*#__PURE__*/ new GraphQLScalarType({
+  name: 'GeoJSON',
+  description:
+    'A GeoJSON object as defined by RFC 7946: https://datatracker.ietf.org/doc/html/rfc7946',
+
+  serialize(value) {
+    return validate(value);
+  },
+
+  parseValue(value) {
+    return validate(value);
+  },
+
+  parseLiteral(ast) {
+    if (ast.kind !== Kind.STRING && ast.kind !== Kind.OBJECT) {
+      throw createGraphQLError(
+        `Can only validate strings or objects as GeoJSON but got a: ${ast.kind}`,
+        { nodes: [ast] },
+      );
+    }
+    return validate(ast.kind === Kind.STRING ? ast.value : ast, ast);
+  },
+
+  extensions: {
+    codegenScalarType: generateGeoJSONType(),
+    jsonSchema: geojsonSchema,
+  },
+});

src/scalars/GeoJSON/codegenScalarType.ts

@@ -0,0 +1,74 @@
+// Helper function to generate Position type
+const generatePositionType = () => `[number, number] | [number, number, number]`;
+
+// Helper function to generate BBox type
+const generateBBoxType = () =>
+  `[number, number, number, number] | [number, number, number, number, number, number]`;
+
+// Helper function to generate Point type
+const generatePointType = () => `{
+  type: "Point";
+  coordinates: ${generatePositionType()};
+  bbox?: ${generateBBoxType()};
+}`;
+
+// Helper function to generate MultiPoint type
+const generateMultiPointType = () => `{
+  type: "MultiPoint";
+  coordinates: ${generatePositionType()}[];
+  bbox?: ${generateBBoxType()};
+}`;
+
+// Helper function to generate LineString type
+const generateLineStringType = () => `{
+  type: "LineString";
+  coordinates: ${generatePositionType()}[];
+  bbox?: ${generateBBoxType()};
+}`;
+
+// Helper function to generate MultiLineString type
+const generateMultiLineStringType = () => `{
+  type: "MultiLineString";
+  coordinates: ${generatePositionType()}[][];
+  bbox?: ${generateBBoxType()};
+}`;
+
+// Helper function to generate Polygon type
+const generatePolygonType = () => `{
+  type: "Polygon";
+  coordinates: ${generatePositionType()}[][];
+  bbox?: ${generateBBoxType()};
+}`;
+
+// Helper function to generate MultiPolygon type
+const generateMultiPolygonType = () => `{
+  type: "MultiPolygon";
+  coordinates: ${generatePositionType()}[][][];
+  bbox?: ${generateBBoxType()};
+}`;
+
+// Helper function to generate GeometryCollection type
+const generateGeometryCollectionType = () => `{
+  type: "GeometryCollection";
+  geometries: (${generatePointType()} | ${generateMultiPointType()} | ${generateLineStringType()} | ${generateMultiLineStringType()} | ${generatePolygonType()} | ${generateMultiPolygonType()})[];
+  bbox?: ${generateBBoxType()};
+}`;
+
+// Helper function to generate Feature type
+const generateFeatureType = () => `{
+  type: "Feature";
+  geometry: (${generatePointType()} | ${generateMultiPointType()} | ${generateLineStringType()} | ${generateMultiLineStringType()} | ${generatePolygonType()} | ${generateMultiPolygonType()} | ${generateGeometryCollectionType()}) | null;
+  properties: { [key: string]: any } | null;
+  bbox?: ${generateBBoxType()};
+}`;
+
+// Helper function to generate FeatureCollection type
+const generateFeatureCollectionType = () => `{
+  type: "FeatureCollection";
+  features: ${generateFeatureType()}[];
+  bbox?: ${generateBBoxType()};
+}`;
+
+// Generate the complete GeoJSON type
+export const generateGeoJSONType = () =>
+  `(${generatePointType()} | ${generateMultiPointType()} | ${generateLineStringType()} | ${generateMultiLineStringType()} | ${generatePolygonType()} | ${generateMultiPolygonType()} | ${generateGeometryCollectionType()} | ${generateFeatureType()} | ${generateFeatureCollectionType()})`;

src/scalars/GeoJSON/index.ts

@@ -0,0 +1 @@
+export { GraphQLGeoJSON } from './GeoJSON.js';