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

package/dist/extractor/ApiExtractor.d.ts

@@ -1,139 +1,74 @@
-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 { ApiModule } from "../apiJson.js";
+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;
+  /** @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-9f8GK91w.js";
+import { A as x } from "../ApiExtractor-DXDxS3Cb.js";
+import "../worker-DuJtWFW5.js";
+import "./processing/links.js";
+import "typescript";
+import "@arcgis/toolkit/function";
+export {
+  x as ApiExtractor
+};