JsonPointer

Parses a JSON Pointer URI fragment into decoded path tokens.

When to use

Use when you need to resolve a URI fragment against a JSON document.

Details

Percent-encoding is decoded before the pointer is split into tokens, then each token is decoded with unescapeToken. The empty string and # both represent the document root.

Gotchas

Returns undefined when the input is not a URI fragment, contains characters that require percent-encoding, or contains an invalid JSON Pointer escape sequence.

See

• formatUriFragment for the inverse operation

declare function parseUriFragment(fragment: string): readonly Array<string> | undefined

import { JsonPointer } from "effect"

JsonPointer.parseUriFragment("#/users/a~1b") // => ["users", "a/b"]
JsonPointer.parseUriFragment("#/caf%C3%A9") // => ["café"]
JsonPointer.parseUriFragment("#/%") // => undefined
JsonPointer.parseUriFragment("#/a#b") // => undefined

Decodes a JSON Pointer reference token according to RFC 6901 escaping rules.

When to use

Use when you need to decode a single escaped JSON Pointer path segment.

Details

• Returns a new unescaped string
• Replaces ~1 with / (forward slash) and ~0 with ~ (tilde)
• Returns the input unchanged if it contains no escaped sequences
• Empty strings are valid and returned unchanged

Gotchas

The replacement order matters: ~1 is replaced before ~0 to prevent incorrect decoding.

See

• escapeToken The inverse operation for encoding tokens

declare function unescapeToken(token: string): string

import { JsonPointer } from "effect"

JsonPointer.unescapeToken("a~1b") // => "a/b"
JsonPointer.unescapeToken("c~0d") // => "c~d"
JsonPointer.unescapeToken("path~1to~0key") // => "path/to~key"

Escapes a JSON Pointer reference token according to RFC 6901 by encoding special characters so the token can be safely used as a segment in a JSON Pointer.

When to use

Use when you need to escape a single JSON Pointer path segment.

Details

• Returns a new escaped string
• Replaces ~ (tilde) with ~0 and / (forward slash) with ~1
• Returns the input unchanged if it contains no special characters
• Empty strings are valid and returned unchanged

Gotchas

The replacement order matters: ~ is replaced before / to prevent double-escaping.

See

• unescapeToken The inverse operation for decoding escaped tokens

declare function escapeToken(token: string): string

import { JsonPointer } from "effect"

JsonPointer.escapeToken("a/b") // => "a~1b"
JsonPointer.escapeToken("c~d") // => "c~0d"
JsonPointer.escapeToken("path/to~key") // => "path~1to~0key"

Formats path tokens as a JSON Pointer URI fragment.

When to use

Use when you need a URI fragment that identifies a value in a JSON document.

Details

Each token is encoded with escapeToken before URI percent-encoding is applied. An empty path is formatted as #.

Gotchas

Throws a URIError when a token contains an unpaired surrogate.

See

• parseUriFragment for the inverse operation

declare function formatUriFragment(path: readonly Array<string>): string

import { JsonPointer } from "effect"

JsonPointer.formatUriFragment(["users", "a/b", "Rate%"]) // => "#/users/a~1b/Rate%25"