0
# StandardChangelog API
1

2
The StandardChangelog class provides programmatic access to changelog generation with Angular commit conventions pre-configured.
3

4
## Capabilities
5

6
### Constructor
7

8
Creates a new StandardChangelog instance with Angular preset automatically configured.
9

10
```typescript { .api }
11
/**
12
 * Creates a StandardChangelog instance with Angular preset pre-configured
13
 * @param cwdOrGitClient - Working directory path or ConventionalGitClient instance (required)
14
 */
15
constructor(cwdOrGitClient: string | ConventionalGitClient)
16
```
17

18
**Usage Examples:**
19

20
```typescript
21
import { StandardChangelog } from "standard-changelog";
22

23
// Using current working directory  
24
const generator = new StandardChangelog(process.cwd());
25

26
// Using specific directory
27
const generator = new StandardChangelog("/path/to/repo");
28

29
// Using existing git client
30
import { ConventionalGitClient } from "@conventional-changelog/git-client";
31
const gitClient = new ConventionalGitClient("/path/to/repo");
32
const generator = new StandardChangelog(gitClient);
33
```
34

35
### Configuration Methods
36

37
Methods for configuring the changelog generation process.
38

39
```typescript { .api }
40
/**
41
 * Load configuration from a preset
42
 * @param preset - Preset parameters
43
 * @returns this for method chaining
44
 */
45
loadPreset<PresetCreatorParams extends UnknownPresetCreatorParams = UnknownPresetCreatorParams>(
46
  preset: PresetParams<PresetCreatorParams>
47
): this;
48

49
/**
50
 * Set configuration directly
51
 * @param config - Configuration object or promise
52
 * @returns this for method chaining
53
 */
54
config(config: Preset | Promise<Preset>): this;
55

56
/**
57
 * Find and read package.json automatically
58
 * @param transform - Optional transform function for package data
59
 * @returns this for method chaining
60
 */
61
readPackage(transform?: PackageTransform): this;
62

63
/**
64
 * Read package.json from specific path
65
 * @param path - Path to package.json file
66
 * @param transform - Optional transform function for package data
67
 * @returns this for method chaining
68
 */
69
readPackage(path?: string, transform?: PackageTransform): this;
70

71
/**
72
 * Set package.json data directly
73
 * @param pkg - Package data object
74
 * @returns this for method chaining
75
 */
76
package(pkg: Record<string, unknown>): this;
77

78
/**
79
 * Read repository info from current git repository
80
 * @returns this for method chaining
81
 */
82
readRepository(): this;
83

84
/**
85
 * Set repository information
86
 * @param infoOrGitUrl - Repository info object or git URL
87
 * @returns this for method chaining
88
 */
89
repository(infoOrGitUrl: string | Partial<HostedGitInfo>): this;
90

91
/**
92
 * Set changelog generation options
93
 * @param options - Generation options
94
 * @returns this for method chaining
95
 */
96
options(options: Options): this;
97

98
/**
99
 * Set writer context data
100
 * @param context - Context data for template rendering
101
 * @returns this for method chaining
102
 */
103
context(context: Context): this;
104

105
/**
106
 * Configure semver tag parameters
107
 * @param params - Parameters for semver tag retrieval
108
 * @returns this for method chaining
109
 */
110
tags(params: GetSemverTagsParams): this;
111

112
/**
113
 * Configure commit retrieval parameters
114
 * @param params - Parameters for commit retrieval
115
 * @param parserOptions - Optional parser configuration
116
 * @returns this for method chaining
117
 */
118
commits(params: GetCommitsParams, parserOptions?: ParserStreamOptions): this;
119

120
/**
121
 * Configure writer options
122
 * @param params - Writer configuration options
123
 * @returns this for method chaining
124
 */
125
writer(params: WriterOptions): this;
126
```
127

128
### Generation Methods
129

130
Methods for generating changelog content.
131

132
```typescript { .api }
133
/**
134
 * Generate changelog as string chunks
135
 * @returns Async generator yielding string chunks
136
 */
137
write(): AsyncGenerator<string, void>;
138

139
/**
140
 * Generate changelog with detailed data objects
141
 * @param includeDetails - When true, returns data objects instead of strings
142
 * @returns Async generator yielding Details objects
143
 */
144
write(includeDetails: true): AsyncGenerator<Details<Commit>, void>;
145

146
/**
147
 * Generate changelog as readable stream
148
 * @param includeDetails - Optional flag to include detailed data objects
149
 * @returns Readable stream of changelog content
150
 */
151
writeStream(includeDetails?: boolean): Readable;
152
```
153

154
**Usage Examples:**
155

156
```typescript
157
import { StandardChangelog } from "standard-changelog";
158

159
// Basic changelog generation
160
const generator = new StandardChangelog()
161
  .readPackage()
162
  .options({ releaseCount: 1 });
163

164
// Generate as async iterator
165
for await (const chunk of generator.write()) {
166
  process.stdout.write(chunk);
167
}
168

169
// Generate as stream
170
generator.writeStream().pipe(process.stdout);
171

172
// Generate with details
173
const detailsGenerator = generator.write(true);
174
for await (const details of detailsGenerator) {
175
  console.log('Log chunk:', details.log);
176
  console.log('Commit data:', details.data);
177
}
178

179
// Complex configuration example
180
const complexGenerator = new StandardChangelog("/path/to/repo")
181
  .readPackage((pkg) => ({ ...pkg, name: "custom-name" }))
182
  .options({
183
    releaseCount: 3,
184
    append: false,
185
    outputUnreleased: true
186
  })
187
  .tags({ prefix: "v" })
188
  .commits({ from: "v1.0.0" });
189
```
190

191
## Configuration Types
192

193
```typescript { .api }
194
interface Options {
195
  reset?: boolean;
196
  append?: boolean;
197
  releaseCount?: number;
198
  outputUnreleased?: boolean;
199
  transformCommit?: CommitTransformFunction;
200
  warn?: Logger;
201
  debug?: Logger;
202
  formatDate?(date: Date): string;
203
}
204

205
interface Preset {
206
  tags?: GetSemverTagsParams;
207
  commits?: GetCommitsParams;
208
  parser?: ParserStreamOptions;
209
  writer?: WriterOptions;
210
}
211

212
interface HostedGitInfo {
213
  url: string;
214
  type: 'github' | 'gitlab' | 'bitbucket' | 'sourcehut' | '';
215
  host: string;
216
  owner?: string;
217
  project?: string;
218
}
219

220
type PackageTransform = (pkg: Package) => Package;
221

222
type CommitTransformFunction = (
223
  commit: Commit,
224
  params: Params
225
) => Partial<Commit> | null | Promise<Partial<Commit> | null>;
226
```