filing-cabinet

Get the file associated with a dependency/partial's path

npm install filing-cabinet

Usage

const cabinet = require('filing-cabinet');

const result = cabinet({
  partial: 'somePartialPath',
  directory: 'path/to/all/files',
  filename: 'path/to/parent/file',
  ast: {}, // an optional AST representation of `filename`
  // Only for JavaScript files
  config: 'path/to/requirejs/config',
  webpackConfig: 'path/to/webpack/config',
  // Node modules entry resolution:
  // - As an object: choose which package.json field to use as entry instead of "main"
  nodeModulesConfig: {
    entry: 'module'
  },
  // - Or as a function: fully custom package.json transformer (resolve's packageFilter)
  //   nodeModulesConfig: (pkg) => {
  //     // Example: prefer "module" and fallback to "main"
  //     pkg.main = pkg.module ?? pkg.main;
  //     return pkg;
  //   },
  tsConfig: 'path/to/tsconfig.json', // or an object
  tsConfigPath: 'path/to/tsconfig.json'
});

console.log(result); // /absolute/path/to/somePartialPath

• partial: the dependency path
  • This could be in any of the registered languages
• directory: the path to all files
• filename: the path to the file containing the partial
• ast: (optional) the parsed AST for filename.
  • Useful optimization for avoiding a parse of filename
• config: (optional) requirejs config for resolving aliased JavaScript modules
• webpackConfig: (optional) Webpack config for resolving aliased JavaScript modules. If exporting multiple configurations, the first configuration is used.
• nodeModulesConfig: (optional) configuration to choose the entry file when resolving packages from node_modules.
  • You can pass an object like { entry: 'module' } — in this case the entry field replaces main in the target package's package.json (for example, to select the ESM entry via the module field).
  • Or you can pass a function — a custom packageFilter from the resolve package. The function receives the package.json object (pkg), may mutate it (e.g., set pkg.main), and must return the object. This gives you full control over how the entry file is selected.
• tsConfig: (optional) path to a TypeScript configuration. Could also be an object representing a pre-parsed TypeScript config.
• tsConfigPath: (optional) A (virtual) path to TypeScript config file when tsConfig option is given as an object, not a string. Needed to calculate Path Mapping. If not given when tsConfig is an object, Path Mapping is ignored. This is not need when tsConfig is given as string (path to the tsconfig file).
• noTypeDefinitions: (optional) For TypeScript files, whether to prefer *.js over *.d.ts.

Registered languages

By default, filing-cabinet provides support for the following languages:

• JavaScript: CommonJS, AMD, ES6
• TypeScript
• CSS Preprocessors: Sass (.scss and .sass), Stylus (.styl), and Less (.less)
• Svelte
• Vue

You can register resolvers for new languages via cabinet.register(extension, resolver).

• extension: the extension of the file that should use the custom resolver (ex: '.py', '.php')
• resolver: a function that accepts the following (ordered) arguments that were given to cabinet:
  • partial
  • filename
  • directory
  • config

For examples of resolver implementations, take a look at the default language resolvers:

• sass-lookup
• stylus-lookup
• amdLookup

If a given extension does not have a registered resolver, cabinet will use a generic file resolver which is basically require('path').join with a bit of extension defaulting logic.

CLI

Requires a global install with npm install -g filing-cabinet

filing-cabinet [options] <dependencyPath>

See filing-cabinet --help for details on the options.

License

MIT