properties-reader

Properties-Reader
=================

An ini file compatible properties reader for Node.JS

See the upgrade guide for how to upgrade between major version 2 and 3.

Installation
============

The easiest installation is through NPM:

npm install properties-reader

API
===

Read properties from a file:

import { propertiesReader } from 'properties-reader';

const properties = propertiesReader({ sourceFile: '/path/to/properties.file' });

The properties are then accessible either by fully qualified name, or if the property names
are in dot-delimited notation, they can be accessed as an object:

// fully qualified name
const property = properties.get('some.property.name');

// lazily evaluated nested object path
const property = properties.path().some?.property?.name;

// flatten all properties into an object
const obj = Object.from(properties.entries())
const property = obj['some.property.name'];

// flatten all properties into an object - with value parsing
const obj = Object.from(properties.entries({ parsed: true }))
const property = obj['some.property.name'];

// eagerly evaluate a subset of properties into an object
const obj = properties.getByRoot('some.property')
const property = obj.name;

To read more than one file, chain calls to the .append() method:

properties.append('/another.file').append('/yet/another.file');

To read properties from a string, use the .read() method:

properties.read(
some.property = Value
another.property = Another Value
);

To set a single property into the properties object, use .set():

properties.set('property.name', 'Property Value');

When reading a .ini file, sections are created by having a line that contains just a
section name in square brackets. The section name is then prefixed to all property names
that follow it until another section name is found to replace the current section.

# contents of properties file
[main]
some.thing = foo

[blah]
something.numeric = 123

// reading these back from the properties reader
properties.get('main.some.thing') == 'foo';
properties.get('blah.something.numeric') == 123;

// iterator access for all properties - not parsed (ie: always string values)
for (const [key, value] of properties.entries()) {
// loops through each entry, for example:
// key="main.some.thing", value="foo"
// key="blah.something.numeric", value="123"
}

// iterator access for all properties - parsed
for (const [key, value] of properties.entries({ parsed: true })) {
// loops through each entry, for example:
// key="main.some.thing", value="foo"
// key="blah.something.numeric", value=123 <-- note, is now a number
}

// get subset of properties
expect(properties.getByRoot('blah')).toEqual({
'something.numeric': 123,
})

Checking for the current number of properties that have been read into the reader:

const propertiesCount = properties.length;

When duplicate names are found in the properties, the first one read will be replaced with
the later one.

$3

Once a file has been read and changes made, saving those changes to another
file is as simple as running:

``typescript
import { propertiesReader } from 'properties-reader';

const sourceFile = 'properties.ini'
const props = propertiesReader({ sourceFile, saveSections: true });

props.set('new.property', 'new value');

await props.save(sourceFile);
`

To output the properties without any section headings, set the
saveSections option to false.

Parsed Data Types
==========

Properties are automatically converted to their primitive data types
when using properties.get(key) if they represent true, false or
numeric values.

To get the original value without any parsing / type coercion applied,
use properties.getRaw(key).


Upgrading V2 to V3
===============

- Import the propertiesReader named factory function instead of the
package default export.

`
// v2
const propertiesReader = require('properties-reader');

// v3 - default and named import
import propertiesReader from 'properties-reader';
import { propertiesReader } from 'properties-reader';

// v3 - named property on require
const { propertiesReader } = require('properties-reader');
`

- All factory arguments are now supplied in a single options object

`
const options = { allowDuplicateSections, saveSections };

// v2
props = propertiesReader(sourceFile, encoding, options);

// v3
propertiesReader({
sourceFile,
encoding,
...options,
});
`

- Custom appender and writer functions are no longer supported as
configuration options, instead use the props.entries() or props.out()
iterators to gain access to the data within the reader:

`
// v2
propertiesReader(sourceFile, encoding, {
writer (reader, filePath, onComplete) { }
})

// v3
fs.writeFile(props.ini, Array.from(props.out()).join('\n'), 'utf8');
`

As the props.out() method returns an iterator, you can now transform the
output as necessary, in this basic example simply joining as an array - for
very large files this should be written to the file line by line.

- TypeScript types are now published as part of the properties-reader package,
so @type/properties-reader can now be safely removed as a dependency.

FAQ / Breaking Changes
======================

From version 3.0.0 the following have changed:

- To improve performance when reading properties files, nested properties
will no longer be eagerly evaluated meaning getRaw

- propertiesReader(...) now consumes a single object of options, see above
for how to supply sourceFile and encoding options that were previously
position based arguments.

- Custom property appender/writer functions are no longer supported,
removes support for passing functions as appender or writer
configuration properties.

- props.save(destFile) now returns a Promise that resolves once the
file has been written. It will no longer return the generated content to
avoid needlessly building it in memory, to use the generated file content
switch to using the props.out() function to get an iterator for the
output file content.

- props.save(destFile) will now write a file that includes a trailing new line.

Duplicate Section Headings

The properties-reader automatically supports sections in the properties file, merging duplicate
sections together when generating the output file contents with props.out() or props.save().

Where duplicate sections are found in the sourceFile they can be kept in the output by setting
allowDuplicateSections: true in the propertiesReader factory function.

`typescript
import { propertiesReader } from 'properties-reader';

const props = propertiesReader({ sourceFile, allowDuplicateSections: true });
``

Contributions
=============

If you find bugs or want to change functionality, feel free to fork and pull request.