feat: Correct client evaluation typings. (#554)

Some code was refactored to make server and client share evaluation
results. This should not have been done because the results are not the
same in client and server SDKs. Server SDKs can always produce a reason
and client SDKs cannot.

This meant that the typing said that reason was required in the client
SDK, but it could be null.

This is a 'feat' to ensure a minor version bump in case of minor
incompatibilities.

Author: kinyoklion

packages/shared/common/src/api/data/LDEvaluationDetail.ts

@@ -1,6 +1,8 @@
 import { LDEvaluationReason } from './LDEvaluationReason';
 import { LDFlagValue } from './LDFlagValue';
 
+// TODO: On major version change "variationIndex" to only be optional and not nullable.
+
 /**
  * An object that combines the result of a feature flag evaluation with information about
  * how it was calculated.

packages/shared/common/src/internal/evaluation/evaluationDetail.ts

@@ -1,11 +1,4 @@
 import ErrorKinds from './ErrorKinds';
-import { createErrorEvaluationDetail, createSuccessEvaluationDetail } from './evaluationDetail';
 import EventFactoryBase, { EvalEventArgs } from './EventFactoryBase';
 
-export {
-  createSuccessEvaluationDetail,
-  createErrorEvaluationDetail,
-  ErrorKinds,
-  EvalEventArgs,
-  EventFactoryBase,
-};
+export { ErrorKinds, EvalEventArgs, EventFactoryBase };

packages/shared/common/src/internal/evaluation/index.ts

@@ -5,10 +5,10 @@ import {
   setupMockStreamingProcessor,
 } from '@launchdarkly/private-js-mocks';
 
-import LDEmitter from './api/LDEmitter';
 import { toMulti } from './context/addAutoEnv';
 import * as mockResponseJson from './evaluation/mockResponse.json';
 import LDClientImpl from './LDClientImpl';
+import LDEmitter from './LDEmitter';
 import { DeleteFlag, Flags, PatchFlag } from './types';
 
 let mockPlatform: ReturnType<typeof createBasicPlatform>;

packages/shared/sdk-client/src/LDClientImpl.storage.test.ts

@@ -6,8 +6,6 @@ import {
   internal,
   LDClientError,
   LDContext,
-  LDEvaluationDetail,
-  LDEvaluationDetailTyped,
   LDFlagSet,
   LDFlagValue,
   LDLogger,
@@ -20,21 +18,25 @@ import {
 import { LDStreamProcessor } from '@launchdarkly/js-sdk-common/dist/api/subsystem';
 
 import { ConnectionMode, LDClient, type LDOptions } from './api';
-import LDEmitter, { EventName } from './api/LDEmitter';
+import { LDEvaluationDetail, LDEvaluationDetailTyped } from './api/LDEvaluationDetail';
 import { LDIdentifyOptions } from './api/LDIdentifyOptions';
 import Configuration from './configuration';
 import { addAutoEnv } from './context/addAutoEnv';
 import { ensureKey } from './context/ensureKey';
 import createDiagnosticsManager from './diagnostics/createDiagnosticsManager';
+import {
+  createErrorEvaluationDetail,
+  createSuccessEvaluationDetail,
+} from './evaluation/evaluationDetail';
 import createEventProcessor from './events/createEventProcessor';
 import EventFactory from './events/EventFactory';
 import FlagManager from './flag-manager/FlagManager';
 import { ItemDescriptor } from './flag-manager/ItemDescriptor';
+import LDEmitter, { EventName } from './LDEmitter';
 import PollingProcessor from './polling/PollingProcessor';
 import { DeleteFlag, Flags, PatchFlag } from './types';
 
-const { createErrorEvaluationDetail, createSuccessEvaluationDetail, ClientMessages, ErrorKinds } =
-  internal;
+const { ClientMessages, ErrorKinds } = internal;
 
 export default class LDClientImpl implements LDClient {
   private readonly config: Configuration;
@@ -483,7 +485,7 @@ export default class LDClientImpl implements LDClient {
     defaultValue: any,
     eventFactory: EventFactory,
     typeChecker?: (value: any) => [boolean, string],
-  ): LDFlagValue {
+  ): LDEvaluationDetail {
     if (!this.uncheckedContext) {
       this.logger.debug(ClientMessages.missingContextKeyNoEvent);
       return createErrorEvaluationDetail(ErrorKinds.UserNotSpecified, defaultValue);

packages/shared/sdk-client/src/LDClientImpl.ts

@@ -1,13 +1,7 @@
-import {
-  LDContext,
-  LDEvaluationDetail,
-  LDEvaluationDetailTyped,
-  LDFlagSet,
-  LDFlagValue,
-  LDLogger,
-} from '@launchdarkly/js-sdk-common';
+import { LDContext, LDFlagSet, LDFlagValue, LDLogger } from '@launchdarkly/js-sdk-common';
 
 import ConnectionMode from './ConnectionMode';
+import { LDEvaluationDetail, LDEvaluationDetailTyped } from './LDEvaluationDetail';
 import { LDIdentifyOptions } from './LDIdentifyOptions';
 
 /**

packages/shared/sdk-client/src/api/LDEmitter.test.ts renamed to packages/shared/sdk-client/src/LDEmitter.test.ts

@@ -0,0 +1,37 @@
+import {
+  LDEvaluationDetail as CommonDetail,
+  LDEvaluationDetailTyped as CommonDetailTyped,
+  LDEvaluationReason,
+} from '@launchdarkly/js-sdk-common';
+
+// Implementation note: In client-side SDKs the reason is optional. The common type, which is also
+// used by server SDKs, has a required reason. This file contains a client specific
+// LDEvaluationDetail which has an optional reason.
+
+// TODO: On major version change "reason" to be optional instead of nullable.
+
+/**
+ * An object that combines the result of a feature flag evaluation with information about
+ * how it was calculated.
+ *
+ * This is the result of calling `LDClient.variationDetail`.
+ */
+export type LDEvaluationDetail = Omit<CommonDetail, 'reason'> & {
+  /**
+   * An optional object describing the main factor that influenced the flag evaluation value.
+   */
+  reason: LDEvaluationReason | null;
+};
+
+/**
+ * An object that combines the result of a feature flag evaluation with information about
+ * how it was calculated.
+ *
+ * This is the result of calling detailed variation methods.
+ */
+export type LDEvaluationDetailTyped<TFlag> = Omit<CommonDetailTyped<TFlag>, 'reason'> & {
+  /**
+   * An optional object describing the main factor that influenced the flag evaluation value.
+   */
+  reason: LDEvaluationReason | null;
+};