@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 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

View source →

§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

View source →

● Variables

§type

DEFAULT_SERIALIZE_OPTIONS

Default serialization options.

View source →