The Bumper class is the main interface for analyzing conventional commits and determining appropriate version bumps. It provides a fluent API for configuration and supports both preset-based and custom configurations.
Creates a new Bumper instance with an optional working directory or Git client.
/**
* Create a new Bumper instance
* @param cwdOrGitClient - Current working directory path or ConventionalGitClient instance
*/
constructor(cwdOrGitClient?: string | ConventionalGitClient);Usage Examples:
import { Bumper } from "conventional-recommended-bump";
// Default to current working directory
const bumper = new Bumper();
// Specify working directory
const bumper = new Bumper("/path/to/repo");
// Use custom Git client
import { ConventionalGitClient } from "@conventional-changelog/git-client";
const gitClient = new ConventionalGitClient("/path/to/repo");
const bumper = new Bumper(gitClient);Load configuration from a conventional commit preset (Angular, Atom, etc.).
/**
* Load configs from a preset
* @param preset - Preset name or configuration parameters
* @param loader - Optional custom preset module loader
* @returns this (for method chaining)
*/
loadPreset<PresetCreatorParams extends UnknownPresetCreatorParams = UnknownPresetCreatorParams>(
preset: PresetParams<PresetCreatorParams>,
loader?: PresetModuleLoader
): this;Usage Examples:
// Load Angular preset
const bumper = new Bumper().loadPreset("angular");
// Load preset with custom parameters
const bumper = new Bumper().loadPreset({
name: "angular",
preMajor: false
});
// Load preset with custom loader
import { createPresetLoader } from "conventional-changelog-preset-loader";
const customLoader = createPresetLoader(/* custom loader config */);
const bumper = new Bumper().loadPreset("angular", customLoader);Set configuration parameters directly using a preset object. Note: This method only sets configuration parameters (tags, commits, parser options) but does NOT set the whatBump function. Use loadPreset() to set whatBump function.
/**
* Set config directly - sets tags, commits, parser options only
* @param config - Preset configuration object (whatBump function is ignored)
* @returns this (for method chaining)
*/
config(config: Preset | Promise<Preset>): this;Usage Example:
const configParams = {
tags: {
prefix: 'v',
skipUnstable: true
},
commits: {
path: './src'
},
parser: {
headerPattern: /^(\w*)(?:\((.*)\))?: (.*)$/,
headerCorrespondence: ['type', 'scope', 'subject']
}
};
// This only sets config params, not whatBump
const bumper = new Bumper().config(configParams);
// You still need to provide whatBump via loadPreset() or bump() parameter
const result = await bumper.loadPreset('angular').bump();Configure logging and debugging options.
/**
* Set bumper options
* @param options - Bumper configuration options
* @returns this (for method chaining)
*/
options(options: Options): this;
interface Options {
warn?: Logger;
debug?: Logger;
}
type Logger = (source: string, messages: string | string[]) => void;Usage Example:
const bumper = new Bumper().options({
warn: (source, messages) => console.warn(`[${source}]`, messages),
debug: (source, messages) => console.debug(`[${source}]`, messages)
});Set parameters for Git tag analysis or specify a specific tag.
/**
* Set params to get the last semver tag
* @param paramsOrTag - Tag parameters or specific tag name
* @returns this (for method chaining)
*/
tag(paramsOrTag: GetSemverTagsParams | string): this;Usage Examples:
// Use specific tag
const bumper = new Bumper().tag("v1.2.0");
// Configure tag parameters
const bumper = new Bumper().tag({
prefix: "v",
skipUnstable: true
});
// Lerna package prefix
const bumper = new Bumper().tag({
prefix: "package-name@"
});Configure commit retrieval parameters or provide commits directly.
/**
* Set params to get commits since last release
* @param params - Commit retrieval parameters
* @param parserOptions - Optional parser configuration
* @returns this (for method chaining)
*/
commits(params: GetCommitsParams, parserOptions?: ParserStreamOptions): this;
/**
* Set commits since last release
* @param commits - Iterable or async iterable of commits
* @returns this (for method chaining)
*/
commits(commits: Iterable<Commit> | AsyncIterable<Commit>): this;Usage Examples:
// Configure commit retrieval
const bumper = new Bumper().commits({
from: "v1.0.0",
to: "HEAD",
path: "./src"
});
// Provide commits directly
const commits = [
{ type: 'feat', subject: 'add new feature', hash: 'abc123' },
{ type: 'fix', subject: 'fix bug', hash: 'def456' }
];
const bumper = new Bumper().commits(commits);
// With parser options
const bumper = new Bumper().commits({
from: "v1.0.0"
}, {
headerPattern: /^(\w*)(?:\((.*)\))?: (.*)$/,
headerCorrespondence: ['type', 'scope', 'subject']
});Analyze commits and determine the recommended version bump.
/**
* Recommend a bump by whatBump function
* @param whatBump - Optional custom function to determine bump from commits
* @returns Promise resolving to bump recommendation
*/
async bump(whatBump?: (commits: Commit[]) => Promise<BumperRecommendation | null | undefined>): Promise<BumperRecommendationResult>;Usage Examples:
// Basic bump with preset
const bumper = new Bumper().loadPreset("angular");
const recommendation = await bumper.bump();
if ("releaseType" in recommendation) {
console.log(`Recommended bump: ${recommendation.releaseType}`);
console.log(`Reason: ${recommendation.reason}`);
console.log(`Commits analyzed: ${recommendation.commits.length}`);
} else {
console.log("No bump recommended");
console.log(`Commits analyzed: ${recommendation.commits.length}`);
}
// Custom whatBump function
const customBump = (commits) => {
const breakingChanges = commits.filter(c =>
c.notes.some(n => n.title === 'BREAKING CHANGE')
);
if (breakingChanges.length > 0) {
return {
level: 0,
reason: `${breakingChanges.length} breaking changes detected`
};
}
return null; // No bump needed
};
const recommendation = await bumper.bump(customBump);All configuration methods return this, enabling fluent method chaining:
const recommendation = await new Bumper()
.loadPreset("angular")
.tag({ prefix: "v", skipUnstable: true })
.commits({ path: "./src" })
.options({
warn: console.warn.bind(console),
debug: console.debug.bind(console)
})
.bump();