properties-file 1.0.0 → 2.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Avansai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,215 @@
+# properties-file
+
+[![License](https://img.shields.io/npm/l/make-coverage-badge.svg)](https://opensource.org/licenses/MIT)
+[![npm download](https://img.shields.io/npm/dw/properties-file.svg)](https://www.npmjs.com/package/properties-file)
+![Coverage](https://img.shields.io/badge/Coverage-100%25-brightgreen.svg)
+![Dependencies](https://img.shields.io/badge/dependencies-0-green)
+[![Known Vulnerabilities](https://snyk.io/test/github/Avansai/properties-file/badge.svg?targetFile=package.json)](https://snyk.io/test/github/Avansai/properties-file?targetFile=package.json)
+
+.properties file parser, JSON converter and Webpack loader.
+
+## Installation 💻
+
+> ⚠ in June 2022 we have released version 2 of this package which is not compatible with the previous versions. Make sure to read the documentation before upgrading.
+
+Add the package as a dependency:
+
+```
+npm install properties-file
+```
+
+## What's in it for me? 🤔
+
+- A modern TypeScript library that reproduces exactly the [Properties Java implementation](/assets/java-implementation.md).
+- Flexible APIs:
+  - `propertiesToJson` allows quick conversion from `.properties` files to JSON.
+  - `getProperties` returns a `Properties` object that allows insights into parsing issues such as key collisions.
+  - `propertiesToJson` & `getProperties` also have a browser-compatible version when passing directly the content of a file using the APIs under `properties-file/content`.
+  - Out of the box Webpack loader to `import` `.properties` files directly in your application.
+- 100% test coverage based on the output from a Java implementation.
+- Active maintenance (many popular .properties packages have been inactive years).
+
+## Usage 🎬
+
+We put a lot of effort into adding [TSDoc](https://tsdoc.org/) to all our APIs. Please check directly in your IDE if you are unsure how to use certain APIs provided in our examples.
+
+Both APIs (`getProperties` and `propertiesToJson`) directly under `properties-file` depend on [`fs`](https://nodejs.org/api/fs.html) which means they cannot be used by browsers. If you cannot use `fs` and already have a `.properties` file content, the same APIs are available under `properties-file/content`. Instead of taking the `filePath` as the first argument, they take `content`. The example below will use "`fs`" APIs since they are the most common use cases.
+
+### `propertiesToJson`
+
+This API is probably the most used. You have a `.properties` file that you want to open and access like a simple key/value JSON object. Here is how this can be done with a single API call:
+
+```ts
+import { propertiesToJson } from 'properties-file';
+
+console.log(propertiesToJson('hello-world.properties'));
+```
+
+Output:
+
+```js
+{ hello: 'hello', world: 'world' }
+```
+
+If you cannot use `fs` and already have the content of a `.properties` file, your code would look like this instead:
+
+```ts
+import { propertiesToJson } from 'properties-file/content';
+
+// ...some code to get the .properties file content into a variable called `propertiesFileContent`
+
+console.log(propertiesToJson(propertiesFileContent));
+```
+
+### `getProperties` (advanced use case)
+
+Java's implementation of `Properties` is quite resilient. In fact, there are only two ways an exception can be thrown:
+
+- The file is not found.
+- A (`\u`) Unicode escape character is malformed.
+
+This means that almost all files will be valid.
+
+But what about a file that has duplicate keys? Duplicate keys have no reason to exist and they probably should have thrown errors as well but instead Java decided to simply overwrite the value with the latest occurrence in a file.
+
+So how can we know if there were duplicate keys if we want to log some warnings? Simply by using `getProperties` which will return all the data that was used to parse the content. Here is an example on how it can be used:
+
+```properties
+# collisions-test.properties
+hello: hello1
+world: world1
+world: world2
+hello: hello2
+world: world3
+```
+
+```ts
+import { getProperties } from 'properties-file';
+
+const properties = getProperties('assets/tests/collisions-test.properties');
+
+properties.collection.forEach((property) => {
+  console.log(`${property.key} => '${property.value}'`);
+});
+
+/**
+ * Outputs:
+ *
+ * hello => 'hello2'
+ * world => 'world3'
+ *
+ */
+
+const keyCollisions = properties.getKeyCollisions();
+
+keyCollisions.forEach((keyCollision) => {
+  console.warn(
+    `Found a key collision for key '${
+      keyCollision.key
+    }' on lines ${keyCollision.startingLineNumbers.join(
+      ', '
+    )} (will use the value at line ${keyCollision.getApplicableLineNumber()}).`
+  );
+});
+
+/**
+ * Outputs:
+ *
+ * Found a key collision for key 'hello' on lines 1, 4 (will use the value at line 4).
+ * Found a key collision for key 'world' on lines 2, 3, 5 (will use the value at line 5).
+ *
+ */
+```
+
+### Webpack File Loader
+
+If you would like to import `.properties` directly using `import`, this package comes with its own Webpack file loader located under `properties-file/webpack-loader`. Here is an example of how to configure it:
+
+```js
+// webpack.config.js
+module.exports = {
+  module: {
+    rules: [
+      {
+        test: /\.properties$/i,
+        use: [
+          {
+            loader: 'properties-file/webpack-loader',
+          },
+        ],
+      },
+    ],
+  },
+};
+```
+
+As soon as you configure Webpack, the `.properties` type should be available in your IDE when using `import`. If you ever need to add it manually, you can add a `*.properties` type declaration file at the root of your application, like this:
+
+```js
+// properties-file.d.ts
+declare module '*.properties' {
+  const properties: { readonly [key: string]: string };
+  export default properties;
+}
+```
+
+By adding these configurations you should now be able to import directly `.properties` files just like this:
+
+```ts
+import helloWorld from './hello-world.properties';
+
+console.dir(helloWorld);
+```
+
+Output:
+
+```json
+{ "hello": "world" }
+```
+
+## Why another `.properties` file package?
+
+There are probably over 20 similar packages available but:
+
+- A lot of the most popular packages have had no activity for over 5 years.
+- A large portion of the packages will not replicate the current Java implementation.
+- No package offers the same capabilities as this one.
+
+Unfortunately the `.properties` file specification is not well documented. One reason for this is that it was originally used in Java to store configurations. Most applications will handle this using JSON, YAML or other modern formats today because the formats are more flexible.
+
+### So why `.properties` files?
+
+While many options exists today to handle configurations, `.properties` file remain one of the best option to store localizable strings (also known as messages). On the Java side, `PropertyResourceBundle` is how most implementations handle localization today. Because of its simplicity and maturity, `.properties` files remain one of the best options today when it comes to internationalization (i18n):
+
+| File format   | Key/value based  | Supports inline comments | Built for localization | Good linguistic tools support |
+| ------------- | ---------------- | ------------------------ | ---------------------- | ----------------------------- |
+| `.properties` | Yes              | Yes                      | Yes (Resource Bundles) | Yes                           |
+| `JSON`        | No (can do more) | No (requires JSON5)      | No                     | Depends on the schema         |
+| `YAML`        | No (can do more) | Yes                      | No                     | Depends on the schema         |
+
+By having good JavaScript/TypeScript support for `.properties` files, it provides more options when it comes to i18n.
+
+### How does this package work?
+
+Basically our goal was to offer parity with the Java implementation, which is the closest thing to a specification `.properties` file have. Here is in a nutshell the logic behind this package:
+
+1. Split the file content by lines (create line objects)
+2. Create `LineObjects` by combining multi-line properties and removing trailing backslash
+3. Create `PropertyObjects` from `LineObjects` that combined all lines of a property
+4. Identify the key/value delimiter and populate escaped keys and values.
+5. Unescape keys and values
+6. Create a `PropertiesObject` that will include all `PropertyObjects` while removing collisions
+
+Just like Java, if a Unicode escaped characters (`\u`) is malformed, it will throw an error. But of course, we do not recommend using Unicode escaped characters but rather UTF-8 encoding that supports more characters.
+
+## Additional references
+
+- Java [Test Sandbox](https://codehs.com/sandbox/id/java-main-kYynuh?filename=TestProperties.java)
+- Java's `Properties` class [documentation](https://docs.oracle.com/javase/9/docs/api/java/util/Properties.html)
+- Java's `PropertyResourceBundle` [documentation](https://docs.oracle.com/javase/9/docs/api/java/util/PropertyResourceBundle.html)
+- Java's Internationalization [Guide](https://docs.oracle.com/en/java/javase/18/intl/internationalization-overview.html)
+- Wikipedia's .properties [page](https://en.wikipedia.org/wiki/.properties)
+
+### Special mention
+
+Thanks to [@calibr](https://github.com/calibr), the creator of [properties-file version 1.0](https://github.com/calibr/properties-file), for letting us use the [https://www.npmjs.com/package/properties-file](https://www.npmjs.com/package/properties-file) package name. We hope that it will make it easier to find our package.

package/lib/content/index.d.ts

@@ -0,0 +1,18 @@
+import { KeyValueObject } from '../';
+import { Properties } from '../properties';
+/**
+ * Get a `Properties` object from the content of a `.properties` file.
+ *
+ * @param content - the content of a `.properties` file.
+ *
+ * @returns A `Properties` object representing the content of a `.properties` file.
+ */
+export declare function getProperties(content: string): Properties;
+/**
+ * Converts the content of a `.properties` file to JSON.
+ *
+ * @param content - the content of a `.properties` file.
+ *
+ * @returns A (JSON) key/value object representing the content of a `.properties` file.
+ */
+export declare function propertiesToJson(content: string): KeyValueObject;

package/lib/content/index.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.propertiesToJson = exports.getProperties = void 0;
+var properties_1 = require("../properties");
+var property_1 = require("../property");
+var property_line_1 = require("../property-line");
+/**
+ * Get a `Properties` object from the content of a `.properties` file.
+ *
+ * @param content - the content of a `.properties` file.
+ *
+ * @returns A `Properties` object representing the content of a `.properties` file.
+ */
+function getProperties(content) {
+    // Remove BOM character if present and create an array from lines.
+    var lines = (content.charCodeAt(0) === 0xfeff ? content.slice(1) : content).split(/\r?\n/);
+    /** Line number while parsing properties file content. */
+    var lineNumber = 0;
+    /** The current property object being parsed. */
+    var property;
+    /** The collection of property objects. */
+    var properties = new properties_1.Properties();
+    for (var _i = 0, lines_1 = lines; _i < lines_1.length; _i++) {
+        var line = lines_1[_i];
+        lineNumber++;
+        var propertyLine = new property_line_1.PropertyLine(line, !!property);
+        if (!property) {
+            // Check if the line is a new property.
+            if (propertyLine.isComment || propertyLine.isBlank) {
+                continue; // Skip line if its a comment or blank.
+            }
+            // The line is a new property.
+            property = new property_1.Property(propertyLine, lineNumber);
+            if (propertyLine.continues) {
+                continue; // Continue parsing the next line.
+            }
+        }
+        else {
+            // Continue parsing an existing property.
+            property.addLine(propertyLine);
+            if (propertyLine.continues) {
+                continue;
+            }
+        }
+        // If the line does not continue, add the property to the collection.
+        property = properties.add(property);
+    }
+    return properties;
+}
+exports.getProperties = getProperties;
+/**
+ * Converts the content of a `.properties` file to JSON.
+ *
+ * @param content - the content of a `.properties` file.
+ *
+ * @returns A (JSON) key/value object representing the content of a `.properties` file.
+ */
+function propertiesToJson(content) {
+    return getProperties(content).toJson();
+}
+exports.propertiesToJson = propertiesToJson;

package/lib/file/index.d.ts

@@ -0,0 +1,21 @@
+/// <reference types="node" />
+import { KeyValueObject, Properties } from '../';
+export { KeyValueObject } from '../';
+/**
+ * Get a `Properties` object from the content of a `.properties` file.
+ *
+ * @param filePath - The file path of the `.properties` file.
+ * @param encoding - The encoding of the file to parse (default is UTF-8).
+ *
+ * @returns A `Properties` object representing the content of a `.properties` file.
+ */
+export declare function getProperties(filePath: string, encoding?: BufferEncoding): Properties;
+/**
+ * Converts the content of a `.properties` file to JSON.
+ *
+ * @param filePath - The file path of the `.properties` file.
+ * @param encoding - The encoding of the file to parse (default is UTF-8).
+ *
+ * @returns A (JSON) key/value object representing the content of a `.properties` file.
+ */
+export declare function propertiesToJson(filePath: string, encoding?: BufferEncoding): KeyValueObject;

package/lib/file/index.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.propertiesToJson = exports.getProperties = void 0;
+var fs_1 = require("fs");
+var content_1 = require("../content/");
+/**
+ * Get a `Properties` object from the content of a `.properties` file.
+ *
+ * @param filePath - The file path of the `.properties` file.
+ * @param encoding - The encoding of the file to parse (default is UTF-8).
+ *
+ * @returns A `Properties` object representing the content of a `.properties` file.
+ */
+function getProperties(filePath, encoding) {
+    if (!(0, fs_1.existsSync)(filePath)) {
+        throw Error("file not found at ".concat(filePath));
+    }
+    return (0, content_1.getProperties)((0, fs_1.readFileSync)(filePath, encoding ? encoding : 'utf-8'));
+}
+exports.getProperties = getProperties;
+/**
+ * Converts the content of a `.properties` file to JSON.
+ *
+ * @param filePath - The file path of the `.properties` file.
+ * @param encoding - The encoding of the file to parse (default is UTF-8).
+ *
+ * @returns A (JSON) key/value object representing the content of a `.properties` file.
+ */
+function propertiesToJson(filePath, encoding) {
+    return getProperties(filePath, encoding).toJson();
+}
+exports.propertiesToJson = propertiesToJson;

package/lib/index.d.ts

@@ -0,0 +1,13 @@
+/// <reference types="./properties-file" />
+
+export { Properties, KeyLineNumbers } from './properties';
+export { Property } from './property';
+export { PropertyLine } from './property-line';
+export { getProperties } from './file';
+export { propertiesToJson } from './file';
+/**
+ * A simple "key/value" object.
+ */
+export declare type KeyValueObject = {
+    [key: string]: string;
+};

package/lib/index.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.propertiesToJson = exports.getProperties = exports.PropertyLine = exports.Property = exports.Properties = void 0;
+var properties_1 = require("./properties");
+Object.defineProperty(exports, "Properties", { enumerable: true, get: function () { return properties_1.Properties; } });
+var property_1 = require("./property");
+Object.defineProperty(exports, "Property", { enumerable: true, get: function () { return property_1.Property; } });
+var property_line_1 = require("./property-line");
+Object.defineProperty(exports, "PropertyLine", { enumerable: true, get: function () { return property_line_1.PropertyLine; } });
+var file_1 = require("./file");
+Object.defineProperty(exports, "getProperties", { enumerable: true, get: function () { return file_1.getProperties; } });
+var file_2 = require("./file");
+Object.defineProperty(exports, "propertiesToJson", { enumerable: true, get: function () { return file_2.propertiesToJson; } });

package/lib/loader/webpack.d.ts

@@ -0,0 +1,10 @@
+/// <reference types="../properties-file" />
+
+/**
+ * Webpack file loader for `.properties` files.
+ *
+ * @param content - the content of a `.properties` file.
+ *
+ * @returns A Webpack file loader string containing the content of  a `.properties` file.
+ */
+export default function (content: string): string;

package/lib/loader/webpack.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+var content_1 = require("../content");
+/**
+ * Webpack file loader for `.properties` files.
+ *
+ * @param content - the content of a `.properties` file.
+ *
+ * @returns A Webpack file loader string containing the content of  a `.properties` file.
+ */
+function default_1(content) {
+    return "module.exports = ".concat(JSON.stringify((0, content_1.propertiesToJson)(content)), ";");
+}
+exports.default = default_1;

package/lib/properties-file.d.ts

@@ -0,0 +1,7 @@
+/** This allows to get the correct type when using `import` on `.properties` files. */
+declare module '*.properties' {
+  const properties: {
+    readonly [key: string]: string;
+  };
+  export default properties;
+}

package/lib/properties.d.ts

@@ -0,0 +1,55 @@
+import { KeyValueObject } from './';
+import { Property } from './property';
+/**
+ * A class representing the content of a .properties file.
+ */
+export declare class Properties {
+    /** Object associating keys with their starting line numbers. */
+    keyLineNumbers: KeyLineNumbers;
+    /** The collection of property object. */
+    collection: Property[];
+    /**
+     * Add a property object into a properties object collection.
+     *
+     * @param property - A property object, or undefined.
+     *
+     * @returns Undefined so that we conveniently overwrite the property object.
+     */
+    add(property: Property | undefined): undefined;
+    /**
+     * Get the JSON (key/value) representation of the properties.
+     *
+     * @returns A key/value representing the properties of the object.
+     */
+    toJson(): KeyValueObject;
+    /**
+     * Get keys that have collisions (more than one occurrence).
+     */
+    getKeyCollisions(): KeyCollisions[];
+}
+/**
+ * Object associating keys with their line numbers.
+ */
+export declare type KeyLineNumbers = {
+    [key: string]: number[];
+};
+/**
+ * A class representing key within a .properties file that had collisions (more than one occurrence).
+ */
+export declare class KeyCollisions {
+    /** The key with collisions. */
+    key: string;
+    /** The starting line numbers where collisions are found. */
+    startingLineNumbers: number[];
+    /**
+     * Create a new key collision object.
+     *
+     * @param key - The key with collisions.
+     * @param startingLineNumbers - The starting line numbers where collisions are found.
+     */
+    constructor(key: string, startingLineNumbers: number[]);
+    /**
+     * Get the number of the line from which the value will be used.
+     */
+    getApplicableLineNumber(): number;
+}

package/lib/properties.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KeyCollisions = exports.Properties = void 0;
+/**
+ * A class representing the content of a .properties file.
+ */
+var Properties = /** @class */ (function () {
+    function Properties() {
+        /** Object associating keys with their starting line numbers. */
+        this.keyLineNumbers = {};
+        /** The collection of property object. */
+        this.collection = [];
+    }
+    /**
+     * Add a property object into a properties object collection.
+     *
+     * @param property - A property object, or undefined.
+     *
+     * @returns Undefined so that we conveniently overwrite the property object.
+     */
+    Properties.prototype.add = function (property) {
+        var _a;
+        if (property === undefined)
+            return undefined;
+        property.setKeyAndValue();
+        if ((_a = this.keyLineNumbers[property.key]) === null || _a === void 0 ? void 0 : _a.length) {
+            this.keyLineNumbers[property.key].push(property.startingLineNumber);
+            property.hasKeyCollisions = true;
+            property.keyCollisionLines = this.keyLineNumbers[property.key];
+            // Remove collision so that we can overwrite it with the latest object.
+            this.collection = this.collection.filter(function (existingPropertyObject) { return existingPropertyObject.key !== property.key; });
+        }
+        else {
+            // Initialize the key line numbers.
+            this.keyLineNumbers[property.key] = [property.startingLineNumber];
+        }
+        // Add the property to the collection.
+        this.collection.push(property);
+        return undefined;
+    };
+    /**
+     * Get the JSON (key/value) representation of the properties.
+     *
+     * @returns A key/value representing the properties of the object.
+     */
+    Properties.prototype.toJson = function () {
+        var keyValueObject = {};
+        this.collection.forEach(function (property) {
+            keyValueObject[property.key] = property.value;
+        });
+        return keyValueObject;
+    };
+    /**
+     * Get keys that have collisions (more than one occurrence).
+     */
+    Properties.prototype.getKeyCollisions = function () {
+        var keyCollisions = [];
+        for (var _i = 0, _a = Object.entries(this.keyLineNumbers); _i < _a.length; _i++) {
+            var _b = _a[_i], key = _b[0], startingLineNumbers = _b[1];
+            if (startingLineNumbers.length > 1) {
+                keyCollisions.push(new KeyCollisions(key, startingLineNumbers));
+            }
+        }
+        return keyCollisions;
+    };
+    return Properties;
+}());
+exports.Properties = Properties;
+/**
+ * A class representing key within a .properties file that had collisions (more than one occurrence).
+ */
+var KeyCollisions = /** @class */ (function () {
+    /**
+     * Create a new key collision object.
+     *
+     * @param key - The key with collisions.
+     * @param startingLineNumbers - The starting line numbers where collisions are found.
+     */
+    function KeyCollisions(key, startingLineNumbers) {
+        this.key = key;
+        this.startingLineNumbers = startingLineNumbers;
+    }
+    /**
+     * Get the number of the line from which the value will be used.
+     */
+    KeyCollisions.prototype.getApplicableLineNumber = function () {
+        return this.startingLineNumbers.slice(-1)[0];
+    };
+    return KeyCollisions;
+}());
+exports.KeyCollisions = KeyCollisions;

package/lib/property-line.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Object representing a line from the content of .properties file.
+ */
+export declare class PropertyLine {
+    /** The line content, minus the trailing \ that identifies that the line continues. */
+    content: string;
+    /** Is the line object a continuation from a previous line? */
+    isMultiline: boolean;
+    /** True if the line continues, otherwise false. */
+    continues: boolean;
+    /** True if the line is a comment, otherwise false. */
+    isComment: boolean;
+    /** True if the line is blank, otherwise false. */
+    isBlank: boolean;
+    /**
+     * Create a new line object.
+     *
+     * @param line - The raw content of a line.
+     * @param isMultiline - Is the line spreading on multiple lines?
+     */
+    constructor(line: string, isMultiline: boolean);
+}

package/lib/property-line.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PropertyLine = void 0;
+/**
+ * Object representing a line from the content of .properties file.
+ */
+var PropertyLine = /** @class */ (function () {
+    /**
+     * Create a new line object.
+     *
+     * @param line - The raw content of a line.
+     * @param isMultiline - Is the line spreading on multiple lines?
+     */
+    function PropertyLine(line, isMultiline) {
+        /** True if the line continues, otherwise false. */
+        this.continues = false;
+        /** True if the line is a comment, otherwise false. */
+        this.isComment = false;
+        /** True if the line is blank, otherwise false. */
+        this.isBlank = false;
+        this.content = line.trimStart();
+        this.isMultiline = isMultiline;
+        if (!this.content.length) {
+            // Line is blank.
+            this.isBlank = true;
+        }
+        else {
+            if (!this.isMultiline) {
+                // Line is a comment.
+                this.isComment = !!this.content.match(/^[!#]/);
+            }
+            if (!this.isComment) {
+                // Otherwise, check if the line continues on the next line.
+                var backslashMatch = this.content.match(/(?<backslashes>\\+)$/);
+                if (backslashMatch === null || backslashMatch === void 0 ? void 0 : backslashMatch.groups) {
+                    // If the number of backslashes is odd, the line continues, otherwise it doesn't.
+                    this.continues = !!(backslashMatch.groups.backslashes.length % 2);
+                    if (this.continues) {
+                        // Remove the trailing slash so that we can concatenate the line with the next one.
+                        this.content = this.content.slice(0, -1);
+                    }
+                }
+            }
+        }
+    }
+    return PropertyLine;
+}());
+exports.PropertyLine = PropertyLine;

package/lib/property.d.ts

@@ -0,0 +1,64 @@
+import { PropertyLine } from './property-line';
+/**
+ * Object representing a property (key/value).
+ */
+export declare class Property {
+    /** The line number at which the property starts. */
+    startingLineNumber: number;
+    /** The content of one or multiple lines when applicable. */
+    linesContent: string;
+    /** Positions of the newline characters if any. */
+    newlinePositions: number[];
+    /** Starting line numbers of property objects with the same key. */
+    keyCollisionLines: number[];
+    /** The starting position of the delimiter separating the key from the value. */
+    delimiterPosition: number | undefined;
+    /** The length of the delimiter, including its whitespace characters. */
+    delimiterLength: number | undefined;
+    /** The property key, including its escaped characters. */
+    escapedKey: string;
+    /** The property value, including its escaped characters. */
+    escapedValue: string;
+    /** The property key (unescaped). */
+    key: string;
+    /** The property value (unescaped). */
+    value: string;
+    /** Was the property's key used more than once? */
+    hasKeyCollisions: boolean;
+    /** Does the key definition spread across multiple lines? */
+    private hasMultilineKey;
+    /** Is the key empty? */
+    private hasNoKey;
+    /** Is the value empty? */
+    private hasNoValue;
+    /**
+     * Create a new property object.
+     *
+     * @param propertyLine - A property line object.
+     * @param startingLineNumber - The line number at which the property starts.
+     */
+    constructor(propertyLine: PropertyLine, startingLineNumber: number);
+    /**
+     * Add the a line to a multiline property object.
+     *
+     * @param propertyLine - A property line object.
+     */
+    addLine(propertyLine: PropertyLine): void;
+    /**
+     * Set the property's key and value.
+     */
+    setKeyAndValue(): void;
+    /**
+     * Unescape the content from either key or value of a property.
+     *
+     * @param escapedContent - The content to unescape.
+     * @param startingLineNumber - The starting line number of the content being unescaped.
+     *
+     * @returns The unescaped content.
+     */
+    unescape(escapedContent: string, startingLineNumber: number): string;
+    /**
+     * Find the delimiting characters separating the key from the value.
+     */
+    private findDelimiter;
+}

package/lib/property.js

@@ -0,0 +1,198 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Property = void 0;
+/**
+ * Object representing a property (key/value).
+ */
+var Property = /** @class */ (function () {
+    /**
+     * Create a new property object.
+     *
+     * @param propertyLine - A property line object.
+     * @param startingLineNumber - The line number at which the property starts.
+     */
+    function Property(propertyLine, startingLineNumber) {
+        /** Positions of the newline characters if any. */
+        this.newlinePositions = [];
+        /** Starting line numbers of property objects with the same key. */
+        this.keyCollisionLines = [];
+        /** The property key, including its escaped characters. */
+        this.escapedKey = '';
+        /** The property value, including its escaped characters. */
+        this.escapedValue = '';
+        /** The property key (unescaped). */
+        this.key = '';
+        /** The property value (unescaped). */
+        this.value = '';
+        /** Was the property's key used more than once? */
+        this.hasKeyCollisions = false;
+        /** Does the key definition spread across multiple lines? */
+        this.hasMultilineKey = false;
+        /** Is the key empty? */
+        this.hasNoKey = false;
+        /** Is the value empty? */
+        this.hasNoValue = false;
+        this.linesContent = propertyLine.content;
+        this.startingLineNumber = startingLineNumber;
+    }
+    /**
+     * Add the a line to a multiline property object.
+     *
+     * @param propertyLine - A property line object.
+     */
+    Property.prototype.addLine = function (propertyLine) {
+        if (this.linesContent.length) {
+            this.newlinePositions.push(this.linesContent.length);
+        }
+        this.linesContent += propertyLine.content;
+    };
+    /**
+     * Set the property's key and value.
+     */
+    Property.prototype.setKeyAndValue = function () {
+        this.findDelimiter();
+        if (this.delimiterPosition !== undefined && this.delimiterLength !== undefined) {
+            // Set key if present.
+            if (!this.hasNoKey) {
+                this.escapedKey = this.linesContent.substring(0, this.delimiterPosition);
+                this.key = this.unescape(this.escapedKey, this.startingLineNumber);
+            }
+            // Set value if present.
+            if (!this.hasNoValue) {
+                this.escapedValue = this.linesContent.substring(this.delimiterPosition + this.delimiterLength);
+                this.value = this.unescape(this.escapedValue, this.startingLineNumber);
+            }
+        }
+        else if (this.hasNoValue) {
+            // Set key if present (no delimiter).
+            this.escapedKey = this.linesContent;
+            this.key = this.unescape(this.escapedKey, this.startingLineNumber);
+        }
+    };
+    /**
+     * Unescape the content from either key or value of a property.
+     *
+     * @param escapedContent - The content to unescape.
+     * @param startingLineNumber - The starting line number of the content being unescaped.
+     *
+     * @returns The unescaped content.
+     */
+    Property.prototype.unescape = function (escapedContent, startingLineNumber) {
+        var unescapedContent = '';
+        for (var position = 0, character = escapedContent[0]; position < escapedContent.length; position++, character = escapedContent[position]) {
+            if (character === '\\') {
+                var nextCharacter = escapedContent[position + 1];
+                if (nextCharacter === 'f') {
+                    // Formfeed/
+                    unescapedContent += '\f';
+                    position++;
+                }
+                else if (nextCharacter === 'n') {
+                    // Newline.
+                    unescapedContent += '\n';
+                    position++;
+                }
+                else if (nextCharacter === 'r') {
+                    // Carriage return.
+                    unescapedContent += '\r';
+                    position++;
+                }
+                else if (nextCharacter === 't') {
+                    // Tab.
+                    unescapedContent += '\t';
+                    position++;
+                }
+                else if (nextCharacter === 'u') {
+                    // Unicode character.
+                    var codePoint = escapedContent.substring(position + 2, position + 6);
+                    if (!/[0-9a-f]{4}/i.test(codePoint)) {
+                        // Code point can only be within Unicode's Multilingual Plane (BMP).
+                        throw new Error("malformed escaped unicode characters '\\u".concat(codePoint, "' in property starting at line ").concat(startingLineNumber));
+                    }
+                    unescapedContent += String.fromCharCode(parseInt(codePoint, 16));
+                    position += 5;
+                }
+                else {
+                    // Otherwise the escape character is not required.
+                    unescapedContent += nextCharacter;
+                    position++;
+                }
+            }
+            else {
+                // When there is \, simply add the character.
+                unescapedContent += character;
+            }
+        }
+        return unescapedContent;
+    };
+    /**
+     * Find the delimiting characters separating the key from the value.
+     */
+    Property.prototype.findDelimiter = function () {
+        var _a, _b;
+        // If the delimiter was already found, skip.
+        if (this.hasNoKey || this.hasNoValue || this.delimiterPosition) {
+            return;
+        }
+        for (var position = 0, character = this.linesContent[0]; position < this.linesContent.length; position++, character = this.linesContent[position]) {
+            // If the character is not a delimiter, check the next one.
+            if (!/[ \t\f=:]/.test(character)) {
+                continue;
+            }
+            // Check if the delimiter might be escaped.
+            var prefix = !position ? '' : this.linesContent.substring(0, position);
+            if (prefix.length) {
+                var backslashMatch = prefix.match(/(?<backslashes>\\+)$/);
+                if (backslashMatch === null || backslashMatch === void 0 ? void 0 : backslashMatch.groups) {
+                    var delimiterIsEscaped = !!(backslashMatch.groups.backslashes.length % 2);
+                    if (delimiterIsEscaped) {
+                        // If the delimiter is escaped, check the next character.
+                        continue;
+                    }
+                }
+            }
+            var delimiter = '';
+            this.delimiterPosition = position;
+            this.hasMultilineKey = !!(this.newlinePositions.length && this.newlinePositions[0] > position);
+            // Check if the delimiter starts with a whitespace.
+            var nextContent = this.linesContent.substring(position);
+            var leadingWhitespaceMatch = nextContent.match(/^(?<whitespace>\s+)/);
+            var leadingWhitespace = ((_a = leadingWhitespaceMatch === null || leadingWhitespaceMatch === void 0 ? void 0 : leadingWhitespaceMatch.groups) === null || _a === void 0 ? void 0 : _a.whitespace) || '';
+            // If there is a whitespace, move to the next character.
+            if (leadingWhitespace.length) {
+                delimiter += leadingWhitespace;
+                nextContent = nextContent.substring(leadingWhitespace.length);
+            }
+            // Check if there is an equal or colon character.
+            if (/[=:]/.test(nextContent[0])) {
+                delimiter += nextContent[0];
+                nextContent = nextContent.substring(1);
+                // If an equal or colon character was found, try to get trailing whitespace.
+                var trailingWhitespaceMatch = nextContent.match(/^(?<whitespace>\s+)/);
+                var trailingWhitespace = ((_b = trailingWhitespaceMatch === null || trailingWhitespaceMatch === void 0 ? void 0 : trailingWhitespaceMatch.groups) === null || _b === void 0 ? void 0 : _b.whitespace) || '';
+                delimiter += trailingWhitespace;
+            }
+            this.delimiterLength = delimiter.length;
+            // If the line starts with a delimiter, the property has no key.
+            if (!position) {
+                this.hasNoKey = true;
+            }
+            break;
+        }
+        // If there was no delimiter found, the property has no value.
+        if (this.delimiterPosition === undefined) {
+            this.hasNoValue = true;
+        }
+        else {
+            // If the delimiter is after the first newline, mark the key as multiline.
+            if (this.newlinePositions.length) {
+                var firstLinePosition = this.newlinePositions[0];
+                if (firstLinePosition > this.delimiterPosition) {
+                    this.hasMultilineKey = true;
+                }
+            }
+        }
+    };
+    return Property;
+}());
+exports.Property = Property;

package/package.json

@@ -1,29 +1,70 @@
-{
-  "name": "properties-file",
-  "version": "1.0.0",
-  "description": "Parse .properties file",
-  "main": "index.js",
-  "scripts": {
-    "test": "mocha"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/calibr/properties-file.git"
-  },
-  "keywords": [
-    "parse",
-    "properties",
-    "file",
-    "locales",
-    "firefox"
-  ],
-  "author": "calibr <awcalibr@gmail.com>",
-  "license": "ISC",
-  "bugs": {
-    "url": "https://github.com/calibr/properties-file/issues"
-  },
-  "homepage": "https://github.com/calibr/properties-file",
-  "devDependencies": {
-    "should": "^7.1.0"
-  }
-}
+{
+  "name": "properties-file",
+  "version": "2.0.1",
+  "description": ".properties file parser, JSON converter and Webpack loader.",
+  "author": "Avansai (https://avansai.com)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Avansai/properties-file.git"
+  },
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": "./lib/index.js",
+    "./content": "./lib/content/index.js",
+    "./webpack-loader": "./lib/loader/webpack.js"
+  },
+  "typesVersions": {
+    "*": {
+      "content": [
+        "lib/content/index.d.ts"
+      ],
+      "webpack-loader": [
+        "lib/loader/webpack.d.ts"
+      ]
+    }
+  },
+  "license": "MIT",
+  "files": [
+    "lib"
+  ],
+  "keywords": [
+    ".properties",
+    "properties",
+    ".properties file",
+    "properties file",
+    "parser",
+    "Java",
+    "intl",
+    "i18n",
+    "properties Webpack loader",
+    "Webpack loader",
+    "internationalization"
+  ],
+  "scripts": {
+    "build": "rm -Rf ./lib && tsc && npm run add-import-type && npm run lint && npm test",
+    "add-import-type": "node ./src/add-import-type",
+    "test": "jest --coverage",
+    "tmp-test": "tsc && node ./lib/tmp.js",
+    "lint": "eslint . --fix",
+    "prettier-check": "prettier --check .",
+    "prettier-fix": "prettier --write .",
+    "release": "dotenv -- release-it --only-version"
+  },
+  "devDependencies": {
+    "@release-it/conventional-changelog": "^5.0.0",
+    "@types/jest": "^28.1.1",
+    "@typescript-eslint/eslint-plugin": "^5.27.1",
+    "@typescript-eslint/parser": "^5.27.1",
+    "dotenv-cli": "^5.1.0",
+    "eslint": "^8.17.0",
+    "eslint-config-prettier": "^8.5.0",
+    "eslint-plugin-jest": "^26.5.3",
+    "jest": "^28.1.1",
+    "prettier": "2.6.2",
+    "release-it": "^15.0.0",
+    "ts-jest": "^28.0.4",
+    "ts-node": "^10.8.1",
+    "typescript": "^4.7.3"
+  }
+}

package/.npmignore

@@ -1,4 +0,0 @@
-.DS_Store
-node_modules
-*.sublime-project
-*.sublime-workspace

package/index.js

@@ -1,25 +0,0 @@
-exports.parse = function(string) {
-  var object = {};
-  string.split(/(\n|\r\n)/).forEach(function(s) {
-    s = s.trim();
-    if(!s) {
-      return;
-    }
-    var eqIndex = s.indexOf("=");
-    if(eqIndex < 0) {
-      return;
-    }
-    var key = s.substr(0, eqIndex).trim();
-    var value = s.substr(eqIndex + 1).trim();
-    object[key] = value;
-  });
-  return object;
-};
-
-exports.stringify = function(object) {
-  var strings = [];
-  for(var k in object) {
-    strings.push(k + "=" + object[k]);
-  }
-  return strings.join("\n");
-};

package/readme.md

@@ -1,40 +0,0 @@
-# Just parse .properties files which used in firefox localization
-
-## Install
-
-`npm i properties-file`
-
-## Usage
-
-### Parse .properties file
-
-```js
-var parser = require("properties-file");
-
-var object = parser.parse(propertiesFileContents);
-// object with key value strings
-// for example if you have .properties file:
-// str1=text1
-// str2=text2
-// you will get object like this:
-// {
-//   "str1": "text1",
-//   "str2": "text2"
-// }
-```
-
-### Generate properties file from object
-
-```js
-var parser = require("properties-file");
-
-var string = parser.stringify({
-  str1: "text1",
-  str2: "text2"
-});
-// string will be
-// str1=text1
-// str2=text2
-```
-
-

package/test/stringify_result.properties

@@ -1,72 +0,0 @@
-enable_speed_dial=Speed Dial aktivieren
-max_groups=Maximale Dials in Beliebt Gruppe:
-thumbnails=Vorschaubilder
-groups=Gruppen
-default=Standard
-manage_groups=Gruppen verwalten
-enable_most_visited=Am Häufigsten Besucht aktivieren
-default_group=Standard:
-big=Groß
-medium=Mittel
-small=Klein
-custom=Benutzerdefiniert
-list=Liste
-enable_recently_closed=Kürzlich Geschlossen aktivieren
-show_last=Zeige letzte:
-restore_removed=Stelle gelöschte wieder her
-all_group_title=Beliebt
-last_selected_group_title=Zuletzt Ausgewählt
-yes=Ja
-no=Nein
-sure=Sicher?
-options=Optionen
-expand_all=Alle erweitern
-hide_all=Alle ausblenden
-cache_life_time=Synchronisieren alle:
-hours=Stunde(n)
-synchronization=Synchronisierung
-sync_now=Statistiken aktualisieren
-done=Fertig!
-global_options=Globale Optionen
-make_as_homepage=Als Startseite festlegen
-number_of_columns=Spaltenanzahl:
-columns_auto=Automatisch
-change_background=Hintergrund ändern
-restore_previous_session=Letzte Sitzung wiederherstellen
-do_not_display_migrate=Diese Meldung nicht noch einmal zeigen
-start_migrate=Importieren starten
-cancel_migrate=Importieren abbrechen
-migrate_message=Du kannst Daten von Dials/Gruppen aus Erweiterungen importieren:
-import=Importieren
-import_available=Verfügbare importieren
-most_visited_display_order=Sortieren nach
-most_visited_visits=Besuche
-most_visited_date=Datum
-rate_message=Bitte schreibe deine Beurteilung und gib uns eine Bewertung.
-menu_hot_key=HotKey: Drücke Leertaste
-hot_key_number_tpl=HotKey: Drücke %number%
-found_data_for_sync=Daten für Synchronisierung gefunden
-sync_updates_now=Jetzt synchronisieren
-skip_sync_updates=Synchronisieren überspringen
-rate_message_fvd_speed_dial=FVD Speed Dial
-rate_message_appreciate=Wir wissen deine Hilfe zu schätzen
-can_turn_off_newtab_msg=Hinweis: Du kannst FVD Speed Dial in einer neuen Tab-Seite deaktivieren und nur auf Knopfdruck starten.
-can_turn_off_newtab_opt_app=Optionen > Erscheinungsbild
-can_turn_off_newtab_got_it=Ich habe es verstanden. Danke.
-poweroff_button_title=Power Off
-showhide_button_title=Show/Hide
-number_of_rows=Number of Rows:
-cant_arrange_in_popular=You can rearrange dials in ANY group except in "Popular Group". This group arranges dials by clicks popularity.
-install_eversync_title_head=In order to use Sync you need to install EverSync extension
-install_eversync_title_head_sub=To use Fvd Sync you need to install additional addon - EverSync extension:
-install_eversync_f1=Sync your Dials
-install_eversync_f2=Sync your Groups
-install_eversync_f3=Use it between Firefox, Chrome, Opera and Mobile Phones, Different PCs.
-install_eversync_f4=Sync your Firefox, Chrome, Opera, Mobile Phones Bookmarks
-install_eversync_f5=Sync your Folders.
-install_eversync_f6=Manage Bookmarks and Dials
-install_eversync_f7=Copy Bookmarks to FVD Speed Dial and From Speed Dial to Bookmarks
-install_eversync_f8=Trash / Favorites / Private / Archive / Advanced Search and more additional features.
-install_eversync_f9=Server auto backups and restore.
-install_eversync_install=Install from Mozilla.org
-install_eversync_installing=Installation...

package/test/test.js

@@ -1,23 +0,0 @@
-var
-  parser = require("../index"),
-  should = require("should"),
-  fs = require("fs");
-
-describe("Common", function() {
-  it("should parse test file", function() {
-    var raw = fs.readFileSync(__dirname + "/test.properties", "utf8");
-    var res = parser.parse(raw);
-    var strRes = parser.stringify(res);
-    strRes.should.equal(fs.readFileSync(__dirname + "/stringify_result.properties", "utf8"));
-  });
-
-  it("should stringify object", function() {
-    var obj = {
-      str1: "text1",
-      str2: "text2"
-    };
-    var res = parser.stringify(obj);
-    res.should.equal("str1=text1\nstr2=text2");
-  });
-});
-

package/test/test.properties

@@ -1,72 +0,0 @@
-enable_speed_dial=Speed Dial aktivieren
-max_groups=Maximale Dials in Beliebt Gruppe:
-thumbnails=Vorschaubilder
-groups=Gruppen
-default=Standard
-manage_groups=Gruppen verwalten
-enable_most_visited=Am Häufigsten Besucht aktivieren
-default_group=Standard:
-big=Groß
-medium=Mittel
-small=Klein
-custom=Benutzerdefiniert
-list=Liste
-enable_recently_closed=Kürzlich Geschlossen aktivieren
-show_last=Zeige letzte:
-restore_removed=Stelle gelöschte wieder her
-all_group_title=Beliebt
-last_selected_group_title=Zuletzt Ausgewählt
-yes=Ja
-no=Nein
-sure=Sicher?
-options=Optionen
-expand_all=Alle erweitern
-hide_all=Alle ausblenden
-cache_life_time=Synchronisieren alle:
-hours=Stunde(n)
-synchronization=Synchronisierung
-sync_now=Statistiken aktualisieren
-done=Fertig!
-global_options=Globale Optionen
-make_as_homepage=Als Startseite festlegen
-number_of_columns=Spaltenanzahl:
-columns_auto=Automatisch
-change_background=Hintergrund ändern
-restore_previous_session=Letzte Sitzung wiederherstellen
-do_not_display_migrate=Diese Meldung nicht noch einmal zeigen
-start_migrate=Importieren starten
-cancel_migrate=Importieren abbrechen
-migrate_message=Du kannst Daten von Dials/Gruppen aus Erweiterungen importieren:
-import=Importieren
-import_available=Verfügbare importieren
-most_visited_display_order=Sortieren nach
-most_visited_visits=Besuche
-most_visited_date=Datum
-rate_message=Bitte schreibe deine Beurteilung und gib uns eine Bewertung.
-menu_hot_key=HotKey: Drücke Leertaste
-hot_key_number_tpl=HotKey: Drücke %number%
-found_data_for_sync=Daten für Synchronisierung gefunden
-sync_updates_now=Jetzt synchronisieren
-skip_sync_updates=Synchronisieren überspringen
-rate_message_fvd_speed_dial=FVD Speed Dial
-rate_message_appreciate=Wir wissen deine Hilfe zu schätzen
-can_turn_off_newtab_msg=Hinweis: Du kannst FVD Speed Dial in einer neuen Tab-Seite deaktivieren und nur auf Knopfdruck starten.
-can_turn_off_newtab_opt_app=Optionen > Erscheinungsbild
-can_turn_off_newtab_got_it=Ich habe es verstanden. Danke.
-poweroff_button_title=Power Off
-showhide_button_title=Show/Hide
-number_of_rows=Number of Rows:
-cant_arrange_in_popular=You can rearrange dials in ANY group except in "Popular Group". This group arranges dials by clicks popularity.
-install_eversync_title_head = In order to use Sync you need to install EverSync extension
-install_eversync_title_head_sub = To use Fvd Sync you need to install additional addon - EverSync extension:
-install_eversync_f1 = Sync your Dials
-install_eversync_f2 = Sync your Groups
-install_eversync_f3 = Use it between Firefox, Chrome, Opera and Mobile Phones, Different PCs.
-install_eversync_f4 = Sync your Firefox, Chrome, Opera, Mobile Phones Bookmarks
-install_eversync_f5 = Sync your Folders.
-install_eversync_f6 = Manage Bookmarks and Dials
-install_eversync_f7 = Copy Bookmarks to FVD Speed Dial and From Speed Dial to Bookmarks
-install_eversync_f8 = Trash / Favorites / Private / Archive / Advanced Search and more additional features.
-install_eversync_f9 = Server auto backups and restore.
-install_eversync_install = Install from Mozilla.org
-install_eversync_installing = Installation...