dpdm

DPDM provides a CLI to analyze dependencies and find circular references in JavaScript and TypeScript projects.

Basic Usage

Analyze a specific file:

dpdm ./src/index.ts

Common CLI Tasks

• Print circular dependencies only:

  dpdm --no-warning --no-tree ./src/index.ts

• Exit with a non-zero code if circular dependencies are found:

  dpdm --exit-code circular:1 ./src/index.ts

• Ignore TypeScript type dependencies:

  dpdm -T ./src/index.ts

• Find unused files: Provide a glob for files to check against and a starting entry point:

  dpdm --no-tree --no-warning --no-circular --detect-unused-files-from 'src/**/*.*' 'index.js'

• Skip dynamic imports: Use --skip-dynamic-imports circular to ignore them only when parsing circular references, or --skip-dynamic-imports tree to ignore them when parsing source files.

  dpdm --skip-dynamic-imports circular index.js

• Ignore specific imports in circular checks: Use --skip-imports with ISSUER:DEPENDENCY regex pairs.

  dpdm ./src/index.js --skip-imports 'src/a.js:.*' src/c.js:src/d.js

• Analyze from a different working directory:

  dpdm --cwd ../other-project ./src/index.ts

• Group output by package:

  dpdm --group-by-package './packages/*/src/index.ts'

You can import DPDM functions directly into your application to programmatically analyze dependency trees and circular dependencies.

Core API Functions

• parseDependencyTree(entries, options): Parses dependencies for the provided glob entries. Returns a Promise<DependencyTree>.
• parseCircular(tree): Parses circular dependencies from a DependencyTree. Returns an array of circular dependency paths (string[][]).
• prettyCircular(circulars): Formats circular dependencies for readable output.
• defineConfig(config): Helper to define configuration objects.
• groupDependencyTreeByPackage(tree, context): Groups a dependency tree by the nearest package.json.

Data Structures

• DependencyTree: A Record<string, Dependency[] | null> where the key is the file ID and the value is its dependencies. If a file is ignored, its value is null.
• Dependency: Represents an edge in the graph:
  • issuer: The file initiating the import.
  • request: The requested module path.
  • kind: The DependencyKind (e.g., StaticImport, DynamicImport, CommonJS).
  • id: The shortened, resolved filename (null if unresolvable).

Example Usage

import {
  defineConfig,
  parseDependencyTree,
  parseCircular,
  prettyCircular,
} from 'dpdm';

parseDependencyTree('./index', {
  /* options */
}).then((tree) => {
  const circulars = parseCircular(tree);
  console.log(prettyCircular(circulars));
});

The Config interface defines the options available when using dpdm as a package or via its configuration surface. It allows you to control file selection, directory context, dependency parsing behavior, and output formatting.

Key configuration areas:

• File Selection: Use files to specify entry points, extensions for file types, and include/exclude (RegExp or string) to filter files.
• Parsing Behavior:
  • tree: Set to true to ignore dynamic imports when parsing source files.
  • circular: Set to true to ignore dynamic imports when parsing circular references.
  • skipDynamicImports: Can be set to 'tree' or 'circular' to specifically target which phase ignores dynamic imports.
  • transform: Boolean to enable/disable transformation.
• Output & Reporting:
  • output: Path to save results.
  • warning: Boolean to enable/disable warnings.
  • progress: Boolean to show progress.
  • exitCode: Specify the exit code behavior.
• Filtering & Warnings:
  • ignoreMissWarnings, ignoreSkipWarnings, and ignoreMissWarning/ignoreSkipWarning allow you to suppress specific warning patterns using RegExp or strings.
• Dependency Management:
  • skipImports: Array of strings to skip specific imports.
  • groupByPackage: Boolean to group dependencies by package.

const config: Config = {
  files: ['./src/index.ts'],
  cwd: process.cwd(),
  extensions: ['.ts', '.js'],
  include: /src\//,
  exclude: /node_modules/,
  tree: true,
  skipDynamicImports: 'tree',
  output: './dependency-report.json'
};

The following options are available for the dpdm command line interface: