From e6db276347ab532249d455a7bf3d39a0d6b0f724 Mon Sep 17 00:00:00 2001 From: Andrew Thauer Date: Thu, 30 Jun 2022 09:38:41 -0400 Subject: [PATCH] update api report for cost-insight types Signed-off-by: Andrew Thauer --- plugins/cost-insights-common/api-report.md | 36 +--- .../src/types/ChangeStatistic.ts | 3 + .../src/types/ChartData.ts | 3 + .../cost-insights-common/src/types/Cost.ts | 3 + .../src/types/Currency.ts | 3 + .../src/types/DateAggregation.ts | 3 + .../src/types/Duration.ts | 1 + .../cost-insights-common/src/types/Entity.ts | 192 +++++++++--------- .../cost-insights-common/src/types/Filters.ts | 9 + .../cost-insights-common/src/types/Group.ts | 3 + .../cost-insights-common/src/types/Maybe.ts | 3 + .../cost-insights-common/src/types/Metric.ts | 3 + .../src/types/MetricData.ts | 3 + .../cost-insights-common/src/types/Product.ts | 3 + .../cost-insights-common/src/types/Project.ts | 3 + .../src/types/Trendline.ts | 4 + 16 files changed, 147 insertions(+), 128 deletions(-) diff --git a/plugins/cost-insights-common/api-report.md b/plugins/cost-insights-common/api-report.md index af95e8765b..daf8f5767d 100644 --- a/plugins/cost-insights-common/api-report.md +++ b/plugins/cost-insights-common/api-report.md @@ -3,8 +3,6 @@ > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/). ```ts -// Warning: (ae-missing-release-tag) "ChangeStatistic" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export interface ChangeStatistic { // (undocumented) @@ -13,8 +11,6 @@ export interface ChangeStatistic { ratio?: number; } -// Warning: (ae-missing-release-tag) "ChartData" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export type ChartData = { date: number; @@ -23,8 +19,6 @@ export type ChartData = { [key: string]: number; }; -// Warning: (ae-missing-release-tag) "Cost" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export interface Cost { // (undocumented) @@ -39,8 +33,6 @@ export interface Cost { trendline?: Trendline; } -// Warning: (ae-missing-release-tag) "Currency" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export interface Currency { // (undocumented) @@ -55,16 +47,12 @@ export interface Currency { unit: string; } -// Warning: (ae-missing-release-tag) "DateAggregation" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export type DateAggregation = { date: string; amount: number; }; -// Warning: (ae-missing-release-tag) "Duration" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export enum Duration { // (undocumented) @@ -77,9 +65,7 @@ export enum Duration { P90D = 'P90D', } -// Warning: (ae-missing-release-tag) "Entity" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export interface Entity { // (undocumented) aggregation: [number, number]; @@ -91,20 +77,14 @@ export interface Entity { id: Maybe; } -// Warning: (ae-missing-release-tag) "Group" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export type Group = { id: string; }; -// Warning: (ae-missing-release-tag) "Maybe" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export type Maybe = T | null; -// Warning: (ae-missing-release-tag) "Metric" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export type Metric = { kind: string; @@ -112,8 +92,6 @@ export type Metric = { default: boolean; }; -// Warning: (ae-missing-release-tag) "MetricData" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export interface MetricData { // (undocumented) @@ -126,8 +104,6 @@ export interface MetricData { id: string; } -// Warning: (ae-missing-release-tag) "PageFilters" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export interface PageFilters { // (undocumented) @@ -140,8 +116,6 @@ export interface PageFilters { project: Maybe; } -// Warning: (ae-missing-release-tag) "Product" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export interface Product { // (undocumented) @@ -150,13 +124,9 @@ export interface Product { name: string; } -// Warning: (ae-missing-release-tag) "ProductFilters" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export type ProductFilters = Array; -// Warning: (ae-missing-release-tag) "ProductPeriod" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export interface ProductPeriod { // (undocumented) @@ -165,8 +135,6 @@ export interface ProductPeriod { productType: string; } -// Warning: (ae-missing-release-tag) "Project" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export interface Project { // (undocumented) @@ -175,8 +143,6 @@ export interface Project { name?: string; } -// Warning: (ae-missing-release-tag) "Trendline" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export type Trendline = { slope: number; diff --git a/plugins/cost-insights-common/src/types/ChangeStatistic.ts b/plugins/cost-insights-common/src/types/ChangeStatistic.ts index 079d9bcb07..29be6e9367 100644 --- a/plugins/cost-insights-common/src/types/ChangeStatistic.ts +++ b/plugins/cost-insights-common/src/types/ChangeStatistic.ts @@ -14,6 +14,9 @@ * limitations under the License. */ +/** + * @public + */ export interface ChangeStatistic { // The ratio of change from one duration to another, expressed as: (newSum - oldSum) / oldSum // If a ratio cannot be calculated - such as when a new or old sum is zero, diff --git a/plugins/cost-insights-common/src/types/ChartData.ts b/plugins/cost-insights-common/src/types/ChartData.ts index 9de8af496d..f4ae204a22 100644 --- a/plugins/cost-insights-common/src/types/ChartData.ts +++ b/plugins/cost-insights-common/src/types/ChartData.ts @@ -14,6 +14,9 @@ * limitations under the License. */ +/** + * @public + */ export type ChartData = { date: number; trend: number; diff --git a/plugins/cost-insights-common/src/types/Cost.ts b/plugins/cost-insights-common/src/types/Cost.ts index 2ae4755bc7..90ccbe17c0 100644 --- a/plugins/cost-insights-common/src/types/Cost.ts +++ b/plugins/cost-insights-common/src/types/Cost.ts @@ -18,6 +18,9 @@ import { DateAggregation } from './DateAggregation'; import { ChangeStatistic } from './ChangeStatistic'; import { Trendline } from './Trendline'; +/** + * @public + */ export interface Cost { id: string; aggregation: DateAggregation[]; diff --git a/plugins/cost-insights-common/src/types/Currency.ts b/plugins/cost-insights-common/src/types/Currency.ts index e82f0c9a52..4bd1490a69 100644 --- a/plugins/cost-insights-common/src/types/Currency.ts +++ b/plugins/cost-insights-common/src/types/Currency.ts @@ -14,6 +14,9 @@ * limitations under the License. */ +/** + * @public + */ export interface Currency { kind: string | null; label: string; diff --git a/plugins/cost-insights-common/src/types/DateAggregation.ts b/plugins/cost-insights-common/src/types/DateAggregation.ts index 72a2514006..4faed85241 100644 --- a/plugins/cost-insights-common/src/types/DateAggregation.ts +++ b/plugins/cost-insights-common/src/types/DateAggregation.ts @@ -14,6 +14,9 @@ * limitations under the License. */ +/** + * @public + */ export type DateAggregation = { date: string; // YYYY-MM-DD amount: number; diff --git a/plugins/cost-insights-common/src/types/Duration.ts b/plugins/cost-insights-common/src/types/Duration.ts index 25806a3346..3a4c7a3a9f 100644 --- a/plugins/cost-insights-common/src/types/Duration.ts +++ b/plugins/cost-insights-common/src/types/Duration.ts @@ -19,6 +19,7 @@ * 'last completed quarter', and P30D/P90D to be '[month|quarter] relative to today'. So if * it's September 15, P3M represents costs for Q2 and P30D represents August 16 - * September 15. + * @public */ export enum Duration { P7D = 'P7D', diff --git a/plugins/cost-insights-common/src/types/Entity.ts b/plugins/cost-insights-common/src/types/Entity.ts index ccfea6667e..9a6d6746aa 100644 --- a/plugins/cost-insights-common/src/types/Entity.ts +++ b/plugins/cost-insights-common/src/types/Entity.ts @@ -17,102 +17,108 @@ import { ChangeStatistic } from './ChangeStatistic'; import { Maybe } from './Maybe'; +/** + * + * An entity is a tree-like structure that represents any unique + * product or service that generates cost over a fixed period of time. + * An entity could be atomic or composite. An atomic entity is indivisible + * and cannot be broken into sub-entities. + * + * A composite entity is divided into sub-entities that account for portions + * of the total cost **over the same time period**. The root entity is + * expected to only have _one_ Record consisting of the sub-entities to display + * in the product panel (keyed by the entity type, such as "service" for + * compute entities). + * + * The root sub-entities may have multiple breakdowns - for example, a + * breakdown of an entity cost by SKU vs deployment environment. The sum + * aggregated cost of each keyed breakdown should equal the sub-entity's cost. + * + * Entities with null ids are considered "unlabeled" - costs without attribution. + * If an entity is a composite, it may only have one (1) null child but may have any number of + * null grandchildren. + * + * @public + * + * @example + * Here's an example composite entity: + * ``` + * const compositeEntity = { + * id: 'product', + * aggregation: [0, 200], + * change: { + * ratio: 2000, + * amount: 200 + * }, + * entities: { + * service: [ + * { + * id: 'service-a', + * aggregation: [0, 100], + * change: { + * ratio: 100, + * amount: 100 + * }, + * entities: {} + * }, + * { + * id: 'service-b', + * aggregation: [0, 100], + * change: { + * ratio: 100, + * amount: 100 + * }, + * entities: { + * SKU: [ + * { + * id: 'service-b-sku-a', + * aggregation: [0, 25], + * change: { + * ratio: 25, + * amount: 25 + * }, + * entities: {} + * }, + * { + * id: null, // Unlabeled cost for service-b + * aggregation: [0, 75], + * change: { + * ratio: 75, + * amount: 75 + * }, + * entities: {} + * }, + * ], + * deployment: [ + * { + * id: 'service-b-env-a', + * aggregation: [0, 50], + * change: { + * ratio: 50, + * amount: 50 + * }, + * entities: {} + * }, + * { + * id: 'service-b-env-b', + * aggregation: [0, 50], + * change: { + * ratio: 50, + * amount: 50 + * }, + * entities: {} + * }, + * ] + * } + * }, + * ] + * } + * } + * ``` + */ export interface Entity { id: Maybe; aggregation: [number, number]; entities: Record; change: ChangeStatistic; } - -/* - An entity is a tree-like structure that represents any unique - product or service that generates cost over a fixed period of time. - An entity could be atomic or composite. An atomic entity is indivisible - and cannot be broken into sub-entities. - - A composite entity is divided into sub-entities that account for portions - of the total cost **over the same time period**. The root entity is - expected to only have _one_ Record consisting of the sub-entities to display - in the product panel (keyed by the entity type, such as "service" for - compute entities). - - The root sub-entities may have multiple breakdowns - for example, a - breakdown of an entity cost by SKU vs deployment environment. The sum - aggregated cost of each keyed breakdown should equal the sub-entity's cost. - - Entities with null ids are considered "unlabeled" - costs without attribution. - If an entity is a composite, it may only have one (1) null child but may have any number of - null grandchildren. - - { - id: 'product', - aggregation: [0, 200], - change: { - ratio: 2000, - amount: 200 - }, - entities: { - service: [ - { - id: 'service-a', - aggregation: [0, 100], - change: { - ratio: 100, - amount: 100 - }, - entities: {} - }, - { - id: 'service-b', - aggregation: [0, 100], - change: { - ratio: 100, - amount: 100 - }, - entities: { - SKU: [ - { - id: 'service-b-sku-a', - aggregation: [0, 25], - change: { - ratio: 25, - amount: 25 - }, - entities: {} - }, - { - id: null, // Unlabeled cost for service-b - aggregation: [0, 75], - change: { - ratio: 75, - amount: 75 - }, - entities: {} - }, - ], - deployment: [ - { - id: 'service-b-env-a', - aggregation: [0, 50], - change: { - ratio: 50, - amount: 50 - }, - entities: {} - }, - { - id: 'service-b-env-b', - aggregation: [0, 50], - change: { - ratio: 50, - amount: 50 - }, - entities: {} - }, - ] - } - }, - ] - } - } -*/ diff --git a/plugins/cost-insights-common/src/types/Filters.ts b/plugins/cost-insights-common/src/types/Filters.ts index 6beef5cacc..67cbb6ce2f 100644 --- a/plugins/cost-insights-common/src/types/Filters.ts +++ b/plugins/cost-insights-common/src/types/Filters.ts @@ -17,6 +17,9 @@ import { Maybe } from './Maybe'; import { Duration } from './Duration'; +/** + * @public + */ export interface PageFilters { group: Maybe; project: Maybe; @@ -24,8 +27,14 @@ export interface PageFilters { metric: string | null; } +/** + * @public + */ export type ProductFilters = Array; +/** + * @public + */ export interface ProductPeriod { duration: Duration; productType: string; diff --git a/plugins/cost-insights-common/src/types/Group.ts b/plugins/cost-insights-common/src/types/Group.ts index 8e0c768924..b34cac083f 100644 --- a/plugins/cost-insights-common/src/types/Group.ts +++ b/plugins/cost-insights-common/src/types/Group.ts @@ -14,6 +14,9 @@ * limitations under the License. */ +/** + * @public + */ export type Group = { id: string; }; diff --git a/plugins/cost-insights-common/src/types/Maybe.ts b/plugins/cost-insights-common/src/types/Maybe.ts index 461c31f6a5..824c64c334 100644 --- a/plugins/cost-insights-common/src/types/Maybe.ts +++ b/plugins/cost-insights-common/src/types/Maybe.ts @@ -14,4 +14,7 @@ * limitations under the License. */ +/** + * @public + */ export type Maybe = T | null; diff --git a/plugins/cost-insights-common/src/types/Metric.ts b/plugins/cost-insights-common/src/types/Metric.ts index 107513b80d..901d40f106 100644 --- a/plugins/cost-insights-common/src/types/Metric.ts +++ b/plugins/cost-insights-common/src/types/Metric.ts @@ -14,6 +14,9 @@ * limitations under the License. */ +/** + * @public + */ export type Metric = { kind: string; name: string; diff --git a/plugins/cost-insights-common/src/types/MetricData.ts b/plugins/cost-insights-common/src/types/MetricData.ts index 225da185f8..56742e76e9 100644 --- a/plugins/cost-insights-common/src/types/MetricData.ts +++ b/plugins/cost-insights-common/src/types/MetricData.ts @@ -17,6 +17,9 @@ import { DateAggregation } from './DateAggregation'; import { ChangeStatistic } from './ChangeStatistic'; +/** + * @public + */ export interface MetricData { id: string; format: 'number' | 'currency'; diff --git a/plugins/cost-insights-common/src/types/Product.ts b/plugins/cost-insights-common/src/types/Product.ts index 9920841223..7ed49c18da 100644 --- a/plugins/cost-insights-common/src/types/Product.ts +++ b/plugins/cost-insights-common/src/types/Product.ts @@ -14,6 +14,9 @@ * limitations under the License. */ +/** + * @public + */ export interface Product { kind: string; name: string; diff --git a/plugins/cost-insights-common/src/types/Project.ts b/plugins/cost-insights-common/src/types/Project.ts index c12a3f1fa2..6cad92ed46 100644 --- a/plugins/cost-insights-common/src/types/Project.ts +++ b/plugins/cost-insights-common/src/types/Project.ts @@ -14,6 +14,9 @@ * limitations under the License. */ +/** + * @public + */ export interface Project { id: string; name?: string; diff --git a/plugins/cost-insights-common/src/types/Trendline.ts b/plugins/cost-insights-common/src/types/Trendline.ts index 64405678f1..3a7e372880 100644 --- a/plugins/cost-insights-common/src/types/Trendline.ts +++ b/plugins/cost-insights-common/src/types/Trendline.ts @@ -13,6 +13,10 @@ * See the License for the specific language governing permissions and * limitations under the License. */ + +/** + * @public + */ export type Trendline = { slope: number; intercept: number;