@hyperfrontend/versioning/flow/models

models

Type definitions and immutable builders for version flows and their steps.

VersionFlow is the top-level shape carrying steps, configuration, and metadata; FlowStep is the per-step shape carrying an ID, a condition, and an executor. createFlow, addStep, removeStep, insertStep, insertStepAfter, and insertStepBefore are the immutable builders — every operation returns a new VersionFlow rather than mutating in place. FlowConfig, FlowContext, FlowResult, FlowState, FlowStatus, FlowStepResult, and FlowStepResultWithId describe the runtime surface that the executor threads through each step.

API Reference

ƒ Functions

§function

addStep(flow: VersionFlow, step: FlowStep): VersionFlow

Adds a step to a flow. Returns a new flow with the step appended.

Parameters

Name	Type	Description
§flow	`VersionFlow`	The flow to extend
§step	`FlowStep`	The step to add

Returns

VersionFlow

A new VersionFlow with the step added

Example

Adding a custom step to a flow

import { addStep, createConventionalFlow, createNoopStep } from '@hyperfrontend/versioning'

const flow = createConventionalFlow()
const extended = addStep(flow, createNoopStep('custom', 'Custom Step'))

console.log(extended.steps.length)
// => original steps + 1

§function

createFailedResult(error: Error, message?: string): FlowStepResult

Creates a failed step result.

Parameters

Name	Type	Description
§error	`Error`	Error that caused the failure
§message?	`string`	Optional message (defaults to error.message)

Returns

FlowStepResult

A FlowStepResult with 'failed' status

Example

Handling step execution errors

import { createFailedResult } from '@hyperfrontend/versioning'

// In a step handler:
try {
  await doOperation()
} catch (err) {
  return createFailedResult(err as Error, 'Operation failed')
}

§function

createFlow(id: string, name: string, steps: unknown, options: CreateFlowOptions): VersionFlow

Creates a version flow.

Parameters

Name	Type	Description
§id	`string`	Flow identifier
§name	`string`	Human-readable flow name
§steps	`unknown`	Ordered steps to execute
§options	`CreateFlowOptions`	Optional flow configuration (default: `{}`)

Returns

VersionFlow

A VersionFlow object

Example

Creating a custom flow

const myFlow = createFlow(
  'custom',
  'Custom Release Flow',
  [fetchStep, analyzeStep, bumpStep],
  { description: 'My custom versioning workflow' }
)

§function

createNoopStep(id: string, name: string, message: string): FlowStep

Creates a step that succeeds immediately. Useful for placeholder or conditional steps.

Parameters

Name	Type	Description
§id	`string`	Unique identifier within the flow
§name	`string`	Display label shown during execution
§message	`string`	Success message (default: `'Step completed (no-op)'`)

Returns

FlowStep

A FlowStep that always succeeds

Example

Creating a placeholder step

import { createNoopStep, executeStep } from '@hyperfrontend/versioning'

const step = createNoopStep('placeholder', 'Placeholder Step')
const result = await executeStep(step, context)

console.log(result.status)
// => 'success'

§function

createSkippedResult(message: string): FlowStepResult

Creates a skipped step result.

Parameters

Name	Type	Description
§message	`string`	Explanation for why the step was skipped

Returns

FlowStepResult

A FlowStepResult with 'skipped' status

Example

Skipping a step conditionally

import { createSkippedResult } from '@hyperfrontend/versioning'

// In a step handler:
if (!config.enabled) {
  return createSkippedResult('Feature disabled in config')
}

§function

createStep(id: string, name: string, execute: StepExecutor, options: CreateStepOptions): FlowStep

Creates a flow step.

Parameters

Name	Type	Description
§id	`string`	Unique step identifier
§name	`string`	Human-readable step name
§execute	`StepExecutor`	Step executor function
§options	`CreateStepOptions`	Optional step configuration (default: `{}`)

Returns

FlowStep

A FlowStep object

Example

Creating a custom fetch step

const fetchStep = createStep(
  'fetch-registry',
  'Fetch Registry Version',
  async (ctx) => {
    const version = await ctx.registry.getLatestVersion(ctx.packageName)
    return {
      status: 'success',
      stateUpdates: { publishedVersion: version },
      message: `Found published version: ${version}`
    }
  }
)

§function

createSuccessResult(message: string, stateUpdates?: Partial<FlowState>): FlowStepResult

Creates a success step result.

Parameters

Name	Type	Description
§message	`string`	Output text describing what the step accomplished
§stateUpdates?	`Partial<FlowState>`	Optional state updates to apply after step completion

Returns

FlowStepResult

A FlowStepResult with 'success' status

Example

Returning a success result with state updates

import { createSuccessResult } from '@hyperfrontend/versioning'

// In a step handler:
return createSuccessResult('Updated 3 files', {
  modifiedFiles: ['/path/a.ts', '/path/b.ts', '/path/c.ts']
})

§function

getStep(flow: VersionFlow, stepId: string): FlowStep

Gets a step from a flow by ID.

Parameters

Name	Type	Description
§flow	`VersionFlow`	The flow to search
§stepId	`string`	The step ID to find

Returns

FlowStep

The step if found, undefined otherwise

Example

Getting a step by ID

import { getStep, createConventionalFlow } from '@hyperfrontend/versioning'

const flow = createConventionalFlow()
const step = getStep(flow, 'analyze-commits')

console.log(step?.name)
// => 'Analyze Commits'

§function

hasStep(flow: VersionFlow, stepId: string): boolean

Checks if a flow has a specific step.

Parameters

Name	Type	Description
§flow	`VersionFlow`	The flow to check
§stepId	`string`	The step ID to look for

Returns

boolean

True if the flow contains the step

Example

Checking if a flow has a step

import { hasStep, createConventionalFlow } from '@hyperfrontend/versioning'

const flow = createConventionalFlow()

console.log(hasStep(flow, 'create-commit'))
// => true
console.log(hasStep(flow, 'custom-step'))
// => false

§function

insertStep(flow: VersionFlow, step: FlowStep, index: number): VersionFlow

Inserts a step at a specific position.

Parameters

Name	Type	Description
§flow	`VersionFlow`	The flow to modify
§step	`FlowStep`	The step to insert
§index	`number`	Position to insert at (0-based)

Returns

VersionFlow

A new VersionFlow with the step inserted

Example

Inserting a step at a specific position

import { insertStep, createConventionalFlow, createNoopStep } from '@hyperfrontend/versioning'

const flow = createConventionalFlow()
const modified = insertStep(flow, createNoopStep('early', 'Early Step'), 0)

console.log(modified.steps[0].id)
// => 'early'

§function

insertStepAfter(flow: VersionFlow, step: FlowStep, afterStepId: string): VersionFlow

Inserts a step after another step.

Parameters

Name	Type	Description
§flow	`VersionFlow`	The flow to modify
§step	`FlowStep`	The step to insert
§afterStepId	`string`	ID of the step to insert after

Returns

VersionFlow

A new VersionFlow with the step inserted

Example

Inserting a step after another step

import { insertStepAfter, createConventionalFlow, createNoopStep } from '@hyperfrontend/versioning'

const flow = createConventionalFlow()
const modified = insertStepAfter(flow, createNoopStep('validate', 'Validate'), 'analyze-commits'))

// 'validate' step now follows 'analyze-commits'

§function

insertStepBefore(flow: VersionFlow, step: FlowStep, beforeStepId: string): VersionFlow

Inserts a step before another step.

Parameters

Name	Type	Description
§flow	`VersionFlow`	The flow to modify
§step	`FlowStep`	The step to insert
§beforeStepId	`string`	ID of the step to insert before

Returns

VersionFlow

A new VersionFlow with the step inserted

Example

Inserting a step before another step

import { insertStepBefore, createConventionalFlow, createNoopStep } from '@hyperfrontend/versioning'

const flow = createConventionalFlow()
const modified = insertStepBefore(flow, createNoopStep('prep', 'Prepare'), 'create-commit'))

// 'prep' step now runs before 'create-commit'

§function

removeStep(flow: VersionFlow, stepId: string): VersionFlow

Removes a step from a flow by ID. Returns a new flow without the specified step.

Parameters

Name	Type	Description
§flow	`VersionFlow`	The flow to modify
§stepId	`string`	The ID of the step to remove

Returns

VersionFlow

A new VersionFlow without the step

Example

Removing a step from a flow

import { removeStep, createConventionalFlow } from '@hyperfrontend/versioning'

const flow = createConventionalFlow()
const minimal = removeStep(flow, 'generate-changelog')

// Flow no longer has changelog step
console.log(minimal.steps.find(s => s.id === 'generate-changelog'))
// => undefined

§function

replaceStep(flow: VersionFlow, stepId: string, newStep: FlowStep): VersionFlow

Replaces a step in the flow.

Parameters

Name	Type	Description
§flow	`VersionFlow`	The flow to modify
§stepId	`string`	ID of the step to replace
§newStep	`FlowStep`	The replacement step

Returns

VersionFlow

A new VersionFlow with the step replaced

Example

Replacing a step with a custom implementation

import { replaceStep, createConventionalFlow, createNoopStep } from '@hyperfrontend/versioning'

const flow = createConventionalFlow()
const modified = replaceStep(flow, 'create-tag', createNoopStep('create-tag', 'Custom Tag'))

// 'create-tag' now uses custom implementation

§function

withConfig(flow: VersionFlow, config: Partial<FlowConfig>): VersionFlow

Updates the flow configuration.

Parameters

Name	Type	Description
§flow	`VersionFlow`	The flow to configure
§config	`Partial<FlowConfig>`	Configuration updates to merge

Returns

VersionFlow

A new VersionFlow with updated config

Example

Updating flow configuration

import { withConfig, createConventionalFlow } from '@hyperfrontend/versioning'

const flow = createConventionalFlow()
const dryRunFlow = withConfig(flow, { dryRun: true })

// Flow now runs in dry-run mode

◈ Interfaces

§interface

CreateFlowOptions

Options for creating a version flow.

Properties

§config?:FlowConfig—

Flow configuration

§description?:string—

Flow description

§interface

CreateStepOptions

Options for creating a flow step.

Properties

§continueOnError?:boolean—

Whether step failure should fail the flow

§dependsOn?:unknown—

Steps that must complete before this one

§description?:string—

Step description

§skipIf?:StepCondition—

Condition for skipping step

§interface

FlowConfig

Flow configuration options.

Properties

§readonly allowPrerelease?:boolean—

Allow prerelease versions

§readonly backupChangelog?:boolean—

Create a backup of the existing changelog before modification.
When enabled:

Existing CHANGELOG.md is renamed to CHANGELOG.backup.md
New changelog is written
Backup is deleted on success

Useful for safety during changelog regeneration.

§readonly changelogFileName?:string—

Changelog file name relative to project root.

§readonly commitMessage?:string—

Custom commit message template

§readonly commitTypeToSection?:Partial<Record<string, ChangelogSectionType | null>>—

Custom mapping from commit type to changelog section. Merged with defaults; use null to exclude a type from changelog.

§readonly dryRun?:boolean—

Dry run mode - preview changes without applying

§readonly firstReleaseVersion?:string—

Base version for first release

§readonly maxCommitFallback?:number—

Maximum commits to analyze when no base commit is available. Used for first releases, history rewrites, and path-filtered queries.
Set higher if you expect >500 commits between releases.

§readonly minorTypes?:unknown—

Commit types that trigger minor bumps

§readonly patchTypes?:unknown—

Commit types that trigger patch bumps

§readonly prereleaseId?:string—

Prerelease identifier (e.g., 'alpha', 'beta')

§readonly preset?:"conventional" | "independent" | "synced"—

Preset name or custom configuration

§readonly releaseAs?:"minor" | "patch" | "major"—

Force a specific bump type, bypassing commit analysis

§readonly releaseBranch?:string—

Branch allowed for releases

§readonly releaseTypes?:unknown—

Commit types that trigger releases

§readonly repository?:RepositoryConfig | "inferred" | "disabled" | RepositoryResolution—

Repository resolution configuration for compare URL generation.
Controls how repository information is resolved:

'disabled': No compare URLs generated (default, backward compatible)
'inferred': Auto-detect from package.json or git remote
RepositoryResolution: Fine-grained control with explicit mode and options
RepositoryConfig: Direct repository configuration

§readonly scopeFiltering?:ScopeFilteringConfig—

Commit scope filtering configuration. Controls how commits are attributed to projects in changelogs.
By default, hybrid filtering ensures commits are included based on conventional commit scope OR file changes within the project.

§readonly skipChangelog?:boolean—

Skip changelog update

§readonly skipGit?:boolean—

Skip git operations

§readonly skipTag?:boolean—

Skip tag creation

§readonly tagFormat?:string—

Custom tag format

§readonly trackDeps?:boolean—

Track dependencies for cascade bumps

§interface

FlowContext

Execution context passed to each step. Contains all resources and accumulated state.
Note: state is mutable within context to allow accumulation, but individual FlowState objects are immutable.

Properties

§readonly config:FlowConfig—

Flow configuration

§readonly git:GitClient—

Git client

§readonly logger:Logger—

Logger instance

§readonly packageName:string—

Package name from package.json

§readonly projectName:string—

Target project name

§readonly projectRoot:string—

Project root path

§readonly registry:Registry—

Registry client

§state:FlowState—

Accumulated state from previous steps (mutable reference)

§readonly tree:Tree—

Virtual file system tree

§readonly workspaceRoot:string—

Workspace root path

§interface

FlowResult

Complete result of flow execution.

Properties

§readonly diffs?:unknown—

Detailed diffs for pending changes. Populated when showDiff: true is passed to executeFlow. Provides unified diff format for programmatic access.

§readonly duration:number—

Duration in milliseconds

§readonly modifiedFiles?:unknown—

Files that were modified (or would be in dry-run)

§readonly state:FlowState—

Final accumulated state

§readonly status:FlowStatus—

Overall flow outcome

§readonly steps:unknown—

Results for each step

§readonly summary:string—

Summary message

§interface

FlowState

Accumulated state during flow execution. Each step can read previous state and contribute updates.

Properties

§readonly bumpType?:BumpType—

Bump type (major/minor/patch/none)

§readonly changelogEntry?:ChangelogEntry—

Generated changelog entry

§readonly classificationResult?:ClassificationResult—

Classification result with source attribution (when scope filtering enabled)

§readonly commitHash?:string—

Created git commit hash

§readonly commits?:unknown—

Analyzed commits since last release

§readonly currentVersion?:string—

Current/local version from package.json

§readonly effectiveBaseCommit?:string—

The verified base commit used for commit scoping and changelog generation. This will be publishedCommit if that commit is reachable from HEAD, or null if a fallback was used (e.g., history was rewritten).
When null, compare URLs are omitted from the changelog.

§readonly isFirstRelease?:boolean—

Whether this is a first release (no prior versions)

§readonly isPendingPublication?:boolean—

Whether this is a pending publication scenario. True when currentVersion > publishedVersion, meaning the version was already bumped but not yet published to the registry. When true:

nextVersion is calculated from publishedVersion (not currentVersion)
Changelog entries > publishedVersion should be cleaned up
The correct changelog entry replaces any stacked ones

§readonly modifiedFiles?:unknown—

Files modified during flow execution

§readonly nextVersion?:string—

Calculated next version

§readonly publishedCommit?:string—

Git commit hash of the last published version

§readonly publishedVersion?:string—

Published version on registry (null if never published)

§readonly repositoryConfig?:RepositoryConfig—

Repository configuration for compare URL generation

§readonly tagName?:string—

Created git tag name

§interface

FlowStep

A single step in a version flow.
Steps are pure functions that:

Read from context (state, config, services)
Perform work (possibly with side effects via services)
Return state updates

Properties

§readonly continueOnError?:boolean—

Whether step failure should fail the flow

§readonly dependsOn?:unknown—

Steps that must complete before this one

§readonly description?:string—

Optional step description

§readonly execute:StepExecutor—

Step function to execute

§readonly id:string—

Step identifier (unique within flow)

§readonly name:string—

Human-readable step name

§readonly skipIf?:StepCondition—

Condition for skipping step

§interface

FlowStepResult

Result of a single step execution.

Properties

§readonly error?:Error—

Error if failed

§readonly message?:string—

Descriptive message

§readonly stateUpdates?:Partial<FlowState>—

State updates from this step

§readonly status:"success" | "skipped" | "failed"—

Step outcome

§interface

FlowStepResultWithId

Step result with step identification.

Properties

§readonly error?:Error—

Error if failed

§readonly message?:string—

Descriptive message

§readonly stateUpdates?:Partial<FlowState>—

State updates from this step

§readonly status:"success" | "skipped" | "failed"—

Step outcome

§readonly stepId:string—

Step identifier

§readonly stepName:string—

Step display name

§interface

Logger

Logger interface with level-specific methods and level control

Properties

§debug:DebugLevelFn—

Debug-level output

§error:ErrorLevelFn—

Error-level output

§getLogLevel:GetLogLevel—

Gets the current log level

§info:InfoLevelFn—

Info-level output

§log:LogLevelFn—

Standard log output

§setLogLevel:SetLogLevel—

Sets the current log level

§warn:WarnLevelFn—

Warning-level output

§interface

VersionFlow

A complete version flow definition.
Flows are immutable configurations that define:

What steps to execute
In what order
With what configuration

Properties

§readonly config:FlowConfig—

Flow-level configuration

§readonly description?:string—

Flow description

§readonly id:string—

Flow identifier

§readonly name:string—

Human-readable flow name

§readonly steps:unknown—

Ordered steps to execute

◆ Types

§type

FlowStatus

Overall flow execution status.

type FlowStatus = "success" | "partial" | "failed" | "skipped"

§type

StepCondition

Step skip condition function type. Returns true if the step should be skipped.

type StepCondition = (context: FlowContext) => boolean

§type

StepExecutor

Step executor function type. Takes flow context and returns a step result promise.

type StepExecutor = (context: FlowContext) => Promise<FlowStepResult>

● Variables

§type

DEFAULT_CHANGELOG_FILENAME

Default changelog filename.

§type

DEFAULT_FLOW_CONFIG

Default flow configuration values.