@winglet/json

yarn add @winglet/json

TypeScript library for safe JSON data manipulation. Implements RFC 6901 (JSON Pointer) and RFC 6902 (JSON Patch) with prototype pollution protection, immutable operations, and sub-path exports.

Installation

yarn add @winglet/json

Sub-path Exports

Import path	Contents
@winglet/json	All exports
@winglet/json/pointer	Full JSON Pointer API
@winglet/json/pointer-manipulator	getValue, setValue, compilePointer
@winglet/json/pointer-patch	JSON Patch operations
@winglet/json/pointer-escape	escapePath, unescapePath
@winglet/json/path	JSON Path constants

Key Exports

Pointer Manipulation (/pointer-manipulator)

• getValue(object, pointer, options?) — read a value at a JSON Pointer path
• setValue(object, pointer, value, options?) — write a value at the path
• compilePointer(pointer) — compile a pointer to reusable segments

JSON Patch (/pointer-patch)

• compare(a, b, options?) — generate RFC 6902 patch between two objects
• applyPatch(object, patches, options?) — apply a patch array
• difference(a, b) — generate RFC 7396 merge patch
• mergePatch(object, patch) — apply a merge patch

Options

Option	Default	Description
immutable	true	Return new object instead of mutating
protectPrototype	true	Block __proto__, constructor, prototype
strict	false	Throw on missing paths

Usage Examples

import { getValue, setValue } from '@winglet/json/pointer-manipulator';

const data = { user: { name: 'Alice', roles: ['admin'] } };

getValue(data, '/user/name');              // 'Alice'
setValue(data, '/user/name', 'Bob');        // new object, original unchanged

import { compare, applyPatch } from '@winglet/json/pointer-patch';

const a = { x: 1, y: 2 };
const b = { x: 1, y: 3, z: 4 };

const patch = compare(a, b);
// [{ op: 'replace', path: '/y', value: 3 }, { op: 'add', path: '/z', value: 4 }]

applyPatch(a, patch); // { x: 1, y: 3, z: 4 }

Claude Code Integration

@winglet/json ships Claude Code assets — the json-skill expert skill and its knowledge base covering JSON Pointer, JSON Path, JSON Patch, and security options — under docs/claude/. They are published alongside the package so AI assistants can reason about pointer-based manipulation with package-specific context.

Inject those assets into your local Claude Code environment with @slats/claude-assets-sync (bin: inject-claude-settings):

npx -p @slats/claude-assets-sync inject-claude-settings --package=@winglet/json --scope=user         # inject into ~/.claude (user-level)
npx -p @slats/claude-assets-sync inject-claude-settings --package=@winglet/json --scope=project      # inject into the nearest existing .claude, walking up from cwd

# Preview / overwrite flags
npx -p @slats/claude-assets-sync inject-claude-settings --package=@winglet/json --scope=user --dry-run   # show the plan without writing
npx -p @slats/claude-assets-sync inject-claude-settings --package=@winglet/json --scope=user --force     # overwrite locally-modified files

The CLI resolves @winglet/json/package.json via createRequire, reads its claude.assetPath (docs/claude), and applies hash-based diff into the selected .claude/ (skip unchanged, warn on divergence, require --force to overwrite).

AI Agent Reference

AI Reference

Package: @winglet/json v0.10.0 Purpose: RFC 6901 JSON Pointer and RFC 6902 JSON Patch with security protections.

Key exports

./path → JSONPath
./path-common → convertJsonPathToPointer
                getJSONPath
./pointer → JSONPointer
./pointer-common → convertJsonPointerToPath
                   getJSONPointer
./pointer-escape → escapeSegment
                   escapePath
                   unescapePath
                   unescapeSegment
./pointer-manipulator → getValue
                        setValue
                        compilePointer
./pointer-patch → applyPatch
                  ApplyPatchOptions (type)
                  compare
                  CompareOptions (type)
                  difference
                  mergePatch
                  Patch (type)
                  TestPatch (type)
                  AddPatch (type)
                  ReplacePatch (type)
                  RemovePatch (type)
                  CopyPatch (type)
                  MovePatch (type)