feat: implement custom resolver interface v3

[SukkaW]

The PR implements the new resolver design I proposed in #40 (comment)

---

For eslint-plugin-import-x users

Like the ESLint flat config allows you to use any js objects (e.g. import and require) as ESLint plugins, the new eslint-plugin-import-x resolver settings allow you to use js objects as custom resolvers through the new setting import-x/resolver-next:

// eslint.config.js
import { createTsResolver } from '#custom-resolver';
const { createOxcResolver } = require('path/to/a/custom/resolver');

const nodeResolverObject = {
  interfaceVersion: 3,
  name: 'my-custom-eslint-import-resolver',
  resolve(modPath, sourcePath) {
  };
};

module.exports = {
  settings: {
    // multiple resolvers
    'import-x/resolver-next': [
      nodeResolverObject,
      createTsResolver(enhancedResolverOptions),
      createOxcResolver(oxcOptions),
    ],
    // single resolver:
    'import-x/resolver-next': [createOxcResolver(oxcOptions)]
  }
}

The new import-x/resolver-next no longer accepts strings as the resolver, thus will not be compatible with the ESLint legacy config (a.k.a. .eslintrc). Those who are still using the ESLint legacy config should stick with import-x/resolver.

In the next major version of eslint-plugin-import-x (v5), we will rename the currently existing import-x/resolver to import-x/resolver-legacy (which still allows the existing ESLint legacy config users to use their existing resolver settings), and import-x/resolver-next will become the new import-x/resolver. When ESLint v9 (the last ESLint version with ESLint legacy config support) reaches EOL in the future, we will remove import-x/resolver-legacy.

We have also made a few breaking changes to the new resolver API design, so you can't use existing custom resolvers directly with import-x/resolver-next:

// An example of the current `import-x/resolver` settings
module.exports = {
  settings: {
    'import-x/resolver': {
      node: nodeResolverOpt
      webpack: webpackResolverOpt,
      'custom-resolver': customResolverOpt
    }
  }
}

// When migrating to `import-x/resolver-next`, you CAN'T use legacy versions of resolvers directly:
module.exports = {
  settings: {
    // THIS WON'T WORK, the resolver interface required for `import-x/resolver-next` is different.
    'import-x/resolver-next': [
       require('eslint-import-resolver-node'),
       require('eslint-import-resolver-webpack'),
       require('some-custom-resolver')
    ];
  }
}

For easier migration, the PR also introduces a compat utility importXResolverCompat that you can use in your eslint.config.js:

// eslint.config.js
import eslintPluginImportX, { importXResolverCompat } from 'eslint-plugin-import-x';
// or
const eslintPluginImportX = require('eslint-plugin-import-x');
const { importXResolverCompat } = eslintPluginImportX;

module.exports = {
  settings: {
    // THIS WILL WORK as you have wrapped the previous version of resolvers with the `importXResolverCompat`
    'import-x/resolver-next': [
       importXResolverCompat(require('eslint-import-resolver-node'), nodeResolveOptions),
       importXResolverCompat(require('eslint-import-resolver-webpack'), webpackResolveOptions),
       importXResolverCompat(require('some-custom-resolver'), {})
    ];
  }
}

---

For custom import resolver developers

This is the new API design of the resolver interface:

export interface NewResolver {
  interfaceVersion: 3,
  name?: string, // This will be included in the debug log
  resolve: (modulePath: string, sourceFile: string) => ResolvedResult
}

// The `ResultNotFound` (returned when not resolved) is the same, no changes
export interface ResultNotFound {
  found: false
  path?: undefined
}

// The `ResultFound` (returned resolve result) is also the same, no changes
export interface ResultFound {
  found: true
  path: string | null
}

export type ResolvedResult = ResultNotFound | ResultFound

You will be able to import NewResolver from eslint-plugin-import-x/types.

The most notable change is that eslint-plugin-import-x no longer passes the third argument (options) to the resolve function.

We encourage custom resolvers' authors to consume the options outside the actual resolve function implementation. You can export a factory function to accept the options, this factory function will then be called inside the eslint.config.js to get the actual resolver:

// custom-resolver.js
exports.createCustomResolver = (options) => {
  // The options are consumed outside the `resolve` function.
  const resolverInstance = new ResolverFactory(options);

  return {
    name: 'custom-resolver',
    interfaceVersion: 3,
    resolve(mod, source) {
      const found = resolverInstance.resolve(mod, {});

      // Of course, you still have access to the `options` variable here inside
      // the `resolve` function. That's the power of JavaScript Closures~
    }
  }
};

// eslint.config.js
const { createCustomResolver } = require('custom-resolver')

module.exports = {
  settings: {
    'import-x/resolver-next': [
       createCustomResolver(options)
    ];
  }
}

This allows you to create a reusable resolver instance to improve the performance. With the existing version of the resolver interface, because the options are passed to the resolver function, you will have to create a resolver instance every time the resolve function is called:

module.exports = {
  interfaceVersion: 2,
  resolve(mod, source) {
    // every time the `resolve` function is called, a new instance is created
    // This is very slow
    const resolverInstance = ResolverFactory.createResolver({});
    const found = resolverInstance.resolve(mod, {});
  }
}

With the factory function pattern, you can create a resolver instance beforehand:

exports.createCustomResolver = (options) => {
  // `enhance-resolve` allows you to create a reusable instance:
  const resolverInstance = ResolverFactory.createResolver({});
  const resolverInstance = enhanceResolve.create({});

  // `oxc-resolver` also allows you to create a reusable instance:
  const resolverInstance = new ResolverFactory({});

  return {
    name: 'custom-resolver',
    interfaceVersion: 3,
    resolve(mod, source) {
      // the same re-usable instance is shared across `resolve` invocations.
      // more performant
      const found = resolverInstance.resolve(mod, {});
    }
  }
};

You can make your resolver implements both legacy resolver interface and new resolver interface:

module.exports = {
  // interface version 2
  interfaceVersion: 2,
  resolve(mod, source) {
  },
  // interface version 3
  createCustomResolver(options) {
    // do something w/ options
    return {
      name: 'custom-resolver',
      interfaceVersion: 3,
      resolve(mod, source) {
        // the same re-usable instance is shared across `resolve` invocations.
        // more performant
        const found = resolverInstance.resolve(mod, {});
      }
    }
  } 
}

[changeset-bot]

🦋 Changeset detected

Latest commit: e03e3de

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[codesandbox-ci]

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

[SukkaW]

Custom resolvers adoption status:

• @9romise (eslint-import-resolver-oxc) feat: implement interface version 3 9romise/eslint-import-resolver-oxc#41
• @riywo (eslint-import-resolver-typescript-bun)
• @pzmosquito (eslint-import-resolver-vite) implements import-x resolver interface version 3 pzmosquito/eslint-import-resolver-vite#26
• @dmail (@jsenv/importmap-eslint-resolver)
• @kuoruan (eslint-import-resolver-next)
• @thepassle (eslint-plugin-import-exports-imports-resolver)
• @redabacha (eslint-import-resolver-deno)
• @romanlex (eslint-import-resolver-x) Add v3 resolver interface helljs/eslint-import-resolver-x#2
• @SukkaW [myself] (eslint-import-resolver-typescript) feat: implement import-x resolver interface v3 import-js/eslint-import-resolver-typescript#326

I'd also like to here your ideas about new resolver design for eslint-plugin-import-x~

[romanlex]

@SukkaW
If I understood correctly
helljs/eslint-import-resolver-x#2

[romanlex]

@SukkaW done

[kuoruan]

Hi @SukkaW Can the resolve function return a promise? so that I can use import() function in the resolver to read some config files.

[SukkaW]

Hi @SukkaW Can the resolve function return a promise? so that I can use import() function in the resolver to read some config files.

Currently, it is still impossible: ESLint requires rules to be synchronous, and we must run the resolver within the rules because only there can we identify imports from the AST, which we then invoke the resolver on.

If the config file is in cloneable format (JSON, JSON5, JSONC, etc.), you can check out synckit. This is a library made by @JounQin that runs async functions in a worker_threads while blocking the main thread, then returning the result back to the main thread.

[pzmosquito]

It looks like this change will not be compatible with original the eslint-plugin-import package, which uses interface v2, right?

[SukkaW]

It looks like this change will not be compatible with original the eslint-plugin-import package, which uses interface v2, right?

Yeah. So to retain compatibility with the eslint-plugin-import, the default export of the import resolver module should still be interface v2.

[romanlex]

The interface of version 3 does not take into account one point in the monorepository.
For example project structure:

client
   src
      core
      // etc
      packages
         PackageA
            .eslintrc
   .eslintrc

If codebase use js and ts at the same time and .eslintrc on root and on package have different settings of resolver
For example root eslintrc:

settings: {
    'import/resolver': {
      [require.resolve('@helljs/eslint-import-resolver-x')]: {
        project: ['jsconfig?(.*).json', '*/packages/*/jsconfig?(.*).json', '*/jsconfig?(.*).json'],
        extensions: ['.js', '.jsx', '.mjs', '.cjs', '.json', '.flow', '.ts', '.tsx', '.d.ts'],
      },
    },
  },

and PackageA eslintrc:

settings = {
  'import/resolver': {
    [require.resolve('@helljs/eslint-import-resolver-x')]: {
      alwaysTryTypes: true,
      project: ['tsconfig?(.*).json', '*/packages/*/tsconfig?(.*).json', '*/tsconfig?(.*).json'],
      extensions: ['.ts', '.tsx', '.d.ts', '.js', '.jsx', '.mjs', '.cjs', '.json'],
    },
  },
}

and we must be able to resolve modules REGARDLESS of where eslint was launched from, i.e. we accept as a requirement that eslint must equally be able to resolve when linting at the package level or at the root level

then in the old interface, the resolve function always accepted the current resolver settings from the import plugin for the current file as an argument and we can use for example digest of options for cache mappers functions

I fixed this for myself by caching mappers based on the digest of the resolver settings object, but I can't imagine how this can be fixed in the v3 interface
helljs/eslint-import-resolver-x@b23ec50

[SukkaW]

I fixed this for myself by caching mappers based on the digest of the resolver settings object, but I can't imagine how this can be fixed in the v3 interface

@romanlex

If I understand correctly, in the previous version of the import resolver interface, there was only one active resolver that received two different options from two eslintrc files. Since there is only one resolver, you will have to do a module-scope singleton "global" cache:

let previousDigestHash;
let cachedGlobalSingleton = new DummyExample();

const resolve = (source, parent, options) => {
  const digest = hash(options);
};

But with the interface version 3 and eslint.config.js, you can create two resolvers (one per eslint.config.js), and you can make them completely separated:

const createResolver = (options) => {
  const internalInstance = new DummyExample();
  // one internalInstance per `createResolver()` call.
  // only belong to its scope, not shared with other resolvers.

  const resolve = (source, parent) => {
  };
}

With that, both eslint.config.js files will initiate their own createResolver(), so there will be two internalInstance (one per eslint.config.js), and each belongs to their own createResolver scope, not shared! In fact, since you no longer rely on module-scope variables to store the instance, you don't even have to do digest anymore! And that's the primary reason why I push the interface version 3 in the first place.

[romanlex]

It is reasonable, I did not think that it is possible to create several revolvers at the same time
thx