@nmarks/graphql-codegen-per-operation-file-preset 1.0.6 → 1.0.7

package/cjs/index.js

@@ -24,97 +24,178 @@ function extractDefinitions(document) {
     return definitions;
 }
 /**
- * Check if a document actually needs type imports from the schema.
- * Only returns true if the document uses:
- * - Enums
- * - Custom scalars that aren't mapped to primitives
- * - Input types (in variables)
+ * Finds "local" fragments - fragments defined in the same source file as the current definition.
+ * These are initially local but become external after we split the file per-operation.
  *
- * Does NOT return true for just referencing object types.
+ * Example:
+ * Source file has: query MyQuery { ...MyFragment } + fragment MyFragment { ... }
+ * After split: MyQuery.ts needs to import from MyFragment.ts
+ */
+function findLocalFragments(allDefinitions, currentDefinitionName) {
+    return allDefinitions
+        .filter(d => d.definition.kind === graphql_1.Kind.FRAGMENT_DEFINITION &&
+        d.name !== currentDefinitionName)
+        .map(d => d.definition);
+}
+/**
+ * Creates LoadedFragment objects for local fragments so they can be treated as external fragments
+ * during code generation. This ensures proper validation and type generation.
+ */
+function createLoadedFragments(fragments) {
+    return fragments.map(frag => ({
+        level: 0,
+        isExternal: true,
+        name: frag.name.value,
+        onType: frag.typeCondition.name.value,
+        node: frag,
+    }));
+}
+/**
+ * Creates fragment import declarations for local fragments.
+ * After splitting, these fragments will be in separate files, so we need to generate imports.
+ *
+ * Example: query references RetailerServicesData → import from './RetailerServicesData.ts'
+ */
+function createLocalFragmentImports(localFragments, sourceLocation, currentFilename, folder, extension, options) {
+    return localFragments.map((frag) => {
+        var _a;
+        const fragmentFilePath = (0, utils_js_1.generateOperationFilePath)(sourceLocation, frag.name.value, folder, extension);
+        // Generate import identifiers: both the document (for runtime) and type (for TypeScript)
+        const identifiers = [
+            {
+                name: `${frag.name.value}FragmentDoc`,
+                kind: 'document',
+            },
+            {
+                name: `${frag.name.value}Fragment`,
+                kind: 'type',
+            },
+        ];
+        return {
+            baseDir: options.baseDir,
+            baseOutputDir: options.baseOutputDir,
+            outputPath: currentFilename,
+            importSource: {
+                path: fragmentFilePath,
+                identifiers,
+            },
+            emitLegacyCommonJSImports: options.emitLegacyCommonJSImports,
+            importExtension: options.importExtension,
+            typesImport: (_a = options.useTypeImports) !== null && _a !== void 0 ? _a : false,
+        };
+    });
+}
+/**
+ * TYPES IMPORT OPTIMIZATION
+ *
+ * Determines if `import * as Types from '...'` is actually needed for this specific operation/fragment.
+ *
+ * Background:
+ * The standard `isUsingTypes()` function is too broad - it returns true for ANY schema type reference,
+ * including object types. But object types don't need imports since they're generated inline.
+ *
+ * We ONLY need the Types import when generated code actually references the Types namespace:
+ *
+ * ✅ NEEDS IMPORT:
+ * - Operations (query/mutation/subscription) - generate `Types.Exact<{...}>` for Variables type
+ * - Enums - generate `role: Types.Role`
+ * - Custom scalars (unless mapped to primitives) - generate `date: Types.DateTime`
+ * - Input types - used in variables as `Types.MyInput`
+ *
+ * ❌ NO IMPORT NEEDED:
+ * - Fragments with only scalars/object types - no Types namespace references
+ * - Custom scalars mapped to primitives (JSON → any) - uses TypeScript primitives
+ * - Object type references (User, Product) - generated inline, not from Types
+ *
+ * This optimization reduces unnecessary imports and makes generated files cleaner.
  */
 function needsSchemaTypesImport(document, schema, config) {
     const builtInScalars = ['String', 'Int', 'Float', 'Boolean', 'ID'];
     const primitiveTypes = ['any', 'string', 'number', 'boolean', 'null', 'undefined', 'void', 'never', 'unknown'];
     let needsImport = false;
-    // Get scalar mappings from config
     const scalarMappings = config.scalars || {};
-    // Check if document has an operation definition
-    // ALL operations (query/mutation/subscription) generate a Variables type that uses Types.Exact
-    // even if they have no variables: Types.Exact<{ [key: string]: never; }>
+    /**
+     * STEP 1: Check for operations (queries/mutations/subscriptions)
+     * All operations generate a Variables type that uses Types.Exact, even without variables:
+     * `export type MyQueryVariables = Types.Exact<{ [key: string]: never; }>;`
+     */
     let hasOperation = false;
-    // Collect all type names referenced in the document
     const referencedTypeNames = new Set();
     (0, graphql_1.visit)(document, {
-        // Operations always need Types import for their Variables type
         OperationDefinition: () => {
             hasOperation = true;
         },
-        // Check variable types for input types or custom scalars
         VariableDefinition: (node) => {
             const typeName = getBaseTypeName(node.type);
             referencedTypeNames.add(typeName);
         },
-        // Collect fragment type conditions
         FragmentDefinition: (node) => {
             referencedTypeNames.add(node.typeCondition.name.value);
         },
     });
-    // All operations generate Variables type that uses Types.Exact
     if (hasOperation) {
         return true;
     }
-    // Helper to recursively check if a type needs importing
+    /**
+     * STEP 2: Check if any schema types actually need importing
+     *
+     * Helper that checks if a GraphQL type requires an import from Types namespace.
+     * Returns true only for enums, custom scalars (unless mapped to primitives), and input types.
+     */
     const checkType = (type) => {
         if (!type)
             return false;
-        // Unwrap lists and non-null
+        // Unwrap wrapper types (List, NonNull)
         while ('ofType' in type && type.ofType) {
             type = type.ofType;
         }
-        // Enums always need to be imported
+        // Enums always need import: `role: Types.Role`
         if ((0, graphql_1.isEnumType)(type)) {
             return true;
         }
-        // Custom scalars need to be imported UNLESS mapped to primitives
+        // Custom scalars - depends on mapping
         if ((0, graphql_1.isScalarType)(type) && !builtInScalars.includes(type.name)) {
-            // Check if this scalar is mapped to a primitive type
             const mapping = scalarMappings[type.name];
-            if (mapping) {
-                // If mapped to a primitive type string, no import needed
-                if (typeof mapping === 'string' && primitiveTypes.includes(mapping)) {
-                    return false;
-                }
-                // If mapped to an object like { input: 'any', output: 'any' }, check both
-                if (typeof mapping === 'object') {
-                    const inputMapping = mapping.input || mapping.output;
-                    const outputMapping = mapping.output || mapping.input;
-                    if (primitiveTypes.includes(inputMapping) && primitiveTypes.includes(outputMapping)) {
-                        return false;
-                    }
-                }
+            // No mapping = defaults to 'any' = no import needed
+            if (!mapping) {
+                return false;
             }
-            else {
-                // No mapping specified, defaults to 'any', so no import needed
+            // Mapped to primitive (string, any, number, etc.) = no import needed
+            if (typeof mapping === 'string' && primitiveTypes.includes(mapping)) {
                 return false;
             }
-            // Scalar is mapped to something non-primitive, needs import
+            // Mapped to object with input/output
+            if (typeof mapping === 'object') {
+                const inputMapping = mapping.input || mapping.output;
+                const outputMapping = mapping.output || mapping.input;
+                if (primitiveTypes.includes(inputMapping) && primitiveTypes.includes(outputMapping)) {
+                    return false;
+                }
+            }
+            // Scalar mapped to custom type (e.g., Date) = needs import
             return true;
         }
-        // Input types need to be imported
+        // Input types always need import: `input: Types.MyInput`
         if ((0, graphql_1.isInputObjectType)(type)) {
             return true;
         }
         return false;
     };
-    // Check variable types
+    /**
+     * STEP 3: Check variable types
+     * Variables can use enums, input types, or custom scalars directly
+     */
     for (const typeName of referencedTypeNames) {
         const type = schema.getType(typeName);
         if (checkType(type)) {
             return true;
         }
     }
-    // Now we need to check all fields in the document to see if any return enums/custom scalars
-    // We'll do a more thorough traversal with TypeInfo
+    /**
+     * STEP 4: Check field return types
+     * Use TypeInfo to properly resolve field types through the schema.
+     * This catches cases like: user { role } where 'role' returns an enum.
+     */
     const typeInfo = new graphql_1.TypeInfo(schema);
     (0, graphql_1.visit)(document, (0, graphql_1.visitWithTypeInfo)(typeInfo, {
         Field: () => {
@@ -138,12 +219,28 @@ function getBaseTypeName(type) {
     }
     return '';
 }
+/**
+ * PER-OPERATION-FILE PRESET
+ *
+ * Generates ONE FILE PER OPERATION/FRAGMENT instead of one file per source file.
+ *
+ * Architecture:
+ * 1. Fragment Resolution: Analyze all documents to build fragment registry and dependencies
+ * 2. Document Splitting: Split each source document into separate operations/fragments
+ * 3. Local Fragment Handling: Treat same-file fragments as external after splitting
+ * 4. Import Optimization: Only add Types import when actually needed (enums, scalars, operations)
+ *
+ * Example:
+ * Input:  src/user.ts with query GetUser + fragment UserFields
+ * Output: src/__generated__/GetUser.ts + src/__generated__/UserFields.ts
+ */
 exports.preset = {
     buildGeneratesSection: options => {
         var _a, _b;
         const schemaObject = options.schemaAst
             ? options.schemaAst
             : (0, graphql_1.buildASTSchema)(options.schema, options.config);
+        // Extract configuration with defaults
         const baseDir = options.presetConfig.cwd || process.cwd();
         const extension = options.presetConfig.extension || '.ts';
         const folder = options.presetConfig.folder || '__generated__';
@@ -157,8 +254,13 @@ exports.preset = {
             ...options.pluginMap,
             add: add_1.default,
         };
-        // Resolve fragment dependencies using our adapted fragment resolver
-        // Fragment paths will be generated based on fragment names
+        /**
+         * PHASE 1: FRAGMENT RESOLUTION
+         *
+         * Analyze all documents to build fragment registry and resolve dependencies.
+         * This uses our adapted fragment-resolver that generates paths based on fragment NAMES
+         * (not source file names), enabling proper imports after splitting.
+         */
         const sources = (0, resolve_document_imports_js_1.resolveDocumentImports)(options, schemaObject, {
             baseDir,
             folder,
@@ -170,75 +272,77 @@ exports.preset = {
             typesImport: (_a = options.config.useTypeImports) !== null && _a !== void 0 ? _a : false,
         }, (0, visitor_plugin_common_1.getConfigValue)(options.config.dedupeFragments, false));
         const artifacts = [];
-        // Now split each source into separate files per operation/fragment
+        /**
+         * MAIN SPLITTING LOGIC
+         *
+         * For each source document (input file), we:
+         * 1. Extract all operations and fragments
+         * 2. Create a separate output file for EACH operation/fragment
+         * 3. Handle fragment dependencies (both external and local)
+         */
         for (const source of sources) {
             const definitions = extractDefinitions(source.documents[0].document);
+            // Process each operation/fragment definition separately
             for (const { name, definition } of definitions) {
+                // Generate output file path: sourceDir/folder/OperationName.extension
                 const filename = (0, utils_js_1.generateOperationFilePath)(source.documents[0].location, name, folder, extension);
-                // Create a document with just this operation/fragment
+                // Create a document with ONLY this single definition
                 const singleDefDocument = {
                     kind: graphql_1.Kind.DOCUMENT,
                     definitions: [definition],
                 };
+                // Note: Initially create source with just the single definition
+                // We'll update it later to include external fragments
                 const singleDefSource = {
-                    rawSDL: source.documents[0].rawSDL, // TODO: might need to filter this
-                    document: singleDefDocument,
+                    rawSDL: source.documents[0].rawSDL, // Contains all original SDL (not filtered)
+                    document: singleDefDocument, // Initially just this one definition
                     location: source.documents[0].location,
                 };
-                // Find other fragments in the same source file (they are "local" now but will be "external" after split)
-                const localFragments = definitions
-                    .filter(d => d.definition.kind === graphql_1.Kind.FRAGMENT_DEFINITION && d.name !== name)
-                    .map(d => d.definition);
-                // Add local fragments to external fragments list so they're available during generation
-                const localFragmentNodes = localFragments.map(frag => ({
-                    level: 0,
-                    isExternal: true,
-                    name: frag.name.value,
-                    onType: frag.typeCondition.name.value,
-                    node: frag,
-                }));
+                /**
+                 * HANDLE LOCAL FRAGMENTS
+                 *
+                 * Problem: If source file has both query + fragment in same gql template:
+                 *   gql`query MyQuery { ...MyFrag } fragment MyFrag { ... }`
+                 *
+                 * After splitting, MyQuery needs to import from MyFrag.ts, but fragment
+                 * resolver marked MyFrag as "local" (same document).
+                 *
+                 * Solution: Treat local fragments as external after splitting.
+                 */
+                const localFragments = findLocalFragments(definitions, name);
+                const localFragmentNodes = createLoadedFragments(localFragments);
+                // Combine external fragments (from other files) + local fragments (same source file)
                 const allExternalFragments = [
                     ...source.externalFragments,
                     ...localFragmentNodes,
                 ];
-                // Update fragment imports to use the correct output path for this operation
+                /**
+                 * UPDATE FRAGMENT IMPORTS
+                 *
+                 * 1. External fragments: Update outputPath to this operation's file
+                 * 2. Local fragments: Generate new imports pointing to their split files
+                 */
                 const updatedFragmentImports = source.fragmentImports.map(fragmentImport => ({
                     ...fragmentImport,
-                    outputPath: filename, // Update to actual output path
+                    outputPath: filename,
                 }));
-                // Generate fragment imports for local fragments (they'll be in separate files after splitting)
-                const localFragmentImports = localFragments.map((frag) => {
-                    var _a;
-                    const fragmentFilePath = (0, utils_js_1.generateOperationFilePath)(source.documents[0].location, frag.name.value, folder, extension);
-                    // Get fragment import identifiers (document + type)
-                    const identifiers = [
-                        {
-                            name: `${frag.name.value}FragmentDoc`,
-                            kind: 'document',
-                        },
-                        {
-                            name: `${frag.name.value}Fragment`,
-                            kind: 'type',
-                        },
-                    ];
-                    return {
-                        baseDir,
-                        baseOutputDir: options.baseOutputDir,
-                        outputPath: filename,
-                        importSource: {
-                            path: fragmentFilePath,
-                            identifiers,
-                        },
-                        emitLegacyCommonJSImports: options.config.emitLegacyCommonJSImports,
-                        importExtension: options.config.importExtension,
-                        typesImport: (_a = options.config.useTypeImports) !== null && _a !== void 0 ? _a : false,
-                    };
+                const localFragmentImports = createLocalFragmentImports(localFragments, source.documents[0].location, filename, folder, extension, {
+                    baseDir,
+                    baseOutputDir: options.baseOutputDir,
+                    emitLegacyCommonJSImports: options.config.emitLegacyCommonJSImports,
+                    importExtension: options.config.importExtension,
+                    useTypeImports: options.config.useTypeImports,
                 });
                 const allFragmentImports = [
                     ...updatedFragmentImports,
                     ...localFragmentImports,
                 ];
-                // Check if THIS specific operation uses types (not the whole source file)
+                /**
+                 * ADD EXTERNAL FRAGMENTS TO DOCUMENT
+                 *
+                 * The plugin needs external fragment definitions in the document to properly resolve types.
+                 * Without these, fragment spreads can't be expanded correctly.
+                 */
                 const singleDefDocumentWithFragments = {
                     ...singleDefDocument,
                     definitions: [
@@ -246,8 +350,21 @@ exports.preset = {
                         ...allExternalFragments.map(fragment => fragment.node),
                     ],
                 };
+                // Update the source to use the document with external fragments
+                singleDefSource.document = singleDefDocumentWithFragments;
+                /**
+                 * CHECK IF TYPES IMPORT IS NEEDED
+                 *
+                 * We only add `import * as Types from '...'` if the operation actually uses:
+                 * - Enums (e.g., Role.ADMIN)
+                 * - Custom scalars mapped to non-primitives
+                 * - Input types (in variables)
+                 * - Operations (all operations generate Variables type using Types.Exact)
+                 *
+                 * We DON'T import for just object type references (e.g., fragment on User)
+                 */
                 const needsTypesImport = needsSchemaTypesImport(singleDefDocumentWithFragments, schemaObject, options.config);
-                // Generate the types import statement if needed
+                // Generate the schema types import statement if needed
                 const importStatements = [];
                 if (needsTypesImport && !options.config.globalNamespace) {
                     const schemaTypesImportStatement = (0, visitor_plugin_common_1.generateImportStatement)({
@@ -264,6 +381,13 @@ exports.preset = {
                     });
                     importStatements.push(schemaTypesImportStatement);
                 }
+                /**
+                 * BUILD PLUGIN CONFIGURATION
+                 *
+                 * Plugins are processed in order:
+                 * 1. 'add' plugin - adds import statements
+                 * 2. User plugins - generate actual operation code (typescript-operations, etc.)
+                 */
                 const plugins = [
                     ...importStatements.map(importStatement => ({
                         add: { content: importStatement },
@@ -274,9 +398,26 @@ exports.preset = {
                     ...options.config,
                     exportFragmentSpreadSubTypes: true,
                     namespacedImportName: importTypesNamespace,
-                    externalFragments: allExternalFragments,
-                    fragmentImports: allFragmentImports,
+                    externalFragments: allExternalFragments, // Includes both external + local fragments
+                    fragmentImports: allFragmentImports, // Import declarations for all fragments
                 };
+                // DEBUG: Log fragment generation details
+                if (name === 'Items_item') {
+                    console.log('\n=== GENERATING Items_item ===');
+                    console.log('External fragments:', allExternalFragments.map(f => ({ name: f.name, level: f.level })));
+                    console.log('Fragment imports:', allFragmentImports.map(fi => fi.importSource.path));
+                    console.log('Document selections:', definition.selectionSet.selections.map((s) => s.kind === 'Field' ? s.name.value : `...${s.name.value}`));
+                    console.log('Document definitions (should be 1):', singleDefDocument.definitions.length);
+                    console.log('singleDefDocumentWithFragments definitions:', singleDefDocumentWithFragments.definitions.length);
+                    console.log('  - Main definition:', singleDefDocumentWithFragments.definitions[0].kind);
+                    console.log('  - External fragments added:', singleDefDocumentWithFragments.definitions.slice(1).map((d) => d.name.value));
+                }
+                /**
+                 * CREATE GENERATION ARTIFACT
+                 *
+                 * Each artifact represents one output file with its configuration.
+                 * The codegen core will process each artifact through the plugin pipeline.
+                 */
                 artifacts.push({
                     ...options,
                     filename,
@@ -287,7 +428,7 @@ exports.preset = {
                     schema: options.schema,
                     schemaAst: schemaObject,
                     skipDocumentsValidation: typeof options.config.skipDocumentsValidation === 'undefined'
-                        ? { skipDuplicateValidation: true }
+                        ? { skipDuplicateValidation: true } // Skip duplicate validation by default
                         : options.config.skipDocumentsValidation,
                 });
             }

package/esm/index.js

@@ -20,97 +20,178 @@ function extractDefinitions(document) {
     return definitions;
 }
 /**
- * Check if a document actually needs type imports from the schema.
- * Only returns true if the document uses:
- * - Enums
- * - Custom scalars that aren't mapped to primitives
- * - Input types (in variables)
+ * Finds "local" fragments - fragments defined in the same source file as the current definition.
+ * These are initially local but become external after we split the file per-operation.
  *
- * Does NOT return true for just referencing object types.
+ * Example:
+ * Source file has: query MyQuery { ...MyFragment } + fragment MyFragment { ... }
+ * After split: MyQuery.ts needs to import from MyFragment.ts
+ */
+function findLocalFragments(allDefinitions, currentDefinitionName) {
+    return allDefinitions
+        .filter(d => d.definition.kind === Kind.FRAGMENT_DEFINITION &&
+        d.name !== currentDefinitionName)
+        .map(d => d.definition);
+}
+/**
+ * Creates LoadedFragment objects for local fragments so they can be treated as external fragments
+ * during code generation. This ensures proper validation and type generation.
+ */
+function createLoadedFragments(fragments) {
+    return fragments.map(frag => ({
+        level: 0,
+        isExternal: true,
+        name: frag.name.value,
+        onType: frag.typeCondition.name.value,
+        node: frag,
+    }));
+}
+/**
+ * Creates fragment import declarations for local fragments.
+ * After splitting, these fragments will be in separate files, so we need to generate imports.
+ *
+ * Example: query references RetailerServicesData → import from './RetailerServicesData.ts'
+ */
+function createLocalFragmentImports(localFragments, sourceLocation, currentFilename, folder, extension, options) {
+    return localFragments.map((frag) => {
+        var _a;
+        const fragmentFilePath = generateOperationFilePath(sourceLocation, frag.name.value, folder, extension);
+        // Generate import identifiers: both the document (for runtime) and type (for TypeScript)
+        const identifiers = [
+            {
+                name: `${frag.name.value}FragmentDoc`,
+                kind: 'document',
+            },
+            {
+                name: `${frag.name.value}Fragment`,
+                kind: 'type',
+            },
+        ];
+        return {
+            baseDir: options.baseDir,
+            baseOutputDir: options.baseOutputDir,
+            outputPath: currentFilename,
+            importSource: {
+                path: fragmentFilePath,
+                identifiers,
+            },
+            emitLegacyCommonJSImports: options.emitLegacyCommonJSImports,
+            importExtension: options.importExtension,
+            typesImport: (_a = options.useTypeImports) !== null && _a !== void 0 ? _a : false,
+        };
+    });
+}
+/**
+ * TYPES IMPORT OPTIMIZATION
+ *
+ * Determines if `import * as Types from '...'` is actually needed for this specific operation/fragment.
+ *
+ * Background:
+ * The standard `isUsingTypes()` function is too broad - it returns true for ANY schema type reference,
+ * including object types. But object types don't need imports since they're generated inline.
+ *
+ * We ONLY need the Types import when generated code actually references the Types namespace:
+ *
+ * ✅ NEEDS IMPORT:
+ * - Operations (query/mutation/subscription) - generate `Types.Exact<{...}>` for Variables type
+ * - Enums - generate `role: Types.Role`
+ * - Custom scalars (unless mapped to primitives) - generate `date: Types.DateTime`
+ * - Input types - used in variables as `Types.MyInput`
+ *
+ * ❌ NO IMPORT NEEDED:
+ * - Fragments with only scalars/object types - no Types namespace references
+ * - Custom scalars mapped to primitives (JSON → any) - uses TypeScript primitives
+ * - Object type references (User, Product) - generated inline, not from Types
+ *
+ * This optimization reduces unnecessary imports and makes generated files cleaner.
  */
 function needsSchemaTypesImport(document, schema, config) {
     const builtInScalars = ['String', 'Int', 'Float', 'Boolean', 'ID'];
     const primitiveTypes = ['any', 'string', 'number', 'boolean', 'null', 'undefined', 'void', 'never', 'unknown'];
     let needsImport = false;
-    // Get scalar mappings from config
     const scalarMappings = config.scalars || {};
-    // Check if document has an operation definition
-    // ALL operations (query/mutation/subscription) generate a Variables type that uses Types.Exact
-    // even if they have no variables: Types.Exact<{ [key: string]: never; }>
+    /**
+     * STEP 1: Check for operations (queries/mutations/subscriptions)
+     * All operations generate a Variables type that uses Types.Exact, even without variables:
+     * `export type MyQueryVariables = Types.Exact<{ [key: string]: never; }>;`
+     */
     let hasOperation = false;
-    // Collect all type names referenced in the document
     const referencedTypeNames = new Set();
     visit(document, {
-        // Operations always need Types import for their Variables type
         OperationDefinition: () => {
             hasOperation = true;
         },
-        // Check variable types for input types or custom scalars
         VariableDefinition: (node) => {
             const typeName = getBaseTypeName(node.type);
             referencedTypeNames.add(typeName);
         },
-        // Collect fragment type conditions
         FragmentDefinition: (node) => {
             referencedTypeNames.add(node.typeCondition.name.value);
         },
     });
-    // All operations generate Variables type that uses Types.Exact
     if (hasOperation) {
         return true;
     }
-    // Helper to recursively check if a type needs importing
+    /**
+     * STEP 2: Check if any schema types actually need importing
+     *
+     * Helper that checks if a GraphQL type requires an import from Types namespace.
+     * Returns true only for enums, custom scalars (unless mapped to primitives), and input types.
+     */
     const checkType = (type) => {
         if (!type)
             return false;
-        // Unwrap lists and non-null
+        // Unwrap wrapper types (List, NonNull)
         while ('ofType' in type && type.ofType) {
             type = type.ofType;
         }
-        // Enums always need to be imported
+        // Enums always need import: `role: Types.Role`
         if (isEnumType(type)) {
             return true;
         }
-        // Custom scalars need to be imported UNLESS mapped to primitives
+        // Custom scalars - depends on mapping
         if (isScalarType(type) && !builtInScalars.includes(type.name)) {
-            // Check if this scalar is mapped to a primitive type
             const mapping = scalarMappings[type.name];
-            if (mapping) {
-                // If mapped to a primitive type string, no import needed
-                if (typeof mapping === 'string' && primitiveTypes.includes(mapping)) {
-                    return false;
-                }
-                // If mapped to an object like { input: 'any', output: 'any' }, check both
-                if (typeof mapping === 'object') {
-                    const inputMapping = mapping.input || mapping.output;
-                    const outputMapping = mapping.output || mapping.input;
-                    if (primitiveTypes.includes(inputMapping) && primitiveTypes.includes(outputMapping)) {
-                        return false;
-                    }
-                }
+            // No mapping = defaults to 'any' = no import needed
+            if (!mapping) {
+                return false;
             }
-            else {
-                // No mapping specified, defaults to 'any', so no import needed
+            // Mapped to primitive (string, any, number, etc.) = no import needed
+            if (typeof mapping === 'string' && primitiveTypes.includes(mapping)) {
                 return false;
             }
-            // Scalar is mapped to something non-primitive, needs import
+            // Mapped to object with input/output
+            if (typeof mapping === 'object') {
+                const inputMapping = mapping.input || mapping.output;
+                const outputMapping = mapping.output || mapping.input;
+                if (primitiveTypes.includes(inputMapping) && primitiveTypes.includes(outputMapping)) {
+                    return false;
+                }
+            }
+            // Scalar mapped to custom type (e.g., Date) = needs import
             return true;
         }
-        // Input types need to be imported
+        // Input types always need import: `input: Types.MyInput`
         if (isInputObjectType(type)) {
             return true;
         }
         return false;
     };
-    // Check variable types
+    /**
+     * STEP 3: Check variable types
+     * Variables can use enums, input types, or custom scalars directly
+     */
     for (const typeName of referencedTypeNames) {
         const type = schema.getType(typeName);
         if (checkType(type)) {
             return true;
         }
     }
-    // Now we need to check all fields in the document to see if any return enums/custom scalars
-    // We'll do a more thorough traversal with TypeInfo
+    /**
+     * STEP 4: Check field return types
+     * Use TypeInfo to properly resolve field types through the schema.
+     * This catches cases like: user { role } where 'role' returns an enum.
+     */
     const typeInfo = new TypeInfo(schema);
     visit(document, visitWithTypeInfo(typeInfo, {
         Field: () => {
@@ -134,12 +215,28 @@ function getBaseTypeName(type) {
     }
     return '';
 }
+/**
+ * PER-OPERATION-FILE PRESET
+ *
+ * Generates ONE FILE PER OPERATION/FRAGMENT instead of one file per source file.
+ *
+ * Architecture:
+ * 1. Fragment Resolution: Analyze all documents to build fragment registry and dependencies
+ * 2. Document Splitting: Split each source document into separate operations/fragments
+ * 3. Local Fragment Handling: Treat same-file fragments as external after splitting
+ * 4. Import Optimization: Only add Types import when actually needed (enums, scalars, operations)
+ *
+ * Example:
+ * Input:  src/user.ts with query GetUser + fragment UserFields
+ * Output: src/__generated__/GetUser.ts + src/__generated__/UserFields.ts
+ */
 export const preset = {
     buildGeneratesSection: options => {
         var _a, _b;
         const schemaObject = options.schemaAst
             ? options.schemaAst
             : buildASTSchema(options.schema, options.config);
+        // Extract configuration with defaults
         const baseDir = options.presetConfig.cwd || process.cwd();
         const extension = options.presetConfig.extension || '.ts';
         const folder = options.presetConfig.folder || '__generated__';
@@ -153,8 +250,13 @@ export const preset = {
             ...options.pluginMap,
             add: addPlugin,
         };
-        // Resolve fragment dependencies using our adapted fragment resolver
-        // Fragment paths will be generated based on fragment names
+        /**
+         * PHASE 1: FRAGMENT RESOLUTION
+         *
+         * Analyze all documents to build fragment registry and resolve dependencies.
+         * This uses our adapted fragment-resolver that generates paths based on fragment NAMES
+         * (not source file names), enabling proper imports after splitting.
+         */
         const sources = resolveDocumentImports(options, schemaObject, {
             baseDir,
             folder,
@@ -166,75 +268,77 @@ export const preset = {
             typesImport: (_a = options.config.useTypeImports) !== null && _a !== void 0 ? _a : false,
         }, getConfigValue(options.config.dedupeFragments, false));
         const artifacts = [];
-        // Now split each source into separate files per operation/fragment
+        /**
+         * MAIN SPLITTING LOGIC
+         *
+         * For each source document (input file), we:
+         * 1. Extract all operations and fragments
+         * 2. Create a separate output file for EACH operation/fragment
+         * 3. Handle fragment dependencies (both external and local)
+         */
         for (const source of sources) {
             const definitions = extractDefinitions(source.documents[0].document);
+            // Process each operation/fragment definition separately
             for (const { name, definition } of definitions) {
+                // Generate output file path: sourceDir/folder/OperationName.extension
                 const filename = generateOperationFilePath(source.documents[0].location, name, folder, extension);
-                // Create a document with just this operation/fragment
+                // Create a document with ONLY this single definition
                 const singleDefDocument = {
                     kind: Kind.DOCUMENT,
                     definitions: [definition],
                 };
+                // Note: Initially create source with just the single definition
+                // We'll update it later to include external fragments
                 const singleDefSource = {
-                    rawSDL: source.documents[0].rawSDL, // TODO: might need to filter this
-                    document: singleDefDocument,
+                    rawSDL: source.documents[0].rawSDL, // Contains all original SDL (not filtered)
+                    document: singleDefDocument, // Initially just this one definition
                     location: source.documents[0].location,
                 };
-                // Find other fragments in the same source file (they are "local" now but will be "external" after split)
-                const localFragments = definitions
-                    .filter(d => d.definition.kind === Kind.FRAGMENT_DEFINITION && d.name !== name)
-                    .map(d => d.definition);
-                // Add local fragments to external fragments list so they're available during generation
-                const localFragmentNodes = localFragments.map(frag => ({
-                    level: 0,
-                    isExternal: true,
-                    name: frag.name.value,
-                    onType: frag.typeCondition.name.value,
-                    node: frag,
-                }));
+                /**
+                 * HANDLE LOCAL FRAGMENTS
+                 *
+                 * Problem: If source file has both query + fragment in same gql template:
+                 *   gql`query MyQuery { ...MyFrag } fragment MyFrag { ... }`
+                 *
+                 * After splitting, MyQuery needs to import from MyFrag.ts, but fragment
+                 * resolver marked MyFrag as "local" (same document).
+                 *
+                 * Solution: Treat local fragments as external after splitting.
+                 */
+                const localFragments = findLocalFragments(definitions, name);
+                const localFragmentNodes = createLoadedFragments(localFragments);
+                // Combine external fragments (from other files) + local fragments (same source file)
                 const allExternalFragments = [
                     ...source.externalFragments,
                     ...localFragmentNodes,
                 ];
-                // Update fragment imports to use the correct output path for this operation
+                /**
+                 * UPDATE FRAGMENT IMPORTS
+                 *
+                 * 1. External fragments: Update outputPath to this operation's file
+                 * 2. Local fragments: Generate new imports pointing to their split files
+                 */
                 const updatedFragmentImports = source.fragmentImports.map(fragmentImport => ({
                     ...fragmentImport,
-                    outputPath: filename, // Update to actual output path
+                    outputPath: filename,
                 }));
-                // Generate fragment imports for local fragments (they'll be in separate files after splitting)
-                const localFragmentImports = localFragments.map((frag) => {
-                    var _a;
-                    const fragmentFilePath = generateOperationFilePath(source.documents[0].location, frag.name.value, folder, extension);
-                    // Get fragment import identifiers (document + type)
-                    const identifiers = [
-                        {
-                            name: `${frag.name.value}FragmentDoc`,
-                            kind: 'document',
-                        },
-                        {
-                            name: `${frag.name.value}Fragment`,
-                            kind: 'type',
-                        },
-                    ];
-                    return {
-                        baseDir,
-                        baseOutputDir: options.baseOutputDir,
-                        outputPath: filename,
-                        importSource: {
-                            path: fragmentFilePath,
-                            identifiers,
-                        },
-                        emitLegacyCommonJSImports: options.config.emitLegacyCommonJSImports,
-                        importExtension: options.config.importExtension,
-                        typesImport: (_a = options.config.useTypeImports) !== null && _a !== void 0 ? _a : false,
-                    };
+                const localFragmentImports = createLocalFragmentImports(localFragments, source.documents[0].location, filename, folder, extension, {
+                    baseDir,
+                    baseOutputDir: options.baseOutputDir,
+                    emitLegacyCommonJSImports: options.config.emitLegacyCommonJSImports,
+                    importExtension: options.config.importExtension,
+                    useTypeImports: options.config.useTypeImports,
                 });
                 const allFragmentImports = [
                     ...updatedFragmentImports,
                     ...localFragmentImports,
                 ];
-                // Check if THIS specific operation uses types (not the whole source file)
+                /**
+                 * ADD EXTERNAL FRAGMENTS TO DOCUMENT
+                 *
+                 * The plugin needs external fragment definitions in the document to properly resolve types.
+                 * Without these, fragment spreads can't be expanded correctly.
+                 */
                 const singleDefDocumentWithFragments = {
                     ...singleDefDocument,
                     definitions: [
@@ -242,8 +346,21 @@ export const preset = {
                         ...allExternalFragments.map(fragment => fragment.node),
                     ],
                 };
+                // Update the source to use the document with external fragments
+                singleDefSource.document = singleDefDocumentWithFragments;
+                /**
+                 * CHECK IF TYPES IMPORT IS NEEDED
+                 *
+                 * We only add `import * as Types from '...'` if the operation actually uses:
+                 * - Enums (e.g., Role.ADMIN)
+                 * - Custom scalars mapped to non-primitives
+                 * - Input types (in variables)
+                 * - Operations (all operations generate Variables type using Types.Exact)
+                 *
+                 * We DON'T import for just object type references (e.g., fragment on User)
+                 */
                 const needsTypesImport = needsSchemaTypesImport(singleDefDocumentWithFragments, schemaObject, options.config);
-                // Generate the types import statement if needed
+                // Generate the schema types import statement if needed
                 const importStatements = [];
                 if (needsTypesImport && !options.config.globalNamespace) {
                     const schemaTypesImportStatement = generateImportStatement({
@@ -260,6 +377,13 @@ export const preset = {
                     });
                     importStatements.push(schemaTypesImportStatement);
                 }
+                /**
+                 * BUILD PLUGIN CONFIGURATION
+                 *
+                 * Plugins are processed in order:
+                 * 1. 'add' plugin - adds import statements
+                 * 2. User plugins - generate actual operation code (typescript-operations, etc.)
+                 */
                 const plugins = [
                     ...importStatements.map(importStatement => ({
                         add: { content: importStatement },
@@ -270,9 +394,26 @@ export const preset = {
                     ...options.config,
                     exportFragmentSpreadSubTypes: true,
                     namespacedImportName: importTypesNamespace,
-                    externalFragments: allExternalFragments,
-                    fragmentImports: allFragmentImports,
+                    externalFragments: allExternalFragments, // Includes both external + local fragments
+                    fragmentImports: allFragmentImports, // Import declarations for all fragments
                 };
+                // DEBUG: Log fragment generation details
+                if (name === 'Items_item') {
+                    console.log('\n=== GENERATING Items_item ===');
+                    console.log('External fragments:', allExternalFragments.map(f => ({ name: f.name, level: f.level })));
+                    console.log('Fragment imports:', allFragmentImports.map(fi => fi.importSource.path));
+                    console.log('Document selections:', definition.selectionSet.selections.map((s) => s.kind === 'Field' ? s.name.value : `...${s.name.value}`));
+                    console.log('Document definitions (should be 1):', singleDefDocument.definitions.length);
+                    console.log('singleDefDocumentWithFragments definitions:', singleDefDocumentWithFragments.definitions.length);
+                    console.log('  - Main definition:', singleDefDocumentWithFragments.definitions[0].kind);
+                    console.log('  - External fragments added:', singleDefDocumentWithFragments.definitions.slice(1).map((d) => d.name.value));
+                }
+                /**
+                 * CREATE GENERATION ARTIFACT
+                 *
+                 * Each artifact represents one output file with its configuration.
+                 * The codegen core will process each artifact through the plugin pipeline.
+                 */
                 artifacts.push({
                     ...options,
                     filename,
@@ -283,7 +424,7 @@ export const preset = {
                     schema: options.schema,
                     schemaAst: schemaObject,
                     skipDocumentsValidation: typeof options.config.skipDocumentsValidation === 'undefined'
-                        ? { skipDuplicateValidation: true }
+                        ? { skipDuplicateValidation: true } // Skip duplicate validation by default
                         : options.config.skipDocumentsValidation,
                 });
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nmarks/graphql-codegen-per-operation-file-preset",
-  "version": "1.0.6",
+  "version": "1.0.7",
   "description": "GraphQL Code Generator preset for generating one file per operation/fragment",
   "peerDependencies": {
     "graphql": "^0.8.0 || ^0.9.0 || ^0.10.0 || ^0.11.0 || ^0.12.0 || ^0.13.0 || ^14.0.0 || ^15.0.0 || ^16.0.0"

package/typings/index.d.cts

@@ -127,5 +127,20 @@ export type PerOperationFileConfig = {
      */
     importTypesNamespace?: string;
 };
+/**
+ * PER-OPERATION-FILE PRESET
+ *
+ * Generates ONE FILE PER OPERATION/FRAGMENT instead of one file per source file.
+ *
+ * Architecture:
+ * 1. Fragment Resolution: Analyze all documents to build fragment registry and dependencies
+ * 2. Document Splitting: Split each source document into separate operations/fragments
+ * 3. Local Fragment Handling: Treat same-file fragments as external after splitting
+ * 4. Import Optimization: Only add Types import when actually needed (enums, scalars, operations)
+ *
+ * Example:
+ * Input:  src/user.ts with query GetUser + fragment UserFields
+ * Output: src/__generated__/GetUser.ts + src/__generated__/UserFields.ts
+ */
 export declare const preset: Types.OutputPreset<PerOperationFileConfig>;
 export default preset;

package/typings/index.d.ts

@@ -127,5 +127,20 @@ export type PerOperationFileConfig = {
      */
     importTypesNamespace?: string;
 };
+/**
+ * PER-OPERATION-FILE PRESET
+ *
+ * Generates ONE FILE PER OPERATION/FRAGMENT instead of one file per source file.
+ *
+ * Architecture:
+ * 1. Fragment Resolution: Analyze all documents to build fragment registry and dependencies
+ * 2. Document Splitting: Split each source document into separate operations/fragments
+ * 3. Local Fragment Handling: Treat same-file fragments as external after splitting
+ * 4. Import Optimization: Only add Types import when actually needed (enums, scalars, operations)
+ *
+ * Example:
+ * Input:  src/user.ts with query GetUser + fragment UserFields
+ * Output: src/__generated__/GetUser.ts + src/__generated__/UserFields.ts
+ */
 export declare const preset: Types.OutputPreset<PerOperationFileConfig>;
 export default preset;