@theihtisham/devtools-with-cloud 1.0.0

package/src/lib/graphql/formatter.ts

@@ -0,0 +1,147 @@
+/**
+ * GraphQL Query Formatter — pretty-print GraphQL queries with proper indentation.
+ */
+
+const INDENT = '  ';
+
+/**
+ * Pretty-print a raw GraphQL query string with proper indentation.
+ * Handles queries, mutations, subscriptions, fragments, and inline fragments.
+ */
+export function formatQuery(query: string): string {
+  const cleaned = removeComments(query).trim();
+  if (!cleaned) return '';
+
+  const tokens = tokenize(cleaned);
+  return formatTokens(tokens);
+}
+
+/**
+ * Minify a GraphQL query (remove whitespace/comments).
+ */
+export function minifyQuery(query: string): string {
+  return removeComments(query)
+    .replace(/\s+/g, ' ')
+    .replace(/\s*({|}|\(|\)|:|,)\s*/g, '$1')
+    .trim();
+}
+
+/**
+ * Remove GraphQL comments (# ...) from a query string.
+ */
+function removeComments(query: string): string {
+  return query.replace(/#[^\n]*/g, '');
+}
+
+/**
+ * Simple tokenizer — splits query into meaningful chunks.
+ */
+function tokenize(query: string): string[] {
+  const tokens: string[] = [];
+  let current = '';
+  let inString = false;
+  let stringChar = '';
+
+  for (let i = 0; i < query.length; i++) {
+    const char = query[i];
+
+    if (inString) {
+      current += char;
+      if (char === stringChar && query[i - 1] !== '\\') {
+        inString = false;
+        tokens.push(current);
+        current = '';
+      }
+      continue;
+    }
+
+    if (char === '"' || char === "'") {
+      if (current.trim()) tokens.push(current.trim());
+      current = char;
+      inString = true;
+      stringChar = char;
+      continue;
+    }
+
+    if (char === '{' || char === '}' || char === '(' || char === ')') {
+      if (current.trim()) tokens.push(current.trim());
+      tokens.push(char);
+      current = '';
+    } else if (char === ':' || char === ',') {
+      if (current.trim()) tokens.push(current.trim());
+      tokens.push(char);
+      current = '';
+    } else {
+      current += char;
+    }
+  }
+
+  if (current.trim()) tokens.push(current.trim());
+  return tokens;
+}
+
+/**
+ * Format tokens into a properly indented string.
+ */
+function formatTokens(tokens: string[]): string {
+  let result = '';
+  let indentLevel = 0;
+  let firstToken = true;
+  let afterColon = false;
+  let afterOpenParen = false;
+  let parenDepth = 0;
+
+  for (const token of tokens) {
+    switch (token) {
+      case '{':
+        result += ` {\n`;
+        indentLevel++;
+        afterColon = false;
+        break;
+
+      case '}':
+        indentLevel = Math.max(0, indentLevel - 1);
+        result += `${INDENT.repeat(indentLevel)}}\n`;
+        afterColon = false;
+        break;
+
+      case '(':
+        result += '(';
+        parenDepth++;
+        afterOpenParen = true;
+        break;
+
+      case ')':
+        parenDepth = Math.max(0, parenDepth - 1);
+        result += ')';
+        afterOpenParen = false;
+        break;
+
+      case ':':
+        result += ': ';
+        afterColon = true;
+        break;
+
+      case ',':
+        result += ', ';
+        afterColon = false;
+        break;
+
+      default:
+        if (firstToken) {
+          result += token;
+          firstToken = false;
+        } else if (afterOpenParen || parenDepth > 0) {
+          result += token;
+        } else if (afterColon) {
+          result += token;
+          afterColon = false;
+        } else {
+          result += `${INDENT.repeat(indentLevel)}${token}`;
+        }
+        break;
+    }
+  }
+
+  return result.trim();
+}

package/src/lib/graphql/index.ts

@@ -0,0 +1,43 @@
+/**
+ * GraphQL module — query builder, introspection, formatting, and validation.
+ */
+
+export type {
+  GraphQLOperationType,
+  GraphQLVariable,
+  GraphQLField,
+  GraphQLArgument,
+  GraphQLFragment,
+  GraphQLQuery,
+  GraphQLSchemaType,
+  GraphQLSchemaField,
+  GraphQLSchemaArg,
+  GraphQLSchema,
+  GraphQLValidationError,
+  GraphQLValidationResult,
+  IntrospectionResponse,
+} from './types';
+
+export { QueryBuilder } from './builder';
+
+export {
+  fetchSchema,
+  parseSchema,
+  getQueryFields,
+  getMutationFields,
+  getSubscriptionFields,
+  getTypeFields,
+  getTypesByKind,
+  findType,
+  unwrapTypeName,
+  isLeafType,
+  INTROSPECTION_QUERY,
+} from './introspection';
+
+export { formatQuery, minifyQuery } from './formatter';
+
+export {
+  validateQuery,
+  validateQueryString,
+  validateAgainstSchema,
+} from './validator';

package/src/lib/graphql/introspection.ts

@@ -0,0 +1,175 @@
+/**
+ * GraphQL Schema Introspection — fetch, parse, and query a GraphQL schema.
+ */
+
+import type {
+  GraphQLSchema,
+  GraphQLSchemaType,
+  GraphQLSchemaField,
+  IntrospectionResponse,
+} from './types';
+
+/** Full introspection query string */
+const INTROSPECTION_QUERY = `
+  query IntrospectionQuery {
+    __schema {
+      queryType { name }
+      mutationType { name }
+      subscriptionType { name }
+      types {
+        kind
+        name
+        fields(includeDeprecated: true) {
+          name
+          description
+          args {
+            name
+            description
+            type {
+              kind
+              name
+              ofType { kind name ofType { kind name ofType { kind name } } }
+            }
+            defaultValue
+          }
+          type {
+            kind
+            name
+            ofType { kind name ofType { kind name ofType { kind name } } }
+          }
+        }
+        inputFields {
+          name
+          description
+          type {
+            kind
+            name
+            ofType { kind name ofType { kind name ofType { kind name } } }
+          }
+          defaultValue
+        }
+        enumValues(includeDeprecated: true) {
+          name
+          description
+        }
+      }
+    }
+  }
+`;
+
+/**
+ * Fetch the GraphQL schema from an endpoint via introspection.
+ */
+export async function fetchSchema(
+  endpoint: string,
+  headers: Record<string, string> = {},
+): Promise<GraphQLSchema> {
+  const response = await fetch(endpoint, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      ...headers,
+    },
+    body: JSON.stringify({ query: INTROSPECTION_QUERY }),
+  });
+
+  if (!response.ok) {
+    throw new Error(`Introspection request failed: ${response.status} ${response.statusText}`);
+  }
+
+  const json = (await response.json()) as IntrospectionResponse;
+
+  if (json.errors && json.errors.length > 0) {
+    throw new Error(`Introspection errors: ${json.errors.map((e) => e.message).join(', ')}`);
+  }
+
+  if (!json.data?.__schema) {
+    throw new Error('No schema data returned from introspection query');
+  }
+
+  return json.data.__schema;
+}
+
+/**
+ * Parse a raw introspection response into our schema types.
+ */
+export function parseSchema(schemaResponse: IntrospectionResponse): GraphQLSchema | null {
+  if (!schemaResponse.data?.__schema) return null;
+  return schemaResponse.data.__schema;
+}
+
+/**
+ * Get the available query fields from a schema.
+ */
+export function getQueryFields(schema: GraphQLSchema): GraphQLSchemaField[] {
+  if (!schema.queryType?.name) return [];
+  const queryType = findType(schema, schema.queryType.name);
+  return queryType?.fields ?? [];
+}
+
+/**
+ * Get the available mutation fields from a schema.
+ */
+export function getMutationFields(schema: GraphQLSchema): GraphQLSchemaField[] {
+  const name = schema.mutationType?.name;
+  if (!name) return [];
+  const mutationType = findType(schema, name);
+  return mutationType?.fields ?? [];
+}
+
+/**
+ * Get the available subscription fields from a schema.
+ */
+export function getSubscriptionFields(schema: GraphQLSchema): GraphQLSchemaField[] {
+  const name = schema.subscriptionType?.name;
+  if (!name) return [];
+  const subscriptionType = findType(schema, name);
+  return subscriptionType?.fields ?? [];
+}
+
+/**
+ * Get the fields for a specific named type.
+ */
+export function getTypeFields(schema: GraphQLSchema, typeName: string): GraphQLSchemaField[] {
+  const type = findType(schema, typeName);
+  return type?.fields ?? [];
+}
+
+/**
+ * Get all types of a specific kind from the schema.
+ */
+export function getTypesByKind(
+  schema: GraphQLSchema,
+  kind: GraphQLSchemaType['kind'],
+): GraphQLSchemaType[] {
+  return schema.types.filter((t) => t.kind === kind);
+}
+
+/**
+ * Find a type by name in the schema.
+ */
+export function findType(schema: GraphQLSchema, name: string): GraphQLSchemaType | undefined {
+  return schema.types.find((t) => t.name === name);
+}
+
+/**
+ * Get a human-readable type name, unwrapping NON_NULL and LIST wrappers.
+ */
+export function unwrapTypeName(type: GraphQLSchemaType | undefined): string {
+  if (!type) return 'Unknown';
+  if (type.name) return type.name;
+  if (type.ofType) return unwrapTypeName(type.ofType);
+  return 'Unknown';
+}
+
+/**
+ * Check if a type is a leaf type (SCALAR or ENUM).
+ */
+export function isLeafType(type: GraphQLSchemaType): boolean {
+  return type.kind === 'SCALAR' || type.kind === 'ENUM';
+}
+
+/**
+ * Export the introspection query string for custom use.
+ */
+export { INTROSPECTION_QUERY };

package/src/lib/graphql/types.ts

@@ -0,0 +1,99 @@
+/**
+ * GraphQL type definitions for the query builder, introspection, and validation.
+ */
+
+/** Supported GraphQL operation types */
+export type GraphQLOperationType = 'query' | 'mutation' | 'subscription';
+
+/** A GraphQL variable definition */
+export interface GraphQLVariable {
+  name: string;
+  type: string;
+  defaultValue?: string;
+}
+
+/** A field argument */
+export interface GraphQLArgument {
+  name: string;
+  value: string;
+}
+
+/** A field within a selection set */
+export interface GraphQLField {
+  name: string;
+  alias?: string;
+  arguments?: GraphQLArgument[];
+  subfields?: GraphQLField[];
+  fragments?: string[];
+}
+
+/** A named fragment definition */
+export interface GraphQLFragment {
+  name: string;
+  onType: string;
+  fields: GraphQLField[];
+}
+
+/** A complete GraphQL query/mutation */
+export interface GraphQLQuery {
+  operationType: GraphQLOperationType;
+  name?: string;
+  variables: GraphQLVariable[];
+  fields: GraphQLField[];
+  fragments: GraphQLFragment[];
+}
+
+/** Schema type information from introspection */
+export interface GraphQLSchemaType {
+  name: string;
+  kind: 'SCALAR' | 'OBJECT' | 'INTERFACE' | 'UNION' | 'ENUM' | 'INPUT_OBJECT' | 'LIST' | 'NON_NULL';
+  fields?: GraphQLSchemaField[];
+  enumValues?: string[];
+  inputFields?: GraphQLSchemaField[];
+  ofType?: GraphQLSchemaType;
+}
+
+/** Schema field from introspection */
+export interface GraphQLSchemaField {
+  name: string;
+  type: GraphQLSchemaType;
+  args: GraphQLSchemaArg[];
+  description?: string;
+}
+
+/** Schema argument from introspection */
+export interface GraphQLSchemaArg {
+  name: string;
+  type: GraphQLSchemaType;
+  defaultValue?: string | null;
+  description?: string;
+}
+
+/** Full introspected schema */
+export interface GraphQLSchema {
+  queryType?: { name: string };
+  mutationType?: { name: string | null };
+  subscriptionType?: { name: string | null };
+  types: GraphQLSchemaType[];
+}
+
+/** Validation error */
+export interface GraphQLValidationError {
+  message: string;
+  line?: number;
+  column?: number;
+}
+
+/** Validation result */
+export interface GraphQLValidationResult {
+  valid: boolean;
+  errors: GraphQLValidationError[];
+}
+
+/** Introspection response shape */
+export interface IntrospectionResponse {
+  data?: {
+    __schema: GraphQLSchema;
+  };
+  errors?: Array<{ message: string }>;
+}

package/src/lib/graphql/validator.ts

@@ -0,0 +1,216 @@
+/**
+ * GraphQL Query Validator — validate queries against known patterns and report errors.
+ *
+ * This is a structural/syntactic validator (not a full GraphQL spec validator).
+ * For full spec validation, pair with a server-side validation step.
+ */
+
+import type {
+  GraphQLQuery,
+  GraphQLSchema,
+  GraphQLValidationError,
+  GraphQLValidationResult,
+  GraphQLField,
+} from './types';
+
+/**
+ * Validate a GraphQLQuery object for structural correctness.
+ */
+export function validateQuery(query: GraphQLQuery): GraphQLValidationResult {
+  const errors: GraphQLValidationError[] = [];
+
+  // Check operation type
+  const validOps = ['query', 'mutation', 'subscription'];
+  if (!validOps.includes(query.operationType)) {
+    errors.push({
+      message: `Invalid operation type: "${query.operationType}". Must be one of: ${validOps.join(', ')}`,
+    });
+  }
+
+  // Check that the selection set is non-empty
+  if (query.fields.length === 0) {
+    errors.push({
+      message: 'Selection set is empty. At least one field is required.',
+    });
+  }
+
+  // Validate fields recursively
+  validateFields(query.fields, errors, []);
+
+  // Validate variables have names and types
+  for (const v of query.variables) {
+    if (!v.name) {
+      errors.push({ message: 'Variable definition is missing a name.' });
+    }
+    if (!v.type) {
+      errors.push({ message: `Variable "$${v.name}" is missing a type.` });
+    }
+  }
+
+  // Validate fragments
+  for (const f of query.fragments) {
+    if (!f.name) {
+      errors.push({ message: 'Fragment definition is missing a name.' });
+    }
+    if (!f.onType) {
+      errors.push({ message: `Fragment "${f.name}" is missing the "onType" condition.` });
+    }
+    if (f.fields.length === 0) {
+      errors.push({ message: `Fragment "${f.name}" has an empty selection set.` });
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Validate a raw GraphQL query string for basic syntax errors.
+ */
+export function validateQueryString(queryString: string): GraphQLValidationResult {
+  const errors: GraphQLValidationError[] = [];
+  const trimmed = queryString.trim();
+
+  if (!trimmed) {
+    errors.push({ message: 'Query string is empty.' });
+    return { valid: false, errors };
+  }
+
+  // Check balanced braces
+  let braceDepth = 0;
+  let parenDepth = 0;
+  let inString = false;
+  let stringChar = '';
+
+  for (let i = 0; i < trimmed.length; i++) {
+    const char = trimmed[i];
+    const prev = i > 0 ? trimmed[i - 1] : '';
+
+    if (inString) {
+      if (char === stringChar && prev !== '\\') {
+        inString = false;
+      }
+      continue;
+    }
+
+    if (char === '"' || char === "'") {
+      inString = true;
+      stringChar = char;
+      continue;
+    }
+
+    if (char === '{') braceDepth++;
+    if (char === '}') {
+      braceDepth--;
+      if (braceDepth < 0) {
+        errors.push({ message: 'Unexpected closing brace "}"', column: i + 1 });
+      }
+    }
+    if (char === '(') parenDepth++;
+    if (char === ')') {
+      parenDepth--;
+      if (parenDepth < 0) {
+        errors.push({ message: 'Unexpected closing parenthesis ")"', column: i + 1 });
+      }
+    }
+  }
+
+  if (braceDepth > 0) {
+    errors.push({ message: `Missing ${braceDepth} closing brace(s) "}"` });
+  }
+  if (braceDepth < 0) {
+    errors.push({ message: `Unexpected ${Math.abs(braceDepth)} closing brace(s) "}"` });
+  }
+  if (parenDepth > 0) {
+    errors.push({ message: `Missing ${parenDepth} closing parenthesis ")"` });
+  }
+
+  // Check that the query starts with a valid keyword or brace
+  const startsWithKeyword = /^(query|mutation|subscription|fragment|\{)/.test(trimmed);
+  if (!startsWithKeyword) {
+    errors.push({
+      message: 'Query must start with "query", "mutation", "subscription", "fragment", or "{".',
+    });
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Validate a query against a known schema (field existence check).
+ */
+export function validateAgainstSchema(
+  query: GraphQLQuery,
+  schema: GraphQLSchema,
+): GraphQLValidationResult {
+  const errors: GraphQLValidationError[] = [];
+
+  // First do structural validation
+  const structuralResult = validateQuery(query);
+  if (!structuralResult.valid) {
+    return structuralResult;
+  }
+
+  // Determine the root type
+  let rootTypeName: string | undefined;
+  if (query.operationType === 'query') {
+    rootTypeName = schema.queryType?.name;
+  } else if (query.operationType === 'mutation') {
+    rootTypeName = schema.mutationType?.name ?? undefined;
+  }
+
+  if (!rootTypeName) {
+    errors.push({
+      message: `Schema does not define a ${query.operationType} type.`,
+    });
+    return { valid: false, errors };
+  }
+
+  // Find the root type in schema
+  const rootType = schema.types.find((t) => t.name === rootTypeName);
+  if (!rootType?.fields) {
+    errors.push({ message: `Could not find type "${rootTypeName}" in schema.` });
+    return { valid: false, errors };
+  }
+
+  // Check each top-level field exists
+  for (const field of query.fields) {
+    const fieldName = field.name.startsWith('...') ? field.name.slice(3) : field.name;
+    const schemaField = rootType.fields.find((f) => f.name === fieldName);
+    if (!schemaField && !field.name.startsWith('...')) {
+      errors.push({
+        message: `Field "${fieldName}" does not exist on type "${rootTypeName}".`,
+      });
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Recursively validate field structure.
+ */
+function validateFields(fields: GraphQLField[], errors: GraphQLValidationError[], path: string[]): void {
+  for (const field of fields) {
+    const fieldPath = [...path, field.name].join('.');
+
+    if (!field.name) {
+      errors.push({ message: `Empty field name at path: ${path.join('.') || '<root>'}` });
+      continue;
+    }
+
+    // Fragment spreads are valid
+    if (field.name.startsWith('...')) continue;
+
+    if (field.arguments) {
+      for (const arg of field.arguments) {
+        if (!arg.name) {
+          errors.push({ message: `Argument missing name in field "${fieldPath}".` });
+        }
+      }
+    }
+
+    if (field.subfields && field.subfields.length > 0) {
+      validateFields(field.subfields, errors, [...path, field.name]);
+    }
+  }
+}