@croct/json-pointer/relativePointer.d.ts

A RFC6901 compliant type-safe JSON pointer library to handle arbitrary structured data.

import { JsonConvertible } from '@croct/json';
import { JsonPointer, JsonPointerSegments, JsonPointerSegment, JsonPointerLike, ReferencedValue, RootValue } from './pointer';
/**
 * A value that can be converted to a relative JSON pointer.
 */
export type JsonRelativePointerLike = JsonRelativePointer | number | string | JsonPointerSegments;
/**
 * A relative JSON pointer.
 *
 * @see https://datatracker.ietf.org/doc/html/draft-bhutton-relative-json-pointer-00
 */
export declare class JsonRelativePointer implements JsonConvertible {
    /**
     * The list of segments that form the pointer.
     */
    private readonly segments;
    private constructor();
    /**
     * Creates a pointer from any valid pointer-like value.
     *
     * The return is as follows:
     *
     * - Pointers are returned as given
     * - Numbers are used as the number of parent levels
     * - Arrays are assumed to be unescaped segments
     * - Strings are delegated to `JsonRelativePointer.parse` and the result is returned
     *
     * @param path A pointer-like value.
     *
     * @returns The normalized pointer for the given value.
     *
     * @see JsonRelativePointer.parse
     */
    static from(path: JsonRelativePointerLike): JsonRelativePointer;
    /**
     * Creates a pointer from a list of unescaped segments.
     *
     * Numeric segments must be safe non-negative integers.
     *
     * @param {JsonPointerSegments} segments A list of unescaped segments.
     *
     * @returns {JsonPointer} The pointer to the value at the path specified by the segments.
     *
     * @throws {InvalidSyntaxError} If the segments are not valid.
     */
    private static fromSegments;
    /**
     * Parses a string into a pointer. The string is split on the dot character and
     * segments composed solely of numbers are parsed as integers.
     *
     * @param {string} path The string representation of a pointer.
     *
     * @returns {JsonPointer} The pointer to the value at the specified path.
     *
     * @throws {InvalidSyntaxError} If the path is not a valid JSON Pointer.
     */
    static parse(path: string): JsonRelativePointer;
    /**
     * Checks whether the pointer references a key (array index or object property).
     *
     * @returns {boolean} Whether the pointer references key.
     */
    isKeyPointer(): boolean;
    /**
     * Returns the number of levels up from the initial location.
     *
     * @returns {number} The number of levels up from the initial location.
     */
    getParentIndex(): number;
    /**
     * Returns the index offset of the pointer.
     *
     * @returns {number} A signed integer representing the offset of the pointer.
     */
    getParentIndexOffset(): number;
    /**
     * Returns a pointer to the parent of the current pointer.
     *
     * @returns {JsonPointer} The parent pointer.
     */
    getParent(): JsonRelativePointer;
    /**
     * Returns a pointer that represents the remainder of the path after the first segment.
     *
     * For example, if the current pointer is `0/foo/bar/baz` calling this method returns
     * a pointer to `/foo/bar/baz`.
     *
     * @returns {JsonPointer} A pointer to the remainder of the path.
     */
    getRemainderPointer(): JsonPointer;
    /**
     * Returns the segments of the pointer.
     *
     * @returns {JsonPointerSegments} The segments of the pointer.
     */
    getSegments(): JsonPointerSegments;
    /**
     * Joins this pointer with another one and returns the result.
     *
     * The segments of the second pointer are appended to the segments of the first.
     *
     * These are equivalent:
     *
     * ```js
     * JsonRelativePointer.from([1, 'bar']).join(JsonPointer.from(['baz']))
     * JsonRelativePointer.from(['1', 'bar', 'baz'])
     * ```
     *
     * @param {JsonPointer} other The pointer to append to this one.
     *
     * @returns {JsonPointer} A pointer with the segments of this and the other pointer joined.
     */
    joinedWith(other: JsonPointerLike): JsonRelativePointer;
    /**
     * Resolves relative pointer from an absolute pointer.
     *
     * @param {JsonPointerLike} pointer The base pointer.
     *
     * @returns {JsonPointer} The resolved pointer.
     *
     * @throws {JsonPointerError} If the pointer is out of bounds.
     * @throws {JsonPointerError} If the pointer is a key pointer.
     * @throws {JsonPointerError} If the pointer includes index offsets.
     */
    resolve(pointer: JsonPointerLike): JsonPointer;
    /**
     * Returns the value at the referenced location.
     *
     * @param {RootValue} root The value to read from.
     * @param {JsonPointer} pointer The base pointer to resolve the current pointer against.
     *
     * @returns {ReferencedValue|JsonPointerSegment} The value at the referenced location.
     *
     * @throws {InvalidReferenceError} If a numeric segment references a non-array value.
     * @throws {InvalidReferenceError} If a string segment references an array value.
     * @throws {InvalidReferenceError} If an array index is out of bounds.
     * @throws {InvalidReferenceError} If there is no value at any level of the pointer.
     * @throws {InvalidReferenceError} If the pointer references the key of the root value.
     */
    get<T extends RootValue>(root: T, pointer?: JsonPointer): ReferencedValue<T> | JsonPointerSegment;
    /**
     * Checks whether the value at the referenced location exists.
     *
     * This method gracefully handles missing values by returning `false`.
     *
     * @param {RootValue} root The value to check if the reference exists in.
     * @param {JsonPointer} pointer The base pointer to resolve the current pointer against.
     *
     * @returns {boolean} Returns `true` if the value exists, `false` otherwise.
     */
    has(root: RootValue, pointer?: JsonPointer): boolean;
    /**
     * Sets the value at the referenced location.
     *
     * @param {RootValue} root The value to write to.
     * @param {unknown} value The value to set at the referenced location.
     * @param {JsonPointer} pointer The base pointer to resolve the current pointer against.
     *
     * @throws {InvalidReferenceError} If the pointer references the root of the structure.
     * @throws {InvalidReferenceError} If a numeric segment references a non-array value.
     * @throws {InvalidReferenceError} If a string segment references an array value.
     * @throws {InvalidReferenceError} If there is no value at any level of the pointer.
     * @throws {InvalidReferenceError} If an array index is out of bounds.
     * @throws {InvalidReferenceError} If setting the value to an array would cause it to become
     * sparse.
     */
    set(root: RootValue, value: unknown, pointer?: JsonPointer): void;
    /**
     * Unsets the value at the referenced location and returns the unset value.
     *
     * If the given location does not exist, the method returns `undefined`, meaning the call
     * is a no-op. Pointers referencing array elements remove the element while keeping
     * the array dense.
     *
     * @param {RootValue} root The value to write to.
     * @param {JsonPointer} pointer The base pointer to resolve the current pointer against.
     *
     * @returns {JsonValue} The unset value, or `undefined` if the referenced location
     * does not exist.
     *
     * @throws {InvalidReferenceError} If the pointer references the root of the structure.
     */
    unset<T extends RootValue>(root: T, pointer?: JsonPointer): ReferencedValue<T> | undefined;
    /**
     * Returns the stack of references to the value at the referenced location.
     *
     * @param {RootValue} root The value to read from.
     * @param {JsonPointer} pointer The base pointer to resolve the current pointer against.
     *
     * @returns {Entry<ReferencedValue>[]} The list of entries in top-down order.
     *
     * @throws {InvalidReferenceError} If a numeric segment references a non-array value.
     * @throws {InvalidReferenceError} If a string segment references an array value.
     * @throws {InvalidReferenceError} If an array index is out of bounds.
     * @throws {InvalidReferenceError} If there is no value at any level of the pointer.
     */
    private getReferenceStack;
    /**
     * Checks whether the pointer is logically equivalent to another pointer.
     *
     * @param {any} other The pointer to check for equality.
     *
     * @returns {boolean} `true` if the pointers are logically equal, `false` otherwise.
     */
    equals(other: any): other is JsonRelativePointer;
    /**
     * Returns the string representation of the pointer.
     *
     * @returns {string} The string representation of the pointer
     */
    toJSON(): string;
    /**
     * Returns the string representation of the pointer.
     *
     * @returns {string} The string representation of the pointer
     */
    toString(): string;
}