properties-file parser & editor

Common errors

• TypeError: (0 , properties_file_1.PropertiesEditor) is not a constructor

  cause Attempting to import `PropertiesEditor` from the root `properties-file` module instead of its specific subpath.
  fix Change your import statement to `import { PropertiesEditor } from 'properties-file/editor'`.

• Module not found: Error: Can't resolve 'properties-file/webpack-loader' in '...' OR Cannot find module 'properties-file/webpack-loader'

  cause Using the old Webpack loader path which was changed in v4.0.0.
  fix Update the import or configuration path for the Webpack loader to `properties-file/bundler/webpack`.

• Property 'someMethod' does not exist on type 'Properties'.

  cause Attempting to use methods or properties on the `Properties` class that existed in v3.x or prior, or expecting it to behave like a simple key-value object after v5.0.0's lossless model change.
  fix For basic key-value access, use `getProperties()`. For the `Properties` class (v5+), interact with its `nodes` array for granular control and use `format()` to generate output, or refer to TSDoc for available methods on the lossless data model.

Warnings

• breaking The Webpack loader export path changed from `properties-file/webpack-loader` to `properties-file/bundler/webpack`.
  Fix: Update your Webpack configuration or import statements to use `properties-file/bundler/webpack`.
• breaking Version 5.0.0 introduced a significant architectural change to a lossless data model for the `Properties` class. This means every element (properties, comments, blank lines, whitespace, duplicate keys) is preserved as typed nodes. While this enables exact reconstruction and powerful transformations, code directly manipulating the internal structure of `Properties` instances or expecting a simple key-value object from `new Properties()` will break.
  Fix: Review the migration guide for v5.0.0. Use `getProperties()` for simple key-value object conversion. For advanced use cases, interact with `Properties` via its `nodes` array and `format()` method, leveraging new options like `deduplicateKeys`.
• gotcha When deleting duplicate keys, the default behavior of `delete()` removes the *last* occurrence. If you need to remove the first or a specific occurrence, you must explicitly use the `occurrence` option.
  Fix: To delete the first occurrence of a duplicate key, use `editor.delete(key, { occurrence: 'first' })`.

Install

• npm install properties-file npm
• yarn add properties-file yarn
• pnpm add properties-file pnpm

Imports

• getProperties
  wrong:

  const { getProperties } = require('properties-file')

  correct:

  import { getProperties } from 'properties-file'

  This is the entry point for quickly converting .properties content to a key-value object. While ES5 compatible, modern Node.js and browser environments should use ESM imports.
• Properties
  wrong:

  import { Properties } from 'properties-file'

  correct:

  import { Properties } from 'properties-file/parser'

  The `Properties` class for lossless parsing and full data model access is exposed via the specific `/parser` subpath. Incorrectly importing from the root `properties-file` path will result in undefined or incomplete access.
• PropertiesEditor
  wrong:

  import { PropertiesEditor } from 'properties-file'

  correct:

  import { PropertiesEditor } from 'properties-file/editor'

  The `PropertiesEditor` for modifying properties files while preserving formatting is found in the `/editor` subpath. Importing from the root module directly is incorrect.
• Webpack Loader
  wrong:

  import 'properties-file/webpack-loader'

  correct:

  import 'properties-file/bundler/webpack'

  Since v4.0.0, the Webpack loader path was moved and renamed to `properties-file/bundler/webpack` for consistency with other bundler integrations.

Quickstart

This quickstart demonstrates the core functionalities: `getProperties` for simple key-value extraction, `Properties` for lossless parsing and node inspection, and `PropertiesEditor` for modifying entries while preserving formatting.

import { readFileSync } from 'node:fs';
import { getProperties, Properties, PropertiesNodeType } from 'properties-file/parser';
import { PropertiesEditor } from 'properties-file/editor';

// Example .properties content
const fileContent = `
# This is a comment
hello=world
foo:bar\n\r
key.with.escapes=value with spaces and \\ backslashes
duplicate=first
duplicate=second
`;

// 1. Basic key-value parsing
const simpleObject = getProperties(fileContent);
console.log('Simple object:', simpleObject);
// Expected: { hello: 'world', 'foo:bar': '', 'key.with.escapes': 'value with spaces and \ backslashes', duplicate: 'second' }

// 2. Lossless parsing with full data model
const properties = new Properties(fileContent);
console.log('\nLossless Nodes:');
for (const node of properties.nodes) {
  switch (node.type) {
    case PropertiesNodeType.PROPERTY:
      console.log(`PROPERTY: ${node.key} = ${node.value}`);
      break;
    case PropertiesNodeType.COMMENT:
      console.log(`COMMENT: ${node.body}`);
      break;
    case PropertiesNodeType.BLANK:
      console.log('BLANK LINE');
      break;
  }
}

// 3. Editing properties
const editor = new PropertiesEditor(fileContent);
editor.upsert('new_key', 'new_value');
editor.delete('duplicate', { occurrence: 'first' }); // Delete the first 'duplicate'
editor.update('hello', 'updated_world');

console.log('\nEdited properties:');
console.log(editor.format());