js-java-properties

This is a small library that provides utilities to parse and manipulate Java properties files.

Intended mostly for the tools that need to modify an existing property file without reformatting the contents. This is achieved by using a string array as a backing storage. If you want only to read the properties, you should convert it to an object or a Map using toObject(...) or toMap(...) function, respectively.

Usage

You can install this library using NPM:

npm install js-java-properties

Types

Properties represent lines in the properties file. A single property can span multiple lines. It is a part of the API, and it may be extended in future versions.
KeyValuePair parsed key and value. Used by listProperties.

Parsing

Parses correctly file contents as a string into lines.

import * as properties from 'js-java-properties'

const props = properties.parse('key1=value1\nkey2 = value2\nkey3: value3')
console.log(props)
// { lines: [ 'key1=value1', 'key2 = value2', 'key3: value3' ] }

To read a file from a disk, use standard node fs module:

import fs from 'node:fs'
import * as properties from 'js-java-properties'

const props = properties.parse(fs.readFileSync('file.properties', 'utf-8'))

Stringify

Formats property lines into string.

import * as properties from 'js-java-properties'

const props = properties.empty()
props.lines.push('key1=value1', 'key2 = value2', 'key3: value3')

const output = properties.stringify(props)
console.log(output)
// 'key1=value1\nkey2 = value2\nkey3: value3\n'

Listing key-value pairs

Iterate over every key-value pair. Note that if file contains duplicate keys, they are returned here as well.

import * as properties from 'js-java-properties'

const props = properties.empty()
props.lines.push('# comment')
props.lines.push('key1=value1', 'key2 = value2', 'key3: value3')
props.lines.push('key3: duplicate')

for (const {key, value} of properties.listProperties(props)) {
  console.log(`${key}=${value}`)
  // key1=value1
  // key2=value2
  // key3=value3
  // key3=duplicate
}

Getting a value by key

Note that this method has O(n) complexity for every operation. Use toObject or toMap methods to convert it into a readable object.

In case there are duplicate keys, the last one is returned.

import * as properties from 'js-java-properties'

const props = properties.empty()
props.lines.push('key1=value1', 'key2 = value2', 'key3: value3')

console.log(properties.getProperty(props, 'key2'))
// 'value2'

props.lines.push('key2 = duplicate')
console.log(properties.getProperty(props, 'key2'))
// 'duplicate'

Converting to object or map

In case there are duplicate keys, the last one is returned.

import * as properties from 'js-java-properties'

const props = properties.empty()
props.lines.push('key1=value1', 'key2 = value2', 'key3: value3')

console.log(properties.toObject(props))
// { key1: 'value1', key2: 'value2', key3: 'value3' }

console.log(properties.toMap(props))
// Map(3) { 'key1' => 'value1', 'key2' => 'value2', 'key3' => 'value3' }

Setting a value

This method adds or replaces the given key-value pair. If the value is undefined, the key is removed. Note that an empty string is still considered a value.

If there are multiple occurrences of the same key in the list, only the first one is kept and all other occurrences are removed.

import * as properties from 'js-java-properties'

const props = properties.empty()
props.lines.push('key1=value1', 'key2 = value2', 'key3: value3')

properties.setProperty(props, 'key2', 'new-value')
console.log(props)
// { lines: [ 'key1=value1', 'key2 = new-value', 'key3: value3' ] }

properties.setProperty(props, 'new-key', 'new-value')
console.log(props)
// { lines: [ 'key1=value1', 'key2 = new-value', 'key3: value3', 'new-key: new-value' ] }

properties.setProperty(props, 'new-key', 'new-value', {separator: ' = '})
console.log(props)
// { lines: [ 'key1=value1', 'key2 = new-value', 'key3: value3', 'new-key = new-value' ] }

properties.setProperty(props, 'key3', undefined)
console.log(props)
// { lines: [ 'key1=value1', 'key2 = new-value', 'new-key = new-value' ] }

Removing a value

Removes the given key and its associated value. If there are duplicate keys with the same name, all values associated with the given key are removed.

import * as properties from 'js-java-properties'

const props = properties.empty()
props.lines.push('key1=value1', 'key2 = value2', 'key3: value3')

properties.removeProperty(props, 'key2')
console.log(props)
// { lines: [ 'key1=value1', 'key3: value3' ] }

Development

Commits must follow Conventional Commits standard
Code must conform to eslint and prettier rules
100% test coverage is required

Publishing

This package uses Release Please to generate releases. The package is automatically published to a npm registry when release is created.

Contributing

If you would like to contribute to this library, feel free to submit a pull request on GitHub.

mdvorak/js-java-properties