@haetae/javascript

@haetae/javascript provides features for javascript ecosystem.
For instance, you can find out which module depends on which modules.
If your project do not use javascript-related languages, you don't need this package.

peerDependencies

Note: This might not be exhaustive and lists only Haetae's packages.

• @haetae/core
• @haetae/utils

Dependents

• haetae

Installation

To automatically install @haetae/javascript and its peerDependencies

You may want to install @haetae/javascript and its peerDependencies all at once.
install-peerdeps (opens in a new tab) is a good tool for that.

# As dependencies
npx install-peerdeps @haetae/javascript
# As devDependencies
npx install-peerdeps --dev @haetae/javascript

To manually handle the installation

You might want to manually deal with the installation.
First, install @haetae/javascript itself.

# As dependencies
npm install @haetae/javascript
# As devDependencies
npm install --save-dev @haetae/javascript

Then, check out peerDependencies and manually handle them.
(e.g. Install them as dependencies or set them as peerDependencies)

# This does not install, but just shows peerDependencies.
npm info @haetae/javascript peerDependencies

API

pkg

Refer to introduction#pkg.

VersionOptions

An argument interface for version.

Type

interface VersionOptions {
  rootDir?: string
}

version

A function to get the version (not SemVer range, but the exact real version) of installed packages.
(Any packages, like typescript, jest, react, @changesets/cli etc.)
It supports npm, yarn classic(v1), yarn berry(v2, v3) and pnpm.

Type

(packageName: string, options?: VersionOptions) => Promise<string>

Arguments

• packageName : A package name to get the version of.
• options?
  • options.rootDir? : A directory to start search. This should be your project root or its inner directory. (default: core.getConfigDirname())

Usage

You can get parsed object of any package's version by version.
For example, let's assume eslint's version is 1.2.3-beta.4.

import * as js from '@haetae/javascript'
 
const eslintVersion = await js.version('eslint')
 
eslintVersion.value // '1.2.3-beta.4'
eslintVersion.major // 1 // Integer
eslintVersion.minor // 2 // Integer
eslintVersion.patch // 3 // Integer
eslintVersion.prerelease // ['beta', 4] // 'beta' is string, 4 is integer
eslintVersion.untilMinor //  '1.2'
eslintVersion.untilPatch // '1.2.3'

env in the config file can be a good place to use version.

import { configure, js, utils } from 'haetae'
 
export default configure({
  // Other options are omitted for brevity.
  commands: {
    myLint: {
      env: async () => ({
        eslintrc: await utils.hash(['.eslintrc.js']),
        eslint: (await js.version('eslint')).major,
      }),
      run: async () => { /* ... */ }
    }
  },
})

GraphOptions

An argument interface for graph.

Type

interface GraphOptions {
  entrypoint: string
  tsConfig?: string
  webpackConfig?: string
  skipNodeModules?: boolean
  rootDir?: string
}

graph

A function to create a dependency graph.
it's not just for a specific language, but for any dependency graph.

Type

(options: GraphOptions) => Promise<utils.DepsGraph>

Options?

• entrypoint : A starting point of a file to search the dependency graph.
• tsConfig? : A path to Typescript config file. (default: tsconfig.json file by walking up parent directories recursively.).
• webpackConfig? : A path to Webpack config file. (default: webpack.config.js, webpack.config.mjs, or webpack.config.cjs file by walking up parent directories recursively.).
• skipNodeModules? : Whether to exclude dependencies in node_modules. (default: true).
• rootDir? : A directory to use when entrypoint or tsConfig is given as relative paths. (default: core.getConfigDirname())

DepsOptions

An argument interface for deps.

interface DepsOptions {
  entrypoint: string
  tsConfig?: string
  webpackConfig?: string
  skipNodeModules?: boolean
  rootDir?: string
  additionalGraph?: utils.DepsGraph
}

deps

A function to get all of the direct and transitive dependencies of a single entry point.
The searched result keeps the order by breath-first approach, without duplication of elements.

(options: DepsOptions) => Promise<string[]>

Options

• entrypoint : An entry point to get all of whose direct and transitive dependencies.
• tsConfig? : A path to Typescript config file. (default: tsconfig.json file by walking up parent directories recursively.).
• webpackConfig? : A path to Webpack config file. (default: webpack.config.js, webpack.config.mjs, or webpack.config.cjs file by walking up parent directories recursively.).
• skipNodeModules? : Whether to exclude dependencies in node_modules. (default: true).
• rootDir? : A directory to join with when entrypoint is given as a relative path. (default: core.getConfigDirname())
• additionalGraph? : A graph to manually specify explicit dependency relationships. This is purely additional, not an override or replacement of the source code dependency graph. (default: await graph({ edges: [], rootDir }))

DependsOnOptions

An argument interface for dependsOn.

Type

interface DependsOnOptions {
  dependent: string
  dependencies: readonly string[]
  tsConfig?: string
  webpackConfig?: string
  skipNodeModules?: boolean
  rootDir?: string
  additionalGraph?: utils.DepsGraph
  glob?: boolean
}

dependsOn

A function to check if a module depends on one of the other modules, transitively or directly.

Type

(options: DependsOnOptions) => Promise<boolean>

Options?

• dependent : A target to check if it is a dependent of at least one of dependencies, directly or transitively.
• dependencies : Candidates that may be a dependency of Dependents, directly or transitively.
• tsConfig? : A path to Typescript config file. (default: tsconfig.json file by walking up parent directories recursively.).
• webpackConfig? : A path to Webpack config file. (default: webpack.config.js, webpack.config.mjs, or webpack.config.cjs file by walking up parent directories recursively.).
• skipNodeModules? : Whether to exclude dependencies in node_modules. (default: true).
• rootDir? : A directory to join with when dependent, dependencies, or tsConfig is given as a relative path. (default: core.getConfigDirname())
• additionalGraph? : A graph to manually specify explicit dependency relationships. This is purely additional, not an override or replacement of the source code dependency graph. (default: await graph({ edges: [], rootDir }))
• glob? : Whether to enable glob pattern. (default: true)

Basic Usage

Let's say,

• a.ts depends on b.ts.
• c.ts depends on a.ts, which depends on b.ts
• e.ts does not (even transitively) depend on neither f.ts nor b.ts.
• f.ts does not (even transitively) depend on b.ts.

then the result would be like this.

const dependencies = ['f.ts', 'b.ts']
 
await dependsOn({ dependent: 'a.ts', dependencies }) // true
await dependsOn({ dependent: 'c.ts', dependencies }) // true -> transitively
await dependsOn({ dependent: 'e.ts', dependencies }) // false
await dependsOn({ dependent: 'f.ts', dependencies }) // true -> 'f.ts' depends on 'f.ts' itself.

DependOnOptions

An argument interface for dependOn.

Type

interface DependOnOptions {
  dependents: readonly string[]
  dependencies: readonly string[]
  tsConfig?: string
  webpackConfig?: string
  skipNodeModules?: boolean
  rootDir?: string
  additionalGraph?: utils.DepsGraph
  glob?: boolean
}

dependOn

A function to check if some of the given modules depend on one of the other modules, transitively or directly.
It filters options.dependencies. the result only contains files that depend on at least one of options.dependencies.

Type

(options: DependOnOptions) => Promise<string[]>

Options?

• dependents : Targets to filter by whether it's a dependent of at least one of dependencies, directly or transitively.
• dependencies : Candidates that may be a dependency of dependent, directly or transitively.
• tsConfig? : A path to Typescript config file. (default: tsconfig.json file by walking up parent directories recursively.).
• webpackConfig? : A path to Webpack config file. (default: webpack.config.js, webpack.config.mjs, or webpack.config.cjs file by walking up parent directories recursively.).
• skipNodeModules? : Whether to exclude dependencies in node_modules. (default: true).
• rootDir? : A directory to join with when dependents, dependencies, or tsConfig is given as relative paths. (default: core.getConfigDirname())
• additionalGraph? : A graph to manually specify explicit dependency relationships. This is purely additional, not an override or replacement of the source code dependency graph. (default: await graph({ edges: [], rootDir }))
• glob? : Whether to enable glob pattern. (default: true)

Usage

Basic usage is guided in the Getting Started article. For example, combination with git.changedFiles or how to utilize additionalGraph.