properties-file 4.0.0 → 5.0.1

package/README.md

@@ -2,15 +2,15 @@
 
 [![License](https://img.shields.io/npm/l/make-coverage-badge.svg?color=brightgreen)](https://opensource.org/licenses/MIT)
 [![Download Stats](https://img.shields.io/npm/dw/properties-file.svg?color=brightgreen)](https://www.npmjs.com/package/properties-file)
-![Coverage](https://img.shields.io/badge/Coverage-100%25-brightgreen.svg)
-[![Package Size](https://deno.bundlejs.com/badge?q=properties-file@latest&treeshake=[*])](https://bundlejs.com/?q=properties-file@latest&treeshake=[*])
+![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)
+![Package Size](https://img.shields.io/badge/min%2Bgzip-1.1%20kB-brightgreen)
 ![Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)
 
 `.properties` file parser, editor, formatter and bundler integrations.
 
-## Installation 💻
+## Installation
 
-> ⚠ In April 2023, we released version 3 of this package, which includes breaking changes. Please refer to the [upgrade guide](./V2-TO-V3-UPGRADE-GUIDE.md) before upgrading.
+> Doing a major version update? Check our [migration guides](./docs/migration/README.md).
 
 Add the package as a dependency:
 
@@ -18,21 +18,22 @@ Add the package as a dependency:
 npm install properties-file
 ```
 
-## What's in it for me? 🤔
+## What's in it for me?
 
 - A modern library written entirely in TypeScript that exactly reproduces the [Properties Java implementation](/assets/java-implementation.md).
 - Works for both Node.js applications and browsers that support at least [ES5](https://www.w3schools.com/js/js_es5.asp).
-- Flexible APIs:
-  - `getProperties` converts the content of `.properties` files to a key-value pair object.
-  - A `Properties` class provides insights into parsing data.
-  - 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.
-  - Bundler integrations for Webpack, Rollup/Vite, esbuild, and Bun to import `.properties` files directly. See [BUNDLER.md](./BUNDLER.md).
-- [Tiny](https://bundlejs.com/?q=properties-file%40latest&treeshake=%5B*%5D) 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).
-
-## Usage 🎬
+- Flexible, tree-shakable APIs — import only what you need, and your bundler will exclude the rest:
+  - `getProperties` converts `.properties` content to a key-value pair object.
+  - `Properties` provides lossless parsing with a full data model — every element (properties, comments, blank lines, whitespace, duplicate keys) is preserved and can be round-tripped exactly or normalized via `format()` options.
+  - `PropertiesEditor` enables insertion, edition, and removal of entries while preserving formatting.
+  - `escapeKey` and `escapeValue` convert any content to `.properties` compatible format.
+  - Bundler integrations for Webpack, Rollup/Vite, esbuild, and Bun to import `.properties` files directly. See [BUNDLER.md](./docs/BUNDLER.md).
+- **Tiny with 0 dependencies** — `getProperties` is only 1.1 kB min+gzip.
+- **Runs everywhere** — compiled to ES5, works in any browser and on Node.js all the way back to v0.10 (2013). [Verified via Docker](./tests/node-compat/).
+- **100% test coverage** based on the output from a Java implementation.
+- Active maintenance (many popular `.properties` packages have been inactive for years). See our [detailed comparison](./docs/COMPARISON.md) with other packages.
+
+## Usage
 
 We have put a lot of effort into incorporating [TSDoc](https://tsdoc.org/) into all our APIs. If you are unsure about how to use certain APIs provided in our examples, please check directly in your IDE.
 
@@ -53,103 +54,97 @@ Output:
 { hello: 'hello', world: 'world' }
 ```
 
-### `Properties` (using parsing metadata)
+### `Properties` (lossless parsing with full data model)
 
-The `Properties` object is what makes `getProperties` work under the hood, but when using it directly, you can access granular parsing metadata. Here is an example of how the object can be used to find key collisions:
+The `Properties` class parses a `.properties` file into a lossless data model where every element — properties, comments, blank lines — is preserved in order. This is useful when you need to inspect, analyze, or transform `.properties` files while retaining their exact structure.
 
 ```ts
-import { Properties } from 'properties-file'
+import { readFileSync } from 'node:fs'
+import { PropertiesNodeType, Properties } from 'properties-file/parser'
+
+const properties = new Properties(readFileSync('example.properties'))
+
+// Access all nodes in file order (properties, comments, blank lines).
+for (const node of properties.nodes) {
+  switch (node.type) {
+    case PropertiesNodeType.PROPERTY:
+      console.log(`${node.key} = ${node.value}`)
+      break
+    case PropertiesNodeType.COMMENT:
+      console.log(`Comment: ${node.delimiter}${node.body}`)
+      break
+    case PropertiesNodeType.BLANK:
+      console.log('(blank line)')
+      break
+  }
+}
+
+// Get a simple key-value object (last-wins for duplicate keys).
+console.log(properties.toObject())
+
+// Lossless round-trip: format() reproduces the exact original content.
+console.log(properties.format() === readFileSync('example.properties', 'utf8')) // true
+```
+
+#### Finding key collisions
+
+```ts
+import { Properties } from 'properties-file/parser'
 
 const properties = new Properties(
   'hello = hello1\nworld = world1\nworld = world2\nhello = hello2\nworld = world3'
 )
-console.log(properties.format())
-
-/**
- * Outputs:
- *
- * hello = hello1
- * world = world1
- * world = world2
- * hello = hello2
- * world = world3
- */
-
-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()}).`
-  )
+const collisions = properties.getKeyCollisions()
+collisions.forEach((collision) => {
+  const lines = collision.nodes.map((node) => node.startingLineNumber)
+  console.log(`Key '${collision.key}' appears on lines ${lines.join(', ')}`)
 })
 
 /**
  * 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).
+ * Key 'hello' appears on lines 1, 4
+ * Key 'world' appears on lines 2, 3, 5
  */
 ```
 
-For purposes where you require more parsing metadata, such as building a syntax highlighter, it is recommended that you access the `Property` objects included in the `Properties.collection`. These objects provide comprehensive information about each key-value pair.
+#### Normalizing output
 
-### `PropertiesEditor` (editing `.properties` content)
-
-In certain scenarios, it may be necessary to modify the content of the `.properties` key-value pair objects. This can be achieved easily using the `Properties` object, with the assistance of the `escapeKey` and `escapeValue` APIs, as demonstrated below:
+Passing options to `format()` produces a normalized version of the file with granular control over formatting:
 
 ```ts
-import { Properties } from 'properties-file'
-import { escapeKey, escapeValue } from 'properties-file/escape'
-
-const properties = new Properties('hello = hello\n# This is a comment\nworld = world')
-const newProperties: string[] = []
-
-properties.collection.forEach((property) => {
-  const key = property.key === 'world' ? 'new world' : property.key
-  const value = property.value === 'world' ? 'new world' : property.value
-  newProperties.push(`${escapeKey(key)} = ${escapeValue(value)}`)
-})
-
-console.log(newProperties.join('\n'))
+import { Properties } from 'properties-file/parser'
+
+const properties = new Properties('# comment\n\n    key : value\n    key : updated')
+
+console.log(
+  properties.format({
+    removeComments: true, // Strip all comments
+    removeBlankLines: true, // Strip all blank lines
+    removeLeadingWhitespace: true, // Strip indentation
+    deduplicateKeys: true, // Keep only last occurrence
+    separatorChar: '=', // Standardize separator
+    separatorLeading: ' ', // Space before =
+    separatorTrailing: ' ', // Space after =
+  })
+)
 
 /**
  * Outputs:
  *
- * hello = hello
- * new\ world = new world
+ * key = updated
  */
 ```
 
-The limitation of this approach is that its output contains only valid keys, without any comments or whitespace. However, if you require a more advanced editor that preserves these original elements, then the `PropertiesEditor` object is exactly what you need.
+### `PropertiesEditor` (editing `.properties` content)
+
+The `PropertiesEditor` extends `Properties` with methods to insert, update, delete, and upsert entries while preserving formatting.
 
 ```ts
 import { PropertiesEditor } from 'properties-file/editor'
 
 const properties = new PropertiesEditor('hello = hello\n# This is a comment\nworld = world')
-console.log(properties.format())
-
-/**
- * Outputs:
- *
- * hello = hello
- * # This is a comment
- * world = world
- */
 
 properties.insertComment('This is a multiline\ncomment before `newKey3`')
 properties.insert('newKey3', 'This is my third key')
@@ -161,7 +156,7 @@ properties.insert('newKey1', 'This is my first new key', {
   commentDelimiter: '!',
 })
 
-properties.insert('newKey2', 'こんにちは', {
+properties.insert('newKey2', 'hello', {
   referenceKey: 'newKey1',
   position: 'after',
   escapeUnicode: true,
@@ -180,20 +175,20 @@ console.log(properties.format())
  * world = new world
  * ! Below are the new keys being edited
  * newKey1 = This is my first new key
- * newKey2 = \u3053\u3093\u306b\u3061\u306f
+ * newKey2 = hello
  * # This is a multiline
  * # comment before `newKey3`
  * newKey3 = This is my third key
  */
 ```
 
-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.
+The editor also provides `upsert` (update or insert) and `deleteAll` (remove all occurrences of a duplicate key). Check your IDE for all available methods and options via TSDoc.
 
 ### Bundler Integrations
 
 If you would like to import `.properties` directly using `import`, this package provides integrations for all major bundlers: **Webpack/Rspack**, **Rollup/Vite/Rolldown**, **esbuild**, and **Bun**.
 
-See [BUNDLER.md](./BUNDLER.md) for setup instructions and examples.
+See [BUNDLER.md](./docs/BUNDLER.md) for setup instructions and examples.
 
 By adding these configurations you should now be able to import directly `.properties` files just like this:
 
@@ -211,11 +206,11 @@ Output:
 
 ## Why another `.properties` file package?
 
-There are probably over 20 similar packages available, but:
+There are over 20 similar packages available, but most are abandoned, incomplete, or not compliant with the Java specification. See our [detailed comparison](./docs/COMPARISON.md) for benchmarks, compliance tests, and a feature matrix against the top 5 packages. The short version:
 
-- Many of the most popular packages have had no activity for over 5 years.
-- Most packages will not replicate the current Java implementation.
-- No package offers the same capabilities as this one.
+- **100% Java spec compliance** — the only package (alongside `properties-parser`) to pass all test cases.
+- **3–7x faster** than alternatives on a 10,000-entry file.
+- **Lossless data model** — no other package preserves comments, blank lines, whitespace, and duplicate keys for round-trip editing.
 
 Unfortunately, the `.properties` file specification is not well-documented. One reason for this is that it was originally used in Java to store configurations. Today, most applications handle this using JSON, YAML, or other modern formats because these formats are more flexible.
 
@@ -233,15 +228,17 @@ Having good JavaScript/TypeScript support for `.properties` files offers more in
 
 ### How does this package work?
 
-Basically, our goal was to offer parity with the Java implementation, which is the closest thing to a specification for `.properties` files. Here is the logic behind this package in a nutshell:
+Our goal is to offer parity with the Java implementation, which is the closest thing to a specification for `.properties` files. The package provides two parsing paths:
+
+1. **`getProperties`** — a fast, functional parser optimized for the common case of converting `.properties` content to a key-value object. Uses `charCodeAt`-based scanning with zero-copy optimizations.
+
+2. **`Properties`** — a lossless parser that produces an ordered array of typed nodes (`PropertyNode`, `CommentNode`, `BlankLineNode`). Every element in the file is preserved, enabling exact round-trip reconstruction via `format()` and flexible normalization by passing options to `format()`.
+
+Both parsers are fully compliant with the Java `Properties` specification and produce identical key-value output. Just like Java, if a Unicode-escaped character (`\u`) is malformed, an error will be thrown.
 
-1. The content is split by lines, creating an array of strings where each line is an element.
-2. All lines are parsed to create a collection of `Property` objects that:
-   1. Identify key-value pair lines from the other lines (e.g., comments, blank lines, etc.).
-   2. Merge back multiline key-value pairs on single lines by removing trailing backslashes.
-   3. Unescape the keys and values.
+## Contributing
 
-Just like Java, if a Unicode-escaped character (`\u`) is malformed, an error will be thrown. However, we do not recommend using Unicode-escaped characters, but rather using UTF-8 encoding that supports more characters.
+See [CONTRIBUTING.md](./docs/CONTRIBUTING.md) for project principles, architecture, code style, and development commands.
 
 ## Additional references
 

package/dist/cjs/bundler/bun.js

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:!0});var node_fs_1=require("node:fs"),__1=require(".."),bunPlugin={name:"properties-file",setup:function(e){e.onLoad({filter:/\.properties$/},function(e){var r=e.path;return{exports:{properties:(0,__1.getProperties)((0,node_fs_1.readFileSync)(r,"utf8"))},loader:"object"}})}};exports.default=bunPlugin;
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),Object.defineProperty(exports,"default",{enumerable:!0,get:function(){return _default}});var _nodefs=require("node:fs"),_index=require("../index.js"),bunPlugin={name:"properties-file",setup:function(e){e.onLoad({filter:/\.properties$/},function(e){var r=e.path;return{exports:{properties:(0,_index.getProperties)((0,_nodefs.readFileSync)(r,"utf8"))},loader:"object"}})}},_default=bunPlugin;

package/dist/cjs/bundler/esbuild.js

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:!0});var node_fs_1=require("node:fs"),__1=require(".."),esbuildPlugin=function(){return{name:"properties-file",setup:function(e){e.onLoad({filter:/\.properties$/},function(e){var r=e.path;return{contents:"export const properties = ".concat(JSON.stringify((0,__1.getProperties)((0,node_fs_1.readFileSync)(r,"utf8"))),";"),loader:"js"}})}}};exports.default=esbuildPlugin;
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),Object.defineProperty(exports,"default",{enumerable:!0,get:function(){return _default}});var _nodefs=require("node:fs"),_index=require("../index.js"),esbuildPlugin=function(){return{name:"properties-file",setup:function(e){e.onLoad({filter:/\.properties$/},function(e){var t=e.path;return{contents:"export const properties = ".concat(JSON.stringify((0,_index.getProperties)((0,_nodefs.readFileSync)(t,"utf8"))),";"),loader:"js"}})}}},_default=esbuildPlugin;

package/dist/cjs/bundler/rollup.js

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:!0});var __1=require(".."),PROPERTIES_EXTENSION=".properties",rollupPlugin=function(){return{name:"properties-file",transform:function(e,r){return-1===r.indexOf(PROPERTIES_EXTENSION,r.length-PROPERTIES_EXTENSION.length)?null:{code:"export const properties = ".concat(JSON.stringify((0,__1.getProperties)(e)),";"),map:null}}}};exports.default=rollupPlugin;
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),Object.defineProperty(exports,"default",{enumerable:!0,get:function(){return _default}});var _index=require("../index.js"),PROPERTIES_EXTENSION=".properties",rollupPlugin=function(){return{name:"properties-file",transform:function(e,r){return-1===r.indexOf(PROPERTIES_EXTENSION,r.length-PROPERTIES_EXTENSION.length)?null:{code:"export const properties = ".concat(JSON.stringify((0,_index.getProperties)(e)),";"),map:null}}}},_default=rollupPlugin;

package/dist/cjs/bundler/webpack.js

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:!0});var __1=require(".."),webpackLoader=function(e){return"exports.properties = ".concat(JSON.stringify((0,__1.getProperties)(e)),";")};exports.default=webpackLoader;
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),Object.defineProperty(exports,"default",{enumerable:!0,get:function(){return _default}});var _index=require("../index.js"),webpackLoader=function(e){return"exports.properties = ".concat(JSON.stringify((0,_index.getProperties)(e)),";")},_default=webpackLoader;

package/dist/cjs/editor/index.d.ts

@@ -1,154 +1,161 @@
-import { KeyValuePairObject } from '..';
-import { Properties } from '../properties';
-/** The default separator between keys and values. */
-export declare const DEFAULT_SEPARATOR = "=";
-/** The default character used as comment delimiter. */
-export declare const DEFAULT_COMMENT_DELIMITER = "#";
+import { Properties } from '../parser/properties.js';
+import type { PropertyNode } from '../parser/nodes.js';
 /** Characters that can be used as key-value pair separators. */
-export type KeyValuePairSeparator = ' ' | ':' | '=';
+export type KeyValuePairSeparator = '=' | ':' | ' ';
 /** Characters that can be used as comment delimiters. */
 export type CommentDelimiter = '#' | '!';
-/** Options on the `Properties.insert` method. */
+/** Options for {@link PropertiesEditor.insert}. */
 export type InsertOptions = {
-    /** The name of the key to insert before or after. If the key not found, the new property will not be inserted. */
+    /**
+     * Insert relative to this key (last occurrence). If the key is not found,
+     * the property is appended at the end.
+     */
     referenceKey?: string;
-    /** The position of the insertion related to the `referenceKey` (default is `after`) */
+    /** Position relative to the reference key. Default: `'after'`. */
     position?: 'before' | 'after';
-    /** Escape unicode characters into ISO-8859-1 compatible encoding? */
+    /** If `true`, escape non-ASCII characters as `\\uXXXX` sequences. Default: `false`. */
     escapeUnicode?: boolean;
-    /** The key/value separator character. */
+    /** Separator character to use between key and value. Default: `'='`. */
     separator?: KeyValuePairSeparator;
-    /** A comment to insert before. */
+    /**
+     * Comment text to prepend before the property. Supports multi-line: newlines
+     * in the string create separate comment nodes. Empty lines within the text
+     * become blank line nodes.
+     */
     comment?: string;
-    /** The comment's delimiter. */
+    /** Delimiter character for the comment. Default: `'#'`. */
     commentDelimiter?: CommentDelimiter;
 };
-/** Options on the `Properties.insertComment` method. */
+/** Options for {@link PropertiesEditor.insertComment}. */
 export type InsertCommentOptions = {
-    /** The name of the key to insert before or after. If the key not found, the new property will not be inserted. */
+    /**
+     * Insert relative to this key (last occurrence). If the key is not found,
+     * the comment is appended at the end.
+     */
     referenceKey?: string;
-    /** The position of the insertion related to the `referenceKey` (default is `after`) */
+    /** Position relative to the reference key. Default: `'after'`. */
     position?: 'before' | 'after';
-    /** The comment's delimiter. */
+    /** Delimiter character for the comment. Default: `'#'`. */
     commentDelimiter?: CommentDelimiter;
 };
-/** Options on the `Properties.update` method. */
+/** Options for {@link PropertiesEditor.insertBlankLine}. */
+export type InsertBlankLineOptions = {
+    /**
+     * Insert relative to this key (last occurrence). If the key is not found,
+     * the blank line is appended at the end.
+     */
+    referenceKey?: string;
+    /** Position relative to the reference key. Default: `'after'`. */
+    position?: 'before' | 'after';
+};
+/** Options for {@link PropertiesEditor.update}. */
 export type UpdateOptions = {
-    /** Optionally replace the existing value with a new value. */
+    /** Replacement value. When not set, the original value is preserved. */
     newValue?: string;
-    /** Optionally replace the existing key with a new key name. */
+    /** Replacement key (rename). When not set, the original key is preserved. */
     newKey?: string;
-    /** Escape unicode characters into ISO-8859-1 compatible encoding? */
+    /** If `true`, escape non-ASCII characters as `\\uXXXX` sequences. Default: `false`. */
     escapeUnicode?: boolean;
-    /** A key/value separator character. */
-    separator?: ' ' | ':' | '=';
-    /** Optionally insert a new comment, or replace the existing one (including white-space characters). */
+    /** New separator character. When not set, the original separator is preserved. */
+    separator?: KeyValuePairSeparator;
+    /**
+     * Replacement comment text. When set, all comment and blank line nodes immediately
+     * preceding the property (up to the previous property) are removed and replaced
+     * with the new comment. Supports multi-line via newlines in the string.
+     */
     newComment?: string;
-    /** The comment's delimiter. */
+    /** Delimiter character for the new comment. Default: `'#'`. */
     commentDelimiter?: CommentDelimiter;
 };
-/** Options on the `Properties.upsert` method. */
+/** Options for {@link PropertiesEditor.upsert}. */
 export type UpsertOptions = {
-    /** Escape unicode characters into ISO-8859-1 compatible encoding? */
+    /** If `true`, escape non-ASCII characters as `\\uXXXX` sequences. Default: `false`. */
     escapeUnicode?: boolean;
-    /** The key/value separator character. */
+    /** Separator character. Default: `'='`. */
     separator?: KeyValuePairSeparator;
-    /** A comment to insert before. */
+    /**
+     * Comment text. When inserting a new property, this is prepended as a comment.
+     * When updating an existing property, this replaces the leading comment nodes.
+     */
     comment?: string;
-    /** The comment's delimiter. */
+    /** Delimiter character for the comment. Default: `'#'`. */
     commentDelimiter?: CommentDelimiter;
 };
+/** Options for {@link PropertiesEditor.delete}. */
+export type DeleteOptions = {
+    /**
+     * If `false`, only the property node itself is removed. If `true` (default),
+     * all comment and blank line nodes immediately preceding the property (up to
+     * the previous property) are also removed.
+     */
+    deleteLeadingNodes?: boolean;
+};
 /**
- * A .properties file editor.
+ * An editor for `.properties` files that extends the lossless {@link Properties}
+ * parser with insert, update, delete, and upsert operations.
  */
 export declare class PropertiesEditor extends Properties {
-    /** Is line parsing required to re-async the object's properties? */
-    private needsLineParsing;
-    /**
-     * Create `PropertiesEditor` object.
-     *
-     * @param content - The content of a `.properties` file.
-     */
-    constructor(content: string);
     /**
-     * Find the last occurrence of a property by key (iterates backward for performance).
+     * Find the index of the last property node with the given key.
      *
-     * @param key - The property key to search for.
+     * @param key - The unescaped key to search for.
      *
-     * @returns The last matching property, or undefined if not found.
-     */
-    private findLastPropertyByKey;
-    /**
-     * Parse the `.properties` content line by line only when needed.
+     * @returns The index in `this.nodes`, or `-1` if not found.
      */
-    private parseLinesIfNeeded;
+    private findLastPropertyIndex;
     /**
-     * Insert a new property in the existing object (by default it will be at the end).
+     * Insert a new property.
      *
-     * @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.
+     * @param key - The unescaped key.
+     * @param value - The unescaped value.
+     * @param options - Insert options.
      */
-    insert(key: string, value: string, options?: InsertOptions): boolean;
+    insert(key: string, value: string, options?: InsertOptions): void;
     /**
-     * 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.
+     * Insert a comment.
      *
-     * @returns True if the comment was inserted, otherwise false.
+     * @param comment - The comment text (may contain newlines).
+     * @param options - Insert comment options.
      */
-    insertComment(comment: string, options?: InsertCommentOptions): boolean;
+    insertComment(comment: string, options?: InsertCommentOptions): void;
     /**
-     * Delete the last occurrence of a given key from the existing object.
+     * Insert a blank line.
      *
-     * @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.
+     * @param options - Insert blank line options.
      */
-    delete(key: string, deleteCommentsAndWhiteSpace?: boolean): boolean;
+    insertBlankLine(options?: InsertBlankLineOptions): void;
     /**
-     * Restore the original newline characters of a key.
+     * Update an existing property.
      *
-     * @param property - A property object.
+     * @param key - The unescaped key to update (uses last occurrence).
+     * @param options - Update options.
      *
-     * @returns The key with its original newlines characters restored.
+     * @returns `true` if the property was found and updated, `false` otherwise.
      */
-    private getKeyWithNewlines;
+    update(key: string, options: UpdateOptions): boolean;
     /**
-     * Restore the original newline characters of a value.
-     *
-     * @param property - A property object.
+     * Update a property if it exists, or insert it if it doesn't.
      *
-     * @returns The value with its original newlines characters restored.
+     * @param key - The unescaped key.
+     * @param value - The unescaped value.
+     * @param options - Upsert options.
      */
-    private getValueWithNewlines;
+    upsert(key: string, value: string, options?: UpsertOptions): void;
     /**
-     * Update the last occurrence of a given key from the existing object.
+     * Delete the last occurrence of a property (the effective value in last-wins semantics).
      *
-     * @param key - The name of the key to update.
-     * @param options - Additional options.
+     * @param key - The unescaped key to delete.
+     * @param options - Delete options.
      *
-     * @returns True if the key was updated, otherwise false.
+     * @returns The deleted {@link PropertyNode}, or `undefined` if the key was not found.
      */
-    update(key: string, options?: UpdateOptions): boolean;
+    delete(key: string, options?: DeleteOptions): PropertyNode | undefined;
     /**
-     * Update a key if it exist, otherwise add it at the end.
+     * Delete all occurrences of a key.
      *
-     * @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.
-     */
-    upsert(key: string, value: string, options?: UpsertOptions): boolean;
-    /**
-     * Get the key/value object representing the properties.
+     * @param key - The unescaped key to delete.
      *
-     * @returns A key/value object representing the properties.
+     * @returns An array of the deleted {@link PropertyNode} instances.
      */
-    toObject(): KeyValuePairObject;
+    deleteAll(key: string): PropertyNode[];
 }