operations

const newChangelog = addEntry(changelog, {
  version: '1.2.0',
  date: '2024-01-15',
  unreleased: false,
  sections: [...]
})

const item = { description: 'Add dark mode support', scope: 'ui' }
const updated = addItemToEntry(changelog, '1.2.0', 'features', item)
// Item added to the features section of version 1.2.0

const sections = [createChangelogSection('features', 'Added', [item])]
const updated = addUnreleasedEntry(changelog, sections)
// => Changelog with unreleased entry at the top

const combined = appendChangelog(mainChangelog, newChangelog, 'start')
// newChangelog entries appear before mainChangelog entries

const copy = cloneChangelog(changelog)
// Independent deep copy, safe to mutate

const unified = combineChangelogs([pkg1Changelog, pkg2Changelog], {
  strategy: 'merge-sections',
})
// All entries from both changelogs merged with conflict resolution

const compacted = compact(changelog)
// Empty sections and entries removed (unreleased kept)

const strict = compact(changelog, false)
// Even empty unreleased entry is removed

const deduped = deduplicateItems(changelog)
// Duplicate items (same scope:description) are removed

const publicChanges = excludeByScope(changelog, ['internal', 'test'])
// Items scoped to 'internal' or 'test' are removed

const breaking = filterBreakingChanges(changelog)
// Only entries containing breaking changes or items marked as breaking

const q1 = filterByDateRange(changelog, '2024-01-01', '2024-03-31')
// Entries released in Q1 2024

const apiChanges = filterByScope(changelog, ['api', 'core'])
// Only items scoped to 'api' or 'core'

const majors = filterByVersionRange(changelog, '>=1.0.0 <2.0.0')

const filtered = filterEntries(changelog, (entry) => !entry.unreleased)

const recent = filterFromVersion(changelog, '2.0.0')
// Only entries for version 2.0.0 and later

const withRefs = filterItems(changelog, (item) => item.references.length > 0)
// Only items with issue/PR references

const latest = filterRecentEntries(changelog, 5)
// Last 5 released versions (plus unreleased if present)

const userFacing = filterSections(changelog, (section) =>
  ['features', 'fixes', 'breaking'].includes(section.type)
)

const userChanges = filterSectionTypes(changelog, ['features', 'fixes'])
// Only features and fixes sections remain

const legacy = filterToVersion(changelog, '1.9.9')
// Only entries for versions up to 1.9.9

const range = filterVersionRange(changelog, '1.5.0', '2.0.0')
// Entries from 1.5.0 through 2.0.0

const result = mergeChangelogs(mainChangelog, branchChangelog)
console.log(`Merged ${result.stats.merged} entries`)

const normalized = normalizeSectionHeadings(changelog)
// 'New Features' becomes 'Added', 'Bug Fixes' becomes 'Fixed', etc.

const released = releaseUnreleased(changelog, '2.0.0', '2024-03-01')
// Unreleased entry becomes version 2.0.0 with the specified date

const cleaned = removeEmptyEntries(changelog)
// Entries with no content are removed (unreleased kept by default)

const strict = removeEmptyEntries(changelog, false)
// Even empty unreleased entry is removed

const cleaned = removeEmptySections(changelog)
// Sections with no items are removed from all entries

const cleaned = removeEntries(changelog, ['0.1.0', '0.2.0'])
// Pre-release versions removed from changelog

const newChangelog = removeEntry(changelog, '1.0.0')

const updated = removeItem(changelog, '1.0.0', 'features', 'Add dark mode')
// The 'Add dark mode' item is removed from features in 1.0.0

const updated = removeSection(changelog, '1.0.0', 'deprecated')
// Version 1.0.0 no longer has a deprecated section

const released = removeUnreleased(changelog)
// Changelog without the unreleased entry

// Silently ignore if not found
const safe = removeUnreleased(changelog, { throwIfNotFound: false })

const reversed = reverseEntries(changelog)
// Oldest entries now appear first

const sorted = sortEntries(changelog)
// Entries ordered: Unreleased, 2.0.0, 1.1.0, 1.0.0, ...

const sorted = sortEntriesByDate(changelog)
// Entries ordered by release date, most recent first

const sorted = sortSections(changelog)
// Sections in each entry follow: breaking, features, fixes, ...

const custom = sortSections(changelog, ['fixes', 'features', 'breaking'])
// Custom ordering: fixes first, then features, then breaking

const stripped = stripMetadata(changelog)
// Source and warnings removed, only format and isConventional retained

const transformed = transformEntries(changelog, (entry) => ({
  ...entry,
  date: entry.date?.toUpperCase()
}))

const prefixed = transformItems(changelog, (item) => ({
  ...item,
  description: `[${item.scope || 'misc'}] ${item.description}`,
}))

const renamed = transformSections(changelog, (section) => ({
  ...section,
  heading: section.heading.toUpperCase(),
}))

const updated = updateEntry(changelog, '1.0.0', { date: '2024-01-15' })

// Or with transformer function
const modified = updateEntry(changelog, '1.0.0', (entry) => ({
  ...entry,
  compareUrl: `https://github.com/org/repo/compare/v0.9.0...v${entry.version}`,
}))

const updated = updateHeader(changelog, { title: '# Release Notes' })

const updated = updateMetadata(changelog, { repositoryUrl: 'https://github.com/org/repo' })