Skip to content

Commit eecafc6

Browse files
octogonzoctogonz
committed
Introduce a DeserializerContext that can be used to track backward compatibility during deserialization
1 parent 662db07 commit eecafc6

20 files changed

Lines changed: 181 additions & 74 deletions

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

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33

44
import { ApiDocumentedItem, IApiDocumentedItemJson, IApiDocumentedItemOptions } from './ApiDocumentedItem';
55
import { Excerpt, ExcerptToken, IExcerptTokenRange, IExcerptToken } from '../mixins/Excerpt';
6+
import { DeserializerContext } from '../model/DeserializerContext';
67

78
/**
89
* Constructor options for {@link ApiDeclaredItem}.
@@ -35,10 +36,10 @@ export class ApiDeclaredItem extends ApiDocumentedItem {
3536
private _excerpt: Excerpt;
3637

3738
/** @override */
38-
public static onDeserializeInto(options: Partial<IApiDeclaredItemOptions>,
39+
public static onDeserializeInto(options: Partial<IApiDeclaredItemOptions>, context: DeserializerContext,
3940
jsonObject: IApiDeclaredItemJson): void {
4041

41-
super.onDeserializeInto(options, jsonObject);
42+
super.onDeserializeInto(options, context, jsonObject);
4243

4344
options.excerptTokens = jsonObject.excerptTokens;
4445
}

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

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44
import * as tsdoc from '@microsoft/tsdoc';
55
import { ApiItem, IApiItemOptions, IApiItemJson } from './ApiItem';
66
import { AedocDefinitions } from '../aedoc/AedocDefinitions';
7+
import { DeserializerContext } from '../model/DeserializerContext';
78

89
/**
910
* Constructor options for {@link ApiDocumentedItem}.
@@ -31,10 +32,10 @@ export class ApiDocumentedItem extends ApiItem {
3132
private _tsdocComment: tsdoc.DocComment | undefined;
3233

3334
/** @override */
34-
public static onDeserializeInto(options: Partial<IApiDocumentedItemOptions>,
35+
public static onDeserializeInto(options: Partial<IApiDocumentedItemOptions>, context: DeserializerContext,
3536
jsonObject: IApiItemJson): void {
3637

37-
super.onDeserializeInto(options, jsonObject);
38+
super.onDeserializeInto(options, context, jsonObject);
3839

3940
const documentedJson: IApiDocumentedItemJson = jsonObject as IApiDocumentedItemJson;
4041

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

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44
import { Constructor, PropertiesOf } from '../mixins/Mixin';
55
import { ApiPackage } from '../model/ApiPackage';
66
import { ApiParameterListMixin } from '../mixins/ApiParameterListMixin';
7+
import { DeserializerContext } from '../model/DeserializerContext';
78

89
/**
910
* The type returned by the {@link ApiItem.kind} property, which can be used to easily distinguish subclasses of
@@ -64,15 +65,16 @@ export const ApiItem_parent: unique symbol = Symbol('ApiItem._parent');
6465
export class ApiItem {
6566
public [ApiItem_parent]: ApiItem | undefined;
6667

67-
public static deserialize(jsonObject: IApiItemJson): ApiItem {
68+
public static deserialize(jsonObject: IApiItemJson, context: DeserializerContext): ApiItem {
6869
// The Deserializer class is coupled with a ton of other classes, so we delay loading it
6970
// to avoid ES5 circular imports.
7071
const deserializerModule: typeof import('../model/Deserializer') = require('../model/Deserializer');
71-
return deserializerModule.Deserializer.deserialize(jsonObject);
72+
return deserializerModule.Deserializer.deserialize(context, jsonObject);
7273
}
7374

7475
/** @virtual */
75-
public static onDeserializeInto(options: Partial<IApiItemOptions>, jsonObject: IApiItemJson): void {
76+
public static onDeserializeInto(options: Partial<IApiItemOptions>, context: DeserializerContext,
77+
jsonObject: IApiItemJson): void {
7678
// (implemented by subclasses)
7779
}
7880

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

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ import { Excerpt, IExcerptTokenRange } from '../mixins/Excerpt';
55
import { IApiDeclaredItemOptions, ApiDeclaredItem, IApiDeclaredItemJson } from '../items/ApiDeclaredItem';
66
import { ApiReleaseTagMixin, IApiReleaseTagMixinOptions } from '../mixins/ApiReleaseTagMixin';
77
import { IApiNameMixinOptions, ApiNameMixin } from '../mixins/ApiNameMixin';
8+
import { DeserializerContext } from '../model/DeserializerContext';
89

910
/**
1011
* Constructor options for {@link ApiPropertyItem}.
@@ -34,8 +35,10 @@ export class ApiPropertyItem extends ApiNameMixin(ApiReleaseTagMixin(ApiDeclared
3435
public readonly propertyTypeExcerpt: Excerpt;
3536

3637
/** @override */
37-
public static onDeserializeInto(options: Partial<IApiPropertyItemOptions>, jsonObject: IApiPropertyItemJson): void {
38-
super.onDeserializeInto(options, jsonObject);
38+
public static onDeserializeInto(options: Partial<IApiPropertyItemOptions>, context: DeserializerContext,
39+
jsonObject: IApiPropertyItemJson): void {
40+
41+
super.onDeserializeInto(options, context, jsonObject);
3942

4043
options.propertyTypeTokenRange = jsonObject.propertyTypeTokenRange;
4144
}

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

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33

44
import { ApiItem, ApiItem_parent, IApiItemJson, IApiItemOptions, IApiItemConstructor } from '../items/ApiItem';
55
import { ApiNameMixin } from './ApiNameMixin';
6+
import { DeserializerContext } from '../model/DeserializerContext';
67

78
/**
89
* Constructor options for {@link (ApiItemContainerMixin:interface)}.
@@ -89,13 +90,13 @@ export function ApiItemContainerMixin<TBaseClass extends IApiItemConstructor>(ba
8990

9091
/** @override */
9192
public static onDeserializeInto(options: Partial<IApiItemContainerMixinOptions>,
92-
jsonObject: IApiItemContainerJson): void {
93+
context: DeserializerContext, jsonObject: IApiItemContainerJson): void {
9394

94-
baseClass.onDeserializeInto(options, jsonObject);
95+
baseClass.onDeserializeInto(options, context, jsonObject);
9596

9697
options.members = [];
9798
for (const memberObject of jsonObject.members) {
98-
options.members.push(ApiItem.deserialize(memberObject));
99+
options.members.push(ApiItem.deserialize(memberObject, context));
99100
}
100101
}
101102

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

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22
// See LICENSE in the project root for license information.s
33

44
import { ApiItem, IApiItemJson, IApiItemConstructor, IApiItemOptions } from '../items/ApiItem';
5+
import { DeserializerContext } from '../model/DeserializerContext';
56

67
/**
78
* Constructor options for {@link (IApiNameMixinOptions:interface)}.
@@ -62,8 +63,10 @@ export function ApiNameMixin<TBaseClass extends IApiItemConstructor>(baseClass:
6263
public readonly [_name]: string;
6364

6465
/** @override */
65-
public static onDeserializeInto(options: Partial<IApiNameMixinOptions>, jsonObject: IApiNameMixinJson): void {
66-
baseClass.onDeserializeInto(options, jsonObject);
66+
public static onDeserializeInto(options: Partial<IApiNameMixinOptions>, context: DeserializerContext,
67+
jsonObject: IApiNameMixinJson): void {
68+
69+
baseClass.onDeserializeInto(options, context, jsonObject);
6770

6871
options.name = jsonObject.name;
6972
}

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

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ import { Parameter } from '../model/Parameter';
66
import { ApiDeclaredItem } from '../items/ApiDeclaredItem';
77
import { IExcerptTokenRange } from './Excerpt';
88
import { InternalError } from '@microsoft/node-core-library';
9+
import { DeserializerContext } from '../model/DeserializerContext';
910

1011
/**
1112
* Represents parameter information that is part of {@link IApiParameterListMixinOptions}
@@ -103,10 +104,10 @@ export function ApiParameterListMixin<TBaseClass extends IApiItemConstructor>(ba
103104
public readonly [_parameters]: Parameter[];
104105

105106
/** @override */
106-
public static onDeserializeInto(options: Partial<IApiParameterListMixinOptions>,
107+
public static onDeserializeInto(options: Partial<IApiParameterListMixinOptions>, context: DeserializerContext,
107108
jsonObject: IApiParameterListJson): void {
108109

109-
baseClass.onDeserializeInto(options, jsonObject);
110+
baseClass.onDeserializeInto(options, context, jsonObject);
110111

111112
options.overloadIndex = jsonObject.overloadIndex;
112113
options.parameters = jsonObject.parameters || [];

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

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33

44
import { ApiItem, IApiItemJson, IApiItemConstructor, IApiItemOptions } from '../items/ApiItem';
55
import { ReleaseTag } from '../aedoc/ReleaseTag';
6+
import { DeserializerContext } from '../model/DeserializerContext';
67

78
/**
89
* Constructor options for {@link (ApiReleaseTagMixin:interface)}.
@@ -64,10 +65,10 @@ export function ApiReleaseTagMixin<TBaseClass extends IApiItemConstructor>(baseC
6465
public [_releaseTag]: ReleaseTag;
6566

6667
/** @override */
67-
public static onDeserializeInto(options: Partial<IApiReleaseTagMixinOptions>,
68+
public static onDeserializeInto(options: Partial<IApiReleaseTagMixinOptions>, context: DeserializerContext,
6869
jsonObject: IApiReleaseTagMixinJson): void {
6970

70-
baseClass.onDeserializeInto(options, jsonObject);
71+
baseClass.onDeserializeInto(options, context, jsonObject);
7172

7273
const deserializedReleaseTag: ReleaseTag | undefined = ReleaseTag[jsonObject.releaseTag];
7374
if (deserializedReleaseTag === undefined) {

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

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ import { ApiItem, IApiItemJson, IApiItemConstructor, IApiItemOptions } from '../
55
import { IExcerptTokenRange, Excerpt } from './Excerpt';
66
import { ApiDeclaredItem } from '../items/ApiDeclaredItem';
77
import { InternalError } from '@microsoft/node-core-library';
8+
import { DeserializerContext } from '../model/DeserializerContext';
89

910
/**
1011
* Constructor options for {@link (ApiReturnTypeMixin:interface)}.
@@ -61,10 +62,10 @@ export function ApiReturnTypeMixin<TBaseClass extends IApiItemConstructor>(baseC
6162
public [_returnTypeExcerpt]: Excerpt;
6263

6364
/** @override */
64-
public static onDeserializeInto(options: Partial<IApiReturnTypeMixinOptions>,
65+
public static onDeserializeInto(options: Partial<IApiReturnTypeMixinOptions>, context: DeserializerContext,
6566
jsonObject: IApiReturnTypeMixinJson): void {
6667

67-
baseClass.onDeserializeInto(options, jsonObject);
68+
baseClass.onDeserializeInto(options, context, jsonObject);
6869

6970
options.returnTypeTokenRange = jsonObject.returnTypeTokenRange;
7071
}

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

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22
// See LICENSE in the project root for license information.s
33

44
import { ApiItem, IApiItemJson, IApiItemConstructor, IApiItemOptions } from '../items/ApiItem';
5+
import { DeserializerContext } from '../model/DeserializerContext';
56

67
/**
78
* Constructor options for {@link (IApiStaticMixinOptions:interface)}.
@@ -58,8 +59,10 @@ export function ApiStaticMixin<TBaseClass extends IApiItemConstructor>(baseClass
5859
public [_isStatic]: boolean;
5960

6061
/** @override */
61-
public static onDeserializeInto(options: Partial<IApiStaticMixinOptions>, jsonObject: IApiStaticMixinJson): void {
62-
baseClass.onDeserializeInto(options, jsonObject);
62+
public static onDeserializeInto(options: Partial<IApiStaticMixinOptions>, context: DeserializerContext,
63+
jsonObject: IApiStaticMixinJson): void {
64+
65+
baseClass.onDeserializeInto(options, context, jsonObject);
6366

6467
options.isStatic = jsonObject.isStatic;
6568
}

0 commit comments

Comments
 (0)