Schema से TypeScript टाइप बनाना
मुख्य बात: json-schema-to-typescript और quicktype एक कमांड में .d.ts बना देते हैं, पर वह केवल draft है: optionality, unions, additionalProperties और dates पर एक बार इंसानी जाँच चाहिए।
मुख्य बात: json-schema-to-typescript या quicktype से बनाएँ, फिर optionality, unions, additionalProperties और dates को हाथ से ठीक करें; Schema को स्रोत और टाइप को आउटपुट रखें, जिसे CI में types:check चरण लागू करे।
एक कमांड आपको फ़ाइल दे देता है। सही टाइप नहीं देता।
एक पंक्ति वाला कमांड
npx json-schema-to-typescript schema.json > src/types/order.d.ts
यह $ref, allOf, oneOf, anyOf संभालता है, और description को JSDoc में बदलता है। banner और चुने हुए style के साथ बैच में बनाने के लिए एक छोटी build-types.mjs से इसका Node API कॉल करें।
quicktype विकल्प है, और sample JSON से schema भी अनुमान लगा सकता है:
npx quicktype -s schema schema.json -o order.ts --lang typescript
बाद में ठीक करने वाली चार चीज़ें
Optionality। जो कुछ required में नहीं है वह ? बन जाता है। पर "हमेशा मौजूद, null हो सकता है" और "अनुपस्थित हो सकता है" अलग-अलग अनुबंध हैं:
interface Order {
remark?: string | null; // अनुपस्थित हो सकता है
status: string;
}
अगर backend हमेशा remark: null भेजता है, तो ? हटा दें और हर उपभोक्ता को undefined के लिए guard करना बंद करें।
बिना discriminant वाले unions। oneOf आमतौर पर A | B बन जाता है, जिसे TypeScript literal फ़ील्ड के बिना narrow नहीं कर सकता। Schema में हर शाखा में एक निश्चित type property जोड़ें।
additionalProperties। छोड़ा गया या true कभी-कभी [k: string]: unknown देता है, कभी any। पहला सुरक्षित है, दूसरा पूरे object के लिए चुपचाप type checking बंद कर देता है।
Date फ़ॉर्मैट। format: "date-time" wire पर string है। इसे Date में मैप करने का मतलब है कि deserialize भी करना पड़ेगा, वरना runtime मान string रहता है जबकि टाइप झूठ बोलता है।
दिशा स्थिर रखें
Schema स्रोत है, टाइप आउटपुट। हाथ से लिखे टाइप से Schema बनाना केवल तब स्वीकार्य है जब पुनर्जनन अनिवार्य हो और CI में लागू हो — वरना दोनों पक्ष बहक जाते हैं और किसी को नहीं पता कि कौन अधिकारिक है।
इसे pipeline में डालें
"types:gen": "json2ts -i schemas/ -o src/types/generated",
"types:check": "pnpm types:gen && git diff --exit-code src/types/generated"
types:check ही असली चीज़ है: Schema बदलें और बिना पुनर्जनन के CI विफल हो जाती है।
FAQ
बनी हुई फ़ाइल में any क्यों आता है?
यह आमतौर पर additionalProperties के true होने या छूटे होने से आता है, जिसे कुछ generators [k: string]: any में मैप करते हैं। इसे unknown या स्पष्ट फ़ील्ड से बदलें, क्योंकि any पूरे object के लिए type checking बंद कर देता है।
पुनर्जनन के बाद optional फ़ील्ड कैसे ठीक करूँ?
required से बाहर का हर फ़ील्ड ? बन जाता है, पर "हमेशा मौजूद, null हो सकता है" और "अनुपस्थित हो सकता है" अलग हैं। अगर backend वह फ़ील्ड हमेशा भेजता है, तो ? हटा दें।
Schema और टाइप के बहकने पर CI विफल होनी चाहिए?
हाँ। types:check स्क्रिप्ट जो पुनर्जनन करके git diff --exit-code चलाती है, Schema के बिना पुनर्जनन बदलते ही build विफल कर देती है।