@arcgis/api-extractor 5.0.0-next.136 → 5.0.0-next.137

package/dist/cli.js

@@ -1,7 +1,31 @@
 #!/usr/bin/env node
-import { Command as i } from "@commander-js/extra-typings";
-const e = new i();
+import { Command as p } from "@commander-js/extra-typings";
+const e = new p();
 e.name("api-extractor").description("Extract public API from a TypeScript project to produce .d.ts types and api.json docs");
+e.command("run").description("Generate .d.ts types and api.json API reference for a project").option("--cwd <arcgis-js-api>", "Path to the root of the project (default: process.cwd())").option("--dts <outputDirectory>", "Destination for the .d.ts files (example: dist/)").option("--api-json <outputLocation>", "Destination for the api.json file (example: dist/docs/api.json)").option("--environment <environment>", "Environment to run in (production or development) (default: production)").option("--type-check", "Run full type checking before the extraction (default: false)").option("--verify", "Run type checker on the emitted types (default: false)").option("--watch", "Watch for file changes and re-run the extraction automatically", !1).option(
+  "--config <configPath>",
+  "Path to the ./api-extractor.config.ts file. The provided path will be used as is in import(). The config file should export a `config` object of type ApiExtractorConfig (default: api-extractor.config.ts in the cwd)"
+).option(
+  "--silence-broken-links",
+  "(deprecated) Do not emit errors for broken @links in JSDoc comments. Temporary option for migration period (default: false)"
+).action(async (t) => {
+  const { loadApiExtractorConfig: o, mergeApiExtractorConfigs: n } = await import("./extractor/config.js"), a = await o(t.cwd, t.config), r = n(a, {
+    context: {
+      dtsEmitPath: t.dts,
+      apiJsonEmitPath: t.apiJson,
+      environment: t.environment === "development" ? "development" : void 0,
+      cwd: t.cwd
+    },
+    types: {
+      fullTypeCheck: t.typeCheck
+    },
+    verify: {
+      typeCheckTypes: t.verify,
+      detectBrokenLinks: t.silenceBrokenLinks === !0 ? !1 : void 0
+    }
+  }), { ApiExtractor: c } = await import("./extractor/ApiExtractor.js"), i = new c(r);
+  t.watch ? await i.watch() : await i.run();
+});
 e.command("diff-types").description("Generate a types diff summary .md file").requiredOption("--original-dts <originalTypings>", "Path to the original types folder").requiredOption("--new-dts <newTypings>", "Path to the new types folder").option("--output-md <outputMd>", "Path to the output markdown file", "types-diff.md").option("--no-truncate", "Do not truncate output if it is longer than 1000 lines", !0).action(async (t) => {
   const { diffTypes: o } = await import("./diffTypes/index.js");
   await o({

package/dist/compilerHints.d.ts

@@ -0,0 +1,62 @@
+/**
+ * We try to keep public and private types close to keep the API more
+ * maintainable. However, occasionally we must diverge to hide some private
+ * details from the public API.
+ *
+ * Use this type helper when public TypeScript type must diverge from the
+ * private type.
+ *
+ * @example
+ * ```ts
+ * type ActionType = PublicApiNarrowType<
+ *   "create" | "update" | "delete",
+ *   "create" | "delete"
+ * >;
+ * ```
+ *
+ * In private types, the 1st type parameter will be used for type checking,
+ * making the effective type `"create" | "update" | "delete"`.
+ *
+ * But in public `.d.ts` and public docs, the above will appear like this:
+ *
+ * ```ts
+ * type ActionType = "create" | "delete";
+ * ```
+ *
+ * Remember that properties without `public` tag are not publicly exposed.
+ * Thus, in practice, `PublicApiNarrowType` is most commonly needed to hide
+ * private union members.
+ *
+ * To ensure public type does not get out of date, `PublicApiNarrowType`
+ * requires that the public type extends the private type (or in other words, a
+ * subset of the private type). If that restriction is too tight, use
+ * `PublicApiRelaxType` instead.
+ */
+export type PublicApiNarrowType<PrivateType, _PublicType extends PrivateType> = PrivateType;
+
+/**
+ * Most of the time, when the public type must diverge from the private type,
+ * the public type is a subset of the private type - in such cases use
+ * `PublicApiNarrowType`.
+ *
+ * Occasionally, the public type may need to be a superset of the private type
+ * or even an unrelated type. For those cases, use `PublicApiRelaxType`.
+ *
+ * Keep usages of `PublicApiRelaxType` at minimum as it disables type
+ * checking between public and private types.
+ *
+ * @example
+ * ```ts
+ * type EditableLayers = FeatureLayer | ...;
+ * class MyClass {
+ *   // Layer is a superset of EditableLayers, not subset,
+ *   // so we must use PublicApiRelaxType.
+ *   layer: PublicApiRelaxType<EditableLayers, Layer>;
+ *
+ *   // StrictNumberType is a branded type that is incompatible
+ *   // with regular number type.
+ *   jobId: PublicApiRelaxType<StrictNumberType<"JobId">, number>;
+ * }
+ * ```
+ */
+export type PublicApiRelaxType<PrivateType, _PublicType> = PrivateType;

package/dist/diff/diffApiJson.d.ts

@@ -1,6 +1,9 @@
-import { ApiJson } from '../apiJson.ts';
-import { ApiDiff } from './types.ts';
+import type { ApiJson } from "../apiJson.js";
+import type { ApiDiff } from "./types.js";
+
 /**
+ * @param oldApiJson
+ * @param newApiJson
  * @example
  * ```js
  * import { diffApiJson, fetchApiJsonFromNpm } from "@arcgis/api-extractor/diff";
@@ -20,4 +23,4 @@ import { ApiDiff } from './types.ts';
  * writeFileSync("api-diff.json", JSON.stringify(diff, null, 2));
  * ```
  */
-export declare function diffApiJson(oldApiJson: Pick<ApiJson, "modules">, newApiJson: Pick<ApiJson, "modules">): ApiDiff;
+export function diffApiJson(oldApiJson: Pick<ApiJson, "modules">, newApiJson: Pick<ApiJson, "modules">): ApiDiff;

package/dist/diff/diffApiJson.js

@@ -0,0 +1,142 @@
+function M(r, a) {
+  const n = new Map(r.modules.map((e) => [e.path, e])), t = [];
+  for (const e of a.modules) {
+    const s = n.get(e.path), i = k(s, e, !0);
+    i !== void 0 && t.push(i), n.delete(e.path);
+  }
+  for (const e of n.values()) {
+    const s = k(void 0, e, !1);
+    s !== void 0 && t.push(s);
+  }
+  return { modules: t };
+}
+function k(r, a, n) {
+  const t = [], e = h(r?.declarations ?? []), s = h(a.declarations ?? []);
+  for (const i of s.values()) {
+    const o = i.at(-1), p = o.tagName, u = p ?? o.name, f = e.get(u);
+    e.delete(u);
+    const g = f === void 0 && !n ? !0 : void 0, m = n && // Only mark as deprecated if all overloads are deprecated
+    (i.length === 1 || i.every((d) => d.deprecated !== void 0)) ? o.deprecated : void 0, D = !m && f === void 0 && n ? !0 : void 0;
+    if (g || D) {
+      t.push({
+        kind: o.kind,
+        name: o.name,
+        tagName: p,
+        members: void 0,
+        removed: g,
+        added: D,
+        deprecated: m
+      });
+      continue;
+    } else if (!n)
+      continue;
+    if (p !== void 0) {
+      const d = o, c = f?.[0], l = {
+        kind: d.kind,
+        name: d.name,
+        tagName: d.tagName,
+        deprecated: m,
+        added: void 0,
+        removed: void 0,
+        members: b(c?.members, d.members),
+        events: v(c?.events, d.events),
+        slots: v(c?.slots, d.slots),
+        cssParts: v(c?.cssParts, d.cssParts),
+        cssProperties: v(c?.cssProperties, d.cssProperties),
+        cssStates: v(c?.cssStates, d.cssStates)
+      };
+      (m !== void 0 || l.members !== void 0 || l.events !== void 0 || l.slots !== void 0 || l.cssParts !== void 0 || l.cssProperties !== void 0 || l.cssStates !== void 0) && t.push(l);
+    } else if (o.kind === "class" || o.kind === "interface" || o.kind === "mixin") {
+      const d = f?.[0], c = {
+        kind: o.kind,
+        name: o.name,
+        deprecated: m,
+        added: void 0,
+        removed: void 0,
+        members: b(d?.members, o.members),
+        events: "events" in o ? v(d?.events, o.events) : void 0
+      };
+      (m !== void 0 || c.members !== void 0 || c.events !== void 0) && t.push(c);
+    } else m !== void 0 && t.push({
+      kind: o.kind,
+      name: o.name,
+      deprecated: m,
+      added: void 0,
+      removed: void 0
+    });
+  }
+  if (n)
+    for (const [i] of e.values())
+      t.push({
+        kind: i.kind,
+        name: i.name,
+        tagName: i.tagName,
+        members: void 0,
+        removed: !0,
+        added: void 0,
+        deprecated: void 0
+      });
+  if (t.length !== 0)
+    return {
+      path: a.path,
+      declarations: t
+    };
+}
+function h(r) {
+  const a = /* @__PURE__ */ new Map();
+  for (let n = 0; n < r.length; ++n) {
+    const t = r[n], e = t.tagName ?? t.name ?? t.kind, s = a.get(e);
+    s === void 0 ? a.set(e, [t]) : s.push(t);
+  }
+  return a;
+}
+function v(r, a) {
+  const n = h(r ?? []), t = [];
+  if (a !== void 0)
+    for (const e of a)
+      n.get(e.name) === void 0 ? t.push({
+        name: e.name,
+        added: !0
+      }) : e.deprecated && t.push({
+        name: e.name,
+        deprecated: e.deprecated
+      }), n.delete(e.name);
+  for (const [e] of n.values())
+    t.push({
+      name: e.name,
+      removed: !0
+    });
+  return t.length ? t : void 0;
+}
+function b(r, a) {
+  const n = h(r ?? []), t = h(a ?? []), e = [];
+  for (const [s, i] of t.entries()) {
+    const o = i.at(-1), p = n.get(s);
+    n.delete(s);
+    const u = (
+      // Only mark as deprecated if all overloads are deprecated
+      i.length === 1 || i.every((g) => g.deprecated !== void 0) ? o.deprecated : void 0
+    ), f = s === "constructor" || s === "call-signature" ? void 0 : s;
+    u ? e.push({
+      kind: o.kind,
+      name: f,
+      deprecated: u
+    }) : p === void 0 && e.push({
+      kind: o.kind,
+      name: f,
+      added: !0
+    });
+  }
+  for (const [s, [i]] of n.entries()) {
+    const o = s === "constructor" || s === "call-signature" ? void 0 : s;
+    e.push({
+      kind: i.kind,
+      name: o,
+      removed: !0
+    });
+  }
+  return e.length ? e : void 0;
+}
+export {
+  M as diffApiJson
+};

package/dist/diff/fetchApiJsonFromNpm.d.ts

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

package/dist/diff/fetchApiJsonFromNpm.js

@@ -0,0 +1,9 @@
+async function a(t, s) {
+  const o = await fetch(`https://unpkg.com/${t}@${s}/dist/docs/api.json`);
+  if (!o.ok)
+    throw new Error(`Failed to fetch api.json: ${o.statusText}`);
+  return await o.json();
+}
+export {
+  a as fetchApiJsonFromNpm
+};

package/dist/diff/types.d.ts

@@ -1,83 +1,97 @@
-import { ApiClassCallSignature, ApiClassConstructor, ApiClassDeclaration, ApiClassField, ApiClassMethod, ApiCustomElementDeclaration, ApiFunctionDeclaration, ApiInterfaceDeclaration, ApiMixinDeclaration, ApiModule, ApiVariableDeclaration } from '../apiJson.ts';
+import type { ApiClassCallSignature, ApiClassConstructor, ApiClassDeclaration, ApiClassField, ApiClassMethod, ApiCustomElementDeclaration, ApiFunctionDeclaration, ApiInterfaceDeclaration, ApiMixinDeclaration, ApiModule, ApiVariableDeclaration } from "../apiJson.js";
+
 export interface ApiDiff {
-    modules: ApiModuleDiff[];
+  modules: ApiModuleDiff[];
 }
+
 export interface ApiModuleDiff {
-    path: ApiModule["path"];
-    declarations: ApiDeclarationDiff[];
+  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;
+  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 | ApiInterfaceDeclarationDiff | ApiMixinDeclarationDiff | 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[];
+  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 ApiInterfaceDeclarationDiff extends ApiDiffBase {
-    kind: ApiInterfaceDeclaration["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[];
+  kind: ApiInterfaceDeclaration["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[];
 }
+
 export interface ApiMixinDeclarationDiff extends Omit<ApiClassDeclarationDiff, "kind"> {
-    kind: ApiMixinDeclaration["kind"];
+  kind: ApiMixinDeclaration["kind"];
 }
+
 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[];
+  /** 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 = ApiClassCallSignatureDiff | ApiClassConstructorDiff | ApiClassFieldDiff | ApiClassMethodDiff;
+
 export interface ApiClassFieldDiff extends ApiDiffBase {
-    kind: ApiClassField["kind"];
+  kind: ApiClassField["kind"];
 }
+
 export interface ApiClassMethodDiff extends ApiDiffBase {
-    kind: ApiClassMethod["kind"];
+  kind: ApiClassMethod["kind"];
 }
+
 export interface ApiClassConstructorDiff extends Omit<ApiDiffBase, "name"> {
-    kind: ApiClassConstructor["kind"];
+  kind: ApiClassConstructor["kind"];
 }
+
 export interface ApiClassCallSignatureDiff extends Omit<ApiDiffBase, "name"> {
-    kind: ApiClassCallSignature["kind"];
+  kind: ApiClassCallSignature["kind"];
 }
+
 export interface ApiFunctionDeclarationDiff extends ApiDiffBase {
-    kind: ApiFunctionDeclaration["kind"];
+  kind: ApiFunctionDeclaration["kind"];
 }
+
 export interface ApiVariableDeclarationDiff extends ApiDiffBase {
-    kind: ApiVariableDeclaration["kind"];
-}
+  kind: ApiVariableDeclaration["kind"];
+}

package/dist/diffTypes/index.d.ts

@@ -1,24 +1,21 @@
-interface DiffTypesOptions {
-    /**
-     * Path to the original types folder.
-     */
-    originalDtsPath: string;
-    /**
-     * Path to the new types folder.
-     */
-    newDtsPath: string;
-    /**
-     * Path to the output markdown file.
-     *
-     * @default "types-diff.md"
-     */
-    outputMdPath: string;
-    /**
-     * Whether to truncate output if the diff is longer than 1000 lines.
-     *
-     * @default true
-     */
-    truncate?: boolean;
+export interface DiffTypesOptions {
+  /** Path to the original types folder. */
+  originalDtsPath: string;
+  /** Path to the new types folder. */
+  newDtsPath: string;
+  /**
+   * Path to the output markdown file.
+   *
+   * @default "types-diff.md"
+   */
+  outputMdPath: string;
+  /**
+   * Whether to truncate output if the diff is longer than 1000 lines.
+   *
+   * @default true
+   */
+  truncate?: boolean;
 }
-export declare function diffTypes({ originalDtsPath, newDtsPath, outputMdPath, truncate, }: DiffTypesOptions): Promise<void>;
-export {};
+
+/** @param options */
+export function diffTypes(options: DiffTypesOptions): Promise<void>;

package/dist/diffTypes/index.js

@@ -21,7 +21,9 @@ async function b({
 
 🧐 please verify that the changes to the public API/doc below are intentional.
 🟥 If removing/changing APIs, remember the semver promise.
-🟩 If adding APIs, add to release notes.`;
+🟩 If adding APIs, add to release notes.
+
+`;
     let f = g(r.split(`
 `), n);
     i && f.length > l && (o += `> [!WARNING]
@@ -34,7 +36,7 @@ async function b({
   await m(s.dirname(e), { recursive: !0 }), await d(e, o);
 }
 function g(t, n) {
-  for (let e = 0; e < t.length; e++) {
+  for (let e = 0; e < t.length; ++e) {
     const i = t[e];
     if (
       // Make diff smaller by excluding the `diff ...` lines