properties-file 3.0.0 → 3.1.1

package/README.md

@@ -28,7 +28,7 @@ npm install properties-file
   - A `PropertiesEditor` class enables the addition, edition, and removal of entries.
   - `escapeKey` and `escapeValue` allow the conversion of any content to a `.properties` compatible format.
   - The library also includes a Webpack loader to import `.properties` files directly into your application.
-- Tiny ([under 2kB compressed](https://bundlephobia.com/package/properties-file)) with 0 dependencies.
+- Tiny ([under 3kB compressed](https://bundlephobia.com/package/properties-file)) with 0 dependencies.
 - 100% test coverage based on the output from a Java implementation.
 - Active maintenance (many popular `.properties` packages have been inactive for years).
 
@@ -167,14 +167,17 @@ properties.insert('newKey2', 'こんにちは', {
   escapeUnicode: true,
 })
 
-properties.remove('hello')
+properties.delete('hello')
+properties.update('world', {
+  newValue: 'new world',
+})
 console.log(properties.format())
 
 /**
  * Outputs:
  *
  * # This is a comment
- * world = world
+ * world = new world
  * ! Below are the new keys being edited
  * newKey1 = This is my first new key
  * newKey2 = \u3053\u3093\u306b\u3061\u306f
@@ -184,6 +187,8 @@ console.log(properties.format())
  */
 ```
 
+For convenience, we also added an `upsert` method that allows updating a key if it exists or adding it at the end, when it doesn't. Make sure to check in your IDE for all available methods and options in our TSDoc.
+
 ### 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:

package/lib/editor/index.d.ts

@@ -31,8 +31,8 @@ export type InsertCommentOptions = {
     /** The comment's delimiter. */
     commentDelimiter?: CommentDelimiter;
 };
-/** Options on the `Properties.edit` method. */
-export type EditOptions = {
+/** Options on the `Properties.update` method. */
+export type UpdateOptions = {
     /** Optionally replace the existing value with a new value. */
     newValue?: string;
     /** Optionally replace the existing key with a new key name. */
@@ -46,6 +46,17 @@ export type EditOptions = {
     /** The comment's delimiter. */
     commentDelimiter?: CommentDelimiter;
 };
+/** Options on the `Properties.upsert` method. */
+export type UpsertOptions = {
+    /** Escape unicode characters into ISO-8859-1 compatible encoding? */
+    escapeUnicode?: boolean;
+    /** The key/value separator character. */
+    separator?: KeyValuePairSeparator;
+    /** A comment to insert before. */
+    comment?: string;
+    /** The comment's delimiter. */
+    commentDelimiter?: CommentDelimiter;
+};
 /**
  * A .properties file editor.
  */
@@ -62,22 +73,28 @@ export declare class PropertiesEditor extends Properties {
      * @param key - A property key (unescaped).
      * @param value - A property value (unescaped).
      * @param options - Additional options.
+     *
+     * @returns True if the key was inserted, otherwise false.
      */
-    insert(key: string, value: string, options?: InsertOptions): void;
+    insert(key: string, value: string, options?: InsertOptions): boolean;
     /**
      * Insert a new comment in the existing object (by default it will be at the end).
      *
      * @param comment - The comment to add.
      * @param options - Additional options.
+     *
+     * @returns True if the comment was inserted, otherwise false.
      */
-    insertComment(comment: string, options?: InsertCommentOptions): void;
+    insertComment(comment: string, options?: InsertCommentOptions): boolean;
     /**
-     * Remove the last occurrence of a given key from the existing object.
+     * Delete the last occurrence of a given key from the existing object.
+     *
+     * @param key - The name of the key to delete.
+     * @param deleteCommentsAndWhiteSpace - By default, comments and white-space characters before the key will be deleted.
      *
-     * @param key - The name of the key to remove.
-     * @param removeCommentsAndWhiteSpace - By default, comments and white-space characters before the key will be removed.
+     * @returns True if the key was deleted, otherwise false.
      */
-    remove(key: string, removeCommentsAndWhiteSpace?: boolean): void;
+    delete(key: string, deleteCommentsAndWhiteSpace?: boolean): boolean;
     /**
      * Restore the original newline characters of a key.
      *
@@ -95,10 +112,22 @@ export declare class PropertiesEditor extends Properties {
      */
     private getValueWithNewlines;
     /**
-     * Edit the last occurrence of a given key from the existing object.
+     * Update the last occurrence of a given key from the existing object.
+     *
+     * @param key - The name of the key to update.
+     * @param options - Additional options.
+     *
+     * @returns True if the key was updated, otherwise false.
+     */
+    update(key: string, options?: UpdateOptions): boolean;
+    /**
+     * Update a key if it exist, otherwise add it at the end.
      *
-     * @param key - The name of the key to edit.
+     * @param key - A property key (unescaped).
+     * @param value - A property value (unescaped).
      * @param options - Additional options.
+     *
+     * @returns True if the key was updated or inserted, otherwise false.
      */
-    edit(key: string, options?: EditOptions): void;
+    upsert(key: string, value: string, options?: UpsertOptions): boolean;
 }

package/lib/editor/index.js

@@ -66,6 +66,8 @@ var PropertiesEditor = /** @class */ (function (_super) {
      * @param key - A property key (unescaped).
      * @param value - A property value (unescaped).
      * @param options - Additional options.
+     *
+     * @returns True if the key was inserted, otherwise false.
      */
     PropertiesEditor.prototype.insert = function (key, value, options) {
         var _a;
@@ -78,17 +80,17 @@ var PropertiesEditor = /** @class */ (function (_super) {
             : " ".concat(exports.DEFAULT_SEPARATOR, " ").replace('  ', ' ');
         var referenceKey = options === null || options === void 0 ? void 0 : options.referenceKey;
         var position = (options === null || options === void 0 ? void 0 : options.position) || 'after';
-        // Allow to add multiline keys.
+        // Allow multiline keys.
         var multilineKey = key
             .split(/\r?\n/)
             .map(function (key) { return (0, escape_1.escapeKey)(key, escapeUnicode); })
             .join('\\\n');
-        // Allow to add multiline values.
+        // Allow multiline values.
         var multilineValue = value
             .split(/\r?\n/)
             .map(function (value) { return (0, escape_1.escapeValue)(value, escapeUnicode); })
             .join('\\\n');
-        // Allow to add multiline comments.
+        // Allow multiline comments.
         var commentPrefix = "".concat((options === null || options === void 0 ? void 0 : options.commentDelimiter) || exports.DEFAULT_COMMENT_DELIMITER, " ");
         var multilineComment = (options === null || options === void 0 ? void 0 : options.comment) === undefined
             ? ''
@@ -98,6 +100,7 @@ var PropertiesEditor = /** @class */ (function (_super) {
             // Insert the new property at the end if the reference key was not defined.
             (_a = this.lines).push.apply(_a, __spreadArray([], __read(newLines), false));
             this.parseLines();
+            return true;
         }
         else {
             // Find the last occurrence of the reference key.
@@ -110,7 +113,9 @@ var PropertiesEditor = /** @class */ (function (_super) {
                     : (_c = (_b = property.previousProperty) === null || _b === void 0 ? void 0 : _b.endingLineNumber) !== null && _c !== void 0 ? _c : 0;
                 this.lines = __spreadArray(__spreadArray(__spreadArray([], __read(this.lines.slice(0, insertPosition)), false), __read(newLines), false), __read(this.lines.slice(insertPosition)), false);
                 this.parseLines();
+                return true;
             }
+            return false;
         }
     };
     /**
@@ -118,13 +123,15 @@ var PropertiesEditor = /** @class */ (function (_super) {
      *
      * @param comment - The comment to add.
      * @param options - Additional options.
+     *
+     * @returns True if the comment was inserted, otherwise false.
      */
     PropertiesEditor.prototype.insertComment = function (comment, options) {
         var _a;
         var _b, _c;
         var referenceKey = options === null || options === void 0 ? void 0 : options.referenceKey;
         var position = (options === null || options === void 0 ? void 0 : options.position) || 'after';
-        // Allow to add multiline comments.
+        // Allow multiline comments.
         var commentPrefix = "".concat((options === null || options === void 0 ? void 0 : options.commentDelimiter) || exports.DEFAULT_COMMENT_DELIMITER, " ");
         var newLines = "".concat(commentPrefix).concat(comment)
             .replace(/\r?\n/g, "\n".concat(commentPrefix))
@@ -133,6 +140,7 @@ var PropertiesEditor = /** @class */ (function (_super) {
             // Insert the new comment at the end if the reference key was not defined.
             (_a = this.lines).push.apply(_a, __spreadArray([], __read(newLines), false));
             this.parseLines();
+            return true;
         }
         else {
             // Find the last occurrence of the reference key.
@@ -145,28 +153,34 @@ var PropertiesEditor = /** @class */ (function (_super) {
                     : (_c = (_b = property.previousProperty) === null || _b === void 0 ? void 0 : _b.endingLineNumber) !== null && _c !== void 0 ? _c : 0;
                 this.lines = __spreadArray(__spreadArray(__spreadArray([], __read(this.lines.slice(0, insertPosition)), false), __read(newLines), false), __read(this.lines.slice(insertPosition)), false);
                 this.parseLines();
+                return true;
             }
+            return false;
         }
     };
     /**
-     * Remove the last occurrence of a given key from the existing object.
+     * Delete the last occurrence of a given key from the existing object.
      *
-     * @param key - The name of the key to remove.
-     * @param removeCommentsAndWhiteSpace - By default, comments and white-space characters before the key will be removed.
+     * @param key - The name of the key to delete.
+     * @param deleteCommentsAndWhiteSpace - By default, comments and white-space characters before the key will be deleted.
+     *
+     * @returns True if the key was deleted, otherwise false.
      */
-    PropertiesEditor.prototype.remove = function (key, removeCommentsAndWhiteSpace) {
+    PropertiesEditor.prototype.delete = function (key, deleteCommentsAndWhiteSpace) {
         var _a, _b;
-        if (removeCommentsAndWhiteSpace === void 0) { removeCommentsAndWhiteSpace = true; }
+        if (deleteCommentsAndWhiteSpace === void 0) { deleteCommentsAndWhiteSpace = true; }
         // Find the last occurrence of the key.
         var property = __spreadArray([], __read(this.collection), false).reverse().find(function (property) { return property.key === key; });
         if (property) {
-            var startLine = removeCommentsAndWhiteSpace
+            var startLine = deleteCommentsAndWhiteSpace
                 ? (_b = (_a = property.previousProperty) === null || _a === void 0 ? void 0 : _a.endingLineNumber) !== null && _b !== void 0 ? _b : 0
                 : property.startingLineNumber - 1;
             var endLine = property.endingLineNumber;
             this.lines = __spreadArray(__spreadArray([], __read(this.lines.slice(0, startLine)), false), __read(this.lines.slice(endLine)), false);
             this.parseLines();
+            return true;
         }
+        return false;
     };
     /**
      * Restore the original newline characters of a key.
@@ -204,45 +218,68 @@ var PropertiesEditor = /** @class */ (function (_super) {
                 }, '');
     };
     /**
-     * Edit the last occurrence of a given key from the existing object.
+     * Update the last occurrence of a given key from the existing object.
      *
-     * @param key - The name of the key to edit.
+     * @param key - The name of the key to update.
      * @param options - Additional options.
+     *
+     * @returns True if the key was updated, otherwise false.
      */
-    PropertiesEditor.prototype.edit = function (key, options) {
+    PropertiesEditor.prototype.update = function (key, options) {
         var _a, _b, _c, _d;
-        // Find the last occurrence of the key to edit.
+        // Find the last occurrence of the key to update.
         var property = __spreadArray([], __read(this.collection), false).reverse().find(function (property) { return property.key === key; });
-        if (!property) {
-            return;
+        if (!property || !options) {
+            return false;
         }
-        var escapeUnicode = (options === null || options === void 0 ? void 0 : options.escapeUnicode) || false;
-        var separator = (options === null || options === void 0 ? void 0 : options.separator)
+        var escapeUnicode = options.escapeUnicode || false;
+        var separator = options.separator
             ? options.separator === ' '
                 ? ' '
                 : " ".concat(options.separator, " ")
             : property.separator || " ".concat(exports.DEFAULT_SEPARATOR, " ").replace('  ', ' ');
-        // Allow to edit multiline keys.
-        var multilineKey = ((_a = options === null || options === void 0 ? void 0 : options.newKey) !== null && _a !== void 0 ? _a : this.getKeyWithNewlines(property))
+        // Allow multiline keys.
+        var multilineKey = ((_a = options.newKey) !== null && _a !== void 0 ? _a : this.getKeyWithNewlines(property))
             .split(/\r?\n/)
             .map(function (key) { return (0, escape_1.escapeKey)(key, escapeUnicode); })
             .join('\\\n');
-        // Allow to edit multiline values.
-        var multilineValue = ((_b = options === null || options === void 0 ? void 0 : options.newValue) !== null && _b !== void 0 ? _b : this.getValueWithNewlines(property))
+        // Allow multiline values.
+        var multilineValue = ((_b = options.newValue) !== null && _b !== void 0 ? _b : this.getValueWithNewlines(property))
             .split(/\r?\n/)
             .map(function (value) { return (0, escape_1.escapeValue)(value, escapeUnicode); })
             .join('\\\n');
-        // Allow to edit multiline comments.
-        var commentPrefix = "".concat((options === null || options === void 0 ? void 0 : options.commentDelimiter) || exports.DEFAULT_COMMENT_DELIMITER, " ");
-        var multilineComment = (options === null || options === void 0 ? void 0 : options.newComment) === undefined
+        // Allow multiline comments.
+        var commentPrefix = "".concat(options.commentDelimiter || exports.DEFAULT_COMMENT_DELIMITER, " ");
+        var multilineComment = options.newComment === undefined
             ? ''
             : "".concat("".concat(commentPrefix).concat(options.newComment).split(/\r?\n/).join("\n".concat(commentPrefix)), "\n");
         var newLines = "".concat(multilineComment).concat(multilineKey).concat(separator).concat(multilineValue).split(/\n/);
         // Replace the existing property with the new one.
-        this.lines = __spreadArray(__spreadArray(__spreadArray([], __read(this.lines.slice(0, (options === null || options === void 0 ? void 0 : options.newComment) === undefined
+        this.lines = __spreadArray(__spreadArray(__spreadArray([], __read(this.lines.slice(0, options.newComment === undefined
             ? property.startingLineNumber - 1
             : (_d = (_c = property.previousProperty) === null || _c === void 0 ? void 0 : _c.endingLineNumber) !== null && _d !== void 0 ? _d : 0)), false), __read(newLines), false), __read(this.lines.slice(property.endingLineNumber)), false);
         this.parseLines();
+        return true;
+    };
+    /**
+     * Update a key if it exist, otherwise add it at the end.
+     *
+     * @param key - A property key (unescaped).
+     * @param value - A property value (unescaped).
+     * @param options - Additional options.
+     *
+     * @returns True if the key was updated or inserted, otherwise false.
+     */
+    PropertiesEditor.prototype.upsert = function (key, value, options) {
+        return this.keyLineNumbers[key]
+            ? this.update(key, {
+                newValue: value,
+                newComment: options === null || options === void 0 ? void 0 : options.comment,
+                commentDelimiter: options === null || options === void 0 ? void 0 : options.commentDelimiter,
+                separator: options === null || options === void 0 ? void 0 : options.separator,
+                escapeUnicode: options === null || options === void 0 ? void 0 : options.escapeUnicode,
+            })
+            : this.insert(key, value, options);
     };
     return PropertiesEditor;
 }(properties_1.Properties));

package/lib/properties.d.ts

@@ -8,6 +8,14 @@ export declare const BOM = "\uFEFF";
 export declare const BOM_CODE_POINT: number | undefined;
 /** The default end of line character. */
 export declare const DEFAULT_END_OF_LINE_CHARACTER = "\n";
+/**
+ * Get the first end of line (EOL) character from multiline content.
+ *
+ * @param content - The content of a `.properties` file.
+ *
+ * @returns The multiline content's first end of line (EOL) character.
+ */
+export declare const getFirstEolCharacter: (content: string) => string | undefined;
 /**
  * A class representing the content of a .properties file.
  */

package/lib/properties.js

@@ -27,7 +27,7 @@ var __read = (this && this.__read) || function (o, n) {
     return ar;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.KeyCollisions = exports.Properties = exports.DEFAULT_END_OF_LINE_CHARACTER = exports.BOM_CODE_POINT = exports.BOM = void 0;
+exports.KeyCollisions = exports.Properties = exports.getFirstEolCharacter = exports.DEFAULT_END_OF_LINE_CHARACTER = exports.BOM_CODE_POINT = exports.BOM = void 0;
 var property_1 = require("./property");
 var property_line_1 = require("./property-line");
 /**
@@ -48,6 +48,7 @@ var getFirstEolCharacter = function (content) {
     var newlineIndex = content.indexOf('\n');
     return newlineIndex < 0 ? undefined : "".concat(content[newlineIndex - 1] === '\r' ? '\r' : '', "\n");
 };
+exports.getFirstEolCharacter = getFirstEolCharacter;
 /**
  * A class representing the content of a .properties file.
  */
@@ -63,9 +64,9 @@ var Properties = /** @class */ (function () {
         this.collection = [];
         /** Object associating keys with their starting line numbers. */
         this.keyLineNumbers = {};
-        var stringContent = Buffer.isBuffer(content) ? content.toString() : content;
+        var stringContent = typeof content === 'string' ? content : content.toString();
         this.hasBom = stringContent.codePointAt(0) === exports.BOM_CODE_POINT;
-        this.eolCharacter = (_a = getFirstEolCharacter(stringContent)) !== null && _a !== void 0 ? _a : exports.DEFAULT_END_OF_LINE_CHARACTER;
+        this.eolCharacter = (_a = (0, exports.getFirstEolCharacter)(stringContent)) !== null && _a !== void 0 ? _a : exports.DEFAULT_END_OF_LINE_CHARACTER;
         this.lines = (this.hasBom ? stringContent.slice(1) : stringContent).split(/\r?\n/);
         this.parseLines();
     }
@@ -134,7 +135,7 @@ var Properties = /** @class */ (function () {
             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.
+            // Remove the collision from the collection (we only keep latest value).
             this.collection = this.collection.filter(function (existingPropertyObject) { return existingPropertyObject.key !== property.key; });
         }
         else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "properties-file",
-  "version": "3.0.0",
+  "version": "3.1.1",
   "description": ".properties file parser, editor, formatter and Webpack loader.",
   "keywords": [
     ".properties",
@@ -54,7 +54,7 @@
   "scripts": {
     "add-import-type": "ts-node ./src/add-import-type.ts && rm -f ./lib/add-import-type.*",
     "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",
+    "ci": "npm run build",
     "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",
@@ -65,8 +65,8 @@
   "devDependencies": {
     "@release-it/conventional-changelog": "5.1.1",
     "@types/jest": "29.5.1",
-    "@typescript-eslint/eslint-plugin": "5.59.0",
-    "@typescript-eslint/parser": "5.59.0",
+    "@typescript-eslint/eslint-plugin": "5.59.1",
+    "@typescript-eslint/parser": "5.59.1",
     "dotenv-cli": "7.2.1",
     "eslint": "8.39.0",
     "eslint-config-prettier": "8.8.0",
@@ -83,7 +83,7 @@
     "prettier": "2.8.8",
     "prettier-plugin-organize-imports": "3.2.2",
     "prettier-plugin-sh": "0.12.8",
-    "release-it": "15.10.1",
+    "release-it": "15.10.2",
     "ts-jest": "29.1.0",
     "ts-node": "10.9.1",
     "typescript": "5.0.4"