HyperFrontend
← Back to @hyperfrontend/versioning
@hyperfrontend/versioning/changelog/compare

compare

Equality checks and structural diffs for changelogs, entries, sections, items, and references.

Overview

compare/ answers two questions: are two changelogs equivalent, and where do they differ? Equality functions (isChangelogEqual, isEntryEqual, isSectionEqual, ...) perform deep value comparison ignoring incidental ordering where appropriate. Diff functions (diffChangelogs, diffEntries, summarizeDiff) produce structured ChangelogDiff reports describing added, removed, and modified pieces — useful for round-trip tests, merge conflict resolution, and changelog drift detection in CI.

See Also

API Reference

ƒ Functions

§function

diffChangelogs(source: Changelog, target: Changelog): ChangelogDiff

Computes the diff between two changelogs.

Parameters

NameTypeDescription
§source
Changelog
The source/original changelog
§target
Changelog
The target/modified changelog

Returns

ChangelogDiff
Detailed diff of changes

Example

Comparing two changelogs

const diff = diffChangelogs(mainChangelog, branchChangelog)
console.log(`Added: ${diff.added.length}, Removed: ${diff.removed.length}`)
§function

diffEntries(source: ChangelogEntry, target: ChangelogEntry): EntryDiff

Computes the diff between two changelog entries.

Parameters

NameTypeDescription
§source
ChangelogEntry
The source entry
§target
ChangelogEntry
The target entry

Returns

EntryDiff
Detailed entry diff

Example

Computing diff between two entries

const diff = diffEntries(entryV1, entryV2)
// => { version: '1.0.0', changes: [{ path: ['date'], type: 'changed', ... }], sectionsChanged: true }
§function

getEntryByVersion(changelog: Changelog, version: string): ChangelogEntry

Gets an entry by version from a changelog.

Parameters

NameTypeDescription
§changelog
Changelog
The changelog to search
§version
string
The version to find

Returns

ChangelogEntry
The entry if found, undefined otherwise

Example

Getting an entry by version

const entry = getEntryByVersion(changelog, '1.0.0')
// => ChangelogEntry for 1.0.0 or undefined
§function

hasVersion(changelog: Changelog, version: string): boolean

Checks if a changelog contains a specific version.

Parameters

NameTypeDescription
§changelog
Changelog
The changelog to search
§version
string
The version to look for

Returns

boolean
True if the version exists in the changelog

Example

Checking if a changelog contains a version

hasVersion(changelog, '2.0.0')
// => true if an entry for version 2.0.0 exists
§function

haveSameVersions(a: Changelog, b: Changelog): boolean

Checks if two changelogs have the same entries (by version). Does not compare entry contents, only versions present.

Parameters

NameTypeDescription
§a
Changelog
First changelog
§b
Changelog
Second changelog

Returns

boolean
True if both changelogs have the same versions

Example

Checking if changelogs have the same versions

haveSameVersions(changelog1, changelog2)
// => true if both have entries for the same version strings
§function

isChangelogEqual(a: Changelog, b: Changelog): boolean

Checks if two changelogs are structurally identical.

Parameters

NameTypeDescription
§a
Changelog
First changelog
§b
Changelog
Second changelog

Returns

boolean
True if changelogs are identical

Example

Checking changelog equality

if (isChangelogEqual(mainChangelog, branchChangelog)) {
  console.log('Changelogs are identical')
}
§function

isCommitRefEqual(a: CommitRef, b: CommitRef): boolean

Checks if two commit references are equal.

Parameters

NameTypeDescription
§a
CommitRef
First commit ref
§b
CommitRef
Second commit ref

Returns

boolean
True if commit refs are equal

Example

Comparing commit references

isCommitRefEqual(commitA, commitB)
// => true if hash, shortHash, and url match
§function

isEntryEqual(a: ChangelogEntry, b: ChangelogEntry): boolean

Checks if two changelog entries are equal.

Parameters

NameTypeDescription
§a
ChangelogEntry
First entry
§b
ChangelogEntry
Second entry

Returns

boolean
True if entries are equal

Example

Comparing changelog entries

isEntryEqual(entryA, entryB)
// => true if version, date, sections, and all nested data match
§function

isHeaderEqual(a: ChangelogHeader, b: ChangelogHeader): boolean

Checks if two changelog headers are equal.

Parameters

NameTypeDescription
§a
ChangelogHeader
First header
§b
ChangelogHeader
Second header

Returns

boolean
True if headers are equal

Example

Comparing changelog headers

isHeaderEqual(changelog1.header, changelog2.header)
// => true if titles, descriptions, and links match
§function

isIssueRefEqual(a: IssueRef, b: IssueRef): boolean

Checks if two issue references are equal.

Parameters

NameTypeDescription
§a
IssueRef
First issue ref
§b
IssueRef
Second issue ref

Returns

boolean
True if issue refs are equal

Example

Comparing issue references

isIssueRefEqual({ number: 42, type: 'issue' }, { number: 42, type: 'issue' })
// => true
§function

isItemEqual(a: ChangelogItem, b: ChangelogItem): boolean

Checks if two changelog items are equal.

Parameters

NameTypeDescription
§a
ChangelogItem
First item
§b
ChangelogItem
Second item

Returns

boolean
True if items are equal

Example

Comparing changelog items

isItemEqual(itemA, itemB)
// => true if description, scope, breaking, commits, and references match
§function

isLinkEqual(a: ChangelogLink, b: ChangelogLink): boolean

Checks if two changelog links are equal.

Parameters

NameTypeDescription
§a
ChangelogLink
First link
§b
ChangelogLink
Second link

Returns

boolean
True if links are equal

Example

Comparing changelog links

isLinkEqual({ label: '1.0.0', url: '...' }, { label: '1.0.0', url: '...' })
// => true
§function

isMetadataEqual(a: ChangelogMetadata, b: ChangelogMetadata): boolean

Checks if two changelog metadata objects are equal.

Parameters

NameTypeDescription
§a
ChangelogMetadata
First metadata
§b
ChangelogMetadata
Second metadata

Returns

boolean
True if metadata are equal

Example

Comparing changelog metadata

isMetadataEqual(changelog1.metadata, changelog2.metadata)
// => true if format, isConventional, repositoryUrl, and warnings match
§function

isSectionEqual(a: ChangelogSection, b: ChangelogSection): boolean

Checks if two changelog sections are equal.

Parameters

NameTypeDescription
§a
ChangelogSection
First section
§b
ChangelogSection
Second section

Returns

boolean
True if sections are equal

Example

Comparing changelog sections

isSectionEqual(featuresA, featuresB)
// => true if type, heading, and all items match
§function

summarizeDiff(diff: ChangelogDiff): string

Creates a human-readable summary of a changelog diff.

Parameters

NameTypeDescription
§diff
ChangelogDiff
The diff to summarize

Returns

string
A string summary of the changes

Example

Creating human-readable diff summary

const diff = diffChangelogs(oldChangelog, newChangelog)
summarizeDiff(diff)
// => 'Added 2 version(s): 1.2.0, 1.1.0; Modified 1 version(s): 1.0.0'

◈ Interfaces

§interface

ChangelogDiff

Represents the diff between two changelogs.

Properties

§readonly added:unknown—
Entries added in target but not in source
§readonly identical:boolean—
Whether changelogs are structurally identical
§readonly modified:unknown—
Entries present in both but with differences
§readonly removed:unknown—
Entries removed from source but not in target
§readonly stats:DiffStats—
Summary statistics
§interface

DiffStats

Statistics about the diff.

Properties

§readonly addedCount:number—
Number of added entries
§readonly modifiedCount:number—
Number of modified entries
§readonly removedCount:number—
Number of removed entries
§readonly totalChanges:number—
Total number of property changes across all modified entries
§interface

EntryDiff

Represents differences in a single entry.

Properties

§readonly addedSections:unknown—
Sections added in target
§readonly changes:unknown—
List of property differences
§readonly modifiedSections:unknown—
Sections that were modified
§readonly removedSections:unknown—
Sections removed from source
§readonly source:ChangelogEntry—
Original entry (from source)
§readonly target:ChangelogEntry—
Modified entry (from target)
§readonly version:string—
Version of the entry
§interface

ItemDiff

Represents differences in a single item.

Properties

§readonly changes:unknown—
List of property changes
§readonly source:ChangelogItem—
Source item
§readonly sourceDescription:string—
Description from source
§readonly target:ChangelogItem—
Target item
§interface

PropertyDiff

Represents a single property difference.

Properties

§readonly newValue?:unknown—
New value (for 'added' and 'changed')
§readonly oldValue?:unknown—
Previous value (for 'removed' and 'changed')
§readonly path:unknown—
Path to the property (e.g., ['date'], ['sections', '0', 'heading'])
§readonly type:"added" | "changed" | "removed"—
Type of change
§interface

SectionDiff

Represents differences in a single section.

Properties

§readonly addedItems:unknown—
Items added in target
§readonly modifiedItems:unknown—
Items that were modified
§readonly removedItems:unknown—
Items removed from source
§readonly source:ChangelogSection—
Original section (from source)
§readonly target:ChangelogSection—
Modified section (from target)
§readonly type:string—
Section type