/**
 * Error thrown when an invalid ValueKeyList is provided.
 */
declare class InvalidValueKeyListError extends Error {
    readonly invalidData?: unknown | undefined;
    constructor(message: string, invalidData?: unknown | undefined);
}
/**
 * Error thrown when an invalid JSON object is provided to fromJSON.
 */
declare class InvalidJsonObjectError extends Error {
    readonly invalidData?: unknown | undefined;
    constructor(message: string, invalidData?: unknown | undefined);
}
/**
 * Represents a single key-value pair item.
 *
 * @template V - The type of the value (defaults to string)
 * @template K - The type of the key (defaults to string)
 *
 * @example
 * ```typescript
 * const item: ValueKeyItem<number, string> = { key: 'age', value: 25 };
 * ```
 */
interface ValueKeyItem<V = string, K = string> {
    /** The value associated with the key */
    value: V;
    /** The key identifier */
    key: K;
}
/**
 * Represents a JSON object with typed keys and values.
 *
 * @template V - The type of the values (defaults to string)
 * @template K - The type of the keys, must extend string (defaults to string)
 *
 * @example
 * ```typescript
 * const json: JsonObject<number> = { foo: 1, bar: 2 };
 * ```
 */
type JsonObject<V = string, K extends string = string> = Record<K, V>;
/**
 * A utility class for converting between JSON objects and key-value pair arrays.
 *
 * This class facilitates bidirectional conversion between:
 * - JSON objects: `{ foo: 'bar', taz: 'qux' }`
 * - Key-value arrays: `[{ key: 'foo', value: 'bar' }, { key: 'taz', value: 'qux' }]`
 *
 * @template V - The type of the values (defaults to string)
 * @template K - The type of the keys, must extend string (defaults to string)
 *
 * @example
 * ```typescript
 * // Convert JSON to key-value list
 * const json = { foo: 'bar', taz: 'qux' };
 * const list = ValueKeyList.fromJSON(json);
 * // Result: [{ key: 'foo', value: 'bar' }, { key: 'taz', value: 'qux' }]
 *
 * // Convert key-value list to JSON
 * const items = [{ key: 'foo', value: 'bar' }, { key: 'taz', value: 'qux' }];
 * const valueKeyList = new ValueKeyList(items);
 * const json = valueKeyList.toJSON();
 * // Result: { foo: 'bar', taz: 'qux' }
 * ```
 */
declare class ValueKeyList<V = string, K extends string = string> {
    private readonly items;
    /**
     * Creates a new ValueKeyList instance from an array of key-value items.
     *
     * @param items - Array of key-value pair items
     * @throws {InvalidValueKeyListError} Throws when the items array is invalid
     *
     * @example
     * ```typescript
     * const list = new ValueKeyList([
     *   { key: 'name', value: 'John' },
     *   { key: 'age', value: 30 }
     * ]);
     * ```
     */
    constructor(items: ValueKeyItem<V, K>[]);
    /**
     * Validates if the provided data is a valid array of key-value items.
     *
     * Checks that:
     * - The input is an array
     * - Each item is an object with 'key' and 'value' properties
     * - Both 'key' and 'value' are defined (not undefined or null)
     *
     * @param items - The data to validate
     * @returns `true` if valid, `false` otherwise
     *
     * @example
     * ```typescript
     * ValueKeyList.validate([{ key: 'a', value: 1 }]); // true
     * ValueKeyList.validate([{ key: 'a' }]);           // false (missing 'value')
     * ValueKeyList.validate([{ key: undefined, value: 1 }]); // false (key is undefined)
     * ValueKeyList.validate(null);                     // false
     * ```
     */
    static validate<V = string, K extends string = string>(items: unknown): items is ValueKeyItem<V, K>[];
    /**
     * Creates a ValueKeyList instance from a JSON object.
     *
     * Converts an object like `{ foo: 'bar' }` into an array of key-value pairs
     * like `[{ key: 'foo', value: 'bar' }]`.
     *
     * **Type Safety:** The generic types `V` and `K` are not validated at runtime.
     * It is the caller's responsibility to ensure the JSON object values match the
     * specified type `V`. Mismatched types will not be caught by this method and may
     * lead to runtime errors elsewhere in your code.
     *
     * **Note on ordering:** The order of items in the resulting array follows the
     * enumeration order of `Object.entries()`, which is insertion order for string
     * keys in modern JavaScript engines (ES2015+). While not formally guaranteed by
     * the ECMAScript specification for all cases, this behavior is consistent across
     * all modern environments. If you need guaranteed ordering, consider using the
     * constructor directly with a pre-ordered array.
     *
     * @template V - The type of the values (defaults to string)
     * @template K - The type of the keys, must extend string (defaults to string)
     * @param json - The JSON object to convert
     * @returns A new ValueKeyList instance
     * @throws {InvalidJsonObjectError} When the input is null, an array, or not an object
     * @throws {InvalidValueKeyListError} When the resulting items fail validation (should not occur with valid objects)
     *
     * @example
     * ```typescript
     * const json = { name: 'Alice', role: 'Admin' };
     * const list = ValueKeyList.fromJSON(json);
     * // list contains [{ key: 'name', value: 'Alice' }, { key: 'role', value: 'Admin' }]
     *
     * // With typed values - ensure values match the type!
     * const numbers = { x: 10, y: 20 };
     * const numList = ValueKeyList.fromJSON<number>(numbers); // ✅ Correct
     *
     * // ⚠️ Type mismatch - TypeScript won't catch this, but will cause issues:
     * const invalid = { x: 'string' };
     * const badList = ValueKeyList.fromJSON<number>(invalid); // Compiles, but wrong!
     *
     * // Error handling
     * try {
     *   ValueKeyList.fromJSON(null);
     * } catch (error) {
     *   if (error instanceof InvalidJsonObjectError) {
     *     console.error('Invalid input:', error.message);
     *   }
     * }
     * ```
     */
    static fromJSON<V = string, K extends string = string>(json: JsonObject<V, K>): ValueKeyList<V, K>;
    /**
     * Converts the key-value list back to a JSON object.
     *
     * Transforms an array like `[{ key: 'foo', value: 'bar' }]` into an object
     * like `{ foo: 'bar' }`.
     *
     * **Note on duplicate keys:** If the items array contains duplicate keys,
     * later entries will overwrite earlier ones in the resulting object.
     *
     * @returns A JSON object representation of the key-value pairs
     *
     * @example
     * ```typescript
     * const list = new ValueKeyList([
     *   { key: 'x', value: 10 },
     *   { key: 'y', value: 20 }
     * ]);
     * const json = list.toJSON(); // { x: 10, y: 20 }
     *
     * // Duplicate keys: last value wins
     * const dupes = new ValueKeyList([
     *   { key: 'x', value: 1 },
     *   { key: 'x', value: 2 }
     * ]);
     * dupes.toJSON(); // { x: 2 }
     * ```
     */
    toJSON(): JsonObject<V, K>;
    /**
     * Returns a copy of the internal key-value items array.
     *
     * Creates a shallow copy to preserve immutability.
     *
     * @returns A new array containing all key-value items
     *
     * @example
     * ```typescript
     * const list = new ValueKeyList([{ key: 'a', value: 1 }]);
     * const array = list.toArray();
     * array.push({ key: 'b', value: 2 }); // Doesn't affect the original list
     * ```
     */
    toArray(): ValueKeyItem<V, K>[];
    /**
     * Returns a JSON string representation of the key-value pairs as an object.
     *
     * Equivalent to `JSON.stringify(this.toJSON())`.
     *
     * @returns A JSON-stringified version of the object representation
     *
     * @example
     * ```typescript
     * const list = new ValueKeyList([{ key: 'a', value: 1 }]);
     * console.log(list.toString()); // '{"a":1}'
     * ```
     */
    toString(): string;
}

export { InvalidJsonObjectError, InvalidValueKeyListError, type JsonObject, type ValueKeyItem, ValueKeyList };