@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

Name	Type	Description
§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'

View source →

§function

formatLink(text: string, url: string): string

Creates a markdown link.

Parameters

Name	Type	Description
§text	`string`	The display text for the link
§url	`string`	The destination URL for the link

Returns

string

Formatted markdown link

Example

Formatting a markdown link

formatLink('1.0.0', 'https://github.com/org/repo/releases/tag/v1.0.0')
// => '[1.0.0](https://github.com/org/repo/releases/tag/v1.0.0)'

View source →

§function

getListMarker(useAsterisks: boolean): string

Creates a list item marker.

Parameters

Name	Type	Description
§useAsterisks	`boolean`	Whether to use * instead of -

Returns

string

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

Example

Getting list markers

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

View source →

§function

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

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

Parameters

Name	Type	Description
§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'

View source →

§function

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

Merges user options with defaults.

Parameters

Name	Type	Description
§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', ... }

View source →

§function

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

Serializes a Changelog object to markdown string.

Parameters

Name	Type	Description
§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,
})

View source →

§function

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

Serializes a Changelog object to JSON string.

Parameters

Name	Type	Description
§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,
})

View source →

§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

Name	Type	Description
§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)

View source →

◈ Interfaces

§interface

JsonSerializeOptions

JSON serialization options.

Properties

§readonly pretty?:booleanPretty print with indentation

§readonly indent?:numberIndentation size (for pretty printing)

§readonly includeSource?:booleanInclude source path in output

§readonly includeMetadata?:booleanInclude metadata in output

§readonly includeEmptyArrays?:booleanInclude empty arrays

View source →

§interface

SerializeOptions

Serialization options for controlling output format.

Properties

§readonly includeDescription?:booleanInclude preamble description in header

§readonly includeLinks?:booleanInclude links section

§readonly includeCompareUrls?:booleanInclude compare URLs for entries

§readonly includeCommits?:booleanInclude commit references

§readonly includeReferences?:booleanInclude issue/PR references

§readonly includeScope?:booleanInclude scope in items

§readonly includeRawContent?:booleanInclude raw content fallback

§readonly sectionOrder?:unknownSection ordering (defaults to standard order)

§readonly sectionHeadings?:Partial<Record<ChangelogSectionType, string>>Custom section headings (overrides defaults)

§readonly lineEnding?:

"
" | "
"

Line ending style

§readonly entrySpacing?:numberNumber of blank lines between entries

§readonly sectionSpacing?:numberNumber of blank lines between sections

§readonly useAsterisks?:booleanUse asterisks (*) instead of dashes (-) for list items

View source →

● Variables

§type

DEFAULT_SERIALIZE_OPTIONS

Default serialization options.

View source →