@powerduck/conf-patch

@powerduck/conf-patch — библиотека редактирования конфигураций с двухуровневой архитектурой. Она изменяет строки JSON, JSONC и YAML по правилам RFC 6902 JSON Patch, сохраняя комментарии и форматирование, и предоставляет атомарную запись и межпроцессные блокировки для Node.js и Electron.

Версия:
Лицензия: MIT
Требования к Node.js: >= 22.12.0
Исходный код: github.com/powerducklab/conf-patch

Зачем нужна conf-patch?

При программном редактировании конфигурации часто приходится выбирать между повторной сериализацией всего документа, которая может изменить комментарии и форматирование, и ненадёжными операциями над текстом. conf-patch предлагает:

Инкрементальные изменения с сохранением комментариев для JSON/JSONC через jsonc-parser и изменение AST для YAML через yaml. JSON/JSONC не сериализуется заново целиком; для YAML повторно сериализуется изменённое AST.
Атомарную запись через временный файл и переименование, чтобы целевой файл не оказался записан лишь частично.
Межпроцессные блокировки с токенами владельца, экспоненциальными задержками повторных попыток и восстановлением устаревших блокировок.
API для разных сред: ядро работает также в браузерах, функциях Edge и приложениях с хранилищем IndexedDB.

Двухуровневая архитектура

┌──────────────────────────────────────────────────────────────┐
│                     Application code                          │
├──────────────────────────────────────────────────────────────┤
│  File layer (Node.js / Electron only)                         │
│  ┌───────────────┐ ┌────────────────┐ ┌──────────────────┐  │
│  │ readConfigFile │ │ writeConfigFile│ │ patchConfigFile   │  │
│  │ setConfigValue │ │ deleteConfig…  │ │ withFileLock     │  │
│  └──────┬────────┘ └───────┬────────┘ └────────┬─────────┘  │
│         │                  │                   │            │
│  ┌──────▼──────────────────▼───────────────────▼───────────┐ │
│  │           Core layer (browser-safe, zero Node deps)      │ │
│  │  patchContent   setContentValue   deleteContentValue     │ │
│  └──────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘

Ядро — `@powerduck/conf-patch/core` (совместимо с браузером)

Чистые функции для работы со строками, без node:fs, node:path и других API, специфичных для Node.js. Этот подпуть можно включать в код браузера, функций Edge и сервис-воркеров.

Функция	Назначение
`patchContent`	Применить операции RFC 6902 к строке конфигурации
`setContentValue`	Задать или создать вложенное значение (через `add`)
`deleteContentValue`	Удалить ключ или элемент массива (через `remove`)

Файловый уровень — `@powerduck/conf-patch` (Node.js / Electron)

Асинхронные функции чтения и записи файлов, дополняющие ядро атомарной записью и блокировками.

Функция	Назначение
`readConfigFile`	Прочитать текст UTF-8 по пути или URL `file://`
`writeConfigFile`	Атомарно записать содержимое, при необходимости под блокировкой
`patchConfigFile`	Выполнить транзакцию чтения, изменения и записи под блокировкой
`setConfigValue`	Задать вложенное значение в файле
`deleteConfigValue`	Удалить вложенное значение из файла
`withFileLock`	Выполнить произвольную работу под исключительной блокировкой
`releaseAllLocalLocks`	Освободить все блокировки текущего процесса

Поддерживаемые форматы

Формат	Расширение	Поведение
JSON	`.json`	Стандартный JSON. Инкрементальные изменения через `jsonc-parser`.
JSONC	`.jsonc`	JSON с комментариями и завершающими запятыми. Комментарии сохраняются.
YAML	`.yaml`, `.yml`	YAML 1.2. Изменения AST сохраняют комментарии, якоря и отступы.

detectFormat сопоставляет расширение файла с ConfigFormat. Для других расширений возникает ошибка, если явно не указать format.

Операции RFC 6902

conf-patch реализует часть RFC 6902. Поддерживаются только следующие операции:

`op`	Поведение
`"add"`	Вставить элемент по индексу массива либо добавить/заменить свойство объекта
`"replace"`	Заменить существующее значение; путь должен существовать
`"remove"`	Удалить существующий ключ или элемент массива; путь должен существовать

предупреждение

"move", "copy" и "test" не поддерживаются. Тип JsonPatchOp ограничивает op значениями "add" | "replace" | "remove".

Особенности поведения:

add по индексу массива вставляет элемент (RFC 6902). Для замены существующего элемента используйте replace.
add требует наличия родительского пути. Сначала создавайте родителей, затем дочерние узлы.
replace и remove требуют наличия целевого пути.
При strict: true (по умолчанию) неудачная операция вызывает исключение. При strict: false она пропускается, а в журнал записывается предупреждение.

Сохранение комментариев и форматирования

JSON/JSONC: изменения вычисляются как диапазоны текста по синтаксическому дереву; окружающие комментарии, завершающие запятые и отступы сохраняются.
YAML: AST библиотеки yaml изменяется на месте и сериализуется заново с сохранением комментариев, якорей, псевдонимов и отступов.

Проверка OpenAPI

conf-patch проверяет документы OpenAPI/Swagger через интерфейс к @powerduck/openapi-parser с дополнительными защитными ограничениями:

validateOpenAPISpec проверяет исходное содержимое JSON или YAML.
validateOpenAPIFile проверяет документ по пути к файлу.
Обработка входных данных включает ограничения размера, допустимых путей (allowedRootDirectory), сложности структуры, времени выполнения и отмену через AbortSignal.
При ошибке возникает OpenApiValidationError с полем code для программной обработки.

Установка — добавьте conf-patch и изучите две точки входа.
Быстрый старт — измените строку в браузере и файл на диске.
Справочник API — все экспорты, типы и параметры.
Примеры — исполняемые примеры для JSON, YAML, JSONC, проверки OpenAPI и блокировок.

Зачем нужна conf-patch?​

Двухуровневая архитектура​

Ядро — @powerduck/conf-patch/core (совместимо с браузером)​

Файловый уровень — @powerduck/conf-patch (Node.js / Electron)​

Поддерживаемые форматы​

Операции RFC 6902​

Сохранение комментариев и форматирования​

Проверка OpenAPI​

Далее​