TypeScript Dependency Detective

Common errors

• Error: Cannot find module 'typescript'

  cause The `typescript` package is a peer dependency and was not installed in the project.
  fix Install TypeScript in your project: `npm install typescript` or `yarn add typescript`.

• SyntaxError: Unexpected token 'export' (or similar parsing errors for modern TS features)

  cause The Node.js version is too old (e.g., <18) or the `typescript` peer dependency installed is incompatible with the TypeScript features used in the source code.
  fix Update Node.js to version 18 or newer. Ensure your installed `typescript` version (`npm view detective-typescript peerDependencies.typescript`) matches the supported range and can parse your source code.

• TypeError: detective is not a function

  cause Incorrect import statement. The `detective-typescript` package exports its main function as a default export, not a named export.
  fix Use `import detective from 'detective-typescript';` for ESM or `const detective = require('detective-typescript');` for CommonJS.

Warnings

• breaking Starting with v13.0.0, the `typescript` package is no longer a direct dependency but a peer dependency. Users must install `typescript` explicitly in their project.
  Fix: Run `npm install typescript` or `yarn add typescript` in your project alongside `detective-typescript`.
• breaking Version 12.0.0 dropped support for Node.js versions older than 18. Running the package on unsupported Node.js versions will result in errors.
  Fix: Ensure your Node.js environment is version 18 or newer. Update Node.js if necessary.
• gotcha The `mixedImports` option defaults to `false`. This means that CommonJS `require()` calls are not included in the dependency list by default. If you need to detect both ESM `import` and CJS `require` statements, you must explicitly set this option to `true`.
  Fix: When calling `detective(sourceCode, { mixedImports: true })`, ensure `mixedImports` is set to `true`.
• gotcha Options such as `skipAsyncImports`, `onFile`, and `onAfterFile` were incorrectly forwarded to internal parser/walker constructors in versions prior to v14.1.1. This could lead to unexpected behavior or options not being applied correctly.
  Fix: Upgrade to `detective-typescript@14.1.1` or newer to ensure correct handling of these options.

Install

• npm install detective-typescript npm
• yarn add detective-typescript yarn
• pnpm add detective-typescript pnpm

Imports

• detective
  wrong:

  import { detective } from 'detective-typescript';

  correct:

  import detective from 'detective-typescript';

  The main export is a default function, not a named export.
• detective
  wrong:

  import detective from 'detective-typescript';

  correct:

  const detective = require('detective-typescript');

  CommonJS syntax shown in older documentation, still supported for Node.js environments.

Quickstart

Demonstrates extracting static and dynamic dependencies from TypeScript code using various options.

import fs from 'node:fs';
import path from 'node:path';
import detective from 'detective-typescript';

// Example TypeScript code with various import types
const tsSourceCode = `
import { SomeType } from './types';
import { utilityFunction } from '@scope/utils';
import defaultExport from 'my-module';
import * as all from './all-exports';
const dynamicImport = import('./lazy-module');

interface MyInterface extends SomeType {}

export class MyClass {
  constructor() {
    utilityFunction();
    console.log(defaultExport);
  }
}
`;

// Create a dummy file to simulate reading from disk
const filePath = path.join(process.cwd(), 'temp-file.ts');
fs.writeFileSync(filePath, tsSourceCode, 'utf8');

try {
  const mySourceCode = fs.readFileSync(filePath, 'utf8');

  // Get all dependencies, including dynamic imports
  const dependencies = detective(mySourceCode, { skipAsyncImports: false });
  console.log('All dependencies:', dependencies);
  // Expected: [ './types', '@scope/utils', 'my-module', './all-exports', './lazy-module' ]

  // Get only static dependencies (excluding dynamic imports)
  const staticDependencies = detective(mySourceCode, { skipAsyncImports: true });
  console.log('Static dependencies:', staticDependencies);
  // Expected: [ './types', '@scope/utils', 'my-module', './all-exports' ]

  // Skip type-only imports (if 'SomeType' was a type-only import)
  const nonTypeDependencies = detective(mySourceCode, { skipTypeImports: true });
  console.log('Non-type dependencies:', nonTypeDependencies);

} catch (error) {
  console.error('Error processing file:', error);
} finally {
  fs.unlinkSync(filePath);
}