or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

cli.md configuration.md index.md list-generation.md tree-analysis.md

tile.json

Configuration

The Config class provides robust configuration management for dependency analysis, handling validation, normalization, and optimization of options across different module systems and build tools.

Config Class

class Config {
  constructor(options: Options);
  clone(): Config;
}

The Config class is used internally by the main dependency tree functions but can also be used directly for advanced configuration management.

Constructor Options

interface Options {
  filename: string;                    // Required: Entry point file path
  directory: string;                   // Required: Root directory (alias: root)
  visited?: Tree;                      // Optional: Memoization cache
  nonExistent?: string[];              // Optional: Array for missing dependencies
  isListForm?: boolean;                // Optional: Return format preference
  requireConfig?: string;              // Optional: RequireJS config path (alias: config)
  webpackConfig?: string;              // Optional: Webpack config path
  nodeModulesConfig?: any;             // Optional: Node modules resolution config
  detectiveConfig?: any;               // Optional: AST parsing config (alias: detective)
  tsConfig?: string | Record<string, any>; // Optional: TypeScript config
  tsConfigPath?: string;               // Optional: Virtual TS config path
  noTypeDefinitions?: boolean;         // Optional: Resolve to .js vs .d.ts
  filter?: (path: string, parent: string) => boolean; // Optional: Module filter
}

Usage Examples

Basic Configuration

const Config = require('dependency-tree/lib/config');

const config = new Config({
  filename: './src/app.js',
  directory: './src'
});

console.log(config.filename); // Absolute path
console.log(config.directory); // './src'

Advanced Configuration

const config = new Config({
  filename: './src/index.ts',
  directory: './src',
  tsConfig: './tsconfig.json',
  webpackConfig: './webpack.config.js',
  filter: (path, parent) => !path.includes('node_modules'),
  detectiveConfig: {
    amd: { skipLazyLoaded: true },
    es6: { mixedImports: true }
  }
});

Configuration Properties

Required Properties

filename

Type: string
Description: Path to the entry point file to analyze
Processing: Automatically resolved to absolute path using process.cwd()
Validation: Throws error if not provided

Optional Properties

visited

Type: Tree object
Default: {}
Description: Cache object for memoization to avoid reprocessing files
Usage: Shared across multiple analysis calls for performance

nonExistent

Type: string[]
Default: []
Description: Array to collect dependency paths that cannot be resolved
Usage: Populated during analysis with missing dependencies

isListForm

Type: boolean
Default: false
Description: Determines return format (array vs object tree)
Usage: Set automatically by toList() function

requireConfig

Type: string
Aliases: config
Description: Path to RequireJS configuration file
Usage: Enables AMD module alias resolution

webpackConfig

Type: string
Description: Path to Webpack configuration file
Usage: Enables Webpack alias and loader resolution

nodeModulesConfig

Type: object
Description: Configuration for resolving entry points in node_modules
Example: { entry: 'module' } to use 'module' field instead of 'main'

detectiveConfig

Type: object
Aliases: detective
Description: Configuration passed to precinct for AST parsing
Usage: Customize parsing behavior for different module types

tsConfig

Type: string | object
Description: TypeScript configuration file path or parsed config object
Processing: String paths are automatically parsed and cached for performance

tsConfigPath

Type: string
Description: Virtual path to TypeScript config when tsConfig is an object
Usage: Required for path mapping when tsConfig is provided as object

noTypeDefinitions

Type: boolean
Default: false
Description: Whether to resolve TypeScript imports to .js instead of .d.ts files

filter

Type: function
Signature: (path: string, parent: string) => boolean
Description: Function to determine if a module should be included
Validation: Throws error if provided but not a function

Methods

clone()

Creates a deep copy of the Config instance:

clone(): Config

Usage Example

const originalConfig = new Config({
  filename: './src/app.js',
  directory: './src'
});

const clonedConfig = originalConfig.clone();
clonedConfig.filename = './src/other.js';

// Original config unchanged
console.log(originalConfig.filename); // './src/app.js'
console.log(clonedConfig.filename);   // './src/other.js'

Configuration Validation

The Config constructor performs comprehensive validation:

Required Field Validation

// Throws: "filename not given"
new Config({ directory: './src' });

// Throws: "directory not given"  
new Config({ filename: './app.js' });

Type Validation

// Throws: "filter must be a function"
new Config({
  filename: './app.js',
  directory: './src',
  filter: 'not-a-function'
});

TypeScript Configuration Processing

The Config class optimizes TypeScript configuration handling:

String Path Processing

const config = new Config({
  filename: './src/app.ts',
  directory: './src',
  tsConfig: './tsconfig.json' // Automatically parsed and cached
});

Object Configuration

const tsConfigObject = {
  compilerOptions: {
    baseUrl: './src',
    paths: {
      '@/*': ['*']
    }
  }
};

const config = new Config({
  filename: './src/app.ts',
  directory: './src',
  tsConfig: tsConfigObject,
  tsConfigPath: './tsconfig.json' // Required for path mapping
});

Performance Optimizations

Memoization with visited

const globalVisited = {};

// First analysis
const config1 = new Config({
  filename: './src/app.js',
  directory: './src',
  visited: globalVisited
});

// Subsequent analyses reuse cache
const config2 = new Config({
  filename: './src/other.js', 
  directory: './src',
  visited: globalVisited // Shared cache
});

TypeScript Config Caching

// Config automatically caches parsed TypeScript config
const config = new Config({
  filename: './src/app.ts',
  directory: './src', 
  tsConfig: './tsconfig.json' // Parsed once, cached for performance
});

Advanced Configuration Patterns

Multi-Environment Setup

class EnvironmentConfig {
  static create(env) {
    const baseConfig = {
      filename: './src/index.js',
      directory: './src'
    };
    
    switch (env) {
      case 'development':
        return new Config({
          ...baseConfig,
          filter: () => true // Include all files
        });
        
      case 'production':
        return new Config({
          ...baseConfig,
          filter: (path) => !path.includes('test') // Exclude tests
        });
        
      default:
        return new Config(baseConfig);
    }
  }
}

Build Tool Integration

function createConfigFromBuildTool(buildTool, options) {
  const baseConfig = {
    filename: options.entry,
    directory: options.srcDir
  };
  
  switch (buildTool) {
    case 'webpack':
      return new Config({
        ...baseConfig,
        webpackConfig: options.webpackConfig
      });
      
    case 'requirejs':
      return new Config({
        ...baseConfig,
        requireConfig: options.requireConfig
      });
      
    case 'typescript':
      return new Config({
        ...baseConfig,
        tsConfig: options.tsConfig,
        noTypeDefinitions: options.production
      });
      
    default:
      return new Config(baseConfig);
  }
}