File Updaters

/**
 * Resolve updater object from file path or configuration
 * @param {string|Object} arg - File path string or updater configuration object
 * @returns {Object|false} Updater object with filename and updater, or false if invalid
 */
function resolveUpdaterObjectFromArgument(arg);

const { resolveUpdaterObjectFromArgument } = require('standard-version/lib/updaters');

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

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

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

// Direct updater object
const updater4 = resolveUpdaterObjectFromArgument({
  readVersion: (contents) => extractVersion(contents),
  writeVersion: (contents, version) => updateVersion(contents, version)
});

/**
 * JSON file updater for package.json, manifest.json, etc.
 */
interface JSONUpdater {
  /**
   * Extract version from JSON file contents
   * @param {string} contents - Raw file contents
   * @returns {string} Version string from JSON version property
   */
  readVersion(contents: string): string;
  
  /**
   * Update version in JSON file contents
   * @param {string} contents - Raw file contents  
   * @param {string} version - New version to set
   * @returns {string} Updated file contents with new version
   */
  writeVersion(contents: string, version: string): string;
  
  /**
   * Check if package is marked as private
   * @param {string} contents - Raw file contents
   * @returns {boolean} True if package.private is true
   */
  isPrivate(contents: string): boolean;
}

const jsonUpdater = require('standard-version/lib/updaters/types/json');

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

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

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

// Handles package-lock.json v2 format
const packageLock = `{
  "name": "my-app",
  "version": "1.0.0", 
  "packages": {
    "": {
      "version": "1.0.0"
    }
  }
}`;
const updatedLock = jsonUpdater.writeVersion(packageLock, "1.1.0");
// Updates both root version and packages[""].version

/**
 * Plain text file updater for VERSION.txt, version.txt, etc.
 */
interface PlainTextUpdater {
  /**
   * Extract version from plain text file (returns entire contents)
   * @param {string} contents - Raw file contents
   * @returns {string} File contents as version
   */
  readVersion(contents: string): string;
  
  /**
   * Update plain text file with new version
   * @param {string} _contents - Raw file contents (ignored)
   * @param {string} version - New version to write
   * @returns {string} New version string as file contents
   */
  writeVersion(_contents: string, version: string): string;
}

const plainTextUpdater = require('standard-version/lib/updaters/types/plain-text');

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

// Update VERSION.txt
const updatedVersion = plainTextUpdater.writeVersion(versionFile, '1.1.0');
console.log(updatedVersion); // "1.1.0"

/**
 * Custom updater interface - all custom updaters must implement these methods
 */
interface CustomUpdater {
  /**
   * Extract version from file contents
   * @param {string} contents - Raw file contents
   * @returns {string} Current version extracted from file
   */
  readVersion(contents: string): string;
  
  /**
   * Update file contents with new version
   * @param {string} contents - Raw file contents
   * @param {string} version - New version to set
   * @returns {string} Updated file contents
   */
  writeVersion(contents: string, version: string): string;
  
  /**
   * Check if package/project is private (optional)
   * @param {string} contents - Raw file contents  
   * @returns {boolean} True if marked as private
   */
  isPrivate?(contents: string): boolean;
}

// Custom TOML updater example
const toml = require('@iarna/toml');

const tomlUpdater = {
  readVersion(contents) {
    const parsed = toml.parse(contents);
    return parsed.package?.version || parsed.version;
  },
  
  writeVersion(contents, version) {
    const parsed = toml.parse(contents);
    if (parsed.package) {
      parsed.package.version = version;
    } else {
      parsed.version = version;
    }
    return toml.stringify(parsed);
  },
  
  isPrivate(contents) {
    const parsed = toml.parse(contents);
    return parsed.package?.private === true;
  }
};

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

const xmlUpdater = {
  readVersion(contents) {
    const doc = new DOMParser().parseFromString(contents, 'text/xml');
    const versionNode = doc.getElementsByTagName('version')[0];
    return versionNode?.textContent;
  },
  
  writeVersion(contents, version) {
    const doc = new DOMParser().parseFromString(contents, 'text/xml');
    const versionNode = doc.getElementsByTagName('version')[0];
    if (versionNode) {
      versionNode.textContent = version;
    }
    return new XMLSerializer().serializeToString(doc);
  }
};

/**
 * Updater configuration formats supported in bumpFiles and packageFiles
 */
type UpdaterConfig = 
  | string                          // Simple file path
  | {
      filename: string;             // File path
      type?: 'json' | 'plain-text'; // Built-in updater type
    }
  | {
      filename: string;             // File path
      updater: string;              // Path to custom updater module
    }
  | {
      filename: string;             // File path
      updater: CustomUpdater;       // Custom updater object
    };

{
  "packageFiles": [
    "package.json",
    { "filename": "VERSION", "type": "plain-text" },
    { "filename": "pyproject.toml", "updater": "./updaters/pyproject.js" }
  ],
  "bumpFiles": [
    "package.json",
    "package-lock.json", 
    { "filename": "VERSION", "type": "plain-text" },
    { "filename": "src/version.py", "updater": "./updaters/python-version.js" },
    {
      "filename": "manifest.xml",
      "updater": {
        "readVersion": "require('./xml-reader').readVersion",
        "writeVersion": "require('./xml-writer').writeVersion"
      }
    }
  ]
}

/**
 * Default JSON files (automatically use JSON updater):
 * - package.json
 * - bower.json  
 * - manifest.json
 * - package-lock.json
 * - npm-shrinkwrap.json
 * 
 * Default plain text files (automatically use plain text updater):
 * - VERSION.txt
 * - version.txt
 */
const JSON_BUMP_FILES = ['package.json', 'bower.json', 'manifest.json'];
const PLAIN_TEXT_BUMP_FILES = ['VERSION.txt', 'version.txt'];

// These configurations are equivalent:

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

// Explicit configuration
{ 
  "bumpFiles": [
    { "filename": "package.json", "type": "json" },
    { "filename": "VERSION.txt", "type": "plain-text" }
  ]
}

/**
 * Common updater errors:
 * - Unable to locate updater for provided type
 * - Unsupported file provided for bumping  
 * - Custom updater module not found
 * - Invalid updater object (missing required methods)
 * - File read/write permissions
 */

const { resolveUpdaterObjectFromArgument } = require('standard-version/lib/updaters');

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

try {
  // This will throw error for invalid type
  const updater = resolveUpdaterObjectFromArgument({
    filename: 'test.file',
    type: 'invalid-type'
  });
} catch (error) {
  console.error(error.message);
  // "Unable to locate updater for provided type (invalid-type)."
}

/**
 * Validate updater object has required methods
 * @param {Object} obj - Object to validate
 * @returns {boolean} True if object has readVersion and writeVersion methods
 */
function isValidUpdater(obj) {
  return (
    typeof obj.readVersion === 'function' &&
    typeof obj.writeVersion === 'function'
  );
}

const validUpdater = {
  readVersion: (contents) => '1.0.0',
  writeVersion: (contents, version) => version
};

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

console.log(isValidUpdater(validUpdater));   // true
console.log(isValidUpdater(invalidUpdater)); // false