From 8b14741e79d52a80c5750b3004138d5a3c9f4fe2 Mon Sep 17 00:00:00 2001 From: Ethan Jaffee Date: Wed, 31 Jan 2024 13:12:41 -0500 Subject: [PATCH] EventsSDK: Remove Enums (#125) We learned that using enums in TypeScript is bad practice in favor of types. This updates `Environment`, `Region`, and `VersionLabel` files to use types instead of enums. In addition, we delete the EnumOrString type and update `setupRequestUrl` and relevant tests. [J=FUS-6202 ](https://yexttest.atlassian.net/browse/FUS-6202) R=abenno, mtian TEST=auto --------- Co-authored-by: Ethan Jaffee --- docs/analytics.enumorstring.md | 18 ------- docs/analytics.environment.md | 3 +- docs/analytics.environmentenum.md | 25 --------- docs/analytics.md | 11 +--- docs/analytics.region.md | 3 +- docs/analytics.regionenum.md | 25 --------- docs/analytics.versionlabel.md | 5 +- docs/analytics.versionlabelenum.md | 25 --------- etc/analytics.api.md | 32 ++---------- src/EnumOrString.ts | 9 ---- src/Environment.ts | 17 +----- src/Region.ts | 17 +----- src/VersionLabel.ts | 17 +----- src/index.ts | 1 - src/setupRequestUrl.ts | 12 +++-- test-cdn/index.html | 2 +- test-site/package-lock.json | 10 ++-- tests/AnalyticsEventReporter.test.ts | 22 ++++---- tests/setupRequestUrl.test.ts | 77 +++++++--------------------- 19 files changed, 53 insertions(+), 278 deletions(-) delete mode 100644 docs/analytics.enumorstring.md delete mode 100644 docs/analytics.environmentenum.md delete mode 100644 docs/analytics.regionenum.md delete mode 100644 docs/analytics.versionlabelenum.md delete mode 100644 src/EnumOrString.ts diff --git a/docs/analytics.enumorstring.md b/docs/analytics.enumorstring.md deleted file mode 100644 index 62cb3dd7..00000000 --- a/docs/analytics.enumorstring.md +++ /dev/null @@ -1,18 +0,0 @@ - - -[Home](./index.md) > [@yext/analytics](./analytics.md) > [EnumOrString](./analytics.enumorstring.md) - -## EnumOrString type - -A TypeScript utility type which creates a union of an enum member and its string representation. - -**Signature:** - -```typescript -export type EnumOrString = T | `${T}`; -``` - -## Remarks - -Allows interfaces to support both enums and strings. - diff --git a/docs/analytics.environment.md b/docs/analytics.environment.md index f6c94adc..df55c3a4 100644 --- a/docs/analytics.environment.md +++ b/docs/analytics.environment.md @@ -9,9 +9,8 @@ The Yext Environments **Signature:** ```typescript -export type Environment = EnumOrString; +export type Environment = 'PRODUCTION' | 'SANDBOX' | 'production' | 'sandbox'; ``` -**References:** [EnumOrString](./analytics.enumorstring.md), [EnvironmentEnum](./analytics.environmentenum.md) ## Remarks diff --git a/docs/analytics.environmentenum.md b/docs/analytics.environmentenum.md deleted file mode 100644 index f7e70792..00000000 --- a/docs/analytics.environmentenum.md +++ /dev/null @@ -1,25 +0,0 @@ - - -[Home](./index.md) > [@yext/analytics](./analytics.md) > [EnvironmentEnum](./analytics.environmentenum.md) - -## EnvironmentEnum enum - -An enum for the Yext Environments - -**Signature:** - -```typescript -export declare enum EnvironmentEnum -``` - -## Enumeration Members - -| Member | Value | Description | -| --- | --- | --- | -| Production | "PRODUCTION" | | -| Sandbox | "SANDBOX" | unsupported in the EU region | - -## Remarks - -Affects the domain the requests are sent to. - diff --git a/docs/analytics.md b/docs/analytics.md index a5a290ea..9865c365 100644 --- a/docs/analytics.md +++ b/docs/analytics.md @@ -4,14 +4,6 @@ ## analytics package -## Enumerations - -| Enumeration | Description | -| --- | --- | -| [EnvironmentEnum](./analytics.environmentenum.md) | An enum for the Yext Environments | -| [RegionEnum](./analytics.regionenum.md) | An enum of the physical region the Yext account | -| [VersionLabelEnum](./analytics.versionlabelenum.md) | An enum for the Search Version Labels | - ## Functions | Function | Description | @@ -32,8 +24,7 @@ | Type Alias | Description | | --- | --- | | [Action](./analytics.action.md) | The action types accepted by the Analytics Events API. | -| [EnumOrString](./analytics.enumorstring.md) | A TypeScript utility type which creates a union of an enum member and its string representation. | | [Environment](./analytics.environment.md) | The Yext Environments | | [Region](./analytics.region.md) | The physical region of the Yext account | -| [VersionLabel](./analytics.versionlabel.md) | The Search Version Label | +| [VersionLabel](./analytics.versionlabel.md) | An enum for the Search Version Labels | diff --git a/docs/analytics.region.md b/docs/analytics.region.md index 99d6f086..19cd1641 100644 --- a/docs/analytics.region.md +++ b/docs/analytics.region.md @@ -9,9 +9,8 @@ The physical region of the Yext account **Signature:** ```typescript -export type Region = EnumOrString; +export type Region = 'US' | 'EU' | 'us' | 'eu'; ``` -**References:** [EnumOrString](./analytics.enumorstring.md), [RegionEnum](./analytics.regionenum.md) ## Remarks diff --git a/docs/analytics.regionenum.md b/docs/analytics.regionenum.md deleted file mode 100644 index 2476066b..00000000 --- a/docs/analytics.regionenum.md +++ /dev/null @@ -1,25 +0,0 @@ - - -[Home](./index.md) > [@yext/analytics](./analytics.md) > [RegionEnum](./analytics.regionenum.md) - -## RegionEnum enum - -An enum of the physical region the Yext account - -**Signature:** - -```typescript -export declare enum RegionEnum -``` - -## Enumeration Members - -| Member | Value | Description | -| --- | --- | --- | -| EU | "eu" | | -| US | "us" | | - -## Remarks - -Affects the domain the requests are sent to. - diff --git a/docs/analytics.versionlabel.md b/docs/analytics.versionlabel.md index f4eb2945..6d8bfa36 100644 --- a/docs/analytics.versionlabel.md +++ b/docs/analytics.versionlabel.md @@ -4,14 +4,13 @@ ## VersionLabel type -The Search Version Label +An enum for the Search Version Labels **Signature:** ```typescript -export type VersionLabel = EnumOrString; +export type VersionLabel = 'PRODUCTION' | 'STAGING'; ``` -**References:** [EnumOrString](./analytics.enumorstring.md), [VersionLabelEnum](./analytics.versionlabelenum.md) ## Remarks diff --git a/docs/analytics.versionlabelenum.md b/docs/analytics.versionlabelenum.md deleted file mode 100644 index 0b4a3911..00000000 --- a/docs/analytics.versionlabelenum.md +++ /dev/null @@ -1,25 +0,0 @@ - - -[Home](./index.md) > [@yext/analytics](./analytics.md) > [VersionLabelEnum](./analytics.versionlabelenum.md) - -## VersionLabelEnum enum - -An enum for the Search Version Labels - -**Signature:** - -```typescript -export declare enum VersionLabelEnum -``` - -## Enumeration Members - -| Member | Value | Description | -| --- | --- | --- | -| Production | "PRODUCTION" | | -| Staging | "STAGING" | | - -## Remarks - -Affects the contents of the versionLabel field in the search object field in the event payload. - diff --git a/etc/analytics.api.md b/etc/analytics.api.md index dd210080..fd159e95 100644 --- a/etc/analytics.api.md +++ b/etc/analytics.api.md @@ -27,17 +27,7 @@ export interface AnalyticsEventService { } // @public -export type EnumOrString = T | `${T}`; - -// @public -export type Environment = EnumOrString; - -// @public -export enum EnvironmentEnum { - // (undocumented) - Production = "PRODUCTION", - Sandbox = "SANDBOX" -} +export type Environment = 'PRODUCTION' | 'SANDBOX' | 'production' | 'sandbox'; // @public export interface EventPayload { @@ -100,29 +90,13 @@ export interface EventPayload { } // @public -export type Region = EnumOrString; - -// @public -export enum RegionEnum { - // (undocumented) - EU = "eu", - // (undocumented) - US = "us" -} +export type Region = 'US' | 'EU' | 'us' | 'eu'; // @public export function reportBrowserAnalytics(): Promise; // @public -export type VersionLabel = EnumOrString; - -// @public -export enum VersionLabelEnum { - // (undocumented) - Production = "PRODUCTION", - // (undocumented) - Staging = "STAGING" -} +export type VersionLabel = 'PRODUCTION' | 'STAGING'; // (No @packageDocumentation comment for this package) diff --git a/src/EnumOrString.ts b/src/EnumOrString.ts deleted file mode 100644 index 43a038e3..00000000 --- a/src/EnumOrString.ts +++ /dev/null @@ -1,9 +0,0 @@ -/** - * A TypeScript utility type which creates a union of an enum member and its string representation. - * - * @remarks - * Allows interfaces to support both enums and strings. - * - * @public - */ -export type EnumOrString = T | `${T}`; diff --git a/src/Environment.ts b/src/Environment.ts index f34e58fc..5001cdb4 100644 --- a/src/Environment.ts +++ b/src/Environment.ts @@ -1,18 +1,3 @@ -import { EnumOrString } from './EnumOrString'; -/** - * An enum for the Yext Environments - * - * @remarks - * Affects the domain the requests are sent to. - * - * @public - */ -export enum EnvironmentEnum { - Production = 'PRODUCTION', - /** unsupported in the EU region */ - Sandbox = 'SANDBOX' -} - /** * The Yext Environments * @@ -21,4 +6,4 @@ export enum EnvironmentEnum { * * @public */ -export type Environment = EnumOrString; +export type Environment = 'PRODUCTION' | 'SANDBOX' | 'production' | 'sandbox'; diff --git a/src/Region.ts b/src/Region.ts index 5cfde3f8..f476ef9a 100644 --- a/src/Region.ts +++ b/src/Region.ts @@ -1,17 +1,3 @@ -import { EnumOrString } from './EnumOrString'; -/** - * An enum of the physical region the Yext account - * - * @remarks - * Affects the domain the requests are sent to. - * - * @public - */ -export enum RegionEnum { - US = 'us', - EU = 'eu' -} - /** * The physical region of the Yext account * @@ -20,4 +6,5 @@ export enum RegionEnum { * * @public */ -export type Region = EnumOrString; + +export type Region = 'US' | 'EU' | 'us' | 'eu'; diff --git a/src/VersionLabel.ts b/src/VersionLabel.ts index 4cddfd2f..eca5ddac 100644 --- a/src/VersionLabel.ts +++ b/src/VersionLabel.ts @@ -1,5 +1,3 @@ -import { EnumOrString } from './EnumOrString'; - /** * An enum for the Search Version Labels * @@ -8,17 +6,4 @@ import { EnumOrString } from './EnumOrString'; * * @public */ -export enum VersionLabelEnum { - Production = 'PRODUCTION', - Staging = 'STAGING' -} - -/** - * The Search Version Label - * - * @remarks - * Affects the contents of the versionLabel field in the search object field in the event payload. - * - * @public - */ -export type VersionLabel = EnumOrString; +export type VersionLabel = 'PRODUCTION' | 'STAGING'; diff --git a/src/index.ts b/src/index.ts index b2fa8fd2..0edd6cb8 100644 --- a/src/index.ts +++ b/src/index.ts @@ -50,7 +50,6 @@ export * from './AnalyticsEventService'; export * from './Environment'; export * from './Region'; export * from './EventPayload'; -export * from './EnumOrString'; export * from './Action'; export * from './VersionLabel'; diff --git a/src/setupRequestUrl.ts b/src/setupRequestUrl.ts index 8495f80d..585b13b7 100644 --- a/src/setupRequestUrl.ts +++ b/src/setupRequestUrl.ts @@ -1,16 +1,18 @@ -import { Environment, EnvironmentEnum } from './Environment'; -import { Region, RegionEnum } from './Region'; +import { Environment } from './Environment'; +import { Region } from './Region'; const urlBase = 'yextevents.com/accounts/me/events'; export function setupRequestUrl(env?: Environment, region?: Region): string { - if (env === EnvironmentEnum.Sandbox && region === RegionEnum.EU) { + const isSandbox = env === 'SANDBOX'; + const lowerRegion = region?.toLowerCase(); + if (isSandbox && lowerRegion === 'eu') { throw new Error('Sandbox environment is not available in the EU region.'); } return ( 'https://' + - (env === EnvironmentEnum.Sandbox ? 'sbx.' : '') + - (region ?? 'us') + + (isSandbox ? 'sbx.' : '') + + (lowerRegion ?? 'us') + '.' + urlBase ); diff --git a/test-cdn/index.html b/test-cdn/index.html index 3b9087b1..89b0a034 100644 --- a/test-cdn/index.html +++ b/test-cdn/index.html @@ -13,7 +13,7 @@ const analyticsProvider = window.AnalyticsSDK.analytics({ key: '', sessionTrackingEnabled: false, - region: 'eu' + region: 'EU' }).with({ action: 'CHAT_LINK_CLICK', pageUrl: 'http://www.yext-test-pageurl.com', diff --git a/test-site/package-lock.json b/test-site/package-lock.json index 67e82c8e..ed566410 100644 --- a/test-site/package-lock.json +++ b/test-site/package-lock.json @@ -23,7 +23,7 @@ }, "..": { "name": "@yext/analytics", - "version": "1.0.0-beta.2", + "version": "1.0.0-beta.3", "license": "BSD-3-Clause", "dependencies": { "ulidx": "^2.0.0" @@ -35,8 +35,8 @@ "@microsoft/api-extractor": "^7.19.4", "@playwright/test": "^1.38.0", "@types/node": "^20.6.0", - "@typescript-eslint/eslint-plugin": "^4.28.2", - "@typescript-eslint/parser": "^4.28.2", + "@typescript-eslint/eslint-plugin": "^6.19.1", + "@typescript-eslint/parser": "^6.19.1", "eslint": "^7.32.0", "fetch-mock-jest": "^1.5.1", "generate-license-file": "^1.3.0", @@ -6079,8 +6079,8 @@ "@microsoft/api-extractor": "^7.19.4", "@playwright/test": "^1.38.0", "@types/node": "^20.6.0", - "@typescript-eslint/eslint-plugin": "^4.28.2", - "@typescript-eslint/parser": "^4.28.2", + "@typescript-eslint/eslint-plugin": "^6.19.1", + "@typescript-eslint/parser": "^6.19.1", "eslint": "^7.32.0", "fetch-mock-jest": "^1.5.1", "generate-license-file": "^1.3.0", diff --git a/tests/AnalyticsEventReporter.test.ts b/tests/AnalyticsEventReporter.test.ts index 1f88fba6..5647c593 100644 --- a/tests/AnalyticsEventReporter.test.ts +++ b/tests/AnalyticsEventReporter.test.ts @@ -1,8 +1,6 @@ import { AnalyticsConfig } from '../src/AnalyticsConfig'; import { AnalyticsEventReporter } from '../src/AnalyticsEventReporter'; -import { RegionEnum } from '../src/Region'; import { postWithBeacon, postWithFetch, useBeacon } from '../src/post'; -import { EnvironmentEnum } from '../src/Environment'; import { getOrSetupSessionId } from '../src/setupSessionId'; import { AnalyticsEventService } from '../src/AnalyticsEventService'; @@ -96,7 +94,7 @@ describe('Test report function', () => { const config: AnalyticsConfig = { authorizationType: 'apiKey', authorization: 'validKey', - region: RegionEnum.EU, + region: 'EU', forceFetch: false }; const reporter = new AnalyticsEventReporter(config).with({ @@ -139,7 +137,7 @@ describe('Test report function', () => { const config: AnalyticsConfig = { authorizationType: 'bearer', authorization: 'bearerToken', - env: EnvironmentEnum.Sandbox + env: 'SANDBOX' }; const reporter = new AnalyticsEventReporter(config).with({ action: 'c_lowercase_custom_action', @@ -354,7 +352,7 @@ describe('Test report function', () => { const config: AnalyticsConfig = { authorizationType: 'apiKey', authorization: 'validKey', - region: RegionEnum.EU, + region: 'EU', forceFetch: false }; const reporter = new AnalyticsEventReporter(config).with({ @@ -400,7 +398,7 @@ describe('Test report function', () => { const config: AnalyticsConfig = { authorizationType: 'apiKey', authorization: 'validKey', - region: RegionEnum.EU, + region: 'EU', forceFetch: false }; @@ -448,7 +446,7 @@ describe('Test report function', () => { const config: AnalyticsConfig = { authorizationType: 'apiKey', authorization: 'validKey', - region: RegionEnum.EU, + region: 'EU', forceFetch: true }; @@ -486,7 +484,7 @@ describe('Test report function', () => { const config: AnalyticsConfig = { authorizationType: 'apiKey', authorization: 'validKey', - region: RegionEnum.EU, + region: 'EU', forceFetch: false }; @@ -525,7 +523,7 @@ describe('Test report function', () => { const config: AnalyticsConfig = { authorizationType: 'apiKey', authorization: 'validKey', - region: RegionEnum.EU, + region: 'EU', forceFetch: false }; @@ -601,7 +599,7 @@ describe('Test report function', () => { const config: AnalyticsConfig = { authorizationType: 'apiKey', authorization: 'validKey', - region: RegionEnum.EU, + region: 'EU', forceFetch: false, sessionTrackingEnabled: true }; @@ -657,7 +655,7 @@ describe('Test report function', () => { }, searchTerm: 'searchTerm', sessionId: 'sessionId', - sites: { + pages: { siteUid: 321, template: 'template' }, @@ -736,7 +734,7 @@ describe('Test report function', () => { }, searchTerm: 'searchTerm', sessionId: 'sessionId', - sites: { + pages: { siteUid: 321, template: 'template' }, diff --git a/tests/setupRequestUrl.test.ts b/tests/setupRequestUrl.test.ts index 9534f25c..98d1e02d 100644 --- a/tests/setupRequestUrl.test.ts +++ b/tests/setupRequestUrl.test.ts @@ -1,71 +1,30 @@ -import { EnvironmentEnum } from '../src/Environment'; -import { RegionEnum } from '../src/Region'; import { setupRequestUrl } from '../src/setupRequestUrl'; describe('setUpRequestUrl Test', () => { - it('should set url correctly for env: prod, region: us using their Enums', () => { - const resultUrl = setupRequestUrl( - EnvironmentEnum.Production, - RegionEnum.US - ); + it('should set url correctly for env: prod, region: US', () => { + const resultUrl = setupRequestUrl('PRODUCTION', 'US'); const expectedUrl = 'https://us.yextevents.com/accounts/me/events'; expect(resultUrl).toEqual(expectedUrl); }); - it('should set url correctly for env: prod, region: us using their string literals', () => { - const resultUrl = setupRequestUrl('PRODUCTION', 'us'); - const expectedUrl = 'https://us.yextevents.com/accounts/me/events'; - - expect(resultUrl).toEqual(expectedUrl); - }); - - it('should set url correctly for env: prod, region: eu using their Enums', () => { - const resultUrl = setupRequestUrl( - EnvironmentEnum.Production, - RegionEnum.EU - ); + it('should set url correctly for env: prod, region: EU', () => { + const resultUrl = setupRequestUrl('PRODUCTION', 'EU'); const expectedUrl = 'https://eu.yextevents.com/accounts/me/events'; expect(resultUrl).toEqual(expectedUrl); }); - it('should set url correctly for env: prod, region: eu using their string literals', () => { - const resultUrl = setupRequestUrl('PRODUCTION', 'eu'); - const expectedUrl = 'https://eu.yextevents.com/accounts/me/events'; - - expect(resultUrl).toEqual(expectedUrl); - }); - - it('should set url correctly for env: sbx, region: us using their Enums', () => { - const resultUrl = setupRequestUrl(EnvironmentEnum.Sandbox, RegionEnum.US); - const expectedUrl = 'https://sbx.us.yextevents.com/accounts/me/events'; - - expect(resultUrl).toEqual(expectedUrl); - }); - - it('should set url correctly for env: sbx, region: us using their string literals', () => { - const resultUrl = setupRequestUrl('SANDBOX', 'us'); + it('should set url correctly for env: sbx, region: US', () => { + const resultUrl = setupRequestUrl('SANDBOX', 'US'); const expectedUrl = 'https://sbx.us.yextevents.com/accounts/me/events'; expect(resultUrl).toEqual(expectedUrl); }); - it('should throw error for env: sbx, region: eu using their Enums', () => { + it('should throw error for env: sbx, region: EU', () => { try { - setupRequestUrl(EnvironmentEnum.Sandbox, RegionEnum.EU); - // Fail test if above expression doesn't throw anything. - expect(true).toBe(false); - } catch (e) { - expect(e.message).toBe( - 'Sandbox environment is not available in the EU region.' - ); - } - }); - - it('should throw error for env: sbx, region: eu using their string literals', () => { - try { - setupRequestUrl('SANDBOX', 'eu'); + setupRequestUrl('SANDBOX', 'EU'); // Fail test if above expression doesn't throw anything. expect(true).toBe(false); } catch (e) { @@ -82,30 +41,30 @@ describe('setUpRequestUrl Test', () => { expect(resultUrl).toEqual(expectedUrl); }); - it('should set url correctly with no env argument passed in using its Enum', () => { - const resultUrl = setupRequestUrl(undefined, RegionEnum.EU); + it('should set url correctly with no env argument passed in', () => { + const resultUrl = setupRequestUrl(undefined, 'EU'); const expectedUrl = 'https://eu.yextevents.com/accounts/me/events'; expect(resultUrl).toEqual(expectedUrl); }); - it('should set url correctly with no env argument passed in using their string literals', () => { - const resultUrl = setupRequestUrl(undefined, 'eu'); - const expectedUrl = 'https://eu.yextevents.com/accounts/me/events'; + it('should set url correctly with no region argument passed in', () => { + const resultUrl = setupRequestUrl('SANDBOX', undefined); + const expectedUrl = 'https://sbx.us.yextevents.com/accounts/me/events'; expect(resultUrl).toEqual(expectedUrl); }); - it('should set url correctly with no region argument passed in using its Enum', () => { - const resultUrl = setupRequestUrl(EnvironmentEnum.Sandbox, undefined); + it('should set url correctly with upper case env and lowercase region', () => { + const resultUrl = setupRequestUrl('SANDBOX', 'us'); const expectedUrl = 'https://sbx.us.yextevents.com/accounts/me/events'; expect(resultUrl).toEqual(expectedUrl); }); - it('should set url correctly with no region argument passed in using their string literals', () => { - const resultUrl = setupRequestUrl('SANDBOX', undefined); - const expectedUrl = 'https://sbx.us.yextevents.com/accounts/me/events'; + it('should set url correctly with lower case env and uppercase region', () => { + const resultUrl = setupRequestUrl('production', 'EU'); + const expectedUrl = 'https://eu.yextevents.com/accounts/me/events'; expect(resultUrl).toEqual(expectedUrl); });