feat: Correct client evaluation typings.

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.ts

@@ -6,8 +6,6 @@
   internal,
   LDClientError,
   LDContext,
-  LDEvaluationDetail,
-  LDEvaluationDetailTyped,
   LDFlagSet,
   LDFlagValue,
   LDLogger,
@@ -20,21 +18,25 @@
 import { LDStreamProcessor } from '@launchdarkly/js-sdk-common/dist/api/subsystem';
 
 import { ConnectionMode, LDClient, type LDOptions } from './api';
-import LDEmitter, { EventName } from './api/LDEmitter';
+import LDEmitter, { EventName } from './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 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 @@
     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,

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,10 +1,9 @@
 // eslint-disable-next-line max-classes-per-file
 import { noop, 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;
   }
@@ -46,22 +45,11 @@
 
   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/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,
+  };
+}

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

@@ -1,8 +1,19 @@
 import LDClientImpl from './LDClientImpl';
 
+export * from '@launchdarkly/js-sdk-common';
+
 export * as platform from '@launchdarkly/js-sdk-common';
-export * from './api';
 
-export * from '@launchdarkly/js-sdk-common';
+// To replace the exports from `export *` we need to name them.
+// So the below exports replace them with the Node specific variants.
+
+// These exports are explicit to override those from common.
+export type {
+  LDEvaluationDetail,
+  LDEvaluationDetailTyped,
+  LDClient,
+  LDOptions,
+  ConnectionMode,
+} from './api';
 
 export { LDClientImpl };

packages/shared/sdk-server/src/evaluation/EvalResult.ts

@@ -2,7 +2,6 @@ import { internal, LDEvaluationDetail, LDEvaluationReason } from '@launchdarkly/
 
 import Reasons from './Reasons';
 
-const { createErrorEvaluationDetail, createSuccessEvaluationDetail } = internal;
 /**
  * A class which encapsulates the result of an evaluation. It allows for differentiating between
  * successful and error result types.
@@ -31,11 +30,22 @@ export default class EvalResult {
   }
 
   static forError(errorKind: internal.ErrorKinds, message?: string, def?: any): EvalResult {
-    return new EvalResult(true, createErrorEvaluationDetail(errorKind, def), message);
+    return new EvalResult(
+      true,
+      {
+        value: def ?? null,
+        variationIndex: null,
+        reason: { kind: 'ERROR', errorKind },
+      },
+      message,
+    );
   }
 
   static forSuccess(value: any, reason: LDEvaluationReason, variationIndex?: number) {
-    const successDetail = createSuccessEvaluationDetail(value, variationIndex, reason);
-    return new EvalResult(false, successDetail as LDEvaluationDetail);
+    return new EvalResult(false, {
+      value,
+      variationIndex: variationIndex === undefined ? null : variationIndex,
+      reason,
+    });
   }
 }