Client Management

/**
 * Creates a new GraphQL client instance
 * @param options - Configuration options for the client
 * @returns Configured Client instance
 */
function createClient(options: ClientOptions): Client;

interface ClientOptions {
  /** Target URL for GraphQL API requests */
  url: string;
  /** Array of exchanges that form the processing pipeline */
  exchanges: Exchange[];
  /** Additional options for fetch requests */
  fetchOptions?: RequestInit | (() => RequestInit);
  /** Custom fetch function polyfill */
  fetch?: typeof fetch;
  /** Allow subscriptions via fetch instead of separate transport */
  fetchSubscriptions?: boolean;
  /** Enable React/Preact Suspense support */
  suspense?: boolean;
  /** Default request policy for operations */
  requestPolicy?: RequestPolicy;
  /** Use GET requests for queries */
  preferGetMethod?: boolean | 'force' | 'within-url-limit';
}

import { createClient, cacheExchange, fetchExchange } from "@urql/core";

// Basic client setup
const client = createClient({
  url: "https://api.example.com/graphql",
  exchanges: [cacheExchange, fetchExchange],
});

// Client with custom fetch options
const authenticatedClient = createClient({
  url: "https://api.example.com/graphql",
  exchanges: [cacheExchange, fetchExchange],
  fetchOptions: () => ({
    headers: {
      authorization: `Bearer ${getAuthToken()}`,
    },
  }),
});

// Client with GET requests for queries
const cacheFriendlyClient = createClient({
  url: "https://api.example.com/graphql",
  exchanges: [cacheExchange, fetchExchange],
  preferGetMethod: 'within-url-limit',
});

class Client {
  /** Flag indicating if Suspense support is enabled */
  readonly suspense: boolean;

  /** Create an operation from a request and context */
  createRequestOperation<Data = any, Variables extends AnyVariables = AnyVariables>(
    kind: OperationType,
    request: GraphQLRequest<Data, Variables>,
    opts?: Partial<OperationContext> | undefined
  ): Operation<Data, Variables>;

  /** Execute an operation and return a result source */
  executeRequestOperation<Data = any, Variables extends AnyVariables = AnyVariables>(
    operation: Operation<Data, Variables>
  ): OperationResultSource<OperationResult<Data, Variables>>;

  /** Redispatch an operation if it has active consumers */
  reexecuteOperation(operation: Operation): void;
}

type RequestPolicy = 
  | 'cache-first'      // Use cache if available, fallback to network
  | 'cache-and-network' // Return cache immediately, then network result
  | 'network-only'      // Always make network request, bypass cache
  | 'cache-only';       // Only return cached results, never network

interface OperationContext {
  requestPolicy: RequestPolicy;
  // ... other context properties
}

// Override request policy per operation
const result = await client.query(
  GetUserQuery, 
  { id: "123" },
  { requestPolicy: 'network-only' }
).toPromise();

// Cache-and-network for immediate response with fresh data
const source = client.query(
  GetPostsQuery,
  {},
  { requestPolicy: 'cache-and-network' }
);

interface OperationContext {
  /** GraphQL API endpoint URL */
  url: string;
  /** Fetch options for HTTP requests */
  fetchOptions?: RequestInit | (() => RequestInit);
  /** Custom fetch implementation */
  fetch?: typeof fetch;
  /** Enable subscription over fetch */
  fetchSubscriptions?: boolean;
  /** Caching and network strategy */
  requestPolicy: RequestPolicy;
  /** Use GET method for queries */
  preferGetMethod?: boolean | 'force' | 'within-url-limit';
  /** Enable Suspense mode */
  suspense?: boolean;
  /** Additional cache invalidation typenames */
  additionalTypenames?: string[];
  /** Debug metadata for development */
  meta?: OperationDebugMeta;
  /** Allow arbitrary additional properties */
  [key: string]: any;
}

// Override URL for specific operation
const result = await client.query(
  GetExternalDataQuery,
  { id: "123" },
  { url: "https://external-api.com/graphql" }
).toPromise();

// Add cache invalidation hints
await client.mutation(
  UpdateUserMutation,
  { id: "123", name: "New Name" },
  { additionalTypenames: ['User'] }
).toPromise();

// Force GET request for a specific query
const cached = await client.query(
  GetPublicDataQuery,
  {},
  { preferGetMethod: 'force' }
).toPromise();

interface Client {
  new (options: ClientOptions): Client;
}

const Client: new (opts: ClientOptions) => Client;

// Direct instantiation (equivalent to createClient)
const client = new Client({
  url: "https://api.example.com/graphql",
  exchanges: [cacheExchange, fetchExchange],
});

interface OperationDebugMeta {
  /** Human-readable source of the operation */
  source?: string;
  /** Cache outcome for the operation */
  cacheOutcome?: CacheOutcome;
  /** Network request latency in milliseconds */
  networkLatency?: number;
  /** Request start timestamp */
  startTime?: number;
}

type CacheOutcome = 'miss' | 'partial' | 'hit';