@arcgis/api-extractor 5.0.0-next.14 → 5.0.0-next.141

package/dist/cli.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+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({
+    originalDtsPath: t.originalDts,
+    newDtsPath: t.newDts,
+    outputMdPath: t.outputMd,
+    truncate: t.truncate
+  });
+});
+e.parse();

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,3 +1,26 @@
-import { ApiJson } from '../apiJson';
-import { ApiDiff } from './types';
-export declare function diffApiJson(oldApiJson: Pick<ApiJson, "modules">, newApiJson: Pick<ApiJson, "modules">): ApiDiff;
+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";
+ * import { readFileSync, writeFileSync } from "node:fs";
+ *
+ * // Read -next api.json from file system:
+ * const apiJson = JSON.parse(
+ * readFileSync("packages/map-packages/map-components/dist/docs/api.json", "utf8"),
+ * );
+ * // Read -latest api.json from NPM
+ * const npmApiJson = await fetchApiJsonFromNpm("@arcgis/map-components", "latest");
+ *
+ * // Compute diff
+ * const diff = diffApiJson(npmApiJson, apiJson);
+ *
+ * // Do something with the diff
+ * writeFileSync("api-diff.json", JSON.stringify(diff, null, 2));
+ * ```
+ */
+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';
+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,66 +1,97 @@
-import { ApiClassDeclaration, ApiClassField, ApiClassMethod, ApiCustomElementDeclaration, ApiFunctionDeclaration, ApiModule, ApiVariableDeclaration } from '../apiJson';
+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 | ApiVariableDeclarationDiff;
+
+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[];
+}
+
+export interface ApiMixinDeclarationDiff extends Omit<ApiClassDeclarationDiff, "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 = ApiClassFieldDiff | ApiClassMethodDiff;
+
+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"];
 }
+
+export interface ApiClassCallSignatureDiff extends Omit<ApiDiffBase, "name"> {
+  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

@@ -0,0 +1,21 @@
+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;
+}
+
+/** @param options */
+export function diffTypes(options: DiffTypesOptions): Promise<void>;

package/dist/diffTypes/index.js

@@ -0,0 +1,71 @@
+import { path as s } from "@arcgis/components-build-utils";
+import { execSync as c } from "node:child_process";
+import { mkdir as m, writeFile as d } from "node:fs/promises";
+const a = "diff --new-file --recursive", u = `${a} --unified=2`;
+async function b({
+  originalDtsPath: t,
+  newDtsPath: n,
+  outputMdPath: e = "types-diff.md",
+  truncate: i = !0
+}) {
+  n = s.join(s.resolve(n), "/");
+  const r = c(`${u} ${t} ${n} || true`, {
+    encoding: "utf8",
+    maxBuffer: 1024 * 1024 * 20
+  }).trim();
+  let o = "";
+  if (r.length === 0)
+    console.log("Public types did not change.");
+  else {
+    o = `### Public types changes
+
+🧐 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.
+
+`;
+    let f = g(r.split(`
+`), n);
+    i && f.length > l && (o += `> [!WARNING]
+> Too many changes. Only displaying the first ${l} lines (total ${f.length}) of the diff. If you need to see complete diff, re-run this command with --no-truncate.
+
+`, f = f.slice(0, l)), o += `${h(f)}
+
+`, console.log(`Wrote diff to ${e}`);
+  }
+  await m(s.dirname(e), { recursive: !0 }), await d(e, o);
+}
+function g(t, n) {
+  for (let e = 0; e < t.length; ++e) {
+    const i = t[e];
+    if (
+      // Make diff smaller by excluding the `diff ...` lines
+      (i.startsWith(a) || // Redundant line - make file header smaller
+      i.startsWith("---") || // Not important
+      i === "\") && (t.splice(e, 1), e--), i.startsWith("+++")
+    ) {
+      const r = i.indexOf("	");
+      let o = i.slice(4, r === -1 ? i.length : r);
+      o.startsWith(n) && (o = o.slice(n.length)), t[e] = `🟦 ${o}`;
+    }
+  }
+  return t;
+}
+const l = 1e3;
+function h(t) {
+  const n = t.length, e = p(t.join(`
+`));
+  return n <= 10 ? e : `<details><summary>See diff</summary>
+
+${e}
+
+</details>`;
+}
+function p(t) {
+  return `\`\`\`diff
+${t}
+\`\`\``;
+}
+export {
+  b as diffTypes
+};

package/dist/extractor/ApiExtractor.d.ts

@@ -0,0 +1,74 @@
+import type ts from "typescript";
+import type { ApiModule } from "../apiJson.js";
+import type { ApiExtractorConfig, ResolvedApiExtractorConfig } from "./config.js";
+import type { ApiExtractorResult, ApiExtractorWatcher } from "./types.js";
+
+/**
+ * ApiExtractor's main JavaScript entrypoint.
+ *
+ * @example
+ * ```js
+ *
+ *  import { loadApiExtractorConfig, mergeApiExtractorConfigs } from "@arcgis/api-extractor/extractor/config";
+ *  import { ApiExtractor } from "@arcgis/api-extractor/extractor/ApiExtractor";
+ *
+ *  const baseConfig = await loadApiExtractorConfig(process.cwd(), "api-extractor.config.ts");
+ *
+ *  // Optionally override parts of the config
+ *  const mergedConfig = mergeApiExtractorConfigs(baseConfig, {
+ *    types: {
+ *      fullTypeCheck: true,
+ *    },
+ *  });
+ *
+ *  const extractor = new ApiExtractor(mergedConfig);
+ *
+ *  const { apiJson, dtsFiles } = await extractor.run();
+ *  // OR, start a watcher:
+ *  const watcher = await extractor.watch();
+ * ```
+ */
+export class ApiExtractor {
+  constructor(rawConfig?: ApiExtractorConfig);
+  readonly config: ResolvedApiExtractorConfig;
+  /**
+   * Number of errors logged during the extraction process.
+   * Errors will be logged using the `config.logger.error` callback if provided.
+   * Otherwise, they will be logged using `console.error`.
+   *
+   * @default 0
+   */
+  errorCount: number;
+  /** @experimental */
+  moduleMap: Map<string, ApiModule>;
+  /**
+   * @experimental
+   * @example "https://developers.arcgis.com/javascript/latest/api-reference/esri-"
+   */
+  readonly normalizedApiReferencePrefix: string;
+  /**
+   * If doing typed extraction or full type check, this will be the ts.Program.
+   * If doing untyped watch, this will be a minimal Program-like object to reuse
+   * SourceFiles for unchanged files.
+   * Otherwise, undefined.
+   */
+  program?: {
+      getSourceFile: ts.Program["getSourceFile"];
+      getSourceFiles: ts.Program["getSourceFiles"];
+      getTypeChecker?: ts.Program["getTypeChecker"];
+  };
+  /**
+   * @deprecated
+   * @default 0
+   */
+  silencedBrokenLinkCount: number;
+  /** The high-level API for running the extractor on the current project. */
+  run(): Promise<ApiExtractorResult>;
+  /**
+   * The high-level API for starting a watch-mode extraction on the current project.
+   * When watching, double check that the configuration options the ApiExtractor
+   * was created with are appropriate for watch mode (disable full type check
+   * and type verifier if not necessary).
+   */
+  watch(): Promise<ApiExtractorWatcher>;
+}

package/dist/extractor/ApiExtractor.js

@@ -0,0 +1,9 @@
+import "../typeScript-soMJqHns.js";
+import { A as x } from "../ApiExtractor-DIfug_xm.js";
+import "../worker-On5v54cw.js";
+import "./processing/links.js";
+import "typescript";
+import "@arcgis/toolkit/function";
+export {
+  x as ApiExtractor
+};