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.

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/index.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/sdk-client/src/LDClientImpl.storage.test.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.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/api/LDClient.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/LDEvaluationDetail.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;
+};

packages/shared/sdk-client/src/api/index.ts

@@ -2,5 +2,6 @@ import ConnectionMode from './ConnectionMode';
 
 export * from './LDOptions';
 export * from './LDClient';
+export * from './LDEvaluationDetail';
 
 export { ConnectionMode };

packages/shared/sdk-client/src/configuration/Configuration.test.ts

@@ -20,7 +20,6 @@ describe('Configuration', () => {
       withReasons: false,
       eventsUri: 'https://events.launchdarkly.com',
       flushInterval: 30,
-      inspectors: [],
       logger: {
         destination: console.error,
         logLevel: 1,
@@ -80,17 +79,6 @@ describe('Configuration', () => {
     );
   });
 
-  test('invalid bootstrap should use default', () => {
-    // @ts-ignore
-    const config = new Configuration({ bootstrap: 'localStora' });
-
-    expect(config.bootstrap).toBeUndefined();
-    expect(console.error).toHaveBeenNthCalledWith(
-      1,
-      expect.stringMatching(/should be of type LDFlagSet, got string/i),
-    );
-  });
-
   test('recognize maxCachedContexts', () => {
     const config = new Configuration({ maxCachedContexts: 3 });
 

packages/shared/sdk-client/src/configuration/Configuration.ts

@@ -10,7 +10,6 @@ import {
 } from '@launchdarkly/js-sdk-common';
 
 import { ConnectionMode, type LDOptions } from '../api';
-import { LDInspection } from '../api/LDInspection';
 import validators from './validators';
 
 const DEFAULT_POLLING_INTERVAL: number = 60 * 5;
@@ -41,7 +40,6 @@ export default class Configuration {
   public readonly useReport = false;
   public readonly withReasons = false;
 
-  public readonly inspectors: LDInspection[] = [];
   public readonly privateAttributes: string[] = [];
 
   public readonly initialConnectionMode: ConnectionMode = 'streaming';

packages/shared/sdk-client/src/configuration/validators.ts

@@ -1,18 +1,7 @@
 // eslint-disable-next-line max-classes-per-file
-import { noop, TypeValidator, TypeValidators } from '@launchdarkly/js-sdk-common';
+import { TypeValidator, TypeValidators } from '@launchdarkly/js-sdk-common';
 
 import { type LDOptions } from '../api';
-import { LDInspection } from '../api/LDInspection';
-
-class BootStrapValidator implements TypeValidator {
-  is(u: unknown): boolean {
-    return typeof u === 'object' || typeof u === 'undefined' || u === null;
-  }
-
-  getType(): string {
-    return `LDFlagSet`;
-  }
-}
 
 class ConnectionModeValidator implements TypeValidator {
   is(u: unknown): boolean {
@@ -46,22 +35,11 @@ const validators: Record<keyof LDOptions, TypeValidator> = {
 
   pollInterval: TypeValidators.numberWithMin(30),
 
-  // TODO: inspectors
-  // @ts-ignore
-  inspectors: TypeValidators.createTypeArray<LDInspection>('LDInspection[]', {
-    type: 'flag-used',
-    method: noop,
-    name: '',
-  }),
   privateAttributes: TypeValidators.StringArray,
 
   applicationInfo: TypeValidators.Object,
-  // TODO: bootstrap
-  bootstrap: new BootStrapValidator(),
   wrapperName: TypeValidators.String,
   wrapperVersion: TypeValidators.String,
-  // TODO: hash
-  hash: TypeValidators.String,
 };
 
 export default validators;

packages/shared/sdk-client/src/diagnostics/createDiagnosticsInitConfig.ts

@@ -26,8 +26,9 @@ const createDiagnosticsInitConfig = (config: Configuration): DiagnosticsInitConf
   reconnectTimeMillis: secondsToMillis(config.streamInitialReconnectDelay),
   diagnosticRecordingIntervalMillis: secondsToMillis(config.diagnosticRecordingInterval),
   allAttributesPrivate: config.allAttributesPrivate,
-  usingSecureMode: !!config.hash,
-  bootstrapMode: !!config.bootstrap,
+  // TODO: Implement when corresponding features are implemented.
+  usingSecureMode: false,
+  bootstrapMode: false,
 });
 
 export default createDiagnosticsInitConfig;

packages/shared/sdk-client/src/evaluation/evaluationDetail.ts

@@ -0,0 +1,26 @@
+import { internal, LDEvaluationReason, LDFlagValue } from '@launchdarkly/js-sdk-common';
+
+import { LDEvaluationDetail } from '../api';
+
+export function createErrorEvaluationDetail(
+  errorKind: internal.ErrorKinds,
+  def?: LDFlagValue,
+): LDEvaluationDetail {
+  return {
+    value: def ?? null,
+    variationIndex: null,
+    reason: { kind: 'ERROR', errorKind },
+  };
+}
+
+export function createSuccessEvaluationDetail(
+  value: LDFlagValue,
+  variationIndex?: number,
+  reason?: LDEvaluationReason,
+): LDEvaluationDetail {
+  return {
+    value,
+    variationIndex: variationIndex ?? null,
+    reason: reason ?? null,
+  };
+}