@winglet/json
Version:
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
130 lines (129 loc) • 4.82 kB
TypeScript
/**
* Escapes a complete JSON Pointer path by escaping each segment individually.
*
* This function takes a full JSON Pointer path and ensures that all segments
* within the path are properly escaped according to RFC 6901 specifications.
* It splits the path by the separator character (`/`), escapes each segment
* using the `escapeSegment` function, and then rejoins them to form a valid
* escaped JSON Pointer.
*
* **Important**: Only special characters **within segments** are escaped.
* The path separator (`/`) characters are preserved as-is since they define
* the path structure.
*
* **Key Features:**
* - **Path-level escaping**: Handles complete JSON Pointer paths with multiple segments
* - **Segment isolation**: Each path segment is escaped independently
* - **RFC 6901 compliance**: Follows official JSON Pointer specification
* - **Performance optimized**: Leverages efficient segment-level escaping
* - **Structure preservation**: Path separators remain unchanged
*
* **Use Cases:**
* - Converting user-provided paths to safe JSON Pointer expressions
* - Preparing dynamic paths for JSON Pointer operations
* - Sanitizing paths that may contain special characters in segment names
* - Building JSON Pointers programmatically from potentially unsafe input
*
* @param path - The JSON Pointer path to escape. Should be a valid path structure
* with segments separated by `/` characters. Can start with or without
* a leading `/`. Empty segments and segments with special characters
* are handled correctly.
*
* @returns The fully escaped JSON Pointer path where all segments have been
* individually escaped. The path structure (separator characters) is
* preserved while segment content is made safe for JSON Pointer usage.
*
* @see {@link escapeSegment} for individual segment escaping logic
* @see {@link https://datatracker.ietf.org/doc/html/rfc6901} RFC 6901 - JSON Pointer specification
*
* @example
* ```typescript
* // Basic segment escaping (only tildes in segments are escaped)
* escapePath('/users/john~doe/settings');
* // Returns: "/users/john~0doe/settings"
*
* escapePath('/config/app~name/value');
* // Returns: "/config/app~0name/value"
* ```
*
* @example
* ```typescript
* // Path separators are NOT escaped (they define structure)
* escapePath('/files/config/database');
* // Returns: "/files/config/database" (unchanged - no special chars in segments)
*
* escapePath('/docs/api/endpoints');
* // Returns: "/docs/api/endpoints" (unchanged - no special chars in segments)
* ```
*
* @example
* ```typescript
* // Multiple segments with special characters
* escapePath('/app~config/database~host/connection');
* // Returns: "/app~0config/database~0host/connection"
*
* escapePath('/users/~/profile/~/settings');
* // Returns: "/users/~0/profile/~0/settings"
* ```
*
* @example
* ```typescript
* // Edge cases and various path formats
* escapePath('');
* // Returns: "" (empty path)
*
* escapePath('/');
* // Returns: "/" (root with empty segment)
*
* escapePath('segment~name');
* // Returns: "segment~0name" (single segment, no leading slash)
*
* escapePath('/multiple~tildes~~~in~segment/normal');
* // Returns: "/multiple~0tildes~0~0~0in~0segment/normal"
* ```
*
* @example
* ```typescript
* // Real-world usage scenarios
* const userPath = '/users/jane.doe@company.com/preferences';
* const escapedUserPath = escapePath(userPath);
* // Result: "/users/jane.doe@company.com/preferences" (no escaping needed)
*
* const configPath = '/env/production/database~config/host';
* const escapedConfigPath = escapePath(configPath);
* // Result: "/env/production/database~0config/host"
*
* const backupPath = '/uploads/backup~2023/archive';
* const escapedBackupPath = escapePath(backupPath);
* // Result: "/uploads/backup~02023/archive"
* ```
*
* @example
* ```typescript
* // Dynamic path building with user input
* const buildUserSettingPath = (userId: string, setting: string) => {
* const rawPath = `/users/${userId}/settings/${setting}`;
* return escapePath(rawPath);
* };
*
* buildUserSettingPath('user~123', 'theme~dark');
* // Returns: "/users/user~0123/settings/theme~0dark"
*
* buildUserSettingPath('normaluser', 'normalsetting');
* // Returns: "/users/normaluser/settings/normalsetting"
* ```
*
* @example
* ```typescript
* // RFC 6901 compliance examples
* escapePath('/foo/bar');
* // Returns: "/foo/bar" (no special characters in segments)
*
* escapePath('/a~b');
* // Returns: "/a~0b" (tilde in segment content)
*
* escapePath('/special!@#$%^&*()/chars');
* // Returns: "/special!@#$%^&*()/chars" (only tildes need escaping)
* ```
*/
export declare const escapePath: (path: string) => string;