or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

tessl/npm-require-directory

Recursively iterates over specified directory, require()'ing each file, and returning a nested hash structure containing those modules.

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:npm/require-directory@2.1.x

To install, run

npx @tessl/cli install tessl/npm-require-directory@2.1.0

require-directory

Recursively iterates over specified directory, require()ing each file, and returning a nested hash structure containing those modules. Enables automatic loading and organizing of multiple modules from a directory hierarchy without manually requiring each file.

Package Information

Package Name: require-directory
Package Type: npm
Language: JavaScript
Installation: npm install require-directory

Core Imports

const requireDirectory = require('require-directory');

Basic Usage

const requireDirectory = require('require-directory');

// Require all files from current directory
const modules = requireDirectory(module);

// Require all files from a specific directory
const routes = requireDirectory(module, './routes');

// With options - only JavaScript files, no recursion
const controllers = requireDirectory(module, './controllers', {
  extensions: ['js'],
  recurse: false
});

Capabilities

Directory Requiring

Recursively processes a directory structure, requiring each file and building a nested hash structure that mirrors the directory layout.

/**
 * Recursively requires all files in a directory and returns nested hash structure
 * @param {Object} module - The module object (typically 'module')
 * @param {string} [path] - Path to directory (defaults to module's directory)
 * @param {Object} [options] - Configuration options
 * @returns {Object} Nested hash structure containing required modules
 */
function requireDirectory(module, path, options);

Parameters:

module (required): The module object, typically pass module
path (optional): String path to directory to require from. If omitted, uses the directory containing the calling module
options (optional): Configuration object for controlling behavior

Returns: Object containing nested hash structure where:

File modules are keyed by filename (without extension)
Directory modules are keyed by directory name
Structure mirrors the filesystem hierarchy

Configuration Options

Control file processing, filtering, and transformation behavior.

interface RequireDirectoryOptions {
  /** Array of file extensions to process */
  extensions?: string[];
  /** Whether to recursively process subdirectories */
  recurse?: boolean;
  /** Function to transform object keys */
  rename?: (name: string, joined: string, filename: string) => string;
  /** Function to transform loaded modules - return value used if truthy, otherwise original object */
  visit?: (obj: any, joined: string, filename: string) => any;
  /** RegExp or function to whitelist files */
  include?: RegExp | ((path: string, filename: string) => boolean);
  /** RegExp or function to blacklist files */
  exclude?: RegExp | ((path: string, filename: string) => boolean);
}

Option Details:

extensions: Array of file extensions to include (default: ['js', 'json', 'coffee'])
recurse: Boolean controlling recursive directory processing (default: true)
rename: Function to transform object keys, receives (name, joined, filename)
visit: Function to transform loaded modules, receives (obj, joined, filename). Return value is used if truthy, otherwise original object is kept
include: RegExp or function to whitelist specific files
exclude: RegExp or function to blacklist specific files

Usage Examples:

// Custom extensions
const modules = requireDirectory(module, './lib', {
  extensions: ['js', 'ts']
});

// No recursion
const topLevel = requireDirectory(module, './routes', {
  recurse: false
});

// File filtering with RegExp
const jsOnly = requireDirectory(module, './src', {
  include: /\.js$/
});

// File filtering with function
const filtered = requireDirectory(module, './controllers', {
  exclude: (path, filename) => filename.startsWith('test')
});

// Key transformation
const uppercased = requireDirectory(module, './models', {
  rename: (name) => name.toUpperCase()
});

// Module transformation
const wrapped = requireDirectory(module, './middleware', {
  visit: (obj) => {
    // Wrap functions with logging
    if (typeof obj === 'function') {
      return (...args) => {
        console.log('Calling:', obj.name);
        return obj(...args);
      };
    }
    return obj;
  }
});

Default Options Access

Access the default configuration object used by requireDirectory.

/**
 * Default options object used by requireDirectory
 */
const defaults: RequireDirectoryOptions;

The defaults object contains:

const defaults = {
  extensions: ['js', 'json', 'coffee'],
  recurse: true,
  rename: function(name) { return name; },
  visit: function(obj) { return obj; }
};

Usage:

// Access default options
const defaultOpts = requireDirectory.defaults;

// Modify defaults for all subsequent calls
requireDirectory.defaults.extensions = ['js', 'ts'];

Types

/**
 * Configuration options for requireDirectory function
 */
interface RequireDirectoryOptions {
  /** File extensions to process (default: ['js', 'json', 'coffee']) */
  extensions?: string[];
  /** Enable recursive directory processing (default: true) */
  recurse?: boolean;
  /** Transform function for object keys */
  rename?: (name: string, joined: string, filename: string) => string;
  /** Transform function for loaded modules */
  visit?: (obj: any, joined: string, filename: string) => any;
  /** RegExp pattern or function to include specific files */
  include?: RegExp | ((path: string, filename: string) => boolean);
  /** RegExp pattern or function to exclude specific files */
  exclude?: RegExp | ((path: string, filename: string) => boolean);
}

/**
 * Filter function signature for include/exclude options
 */
type FilterFunction = (path: string, filename: string) => boolean;

/**
 * Rename function signature for transforming object keys
 */
type RenameFunction = (name: string, joined: string, filename: string) => string;

/**
 * Visit function signature for transforming loaded modules
 * Return value is used if truthy, otherwise original object is kept
 */
type VisitFunction = (obj: any, joined: string, filename: string) => any;

Behavior Notes

Self-exclusion: The calling module file is automatically excluded from results
Empty directories: Directories containing no matching files are excluded from results
Key generation: Object keys are generated by removing file extensions from filenames
Module loading: Uses module.require() internally for proper relative path resolution
Error handling: File system and module loading errors are not caught and will propagate
Path resolution: Relative paths are resolved relative to the calling module's directory

Common Patterns

// Route organization pattern
// routes/index.js
module.exports = requireDirectory(module);

// app.js
const routes = require('./routes');
app.get('/', routes.home);
app.get('/users', routes.users.list);

// Controller loading with transformation
const controllers = requireDirectory(module, './controllers', {
  visit: (controller) => {
    // Auto-bind methods to controller instance
    if (typeof controller === 'object') {
      Object.getOwnPropertyNames(Object.getPrototypeOf(controller))
        .filter(name => typeof controller[name] === 'function')
        .forEach(name => controller[name] = controller[name].bind(controller));
    }
    return controller;
  }
});

// Development vs production file loading
const middleware = requireDirectory(module, './middleware', {
  exclude: process.env.NODE_ENV === 'production' ? /dev\.js$/ : /prod\.js$/
});