Requirements

• Node.js v20 or higher

Getting Started

This package is available in the Node Package Repository and can be easily installed with npm or yarn.

$ npm i @nodesecure/tree-walker
# or
$ yarn add @nodesecure/tree-walker

Usage example

import os from "node:os";

import pacote from "pacote";
import { npm } from "@nodesecure/tree-walker";

const manifest = await pacote.manifest("[email protected]", {
  cache: `${os.homedir()}/.npm`
});

const treeWalker = new npm.TreeWalker();

for await (const dependency of treeWalker.walk(manifest)) {
  console.log(dependency);
}

[!NOTE] This package has been designed to be used by the Scanner package/workspace.

API

npm.TreeWalker

constructor(options?: TreeWalkerOptions)

import pacote from "pacote";
import Arborist from "@npmcli/arborist";

interface LocalDependencyTreeLoaderProvider {
  load(
    location: string,
    registry?: string
  ): Promise<Arborist.Node>;
}

interface PacoteProviderApi {
  manifest(
    spec: string,
    opts?: pacote.Options
  ): Promise<pacote.AbbreviatedManifest & pacote.ManifestResult>;
}

interface TreeWalkerOptions {
  registry?: string;
  providers?: {
    pacote?: PacoteProviderApi;
    localTreeLoader?: LocalDependencyTreeLoaderProvider;
  }
}

*walk(manifest: PackageJSON | ManifestVersion, options: WalkOptions): AsyncIterableIterator< DependencyJSON >

The walk method processes package metadata from a given package.json file or a Manifest result from the pacote library.

The options parameter is described by the following TypeScript interface:

interface WalkOptions {
  /**
   * Specifies the maximum depth to traverse for each root dependency.
   * For example, a value of 2 would mean only traversing dependencies and their immediate dependencies.
   *
   * @default Infinity
   */
  maxDepth?: number;

  /**
   * Includes development dependencies in the walk.
   * Note that enabling this option can significantly increase processing time.
   *
   * @default false
   */
  includeDevDeps?: boolean;

  /**
   * Enables the use of Arborist for rapidly walking over the dependency tree.
   * When enabled, it triggers different methods based on the presence of `node_modules`:
   * - `loadActual()` if `node_modules` is available.
   * - `loadVirtual()` otherwise.
   *
   * When disabled, it will iterate on all dependencies by using pacote
   */
  packageLock?: {
    /**
     * Fetches all manifests for additional metadata.
     * This option is useful only when `usePackageLock` is enabled.
     *
     * @default false
     */
    fetchManifest?: boolean;

    /**
     * Specifies the location of the manifest file for Arborist.
     * This is typically the path to the `package.json` file.
     */
    location: string;
  };
}

License

MIT