0
# File Updaters
1

2
Standard Version uses a pluggable file updater system to read version information from various file formats and update them with new versions. The system supports built-in updaters for common formats and allows custom updaters for specialized file types.
3

4
## Capabilities
5

6
### Updater Resolution
7

8
Main function for resolving updaters from file paths or configuration objects.
9

10
```javascript { .api }
11
/**
12
 * Resolve updater object from file path or configuration
13
 * @param {string|Object} arg - File path string or updater configuration object
14
 * @returns {Object|false} Updater object with filename and updater, or false if invalid
15
 */
16
function resolveUpdaterObjectFromArgument(arg);
17
```
18

19
**Usage Examples:**
20

21
```javascript
22
const { resolveUpdaterObjectFromArgument } = require('standard-version/lib/updaters');
23

24
// Simple file path
25
const updater1 = resolveUpdaterObjectFromArgument('package.json');
26
console.log(updater1);
27
// { filename: 'package.json', updater: JSONUpdater }
28

29
// Configuration object with type
30
const updater2 = resolveUpdaterObjectFromArgument({
31
  filename: 'VERSION.txt',
32
  type: 'plain-text'  
33
});
34

35
// Configuration object with custom updater
36
const updater3 = resolveUpdaterObjectFromArgument({
37
  filename: 'Cargo.toml',
38
  updater: './custom-toml-updater.js'
39
});
40

41
// Direct updater object
42
const updater4 = resolveUpdaterObjectFromArgument({
43
  readVersion: (contents) => extractVersion(contents),
44
  writeVersion: (contents, version) => updateVersion(contents, version)
45
});
46
```
47

48
### Built-in Updaters
49

50
Standard Version includes built-in updaters for common file formats.
51

52
**JSON Updater:**
53

54
```javascript { .api }
55
/**
56
 * JSON file updater for package.json, manifest.json, etc.
57
 */
58
interface JSONUpdater {
59
  /**
60
   * Extract version from JSON file contents
61
   * @param {string} contents - Raw file contents
62
   * @returns {string} Version string from JSON version property
63
   */
64
  readVersion(contents: string): string;
65
  
66
  /**
67
   * Update version in JSON file contents
68
   * @param {string} contents - Raw file contents  
69
   * @param {string} version - New version to set
70
   * @returns {string} Updated file contents with new version
71
   */
72
  writeVersion(contents: string, version: string): string;
73
  
74
  /**
75
   * Check if package is marked as private
76
   * @param {string} contents - Raw file contents
77
   * @returns {boolean} True if package.private is true
78
   */
79
  isPrivate(contents: string): boolean;
80
}
81
```
82

83
**Usage Examples:**
84

85
```javascript
86
const jsonUpdater = require('standard-version/lib/updaters/types/json');
87

88
// Read version from package.json
89
const packageJson = '{"name": "my-app", "version": "1.0.0", "private": false}';
90
const currentVersion = jsonUpdater.readVersion(packageJson);
91
console.log(currentVersion); // "1.0.0"
92

93
// Update version in package.json
94
const updatedPackageJson = jsonUpdater.writeVersion(packageJson, "1.1.0");
95
console.log(updatedPackageJson); 
96
// {"name": "my-app", "version": "1.1.0", "private": false}
97

98
// Check if package is private
99
const isPrivate = jsonUpdater.isPrivate(packageJson);
100
console.log(isPrivate); // false
101

102
// Handles package-lock.json v2 format
103
const packageLock = `{
104
  "name": "my-app",
105
  "version": "1.0.0", 
106
  "packages": {
107
    "": {
108
      "version": "1.0.0"
109
    }
110
  }
111
}`;
112
const updatedLock = jsonUpdater.writeVersion(packageLock, "1.1.0");
113
// Updates both root version and packages[""].version
114
```
115

116
**Plain Text Updater:**
117

118
```javascript { .api }
119
/**
120
 * Plain text file updater for VERSION.txt, version.txt, etc.
121
 */
122
interface PlainTextUpdater {
123
  /**
124
   * Extract version from plain text file (returns entire contents)
125
   * @param {string} contents - Raw file contents
126
   * @returns {string} File contents as version
127
   */
128
  readVersion(contents: string): string;
129
  
130
  /**
131
   * Update plain text file with new version
132
   * @param {string} _contents - Raw file contents (ignored)
133
   * @param {string} version - New version to write
134
   * @returns {string} New version string as file contents
135
   */
136
  writeVersion(_contents: string, version: string): string;
137
}
138
```
139

140
**Usage Examples:**
141

142
```javascript
143
const plainTextUpdater = require('standard-version/lib/updaters/types/plain-text');
144

145
// Read version from VERSION.txt
146
const versionFile = '1.0.0\n';
147
const currentVersion = plainTextUpdater.readVersion(versionFile);
148
console.log(currentVersion); // "1.0.0\n"
149

150
// Update VERSION.txt
151
const updatedVersion = plainTextUpdater.writeVersion(versionFile, '1.1.0');
152
console.log(updatedVersion); // "1.1.0"
153
```
154

155
### Custom Updater Interface
156

157
Interface that custom updaters must implement.
158

159
```javascript { .api }
160
/**
161
 * Custom updater interface - all custom updaters must implement these methods
162
 */
163
interface CustomUpdater {
164
  /**
165
   * Extract version from file contents
166
   * @param {string} contents - Raw file contents
167
   * @returns {string} Current version extracted from file
168
   */
169
  readVersion(contents: string): string;
170
  
171
  /**
172
   * Update file contents with new version
173
   * @param {string} contents - Raw file contents
174
   * @param {string} version - New version to set
175
   * @returns {string} Updated file contents
176
   */
177
  writeVersion(contents: string, version: string): string;
178
  
179
  /**
180
   * Check if package/project is private (optional)
181
   * @param {string} contents - Raw file contents  
182
   * @returns {boolean} True if marked as private
183
   */
184
  isPrivate?(contents: string): boolean;
185
}
186
```
187

188
**Usage Examples:**
189

190
```javascript
191
// Custom TOML updater example
192
const toml = require('@iarna/toml');
193

194
const tomlUpdater = {
195
  readVersion(contents) {
196
    const parsed = toml.parse(contents);
197
    return parsed.package?.version || parsed.version;
198
  },
199
  
200
  writeVersion(contents, version) {
201
    const parsed = toml.parse(contents);
202
    if (parsed.package) {
203
      parsed.package.version = version;
204
    } else {
205
      parsed.version = version;
206
    }
207
    return toml.stringify(parsed);
208
  },
209
  
210
  isPrivate(contents) {
211
    const parsed = toml.parse(contents);
212
    return parsed.package?.private === true;
213
  }
214
};
215

216
// Custom XML updater example  
217
const { DOMParser, XMLSerializer } = require('xmldom');
218

219
const xmlUpdater = {
220
  readVersion(contents) {
221
    const doc = new DOMParser().parseFromString(contents, 'text/xml');
222
    const versionNode = doc.getElementsByTagName('version')[0];
223
    return versionNode?.textContent;
224
  },
225
  
226
  writeVersion(contents, version) {
227
    const doc = new DOMParser().parseFromString(contents, 'text/xml');
228
    const versionNode = doc.getElementsByTagName('version')[0];
229
    if (versionNode) {
230
      versionNode.textContent = version;
231
    }
232
    return new XMLSerializer().serializeToString(doc);
233
  }
234
};
235
```
236

237
### Updater Configuration
238

239
Configure updaters through bumpFiles and packageFiles options.
240

241
```javascript { .api }
242
/**
243
 * Updater configuration formats supported in bumpFiles and packageFiles
244
 */
245
type UpdaterConfig = 
246
  | string                          // Simple file path
247
  | {
248
      filename: string;             // File path
249
      type?: 'json' | 'plain-text'; // Built-in updater type
250
    }
251
  | {
252
      filename: string;             // File path
253
      updater: string;              // Path to custom updater module
254
    }
255
  | {
256
      filename: string;             // File path
257
      updater: CustomUpdater;       // Custom updater object
258
    };
259
```
260

261
**Usage Examples:**
262

263
```json
264
{
265
  "packageFiles": [
266
    "package.json",
267
    { "filename": "VERSION", "type": "plain-text" },
268
    { "filename": "pyproject.toml", "updater": "./updaters/pyproject.js" }
269
  ],
270
  "bumpFiles": [
271
    "package.json",
272
    "package-lock.json", 
273
    { "filename": "VERSION", "type": "plain-text" },
274
    { "filename": "src/version.py", "updater": "./updaters/python-version.js" },
275
    {
276
      "filename": "manifest.xml",
277
      "updater": {
278
        "readVersion": "require('./xml-reader').readVersion",
279
        "writeVersion": "require('./xml-writer').writeVersion"
280
      }
281
    }
282
  ]
283
}
284
```
285

286
### Default File Support
287

288
Standard Version automatically detects updater types for common files.
289

290
```javascript { .api }
291
/**
292
 * Default JSON files (automatically use JSON updater):
293
 * - package.json
294
 * - bower.json  
295
 * - manifest.json
296
 * - package-lock.json
297
 * - npm-shrinkwrap.json
298
 * 
299
 * Default plain text files (automatically use plain text updater):
300
 * - VERSION.txt
301
 * - version.txt
302
 */
303
const JSON_BUMP_FILES = ['package.json', 'bower.json', 'manifest.json'];
304
const PLAIN_TEXT_BUMP_FILES = ['VERSION.txt', 'version.txt'];
305
```
306

307
**Usage Examples:**
308

309
```javascript
310
// These configurations are equivalent:
311

312
// Automatic detection
313
{ "bumpFiles": ["package.json", "VERSION.txt"] }
314

315
// Explicit configuration
316
{ 
317
  "bumpFiles": [
318
    { "filename": "package.json", "type": "json" },
319
    { "filename": "VERSION.txt", "type": "plain-text" }
320
  ]
321
}
322
```
323

324
### Error Handling
325

326
Updater system provides informative error messages for common issues.
327

328
```javascript { .api }
329
/**
330
 * Common updater errors:
331
 * - Unable to locate updater for provided type
332
 * - Unsupported file provided for bumping  
333
 * - Custom updater module not found
334
 * - Invalid updater object (missing required methods)
335
 * - File read/write permissions
336
 */
337
```
338

339
**Usage Examples:**
340

341
```javascript
342
const { resolveUpdaterObjectFromArgument } = require('standard-version/lib/updaters');
343

344
try {
345
  // This will throw error for unsupported file
346
  const updater = resolveUpdaterObjectFromArgument('unsupported.xyz');
347
} catch (error) {
348
  console.error(error.message);
349
  // "Unsupported file (unsupported.xyz) provided for bumping.
350
  //  Please specify the updater `type` or use a custom `updater`."
351
}
352

353
try {
354
  // This will throw error for invalid type
355
  const updater = resolveUpdaterObjectFromArgument({
356
    filename: 'test.file',
357
    type: 'invalid-type'
358
  });
359
} catch (error) {
360
  console.error(error.message);
361
  // "Unable to locate updater for provided type (invalid-type)."
362
}
363
```
364

365
### Validation
366

367
Updater objects are validated to ensure they implement the required interface.
368

369
```javascript { .api }
370
/**
371
 * Validate updater object has required methods
372
 * @param {Object} obj - Object to validate
373
 * @returns {boolean} True if object has readVersion and writeVersion methods
374
 */
375
function isValidUpdater(obj) {
376
  return (
377
    typeof obj.readVersion === 'function' &&
378
    typeof obj.writeVersion === 'function'
379
  );
380
}
381
```
382

383
**Usage Examples:**
384

385
```javascript
386
const validUpdater = {
387
  readVersion: (contents) => '1.0.0',
388
  writeVersion: (contents, version) => version
389
};
390

391
const invalidUpdater = {
392
  readVersion: '1.0.0',  // Should be function
393
  writeVersion: (contents, version) => version
394
};
395

396
console.log(isValidUpdater(validUpdater));   // true
397
console.log(isValidUpdater(invalidUpdater)); // false
398
```