chore: added tsdoc for hooks. corrected LDClient variation tsdoc errors.

packages/sdk/react-native/src/hooks/variation/useTypedVariation.ts

@@ -2,53 +2,81 @@ import { LDEvaluationDetailTyped } from '@launchdarkly/js-client-sdk-common';
 
 import useLDClient from '../useLDClient';
 
+/**
+ * Determines the strongly typed variation of a feature flag.
+ *
+ * @param key The unique key of the feature flag.
+ * @param defaultValue The default value of the flag, to be used if the value is not available
+ *   from LaunchDarkly.
+ * @returns
+ *   The strongly typed value.
+ */
 export const useTypedVariation = <T extends boolean | number | string | unknown>(
-  flagKey: string,
+  key: string,
   defaultValue: T,
 ): T => {
   const ldClient = useLDClient();
 
   switch (typeof defaultValue) {
     case 'boolean':
-      return ldClient.boolVariation(flagKey, defaultValue as boolean) as T;
+      return ldClient.boolVariation(key, defaultValue as boolean) as T;
     case 'number':
-      return ldClient.numberVariation(flagKey, defaultValue as number) as T;
+      return ldClient.numberVariation(key, defaultValue as number) as T;
     case 'string':
-      return ldClient.stringVariation(flagKey, defaultValue as string) as T;
+      return ldClient.stringVariation(key, defaultValue as string) as T;
     case 'undefined':
     case 'object':
-      return ldClient.jsonVariation(flagKey, defaultValue) as T;
+      return ldClient.jsonVariation(key, defaultValue) as T;
     default:
-      return ldClient.variation(flagKey, defaultValue);
+      return ldClient.variation(key, defaultValue);
   }
 };
 
+/**
+ * Determines the strongly typed variation of a feature flag for a context, along with information about
+ * how it was calculated.
+ *
+ * The `reason` property of the result will also be included in analytics events, if you are
+ * capturing detailed event data for this flag.
+ *
+ * If the flag variation does not have the specified type, defaultValue is returned. The reason will
+ * indicate an error of the type `WRONG_KIND` in this case.
+ *
+ * For more information, see the [SDK reference
+ * guide](https://docs.launchdarkly.com/sdk/features/evaluation-reasons#react-native).
+ *
+ * @param key The unique key of the feature flag.
+ * @param defaultValue The default value of the flag, to be used if the value is not available
+ *   from LaunchDarkly.
+ * @returns
+ *  The result (as an {@link LDEvaluationDetailTyped<T>}).
+ */
 export const useTypedVariationDetail = <T extends boolean | number | string | unknown>(
-  flagKey: string,
+  key: string,
   defaultValue: T,
 ): LDEvaluationDetailTyped<T> => {
   const ldClient = useLDClient();
 
   switch (typeof defaultValue) {
     case 'boolean':
       return ldClient.boolVariationDetail(
-        flagKey,
+        key,
         defaultValue as boolean,
       ) as LDEvaluationDetailTyped<T>;
     case 'number':
       return ldClient.numberVariationDetail(
-        flagKey,
+        key,
         defaultValue as number,
       ) as LDEvaluationDetailTyped<T>;
     case 'string':
       return ldClient.stringVariationDetail(
-        flagKey,
+        key,
         defaultValue as string,
       ) as LDEvaluationDetailTyped<T>;
     case 'undefined':
     case 'object':
-      return ldClient.jsonVariationDetail(flagKey, defaultValue) as LDEvaluationDetailTyped<T>;
+      return ldClient.jsonVariationDetail(key, defaultValue) as LDEvaluationDetailTyped<T>;
     default:
-      return ldClient.variationDetail(flagKey, defaultValue);
+      return ldClient.variationDetail(key, defaultValue);
   }
 };

packages/sdk/react-native/src/hooks/variation/useVariation.ts

@@ -1,25 +1,147 @@
 import { useTypedVariation, useTypedVariationDetail } from './useTypedVariation';
 
-export const useBoolVariation = (flagKey: string, defaultValue: boolean) =>
-  useTypedVariation<boolean>(flagKey, defaultValue);
+/**
+ * Determines the boolean variation of a feature flag.
+ *
+ * If the flag variation does not have a boolean value, defaultValue is returned.
+ *
+ * @param key The unique key of the feature flag.
+ * @param defaultValue The default value of the flag, to be used if the value is not available
+ *   from LaunchDarkly.
+ * @returns
+ *   The boolean value.
+ */
+export const useBoolVariation = (key: string, defaultValue: boolean) =>
+  useTypedVariation<boolean>(key, defaultValue);
 
-export const useBoolVariationDetail = (flagKey: string, defaultValue: boolean) =>
-  useTypedVariationDetail<boolean>(flagKey, defaultValue);
+/**
+ * Determines the boolean variation of a feature flag for a context, along with information about
+ * how it was calculated.
+ *
+ * The `reason` property of the result will also be included in analytics events, if you are
+ * capturing detailed event data for this flag.
+ *
+ * If the flag variation does not have a boolean value, defaultValue is returned. The reason will
+ * indicate an error of the type `WRONG_KIND` in this case.
+ *
+ * For more information, see the [SDK reference
+ * guide](https://docs.launchdarkly.com/sdk/features/evaluation-reasons#react-native).
+ *
+ * @param key The unique key of the feature flag.
+ * @param defaultValue The default value of the flag, to be used if the value is not available
+ *   from LaunchDarkly.
+ * @returns
+ *  The result (as an {@link LDEvaluationDetailTyped<boolean>}).
+ */
+export const useBoolVariationDetail = (key: string, defaultValue: boolean) =>
+  useTypedVariationDetail<boolean>(key, defaultValue);
 
-export const useNumberVariation = (flagKey: string, defaultValue: number) =>
-  useTypedVariation<number>(flagKey, defaultValue);
+/**
+ * Determines the numeric variation of a feature flag.
+ *
+ * If the flag variation does not have a numeric value, defaultValue is returned.
+ *
+ * @param key The unique key of the feature flag.
+ * @param defaultValue The default value of the flag, to be used if the value is not available
+ *   from LaunchDarkly.
+ * @returns
+ *   The numeric value.
+ */
+export const useNumberVariation = (key: string, defaultValue: number) =>
+  useTypedVariation<number>(key, defaultValue);
 
-export const useNumberVariationDetail = (flagKey: string, defaultValue: number) =>
-  useTypedVariationDetail<number>(flagKey, defaultValue);
+/**
+ * Determines the numeric variation of a feature flag for a context, along with information about
+ * how it was calculated.
+ *
+ * The `reason` property of the result will also be included in analytics events, if you are
+ * capturing detailed event data for this flag.
+ *
+ * If the flag variation does not have a numeric value, defaultValue is returned. The reason will
+ * indicate an error of the type `WRONG_KIND` in this case.
+ *
+ * For more information, see the [SDK reference
+ * guide](https://docs.launchdarkly.com/sdk/features/evaluation-reasons#react-native).
+ *
+ * @param key The unique key of the feature flag.
+ * @param defaultValue The default value of the flag, to be used if the value is not available
+ *   from LaunchDarkly.
+ * @returns
+ *   The result (as an {@link LDEvaluationDetailTyped<number>}).
+ */
+export const useNumberVariationDetail = (key: string, defaultValue: number) =>
+  useTypedVariationDetail<number>(key, defaultValue);
 
-export const useStringVariation = (flagKey: string, defaultValue: string) =>
-  useTypedVariation<string>(flagKey, defaultValue);
+/**
+ * Determines the string variation of a feature flag.
+ *
+ * If the flag variation does not have a string value, defaultValue is returned.
+ *
+ * @param key The unique key of the feature flag.
+ * @param defaultValue The default value of the flag, to be used if the value is not available
+ *   from LaunchDarkly.
+ * @returns
+ *   The string value.
+ */
+export const useStringVariation = (key: string, defaultValue: string) =>
+  useTypedVariation<string>(key, defaultValue);
 
-export const useStringVariationDetail = (flagKey: string, defaultValue: string) =>
-  useTypedVariationDetail<string>(flagKey, defaultValue);
+/**
+ * Determines the string variation of a feature flag for a context, along with information about
+ * how it was calculated.
+ *
+ * The `reason` property of the result will also be included in analytics events, if you are
+ * capturing detailed event data for this flag.
+ *
+ * If the flag variation does not have a string value, defaultValue is returned. The reason will
+ * indicate an error of the type `WRONG_KIND` in this case.
+ *
+ * For more information, see the [SDK reference
+ * guide](https://docs.launchdarkly.com/sdk/features/evaluation-reasons#react-native).
+ *
+ * @param key The unique key of the feature flag.
+ * @param defaultValue The default value of the flag, to be used if the value is not available
+ *   from LaunchDarkly.
+ * @returns
+ *   The result (as an {@link LDEvaluationDetailTyped<string>}).
+ */
+export const useStringVariationDetail = (key: string, defaultValue: string) =>
+  useTypedVariationDetail<string>(key, defaultValue);
 
-export const useJsonVariation = (flagKey: string, defaultValue: unknown) =>
-  useTypedVariation<unknown>(flagKey, defaultValue);
+/**
+ * Determines the json variation of a feature flag.
+ *
+ * This version may be favored in TypeScript versus `variation` because it returns
+ * an `unknown` type instead of `any`. `unknown` will require a cast before usage.
+ *
+ * @param key The unique key of the feature flag.
+ * @param defaultValue The default value of the flag, to be used if the value is not available
+ *   from LaunchDarkly.
+ * @returns
+ *   The json value.
+ */
+export const useJsonVariation = (key: string, defaultValue: unknown) =>
+  useTypedVariation<unknown>(key, defaultValue);
 
-export const useJsonVariationDetail = (flagKey: string, defaultValue: unknown) =>
-  useTypedVariationDetail<unknown>(flagKey, defaultValue);
+/**
+ * Determines the json variation of a feature flag for a context, along with information about how it
+ * was calculated.
+ *
+ * The `reason` property of the result will also be included in analytics events, if you are
+ * capturing detailed event data for this flag.
+ *
+ * This version may be favored in TypeScript versus `variation` because it returns
+ * an `unknown` type instead of `any`. `unknown` will require a cast before usage.
+ *
+ * For more information, see the [SDK reference
+ * guide](https://docs.launchdarkly.com/sdk/features/evaluation-reasons#react-native).
+ *
+ * @param key The unique key of the feature flag.
+ * @param defaultValue The default value of the flag, to be used if the value is not available
+ *   from LaunchDarkly.
+ * @returns
+ *   If you provided a callback, then nothing. Otherwise, a Promise which will be resolved with
+ *   the result (as an{@link LDEvaluationDetailTyped<unknown>}).
+ */
+export const useJsonVariationDetail = (key: string, defaultValue: unknown) =>
+  useTypedVariationDetail<unknown>(key, defaultValue);

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

@@ -55,7 +55,7 @@ export interface LDClient {
    * @param defaultValue The default value of the flag, to be used if the value is not available
    *   from LaunchDarkly.
    * @returns
-   *  The result (as an {@link LDEvaluationDetailTyped<number>}).
+   *  The result (as an {@link LDEvaluationDetailTyped<boolean>}).
    */
   boolVariationDetail(key: string, defaultValue: boolean): LDEvaluationDetailTyped<boolean>;
 
@@ -121,7 +121,7 @@ export interface LDClient {
   jsonVariation(key: string, defaultValue: unknown): unknown;
 
   /**
-   * Determines the variation of a feature flag for a context, along with information about how it
+   * Determines the json variation of a feature flag for a context, along with information about how it
    * was calculated.
    *
    * The `reason` property of the result will also be included in analytics events, if you are