Skip to content

Commit 4e02075

Browse files
octogonzoctogonz
committed
Rename APIs:
- ApiItem.canonicalReference --> .containerKey - ApiItemContainerMixin.tryGetMember() --> .tryGetMemberByKey() - Api___.getCanonicalReference() --> .getContainerKey()
1 parent e297423 commit 4e02075

23 files changed

Lines changed: 178 additions & 157 deletions

‎apps/api-extractor-model/src/items/ApiItem.ts‎

Lines changed: 19 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ export interface IApiItemOptions {
4444

4545
export interface IApiItemJson {
4646
kind: ApiItemKind;
47-
canonicalReference: string;
47+
containerKey: string;
4848
}
4949

5050
/**
@@ -85,17 +85,29 @@ export class ApiItem {
8585
/** @virtual */
8686
public serializeInto(jsonObject: Partial<IApiItemJson>): void {
8787
jsonObject.kind = this.kind;
88-
jsonObject.canonicalReference = this.canonicalReference;
88+
jsonObject.containerKey = this.containerKey;
8989
}
9090

91-
/** @virtual */
91+
/**
92+
* Identifies the subclass of the `ApiItem` base class.
93+
* @virtual
94+
*/
9295
public get kind(): ApiItemKind {
9396
throw new Error('ApiItem.kind was not implemented by the child class');
9497
}
9598

96-
/** @virtual */
97-
public get canonicalReference(): string {
98-
throw new Error('ApiItem.canonicalReference was not implemented by the child class');
99+
/**
100+
* Returns a string key that can be used to efficiently retrieve an `ApiItem` from an `ApiItemContainerMixin`.
101+
* The key is unique within the container. Its format is undocumented and may change at any time.
102+
*
103+
* @remarks
104+
* Use the `getContainerKey()` static member to construct the key. Each subclass has a different implementation
105+
* of this function, according to the aspects that are important for identifying it.
106+
*
107+
* @virtual
108+
*/
109+
public get containerKey(): string {
110+
throw new Error('ApiItem.containerKey was not implemented by the child class');
99111
}
100112

101113
/**
@@ -203,7 +215,7 @@ export class ApiItem {
203215

204216
/** @virtual */
205217
public getSortKey(): string {
206-
return this.canonicalReference;
218+
return this.containerKey;
207219
}
208220
}
209221

‎apps/api-extractor-model/src/mixins/ApiItemContainerMixin.ts‎

Lines changed: 16 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ export interface IApiItemContainerJson extends IApiItemJson {
1919

2020
const _members: unique symbol = Symbol('ApiItemContainerMixin._members');
2121
const _membersSorted: unique symbol = Symbol('ApiItemContainerMixin._membersSorted');
22-
const _membersByCanonicalReference: unique symbol = Symbol('ApiItemContainerMixin._membersByCanonicalReference');
22+
const _membersByContainerKey: unique symbol = Symbol('ApiItemContainerMixin._membersByContainerKey');
2323
const _membersByName: unique symbol = Symbol('ApiItemContainerMixin._membersByName');
2424

2525
/**
@@ -58,9 +58,15 @@ export interface ApiItemContainerMixin extends ApiItem {
5858
addMember(member: ApiItem): void;
5959

6060
/**
61-
* Attempts to retrieve a member using its canonicalReference, or returns undefined if no matching member was found.
61+
* Attempts to retrieve a member using its containerKey, or returns `undefined` if no matching member was found.
62+
*
63+
* @remarks
64+
* Use the `getContainerKey()` static member to construct the key. Each subclass has a different implementation
65+
* of this function, according to the aspects that are important for identifying it.
66+
*
67+
* See {@link ApiItem.containerKey} for more information.
6268
*/
63-
tryGetMember(canonicalReference: string): ApiItem | undefined;
69+
tryGetMemberByKey(containerKey: string): ApiItem | undefined;
6470

6571
/**
6672
* Returns a list of members with the specified name.
@@ -85,7 +91,7 @@ export function ApiItemContainerMixin<TBaseClass extends IApiItemConstructor>(ba
8591
abstract class MixedClass extends baseClass implements ApiItemContainerMixin {
8692
public readonly [_members]: ApiItem[];
8793
public [_membersSorted]: boolean;
88-
public [_membersByCanonicalReference]: Map<string, ApiItem>;
94+
public [_membersByContainerKey]: Map<string, ApiItem>;
8995
public [_membersByName]: Map<string, ApiItem[]> | undefined;
9096

9197
/** @override */
@@ -106,7 +112,7 @@ export function ApiItemContainerMixin<TBaseClass extends IApiItemConstructor>(ba
106112
const options: IApiItemContainerMixinOptions = args[0] as IApiItemContainerMixinOptions;
107113

108114
this[_members] = [];
109-
this[_membersByCanonicalReference] = new Map<string, ApiItem>();
115+
this[_membersByContainerKey] = new Map<string, ApiItem>();
110116

111117
if (options.members) {
112118
for (const member of options.members) {
@@ -125,8 +131,8 @@ export function ApiItemContainerMixin<TBaseClass extends IApiItemConstructor>(ba
125131
}
126132

127133
public addMember(member: ApiItem): void {
128-
if (this[_membersByCanonicalReference].has(member.canonicalReference)) {
129-
throw new Error('Another member has already been added with the same name and canonicalReference');
134+
if (this[_membersByContainerKey].has(member.containerKey)) {
135+
throw new Error('Another member has already been added with the same name and containerKey');
130136
}
131137

132138
const existingParent: ApiItem | undefined = member[ApiItem_parent];
@@ -137,13 +143,13 @@ export function ApiItemContainerMixin<TBaseClass extends IApiItemConstructor>(ba
137143
this[_members].push(member);
138144
this[_membersByName] = undefined; // invalidate the lookup
139145
this[_membersSorted] = false;
140-
this[_membersByCanonicalReference].set(member.canonicalReference, member);
146+
this[_membersByContainerKey].set(member.containerKey, member);
141147

142148
member[ApiItem_parent] = this;
143149
}
144150

145-
public tryGetMember(canonicalReference: string): ApiItem | undefined {
146-
return this[_membersByCanonicalReference].get(canonicalReference);
151+
public tryGetMemberByKey(containerKey: string): ApiItem | undefined {
152+
return this[_membersByContainerKey].get(containerKey);
147153
}
148154

149155
public findMembersByName(name: string): ReadonlyArray<ApiItem> {

‎apps/api-extractor-model/src/model/ApiCallSignature.ts‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -52,8 +52,8 @@ export interface IApiCallSignatureOptions extends
5252
export class ApiCallSignature extends ApiTypeParameterListMixin(ApiParameterListMixin(ApiReleaseTagMixin(
5353
ApiReturnTypeMixin(ApiDeclaredItem)))) {
5454

55-
public static getCanonicalReference(overloadIndex: number): string {
56-
return `(:call,${overloadIndex})`;
55+
public static getContainerKey(overloadIndex: number): string {
56+
return `|${ApiItemKind.CallSignature}|${overloadIndex}`;
5757
}
5858

5959
public constructor(options: IApiCallSignatureOptions) {
@@ -66,7 +66,7 @@ export class ApiCallSignature extends ApiTypeParameterListMixin(ApiParameterList
6666
}
6767

6868
/** @override */
69-
public get canonicalReference(): string {
70-
return ApiCallSignature.getCanonicalReference(this.overloadIndex);
69+
public get containerKey(): string {
70+
return ApiCallSignature.getContainerKey(this.overloadIndex);
7171
}
7272
}

‎apps/api-extractor-model/src/model/ApiClass.ts‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -60,8 +60,8 @@ export class ApiClass extends ApiItemContainerMixin(ApiNameMixin(ApiTypeParamete
6060

6161
private readonly _implementsTypes: HeritageType[] = [];
6262

63-
public static getCanonicalReference(name: string): string {
64-
return `(${name}:class)`;
63+
public static getContainerKey(name: string): string {
64+
return `${name}|${ApiItemKind.Class}`;
6565
}
6666

6767
/** @override */
@@ -94,8 +94,8 @@ export class ApiClass extends ApiItemContainerMixin(ApiNameMixin(ApiTypeParamete
9494
}
9595

9696
/** @override */
97-
public get canonicalReference(): string {
98-
return ApiClass.getCanonicalReference(this.name);
97+
public get containerKey(): string {
98+
return ApiClass.getContainerKey(this.name);
9999
}
100100

101101
/**

‎apps/api-extractor-model/src/model/ApiConstructSignature.ts‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -65,8 +65,8 @@ export interface IApiConstructSignatureOptions extends
6565
export class ApiConstructSignature extends ApiTypeParameterListMixin(ApiParameterListMixin(ApiReleaseTagMixin(
6666
ApiReturnTypeMixin(ApiDeclaredItem)))) {
6767

68-
public static getCanonicalReference(overloadIndex: number): string {
69-
return `(:new,${overloadIndex})`;
68+
public static getContainerKey(overloadIndex: number): string {
69+
return `|${ApiItemKind.ConstructSignature}|${overloadIndex}`;
7070
}
7171

7272
public constructor(options: IApiConstructSignatureOptions) {
@@ -79,7 +79,7 @@ export class ApiConstructSignature extends ApiTypeParameterListMixin(ApiParamete
7979
}
8080

8181
/** @override */
82-
public get canonicalReference(): string {
83-
return ApiConstructSignature.getCanonicalReference(this.overloadIndex);
82+
public get containerKey(): string {
83+
return ApiConstructSignature.getContainerKey(this.overloadIndex);
8484
}
8585
}

‎apps/api-extractor-model/src/model/ApiConstructor.ts‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -45,8 +45,8 @@ export interface IApiConstructorOptions extends
4545
*/
4646
export class ApiConstructor extends ApiParameterListMixin(ApiReleaseTagMixin(ApiDeclaredItem)) {
4747

48-
public static getCanonicalReference(overloadIndex: number): string {
49-
return `(:constructor,${overloadIndex})`;
48+
public static getContainerKey(overloadIndex: number): string {
49+
return `|${ApiItemKind.Constructor}|${overloadIndex}`;
5050
}
5151

5252
public constructor(options: IApiConstructorOptions) {
@@ -59,7 +59,7 @@ export class ApiConstructor extends ApiParameterListMixin(ApiReleaseTagMixin(Api
5959
}
6060

6161
/** @override */
62-
public get canonicalReference(): string {
63-
return ApiConstructor.getCanonicalReference(this.overloadIndex);
62+
public get containerKey(): string {
63+
return ApiConstructor.getContainerKey(this.overloadIndex);
6464
}
6565
}

‎apps/api-extractor-model/src/model/ApiEntryPoint.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,8 @@ export class ApiEntryPoint extends ApiItemContainerMixin(ApiNameMixin(ApiItem))
4747
}
4848

4949
/** @override */
50-
public get canonicalReference(): string {
50+
public get containerKey(): string {
51+
// No prefix needed, because ApiEntryPoint is the only possible member of an ApiPackage
5152
return this.name;
5253
}
5354
}

‎apps/api-extractor-model/src/model/ApiEnum.ts‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -41,8 +41,8 @@ export interface IApiEnumOptions extends
4141
*/
4242
export class ApiEnum extends ApiItemContainerMixin(ApiNameMixin(ApiReleaseTagMixin(ApiDeclaredItem))) {
4343

44-
public static getCanonicalReference(name: string): string {
45-
return `(${name}:enum)`;
44+
public static getContainerKey(name: string): string {
45+
return `${name}|${ApiItemKind.Enum}`;
4646
}
4747

4848
public constructor(options: IApiEnumOptions) {
@@ -60,8 +60,8 @@ export class ApiEnum extends ApiItemContainerMixin(ApiNameMixin(ApiReleaseTagMix
6060
}
6161

6262
/** @override */
63-
public get canonicalReference(): string {
64-
return ApiEnum.getCanonicalReference(this.name);
63+
public get containerKey(): string {
64+
return ApiEnum.getContainerKey(this.name);
6565
}
6666

6767
/** @override */

‎apps/api-extractor-model/src/model/ApiEnumMember.ts‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,8 @@ export class ApiEnumMember extends ApiNameMixin(ApiReleaseTagMixin(ApiDeclaredIt
5050
*/
5151
public readonly initializerExcerpt: Excerpt;
5252

53-
public static getCanonicalReference(name: string): string {
53+
public static getContainerKey(name: string): string {
54+
// No prefix needed, because ApiEnumMember is the only possible member of an ApiEnum
5455
return name;
5556
}
5657

@@ -75,8 +76,8 @@ export class ApiEnumMember extends ApiNameMixin(ApiReleaseTagMixin(ApiDeclaredIt
7576
}
7677

7778
/** @override */
78-
public get canonicalReference(): string {
79-
return ApiEnumMember.getCanonicalReference(this.name);
79+
public get containerKey(): string {
80+
return ApiEnumMember.getContainerKey(this.name);
8081
}
8182

8283
/** @override */

‎apps/api-extractor-model/src/model/ApiFunction.ts‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -46,8 +46,8 @@ export interface IApiFunctionOptions extends
4646
export class ApiFunction extends ApiNameMixin(ApiTypeParameterListMixin(ApiParameterListMixin(ApiReleaseTagMixin(
4747
ApiReturnTypeMixin(ApiDeclaredItem))))) {
4848

49-
public static getCanonicalReference(name: string, overloadIndex: number): string {
50-
return `(${name}:${overloadIndex})`;
49+
public static getContainerKey(name: string, overloadIndex: number): string {
50+
return `${name}|${ApiItemKind.Function}|${overloadIndex}`;
5151
}
5252

5353
public constructor(options: IApiFunctionOptions) {
@@ -60,7 +60,7 @@ export class ApiFunction extends ApiNameMixin(ApiTypeParameterListMixin(ApiParam
6060
}
6161

6262
/** @override */
63-
public get canonicalReference(): string {
64-
return ApiFunction.getCanonicalReference(this.name, this.overloadIndex);
63+
public get containerKey(): string {
64+
return ApiFunction.getContainerKey(this.name, this.overloadIndex);
6565
}
6666
}

0 commit comments

Comments
 (0)