@arcgis/api-extractor 5.0.0-next.58 → 5.0.0-next.59

package/dist/diff/types.d.ts

@@ -1,4 +1,4 @@
-import { ApiClassDeclaration, ApiClassField, ApiClassMethod, ApiCustomElementDeclaration, ApiFunctionDeclaration, ApiModule, ApiVariableDeclaration } from '../apiJson';
+import { ApiClassCallSignature, ApiClassConstructor, ApiClassDeclaration, ApiClassField, ApiClassMethod, ApiCustomElementDeclaration, ApiFunctionDeclaration, ApiInterfaceDeclaration, ApiMixinDeclaration, ApiModule, ApiVariableDeclaration } from '../apiJson';
 export interface ApiDiff {
     modules: ApiModuleDiff[];
 }
@@ -31,7 +31,7 @@ export interface ApiDiffBase {
      */
     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"];
     /**
@@ -41,6 +41,17 @@ export interface ApiClassDeclarationDiff extends ApiDiffBase {
     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.
@@ -51,13 +62,19 @@ export interface ApiCustomElementDeclarationDiff extends ApiClassDeclarationDiff
     cssProperties?: ApiDiffBase[];
     cssStates?: ApiDiffBase[];
 }
-export type ApiClassMemberDiff = ApiClassFieldDiff | ApiClassMethodDiff;
+export type ApiClassMemberDiff = ApiClassCallSignatureDiff | ApiClassConstructorDiff | ApiClassFieldDiff | ApiClassMethodDiff;
 export interface ApiClassFieldDiff extends ApiDiffBase {
     kind: ApiClassField["kind"];
 }
 export interface ApiClassMethodDiff extends ApiDiffBase {
     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"];
 }

package/dist/extractor/ApiExtractor.d.ts

@@ -0,0 +1,137 @@
+import { ApiClassMethod, ApiClassDeclaration, ApiCustomElementField, ApiDeclaration, ApiEvent, ApiJson, ApiModule, ApiCustomElementDeclaration, ApiFunctionDeclaration, ApiVariableDeclaration, ApiInterfaceDeclaration, ApiObjectLikeDeclaration, ApiCustomElementMember, ApiReference, ApiClassMember, ApiAttribute, ApiSlot, ApiCssPart, ApiCssCustomProperty, ApiCssCustomState, ApiMixinDeclaration, ApiClassField } from '../apiJson';
+import { default as ts } from 'typescript';
+import { CopyDocDefinitions } from '../types';
+export type ApiExtractorOptions = {
+    sortModules: boolean;
+    /** The path relative to which module.path will be resolved */
+    cwd: string;
+    environment: "development" | "production";
+};
+/**
+ * This is a base abstract class. It should be subclassed to implement the
+ * specific extraction logic.
+ */
+export declare abstract class ApiExtractor {
+    options: ApiExtractorOptions;
+    constructor(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, destinationModuleName: string): 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: Record<string, string[] | undefined>;
+    /**
+     * Based on the superclass name, find the actual declaration in the modules.
+     */
+    protected resolveInheritance(superClassModule: string, modules: ApiModule[]): 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[]): readonly [string, ApiClassDeclaration | ApiMixinDeclaration] | false;
+    protected handleEventTypesProperty(_apiMember: ApiClassMember, _apiComponent: ApiClassDeclaration | ApiMixinDeclaration, _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;
+}
+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 {};

package/dist/index.d.ts

@@ -1,8 +1,12 @@
-export { ApiExtractor, type ApiExtractorOptions } from './extractor';
 export type * from './apiJson';
-export { hasIgnoredModifier, setDefaultFromInitializer, getMemberName, findDecorator } from './utils/astHelpers';
-export { isApiMethod, isApiProperty, globalPackageIdentifier, multipleJsDocTags } from './utils/apiHelpers';
-export { apiExtractorError, apiExtractorErrorCount, apiExtractorErrorFiles, setApiExtractorErrorLogger, type ApiExtractorErrorContext, } from './utils/error';
-export { debugPrintNode, printNode } from './utils/print';
-export type { CopyDocDefinitions } from './types';
-export { symbolToDocs, apiMemberToSynthesizedComments, setApiDocFromJsDoc } from './utils/docHelpers';
+export { ApiExtractor, type ApiExtractorOptions } from './extractor/ApiExtractor';
+export { unsafeGetUndocumentedPrinter, unsafeUndocumentedTs } from './internalTypeScriptApis';
+export type { CopyDocDefinitions, NodeDoc } from './types';
+export { findReferenceRanges, getApiMemberName, getMaybeStaticApiMemberName, getApiNodeLabel, globalPackageIdentifier, isApiMethod, isApiProperty, multipleJsDocTags, naturalSortModules, postProcessLinks, apiExtractorJsDocError, compareClassMembers, compareNamedNodes, compareStrings, } from './utils/apiHelpers';
+export { extractBooleanInitializer, findDecorator, getMemberName, hasIgnoredModifier, setDefaultFromInitializer, getBasename, } from './utils/astHelpers';
+export { alternativeDocumentationHost, normalizedDocumentationHost } from './utils/jsDocHelpers';
+export { apiMemberToNodeDoc, nodeDocToString, nodeDocToSynthesizedComment } from './utils/jsDocPrinter';
+export { setApiDocFromJsDoc, setApiDocFromSymbol, symbolToDocs, getNodeDoc } from './utils/jsDocParser';
+export { typeScriptGlobals, typeScriptGlobalsViewUrlCommonPrefix } from './config/typeReferences/globals';
+export { printClass, printInterface, printMethod, printFunction, printSignature, printProperty, printGetterSetter, printVariable, printTypeAlias, printTypeParameters, } from './utils/partPrinter';
+export { apiExtractorError, apiExtractorErrorCount, resetApiExtractorErrorCount, setApiExtractorErrorLogger, type ApiExtractorErrorContext, } from './utils/error';