मुख्य कंटेंट तक स्किप करें

@powerduck/conf-patch

@powerduck/conf-patch स्पष्ट दो-स्तरीय संरचना वाली कॉन्फ़िगरेशन संपादन लाइब्रेरी है। यह RFC 6902 JSON Patch के नियमों के अनुसार JSON, JSONC और YAML स्ट्रिंग बदलती है, टिप्पणियाँ और फ़ॉर्मैट बनाए रखती है, और Node.js व Electron के लिए एटॉमिक लेखन तथा प्रक्रियाओं के बीच फ़ाइल लॉक प्रदान करती है।

conf-patch क्यों चुनें?​

कोड से कॉन्फ़िगरेशन फ़ाइल संपादित करते समय अक्सर पूरे दस्तावेज़ को दोबारा सीरियलाइज़ करने और टेक्स्ट में सीधे बदलाव करने के बीच चुनना पड़ता है। पहले विकल्प से टिप्पणियाँ और फ़ॉर्मैट बदल सकते हैं, जबकि दूसरे में गलतियों की आशंका रहती है। conf-patch प्रदान करती है:

  • टिप्पणियाँ सुरक्षित रखते हुए क्रमिक संपादन: JSON/JSONC के लिए jsonc-parser और YAML के AST में बदलाव के लिए 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 या Node.js-विशिष्ट API पर निर्भर नहीं हैं। इस उपपथ को ब्राउज़र, Edge फ़ंक्शन या सर्विस वर्कर के कोड में शामिल किया जा सकता है।

फ़ंक्शनउद्देश्य
patchContentकॉन्फ़िगरेशन स्ट्रिंग पर RFC 6902 ऑपरेशन लागू करना
setContentValueनेस्टेड मान सेट करना या बनाना (add से)
deleteContentValueकुंजी या ऐरे का तत्व हटाना (remove से)

फ़ाइल स्तर — @powerduck/conf-patch (Node.js / Electron)​

वास्तविक फ़ाइलें पढ़ने और लिखने वाले असिंक्रोनस फ़ंक्शन, जो मुख्य स्तर में एटॉमिक लेखन और लॉक जोड़ते हैं।

फ़ंक्शनउद्देश्य
readConfigFileफ़ाइल पथ या file:// URL से UTF-8 टेक्स्ट पढ़ना
writeConfigFileवैकल्पिक लॉक के साथ सामग्री एटॉमिक रूप से लिखना
patchConfigFileफ़ाइल लॉक में पढ़ने, बदलने और लिखने का लेनदेन करना
setConfigValueफ़ाइल में नेस्टेड मान सेट करना
deleteConfigValueफ़ाइल से नेस्टेड मान हटाना
withFileLockअनन्य लॉक के अंतर्गत कार्य चलाना
releaseAllLocalLocksवर्तमान प्रक्रिया के सभी लॉक छोड़ना

समर्थित फ़ॉर्मैट​

फ़ॉर्मैटएक्सटेंशनव्यवहार
JSON.jsonमानक JSON। jsonc-parser से क्रमिक संपादन।
JSONC.jsoncटिप्पणियों और अंतिम कॉमा वाला JSON। टिप्पणियाँ सुरक्षित रहती हैं।
YAML.yaml, .ymlYAML 1.2। AST में बदलाव टिप्पणियाँ, एंकर और इंडेंटेशन बनाए रखते हैं।

detectFormat फ़ाइल एक्सटेंशन को ConfigFormat से जोड़ता है। अन्य एक्सटेंशन पर त्रुटि आती है, जब तक आप format स्पष्ट रूप से न दें।

RFC 6902 ऑपरेशन​

conf-patch RFC 6902 के एक सीमित भाग को लागू करती है। केवल ये ऑपरेशन समर्थित हैं:

opव्यवहार
"add"ऐरे के इंडेक्स पर तत्व डालना या ऑब्जेक्ट की प्रॉपर्टी जोड़ना/बदलना
"replace"मौजूदा मान बदलना; पथ मौजूद होना चाहिए
"remove"मौजूदा कुंजी या ऐरे तत्व हटाना; पथ मौजूद होना चाहिए
caution

"move", "copy" और "test" समर्थित नहीं हैं। JsonPatchOp प्रकार op को "add" | "replace" | "remove" तक सीमित करता है।

व्यवहार संबंधी बातें:

  • ऐरे इंडेक्स पर add तत्व डालता है (RFC 6902)। मौजूदा तत्व बदलने के लिए replace उपयोग करें।
  • add के लिए मूल पथ पहले से मौजूद होना चाहिए। चाइल्ड से पहले पैरेंट बनाएँ।
  • replace और remove के लिए लक्ष्य पथ मौजूद होना चाहिए।
  • strict: true (डिफ़ॉल्ट) पर विफल ऑपरेशन अपवाद उत्पन्न करता है। strict: false पर उसे छोड़ दिया जाता है और चेतावनी दर्ज होती है।

टिप्पणियाँ और फ़ॉर्मैट सुरक्षित रखना​

  • JSON/JSONC: सिंटैक्स ट्री के आधार पर बदलाव के टेक्स्ट क्षेत्र तय किए जाते हैं, जिससे आसपास की टिप्पणियाँ, अंतिम कॉमा और इंडेंटेशन सुरक्षित रहते हैं।
  • YAML: yaml AST को सीधे बदलकर दोबारा सीरियलाइज़ किया जाता है; टिप्पणियाँ, एंकर, उपनाम और इंडेंटेशन सुरक्षित रहते हैं।

OpenAPI सत्यापन​

conf-patch, @powerduck/openapi-parser पर अतिरिक्त सुरक्षा जाँच वाले इंटरफ़ेस से OpenAPI/Swagger दस्तावेज़ सत्यापित करती है:

  • validateOpenAPISpec मूल JSON या YAML सामग्री सत्यापित करता है।
  • validateOpenAPIFile फ़ाइल पथ से दस्तावेज़ सत्यापित करता है।
  • इनपुट प्रक्रिया में आकार सीमा, अनुमत पथों की सीमा (allowedRootDirectory), संरचना की जटिलता की जाँच, समय-सीमा और AbortSignal से रद्द करना लागू होता है।
  • विफलता पर OpenApiValidationError मिलता है, जिसमें प्रोग्राम से संभालने योग्य code होता है।

अगले कदम​

  • स्थापना — conf-patch जोड़ें और दोनों प्रवेश बिंदु समझें।
  • त्वरित शुरुआत — ब्राउज़र की स्ट्रिंग और डिस्क की फ़ाइल बदलें।
  • API संदर्भ — सभी एक्सपोर्ट, प्रकार और विकल्प।
  • उदाहरण — JSON, YAML, JSONC, OpenAPI सत्यापन और लॉक के चलने योग्य उदाहरण।