About

A module for the automatic import of files from a directory and its subdirectories (sync and async). The imported modules can be used either from the returned object or in the callback function.

Installation

npm install directory-import

After installation, you can use the module in your project:

const { directoryImport } = require('directory-import');

const importedModules = directoryImport('./path/to/directory');

// Outputs an object with imported modules
// For example: { modulePath1: module1, modulePath2: module2, ... }
console.log(importedModules);

or:

import { directoryImport } from 'directory-import';

const importedModules = directoryImport('./path/to/directory');

// Outputs an object with imported modules
// For example: { modulePath1: module1, modulePath2: module2, ... }
console.log(importedModules);

Simple usage

Here's a simple example of how to use the library and how it works under the hood:

const { directoryImport } = require('directory-import');

const importedModules = directoryImport('./sample-directory');

console.info(importedModules);

Path to directory from the GIF above

Invoking a callback on each file

This can be handy when, for instance, you need to perform a specific action based on the imported file.

const { directoryImport } = require('directory-import');

directoryImport('./sample-directory', (moduleName, modulePath, moduleData) => {
  console.info({ moduleName, modulePath, moduleData });
});

{Function} Callback properties:

| Property | Type | Description | | -------- | ------ | -------------------------------------------------------------- | | name | String | Module name based on the filename | | path | String | Relative module path | | data | String | Exported data from the module. (Ex: "module.exports = 'test'") | | index | Number | Index of the imported module |

{Object} Options properties:

| Property | Type | Description | | --------------------- | ------- | --------------------------------------------------------------- | | includeSubdirectories | Boolean | If true, the module will import files from subdirectories | | targetDirectoryPath | String | The path to the directory from which modules are to be imported | | importPattern | RegExp | RegExp pattern to filter files | | importMode | String | The import mode. Can be 'sync' or 'async' | | limit | Number | Limit the number of imported modules | | forceReload | Boolean | If true, reload modules disabling require cache |

back to top

More examples:

Minimum code needed for use:

const { directoryImport } = require('directory-import');

// Synchronously imports all modules in the same directory from which the code was called
directoryImport();

Asynchronously import files from the specified directory:

const { directoryImport } = require('directory-import');

const result = directoryImport('./path/to/directory', 'async');

// Promise { <pending> }
console.log(result);

Put the result in a variable and invoke a callback on each file:

const { directoryImport } = require('directory-import');

const importedModules = directoryImport('./path/to/directory', (moduleName, modulePath, moduleData) => {
  // {
  //   moduleName: 'sample-file-1',
  //   modulePath: '/sample-file-1.js',
  //   moduleData: 'This is first sampleFile'
  // }
  // ...
  console.info({ moduleName, modulePath, moduleData });
});

// {
//   '/sample-file-1.js': 'This is first sampleFile',
//   ...
// }
console.info(importedModules);

back to top

Overloads:

const { directoryImport } = require('directory-import');

/**
 * Import modules from the current directory synchronously
 * @returns {Object} An object containing all imported modules.
 */
const importedModules = directoryImport();

// {
//   '/sample-file-1.js': 'This is first sampleFile',
//   ...
// }
console.log(importedModules);

const { directoryImport } = require('directory-import');

/**
 * Import modules from the current directory synchronously and call the provided callback for each imported module.
 * @param {Function} callback - The callback function to call for each imported module.
 * @returns {Object} An object containing all imported modules.
 */
directoryImport((moduleName, modulePath, moduleData) => {
  // {
  //   moduleName: 'sample-file-1',
  //   modulePath: '/sample-file-1.js',
  //   moduleData: 'This is first sampleFile'
  // }
  // ...
  console.info({ moduleName, modulePath, moduleData });
});

const { directoryImport } = require('directory-import');

/**
 * Import modules from the specified directory synchronously
 * @param {String} directoryPath - The path to the directory from which you want to import modules.
 * @returns {Object} An object containing all imported modules.
 */
const importedModules = directoryImport('./path/to/directory');

// {
//   '/sample-file-1.js': 'This is first sampleFile',
//   ...
// }
console.log(importedModules);

const { directoryImport } = require('directory-import');

/**
 * Import modules from the specified directory synchronously and call the provided callback for each imported module.
 * @param {String} directoryPath - The path to the directory from which you want to import modules.
 * @param {Function} callback - The callback function to call for each imported module.
 * @returns {Object} An object containing all imported modules.
 */
directoryImport('./path/to/directory', (moduleName, modulePath, moduleData) => {
  // {
  //   moduleName: 'sample-file-1',
  //   modulePath: '/sample-file-1.js',
  //   moduleData: 'This is first sampleFile'
  // }
  // ...
  console.info({ moduleName, modulePath, moduleData });
});

const { directoryImport } = require('directory-import');

/**
 * Import all modules from the specified directory synchronously or asynchronously.
 * @param {string} targetDirectoryPath - The path to the directory to import modules from.
 * @param {'sync'|'async'} mode - The import mode. Can be 'sync' or 'async'.
 * @returns {Object} An object containing all imported modules.
 */
const importModules = directoryImport('./path/to/directory', 'sync');

// {
//   '/sample-file-1.js': 'This is first sampleFile',
//   ...
// }
console.log(importedModules);

const { directoryImport } = require('directory-import');

/**
 * Import all modules from the specified directory synchronously or asynchronously and call the provided callback for each imported module.
 * @param {string} targetDirectoryPath - The path to the directory to import modules from.
 * @param {'sync'|'async'} mode - The import mode. Can be 'sync' or 'async'.
 * @param {Function} callback - The callback function to call for each imported module.
 * @returns {Object} An object containing all imported modules.
 */
directoryImport('./path/to/directory', 'sync', (moduleName, modulePath, moduleData) => {
  // {
  //   moduleName: 'sample-file-1',
  //   modulePath: '/sample-file-1.js',
  //   moduleData: 'This is first sampleFile'
  // }
  // ...
  console.info({ moduleName, modulePath, moduleData });
});

const { directoryImport } = require('directory-import');

const options = {
  includeSubdirectories: true,
  targetDirectoryPath: './path/to/directory',
  importPattern: /\.js/,
  importMode: 'sync',
  limit: 2,
};

/**
 * Import all modules from the specified directory
 * @param {Object} targetDirectoryPath - options - The options object.
 * @returns {Object} An object containing all imported modules.
 */
const importModules = directoryImport(options);

// {
//   '/sample-file-1.js': 'This is first sampleFile',
//   ...
// }
console.log(importedModules);

const { directoryImport } = require('directory-import');

const options = {
  includeSubdirectories: true,
  targetDirectoryPath: './path/to/directory',
  importPattern: /\.js/,
  importMode: 'sync',
  limit: 2,
};

/**
 * Import all modules from the specified directory and call the provided callback for each imported module.
 * @param {Object} targetDirectoryPath - options - The options object.
 * @param {Function} callback - The callback function to call for each imported module.
 * @returns {Object} An object containing all imported modules.
 */
directoryImport(options, (moduleName, modulePath, moduleData) => {
  // {
  //   moduleName: 'sample-file-1',
  //   modulePath: '/sample-file-1.js',
  //   moduleData: 'This is first sampleFile'
  // }
  // ...
  console.info({ moduleName, modulePath, moduleData });
});

back to top

Change Log

[3.3.2] - 2024-12-25

Added

• Add forceReload option.

[3.3.1] - 2024-03-27

Fixed

• Now module can work with windows operating system!
• Enhance path handling and regular expressions for robustness

[3.2.1] - 2024-01-25

Fixed

• Fixed a problem where the callerFilePath option was not working as expected for node.js versions greater than 20.

[3.1.1] - 2023-11-17

Added

• .mjs files are supported now.

Fixed

• options.callerFilePath now returns the correct path to the file from which the function was called.
• Declaration files are no longer imported.
• Other minor fixes.

[3.0.0] - 2023-07-29

Added

• Added tests to increase code reliability and stability.
• Implemented function overloads for enhanced flexibility and usage
• Backward compatibility with older versions has been ensured to ease user migration.

Changed

• The entire project code has been rewritten in TypeScript for readabilit, reliability, and ease of maintenance.

Fixed

• All known bugs identified in the previous version have been fixed.

Removed

• All third-party dependencies have been removed to reduce the package size and increase performance.

Contribution

Contributions to directory-import are always welcome. Here is how you can contribute to the project:

1. Report issues - Report about a bug or suggest a new feature here.

2. Submit Pull Requests - If you fixed a bug or developed a new feature, you can submit a PR. Please follow these guidelines while preparing your code:

   • Ensure that your code properly complies with the standard TS conventions.
   • Make sure to add comments in your code.
   • Add a description explaining what changes you have made in your PR.

Before making a PR, please make sure your changes are consistent with the project's coding style and all tests are passing.

3. Improve the Documentation - You can enhance the README or the wiki page by adding more explanations, fixing typos, adding examples, etc.

Please note that your contributions should follow the guidelines described in the Code of Conduct.

Thank you for your interest in contributing to the directory-import!

back to top

Help

• If you have any questions or need help, feel free to join our Discord server.
• If you find a bug, or you have any suggestions? please create an issue on GitHub issues.
• If you want to help with the development of the project, you can create a pull request on GitHub pull requests.
• If you like the project, you can put a star on GitHub.
• For more details, please refer to the Code of Conduct.

back to top