beta version.

Author: Song Gao

README.md

@@ -53,9 +53,9 @@ The common steps to send a pull request are:
 
 ### What are the TypeScript team's heuristics for PRs to the DOM APIs
 
-Changes to this repo can have pretty drastic ecosystem effects, because these types are included by default in TypeScript. 
+Changes to this repo can have pretty drastic ecosystem effects, because these types are included by default in TypeScript.
 Due to this, we tend to be quite conservative with our approach to introducing changes.
-To give you a sense of whether we will accept changes, you can use these heuristics to know up-front if we'll be open to merging. 
+To give you a sense of whether we will accept changes, you can use these heuristics to know up-front if we'll be open to merging.
 
 #### Fixes
 
@@ -71,9 +71,9 @@ To give you a sense of whether we will accept changes, you can use these heurist
 > For example, adding a new spec or subsection via a new or updated IDL file
 
 - Does the new objects or fields show up in [mdn/browser-compat-data](https://github.com/mdn/browser-compat-data)? If not, it's likely too soon.
-- Is the IDL source from WHATWG? 
+- Is the IDL source from WHATWG?
     - Are the additions available in at least two of Firefox, Safari and Chromium?
-- Is the IDL source from W3C? 
+- Is the IDL source from W3C?
     - What stage of the [W3C process](https://en.wikipedia.org/wiki/World_Wide_Web_Consortium#Specification_maturation) is the proposal for these changes: We aim for Proposed recommendation, but can accept Candidate recommendation for stable looking proposals.
     - If it's at Working draft the additions available in all three of Firefox, Safari and Chromium
 - Could any types added at the global scope have naming conflicts?
@@ -103,3 +103,4 @@ To give you a sense of whether we will accept changes, you can use these heurist
 - `overridingTypes.json`: types that are defined in the spec file but has a better or more up-to-date definitions in the json files.
 - `removedTypes.json`: types that are defined in the spec file but should be removed.
 - `comments.json`: comment strings to be embedded in the generated .js files.
+- `deprecatedMessage.json`: the reason why one type is deprecated. The reason why it is a sprecate file rather than merge in comment.json is mdn/apiDescriptions.json would also possiably be deprecated.

inputfiles/deprecatedMessage.json

@@ -0,0 +1,32 @@
+{
+    "MutationEvent": "DOM4 [DOM] provides a new mechanism using a MutationObserver interface which addresses the use cases that mutation events solve, but in a more performant manner. Thus, this specification describes mutation events for reference and completeness of legacy behavior, but deprecates the use of the MutationEvent interface.",
+    "IDBFactorySync": " The synchronous version of the IndexedDB API was originally intended for use only with Web Workers, and was eventually removed from the spec because its need was questionable. It may however be reintroduced in the future if there is enough demand from web developers.",
+    "MouseScrollEvent": "Do not use this interface for wheel events.\n\nLike MouseWheelEvent, this interface is non-standard and deprecated. It was used in Gecko-based browsers only. Instead use the standard WheelEvent.\n",
+    "SVGExternalResourcesRequired": " This interface was removed in the SVG 2 specification.",
+    "IDBCursorSync": " The synchronous version of the IndexedDB API was originally intended for use only with Web Workers, and was eventually removed from the spec because its need was questionable. It may however be reintroduced in the future if there is enough demand from web developers.",
+    "IDBTransactionSync": " The synchronous version of the IndexedDB API was originally intended for use only with Web Workers, and was eventually removed from the spec because its need was questionable. It may however be reintroduced in the future if there is enough demand from web developers.",
+    "IDBEnvironmentSync": " The synchronous version of the IndexedDB API was originally intended for use only with Web Workers, and was eventually removed from the spec because its need was questionable. It may however be reintroduced in the future if there is enough demand from web developers.",
+    "SVGAltGlyphDefElement": " This interface was removed in the SVG 2 specification.",
+    "IDBVersionChangeRequest": "  The latest specification does not include this interface anymore as the IDBDatabase.setVersion() method has been removed. See the compatibility table for version details.The new way to do it is to use the IDBOpenDBRequest interface which has now the onblocked handler and the newly needed onupgradeneeded one.",
+    "IDBDatabaseException": " This interface was removed from the specification and was replaced by usage of DOMException.",
+    "FileError": " This interface is obsolete per the latest specification. Use the new DOM4 DOMError interface instead.",
+    "IDBObjectStoreSync": " The synchronous version of the IndexedDB API was originally intended for use only with Web Workers, and was eventually removed from the spec because its need was questionable. It may however be reintroduced in the future if there is enough demand from web developers.",
+    "LocalMediaStream": " This interface is no longer available in any mainstream browser. Do not use LocalMediaStream; you need to update any code that does use it as soon as possible or your content or application will stop working. See Stopping a video stream in MediaStreamTrack to learn how. All other functionality is found in MediaStream.",
+    "SVGAltGlyphItemElement": " This interface was removed in the SVG 2 specification.",
+    "SVGGlyphElement": " This interface was removed in the SVG 2 specification.",
+    "SVGRenderingIntent": " This interface was removed in the SVG 2 specification.",
+    "BlobBuilder": " The BlobBuilder interface has been deprecated in favor of the newly introduced Blob constructor.",
+    "MouseWheelEvent": "Do not use this interface for wheel events.\n\nLike MouseScrollEvent, this interface is non-standard and deprecated. It was used in non-Gecko browsers only. Instead use the standard WheelEvent.\n",
+    "ServiceWorkerMessageEvent": " In modern browsers, this interface has been deprecated. Service worker messages will now use the MessageEvent interface, for consistency with other web messaging features.",
+    "ScriptProcessorNode": " As of the August 29 2014 Web Audio API spec publication, this feature has been marked as deprecated, and was replaced by AudioWorklet (see AudioWorkletNode).",
+    "IDBIndexSync": " The synchronous version of the IndexedDB API was originally intended for use only with Web Workers, and was eventually removed from the spec because its need was questionable. It may however be reintroduced in the future if there is enough demand from web developers.",
+    "NameList": " Although this interface was previously implemented in Gecko, there was no way to actually create one. NameList has been removed, effective with Gecko 10.0",
+    "DOMLocator": " This is not implemented in Mozilla",
+    "RTCSessionDescriptionCallback": "Because this function type is part of the legacy WebRTC API, you should avoid using it (and the callback-based forms of createOffer() and createAnswer() that make use of it).\n",
+    "SVGMatrix": " SVG 2 replaced the SVGMatrix interface by the more general DOMMatrix and DOMMatrixReadOnly interfaces.",
+    "DOMConfiguration": " This interface has never been supported in Gecko, and has been removed from the DOM specification.",
+    "AudioProcessingEvent": " As of the August 29 2014 Web Audio API spec publication, this feature has been marked as deprecated, and is soon to be replaced by AudioWorklet.",
+    "IDBEnvironment": " The indexedDB property that was previously defined in this mixin is instead now WindowOrWorkerGlobalScope.indexedDB (that is, defined as a member of the WindowOrWorkerGlobalScope mixin).",
+    "IDBDatabaseSync": " The synchronous version of the IndexedDB API was originally intended for use only with Web Workers, and was eventually removed from the spec because its need was questionable. It may however be reintroduced in the future if there is enough demand from web developers.",
+    "PerformanceNavigation": "This interface is deprecated in the Navigation Timing Level 2 specification. Please use the PerformanceNavigationTiming interface instead.\n"
+}

manualAnalytics/README.md

@@ -0,0 +1,6 @@
+# READ ME!
+All files in this folder aimes to be used by USER rather than CODE.
+
+Users could have a quick view of some data.
+mdnDeprecatedApis.ts -- all api names marked as deprecated in `https://developer.mozilla.org/en-US/docs/Web/API`
+idlSourceAppearDeprecateText.ts -- check web pages in `inputfiles/idlSources.json`, to see whether there is text "deprecate".

manualAnalytics/idlSourceAppearDeprecateText.ts

@@ -0,0 +1,62 @@
+import * as fs from "fs";
+import * as path from "path";
+import fetch from "node-fetch";
+// import { JSDOM } from "jsdom";
+
+interface IDLSource {
+    url: string;
+    title: string;
+    deprecated?: boolean;
+    local?: boolean;
+}
+
+async function fetchIDLs() {
+    const idlSources = (require("../inputfiles/idlSources.json") as IDLSource[]);
+    await Promise.all(idlSources.map(async source => {
+        if (source.local) {
+            return;
+        }
+        await fetchIDL(source);
+    })).then(
+        ()=>{
+            console.log();
+            console.log(deprecatedSet);
+        }
+    );
+}
+
+const tmpLocalFolder = path.join(__dirname, "localIdlSource");
+const deprecatedSet = new Set<string>();
+
+// ['https://www.w3.org/TR/css-color-3/', 'https://www.w3.org/TR/credential-management-1/', 'https://www.w3.org/TR/css-text-decor-3/', 'https://w3c.github.io/media-playback-quality/', 'https://www.w3.org/TR/css-text-3/', 'https://drafts.csswg.org/css-images-3/', 'https://www.w3.org/TR/secure-contexts/', 'https://www.w3.org/TR/SVG2/types.html', 'https://html.spec.whatwg.org/multipage/obsolete.html', 'https://notifications.spec.whatwg.org/', 'https://www.w3.org/TR/SVG2/text.html', 'https://fetch.spec.whatwg.org/', 'https://html.spec.whatwg.org/multipage/webappapis.html', 'https://dom.spec.whatwg.org/', 'https://drafts.fxtf.org/css-masking-1/', 'https://www.w3.org/TR/filter-effects-1/', 'https://drafts.csswg.org/cssom/', 'https://w3c.github.io/webrtc-pc/', 'https://webaudio.github.io/web-audio-api/', 'https://heycam.github.io/webidl/', 'https://www.w3.org/TR/SVG2/pservers.html', 'https://www.w3.org/TR/uievents/']
+
+async function fetchIDL(source: IDLSource) {
+
+    if (!fs.existsSync(tmpLocalFolder)) {
+        fs.mkdirSync(tmpLocalFolder);
+    }
+
+    if (source.url.endsWith(".idl")) {
+        return;
+    }
+
+    const localFile = path.join(tmpLocalFolder, source.title);
+    let webPageContent: string;
+    if (fs.existsSync(localFile)) {
+        webPageContent = fs.readFileSync(localFile, { encoding: "utf-8" });
+    }
+    else {
+        const response = await fetch(source.url);
+        webPageContent = await response.text();
+        fs.writeFileSync(localFile, webPageContent);
+    }
+    if(webPageContent.toLowerCase().includes("deprecated")){
+        deprecatedSet.add(source.url);
+    }
+    // const dom = JSDOM.fragment(
+    //     ""// webPageContent
+    //     );
+
+}
+
+fetchIDLs();

manualAnalytics/mdnDeprecatedApis.ts

@@ -0,0 +1,139 @@
+import * as fs from "fs";
+import fetch from "node-fetch";
+import { JSDOM } from "jsdom";
+import path from "path";
+
+const outputFolder = __dirname
+
+const mdnDeprecatedApisFile = path.join(outputFolder, "mdnDeprecatedApis.json");
+const mdnObsoleteApisFile = path.join(outputFolder, "mdnObsoleteApis.json");
+const mdnDeprecatedApisReasonFile = path.join(outputFolder, "mdnDeprecatedApisReason.json");
+const mdnObsoleteApisReasonFile = path.join(outputFolder, "mdnObsoleteApisReason.json");
+
+const mdnApiWeb = "https://developer.mozilla.org/en-US/docs/Web/API"
+
+async function fetchInterfaceDescriptions() {
+    const fragment = await fetchDom(mdnApiWeb);
+    const InterfacesSelector = '#wikiArticle > div:nth-child(8)';
+
+    const interfacesFragment = fragment.querySelector(InterfacesSelector);
+
+    if (!interfacesFragment) {
+        // This is not that right, but is better than nothing.
+        throw new Error("css selector for interfaces has been changed!");
+    }
+
+    const deprecatedIconSelector = '.icon-thumbs-down-alt';
+    const deprecatedAPIs = [];
+
+    for (const deprecatedIconElem of interfacesFragment.querySelectorAll(deprecatedIconSelector)) {
+        const deprecatedAPI = deprecatedIconElem?.parentElement?.parentElement?.previousSibling?.textContent;
+        if (!deprecatedAPI) {
+            console.dir(deprecatedIconElem);
+            throw new Error("some element could not ");
+        }
+        deprecatedAPIs.push(deprecatedAPI);
+    }
+
+    const obsoleteIconSelector = '.icon-trash';
+    const obsoleteAPIs = [];
+    for (const obsoleteIconElem of interfacesFragment.querySelectorAll(obsoleteIconSelector)) {
+        const obsoleteAPI = obsoleteIconElem?.parentElement?.parentElement?.previousSibling?.textContent;
+        if (!obsoleteAPI) {
+            console.dir(obsoleteIconElem);
+            throw new Error("some element could not ");
+        }
+        obsoleteAPIs.push(obsoleteAPI);
+    }
+
+    fs.writeFileSync(mdnDeprecatedApisFile, JSON.stringify(deprecatedAPIs));
+    fs.writeFileSync(mdnObsoleteApisFile, JSON.stringify(obsoleteAPIs));
+}
+
+async function fetchDeprecatedApiReasons() {
+    await fetchInterfaceDescriptions();
+
+    const deprecatedAPIArray: string[] = require(mdnDeprecatedApisFile);
+    const obsoleteAPIArray: string[] = require(mdnObsoleteApisFile);
+
+    // const maekDeprecatedJsdocApiArray = [...deprecatedAPIArray, ...obsoleteAPIArray];
+
+    // const deprecatedAPIArray: string[] = JSON.parse(s);
+    // use Promise.all to acclete.
+    const mdnDeprecatedApisReason: Record<string, string> = {};
+    const mdnObsoleteApisReason: Record<string, string> = {};
+
+    Promise.all(deprecatedAPIArray.map(async apiName => {
+        const fragment = await fetchDom(`${mdnApiWeb}/${apiName}`);
+
+        let isSearchedArea = true;
+        const searchArea = Array.from(fragment.querySelector("#wikiArticle")?.children!).filter(item => {
+            if (item.tagName === "H2") {
+                isSearchedArea = false;
+            }
+            return isSearchedArea;
+        });
+        const reason1 = searchArea.find(e => e.className.split(' ').includes("warning"))?.textContent;
+        const reason2 = searchArea.find(e => e.className.split(' ').includes("note"))?.textContent;
+
+        // const reason1 = fragment.querySelector("#wikiArticle > .warning")?.textContent;
+        // const reason2 = fragment.querySelector("#wikiArticle > .note")?.textContent;
+
+        if (reason1 && reason2) {
+            throw new Error("not consider situation! api name is " + apiName);
+        }
+        if (!reason1 && !reason2) {
+            return Promise.resolve();
+        }
+        const reason = reason1 ?? reason2;
+        if (!reason) {
+            throw new Error("impossiable");
+        }
+        mdnDeprecatedApisReason[apiName] = reason.substring(reason.indexOf(':') + 1).replace("\n", "");
+    })).then(() => {
+        fs.writeFileSync(mdnDeprecatedApisReasonFile, JSON.stringify(mdnDeprecatedApisReason));
+    })
+
+    Promise.all(obsoleteAPIArray.map(async apiName => {
+        const fragment = await fetchDom(`${mdnApiWeb}/${apiName}`);
+
+        let isSearchedArea = true;
+        const searchArea = Array.from(fragment.querySelector("#wikiArticle")?.children!).filter(item => {
+            if (item.tagName === "H2") {
+                isSearchedArea = false;
+            }
+            return isSearchedArea;
+        });
+        const reason1 = searchArea.find(e => e.className.split(' ').includes("warning"))?.textContent;
+        const reason2 = searchArea.find(e => e.className.split(' ').includes("note"))?.textContent;
+
+        // const reason1 = fragment.querySelector("#wikiArticle > .warning")?.textContent;
+        // const reason2 = fragment.querySelector("#wikiArticle > .note")?.textContent;
+
+        if (reason1 && reason2 && apiName !== "IDBEnvironment") {
+            throw new Error("not consider situation! api name is " + apiName);
+        }
+        if (!reason1 && !reason2) {
+            return Promise.resolve();
+        }
+        const reason = reason1 ?? reason2;
+        if (!reason) {
+            throw new Error("impossiable");
+        }
+        mdnObsoleteApisReason[apiName] = reason.substring(reason.indexOf(':') + 1).replace("\n", "");
+    })).then(() => {
+        fs.writeFileSync(mdnObsoleteApisReasonFile, JSON.stringify(mdnObsoleteApisReason));
+    })
+}
+
+async function fetchDom(url: string) {
+    const response = await fetch(url);
+    if (!response.ok) {
+        throw new Error(`Failed to fetch ${url}`);
+    }
+    const responseString = await response.text();
+
+    return JSDOM.fragment(responseString);
+}
+
+fetchDeprecatedApiReasons();

package.json

@@ -19,6 +19,7 @@
     "node-fetch": "^2.6.0",
     "print-diff": "^0.1.1",
     "styleless-innertext": "^1.1.2",
+    "ts-node": "^8.10.2",
     "typescript": "next",
     "webidl2": "^23.12.1"
   }

src/emitter.ts

@@ -640,7 +640,7 @@ export function emitWebIdl(webidl: Browser.WebIdl, flavor: Flavor) {
         if (entity.comment) {
             entity.comment.split('\n').forEach(print);
         }
-        if (entity.deprecated) {
+        if (entity.deprecated && !entity.comment?.includes('@deprecated')) {
             print(`/** @deprecated */`);
         }
     }

src/helpers.ts

@@ -70,11 +70,11 @@ export function merge<T>(target: T, src: T, shallow?: boolean): T {
                     if (Array.isArray(targetProp) !== Array.isArray(srcProp)) {
                         throw new Error("Mismatch on property: " + k + JSON.stringify(srcProp));
                     }
-                    if (shallow && typeof (target[k] as any).name === "string" && typeof (src[k] as any).name === "string") {
-                        target[k] = src[k];
+                    if (shallow && typeof (targetProp as any).name === "string" && typeof (srcProp as any).name === "string") {
+                        target[k] = srcProp;
                     }
                     else {
-                        target[k] = merge(target[k], src[k], shallow);
+                        target[k] = merge(targetProp, srcProp, shallow);
                     }
                 }
             }