@winglet/json/dist/JSONPointer/utils/patch/applyPatch/applySinglePatch.d.ts

TypeScript library for safe and efficient JSON data manipulation with RFC 6901 (JSON Pointer) and RFC 6902 (JSON Patch) compliance, featuring prototype pollution protection and immutable operations

import type { JsonRoot } from '../../../../type';
import type { Patch } from '../type';
/**
 * Applies a single JSON Patch operation to a source object or array.
 *
 * This function is the core implementation for applying individual JSON Patch operations.
 * It handles path traversal, validation, and delegates the actual operation execution
 * to specialized handlers based on the target type (object, array, or root).
 *
 * The function performs the following key operations:
 * - Parses and validates JSON Pointer paths
 * - Handles path escaping/unescaping according to RFC 6901
 * - Provides security protection against prototype pollution
 * - Validates intermediate path segments during traversal
 * - Delegates final operation to appropriate type-specific handlers
 * - Provides detailed error information for debugging
 *
 * Path traversal follows JSON Pointer specification:
 * - Paths starting with "/" represent object/array properties
 * - Empty path ("" or "#") represents the root document
 * - Special characters (~0, ~1) are unescaped to (~ and /)
 * - Array indices are validated and converted appropriately
 *
 * @param source - The source object or array to apply the patch to
 * @param patch - A single JSON Patch operation containing op, path, and optional value
 * @param patchIndex - The index of this patch in the original patches array (for error reporting)
 * @param strict - Whether to enforce strict validation rules
 * @param protectPrototype - Whether to prevent prototype pollution attempts
 *
 * @see https://datatracker.ietf.org/doc/html/rfc6901 - JSON Pointer specification
 * @see https://datatracker.ietf.org/doc/html/rfc6902 - JSON Patch specification
 *
 * @returns The modified source object/array with the patch operation applied
 *
 * @throws {JsonPatchError} When the patch operation fails due to:
 *         - SECURITY_PROTOTYPE_MODIFICATION_FORBIDDEN: Attempt to modify prototype properties
 *         - PATCH_TARGET_NOT_OBJECT: Target of operation is not an object/array when required
 *         - PATCH_PATH_INVALID_INTERMEDIATE: Invalid intermediate value during path traversal
 *         - PATCH_PATH_PROCESSING_ERROR: Unexpected error during path processing
 *         - Additional operation-specific errors from specialized handlers
 *
 * @example
 * ```typescript
 * const source = { user: { name: "John", age: 30 } };
 * const patch = { op: "replace", path: "/user/age", value: 31 };
 *
 * const result = applySinglePatch(source, patch, 0, false, true);
 * // Returns: { user: { name: "John", age: 31 } }
 * ```
 *
 * @example
 * ```typescript
 * const sourceArray = [1, 2, 3];
 * const patch = { op: "add", path: "/1", value: 5 };
 *
 * const result = applySinglePatch(sourceArray, patch, 0, false, true);
 * // Returns: [1, 5, 2, 3]
 * ```
 *
 * @example
 * ```typescript
 * // Root patch application
 * const source = { old: "data" };
 * const patch = { op: "replace", path: "", value: { new: "data" } };
 *
 * const result = applySinglePatch(source, patch, 0, false, true);
 * // Returns: { new: "data" }
 * ```
 *
 * @example
 * ```typescript
 * // Security protection - this will throw an error
 * const source = {};
 * const maliciousPatch = { op: "add", path: "/__proto__/isAdmin", value: true };
 *
 * // Throws JsonPatchError with SECURITY_PROTOTYPE_MODIFICATION_FORBIDDEN
 * applySinglePatch(source, maliciousPatch, 0, false, true);
 * ```
 */
export declare const applySinglePatch: (source: JsonRoot, patch: Patch, patchIndex: number, strict: boolean, protectPrototype: boolean) => any;