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 nameconst property = properties.get('some.property.name');// lazily evaluated nested object pathconst property = properties.path().some?.property?.name;// flatten all properties into an objectconst obj = Object.from(properties.entries())const property = obj['some.property.name'];// flatten all properties into an object - with value parsingconst obj = Object.from(properties.entries({ parsed: true }))const property = obj['some.property.name'];// eagerly evaluate a subset of properties into an objectconst obj = properties.getByRoot('some.property')const property = obj.name;
To read more than one file, chain calls to the .append() method:
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 readerproperties.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 - parsedfor (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 propertiesexpect(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.
Saving changes
Once a file has been read and changes made, saving those changes to another
file is as simple as running:
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.
// v2const propertiesReader = require('properties-reader');// v3 - default and named importimport propertiesReader from 'properties-reader';import { propertiesReader } from 'properties-reader';// v3 - named property on requireconst { propertiesReader } = require('properties-reader');
All factory arguments are now supplied in a single options object
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
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<void> 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.
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.