@arcgis/api-extractor 5.0.0-next.8 → 5.0.0-next.9

package/dist/apiJson.d.ts

@@ -115,6 +115,12 @@ export type ApiJavaScriptModule = {
      * Whether the module is deprecated.
      * If the value is a string, it's the reason for the deprecation.
      *
+     * @remarks
+     * If module is marked as deprecated, all its declarations should also be
+     * marked as deprecated. This is because in TypeScript, a usage of a
+     * declaration will only be marked as deprecated if the declaration itself
+     * is marked as deprecated, rather than its module.
+     *
      * @default false
      */
     deprecated?: boolean | string;
@@ -283,10 +289,6 @@ export type ApiCustomElementDeclaration = Omit<ApiClassDeclaration, "members"> &
      * "attributes" is not necessary.
      */
     attributes?: ApiAttribute[];
-    /**
-     * The events that this element fires.
-     */
-    events?: ApiEvent[];
     /**
      * The shadow dom content slots that this element accepts.
      */
@@ -736,6 +738,10 @@ export type ApiClassDeclaration = {
      */
     mixins?: ApiReference[];
     members?: ApiClassMember[];
+    /**
+     * The events that this element fires.
+     */
+    events?: ApiEvent[];
     /**
      * @remarks
      * Not used by `@arcgis/api-extractor`. Preserved in typings for compatibility

package/dist/diff/diffApiJson.d.ts

@@ -0,0 +1,3 @@
+import { ApiJson } from '../apiJson';
+import { ApiDiff } from './types';
+export declare function diffApiJson(oldApiJson: Pick<ApiJson, "modules">, newApiJson: Pick<ApiJson, "modules">): ApiDiff;

package/dist/diff/fetchApiJsonFromNpm.d.ts

@@ -0,0 +1,7 @@
+import { ApiJson } from '../apiJson';
+/**
+ * Read dist/docs/api.json for a given NPM package.
+ *
+ * @example fetchApiJsonFromNpm("@arcgis/map-components", "latest");
+ */
+export declare function fetchApiJsonFromNpm(packageName: string, semverVersion: string): Promise<ApiJson>;

package/dist/diff/index.d.ts

@@ -0,0 +1,3 @@
+export { fetchApiJsonFromNpm } from './fetchApiJsonFromNpm';
+export { diffApiJson } from './diffApiJson';
+export type * from './types';

package/dist/diff/types.d.ts

@@ -0,0 +1,66 @@
+import { ApiClassDeclaration, ApiClassField, ApiClassMethod, ApiCustomElementDeclaration, ApiFunctionDeclaration, ApiModule, ApiVariableDeclaration } from '../apiJson';
+export interface ApiDiff {
+    modules: ApiModuleDiff[];
+}
+export interface ApiModuleDiff {
+    path: ApiModule["path"];
+    declarations: ApiDeclarationDiff[];
+}
+export interface ApiDiffBase {
+    name: string;
+    /**
+     * True if this declaration was removed in the new api.json.
+     * If class is removed, members are not listed.
+     * @default false
+     */
+    removed?: true;
+    /**
+     * True if this declaration was added in the new api.json.
+     * If class is added, members are not listed.
+     *
+     * @default false
+     */
+    added?: true;
+    /**
+     * Whether this declaration is deprecated in the new api.json, regardless of
+     * whether it was deprecated in the old api.json.
+     * If the value is a string, it's the reason for the deprecation.
+     * Deprecated takes precedence over added.
+     *
+     * @default false
+     */
+    deprecated?: boolean | string;
+}
+export type ApiDeclarationDiff = ApiClassDeclarationDiff | ApiCustomElementDeclarationDiff | ApiFunctionDeclarationDiff | ApiVariableDeclarationDiff;
+export interface ApiClassDeclarationDiff extends ApiDiffBase {
+    kind: ApiClassDeclaration["kind"];
+    /**
+     * Inherited members are not included in the diff.
+     * Also, if entire class is added/removed, members are not included in the diff.
+     */
+    members?: ApiClassMemberDiff[];
+    events?: ApiDiffBase[];
+}
+export interface ApiCustomElementDeclarationDiff extends ApiClassDeclarationDiff {
+    /**
+     * Attributes diff is not included as attributes are based on members.
+     */
+    tagName: ApiCustomElementDeclaration["tagName"];
+    slots?: ApiDiffBase[];
+    cssParts?: ApiDiffBase[];
+    cssProperties?: ApiDiffBase[];
+    cssStates?: ApiDiffBase[];
+}
+export type ApiClassMemberDiff = ApiClassFieldDiff | ApiClassMethodDiff;
+export interface ApiClassFieldDiff extends ApiDiffBase {
+    kind: ApiClassField["kind"];
+}
+export interface ApiClassMethodDiff extends ApiDiffBase {
+    kind: ApiClassMethod["kind"];
+}
+export interface ApiFunctionDeclarationDiff extends ApiDiffBase {
+    kind: ApiFunctionDeclaration["kind"];
+}
+export interface ApiVariableDeclarationDiff extends ApiDiffBase {
+    kind: ApiVariableDeclaration["kind"];
+}

package/dist/diff.js

@@ -0,0 +1,147 @@
+async function b(d, i) {
+  const o = await fetch(`https://unpkg.com/${d}@${i}/dist/docs/api.json`);
+  if (!o.ok)
+    throw new Error(`Failed to fetch api.json: ${o.statusText}`);
+  return await o.json();
+}
+function M(d, i) {
+  const o = new Map(d.modules.map((e) => [e.path, e])), t = [];
+  for (const e of i.modules) {
+    const a = o.get(e.path), s = D(a, e, !0);
+    s !== void 0 && t.push(s), o.delete(e.path);
+  }
+  for (const e of o.values()) {
+    const a = D(void 0, e, !1);
+    a !== void 0 && t.push(a);
+  }
+  return { modules: t };
+}
+function D(d, i, o) {
+  const t = [], e = p(d?.declarations ?? []), a = p(i.declarations ?? []);
+  for (const s of a.values()) {
+    const n = s.at(-1), l = "tagName" in n ? n.tagName : void 0, v = l ?? n.name, u = e.get(v);
+    e.delete(v);
+    const h = u === void 0 && !o ? !0 : void 0, m = o && // Only mark as deprecated if all overloads are deprecated
+    (s.length === 1 || s.every((r) => r.deprecated !== void 0)) ? n.deprecated : void 0, g = !m && u === void 0 && o ? !0 : void 0;
+    if (h || g) {
+      t.push({
+        kind: n.kind,
+        name: n.name,
+        tagName: l,
+        members: void 0,
+        removed: h,
+        added: g,
+        deprecated: m
+      });
+      continue;
+    } else if (!o)
+      continue;
+    if ("tagName" in n) {
+      const r = u?.[0], c = {
+        kind: n.kind,
+        name: n.name,
+        tagName: n.tagName,
+        deprecated: m,
+        added: void 0,
+        removed: void 0,
+        members: k(r?.members, n.members),
+        events: f(r?.events, n.events),
+        slots: f(r?.slots, n.slots),
+        cssParts: f(r?.cssParts, n.cssParts),
+        cssProperties: f(r?.cssProperties, n.cssProperties),
+        cssStates: f(r?.cssStates, n.cssStates)
+      };
+      (m !== void 0 || c.members !== void 0 || c.events !== void 0 || c.slots !== void 0 || c.cssParts !== void 0 || c.cssProperties !== void 0 || c.cssStates !== void 0) && t.push(c);
+    } else if (n.kind === "class") {
+      const r = u?.[0], c = {
+        kind: n.kind,
+        name: n.name,
+        deprecated: m,
+        added: void 0,
+        removed: void 0,
+        members: k(r?.members, n.members),
+        events: f(r?.events, n.events)
+      };
+      (m !== void 0 || c.members !== void 0 || c.events !== void 0) && t.push(c);
+    } else m !== void 0 && t.push({
+      kind: n.kind,
+      name: n.name,
+      deprecated: m,
+      added: void 0,
+      removed: void 0
+    });
+  }
+  if (o)
+    for (const [s] of e.values())
+      t.push({
+        kind: s.kind,
+        name: s.name,
+        tagName: "tagName" in s ? s.tagName : void 0,
+        members: void 0,
+        removed: !0,
+        added: void 0,
+        deprecated: void 0
+      });
+  if (t.length !== 0)
+    return {
+      path: i.path,
+      declarations: t
+    };
+}
+function p(d) {
+  const i = /* @__PURE__ */ new Map();
+  for (let o = 0; o < d.length; o++) {
+    const t = d[o], e = "tagName" in t ? t.tagName : t.name, a = i.get(e);
+    a === void 0 ? i.set(e, [t]) : a.push(t);
+  }
+  return i;
+}
+function f(d, i) {
+  const o = p(d ?? []), t = [];
+  if (i !== void 0)
+    for (const e of i)
+      o.get(e.name) === void 0 ? t.push({
+        name: e.name,
+        added: !0
+      }) : e.deprecated && t.push({
+        name: e.name,
+        deprecated: e.deprecated
+      }), o.delete(e.name);
+  for (const [e] of o.values())
+    t.push({
+      name: e.name,
+      removed: !0
+    });
+  return t.length ? t : void 0;
+}
+function k(d, i) {
+  const o = p(d ?? []), t = p(i ?? []), e = [];
+  for (const a of t.values()) {
+    const s = a.at(-1), n = o.get(s.name);
+    o.delete(s.name);
+    const l = (
+      // Only mark as deprecated if all overloads are deprecated
+      a.length === 1 || a.every((v) => v.deprecated !== void 0) ? s.deprecated : void 0
+    );
+    l ? e.push({
+      kind: s.kind,
+      name: s.name,
+      deprecated: l
+    }) : n === void 0 && e.push({
+      kind: s.kind,
+      name: s.name,
+      added: !0
+    });
+  }
+  for (const [a] of o.values())
+    e.push({
+      kind: a.kind,
+      name: a.name,
+      removed: !0
+    });
+  return e.length ? e : void 0;
+}
+export {
+  M as diffApiJson,
+  b as fetchApiJsonFromNpm
+};

package/dist/index.js

@@ -2,7 +2,7 @@ import c from "typescript";
 import { path as y } from "@arcgis/components-build-utils";
 import T, { supportsColorStderr as S } from "chalk";
 import { mappedFind as D } from "@arcgis/toolkit/array";
-const m = "@arcgis/api-extractor", E = "5.0.0-next.8", H = (t) => t.kind === "method", q = (t) => t.kind === "field";
+const m = "@arcgis/api-extractor", E = "5.0.0-next.9", H = (t) => t.kind === "method", q = (t) => t.kind === "field";
 function k(t, e) {
   const s = t.path.split("/"), n = s.pop(), o = s.join("/"), i = e.path.split("/"), r = i.pop(), a = i.join("/");
   return o === a ? n < r ? -1 : 1 : o.startsWith(a) ? 1 : a.startsWith(o) || o < a ? -1 : 1;

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@arcgis/api-extractor",
-  "version": "5.0.0-next.8",
+  "version": "5.0.0-next.9",
   "type": "module",
   "main": "dist/index.cjs",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
     ".": "./dist/index.js",
+    "./diff": "./dist/diff/index.js",
     "./package.json": "./package.json"
   },
   "files": [
@@ -14,8 +15,8 @@
   ],
   "license": "SEE LICENSE IN LICENSE.md",
   "dependencies": {
-    "@arcgis/components-build-utils": "5.0.0-next.8",
-    "@arcgis/toolkit": "5.0.0-next.8",
+    "@arcgis/components-build-utils": "5.0.0-next.9",
+    "@arcgis/toolkit": "5.0.0-next.9",
     "chalk": "^5.4.1",
     "tslib": "^2.8.1",
     "typescript": "~5.8.3"