@microsoft/api-extractor-model 7.32.1 → 7.33.0

package/lib-esm/items/ApiItem.js

@@ -0,0 +1,270 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+import { InternalError } from '@rushstack/node-core-library';
+import { ApiParameterListMixin } from '../mixins/ApiParameterListMixin';
+import { ApiItemContainerMixin } from '../mixins/ApiItemContainerMixin';
+/**
+ * The type returned by the {@link ApiItem.kind} property, which can be used to easily distinguish subclasses of
+ * {@link ApiItem}.
+ *
+ * @public
+ */
+export var ApiItemKind;
+(function (ApiItemKind) {
+    ApiItemKind["CallSignature"] = "CallSignature";
+    ApiItemKind["Class"] = "Class";
+    ApiItemKind["Constructor"] = "Constructor";
+    ApiItemKind["ConstructSignature"] = "ConstructSignature";
+    ApiItemKind["EntryPoint"] = "EntryPoint";
+    ApiItemKind["Enum"] = "Enum";
+    ApiItemKind["EnumMember"] = "EnumMember";
+    ApiItemKind["Function"] = "Function";
+    ApiItemKind["IndexSignature"] = "IndexSignature";
+    ApiItemKind["Interface"] = "Interface";
+    ApiItemKind["Method"] = "Method";
+    ApiItemKind["MethodSignature"] = "MethodSignature";
+    ApiItemKind["Model"] = "Model";
+    ApiItemKind["Namespace"] = "Namespace";
+    ApiItemKind["Package"] = "Package";
+    ApiItemKind["Property"] = "Property";
+    ApiItemKind["PropertySignature"] = "PropertySignature";
+    ApiItemKind["TypeAlias"] = "TypeAlias";
+    ApiItemKind["Variable"] = "Variable";
+    ApiItemKind["None"] = "None";
+})(ApiItemKind || (ApiItemKind = {}));
+// PRIVATE - Allows ApiItemContainerMixin to assign the parent.
+//
+export const apiItem_onParentChanged = Symbol('ApiItem._onAddToContainer');
+/**
+ * The abstract base class for all members of an `ApiModel` object.
+ *
+ * @remarks
+ * This is part of the {@link ApiModel} hierarchy of classes, which are serializable representations of
+ * API declarations.
+ * @public
+ */
+export class ApiItem {
+    constructor(options) {
+        // ("options" is not used here, but part of the inheritance pattern)
+    }
+    static deserialize(jsonObject, context) {
+        // The Deserializer class is coupled with a ton of other classes, so  we delay loading it
+        // to avoid ES5 circular imports.
+        const deserializerModule = require('../model/Deserializer');
+        return deserializerModule.Deserializer.deserialize(context, jsonObject);
+    }
+    /** @virtual */
+    static onDeserializeInto(options, context, jsonObject) {
+        // (implemented by subclasses)
+    }
+    /** @virtual */
+    serializeInto(jsonObject) {
+        jsonObject.kind = this.kind;
+        jsonObject.canonicalReference = this.canonicalReference.toString();
+    }
+    /**
+     * Identifies the subclass of the `ApiItem` base class.
+     * @virtual
+     */
+    get kind() {
+        throw new Error('ApiItem.kind was not implemented by the child class');
+    }
+    /**
+     * Warning: This API is used internally by API extractor but is not yet ready for general usage.
+     *
+     * @remarks
+     *
+     * Returns a `DeclarationReference` object using the experimental new declaration reference notation.
+     *
+     * @beta
+     */
+    get canonicalReference() {
+        if (!this._canonicalReference) {
+            try {
+                this._canonicalReference = this.buildCanonicalReference();
+            }
+            catch (e) {
+                const name = this.getScopedNameWithinPackage() || this.displayName;
+                throw new InternalError(`Error building canonical reference for ${name}:\n` + e.message);
+            }
+        }
+        return this._canonicalReference;
+    }
+    /**
+     * Returns a string key that can be used to efficiently retrieve an `ApiItem` from an `ApiItemContainerMixin`.
+     * The key is unique within the container.  Its format is undocumented and may change at any time.
+     *
+     * @remarks
+     * Use the `getContainerKey()` static member to construct the key.  Each subclass has a different implementation
+     * of this function, according to the aspects that are important for identifying it.
+     *
+     * @virtual
+     */
+    get containerKey() {
+        throw new InternalError('ApiItem.containerKey was not implemented by the child class');
+    }
+    /**
+     * Returns a name for this object that can be used in diagnostic messages, for example.
+     *
+     * @remarks
+     * For an object that inherits ApiNameMixin, this will return the declared name (e.g. the name of a TypeScript
+     * function).  Otherwise, it will return a string such as "(call signature)" or "(model)".
+     *
+     * @virtual
+     */
+    get displayName() {
+        switch (this.kind) {
+            case ApiItemKind.CallSignature:
+                return '(call)';
+            case ApiItemKind.Constructor:
+                return '(constructor)';
+            case ApiItemKind.ConstructSignature:
+                return '(new)';
+            case ApiItemKind.IndexSignature:
+                return '(indexer)';
+            case ApiItemKind.Model:
+                return '(model)';
+        }
+        return '(???)'; // All other types should inherit ApiNameMixin which will override this property
+    }
+    /**
+     * If this item was added to a ApiItemContainerMixin item, then this returns the container item.
+     * If this is an Parameter that was added to a method or function, then this returns the function item.
+     * Otherwise, it returns undefined.
+     * @virtual
+     */
+    get parent() {
+        return this._parent;
+    }
+    /**
+     * This property supports a visitor pattern for walking the tree.
+     * For items with ApiItemContainerMixin, it returns the contained items, sorted alphabetically.
+     * Otherwise it returns an empty array.
+     * @virtual
+     */
+    get members() {
+        return [];
+    }
+    /**
+     * If this item has a name (i.e. extends `ApiNameMixin`), then return all items that have the same parent
+     * and the same name.  Otherwise, return all items that have the same parent and the same `ApiItemKind`.
+     *
+     * @remarks
+     * Examples: For a function, this would return all overloads for the function.  For a constructor, this would
+     * return all overloads for the constructor.  For a merged declaration (e.g. a `namespace` and `enum` with the
+     * same name), this would return both declarations.  If this item does not have a parent, or if it is the only
+     * item of its name/kind, then the result is an array containing only this item.
+     */
+    getMergedSiblings() {
+        const parent = this._parent;
+        if (parent && ApiItemContainerMixin.isBaseClassOf(parent)) {
+            return parent._getMergedSiblingsForMember(this);
+        }
+        return [];
+    }
+    /**
+     * Returns the chain of ancestors, starting from the root of the tree, and ending with the this item.
+     */
+    getHierarchy() {
+        const hierarchy = [];
+        for (let current = this; current !== undefined; current = current.parent) {
+            hierarchy.push(current);
+        }
+        hierarchy.reverse();
+        return hierarchy;
+    }
+    /**
+     * This returns a scoped name such as `"Namespace1.Namespace2.MyClass.myMember()"`.  It does not include the
+     * package name or entry point.
+     *
+     * @remarks
+     * If called on an ApiEntrypoint, ApiPackage, or ApiModel item, the result is an empty string.
+     */
+    getScopedNameWithinPackage() {
+        const reversedParts = [];
+        for (let current = this; current !== undefined; current = current.parent) {
+            if (current.kind === ApiItemKind.Model ||
+                current.kind === ApiItemKind.Package ||
+                current.kind === ApiItemKind.EntryPoint) {
+                break;
+            }
+            if (reversedParts.length !== 0) {
+                reversedParts.push('.');
+            }
+            else {
+                switch (current.kind) {
+                    case ApiItemKind.CallSignature:
+                    case ApiItemKind.ConstructSignature:
+                    case ApiItemKind.Constructor:
+                    case ApiItemKind.IndexSignature:
+                        // These functional forms don't have a proper name, so we don't append the "()" suffix
+                        break;
+                    default:
+                        if (ApiParameterListMixin.isBaseClassOf(current)) {
+                            reversedParts.push('()');
+                        }
+                }
+            }
+            reversedParts.push(current.displayName);
+        }
+        return reversedParts.reverse().join('');
+    }
+    /**
+     * If this item is an ApiPackage or has an ApiPackage as one of its parents, then that object is returned.
+     * Otherwise undefined is returned.
+     */
+    getAssociatedPackage() {
+        for (let current = this; current !== undefined; current = current.parent) {
+            if (current.kind === ApiItemKind.Package) {
+                return current;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * If this item is an ApiModel or has an ApiModel as one of its parents, then that object is returned.
+     * Otherwise undefined is returned.
+     */
+    getAssociatedModel() {
+        for (let current = this; current !== undefined; current = current.parent) {
+            if (current.kind === ApiItemKind.Model) {
+                return current;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * A text string whose value determines the sort order that is automatically applied by the
+     * {@link (ApiItemContainerMixin:interface)} class.
+     *
+     * @remarks
+     * The value of this string is undocumented and may change at any time.
+     * If {@link (ApiItemContainerMixin:interface).preserveMemberOrder} is enabled for the `ApiItem`'s parent,
+     * then no sorting is performed, and this key is not used.
+     *
+     * @virtual
+     */
+    getSortKey() {
+        return this.containerKey;
+    }
+    /**
+     * PRIVATE
+     *
+     * @privateRemarks
+     * Allows ApiItemContainerMixin to assign the parent when the item is added to a container.
+     *
+     * @internal
+     */
+    [apiItem_onParentChanged](parent) {
+        this._parent = parent;
+        this._canonicalReference = undefined;
+    }
+    /**
+     * Builds the cached object used by the `canonicalReference` property.
+     * @virtual
+     */
+    buildCanonicalReference() {
+        throw new InternalError('ApiItem.canonicalReference was not implemented by the child class');
+    }
+}
+//# sourceMappingURL=ApiItem.js.map

package/lib-esm/items/ApiItem.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ApiItem.js","sourceRoot":"","sources":["../../src/items/ApiItem.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.\n// See LICENSE in the project root for license information.\n\nimport type { DeclarationReference } from '@microsoft/tsdoc/lib-commonjs/beta/DeclarationReference';\nimport { InternalError } from '@rushstack/node-core-library';\n\nimport type { Constructor, PropertiesOf } from '../mixins/Mixin';\nimport type { ApiPackage } from '../model/ApiPackage';\nimport { ApiParameterListMixin } from '../mixins/ApiParameterListMixin';\nimport type { DeserializerContext } from '../model/DeserializerContext';\nimport { ApiItemContainerMixin } from '../mixins/ApiItemContainerMixin';\nimport type { ApiModel } from '../model/ApiModel';\n\n/**\n * The type returned by the {@link ApiItem.kind} property, which can be used to easily distinguish subclasses of\n * {@link ApiItem}.\n *\n * @public\n */\nexport enum ApiItemKind {\n  CallSignature = 'CallSignature',\n  Class = 'Class',\n  Constructor = 'Constructor',\n  ConstructSignature = 'ConstructSignature',\n  EntryPoint = 'EntryPoint',\n  Enum = 'Enum',\n  EnumMember = 'EnumMember',\n  Function = 'Function',\n  IndexSignature = 'IndexSignature',\n  Interface = 'Interface',\n  Method = 'Method',\n  MethodSignature = 'MethodSignature',\n  Model = 'Model',\n  Namespace = 'Namespace',\n  Package = 'Package',\n  Property = 'Property',\n  PropertySignature = 'PropertySignature',\n  TypeAlias = 'TypeAlias',\n  Variable = 'Variable',\n  None = 'None'\n}\n\n/**\n * Constructor options for {@link ApiItem}.\n * @public\n */\nexport interface IApiItemOptions {}\n\nexport interface IApiItemJson {\n  kind: ApiItemKind;\n  canonicalReference: string;\n}\n\n// PRIVATE - Allows ApiItemContainerMixin to assign the parent.\n//\nexport const apiItem_onParentChanged: unique symbol = Symbol('ApiItem._onAddToContainer');\n\n/**\n * The abstract base class for all members of an `ApiModel` object.\n *\n * @remarks\n * This is part of the {@link ApiModel} hierarchy of classes, which are serializable representations of\n * API declarations.\n * @public\n */\nexport class ApiItem {\n  private _canonicalReference: DeclarationReference | undefined;\n  private _parent: ApiItem | undefined;\n\n  public constructor(options: IApiItemOptions) {\n    // (\"options\" is not used here, but part of the inheritance pattern)\n  }\n\n  public static deserialize(jsonObject: IApiItemJson, context: DeserializerContext): ApiItem {\n    // The Deserializer class is coupled with a ton of other classes, so  we delay loading it\n    // to avoid ES5 circular imports.\n    const deserializerModule: typeof import('../model/Deserializer') = require('../model/Deserializer');\n    return deserializerModule.Deserializer.deserialize(context, jsonObject);\n  }\n\n  /** @virtual */\n  public static onDeserializeInto(\n    options: Partial<IApiItemOptions>,\n    context: DeserializerContext,\n    jsonObject: IApiItemJson\n  ): void {\n    // (implemented by subclasses)\n  }\n\n  /** @virtual */\n  public serializeInto(jsonObject: Partial<IApiItemJson>): void {\n    jsonObject.kind = this.kind;\n    jsonObject.canonicalReference = this.canonicalReference.toString();\n  }\n\n  /**\n   * Identifies the subclass of the `ApiItem` base class.\n   * @virtual\n   */\n  public get kind(): ApiItemKind {\n    throw new Error('ApiItem.kind was not implemented by the child class');\n  }\n\n  /**\n   * Warning: This API is used internally by API extractor but is not yet ready for general usage.\n   *\n   * @remarks\n   *\n   * Returns a `DeclarationReference` object using the experimental new declaration reference notation.\n   *\n   * @beta\n   */\n  public get canonicalReference(): DeclarationReference {\n    if (!this._canonicalReference) {\n      try {\n        this._canonicalReference = this.buildCanonicalReference();\n      } catch (e) {\n        const name: string = this.getScopedNameWithinPackage() || this.displayName;\n        throw new InternalError(`Error building canonical reference for ${name}:\\n` + (e as Error).message);\n      }\n    }\n    return this._canonicalReference;\n  }\n\n  /**\n   * Returns a string key that can be used to efficiently retrieve an `ApiItem` from an `ApiItemContainerMixin`.\n   * The key is unique within the container.  Its format is undocumented and may change at any time.\n   *\n   * @remarks\n   * Use the `getContainerKey()` static member to construct the key.  Each subclass has a different implementation\n   * of this function, according to the aspects that are important for identifying it.\n   *\n   * @virtual\n   */\n  public get containerKey(): string {\n    throw new InternalError('ApiItem.containerKey was not implemented by the child class');\n  }\n\n  /**\n   * Returns a name for this object that can be used in diagnostic messages, for example.\n   *\n   * @remarks\n   * For an object that inherits ApiNameMixin, this will return the declared name (e.g. the name of a TypeScript\n   * function).  Otherwise, it will return a string such as \"(call signature)\" or \"(model)\".\n   *\n   * @virtual\n   */\n  public get displayName(): string {\n    switch (this.kind) {\n      case ApiItemKind.CallSignature:\n        return '(call)';\n      case ApiItemKind.Constructor:\n        return '(constructor)';\n      case ApiItemKind.ConstructSignature:\n        return '(new)';\n      case ApiItemKind.IndexSignature:\n        return '(indexer)';\n      case ApiItemKind.Model:\n        return '(model)';\n    }\n    return '(???)'; // All other types should inherit ApiNameMixin which will override this property\n  }\n\n  /**\n   * If this item was added to a ApiItemContainerMixin item, then this returns the container item.\n   * If this is an Parameter that was added to a method or function, then this returns the function item.\n   * Otherwise, it returns undefined.\n   * @virtual\n   */\n  public get parent(): ApiItem | undefined {\n    return this._parent;\n  }\n\n  /**\n   * This property supports a visitor pattern for walking the tree.\n   * For items with ApiItemContainerMixin, it returns the contained items, sorted alphabetically.\n   * Otherwise it returns an empty array.\n   * @virtual\n   */\n  public get members(): ReadonlyArray<ApiItem> {\n    return [];\n  }\n\n  /**\n   * If this item has a name (i.e. extends `ApiNameMixin`), then return all items that have the same parent\n   * and the same name.  Otherwise, return all items that have the same parent and the same `ApiItemKind`.\n   *\n   * @remarks\n   * Examples: For a function, this would return all overloads for the function.  For a constructor, this would\n   * return all overloads for the constructor.  For a merged declaration (e.g. a `namespace` and `enum` with the\n   * same name), this would return both declarations.  If this item does not have a parent, or if it is the only\n   * item of its name/kind, then the result is an array containing only this item.\n   */\n  public getMergedSiblings(): ReadonlyArray<ApiItem> {\n    const parent: ApiItem | undefined = this._parent;\n    if (parent && ApiItemContainerMixin.isBaseClassOf(parent)) {\n      return parent._getMergedSiblingsForMember(this);\n    }\n    return [];\n  }\n\n  /**\n   * Returns the chain of ancestors, starting from the root of the tree, and ending with the this item.\n   */\n  public getHierarchy(): ReadonlyArray<ApiItem> {\n    const hierarchy: ApiItem[] = [];\n    for (let current: ApiItem | undefined = this; current !== undefined; current = current.parent) {\n      hierarchy.push(current);\n    }\n    hierarchy.reverse();\n    return hierarchy;\n  }\n\n  /**\n   * This returns a scoped name such as `\"Namespace1.Namespace2.MyClass.myMember()\"`.  It does not include the\n   * package name or entry point.\n   *\n   * @remarks\n   * If called on an ApiEntrypoint, ApiPackage, or ApiModel item, the result is an empty string.\n   */\n  public getScopedNameWithinPackage(): string {\n    const reversedParts: string[] = [];\n\n    for (let current: ApiItem | undefined = this; current !== undefined; current = current.parent) {\n      if (\n        current.kind === ApiItemKind.Model ||\n        current.kind === ApiItemKind.Package ||\n        current.kind === ApiItemKind.EntryPoint\n      ) {\n        break;\n      }\n      if (reversedParts.length !== 0) {\n        reversedParts.push('.');\n      } else {\n        switch (current.kind) {\n          case ApiItemKind.CallSignature:\n          case ApiItemKind.ConstructSignature:\n          case ApiItemKind.Constructor:\n          case ApiItemKind.IndexSignature:\n            // These functional forms don't have a proper name, so we don't append the \"()\" suffix\n            break;\n          default:\n            if (ApiParameterListMixin.isBaseClassOf(current)) {\n              reversedParts.push('()');\n            }\n        }\n      }\n      reversedParts.push(current.displayName);\n    }\n\n    return reversedParts.reverse().join('');\n  }\n\n  /**\n   * If this item is an ApiPackage or has an ApiPackage as one of its parents, then that object is returned.\n   * Otherwise undefined is returned.\n   */\n  public getAssociatedPackage(): ApiPackage | undefined {\n    for (let current: ApiItem | undefined = this; current !== undefined; current = current.parent) {\n      if (current.kind === ApiItemKind.Package) {\n        return current as ApiPackage;\n      }\n    }\n    return undefined;\n  }\n\n  /**\n   * If this item is an ApiModel or has an ApiModel as one of its parents, then that object is returned.\n   * Otherwise undefined is returned.\n   */\n  public getAssociatedModel(): ApiModel | undefined {\n    for (let current: ApiItem | undefined = this; current !== undefined; current = current.parent) {\n      if (current.kind === ApiItemKind.Model) {\n        return current as ApiModel;\n      }\n    }\n    return undefined;\n  }\n\n  /**\n   * A text string whose value determines the sort order that is automatically applied by the\n   * {@link (ApiItemContainerMixin:interface)} class.\n   *\n   * @remarks\n   * The value of this string is undocumented and may change at any time.\n   * If {@link (ApiItemContainerMixin:interface).preserveMemberOrder} is enabled for the `ApiItem`'s parent,\n   * then no sorting is performed, and this key is not used.\n   *\n   * @virtual\n   */\n  public getSortKey(): string {\n    return this.containerKey;\n  }\n\n  /**\n   * PRIVATE\n   *\n   * @privateRemarks\n   * Allows ApiItemContainerMixin to assign the parent when the item is added to a container.\n   *\n   * @internal\n   */\n  public [apiItem_onParentChanged](parent: ApiItem | undefined): void {\n    this._parent = parent;\n    this._canonicalReference = undefined;\n  }\n\n  /**\n   * Builds the cached object used by the `canonicalReference` property.\n   * @virtual\n   */\n  protected buildCanonicalReference(): DeclarationReference {\n    throw new InternalError('ApiItem.canonicalReference was not implemented by the child class');\n  }\n}\n\n/**\n * This abstraction is used by the mixin pattern.\n * It describes a class type that inherits from {@link ApiItem}.\n *\n * @public\n */\nexport interface IApiItemConstructor extends Constructor<ApiItem>, PropertiesOf<typeof ApiItem> {}\n"]}

package/lib-esm/items/ApiPropertyItem.js

@@ -0,0 +1,45 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+import { ApiDeclaredItem } from './ApiDeclaredItem';
+import { ApiReleaseTagMixin } from '../mixins/ApiReleaseTagMixin';
+import { ApiNameMixin } from '../mixins/ApiNameMixin';
+import { ApiOptionalMixin } from '../mixins/ApiOptionalMixin';
+import { ApiReadonlyMixin } from '../mixins/ApiReadonlyMixin';
+/**
+ * The abstract base class for {@link ApiProperty} and {@link ApiPropertySignature}.
+ *
+ * @public
+ */
+export class ApiPropertyItem extends ApiNameMixin(ApiReleaseTagMixin(ApiOptionalMixin(ApiReadonlyMixin(ApiDeclaredItem)))) {
+    constructor(options) {
+        super(options);
+        this.propertyTypeExcerpt = this.buildExcerpt(options.propertyTypeTokenRange);
+    }
+    /** @override */
+    static onDeserializeInto(options, context, jsonObject) {
+        super.onDeserializeInto(options, context, jsonObject);
+        options.propertyTypeTokenRange = jsonObject.propertyTypeTokenRange;
+    }
+    /**
+     * Returns true if this property should be documented as an event.
+     *
+     * @remarks
+     * The `@eventProperty` TSDoc modifier can be added to readonly properties to indicate that they return an
+     * event object that event handlers can be attached to.  The event-handling API is implementation-defined, but
+     * typically the return type would be a class with members such as `addHandler()` and `removeHandler()`.
+     * The documentation should display such properties under an "Events" heading instead of the
+     * usual "Properties" heading.
+     */
+    get isEventProperty() {
+        if (this.tsdocComment) {
+            return this.tsdocComment.modifierTagSet.isEventProperty();
+        }
+        return false;
+    }
+    /** @override */
+    serializeInto(jsonObject) {
+        super.serializeInto(jsonObject);
+        jsonObject.propertyTypeTokenRange = this.propertyTypeExcerpt.tokenRange;
+    }
+}
+//# sourceMappingURL=ApiPropertyItem.js.map

package/lib-esm/items/ApiPropertyItem.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ApiPropertyItem.js","sourceRoot":"","sources":["../../src/items/ApiPropertyItem.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,2DAA2D;AAG3D,OAAO,EAAgC,eAAe,EAA6B,MAAM,mBAAmB,CAAC;AAC7G,OAAO,EAAE,kBAAkB,EAAmC,MAAM,8BAA8B,CAAC;AACnG,OAAO,EAA6B,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAEjF,OAAO,EAAE,gBAAgB,EAAiC,MAAM,4BAA4B,CAAC;AAC7F,OAAO,EAAE,gBAAgB,EAAiC,MAAM,4BAA4B,CAAC;AAmB7F;;;;GAIG;AACH,MAAM,OAAO,eAAgB,SAAQ,YAAY,CAC/C,kBAAkB,CAAC,gBAAgB,CAAC,gBAAgB,CAAC,eAAe,CAAC,CAAC,CAAC,CACxE;IAMC,YAAmB,OAAgC;QACjD,KAAK,CAAC,OAAO,CAAC,CAAC;QAEf,IAAI,CAAC,mBAAmB,GAAG,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,sBAAsB,CAAC,CAAC;IAC/E,CAAC;IAED,gBAAgB;IACT,MAAM,CAAC,iBAAiB,CAC7B,OAAyC,EACzC,OAA4B,EAC5B,UAAgC;QAEhC,KAAK,CAAC,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;QAEtD,OAAO,CAAC,sBAAsB,GAAG,UAAU,CAAC,sBAAsB,CAAC;IACrE,CAAC;IAED;;;;;;;;;OASG;IACH,IAAW,eAAe;QACxB,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YACtB,OAAO,IAAI,CAAC,YAAY,CAAC,cAAc,CAAC,eAAe,EAAE,CAAC;QAC5D,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,gBAAgB;IACT,aAAa,CAAC,UAAyC;QAC5D,KAAK,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC;QAEhC,UAAU,CAAC,sBAAsB,GAAG,IAAI,CAAC,mBAAmB,CAAC,UAAU,CAAC;IAC1E,CAAC;CACF","sourcesContent":["// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.\n// See LICENSE in the project root for license information.\n\nimport type { Excerpt, IExcerptTokenRange } from '../mixins/Excerpt';\nimport { type IApiDeclaredItemOptions, ApiDeclaredItem, type IApiDeclaredItemJson } from './ApiDeclaredItem';\nimport { ApiReleaseTagMixin, type IApiReleaseTagMixinOptions } from '../mixins/ApiReleaseTagMixin';\nimport { type IApiNameMixinOptions, ApiNameMixin } from '../mixins/ApiNameMixin';\nimport type { DeserializerContext } from '../model/DeserializerContext';\nimport { ApiOptionalMixin, type IApiOptionalMixinOptions } from '../mixins/ApiOptionalMixin';\nimport { ApiReadonlyMixin, type IApiReadonlyMixinOptions } from '../mixins/ApiReadonlyMixin';\n\n/**\n * Constructor options for {@link ApiPropertyItem}.\n * @public\n */\nexport interface IApiPropertyItemOptions\n  extends IApiNameMixinOptions,\n    IApiReleaseTagMixinOptions,\n    IApiOptionalMixinOptions,\n    IApiReadonlyMixinOptions,\n    IApiDeclaredItemOptions {\n  propertyTypeTokenRange: IExcerptTokenRange;\n}\n\nexport interface IApiPropertyItemJson extends IApiDeclaredItemJson {\n  propertyTypeTokenRange: IExcerptTokenRange;\n}\n\n/**\n * The abstract base class for {@link ApiProperty} and {@link ApiPropertySignature}.\n *\n * @public\n */\nexport class ApiPropertyItem extends ApiNameMixin(\n  ApiReleaseTagMixin(ApiOptionalMixin(ApiReadonlyMixin(ApiDeclaredItem)))\n) {\n  /**\n   * An {@link Excerpt} that describes the type of the property.\n   */\n  public readonly propertyTypeExcerpt: Excerpt;\n\n  public constructor(options: IApiPropertyItemOptions) {\n    super(options);\n\n    this.propertyTypeExcerpt = this.buildExcerpt(options.propertyTypeTokenRange);\n  }\n\n  /** @override */\n  public static onDeserializeInto(\n    options: Partial<IApiPropertyItemOptions>,\n    context: DeserializerContext,\n    jsonObject: IApiPropertyItemJson\n  ): void {\n    super.onDeserializeInto(options, context, jsonObject);\n\n    options.propertyTypeTokenRange = jsonObject.propertyTypeTokenRange;\n  }\n\n  /**\n   * Returns true if this property should be documented as an event.\n   *\n   * @remarks\n   * The `@eventProperty` TSDoc modifier can be added to readonly properties to indicate that they return an\n   * event object that event handlers can be attached to.  The event-handling API is implementation-defined, but\n   * typically the return type would be a class with members such as `addHandler()` and `removeHandler()`.\n   * The documentation should display such properties under an \"Events\" heading instead of the\n   * usual \"Properties\" heading.\n   */\n  public get isEventProperty(): boolean {\n    if (this.tsdocComment) {\n      return this.tsdocComment.modifierTagSet.isEventProperty();\n    }\n    return false;\n  }\n\n  /** @override */\n  public serializeInto(jsonObject: Partial<IApiPropertyItemJson>): void {\n    super.serializeInto(jsonObject);\n\n    jsonObject.propertyTypeTokenRange = this.propertyTypeExcerpt.tokenRange;\n  }\n}\n"]}

package/lib-esm/mixins/ApiAbstractMixin.js

@@ -0,0 +1,58 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+const _isAbstract = Symbol('ApiAbstractMixin._isAbstract');
+/**
+ * Mixin function for {@link (ApiAbstractMixin:interface)}.
+ *
+ * @param baseClass - The base class to be extended
+ * @returns A child class that extends baseClass, adding the {@link (ApiAbstractMixin:interface)}
+ * functionality.
+ *
+ * @public
+ */
+export function ApiAbstractMixin(baseClass
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+) {
+    class MixedClass extends baseClass {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        constructor(...args) {
+            super(...args);
+            const options = args[0];
+            this[_isAbstract] = options.isAbstract;
+        }
+        /** @override */
+        static onDeserializeInto(options, context, jsonObject) {
+            baseClass.onDeserializeInto(options, context, jsonObject);
+            options.isAbstract = jsonObject.isAbstract || false;
+        }
+        get isAbstract() {
+            return this[_isAbstract];
+        }
+        /** @override */
+        serializeInto(jsonObject) {
+            super.serializeInto(jsonObject);
+            jsonObject.isAbstract = this.isAbstract;
+        }
+    }
+    return MixedClass;
+}
+/**
+ * Static members for {@link (ApiAbstractMixin:interface)}.
+ * @public
+ */
+(function (ApiAbstractMixin) {
+    /**
+     * A type guard that tests whether the specified `ApiItem` subclass extends the `ApiAbstractMixin` mixin.
+     *
+     * @remarks
+     *
+     * The JavaScript `instanceof` operator cannot be used to test for mixin inheritance, because each invocation of
+     * the mixin function produces a different subclass.  (This could be mitigated by `Symbol.hasInstance`, however
+     * the TypeScript type system cannot invoke a runtime test.)
+     */
+    function isBaseClassOf(apiItem) {
+        return apiItem.hasOwnProperty(_isAbstract);
+    }
+    ApiAbstractMixin.isBaseClassOf = isBaseClassOf;
+})(ApiAbstractMixin || (ApiAbstractMixin = {}));
+//# sourceMappingURL=ApiAbstractMixin.js.map

package/lib-esm/mixins/ApiAbstractMixin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ApiAbstractMixin.js","sourceRoot":"","sources":["../../src/mixins/ApiAbstractMixin.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,2DAA2D;AAmB3D,MAAM,WAAW,GAAkB,MAAM,CAAC,8BAA8B,CAAC,CAAC;AA2B1E;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB,CAC9B,SAAqB;AACrB,8DAA8D;;IAE9D,MAAM,UAAW,SAAQ,SAAS;QAGhC,8DAA8D;QAC9D,YAAmB,GAAG,IAAW;YAC/B,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC;YAEf,MAAM,OAAO,GAA6B,IAAI,CAAC,CAAC,CAAC,CAAC;YAClD,IAAI,CAAC,WAAW,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC;QACzC,CAAC;QAED,gBAAgB;QACT,MAAM,CAAC,iBAAiB,CAC7B,OAA0C,EAC1C,OAA4B,EAC5B,UAAiC;YAEjC,SAAS,CAAC,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;YAE1D,OAAO,CAAC,UAAU,GAAG,UAAU,CAAC,UAAU,IAAI,KAAK,CAAC;QACtD,CAAC;QAED,IAAW,UAAU;YACnB,OAAO,IAAI,CAAC,WAAW,CAAC,CAAC;QAC3B,CAAC;QAED,gBAAgB;QACT,aAAa,CAAC,UAA0C;YAC7D,KAAK,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC;YAEhC,UAAU,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;QAC1C,CAAC;KACF;IAED,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;;GAGG;AACH,WAAiB,gBAAgB;IAC/B;;;;;;;;OAQG;IACH,SAAgB,aAAa,CAAC,OAAgB;QAC5C,OAAO,OAAO,CAAC,cAAc,CAAC,WAAW,CAAC,CAAC;IAC7C,CAAC;IAFe,8BAAa,gBAE5B,CAAA;AACH,CAAC,EAbgB,gBAAgB,KAAhB,gBAAgB,QAahC","sourcesContent":["// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.\n// See LICENSE in the project root for license information.\n\n/* eslint-disable @typescript-eslint/no-redeclare */\n\nimport type { ApiItem, IApiItemJson, IApiItemConstructor, IApiItemOptions } from '../items/ApiItem';\nimport type { DeserializerContext } from '../model/DeserializerContext';\n\n/**\n * Constructor options for {@link (ApiAbstractMixin:interface)}.\n * @public\n */\nexport interface IApiAbstractMixinOptions extends IApiItemOptions {\n  isAbstract: boolean;\n}\n\nexport interface IApiAbstractMixinJson extends IApiItemJson {\n  isAbstract: boolean;\n}\n\nconst _isAbstract: unique symbol = Symbol('ApiAbstractMixin._isAbstract');\n\n/**\n * The mixin base class for API items that have an abstract modifier.\n *\n * @remarks\n *\n * This is part of the {@link ApiModel} hierarchy of classes, which are serializable representations of\n * API declarations.  The non-abstract classes (e.g. `ApiClass`, `ApiEnum`, `ApiInterface`, etc.) use\n * TypeScript \"mixin\" functions (e.g. `ApiDeclaredItem`, `ApiItemContainerMixin`, etc.) to add various\n * features that cannot be represented as a normal inheritance chain (since TypeScript does not allow a child class\n * to extend more than one base class).  The \"mixin\" is a TypeScript merged declaration with three components:\n * the function that generates a subclass, an interface that describes the members of the subclass, and\n * a namespace containing static members of the class.\n *\n * @public\n */\n// eslint-disable-next-line @typescript-eslint/naming-convention\nexport interface ApiAbstractMixin extends ApiItem {\n  /**\n   * Indicates that the API item's value has an 'abstract' modifier.\n   */\n  readonly isAbstract: boolean;\n\n  serializeInto(jsonObject: Partial<IApiItemJson>): void;\n}\n\n/**\n * Mixin function for {@link (ApiAbstractMixin:interface)}.\n *\n * @param baseClass - The base class to be extended\n * @returns A child class that extends baseClass, adding the {@link (ApiAbstractMixin:interface)}\n * functionality.\n *\n * @public\n */\nexport function ApiAbstractMixin<TBaseClass extends IApiItemConstructor>(\n  baseClass: TBaseClass\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n): TBaseClass & (new (...args: any[]) => ApiAbstractMixin) {\n  class MixedClass extends baseClass implements ApiAbstractMixin {\n    public [_isAbstract]: boolean;\n\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    public constructor(...args: any[]) {\n      super(...args);\n\n      const options: IApiAbstractMixinOptions = args[0];\n      this[_isAbstract] = options.isAbstract;\n    }\n\n    /** @override */\n    public static onDeserializeInto(\n      options: Partial<IApiAbstractMixinOptions>,\n      context: DeserializerContext,\n      jsonObject: IApiAbstractMixinJson\n    ): void {\n      baseClass.onDeserializeInto(options, context, jsonObject);\n\n      options.isAbstract = jsonObject.isAbstract || false;\n    }\n\n    public get isAbstract(): boolean {\n      return this[_isAbstract];\n    }\n\n    /** @override */\n    public serializeInto(jsonObject: Partial<IApiAbstractMixinJson>): void {\n      super.serializeInto(jsonObject);\n\n      jsonObject.isAbstract = this.isAbstract;\n    }\n  }\n\n  return MixedClass;\n}\n\n/**\n * Static members for {@link (ApiAbstractMixin:interface)}.\n * @public\n */\nexport namespace ApiAbstractMixin {\n  /**\n   * A type guard that tests whether the specified `ApiItem` subclass extends the `ApiAbstractMixin` mixin.\n   *\n   * @remarks\n   *\n   * The JavaScript `instanceof` operator cannot be used to test for mixin inheritance, because each invocation of\n   * the mixin function produces a different subclass.  (This could be mitigated by `Symbol.hasInstance`, however\n   * the TypeScript type system cannot invoke a runtime test.)\n   */\n  export function isBaseClassOf(apiItem: ApiItem): apiItem is ApiAbstractMixin {\n    return apiItem.hasOwnProperty(_isAbstract);\n  }\n}\n"]}

package/lib-esm/mixins/ApiExportedMixin.js

@@ -0,0 +1,63 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+/* eslint-disable @typescript-eslint/no-redeclare */
+import { DeclarationReference, Navigation } from '@microsoft/tsdoc/lib-commonjs/beta/DeclarationReference';
+const _isExported = Symbol('ApiExportedMixin._isExported');
+/**
+ * Mixin function for {@link (ApiExportedMixin:interface)}.
+ *
+ * @param baseClass - The base class to be extended
+ * @returns A child class that extends baseClass, adding the {@link (ApiExportedMixin:interface)} functionality.
+ *
+ * @public
+ */
+export function ApiExportedMixin(baseClass
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+) {
+    class MixedClass extends baseClass {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        constructor(...args) {
+            super(...args);
+            const options = args[0];
+            this[_isExported] = options.isExported;
+        }
+        /** @override */
+        static onDeserializeInto(options, context, jsonObject) {
+            baseClass.onDeserializeInto(options, context, jsonObject);
+            const declarationReference = DeclarationReference.parse(jsonObject.canonicalReference);
+            options.isExported = declarationReference.navigation === Navigation.Exports;
+        }
+        get isExported() {
+            return this[_isExported];
+        }
+        /**
+         * The `isExported` property is intentionally not serialized because the information is already present
+         * in the item's `canonicalReference`.
+         * @override
+         */
+        serializeInto(jsonObject) {
+            super.serializeInto(jsonObject);
+        }
+    }
+    return MixedClass;
+}
+/**
+ * Static members for {@link (ApiExportedMixin:interface)}.
+ * @public
+ */
+(function (ApiExportedMixin) {
+    /**
+     * A type guard that tests whether the specified `ApiItem` subclass extends the `ApiExportedMixin` mixin.
+     *
+     * @remarks
+     *
+     * The JavaScript `instanceof` operator cannot be used to test for mixin inheritance, because each invocation of
+     * the mixin function produces a different subclass.  (This could be mitigated by `Symbol.hasInstance`, however
+     * the TypeScript type system cannot invoke a runtime test.)
+     */
+    function isBaseClassOf(apiItem) {
+        return apiItem.hasOwnProperty(_isExported);
+    }
+    ApiExportedMixin.isBaseClassOf = isBaseClassOf;
+})(ApiExportedMixin || (ApiExportedMixin = {}));
+//# sourceMappingURL=ApiExportedMixin.js.map

package/lib-esm/mixins/ApiExportedMixin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ApiExportedMixin.js","sourceRoot":"","sources":["../../src/mixins/ApiExportedMixin.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,2DAA2D;AAE3D,oDAAoD;AAEpD,OAAO,EAAE,oBAAoB,EAAE,UAAU,EAAE,MAAM,yDAAyD,CAAC;AAiB3G,MAAM,WAAW,GAAkB,MAAM,CAAC,8BAA8B,CAAC,CAAC;AAmD1E;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAC9B,SAAqB;AACrB,8DAA8D;;IAE9D,MAAM,UAAW,SAAQ,SAAS;QAGhC,8DAA8D;QAC9D,YAAmB,GAAG,IAAW;YAC/B,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC;YAEf,MAAM,OAAO,GAA6B,IAAI,CAAC,CAAC,CAAC,CAAC;YAClD,IAAI,CAAC,WAAW,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC;QACzC,CAAC;QAED,gBAAgB;QACT,MAAM,CAAC,iBAAiB,CAC7B,OAA0C,EAC1C,OAA4B,EAC5B,UAAiC;YAEjC,SAAS,CAAC,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;YAE1D,MAAM,oBAAoB,GAAyB,oBAAoB,CAAC,KAAK,CAC3E,UAAU,CAAC,kBAAkB,CAC9B,CAAC;YACF,OAAO,CAAC,UAAU,GAAG,oBAAoB,CAAC,UAAU,KAAK,UAAU,CAAC,OAAO,CAAC;QAC9E,CAAC;QAED,IAAW,UAAU;YACnB,OAAO,IAAI,CAAC,WAAW,CAAC,CAAC;QAC3B,CAAC;QAED;;;;WAIG;QACI,aAAa,CAAC,UAA0C;YAC7D,KAAK,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC;QAClC,CAAC;KACF;IAED,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;;GAGG;AACH,WAAiB,gBAAgB;IAC/B;;;;;;;;OAQG;IACH,SAAgB,aAAa,CAAC,OAAgB;QAC5C,OAAO,OAAO,CAAC,cAAc,CAAC,WAAW,CAAC,CAAC;IAC7C,CAAC;IAFe,8BAAa,gBAE5B,CAAA;AACH,CAAC,EAbgB,gBAAgB,KAAhB,gBAAgB,QAahC","sourcesContent":["// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.\n// See LICENSE in the project root for license information.\n\n/* eslint-disable @typescript-eslint/no-redeclare */\n\nimport { DeclarationReference, Navigation } from '@microsoft/tsdoc/lib-commonjs/beta/DeclarationReference';\n\nimport type { ApiItem, IApiItemJson, IApiItemConstructor, IApiItemOptions } from '../items/ApiItem';\nimport type { DeserializerContext } from '../model/DeserializerContext';\n\n/**\n * Constructor options for {@link (IApiExportedMixinOptions:interface)}.\n * @public\n */\nexport interface IApiExportedMixinOptions extends IApiItemOptions {\n  isExported: boolean;\n}\n\nexport interface IApiExportedMixinJson extends IApiItemJson {\n  isExported: boolean;\n}\n\nconst _isExported: unique symbol = Symbol('ApiExportedMixin._isExported');\n\n/**\n * The mixin base class for API items that can be exported.\n *\n * @remarks\n *\n * This is part of the {@link ApiModel} hierarchy of classes, which are serializable representations of\n * API declarations.  The non-abstract classes (e.g. `ApiClass`, `ApiEnum`, `ApiInterface`, etc.) use\n * TypeScript \"mixin\" functions (e.g. `ApiDeclaredItem`, `ApiItemContainerMixin`, etc.) to add various\n * features that cannot be represented as a normal inheritance chain (since TypeScript does not allow a child class\n * to extend more than one base class).  The \"mixin\" is a TypeScript merged declaration with three components:\n * the function that generates a subclass, an interface that describes the members of the subclass, and\n * a namespace containing static members of the class.\n *\n * @public\n */\n// eslint-disable-next-line @typescript-eslint/naming-convention\nexport interface ApiExportedMixin extends ApiItem {\n  /**\n   * Whether the declaration is exported from its parent item container (i.e. either an `ApiEntryPoint` or an\n   * `ApiNamespace`).\n   *\n   * @remarks\n   * Suppose `index.ts` is your entry point:\n   *\n   * ```ts\n   * // index.ts\n   *\n   * export class A {}\n   * class B {}\n   *\n   * namespace n {\n   *   export class C {}\n   *   class D {}\n   * }\n   *\n   * // file.ts\n   * export class E {}\n   * ```\n   *\n   * Classes `A` and `C` are both exported, while classes `B`, `D`, and `E` are not. `E` is exported from its\n   * local file, but not from its parent item container (i.e. the entry point).\n   *\n   */\n  readonly isExported: boolean;\n\n  /** @override */\n  serializeInto(jsonObject: Partial<IApiItemJson>): void;\n}\n\n/**\n * Mixin function for {@link (ApiExportedMixin:interface)}.\n *\n * @param baseClass - The base class to be extended\n * @returns A child class that extends baseClass, adding the {@link (ApiExportedMixin:interface)} functionality.\n *\n * @public\n */\nexport function ApiExportedMixin<TBaseClass extends IApiItemConstructor>(\n  baseClass: TBaseClass\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n): TBaseClass & (new (...args: any[]) => ApiExportedMixin) {\n  class MixedClass extends baseClass implements ApiExportedMixin {\n    public [_isExported]: boolean;\n\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    public constructor(...args: any[]) {\n      super(...args);\n\n      const options: IApiExportedMixinOptions = args[0];\n      this[_isExported] = options.isExported;\n    }\n\n    /** @override */\n    public static onDeserializeInto(\n      options: Partial<IApiExportedMixinOptions>,\n      context: DeserializerContext,\n      jsonObject: IApiExportedMixinJson\n    ): void {\n      baseClass.onDeserializeInto(options, context, jsonObject);\n\n      const declarationReference: DeclarationReference = DeclarationReference.parse(\n        jsonObject.canonicalReference\n      );\n      options.isExported = declarationReference.navigation === Navigation.Exports;\n    }\n\n    public get isExported(): boolean {\n      return this[_isExported];\n    }\n\n    /**\n     * The `isExported` property is intentionally not serialized because the information is already present\n     * in the item's `canonicalReference`.\n     * @override\n     */\n    public serializeInto(jsonObject: Partial<IApiExportedMixinJson>): void {\n      super.serializeInto(jsonObject);\n    }\n  }\n\n  return MixedClass;\n}\n\n/**\n * Static members for {@link (ApiExportedMixin:interface)}.\n * @public\n */\nexport namespace ApiExportedMixin {\n  /**\n   * A type guard that tests whether the specified `ApiItem` subclass extends the `ApiExportedMixin` mixin.\n   *\n   * @remarks\n   *\n   * The JavaScript `instanceof` operator cannot be used to test for mixin inheritance, because each invocation of\n   * the mixin function produces a different subclass.  (This could be mitigated by `Symbol.hasInstance`, however\n   * the TypeScript type system cannot invoke a runtime test.)\n   */\n  export function isBaseClassOf(apiItem: ApiItem): apiItem is ApiExportedMixin {\n    return apiItem.hasOwnProperty(_isExported);\n  }\n}\n"]}

package/lib-esm/mixins/ApiInitializerMixin.js

@@ -0,0 +1,70 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+/* eslint-disable @typescript-eslint/no-redeclare */
+import { InternalError } from '@rushstack/node-core-library';
+import { ApiDeclaredItem } from '../items/ApiDeclaredItem';
+const _initializerExcerpt = Symbol('ApiInitializerMixin._initializerExcerpt');
+/**
+ * Mixin function for {@link (ApiInitializerMixin:interface)}.
+ *
+ * @param baseClass - The base class to be extended
+ * @returns A child class that extends baseClass, adding the {@link (ApiInitializerMixin:interface)} functionality.
+ *
+ * @public
+ */
+export function ApiInitializerMixin(baseClass
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+) {
+    class MixedClass extends baseClass {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        constructor(...args) {
+            super(...args);
+            const options = args[0];
+            if (this instanceof ApiDeclaredItem) {
+                if (options.initializerTokenRange) {
+                    this[_initializerExcerpt] = this.buildExcerpt(options.initializerTokenRange);
+                }
+            }
+            else {
+                throw new InternalError('ApiInitializerMixin expects a base class that inherits from ApiDeclaredItem');
+            }
+        }
+        /** @override */
+        static onDeserializeInto(options, context, jsonObject) {
+            baseClass.onDeserializeInto(options, context, jsonObject);
+            options.initializerTokenRange = jsonObject.initializerTokenRange;
+        }
+        get initializerExcerpt() {
+            return this[_initializerExcerpt];
+        }
+        /** @override */
+        serializeInto(jsonObject) {
+            super.serializeInto(jsonObject);
+            // Note that JSON does not support the "undefined" value, so we simply omit the field entirely if it is undefined
+            if (this.initializerExcerpt) {
+                jsonObject.initializerTokenRange = this.initializerExcerpt.tokenRange;
+            }
+        }
+    }
+    return MixedClass;
+}
+/**
+ * Static members for {@link (ApiInitializerMixin:interface)}.
+ * @public
+ */
+(function (ApiInitializerMixin) {
+    /**
+     * A type guard that tests whether the specified `ApiItem` subclass extends the `ApiInitializerMixin` mixin.
+     *
+     * @remarks
+     *
+     * The JavaScript `instanceof` operator cannot be used to test for mixin inheritance, because each invocation of
+     * the mixin function produces a different subclass.  (This could be mitigated by `Symbol.hasInstance`, however
+     * the TypeScript type system cannot invoke a runtime test.)
+     */
+    function isBaseClassOf(apiItem) {
+        return apiItem.hasOwnProperty(_initializerExcerpt);
+    }
+    ApiInitializerMixin.isBaseClassOf = isBaseClassOf;
+})(ApiInitializerMixin || (ApiInitializerMixin = {}));
+//# sourceMappingURL=ApiInitializerMixin.js.map

package/lib-esm/mixins/ApiInitializerMixin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ApiInitializerMixin.js","sourceRoot":"","sources":["../../src/mixins/ApiInitializerMixin.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,2DAA2D;AAE3D,oDAAoD;AAEpD,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAI7D,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAe3D,MAAM,mBAAmB,GAAkB,MAAM,CAAC,yCAAyC,CAAC,CAAC;AA4B7F;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CACjC,SAAqB;AACrB,8DAA8D;;IAE9D,MAAM,UAAW,SAAQ,SAAS;QAGhC,8DAA8D;QAC9D,YAAmB,GAAG,IAAW;YAC/B,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC;YAEf,MAAM,OAAO,GAAgC,IAAI,CAAC,CAAC,CAAC,CAAC;YAErD,IAAI,IAAI,YAAY,eAAe,EAAE,CAAC;gBACpC,IAAI,OAAO,CAAC,qBAAqB,EAAE,CAAC;oBAClC,IAAI,CAAC,mBAAmB,CAAC,GAAG,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,qBAAqB,CAAC,CAAC;gBAC/E,CAAC;YACH,CAAC;iBAAM,CAAC;gBACN,MAAM,IAAI,aAAa,CACrB,6EAA6E,CAC9E,CAAC;YACJ,CAAC;QACH,CAAC;QAED,gBAAgB;QACT,MAAM,CAAC,iBAAiB,CAC7B,OAA6C,EAC7C,OAA4B,EAC5B,UAAoC;YAEpC,SAAS,CAAC,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;YAE1D,OAAO,CAAC,qBAAqB,GAAG,UAAU,CAAC,qBAAqB,CAAC;QACnE,CAAC;QAED,IAAW,kBAAkB;YAC3B,OAAO,IAAI,CAAC,mBAAmB,CAAC,CAAC;QACnC,CAAC;QAED,gBAAgB;QACT,aAAa,CAAC,UAA6C;YAChE,KAAK,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC;YAEhC,iHAAiH;YACjH,IAAI,IAAI,CAAC,kBAAkB,EAAE,CAAC;gBAC5B,UAAU,CAAC,qBAAqB,GAAG,IAAI,CAAC,kBAAkB,CAAC,UAAU,CAAC;YACxE,CAAC;QACH,CAAC;KACF;IAED,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;;GAGG;AACH,WAAiB,mBAAmB;IAClC;;;;;;;;OAQG;IACH,SAAgB,aAAa,CAAC,OAAgB;QAC5C,OAAO,OAAO,CAAC,cAAc,CAAC,mBAAmB,CAAC,CAAC;IACrD,CAAC;IAFe,iCAAa,gBAE5B,CAAA;AACH,CAAC,EAbgB,mBAAmB,KAAnB,mBAAmB,QAanC","sourcesContent":["// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.\n// See LICENSE in the project root for license information.\n\n/* eslint-disable @typescript-eslint/no-redeclare */\n\nimport { InternalError } from '@rushstack/node-core-library';\n\nimport type { ApiItem, IApiItemJson, IApiItemConstructor, IApiItemOptions } from '../items/ApiItem';\nimport type { IExcerptTokenRange, Excerpt } from './Excerpt';\nimport { ApiDeclaredItem } from '../items/ApiDeclaredItem';\nimport type { DeserializerContext } from '../model/DeserializerContext';\n\n/**\n * Constructor options for {@link (IApiInitializerMixinOptions:interface)}.\n * @public\n */\nexport interface IApiInitializerMixinOptions extends IApiItemOptions {\n  initializerTokenRange?: IExcerptTokenRange;\n}\n\nexport interface IApiInitializerMixinJson extends IApiItemJson {\n  initializerTokenRange?: IExcerptTokenRange;\n}\n\nconst _initializerExcerpt: unique symbol = Symbol('ApiInitializerMixin._initializerExcerpt');\n\n/**\n * The mixin base class for API items that can have an initializer.\n *\n * @remarks\n *\n * This is part of the {@link ApiModel} hierarchy of classes, which are serializable representations of\n * API declarations.  The non-abstract classes (e.g. `ApiClass`, `ApiEnum`, `ApiInterface`, etc.) use\n * TypeScript \"mixin\" functions (e.g. `ApiDeclaredItem`, `ApiItemContainerMixin`, etc.) to add various\n * features that cannot be represented as a normal inheritance chain (since TypeScript does not allow a child class\n * to extend more than one base class).  The \"mixin\" is a TypeScript merged declaration with three components:\n * the function that generates a subclass, an interface that describes the members of the subclass, and\n * a namespace containing static members of the class.\n *\n * @public\n */\n// eslint-disable-next-line @typescript-eslint/naming-convention\nexport interface ApiInitializerMixin extends ApiItem {\n  /**\n   * An {@link Excerpt} that describes the item's initializer.\n   */\n  readonly initializerExcerpt?: Excerpt;\n\n  /** @override */\n  serializeInto(jsonObject: Partial<IApiInitializerMixinJson>): void;\n}\n\n/**\n * Mixin function for {@link (ApiInitializerMixin:interface)}.\n *\n * @param baseClass - The base class to be extended\n * @returns A child class that extends baseClass, adding the {@link (ApiInitializerMixin:interface)} functionality.\n *\n * @public\n */\nexport function ApiInitializerMixin<TBaseClass extends IApiItemConstructor>(\n  baseClass: TBaseClass\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n): TBaseClass & (new (...args: any[]) => ApiInitializerMixin) {\n  class MixedClass extends baseClass implements ApiInitializerMixin {\n    public [_initializerExcerpt]?: Excerpt;\n\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    public constructor(...args: any[]) {\n      super(...args);\n\n      const options: IApiInitializerMixinOptions = args[0];\n\n      if (this instanceof ApiDeclaredItem) {\n        if (options.initializerTokenRange) {\n          this[_initializerExcerpt] = this.buildExcerpt(options.initializerTokenRange);\n        }\n      } else {\n        throw new InternalError(\n          'ApiInitializerMixin expects a base class that inherits from ApiDeclaredItem'\n        );\n      }\n    }\n\n    /** @override */\n    public static onDeserializeInto(\n      options: Partial<IApiInitializerMixinOptions>,\n      context: DeserializerContext,\n      jsonObject: IApiInitializerMixinJson\n    ): void {\n      baseClass.onDeserializeInto(options, context, jsonObject);\n\n      options.initializerTokenRange = jsonObject.initializerTokenRange;\n    }\n\n    public get initializerExcerpt(): Excerpt | undefined {\n      return this[_initializerExcerpt];\n    }\n\n    /** @override */\n    public serializeInto(jsonObject: Partial<IApiInitializerMixinJson>): void {\n      super.serializeInto(jsonObject);\n\n      // Note that JSON does not support the \"undefined\" value, so we simply omit the field entirely if it is undefined\n      if (this.initializerExcerpt) {\n        jsonObject.initializerTokenRange = this.initializerExcerpt.tokenRange;\n      }\n    }\n  }\n\n  return MixedClass;\n}\n\n/**\n * Static members for {@link (ApiInitializerMixin:interface)}.\n * @public\n */\nexport namespace ApiInitializerMixin {\n  /**\n   * A type guard that tests whether the specified `ApiItem` subclass extends the `ApiInitializerMixin` mixin.\n   *\n   * @remarks\n   *\n   * The JavaScript `instanceof` operator cannot be used to test for mixin inheritance, because each invocation of\n   * the mixin function produces a different subclass.  (This could be mitigated by `Symbol.hasInstance`, however\n   * the TypeScript type system cannot invoke a runtime test.)\n   */\n  export function isBaseClassOf(apiItem: ApiItem): apiItem is ApiInitializerMixin {\n    return apiItem.hasOwnProperty(_initializerExcerpt);\n  }\n}\n"]}