JSDoc ही TypeScript है

 (culi.bearblog.dev)
1 पॉइंट द्वारा GN⁺ 2025-12-16 | 1 टिप्पणियां | WhatsApp पर शेयर करें
  • 2023 में Svelte repository के refactoring PR ने JSDoc-आधारित कोड में बदलाव किया और TypeScript skeptics का ध्यान खींचा
  • Svelte ने इसे TypeScript-विरोधी रुख नहीं, बल्कि TypeScript पर लगातार निर्भरता का हिस्सा बताया
  • लेख JSDoc और TypeScript को आमने-सामने रखने के बजाय यह ज़ोर देता है कि JSDoc खुद TypeScript का ही हिस्सा है
  • TypeScript एक IntelliSense engine के रूप में काम करता है, जो JSDoc comments की व्याख्या और code autocomplete दोनों संभालता है
  • JSDoc बिना build step के वही static analysis क्षमता देता है, और आधुनिक JS projects में व्यवहारिक रूप से TypeScript जैसी ही भूमिका निभाता है

Svelte PR और विवाद की पृष्ठभूमि

  • मई 2023 में Svelte repository का internal refactoring PR Hacker News के पहले पेज पर पहुंचा
    • इस PR में .ts files के type declarations को .js files के JSDoc comments में स्थानांतरित किया गया था
    • कुछ लोगों ने इसे TypeScript के फायदों को नकारने के रूप में देखा
  • Svelte के creator Rich Harris ने HN पर सीधे समझाया कि “यह TypeScript के खिलाफ नहीं है”
    • उन्होंने कहा कि Svelte की TypeScript के प्रति प्रतिबद्धता अब भी मजबूत है
  • इस घटना के बाद “TypeScript vs JSDoc” तुलना वाले कई लेख सामने आए, और JSDoc को “build step के बिना TypeScript” कहने का रुझान फैलने लगा

TypeScript की उत्पत्ति और मूल स्वभाव

  • 2000 के दशक के अंत से 2010 के शुरुआती वर्षों तक JavaScript को autocomplete और type safety की कमी वाली भाषा माना जाता था
    • Microsoft developers ने ScriptSharp का उपयोग करके C# code को JS में बदलने के तरीके से इस समस्या का समाधान किया
  • इसी पृष्ठभूमि में TypeScript का जन्म हुआ, और इसकी शुरुआत मूल रूप से JS development को बेहतर बनाने वाले build tool के रूप में हुई

TypeScript ही IntelliSense है

  • TypeScript सिर्फ एक language नहीं, बल्कि IntelliSense engine की भूमिका निभाता है
    • .ts files का उपयोग न करने पर भी code autocomplete, parameter info और symbol navigation जैसी सुविधाएं TypeScript language service ही देती हैं
    • अधिकांश editors में JS code लिखते समय भी TypeScript service backend के रूप में चलती है

TypeScript ही JSDoc है

  • TypeScript language service का उपयोग JSDoc comments की व्याख्या के लिए भी किया जाता है
    • TypeScript के CHANGELOG में JSDoc से जुड़ी features के जोड़े जाने का विवरण अक्सर शामिल होता है
    • JSDoc-आधारित projects को tsconfig.json से configure किया जा सकता है, और tsc command से type checking भी की जा सकती है
  • इसलिए JSDoc का उपयोग करने वाले developers भी वास्तव में पहले से TypeScript का उपयोग कर रहे होते हैं

JSDoc-आधारित project का अनुभव

  • लेखक ने अपने एक मौजूदा project के frontend को JSDoc type annotations के आधार पर दोबारा लिखने का अनुभव साझा किया
    • enum जैसे runtime features को छोड़ दें, तो TypeScript की अधिकांश अभिव्यक्तियां JSDoc में संभव हैं
    • generics का syntax थोड़ा जटिल है, लेकिन इससे type inference का अधिक सक्रिय उपयोग होता है
  • JSDoc projects में function पर click करने पर सीधे वास्तविक code तक जाया जा सकता है, जिससे development experience बेहतर होता है
  • TypeScript tooling ecosystem को JSDoc projects में भी दोबारा इस्तेमाल किया जा सकता है
    • उदाहरण: OpenAPI या GraphQL schema से types generate करने वाली libraries JSDoc comments के रूप में types generate कर सकती हैं

निष्कर्ष और अतिरिक्त उदाहरण

  • JSDoc, TypeScript का विकल्प नहीं, बल्कि उसी static analysis system को साझा करता है
    • build step हटाकर भी यह समान स्तर की type safety दे सकता है
  • अतिरिक्त रूप से, webpack project के JSDoc में migrate होने का उदाहरण भी दिया गया है
  • TypeScript expert के रूप में लेखक साफ तौर पर यह रुख रखते हैं: “JSDoc ही TypeScript है”

संबंधित पढ़ाई

1 टिप्पणियां

 
GN⁺ 2025-12-16
Hacker News की राय

  • कई वर्षों तक Python/JavaScript में वेब और रोबोटिक्स सॉफ़्टवेयर विकसित और मेंटेन करते हुए मैंने जो सीखा, उसका सार यह है
    टाइप्स बिना स्पष्ट रूप से लिखे भी मौजूद होते हैं, और अगर उन्हें लिखा न जाए तो वे आखिरकार सिर्फ़ हमारे दिमाग़ में ही रह जाते हैं
    लेकिन दिमाग़ की स्मृति अस्थिर होती है और दूसरे लोगों के लिए उस तक पहुँचना मुश्किल होता है
    इसलिए typing दस्तावेज़ीकरण का एक शानदार साधन है
    JSDoc और TypeScript टाइप्स को व्यक्त करने के मानक प्रारूप हैं, और दोनों के अपने फायदे और नुकसान हैं
    महत्वपूर्ण बात यह है कि टाइप्स को एकसमान और पूर्वानुमेय तरीके से परिभाषित किया जाए
    type checker कंप्यूटर का यह कहने का तरीका है: “तो फिर इसे साबित करो”
    हर प्रोग्राम को एक ही स्तर के proof की ज़रूरत नहीं होती, और ज़रूरत से ज़्यादा proof देना व्यर्थ हो सकता है
    इसलिए मैं ऐसी भाषा पसंद करता हूँ जिसमें जितनी ज़रूरत हो उतना ही “prove” किया जा सके

    • “जो जानकारी सिर्फ़ दिमाग़ में है, वह बहुत अस्थिर होती है” — इस बात से मैं पूरी तरह सहमत हूँ
      खासकर काम करते हुए मैंने यह गहराई से सीखा कि ‘दूसरे लोग’ में भविष्य का मैं खुद भी शामिल हूँ
    • Rust को अक्सर “prove it” दर्शन का प्रतिनिधि माना जाता है, लेकिन मुझे लगता है कि व्यवहार में बात ऐसी नहीं है
      Rust में unsafe, Arc, clone जैसी चीज़ों से constraints ढीले किए जा सकते हैं, लेकिन बदले में आपको साफ़-साफ़ चुनना पड़ता है कि कौन-सी constraints prove नहीं की गई हैं
      इसके उलट, जिन भाषाओं में “prove न करने” की छूट होती है, उनमें अंदरूनी तौर पर कौन-सा तरीका अपनाया गया है यह समझना कठिन होता है
      Rust का तरीका शुरुआती चरण में Python जितना ढीला लग सकता है, लेकिन बाद में readability और scalability के लिहाज़ से यह कहीं ज़्यादा फायदेमंद होता है
    • मैं इस बात से सहमत हूँ कि JSDoc और TypeScript का उद्देश्य मूल रूप से एक ही है
      किसी खास टूल की वकालत करने का इरादा नहीं था, बस यह ज़ोर देना था कि दोनों ही type system को व्यक्त करने के तरीके हैं
    • 25 साल पहले विश्वविद्यालय के दिनों में ही मैंने यह सबक सीख लिया था
      statically typed languages टीम प्रोजेक्ट्स में काफ़ी ज़्यादा संभालने योग्य थीं, और आज भी जहाँ संभव हो मैं static types को प्राथमिकता देता हूँ
    • “टाइप्स हमेशा मौजूद रहते हैं” — इससे मैं सहमत हूँ, लेकिन C# जैसी भाषाएँ जहाँ टाइप्स को स्पष्ट लिखना पड़ता है, Ruby की तुलना में कहीं ज़्यादा मेहनत माँगती हैं
      मौजूदा JS libraries में बाद में जोड़ी गई TypeScript type definitions को देखें तो उनकी जटिलता बहुत बड़ी होती है
      एक गलत type पूरे compilation को तोड़ सकता है
      अंततः dynamic languages को ‘खुद ज़िम्मेदारी लेकर’ इस्तेमाल करना पड़ता है

  • मुझे वह सब पसंद है जो build step के बिना JavaScript से बनाया जा सकता है
    आधुनिक HTML/CSS, Web Components, और JSDoc का संयोजन कम आंका गया है
    यह सबके लिए नहीं है, लेकिन मुझे लगता है कि यह एक काफ़ी आधुनिक frontend stack का उम्मीदवार है

    • अब Node 24 से TypeScript भी build step के बिना चल सकता है
    • build step न होने वाले approach का आकर्षण समझ में आता है, लेकिन व्यवहार में dependency management ज़्यादा जटिल हो जाता है
      HMR जैसी सुविधाओं की वजह से build step की लागत भी काफ़ी कम हो गई है
    • पिछले 10 वर्षों में मैंने ऐसा JS code शायद ही कभी लिखा हो जो वास्तव में सीधे deploy हुआ हो
      हमेशा Vite या Webpack से होकर ही गया, इसलिए build-less JS के फायदे मुझे खास महसूस नहीं हुए
    • Web Components बनाना काफ़ी तकलीफ़देह है
      काश जटिल components को आसानी से बनाने का कोई बेहतर तरीका होता
    • HTML+CSS+JSDoc संयोजन का बड़ा फायदा browser developer tools के साथ इसका स्वाभाविक integration है
      network requests ट्रैक करना, source code पर सीधे जाना, breakpoints लगाना — debugging बहुत ज़्यादा सहज हो जाती है
      project का पैमाना बढ़ने पर ऐसा environment बहुत मददगार होता है

  • जब SPA का दौर चरम पर था, तब JSDoc type management का रक्षक था
    बाद में Google Closure Compiler आया, जिसने JSDoc-आधारित type safety दी, और TypeScript ने अपनी syntax के साथ (TS)JSDoc को support किया
    community ने अंततः TypeScript को चुना और Closure Compiler पीछे छूट गया
    इसलिए (TS)JSDoc अब उस दौर का अवशेष बनकर रह गया जब MS और Google प्रतिस्पर्धा कर रहे थे
    आज TS generics, Enum, utility types, Vitest type tests, type guards जैसी कहीं अधिक सुविधाएँ देता है
    मैं TS और JSDoc दोनों साथ में इस्तेमाल करता हूँ — TS code के लिए, JSDoc documentation के लिए (@link, @see, @deprecated, @example आदि)

    • वास्तव में आधुनिक JSDoc, TypeScript language service का उपयोग करता है
      generics, utility types, type guards, regex parsing जैसी TS की अधिकांश सुविधाएँ JSDoc में भी इस्तेमाल की जा सकती हैं
      मैंने अपने निजी प्रोजेक्ट में generics समेत सब कुछ JSDoc से करके देखा है
    • ऊपर किया गया दावा तथ्यात्मक रूप से सही नहीं है
      यह कहना कि (TS)JSDoc अतीत का अवशेष है, गलत जानकारी है, इसलिए इसकी पुष्टि किए बिना इसे फैलाना नहीं चाहिए
    • यह लेख खुद उसी दावे का सीधा खंडन है

  • लोग कहते हैं कि JSDoc से कई तरह के types व्यक्त नहीं किए जा सकते, लेकिन अगर Flow की तरह पूरे language-level का approach मिलता तो अच्छा होता
    TypeScript भी ऐसा कर सकता था, फिर उसने ऐसा क्यों नहीं किया समझ नहीं आता

    • अगर आपके पास कोई ठोस उदाहरण है तो मैं सुनना चाहूँगा
      मैं भी पहले ऐसा ही सोचता था, लेकिन जब प्रोजेक्ट को JSDoc में refactor किया तो मेरी राय बदल गई
      JSDoc में भी @template से generic slots परिभाषित किए जा सकते हैं
      उदाहरण: 
      /** @type {ReturnType<typeof useState<Book[]>>} */
const [books, setBooks] = useState();
    • अब लगभग सभी type system features JSDoc syntax में भी जोड़ दिए गए हैं
    • TypeScript का type system Turing complete है, इसलिए उसमें वस्तुतः असीम अभिव्यक्ति-क्षमता है
      संबंधित लिंक

  • JSDoc में लिखे गए packages का developer experience अच्छा होता है क्योंकि CMD/CTRL क्लिक करने पर सीधे असली code पर जाया जा सकता है

    • इसे editor settings से customize भी किया जा सकता है
    • वास्तव में TypeScript में भी यह बिल्कुल इसी तरह काम करता है

  • 5 साल पहले एक meetup में किसी वक्ता ने कहा था, “अगर TypeScript पसंद नहीं है तो JSDoc एक विकल्प है”
    मैंने समझाया कि आख़िरकार दोनों ही TypeScript हैं, लेकिन मेरे boss ने मेरी बात नहीं मानी

    • मुझे लगता है कि फर्क सिर्फ़ syntax compression की मात्रा का है
    • “JSDoc भी आखिर TypeScript ही है” — यह बात आधी सही है
      JSDoc और TS दोनों types को explicit रूप से व्यक्त करते हैं, लेकिन TS syntax कहीं ज़्यादा शक्तिशाली है
      फिर भी जो लोग JS environment बनाए रखते हुए type tools के फायदे लेना चाहते हैं, उनके लिए JSDoc एक अच्छा विकल्प है

  • एक प्रतिवाद यह है कि JSDoc, TypeScript नहीं है
    @typedef से परिभाषित types अपने-आप export हो जाते हैं, और इसे नियंत्रित करने का कोई तरीका नहीं है
    संबंधित इश्यू
    इसी वजह से library development में IntelliSense बेतरतीब तरीके से उजागर हो जाता था, जो असुविधाजनक था

    • Web Components के लिए JSDoc काफ़ी अच्छी तरह फिट बैठता है
      “my-component.js” फ़ाइल को वैसे ही कॉपी करें तो वह build के बिना भी काम करती है
      लेकिन बड़े प्रोजेक्ट्स में मैं TS syntax को प्राथमिकता देता हूँ
    • तकनीकी रूप से यह सही आपत्ति है, लेकिन @import को नियंत्रित करके ज़्यादातर समस्या हल की जा सकती है

  • मैं इस दावे से सहमत हूँ कि “JSDoc, TypeScript का विकल्प नहीं है”
    JSDoc भी static analysis देता है लेकिन build step नहीं होता
    Node आधिकारिक दस्तावेज़ देखें

    • अंदरूनी तौर पर अब भी build step मौजूद है
      लेकिन JSDoc-आधारित TS browser में भी काम कर सकता है
      व्यक्तिगत रूप से मैं TS syntax की readability को पसंद करता हूँ, और swc जैसे टूल्स से type stripping की गति भी काफ़ी तेज़ है
    • हालाँकि यह सुविधा Node environment तक सीमित है और browser में काम नहीं करती

  • TypeScript ने दूसरे विकल्पों पर इसलिए जीत हासिल की क्योंकि वह नई भाषा बनने के बजाय type checker ही बना रहा
    शुरुआती दौर में दिशा थोड़ी डगमगाई थी, लेकिन बाद में सही सुधार हुए, और आज अधिकांश code में enums तक का ज़्यादा उपयोग नहीं होता

  • VSCode में “TypeScript: Prefer Go To Source Definition” सेटिंग ऑन करने पर सीधे असली source पर जाया जा सकता है
    साथ ही tsconfig में declarationMap: true जोड़ने से यह और अधिक सटीक तरीके से काम करता है
    मैं लगभग हमेशा cmd+click पर source देखना पसंद करता हूँ