@arcgis/api-extractor 5.0.0-next.98 → 5.0.0

package/dist/diff/types.d.ts

@@ -1,83 +1,98 @@
-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. If declaration
+   * was removed, but was deprecated in the old api.json, this will show the old
+   * deprecation message as it points at the replacement API.
+   * 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

package/dist/extractor/ApiExtractor.d.ts

@@ -1,139 +1,66 @@
-import { ApiClassMethod, ApiClassDeclaration, ApiCustomElementField, ApiDeclaration, ApiEvent, ApiJson, ApiModule, ApiCustomElementDeclaration, ApiFunctionDeclaration, ApiVariableDeclaration, ApiInterfaceDeclaration, ApiObjectLikeDeclaration, ApiCustomElementMember, ApiReference, ApiClassMember, ApiAttribute, ApiSlot, ApiCssPart, ApiCssCustomProperty, ApiCssCustomState, ApiMixinDeclaration, ApiClassField, ApiReferenceWithTypeArguments } from '../apiJson.ts';
-import { default as ts } from 'typescript';
-import { CopyDocDefinitions } from '../types.ts';
-export type ApiExtractorOptions = {
-    sortModules: boolean;
-    /** The path relative to which module.path will be resolved */
-    cwd: string;
-    environment: "development" | "production";
-};
+import type ts from "typescript";
+import type { ApiExtractorConfig, ResolvedApiExtractorConfig } from "./config.js";
+import type { ApiExtractorResult, ApiExtractorWatcher } from "./types.js";
+
 /**
- * This is a base abstract class. It should be subclassed to implement the
- * specific extraction logic.
+ * 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 declare abstract class ApiExtractor {
-    constructor(options: ApiExtractorOptions);
-    options: ApiExtractorOptions;
-    /** File that is currently being extracted */
-    file: ts.SourceFile;
-    /** The module that is currently being produced */
-    apiModule: ApiModule;
-    /** Given an array of TypeScript source files, generate an api.json file */
-    extract(files: readonly ts.SourceFile[]): ApiJson;
-    /**
-     * Hostname of the documentation site for the current environment.
-     */
-    normalizedDocumentationHost: string;
-    /**
-     * Hostname of the documentation site that is not for the current environment.
-     * These references will be replaced by the extractor to point to the
-     * normalizedDocumentationHost instead.
-     *
-     * Use case:
-     * - In source code, link to internal docs only. This gives more up to date
-     *   docs and avoids 404 errors for pages that are not yet part of public
-     *   release.
-     * - In production builds, the URLs are replaced with the public docs hostname.
-     */
-    alternativeDocumentationHost: string;
-    extractModules(files: readonly ts.SourceFile[]): ApiModule[];
-    /**
-     * @param module
-     * @param sourcePath cwd-relative path to the source file (esri/core/Accessor.ts)
-     * @param importPath public import path of the module without package name or file extension (core/Accessor)
-     */
-    extractModule(module: ts.SourceFile, sourcePath?: string, importPath?: string): ApiModule;
-    /**
-     * For a given module, extract all public declarations.
-     */
-    protected extractDeclarations(module: ts.SourceFile): void;
-    /**
-     * For each statement in a module, extract a declaration if it is a public API
-     */
-    protected abstract extractDeclaration(statement: ts.Statement, index: number): ApiDeclaration | undefined;
-    /**
-     * Add ApiModule.exports entry based on ApiDeclaration
-     *
-     * To reduce the size of the api.json, we only add exports entries for web
-     * components or default exports.
-     */
-    addExport(declaration: ApiDeclaration, isDefault: boolean): void;
-    copyDoc(errorReportingNode: ts.Node, copyDocDefinitions: CopyDocDefinitions["properties"], apiProperty: ApiCustomElementField, apiComponent: ApiObjectLikeDeclaration, apiModule: ApiModule): void;
-    copyDoc(errorReportingNode: ts.Node, copyDocDefinitions: CopyDocDefinitions["methods"], method: ApiClassMethod, component: ApiObjectLikeDeclaration, apiModule: ApiModule): void;
-    copyDoc(errorReportingNode: ts.Node, copyDocDefinitions: CopyDocDefinitions["events"], event: ApiEvent, component: ApiObjectLikeDeclaration, apiModule: ApiModule): void;
-    copyDoc(errorReportingNode: ts.Node, copyDocDefinitions: CopyDocDefinitions["functions"], apiFunction: ApiFunctionDeclaration, apiModule: ApiModule): void;
-    copyDoc(errorReportingNode: ts.Node, copyDocDefinitions: CopyDocDefinitions["variables"], variable: ApiVariableDeclaration, apiModule: ApiModule): void;
-    copyDoc(errorReportingNode: ts.Node, copyDocDefinitions: CopyDocDefinitions["classes"], classDeclaration: ApiClassDeclaration, apiModule: ApiModule): void;
-    copyDoc(errorReportingNode: ts.Node, copyDocDefinitions: CopyDocDefinitions["customElements"], componentDeclaration: ApiCustomElementDeclaration, apiModule: ApiModule): void;
-    copyDoc(errorReportingNode: ts.Node, copyDocDefinitions: CopyDocDefinitions["interfaces"], interfaceDeclaration: ApiInterfaceDeclaration, apiModule: ApiModule): void;
-    /**
-     * Inherit public members from mixins and superclass.
-     *
-     * In cast of Lumina, for this to work, the superclass needs to be in a file
-     * named like a component (src/components/name/name.tsx), even if it is not a
-     * standalone component. See
-     * https://devtopia.esri.com/WebGIS/arcgis-web-components/issues/3212
-     */
-    inheritMembers(moduleName: string, component: ApiClassDeclaration | ApiMixinDeclaration, modules: ApiModule[]): void;
-    /**
-     * Inherit members from a superclass or mixin.
-     */
-    protected inheritMembersFrom(parent: ApiExtractorInheritanceData, destination: ApiClassDeclaration | ApiMixinDeclaration, eventsWereExplicitlyInherited: boolean): void;
-    protected inheritMembersOfKind<T extends ApiAttribute | ApiCssCustomProperty | ApiCssCustomState | ApiCssPart | ApiEvent | ApiSlot>(members: T[] | undefined, parentMembers: T[], parentIndexedMembers: Record<string, T>, inheritedFrom?: ApiReference): T[];
-    resolvedInheritance: Record<string, 
-    /**
-     * `false` means don't inherit (or resolution failed).
-     *
-     * `undefined` means we already inherited the members, but have not yet
-     * computed the inheritance data for this module (almost every class
-     * inherits some class, but only a few are inherited by other classes, so
-     * we compute inheritance data lazily).
-     */
-    ApiExtractorInheritanceData | false | undefined>;
-    noInheritMembers: Readonly<Record<string, readonly string[]>>;
-    /**
-     * Based on the superclass name, find the actual declaration in the modules.
-     */
-    protected resolveInheritance(superClassModule: string, modules: ApiModule[], isMixin: boolean): ApiExtractorInheritanceData | false;
-    /**
-     * Overwrite point
-     *
-     * FINAL: jsapi-extractor has a more efficient implementation because it
-     * has to deal with inheritance a lot. Unify it with Lumina.
-     */
-    protected findSuperclassDeclaration(moduleName: string, modules: ApiModule[], _isMixin: boolean): readonly [string, ApiClassDeclaration | ApiMixinDeclaration] | false;
-    protected handleEventTypesProperty(_apiMember: ApiClassMember, _apiComponent: ApiClassDeclaration | ApiMixinDeclaration, _moduleName: string): void;
-    protected resolvePropertyAutoCastingType(_apiMember: ApiClassMember, _moduleName: string): void;
-    /**
-     * This method should check if the super property is an accessor, then the
-     * override property should be promoted to an accessor too.
-     * This is necessary until we migrate to standard decorators since - after
-     * that internal accessor status will match the status in the public typings.
-     */
-    protected maybePromotePropertyToAutoAccessor(_apiProperty: ApiClassField, _superApiProperty: ApiClassField): void;
-    protected maybeResolveMixinBaseClass(_apiReference: ApiReferenceWithTypeArguments, _currentModule: string): ApiInterfaceDeclaration | undefined;
-}
-type ApiExtractorInheritanceData = {
-    inheritanceData: ApiReference;
-    declaration: ApiClassDeclaration | ApiMixinDeclaration;
-    /**
-     * Used for validation only. If class has any settable fields, and class is
-     * extended by another one, require that the class module exports the
-     * `<className>Properties` interface. It will be extended by the superclass'
-     * properties interface.
-     */
-    hasSettableField: boolean;
-    /**
-     * Indexed by name for quick lookup of "overridden" status.
-     * Using a map because we do .get() during constructor of the Map, and because
-     * there are often 10+ items with random access.
-     */
-    indexedMembers: Map<string, ApiClassMember | ApiCustomElementMember | undefined> | undefined;
-    indexedEvents: Record<string, ApiEvent> | undefined;
-    indexedAttributes: Record<string, ApiAttribute> | undefined;
-    indexedSlots: Record<string, ApiSlot> | undefined;
-    indexedCssParts: Record<string, ApiCssPart> | undefined;
-    indexedCssProperties: Record<string, ApiCssCustomProperty> | undefined;
-    indexedCssStates: Record<string, ApiCssCustomState> | undefined;
-};
-export {};
+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;
+  /**
+   * 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-Dsim-EQC.js";
+import "../worker-1ouniZM0.js";
+import "./processing/links.js";
+import "typescript";
+import { A as x } from "../ApiExtractor-DIxlsiLk.js";
+import "@arcgis/toolkit/function";
+export {
+  x as ApiExtractor
+};