filing-cabinet

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

Installation

npm install filing-cabinet

Quick Start

ESM

import path from 'node:path';
import { fileURLToPath } from 'node:url';
import cabinet from 'filing-cabinet';

const __dirname = path.dirname(fileURLToPath(import.meta.url));

const result = cabinet({
  // import Button from './button'
  partial: './button',
  filename: path.join(__dirname, 'src', 'app.js'),
  directory: __dirname
});

CommonJS

const { default: cabinet } = require('filing-cabinet');

Options

const result = cabinet({
  // import Button from './button'
  partial: './button',
  filename: path.join(__dirname, 'src', 'app.js'),
  directory: __dirname
});

if (result) {
  console.log(result); // -> /absolute/path/to/src/button.js
} else {
  console.error('Dependency could not be resolved');
}

API

| Member | Type | Description | | --- | --- | --- | | cabinet(options) | Function | Resolve a dependency to an absolute path | | cabinet.register(extension, resolver) | Function | Register a custom resolver for a file extension | | cabinet.unregister(extension) | Function | Remove a registered resolver | | cabinet.getLookup(extension) | Function | Get the resolver for a file extension | | cabinet.supportedFileExtensions | string[] | All currently registered file extensions |

cabinet(options: CabinetOptions)

Resolves a dependency string from the context of a file.

Returns: string - absolute path to the resolved file, or an empty string if it could not be resolved.

Options

| Option | Type | Required | Description | | --- | --- | --- | --- | | partial | string | Yes | Dependency path to resolve | | directory | string | Yes | Project root path used for resolution | | filename | string | Yes | Path to the file containing partial | | ast | Object | No | Pre-parsed AST for filename (avoids reparsing in JS module type detection) | | config | string \| Object | No | JS only. RequireJS config (path or object) for AMD resolution | | configPath | string | No | JS only. Path to the RequireJS config file when config is an object | | webpackConfig | string | No | JS only. Webpack config path for webpack-style resolution; if the config exports an array, the first config is used | | nodeModulesConfig | Object \| Function | No | Controls package entry selection when resolving from node_modules (see examples below) | | nodeModulesConfig.entry | string | No | Object form: field name to prefer instead of main (for example module) | | nodeModulesConfig (function) | Function | No | Function form: custom resolve packageFilter callback for full control of package entry selection | | tsConfig | string \| Object | No | TS only. TypeScript config path or pre-parsed config object | | tsConfigPath | string | No | TS only. (Virtual) path to tsconfig when tsConfig is an object; needed for Path Mapping | | noTypeDefinitions | boolean | No | TS only. Prefer *.js over *.d.ts when resolving TypeScript dependencies | | fileSystem | Object | No | An alternative fs implementation to use for reading tsConfigPath |

nodeModulesConfig examples

Object form - use a specific package.json field instead of main:

cabinet({
  partial: 'some-package',
  filename: '/path/to/file.js',
  directory: '/path/to',
  nodeModulesConfig: { entry: 'module' }
});

Function form - full control via a custom packageFilter:

cabinet({
  partial: 'some-package',
  filename: '/path/to/file.js',
  directory: '/path/to',
  nodeModulesConfig: (pkg) => {
    // prefer "module", fall back to "main"
    pkg.main = pkg.module ?? pkg.main;
    return pkg;
  }
});

cabinet.register(extension: string, resolver: (options: Object) => string)

Register a custom resolver for a file extension.

Parameters:

• extension (string, required) - file extension to handle (for example .py, .php)
• resolver ((options: Object) => string, required) - function that receives the same options object passed to cabinet(options) and returns a resolved absolute path or an empty string

Returns: void

cabinet.register('.py', (options) => {
  // resolve options.partial relative to options.filename
  return '/resolved/path/to/file.py';
});

For examples of resolver implementations, take a look at the built-in resolvers:

• sass-lookup
• stylus-lookup
• module-lookup-amd

If no resolver is registered for an extension, filing-cabinet falls back to a generic file resolver with extension defaulting behavior.

cabinet.unregister(extension: string)

Remove the resolver registered for extension.

Parameters:

• extension (string, required) - file extension whose resolver should be removed

Returns: void

cabinet.unregister('.py');

cabinet.getLookup(extension: string)

Return the resolver function registered for extension, or undefined if none is registered.

Parameters:

• extension (string, required) - file extension to look up

Returns: Function | undefined

const resolver = cabinet.getLookup('.ts'); // built-in TypeScript resolver

cabinet.supportedFileExtensions

A string[] of all currently registered file extensions. Updated automatically by register() and unregister().

console.log(cabinet.supportedFileExtensions);
// ['.js', '.jsx', '.less', '.sass', '.scss', '.styl', '.svelte', '.ts', '.tsx', '.vue']

Supported Languages

By default, filing-cabinet supports:

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

Package #imports Field

filing-cabinet automatically resolves Node.js package imports (dependencies starting with #) for both JavaScript and TypeScript files.

CLI

Install globally:

npm install -g filing-cabinet

Run:

filing-cabinet [options] <path>

Run filing-cabinet --help for full usage.

License

MIT