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

serialize

Serializers that convert structured Changelog objects back to Keep-a-Changelog markdown or to JSON.

serializeChangelog produces a stable, deterministic markdown rendering driven by SerializeOptions (heading style, bullet markers, link references, spacing). Helpers (getSectionHeading, formatLink, getListMarker, createSpacing) expose the underlying templating primitives for downstream tools that want to format individual fragments. serializeChangelogToJson and toJsonObject produce a JsonSerializeOptions-controlled JSON shape suitable for archiving or for tools that prefer structured data over markdown.

API Reference

ƒ Functions

§function

createSpacing(count: number, lineEnding: string): string

Creates blank lines for spacing.

Parameters

NameTypeDescription
§count
number
Number of blank lines
§lineEnding
string
Line ending style

Returns

string
String with specified number of blank lines

Example

Creating blank line spacing

createSpacing(2, '\n')
// => '\n\n'
§function

getListMarker(useAsterisks: boolean): string

Creates a list item marker.

Parameters

NameTypeDescription
§useAsterisks
boolean
Whether to use * instead of -

Returns

string
The list item marker ('- ' or '* ')

Example

Getting list markers

getListMarker(false) // => '- '
getListMarker(true)  // => '* '
§function

getSectionHeading(type: ChangelogSectionType, customHeadings?: Partial<Record<ChangelogSectionType, string>>): string

Gets the heading for a section type, respecting custom headings.

Parameters

NameTypeDescription
§type
ChangelogSectionType
The changelog section type to get the heading for
§customHeadings?
Partial<Record<ChangelogSectionType, string>>
Optional map of custom section type to heading overrides

Returns

string
The heading string to use

Example

Getting section headings

getSectionHeading('features')
// => 'Added'

getSectionHeading('features', { features: 'New Features' })
// => 'New Features'
§function

resolveOptions(options?: SerializeOptions): Required<SerializeOptions>

Merges user options with defaults.

Parameters

NameTypeDescription
§options?
SerializeOptions
User-provided options

Returns

Required<SerializeOptions>
Complete options with defaults applied

Example

Resolving serialize options with defaults

const opts = resolveOptions({ includeCommits: true })
// => { includeCommits: true, includeScope: true, lineEnding: '\n', ... }
§function

serializeChangelog(changelog: Changelog, options?: SerializeOptions): string

Serializes a Changelog object to markdown string.

Parameters

NameTypeDescription
§changelog
Changelog
The changelog to serialize
§options?
SerializeOptions
Optional serialization options

Returns

string
The markdown string representation

Examples

Basic serialization

const markdown = serializeChangelog(changelog)

Serializing with custom options

const markdown = serializeChangelog(changelog, {
  includeCommits: false,
  useAsterisks: true,
})
§function

serializeChangelogToJson(changelog: Changelog, options?: JsonSerializeOptions): string

Serializes a Changelog object to JSON string.

Parameters

NameTypeDescription
§changelog
Changelog
The changelog object to convert to JSON
§options?
JsonSerializeOptions
Optional JSON serialization options

Returns

string
The JSON string representation

Examples

Basic JSON serialization

const json = serializeChangelogToJson(changelog)

Pretty-printing with custom indentation

const json = serializeChangelogToJson(changelog, {
  pretty: true,
  indent: 4,
})
§function

toJsonObject(changelog: Changelog, options?: JsonSerializeOptions): Record<string, unknown>

Converts a Changelog to a plain JSON-serializable object. Useful when you need the object itself rather than a string.

Parameters

NameTypeDescription
§changelog
Changelog
The changelog to convert
§options?
JsonSerializeOptions
Optional JSON serialization options

Returns

Record<string, unknown>
A plain object suitable for JSON serialization

Example

Converting changelog to plain object

const obj = toJsonObject(changelog, { includeSource: true })
// => { source: 'CHANGELOG.md', header: { title: '...', ... }, entries: [...] }

// Send as API response
res.json(obj)

◈ Interfaces

§interface

JsonSerializeOptions

JSON serialization options.

Properties

§readonly includeEmptyArrays?:boolean—
Include empty arrays
§readonly includeMetadata?:boolean—
Include metadata in output
§readonly includeSource?:boolean—
Include source path in output
§readonly indent?:number—
Indentation size (for pretty printing)
§readonly pretty?:boolean—
Pretty print with indentation
§interface

SerializeOptions

Serialization options for controlling output format.

Properties

§readonly entrySpacing?:number—
Number of blank lines between entries
§readonly includeCommits?:boolean—
Include commit references
§readonly includeCompareUrls?:boolean—
Include compare URLs for entries
§readonly includeDescription?:boolean—
Include preamble description in header
§readonly includeLinks?:boolean—
Include links section
§readonly includeRawContent?:boolean—
Include raw content fallback
§readonly includeReferences?:boolean—
Include issue/PR references
§readonly includeScope?:boolean—
Include scope in items
§readonly lineEnding?:" " | " "—
Line ending style
§readonly sectionHeadings?:Partial<Record<ChangelogSectionType, string>>—
Custom section headings (overrides defaults)
§readonly sectionOrder?:unknown—
Section ordering (defaults to standard order)
§readonly sectionSpacing?:number—
Number of blank lines between sections
§readonly useAsterisks?:boolean—
Use asterisks (*) instead of dashes (-) for list items

● Variables

§type

DEFAULT_SERIALIZE_OPTIONS

Default serialization options.