js-dependency-extractor

js-dependency-extractor

A JavaScript and TypeScript files dependency extractor.

Table of Contents

• Table of Contents
• Presentation
• Installation
• Technical information
  • Stack
  • Tests
    • Code quality
    • Unit
  • Logging and debugging
  • Security
• Requirements
  • Production
  • Development
• Usage
  • Lib
    • Import
    • jsDependencyExtractor(options)
  • CLI
    • Command name
    • Options
    • Print
    • Example
  • Environment variables
  • Errors
    • Object structure
    • Codes
  • Development
    • Test
      • Linting
      • Unit
• Code of Conduct
• Contributing
• Support
• Security
• License

Presentation

The purpose of this project is to extract JavaScript and TypeScript dependencies from a project directory or a single file.

Installation

To use as a library:

npm i -S js-dependency-extractor

To use as a CLI tool:

npm i -g js-dependency-extractor

Technical information

Stack

• NodeJS >= Dubnium 10.17.0 with NPM >=6.11.3

Tests

Code quality

Code style follows Airbnb JavaScript Best Practices using ESLint.

Unit

Mocha and Chai.

Logging and debugging

Uses bugbug for debugging.

Security

• Code security and most precisely module dependencies can be audited running npm audit.

Requirements

Production

• See Stack

Development

• See Stack

Usage

Lib

Import

const jsDependencyExtractor = require('js-dependency-extractor');

js-dependency-extractor module exports a function named jsDependencyExtractor.

• jsDependencyExtractor <AsyncFunction>.

jsDependencyExtractor(options)

Extract JavaScript and TypeScript dependencies from a directory or a file.

Note:

• support recursive extracting;
• support scoped dependencies;
• can merge partial requires/imports into one same dependency;
• can ignore specified paths;
• can target specific file extensions.

• options <Object>
  • path <String> Path to directory or file. Could be absolute or relative. Default: none Required: true
  • ignorePaths <Array> Paths to ignore. Could be absolute, relative or a pattern. Default: none Required: false
  • mergePartial <Boolean> Whether to merge partial requires/imports into one same dependency. Default: false Required: false
  • onlyExtensions <Array> File extensions to watch for. Empty list or null values mean to look up into all file extensions. Default: none Required: false
• Returns: <Array> Alphabetically ordered list of dependencies (empty array if no dependency found)

Example:

// my-project/app/index.ts
import path from 'path';
import memwatch from '@airbnb/node-memwatch';
import partial from '@scope/example-lib/partial';
import uuidv1 from 'uuid/v1';
import uuidv4 from 'uuid/v4';
import helpers from './helpers';
// ...

// my-project/app/helpers/index.js
const path = require('path');
const partial = require('@scope/example-lib/partial');
const sharp = require('sharp');
// ...

// my-project/test/helpers/index.js
const chai = require('chai');
const helpers = require('../app/helpers');
// ...

// example 1
try {
  const dependencies = await jsDependencyExtractor({
    ignorePaths: ['node_modules'],
    mergePartial: false,
    onlyExtensions: ['.ts'],
    path: '../../my-project',
  });

  console.log(dependencies);

  // [
  //   '@airbnb/node-memwatch',
  //   '@scope/example-lib/partial',
  //   'path',
  //   'uuid/v1',
  //   'uuid/v4'
  // ]
} catch (e) {
  console.error(e);
}

// example 2
try {
  const dependencies = await jsDependencyExtractor({
    ignorePaths: ['my-project/test', 'node_modules'],
    mergePartial: true,
    onlyExtensions: ['.js', '.ts'],
    path: '../../my-project',
  });

  console.log(dependencies);

  // [
  //   '@airbnb/node-memwatch',
  //   '@scope/example-lib',
  //   'path',
  //   'sharp',
  //   'uuid'
  // ]
} catch (e) {
  console.error(e);
}

CLI

Extract JavaScript and TypeScript dependencies from a directory or a file using the command line interface.

See jsDependencyExtractor(options) for more details.

Command name

jsde

Options

• -p, --path <path> Path to directory or file. Could be absolute or relative. Default: none Required: true
• -d, --debug Output extra debugging. Default: false Required: false
• -e, --only-extensions [onlyExtensions...] File extensions to watch for separated by a white space. Empty list or null values mean to look up into all file extensions. Default: none Required: false
• -i, --ignore-paths [ignorePaths...] Paths to ignore separated by a white space. Could be absolute, relative or a pattern. Default: none Required: false
• -m, --merge-partial Whether to merge partial requires/imports into one same dependency. Default: false Required: false
• -v, --version Output the current version. Default: none Required: false

Print

Alphabetically ordered list of dependencies on stdout.

Example

Based on jsDependencyExtractor(options) example.

jsde -p ../../my-project -e .js .ts -i my-project/test .node_modules -m

# print
@airbnb/node-memwatch
@scope/example-lib
path
sharp
uuid

Environment variables

name	type	description	default	example
DEBUG	Debug	Debug mode. See bugbug.	none	js-dependency-extractor:*

*required

Errors

Object structure

Errors emitted by js-dependency-extractor extend native Error:

{
  name,
  code,
  message,
  stack,
}

Codes

name	code	description	module
DependencyExtractionError	dependency-extraction-error	Dependency extraction encountered an error	src/index

Development

Test

Linting

npm run lint

Unit

npm run test

Code of Conduct

This project has a Code of Conduct. By interacting with this repository, organization, or community you agree to abide by its terms.

Contributing

Please have a look at our TODO for any work in progress.

Please take also a moment to read our Contributing Guidelines if you haven't yet done so.

Support

Please see our Support page if you have any questions or for any help needed.

Security

For any security concerns or issues, please visit our Security Policy page.

License

MIT.

Changelog

1.0.3 - delivery @07/06/2023

• docs: fix author