projen/node_modules/properties-file/dist/esm/editor/index.d.ts

CDK for software projects

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 = '=' | ':' | ' ';
/** Characters that can be used as comment delimiters. */
export type CommentDelimiter = '#' | '!';
/** Options for {@link PropertiesEditor.insert}. */
export type InsertOptions = {
    /**
     * Insert relative to this key (last occurrence). If the key is not found,
     * the property is appended at the end.
     */
    referenceKey?: string;
    /** Position relative to the reference key. Default: `'after'`. */
    position?: 'before' | 'after';
    /** If `true`, escape non-ASCII characters as `\\uXXXX` sequences. Default: `false`. */
    escapeUnicode?: boolean;
    /** Separator character to use between key and value. Default: `'='`. */
    separator?: KeyValuePairSeparator;
    /**
     * 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;
    /** Delimiter character for the comment. Default: `'#'`. */
    commentDelimiter?: CommentDelimiter;
};
/** Options for {@link PropertiesEditor.insertComment}. */
export type InsertCommentOptions = {
    /**
     * Insert relative to this key (last occurrence). If the key is not found,
     * the comment is appended at the end.
     */
    referenceKey?: string;
    /** Position relative to the reference key. Default: `'after'`. */
    position?: 'before' | 'after';
    /** Delimiter character for the comment. Default: `'#'`. */
    commentDelimiter?: CommentDelimiter;
};
/** 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 = {
    /** Replacement value. When not set, the original value is preserved. */
    newValue?: string;
    /** Replacement key (rename). When not set, the original key is preserved. */
    newKey?: string;
    /** If `true`, escape non-ASCII characters as `\\uXXXX` sequences. Default: `false`. */
    escapeUnicode?: boolean;
    /** 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;
    /** Delimiter character for the new comment. Default: `'#'`. */
    commentDelimiter?: CommentDelimiter;
};
/** Options for {@link PropertiesEditor.upsert}. */
export type UpsertOptions = {
    /** If `true`, escape non-ASCII characters as `\\uXXXX` sequences. Default: `false`. */
    escapeUnicode?: boolean;
    /** Separator character. Default: `'='`. */
    separator?: KeyValuePairSeparator;
    /**
     * 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;
    /** 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;
    /**
     * Which occurrence of the key to delete when duplicates exist.
     * - `'last'` (default) — deletes the last occurrence (the effective value in
     *   Java's last-wins semantics).
     * - `'first'` — deletes the first occurrence. Useful for cleaning up duplicate
     *   keys while keeping the effective value.
     */
    occurrence?: 'first' | 'last';
};
/**
 * 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 {
    /**
     * Find the first property node with the given key.
     *
     * @param key - The unescaped key to search for.
     *
     * @returns The matching node and its index in `this.nodes`, or `undefined`.
     */
    private findFirstProperty;
    /**
     * Find the last property node with the given key.
     *
     * @param key - The unescaped key to search for.
     *
     * @returns The matching node and its index in `this.nodes`, or `undefined`.
     */
    private findLastProperty;
    /**
     * Insert a new property.
     *
     * @param key - The unescaped key.
     * @param value - The unescaped value.
     * @param options - Insert options.
     */
    insert(key: string, value: string, options?: InsertOptions): void;
    /**
     * Insert a comment.
     *
     * @param comment - The comment text (may contain newlines).
     * @param options - Insert comment options.
     */
    insertComment(comment: string, options?: InsertCommentOptions): void;
    /**
     * Insert a blank line.
     *
     * @param options - Insert blank line options.
     */
    insertBlankLine(options?: InsertBlankLineOptions): void;
    /**
     * Update an existing property.
     *
     * @param key - The unescaped key to update (uses last occurrence).
     * @param options - Update options.
     *
     * @returns `true` if the property was found and updated, `false` otherwise.
     */
    update(key: string, options: UpdateOptions): boolean;
    /**
     * Update a property if it exists, or insert it if it doesn't.
     *
     * @param key - The unescaped key.
     * @param value - The unescaped value.
     * @param options - Upsert options.
     */
    upsert(key: string, value: string, options?: UpsertOptions): void;
    /**
     * Delete an occurrence of a property.
     *
     * By default, deletes the last occurrence (the effective value in Java's last-wins
     * semantics). Use `{ occurrence: 'first' }` to delete the first occurrence instead,
     * which is useful for cleaning up duplicate keys while keeping the effective value.
     *
     * @param key - The unescaped key to delete.
     * @param options - Delete options.
     *
     * @returns The deleted {@link PropertyNode}, or `undefined` if the key was not found.
     */
    delete(key: string, options?: DeleteOptions): PropertyNode | undefined;
    /**
     * Delete all occurrences of a key.
     *
     * @param key - The unescaped key to delete.
     *
     * @returns An array of the deleted {@link PropertyNode} instances.
     */
    deleteAll(key: string): PropertyNode[];
}