@replit/graphql-codegen-persisted-queries/dist/index.d.mts

GraphQL Codegen plugin to generate persisted query manifests for server and client

import { OperationTypeNode, FragmentDefinitionNode, OperationDefinitionNode, DocumentNode } from 'graphql';
import { PluginFunction } from '@graphql-codegen/plugin-helpers';

/**
 * Configuration for the persisted query generator plugin
 */
interface PluginConfig {
    /**
     * Output format - 'server' generates hash->operation mapping,
     * 'client' generates operation->hash mapping
     */
    output: 'server' | 'client';
    /**
     * Hash algorithm to use (defaults to 'sha256')
     */
    algorithm?: string;
    /**
     * Whether to prefix the hash with the algorithm name (e.g. "sha256:abc123...")
     * Follows the GraphQL over HTTP specification when enabled
     * @see https://github.com/graphql/graphql-over-http/blob/52d56fb36d51c17e08a920510a23bdc2f6a720be/spec/Appendix%20A%20--%20Persisted%20Documents.md#sha256-hex-document-identifier
     * @default false
     */
    includeAlgorithmPrefix?: boolean;
}
/**
 * Represents a single operation in the persisted query manifest
 */
interface PersistedQueryManifestOperation {
    /** Operation type (query, mutation, subscription) */
    type: OperationTypeNode;
    /** Operation name */
    name: string;
    /** Full operation body text */
    body: string;
}
/**
 * Server-side persisted operation manifest format
 */
interface ServerOperationListManifest {
    format: 'apollo-persisted-query-manifest';
    version: 1;
    operations: Record<string, PersistedQueryManifestOperation>;
}
/**
 * Client-side persisted operation manifest format
 */
type ClientOperationListManifest = Record<string, string>;
/**
 * Union type for both manifest formats
 */
type OperationListManifest = ServerOperationListManifest | ClientOperationListManifest;
/**
 * Internal type for a GraphQL definition
 */
type Definition = FragmentDefinitionNode | OperationDefinitionNode;
/**
 * Represents a processed GraphQL operation with hash and query details
 */
interface ProcessedOperation {
    name: string;
    hash: string;
    type: OperationTypeNode;
    query: string;
    definition: OperationDefinitionNode;
    fragments: FragmentDefinitionNode[];
}
/**
 * Plugin function type
 */
type PersistedQueryPlugin = PluginFunction<PluginConfig, string>;

/**
 * Generates a client-side persisted query manifest
 * Client manifests map operation names to their hash
 *
 * @param docs - Array of GraphQL document nodes
 * @param config - Plugin configuration
 * @returns Client-side manifest object
 * @throws Error if an operation is missing a name
 */
declare function generateClientManifest(docs: DocumentNode[], config: PluginConfig): ClientOperationListManifest;
/**
 * Generates a server-side persisted query manifest
 * Server manifests map query hashes to operation details
 *
 * @param docs - Array of GraphQL document nodes
 * @param config - Plugin configuration
 * @returns Server-side manifest object
 * @throws Error if an operation is missing a name
 */
declare function generateServerManifest(docs: DocumentNode[], config: PluginConfig): ServerOperationListManifest;

/**
 * GraphQL CodeGen plugin for generating persisted operation manifests
 *
 * @param _schema - GraphQL schema (unused)
 * @param documents - GraphQL documents to process
 * @param config - Plugin configuration
 * @returns JSON string representation of the generated manifest
 * @throws Error if no documents are provided or output format is not specified
 *
 * For GraphQL over HTTP specification compliance, set `includeAlgorithmPrefix: true`
 * to enable the "Prefixed Document Identifier" format (e.g., `sha256:abc123...`).
 */
declare const plugin: PersistedQueryPlugin;

/**
 * Extracts all fragment definitions from an array of documents
 *
 * @param docs - Array of GraphQL document nodes to scan
 * @returns A map of fragment names to their definitions
 */
declare function findFragments(docs: (DocumentNode | FragmentDefinitionNode)[]): Map<string, FragmentDefinitionNode>;
/**
 * Finds all fragments used in an operation or fragment, including nested fragments
 *
 * @param operation - The operation or fragment to analyze
 * @param knownFragments - Map of all available fragments
 * @param _usedFragments - Optional accumulator for recursive calls
 * @returns Map of all fragments used by the operation
 * @throws Error if a referenced fragment cannot be found
 */
declare function findUsedFragments(operation: OperationDefinitionNode | FragmentDefinitionNode, knownFragments: ReadonlyMap<string, FragmentDefinitionNode>, _usedFragments?: Map<string, FragmentDefinitionNode>): Map<string, FragmentDefinitionNode>;

/**
 * Creates a hash for a given string using the specified algorithm
 *
 * @param content - The content string to hash
 * @param config - Plugin configuration
 * @returns A hex string hash of the content by default, or a prefixed hash (e.g. "sha256:abc123...")
 *          when includeAlgorithmPrefix is true for GraphQL over HTTP specification compliance
 */
declare function createHash(content: string, config: PluginConfig): string;

/**
 * Prints an array of definitions as a single string
 *
 * @param definitions - Array of GraphQL definitions to print
 * @returns Printed string representation
 */
declare function printDefinitions(definitions: (Definition | DocumentNode)[]): string;
/**
 * Adds __typename to all selection sets in a document
 * Adapted from Apollo Client
 *
 * @param doc - GraphQL document node
 * @returns Document with __typename fields added
 */
declare function addTypenameToDocument(doc: DocumentNode): DocumentNode;

export { type ClientOperationListManifest, type Definition, type OperationListManifest, type PersistedQueryManifestOperation, type PersistedQueryPlugin, type PluginConfig, type ProcessedOperation, type ServerOperationListManifest, addTypenameToDocument, createHash, findFragments, findUsedFragments, generateClientManifest, generateServerManifest, plugin, printDefinitions };