@controlium/utils 0.0.0

package/dist/types/detokeniser/detokeniser.d.ts

@@ -0,0 +1,402 @@
+/**
+ * Processes strings containing tokens in the format `[[tokenType|expression|format]]`, replacing each
+ * token with its resolved value. Tokens can be nested — the innermost is always resolved first.
+ *
+ * ## Token syntax
+ * ```
+ * [[tokenType|expression|format]]
+ * ```
+ * - **tokenType** — identifies the built-in handler or is matched against registered callbacks
+ * - **expression** — what to compute (type-specific)
+ * - **format** — how to format the result (type-specific, often optional)
+ *
+ * The delimiter `|` and the `[[` / `]]` endstops are configurable via {@link Detokeniser.delimiter} and
+ * {@link Detokeniser.tokenStartEndChars}, but the defaults cover the vast majority of use cases.
+ *
+ * ---
+ * ## Built-in token types
+ *
+ * ### `random` — random data
+ * | Expression | Format | Example | Sample output |
+ * |---|---|---|---|
+ * | `digits` | count | `[[random\|digits\|6]]` | `482910` |
+ * | `letters` | count | `[[random\|letters\|4]]` | `xKpQ` |
+ * | `lowercaseletters` | count | `[[random\|lowercaseletters\|4]]` | `xkpq` |
+ * | `uppercaseletters` | count | `[[random\|uppercaseletters\|4]]` | `XKPQ` |
+ * | `alphanumerics` | count | `[[random\|alphanumerics\|8]]` | `a3Kx92Zp` |
+ * | `from(<chars>)` | count | `[[random\|from(aeiou)\|3]]` | `ioa` |
+ * | `float(min,max)` | decimal places | `[[random\|float(1.5,3.7)\|2]]` | `2.83` |
+ * | `date(fromEpoch,toEpoch)` | date format | `[[random\|date(0,1700000000000)\|yyyy-MM-dd]]` | `1994-07-12` |
+ *
+ * ### `date` / `date(<state>)` — date and time
+ * Format is a [date-fns format string](https://date-fns.org/docs/format), or the special values
+ * `epoch` (milliseconds since 1970-01-01) or `second-epoch`.
+ *
+ * | Expression | Example | Sample output |
+ * |---|---|---|
+ * | `today` / `now` | `[[date\|today\|dd-MM-yyyy]]` | `01-04-2026` |
+ * | `yesterday` | `[[date\|yesterday\|dd-MM-yyyy]]` | `31-03-2026` |
+ * | `tomorrow` | `[[date\|tomorrow\|dd-MM-yyyy]]` | `02-04-2026` |
+ * | `addYears(n)` | `[[date\|addYears(-1)\|yyyy]]` | `2025` |
+ * | `addMonths(n)` | `[[date\|addMonths(3)\|MMM yyyy]]` | `Jul 2026` |
+ * | `addDays(n)` | `[[date\|addDays(5)\|dd-MM-yyyy]]` | `06-04-2026` |
+ * | `addHours(n)` | `[[date\|addHours(2)\|HH:mm]]` | `14:30` |
+ * | `addMinutes(n)` | `[[date\|addMinutes(30)\|HH:mm]]` | `13:00` |
+ * | `random(fromEpoch,toEpoch)` | date format | `[[date\|random(0,1700000000000)\|yyyy-MM-dd]]` | random date |
+ * | `followingDay(epoch,dayName)` | date format | `[[date\|followingDay(1711929600000,wednesday)\|dd-MM-yyyy]]` | next Wednesday |
+ * | `yyyy-MM-dd` _(fixed date)_ | date format | `[[date\|2026-06-15\|EEEE]]` | `Monday` |
+ * | `timezoneOffset` _(with region)_ | _(none)_ | `[[date(us-east)\|timezoneOffset]]` | `-0500` |
+ *
+ * A region qualifier routes date formatting through the region's IANA timezone (resolved by the
+ * consumer-provided `PublicHolidays` module):
+ * ```
+ * [[date(eu-london)|today|HH:mm]]        ← formatted in London time
+ * [[date(us-east)|addDays(1)|dd-MM-yyyy]]
+ * ```
+ *
+ * The following expressions are **async-only** — use {@link Detokeniser.doAsync} with a region qualifier:
+ * - `addWorkingDays(n)` — adds business days, skipping weekends and public holidays
+ * - `followingWorkingDay(epoch,dayName)` — as `followingDay` but skips weekends and public holidays
+ * - `nextPublicHoliday(fromEpoch,maxDays)` — next public holiday within a search window
+ *
+ * ```typescript
+ * await Detokeniser.doAsync('[[date(us-east)|addWorkingDays(5)|dd-MM-yyyy]]');
+ * await Detokeniser.doAsync('[[date(eu-london)|nextPublicHoliday([[date|today|epoch]],90)|dd-MM-yyyy]]');
+ * ```
+ *
+ * ### `setting` — retrieve a configured value
+ * Parameters are given as JSON key/value pairs after the delimiter. Resolution order:
+ * process env → npm config → context parameters → default value.
+ * ```
+ * [[setting|processEnvName: "MY_VAR"]]
+ * [[setting|processEnvName: "MY_VAR", defaultValue: "fallback"]]
+ * [[setting|npmPackageConfigName: "myconfig"]]
+ * [[setting|profileParameterName: "myParam", defaultValue: "none"]]
+ * ```
+ *
+ * ### `base64` — encode or decode
+ * ```
+ * [[base64|encode|Hello World]]        →  SGVsbG8gV29ybGQ=
+ * [[base64|decode|SGVsbG8gV29ybGQ=]]   →  Hello World
+ * ```
+ *
+ * ### `jwt` — generate a signed JWT
+ * ```
+ * [[jwt|{"sub":"1234","name":"Test"}|MySecret]]
+ * [[jwt|{"sub":"1234"}|MySecret|{"algorithm":"HS256"}]]
+ * ```
+ *
+ * ### `mockintercepts` — harvest a value from intercepted mock requests
+ * ```
+ * [[mockintercepts|$.requests[0].body.userId]]
+ * ```
+ *
+ * ---
+ * ## Nesting
+ * Tokens are resolved innermost-first, so nested tokens compose naturally:
+ * ```typescript
+ * // Date N random days from now, where N is itself a random digit
+ * Detokeniser.do('[[date|addDays([[random|digits|1]])|dd-MM-yyyy]]');
+ *
+ * // Next NSW public holiday from today (async — needs doAsync)
+ * await Detokeniser.doAsync('[[date(eu-london)|nextPublicHoliday([[date|today|epoch]],90)|dd-MM-yyyy]]');
+ * ```
+ *
+ * ---
+ * ## Escaping
+ * The escape character is `/` (configurable via `EscapeChar`). Escaping applies both inside and
+ * outside tokens. A double escape `//` produces a literal `/`.
+ *
+ * | Input | Output | Notes |
+ * |---|---|---|
+ * | `/[[` | `[[` | Literal `[[` — not treated as token start |
+ * | `/]]` | `]]` | Literal `]]` — not treated as token end |
+ * | `//` | `/` | Literal escape char |
+ * | `[[random\|from(xyz/[[)\|3]]` | 3 chars from `xyz[[` | `/[[` inside `from()` = `/[` (→`[`) + `[` = two `[` (higher weight) |
+ * | `[[random\|from(abc/))\|2]]` | 2 chars from `abc)` | `/)` inside `from()` = literal `)` |
+ *
+ * ---
+ * ## Extending with callbacks
+ * Custom token types are registered via {@link Detokeniser.addCallbackSync} (for sync processing) or
+ * {@link Detokeniser.addCallbackAsync} (for async processing). Callbacks are tried in registration
+ * order; return `undefined` to pass to the next callback. If all callbacks return `undefined` and no
+ * built-in handler matched, an error is thrown.
+ *
+ * @see {@link Detokeniser.addCallbackSync}
+ * @see {@link Detokeniser.addCallbackAsync}
+ * @see {@link Detokeniser.do}
+ * @see {@link Detokeniser.doAsync}
+ */
+export declare class Detokeniser {
+    private static _endTokenChar;
+    private static _startTokenChar;
+    private static EscapeChar;
+    private static _delimiter;
+    private static _asyncCallbacks;
+    private static _syncCallbacks;
+    /**
+     * Gets the current single-character delimiter used to separate token parts.
+     * Default: `|`
+     */
+    static get delimiter(): string;
+    /**
+     * Sets the single-character delimiter used to separate token parts.
+     * The new value applies to all subsequent {@link Detokeniser.do} / {@link Detokeniser.doAsync} calls.
+     * @param newDelimiter - Exactly one character
+     * @throws If `newDelimiter` is not exactly one character
+     * @example
+     * Detokeniser.delimiter = ':';
+     * Detokeniser.do('[[random:digits:6]]'); // → e.g. '482910'
+     * Detokeniser.reset();                   // restore default '|'
+     */
+    static set delimiter(newDelimiter: string);
+    /**
+     * Sets the start and end token sequences.
+     * @param startEndChars - An even-length string whose first half is the start sequence and second half the end sequence.
+     * @example Detokeniser.tokenStartEndChars = "[[]]"; // start = "[[", end = "]]"
+     * @remarks Start and end sequences must differ. Minimum total length is 2 (one char each).
+     */
+    static set tokenStartEndChars(startEndChars: string);
+    /**
+     * Gets the current token start/end sequences concatenated (e.g. `"[[]]"`).
+     */
+    static get tokenStartEndChars(): string;
+    /**
+     * Resets the Detokeniser to factory defaults:
+     * - Token endstops restored to `[[` / `]]`
+     * - Delimiter restored to `|`
+     * - Escape char restored to `/`
+     * - All registered sync and async callbacks cleared
+     *
+     * Call this in test teardown to guarantee a clean state between scenarios.
+     * @example
+     * afterEach(() => Detokeniser.reset());
+     */
+    static reset(): void;
+    /**
+     * Registers a synchronous custom token handler.
+     *
+     * When {@link Detokeniser.do} encounters a token not handled by the built-in set, it invokes each
+     * registered sync callback in registration order. The first to return a non-`undefined` string wins.
+     * Return `undefined` to pass to the next callback. If all callbacks return `undefined`, an error is thrown.
+     *
+     * @param callback - `(delimiter: string, token: string) => string | undefined`
+     *   - `delimiter` — current delimiter character (default `|`)
+     *   - `token` — full token body without `[[` / `]]`, e.g. `"mytype|arg1|arg2"`
+     *
+     * @example
+     * // Handle [[env|VAR_NAME]] tokens
+     * Detokeniser.addCallbackSync((delimiter, token) => {
+     *   const [type, name] = token.split(delimiter);
+     *   if (type.toLowerCase() !== 'env') return undefined;
+     *   return process.env[name] ?? '';
+     * });
+     * Detokeniser.do('Path: [[env|HOME]]'); // → 'Path: /home/user'
+     *
+     * @example
+     * // Multiple callbacks — each handles one type, passes on the rest
+     * Detokeniser.addCallbackSync((delimiter, token) => {
+     *   const [type, value] = token.split(delimiter);
+     *   if (type === 'upper') return value.toUpperCase();
+     *   return undefined;
+     * });
+     * Detokeniser.addCallbackSync((delimiter, token) => {
+     *   const [type, value] = token.split(delimiter);
+     *   if (type === 'lower') return value.toLowerCase();
+     *   return undefined;
+     * });
+     * Detokeniser.do('[[upper|hello]] [[lower|WORLD]]'); // → 'HELLO world'
+     *
+     * @see {@link Detokeniser.resetSyncCallbacks} to remove all sync callbacks
+     * @see {@link Detokeniser.addCallbackAsync} for async token handlers
+     */
+    static addCallbackSync(callback: Detokeniser.Callback_Sync): void;
+    /**
+     * Registers an asynchronous custom token handler.
+     *
+     * Works identically to {@link Detokeniser.addCallbackSync} but is invoked by {@link Detokeniser.doAsync}.
+     * Async callbacks are tried in registration order; the first to return a non-`undefined` value wins.
+     * Return `undefined` to pass to the next callback.
+     *
+     * @param asyncCallback - `(delimiter: string, token: string) => Promise<string | undefined>`
+     *   - `delimiter` — current delimiter character (default `|`)
+     *   - `token` — full token body without `[[` / `]]`, e.g. `"mytype|arg1|arg2"`
+     *
+     * @example
+     * // Handle [[db|table|column|whereClause]] tokens
+     * Detokeniser.addCallbackAsync(async (delimiter, token) => {
+     *   const [type, table, column, where] = token.split(delimiter);
+     *   if (type.toLowerCase() !== 'db') return undefined;
+     *   const row = await db.query(`SELECT ${column} FROM ${table} WHERE ${where} LIMIT 1`);
+     *   return String(row[column]);
+     * });
+     * const result = await Detokeniser.doAsync('ID: [[db|users|id|active=1]]');
+     *
+     * @example
+     * // Combine with nested tokens — inner tokens resolve before the callback is called
+     * Detokeniser.addCallbackAsync(async (delimiter, token) => {
+     *   const [type, key] = token.split(delimiter);
+     *   if (type !== 'cache') return undefined;
+     *   return await redis.get(key);
+     * });
+     * // [[random|digits|8]] resolves first, then [[cache|...]] receives the result
+     * await Detokeniser.doAsync('Val: [[cache|prefix-[[random|digits|8]]]]');
+     *
+     * @see {@link Detokeniser.resetAsyncCallbacks} to remove all async callbacks
+     * @see {@link Detokeniser.addCallbackSync} for synchronous token handlers
+     */
+    static addCallbackAsync(asyncCallback: Detokeniser.Callback_Async): void;
+    /**
+     * Removes all registered sync callbacks. Built-in token handlers are unaffected.
+     * Use between tests or scenarios to ensure callback isolation.
+     * @see {@link Detokeniser.reset} to also clear async callbacks and restore all defaults
+     */
+    static resetSyncCallbacks(): void;
+    /**
+     * Removes all registered async callbacks. Built-in token handlers are unaffected.
+     * Use between tests or scenarios to ensure callback isolation.
+     * @see {@link Detokeniser.reset} to also clear sync callbacks and restore all defaults
+     */
+    static resetAsyncCallbacks(): void;
+    /**
+     * Synchronously resolves all tokens in the given string and returns the result.
+     *
+     * Tokens are resolved innermost-first. Registered sync callbacks are invoked for token types not
+     * handled by the built-in set. Use {@link Detokeniser.doAsync} if you need async callbacks or any
+     * of the async-only date expressions (`addWorkingDays`, `followingWorkingDay`, `nextPublicHoliday`).
+     *
+     * @param tokenisedString - String potentially containing `[[...]]` tokens
+     * @param options - Optional processing options
+     * @returns The input string with all tokens replaced by their resolved values
+     * @throws If any token is malformed, unsupported, or a callback throws
+     *
+     * @example
+     * Detokeniser.do('Ref-[[random|digits|6]]');                        // → e.g. 'Ref-482910'
+     * Detokeniser.do('Expires [[date|addDays(30)|dd/MM/yyyy]]');        // → e.g. 'Expires 01/05/2026'
+     * Detokeniser.do('[[random|uppercaseletters|3]]-[[random|digits|4]]'); // → e.g. 'XKP-7391'
+     *
+     * @example
+     * // Nested tokens — innermost resolved first
+     * Detokeniser.do('[[date|addDays([[random|digits|1]])|dd-MM-yyyy]]');
+     *
+     * @example
+     * // Context parameters for [[setting|...]] tokens
+     * Detokeniser.do('Hello [[setting|profileParameterName: "username"]]', {
+     *   contextParameters: { username: 'Alice' }
+     * }); // → 'Hello Alice'
+     *
+     * @example
+     * // Escaping — produce literal [[ / ]] in output
+     * Detokeniser.do('Press /[[Enter/]] to continue'); // → 'Press [[Enter]] to continue'
+     */
+    static do(tokenisedString: string, options?: Detokeniser.DoOptions): string;
+    /**
+     * Asynchronously resolves all tokens in the given string and returns a Promise of the result.
+     *
+     * Functionally equivalent to {@link Detokeniser.do} but additionally supports:
+     * - Async callbacks registered via {@link Detokeniser.addCallbackAsync}
+     * - Async-only date expressions: `addWorkingDays`, `followingWorkingDay`, `nextPublicHoliday`
+     *
+     * Note: sync callbacks registered via {@link Detokeniser.addCallbackSync} are **not** invoked
+     * during async processing — re-register them with {@link Detokeniser.addCallbackAsync} if needed.
+     *
+     * @param tokenisedString - String potentially containing `[[...]]` tokens
+     * @returns Promise resolving to the input string with all tokens replaced
+     * @throws If any token is malformed, unsupported, or a callback throws
+     *
+     * @example
+     * // Async-only date expressions require doAsync and a region qualifier
+     * await Detokeniser.doAsync('[[date(us-east)|addWorkingDays(5)|dd-MM-yyyy]]');
+     * await Detokeniser.doAsync('[[date(eu-london)|nextPublicHoliday([[date|today|epoch]],90)|dd-MM-yyyy]]');
+     *
+     * @example
+     * // Async callback for database-driven tokens
+     * Detokeniser.addCallbackAsync(async (delim, token) => {
+     *   const [type, key] = token.split(delim);
+     *   if (type !== 'db') return undefined;
+     *   return await fetchFromDatabase(key);
+     * });
+     * await Detokeniser.doAsync('User: [[db|users.name.first]]');
+     */
+    static doAsync(tokenisedString: string): Promise<string>;
+    private static doDeEscapesIfRequired;
+    private static doPreamble;
+    private static doTokenMain;
+    private static doToken;
+    private static asyncDoToken;
+    private static doSettingToken;
+    /**
+     * Base64-encodes or decodes a string.
+     *
+     * This is the underlying handler for `[[base64|encode|...]]` and `[[base64|decode|...]]` tokens
+     * but is also exposed for direct use.
+     *
+     * @param original - The string to encode or decode
+     * @param direction - `"encode"` to base64-encode; `"decode"` to base64-decode
+     * @returns The encoded or decoded string
+     * @throws If the conversion fails (e.g. invalid base64 input for decode)
+     *
+     * @example
+     * Detokeniser.doBase64('Hello World', 'encode');      // → 'SGVsbG8gV29ybGQ='
+     * Detokeniser.doBase64('SGVsbG8gV29ybGQ=', 'decode'); // → 'Hello World'
+     */
+    static doBase64(original: string, direction: "encode" | "decode"): string;
+    private static doJWTToken;
+    private static doMockRequests;
+    /**
+     * Extracts the content inside the first set of parentheses in `input`, respecting the escape char.
+     * An escaped `)` (i.e. `/)`) is treated as a literal `)` and does not end the content.
+     * @example parseParenContent("from(abc/))") → "abc)"
+     * @example parseParenContent("from(xyz/[[)") → "xyz[["  (with default escape char `/`)
+     */
+    private static parseParenContent;
+    private static doRandomToken;
+    private static doDateTokenPreamble;
+    private static doDateTokenPostamble;
+    private static doDateTokenNonAsyncVerbs;
+    private static doDateToken;
+    private static asyncDoDateToken;
+    private static getNextPublicHoliday;
+    private static getFollowingDay;
+    private static getParsedDateOffset;
+    private static doRandomDate;
+    private static getOffset;
+    private static numberOfDays;
+    private static doRandomFloat;
+}
+/**
+ * Signature for an asynchronous custom token handler registered via {@link Detokeniser.addCallbackAsync}.
+ *
+ * @param delimiter - Current delimiter character (default `|`)
+ * @param token - Full token body without `[[` / `]]` endstops, e.g. `"mytype|arg1|arg2"`
+ * @returns Promise resolving to the replacement string, or `undefined` to pass to the next handler
+ */
+export interface Detokeniser_Callback_Async {
+    (delimiter: string, token: string): Promise<string | undefined>;
+}
+/**
+ * Signature for a synchronous custom token handler registered via {@link Detokeniser.addCallbackSync}.
+ *
+ * @param delimiter - Current delimiter character (default `|`)
+ * @param token - Full token body without `[[` / `]]` endstops, e.g. `"mytype|arg1|arg2"`
+ * @returns The replacement string, or `undefined` to pass to the next handler
+ */
+export interface Detokeniser_Callback_Sync {
+    (delimiter: string, token: string): string | undefined;
+}
+/**
+ * Options passed to {@link Detokeniser.do} and {@link Detokeniser.doAsync}.
+ */
+export interface Detokeniser_DoOptions {
+    /**
+     * Key/value pairs made available to `[[setting|profileParameterName: "key"]]` tokens.
+     * Typically populated from Cucumber world parameters or a test profile configuration object.
+     * @example { username: 'alice', environment: 'staging' }
+     */
+    contextParameters?: Record<string, unknown>;
+}
+export declare namespace Detokeniser {
+    type Callback_Async = Detokeniser_Callback_Async;
+    type Callback_Sync = Detokeniser_Callback_Sync;
+    type DoOptions = Detokeniser_DoOptions;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,18 @@
+import { Logger } from "./logger/logger";
+export { Logger, Logger as Log };
+export declare const LogLevels: {
+    readonly Maximum: number;
+    readonly Verbose: number;
+    readonly FrameworkDebug: 6;
+    readonly FrameworkInformation: 5;
+    readonly TestDebug: 4;
+    readonly TestInformation: 3;
+    readonly Warning: 2;
+    readonly Error: 1;
+    readonly NoOutput: 0;
+};
+export type { LogLevel, VideoOptions, WriteLineOptions, LogOutputCallbackSignature, } from "./logger/types";
+export { JsonUtils } from "./jsonUtils/jsonUtils";
+export { StringUtils } from "./stringUtils/stringUtils";
+export { Utils, ExistingFileWriteActions } from "./utils/utils";
+export type { AssertTypeMap, ActionAndParams } from "./utils/utils";

package/dist/types/jsonUtils/jsonUtils.d.ts

@@ -0,0 +1,196 @@
+/**
+ * JSON utility methods for querying, manipulating, parsing and validating JSON objects.
+ * All methods are static — no instantiation required.
+ */
+export declare class JsonUtils {
+    /**
+     * Returns the JSONPath path to the parent of the node addressed by the given path.
+     *
+     * @param pathToChild - A valid JSONPath path to a JSON node.
+     * @returns The JSONPath path to the parent of the given node.
+     * @throws {Error} If the node has no parent (i.e. it is a top-level node).
+     *
+     * @example
+     * JsonUtils.getParentPath("$.a.b.c"); // returns "$.a.b"
+     */
+    static getParentPath(pathToChild: string): string;
+    /**
+     * Returns a deep copy of the given object with the property identified by the
+     * given JSONPath renamed. The original object is not mutated.
+     *
+     * The JSONPath must match exactly one property — zero or multiple matches will throw.
+     *
+     * @param jsonObject - The source object containing the property to rename.
+     * @param pathToPropertyToRename - A valid JSONPath identifying the property to rename.
+     * @param newName - The new name for the property.
+     * @returns A new deep-copied object with the property renamed.
+     * @throws {Error} If the JSONPath matches zero or more than one property.
+     *
+     * @example
+     * const result = JsonUtils.withRenamedProperty({ a: { b: 1 } }, "$.a.b", "c");
+     * // result => { a: { c: 1 } }
+     */
+    static withRenamedProperty(jsonObject: object, pathToPropertyToRename: string, newName: string): object;
+    /**
+     * Shallow-merges the given object into the property identified by the given JSONPath
+     * within the source object. Properties in `objectToMerge` overwrite same-named
+     * properties in the target. The JSONPath must match exactly one property.
+     *
+     * Use `"$"` as the path to merge directly into the root object.
+     *
+     * @param jsonObject - The source object containing the property to merge into.
+     * @param pathToPropertyToMergeInto - A valid JSONPath identifying the target property.
+     * @param objectToMerge - The object whose properties will be merged into the target.
+     * @returns The updated source object with the merge applied.
+     * @throws {Error} If the JSONPath matches zero or more than one property.
+     *
+     * @example
+     * const result = JsonUtils.mergeObjectIntoProperty({ a: { x: 1 } }, "$.a", { y: 2 });
+     * // result => { a: { x: 1, y: 2 } }
+     */
+    static mergeObjectIntoProperty(jsonObject: object, pathToPropertyToMergeInto: string, objectToMerge: object): object;
+    /**
+     * Reads a file from disk and parses its contents as JSON, returning the result as an object.
+     * Returns an empty object `{}` if the file contents are not valid JSON.
+     *
+     * @param pathAndFilename - Path to the JSON file to read.
+     * @param options - Optional settings:
+     *   - `encoding` — File encoding to use when reading (default: `"utf-8"`).
+     *   - `detokeniseFileContents` — When `true`, passes file contents through the
+     *     detokeniser before parsing (default: `false`).
+     * @returns The parsed JSON as an object, or `{}` if the file contains invalid JSON.
+     * @throws {Error} If the file cannot be read.
+     */
+    static getObjectFromFile(pathAndFilename: string, options?: {
+        encoding?: BufferEncoding;
+        detokeniseFileContents?: boolean;
+    }): object;
+    /**
+     * Parses a JSON (or optionally JSON5) string into an object.
+     * If `item` is `null`, an empty object `{}` is returned.
+     *
+     * @param item - The JSON string to parse, or `null` (returns `{}`).
+     * @param useJson5 - When `true`, parses using JSON5 rules, allowing comments,
+     *   trailing commas, unquoted keys, etc. Defaults to `false` (strict JSON).
+     * @returns The parsed object.
+     * @throws {Error} If `item` is not a string or null, or if parsing fails.
+     *
+     * @example
+     * JsonUtils.parse('{"a":1}');           // => { a: 1 }
+     * JsonUtils.parse(null);                // => {}
+     * JsonUtils.parse("{a:1}", true);       // => { a: 1 }  (JSON5)
+     */
+    static parse(item: string | null, useJson5?: boolean): any;
+    /**
+     * Checks whether the given item is valid JSON.
+     *
+     * Returns `true` if:
+     * - `item` is a string that parses as a JSON object (not a primitive), or
+     * - `item` is an object that can be `JSON.stringify`-ed and parsed back as an object.
+     *
+     * Returns `false` for `undefined`, unparseable strings, or values that parse
+     * to a primitive (e.g. `"true"`, `"42"`).
+     *
+     * @param item - The value to check.
+     * @param allowJson5 - When `true`, accepts JSON5 syntax (comments, trailing commas,
+     *   unquoted keys, etc.). Defaults to `false` (strict JSON only).
+     * @returns `true` if the item represents a valid JSON object, `false` otherwise.
+     *
+     * @example
+     * JsonUtils.isJson('{"a":1}');        // true
+     * JsonUtils.isJson('42');             // false  (primitive)
+     * JsonUtils.isJson(undefined);        // false
+     * JsonUtils.isJson("{a:1}", true);    // true   (JSON5)
+     */
+    static isJson(item: string | object | undefined | null, allowJson5?: boolean): boolean;
+    /**
+     * Returns all properties within a JSON object that match the given JSONPath expression.
+     * Each result includes the matched value, its JSON Pointer path, and its parent object.
+     *
+     * @param jsonObject - The object (or JSON string) to query.
+     * @param pathToJSONProperties - A valid JSONPath expression identifying the properties to retrieve.
+     * @returns An array of matches, each with `value`, `pointer` (JSON Pointer string), and `parent`.
+     *   Returns an empty array if no properties match.
+     * @throws {Error} If `jsonObject` is not a valid JSON object, or if the JSONPath query fails.
+     *
+     * @see https://jsonpath-plus.github.io/JSONPath/docs/ts/
+     *
+     * @example
+     * JsonUtils.getPropertiesMatchingPath({ a: { b: 1 } }, "$.a.b");
+     * // => [{ value: 1, pointer: "/a/b", parent: { b: 1 } }]
+     */
+    static getPropertiesMatchingPath(jsonObject: object | string, pathToJSONProperties: string): Array<{
+        value: unknown;
+        pointer: string;
+        parent: object;
+    }>;
+    /**
+     * Sets, adds, or deletes a property within a JSON object identified by a JSONPath expression.
+     * Operates on a deep copy of `currentObject` — the original is not mutated.
+     *
+     * - If the property **exists**, its value is updated.
+     * - If the property **does not exist**, it is added with the given value.
+     * - To **delete** a property, pass the string `"_undefined"` as the value.
+     *   Note: deleting a property that does not exist will throw.
+     *
+     * The JSONPath must match zero or one property — multiple matches will throw.
+     *
+     * When `Log.loggingLevel` is below `LogLevels.TestInformation`, a detailed error
+     * including the full object and value is written to the log before throwing.
+     *
+     * @param currentObject - The source object to update (not mutated).
+     * @param pathString - A valid JSONPath expression identifying the property to set/add/delete.
+     * @param value - The value to set. Pass the string `"_undefined"` to delete the property.
+     * @returns A new deep-copied object with the change applied.
+     * @throws {Error} If `currentObject` is not a valid JSON object, if the JSONPath matches
+     *   more than one property, if deletion is attempted on a non-existent property, or if
+     *   the value could not be verified after being set.
+     *
+     * @example
+     * JsonUtils.updateJSONObject({ a: 1 }, "$.a", 2);           // => { a: 2 }
+     * JsonUtils.updateJSONObject({ a: 1 }, "$.b", "hello");     // => { a: 1, b: "hello" }
+     * JsonUtils.updateJSONObject({ a: 1 }, "$.a", "_undefined"); // => {}
+     */
+    static updateJSONObject(currentObject: object, pathString: string, value: string | object | boolean | number | null): object;
+    /**
+     * Returns the number of properties within a JSON object that match the given JSONPath expression.
+     *
+     * @param jsonObject - The object to query.
+     * @param pathString - A valid JSONPath expression identifying the properties to count.
+     * @returns The number of matching properties, or `0` if none match.
+     * @throws {Error} If `jsonObject` is not a valid JSON object.
+     *
+     * @example
+     * JsonUtils.getMatchingJSONPropertyCount({ a: 1, b: 2 }, "$.a"); // => 1
+     * JsonUtils.getMatchingJSONPropertyCount({ a: 1, b: 2 }, "$.*"); // => 2
+     */
+    static getMatchingJSONPropertyCount(jsonObject: object, pathString: string): number;
+    /**
+     * Removes all properties matching the given key names from a JSON object, including
+     * those nested within child objects or arrays. Operates directly on the passed object
+     * (mutates in place).
+     *
+     * @param jsonObject - The object (or array of objects) to remove properties from.
+     * @param removeKeys - One or more property names to remove at any depth.
+     * @param throwError - When `true`, any error encountered during removal is re-thrown.
+     *   When `false` (default), errors are logged and silently swallowed.
+     *
+     * @example
+     * const obj = { a: 1, b: { a: 2, c: 3 } };
+     * JsonUtils.removeJsonPropertyByKey(obj, ["a"]);
+     * // obj => { b: { c: 3 } }
+     */
+    static removeJsonPropertyByKey(jsonObject: object | Array<object>, removeKeys: string[], throwError?: boolean): void;
+    /**
+     * Escapes all RegExp special characters in a string so it can be safely used
+     * as a literal pattern in a `RegExp` constructor.
+     *
+     * @param toBeEscaped - The string to escape.
+     * @returns The input string with all RegExp special characters escaped.
+     *
+     * @example
+     * JsonUtils.escapeRegExp("a.b+c"); // => "a\\.b\\+c"
+     * new RegExp(JsonUtils.escapeRegExp("1+1=2")); // matches literal "1+1=2"
+     */
+    static escapeRegExp(toBeEscaped: string): string;
+}