properties-file 2.1.32 → 2.2.0

package/README.md

@@ -6,7 +6,7 @@
 ![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.
+`.properties` JSON converter, file parser and Webpack loader.
 
 ## Installation 💻
 
@@ -25,6 +25,7 @@ npm install properties-file
   - `propertiesToJson` allows quick conversion from `.properties` files to JSON.
   - `getProperties` returns a `Properties` object that provides 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`.
+  - `escapeKey`, `escapeValue` that can allow you to convert any content to `.properties` compatible format.
   - 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).
@@ -35,7 +36,7 @@ We put a lot of effort into adding [TSDoc](https://tsdoc.org/) to all our APIs.
 
 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`
+### `propertiesToJson` (common use case)
 
 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:
 
@@ -61,6 +62,38 @@ import { propertiesToJson } from 'properties-file/content'
 console.log(propertiesToJson(propertiesFileContent))
 ```
 
+### `escapeKey` and `escapeValue` (converting content to `.properties` format)
+
+> ⚠ This package does not offer full-fledged `.properties` file writer that would include a variety of options like modifying an existing file while keeping comments and line breaks intact. If you have any interest into adding this in, pull requests are welcomed!
+
+It is possible to use this package to do basic conversion between key/value content into `.properties.` compatible format by using `escapeKey` and `escapeValue`. Here is an example of how it can be done:
+
+```ts
+import * as fs from 'node:fs'
+import { EOL } from 'node:os'
+import { getProperties } from 'properties-file'
+import { escapeKey, escapeValue } from 'properties-file/escape'
+
+const properties = getProperties('assets/tests/collisions-test.properties')
+const newProperties: string[] = []
+console.dir(properties)
+
+properties.collection.forEach((property) => {
+  const value = property.value === 'world3' ? 'new world3' : property.value
+  newProperties.push(`${escapeKey(property.key)}: ${escapeValue(value)}`)
+})
+
+fs.writeFileSync('myNewFile.properties', newProperties.join(EOL))
+
+/**
+ * Outputs:
+ *
+ * hello: hello2
+ * world: new world3
+ *
+ */
+```
+
 ### `getProperties` (advanced use case)
 
 Java's implementation of `Properties` is quite resilient. In fact, there are only two ways an exception can be thrown:

package/lib/escape/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Escape a property key.
+ *
+ * @param unescapedKey - A property key to be escaped.
+ * @param escapeUnicode - Escape unicode characters into ISO-8859-1 compatible encoding?
+ *
+ * @return The escaped key.
+ */
+export declare const escapeKey: (unescapedKey: string, escapeUnicode?: boolean) => string;
+/**
+ * Escape property value.
+ *
+ * @param unescapedValue - Property value to be escaped.
+ * @param escapeUnicode - Escape unicode characters into ISO-8859-1 compatible encoding?
+ *
+ * @return The escaped value.
+ */
+export declare const escapeValue: (unescapedValue: string, escapeUnicode?: boolean) => string;

package/lib/escape/index.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.escapeValue = exports.escapeKey = void 0;
+/**
+ * Escape a property key.
+ *
+ * @param unescapedKey - A property key to be escaped.
+ * @param escapeUnicode - Escape unicode characters into ISO-8859-1 compatible encoding?
+ *
+ * @return The escaped key.
+ */
+var escapeKey = function (unescapedKey, escapeUnicode) {
+    if (escapeUnicode === void 0) { escapeUnicode = false; }
+    return escapeContent(unescapedKey, true, escapeUnicode);
+};
+exports.escapeKey = escapeKey;
+/**
+ * Escape property value.
+ *
+ * @param unescapedValue - Property value to be escaped.
+ * @param escapeUnicode - Escape unicode characters into ISO-8859-1 compatible encoding?
+ *
+ * @return The escaped value.
+ */
+var escapeValue = function (unescapedValue, escapeUnicode) {
+    if (escapeUnicode === void 0) { escapeUnicode = false; }
+    return escapeContent(unescapedValue, false, escapeUnicode);
+};
+exports.escapeValue = escapeValue;
+/**
+ * Escape the content from either key or value of a property.
+ *
+ * @param unescapedContent - The content to escape.
+ * @param escapeSpace - Escape spaces?
+ * @param escapeUnicode - Escape unicode characters into ISO-8859-1 compatible encoding?
+ *
+ * @returns The unescaped content.
+ */
+var escapeContent = function (unescapedContent, escapeSpace, escapeUnicode) {
+    var escapedContent = '';
+    for (var character = unescapedContent[0], position = 0; position < unescapedContent.length; position++, character = unescapedContent[position]) {
+        switch (character) {
+            case ' ': {
+                // Escape space if required, or if it is first character.
+                escapedContent += escapeSpace || position === 0 ? '\\ ' : ' ';
+                break;
+            }
+            // Backslash.
+            case '\\': {
+                escapedContent += '\\\\';
+                break;
+            }
+            case '\f': {
+                // Formfeed.
+                escapedContent += '\\f';
+                break;
+            }
+            case '\n': {
+                // Newline.
+                escapedContent += '\\n';
+                break;
+            }
+            case '\r': {
+                // Carriage return.
+                escapedContent += '\\r';
+                break;
+            }
+            case '\t': {
+                // Tab.
+                escapedContent += '\\t';
+                break;
+            }
+            case '=':
+            case ':':
+            case '#':
+            case '!': {
+                // Escapes =, :, # and !.
+                escapedContent += "\\".concat(character);
+                break;
+            }
+            default: {
+                if (escapeUnicode) {
+                    var codePoint = character.codePointAt(0); // Can never be `undefined`.
+                    if (codePoint < 0x0020 || codePoint > 0x007e) {
+                        escapedContent += "\\u".concat(codePoint.toString(16).padStart(4, '0'));
+                        break;
+                    }
+                }
+                // Non-escapable characters.
+                escapedContent += character;
+                break;
+            }
+        }
+    }
+    return escapedContent;
+};

package/lib/property.d.ts

@@ -55,8 +55,11 @@ export declare class Property {
      * @param startingLineNumber - The starting line number of the content being unescaped.
      *
      * @returns The unescaped content.
+     *
+     * @throws {@link Error}
+     * This exception is thrown if malformed escaped unicode characters are present.
      */
-    unescape(escapedContent: string, startingLineNumber: number): string;
+    private unescapeLine;
     /**
      * Find the delimiting characters separating the key from the value.
      */

package/lib/property.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Property = void 0;
+var unescape_1 = require("./unescape");
 /**
  * Object representing a property (key/value).
  */
@@ -55,18 +56,18 @@ var Property = /** @class */ (function () {
             // Set key if present.
             if (!this.hasNoKey) {
                 this.escapedKey = this.linesContent.slice(0, this.delimiterPosition);
-                this.key = this.unescape(this.escapedKey, this.startingLineNumber);
+                this.key = this.unescapeLine(this.escapedKey, this.startingLineNumber);
             }
             // Set value if present.
             if (!this.hasNoValue) {
                 this.escapedValue = this.linesContent.slice(this.delimiterPosition + this.delimiterLength);
-                this.value = this.unescape(this.escapedValue, this.startingLineNumber);
+                this.value = this.unescapeLine(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);
+            this.key = this.unescapeLine(this.escapedKey, this.startingLineNumber);
         }
     };
     /**
@@ -76,61 +77,17 @@ var Property = /** @class */ (function () {
      * @param startingLineNumber - The starting line number of the content being unescaped.
      *
      * @returns The unescaped content.
+     *
+     * @throws {@link Error}
+     * This exception is thrown if malformed escaped unicode characters are present.
      */
-    Property.prototype.unescape = function (escapedContent, startingLineNumber) {
-        var unescapedContent = '';
-        for (var character = escapedContent[0], position = 0; position < escapedContent.length; position++, character = escapedContent[position]) {
-            if (character === '\\') {
-                var nextCharacter = escapedContent[position + 1];
-                switch (nextCharacter) {
-                    case 'f': {
-                        // Formfeed/
-                        unescapedContent += '\f';
-                        position++;
-                        break;
-                    }
-                    case 'n': {
-                        // Newline.
-                        unescapedContent += '\n';
-                        position++;
-                        break;
-                    }
-                    case 'r': {
-                        // Carriage return.
-                        unescapedContent += '\r';
-                        position++;
-                        break;
-                    }
-                    case 't': {
-                        // Tab.
-                        unescapedContent += '\t';
-                        position++;
-                        break;
-                    }
-                    case 'u': {
-                        // Unicode character.
-                        var codePoint = escapedContent.slice(position + 2, position + 6);
-                        if (!/[\da-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.fromCodePoint(Number.parseInt(codePoint, 16));
-                        position += 5;
-                        break;
-                    }
-                    default: {
-                        // Otherwise the escape character is not required.
-                        unescapedContent += nextCharacter;
-                        position++;
-                    }
-                }
-            }
-            else {
-                // When there is \, simply add the character.
-                unescapedContent += character;
-            }
+    Property.prototype.unescapeLine = function (escapedContent, startingLineNumber) {
+        try {
+            return (0, unescape_1.unescapeContent)(escapedContent);
+        }
+        catch (error) {
+            throw new Error("".concat(error.message, " in property starting at line ").concat(startingLineNumber));
         }
-        return unescapedContent;
     };
     /**
      * Find the delimiting characters separating the key from the value.

package/lib/unescape/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Unescape the content from either key or value of a property.
+ *
+ * @param escapedContent - The content to unescape.
+ *
+ * @returns The unescaped content.
+ *
+ * @throws {@link Error}
+ * This exception is thrown if malformed escaped unicode characters are present.
+ */
+export declare const unescapeContent: (escapedContent: string) => string;

package/lib/unescape/index.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.unescapeContent = void 0;
+/**
+ * Unescape the content from either key or value of a property.
+ *
+ * @param escapedContent - The content to unescape.
+ *
+ * @returns The unescaped content.
+ *
+ * @throws {@link Error}
+ * This exception is thrown if malformed escaped unicode characters are present.
+ */
+var unescapeContent = function (escapedContent) {
+    var unescapedContent = '';
+    for (var character = escapedContent[0], position = 0; position < escapedContent.length; position++, character = escapedContent[position]) {
+        if (character === '\\') {
+            var nextCharacter = escapedContent[position + 1];
+            switch (nextCharacter) {
+                case 'f': {
+                    // Formfeed.
+                    unescapedContent += '\f';
+                    position++;
+                    break;
+                }
+                case 'n': {
+                    // Newline.
+                    unescapedContent += '\n';
+                    position++;
+                    break;
+                }
+                case 'r': {
+                    // Carriage return.
+                    unescapedContent += '\r';
+                    position++;
+                    break;
+                }
+                case 't': {
+                    // Tab.
+                    unescapedContent += '\t';
+                    position++;
+                    break;
+                }
+                case 'u': {
+                    // Unicode character.
+                    var codePoint = escapedContent.slice(position + 2, position + 6);
+                    if (!/[\da-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, "'"));
+                    }
+                    unescapedContent += String.fromCodePoint(Number.parseInt(codePoint, 16));
+                    position += 5;
+                    break;
+                }
+                default: {
+                    // Otherwise the escape character is not required.
+                    unescapedContent += nextCharacter;
+                    position++;
+                }
+            }
+        }
+        else {
+            // When there is \, simply add the character.
+            unescapedContent += character;
+        }
+    }
+    return unescapedContent;
+};
+exports.unescapeContent = unescapeContent;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "properties-file",
-  "version": "2.1.32",
+  "version": "2.2.0",
   "description": ".properties file parser, JSON converter and Webpack loader.",
   "keywords": [
     ".properties",
@@ -24,6 +24,8 @@
   "exports": {
     ".": "./lib/index.js",
     "./content": "./lib/content/index.js",
+    "./escape": "./lib/escape/index.js",
+    "./unescape": "./lib/unescape/index.js",
     "./webpack-loader": "./lib/loader/webpack.js"
   },
   "main": "lib/index.js",
@@ -33,6 +35,12 @@
       "content": [
         "lib/content/index.d.ts"
       ],
+      "escape": [
+        "lib/escape/index.d.ts"
+      ],
+      "unescape": [
+        "lib/unescape/index.d.ts"
+      ],
       "webpack-loader": [
         "lib/loader/webpack.d.ts"
       ]
@@ -44,6 +52,7 @@
   "scripts": {
     "add-import-type": "node ./src/add-import-type.mjs",
     "build": "npm run prettier && npm run lint-fix && rm -Rf ./lib && tsc && npm run add-import-type && npm run test",
+    "ci": "npm run lint-check && rm -Rf ./lib && tsc && npm run add-import-type && npm run test",
     "lint-check": "eslint --ext .js --ext .jsx --ext .ts --ext .tsx --ext .json .",
     "lint-fix": "eslint --ext .js --ext .jsx --ext .ts --ext .tsx --ext .json --fix .",
     "lint-print-config": "eslint --print-config ./eslintrc.yaml",