chore: Add initial documentation.

contract-tests/sdkClientEntity.js

@@ -64,7 +64,7 @@ export function makeSdkConfig(options, tag) {
 }
 
 function getExecution(order) {
-  switch(order) {
+  switch (order) {
     case 'serial': {
       return new LDSerialExecution(LDExecutionOrdering.Fixed);
     }
@@ -164,7 +164,7 @@ export async function newSdkClientEntity(options) {
       case 'migrationOperation':
         const migrationOperation = params.migrationOperation;
         const readExecutionOrder = migrationOperation.readExecutionOrder;
-        
+
         const migration = new Migration(client, {
           execution: getExecution(readExecutionOrder),
           latencyTracking: migrationOperation.trackLatency,

packages/shared/sdk-server/src/Migration.ts

@@ -39,13 +39,45 @@ async function safeCall<TResult>(
   }
 }
 
+/**
+ * Report a successful migration operation from `readNew`, `readOld`, `writeNew` or `writeOld`.
+ *
+ * ```
+ * readNew: async () => {
+ *   const myResult = doMyOldRead();
+ *   if(myResult.wasGood) {
+ *     return LDMigrationSuccess(myResult);
+ *   }
+ *   return LDMigrationError(myResult.error)
+ * }
+ * ```
+ *
+ * @param result The result of the operation.
+ * @returns An {@link LDMethodResult}
+ */
 export function LDMigrationSuccess<TResult>(result: TResult): LDMethodResult<TResult> {
   return {
     success: true,
     result,
   };
 }
 
+/**
+ * Report a failed migration operation from `readNew`, `readOld`, `writeNew` or `writeOld`.
+ *
+ * ```
+ * readNew: async () => {
+ *   const myResult = doMyOldRead();
+ *   if(myResult.wasGood) {
+ *     return LDMigrationSuccess(myResult);
+ *   }
+ *   return LDMigrationError(myResult.error)
+ * }
+ * ```
+ *
+ * @param result The result of the operations.
+ * @returns An {@link LDMethodResult}
+ */
 export function LDMigrationError(error: Error): { success: false; error: Error } {
   return {
     success: false,
@@ -59,6 +91,9 @@ interface MigrationContext<TPayload> {
   checkRatio?: number;
 }
 
+/**
+ * Class which allows performing technology migrations.
+ */
 export default class Migration<
   TMigrationRead,
   TMigrationWrite,

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

@@ -123,7 +123,8 @@ export interface LDClient {
   ): Promise<LDEvaluationDetail>;
 
   /**
-   * TKTK: Should use a common description.
+   * MigrationVariation returns the migration stage of the migration feature flag for the given
+   * evaluation context.
    *
    * If the evaluated value of the flag cannot be converted to an LDMigrationStage, then an error
    * event will be raised.

packages/shared/sdk-server/src/api/LDMigration.ts

@@ -51,9 +51,7 @@ export type LDMigrationWriteResult<TResult> = {
 };
 
 /**
- * Interface for a migration.
- *
- * TKTK
+ * Interface representing a migration.
  */
 export interface LDMigration<
   TMigrationRead,
@@ -62,7 +60,7 @@ export interface LDMigration<
   TMigrationWriteInput,
 > {
   /**
-   * TKTK
+   * Perform a read using the migration.
    *
    * @param key The key of the flag controlling the migration.
    * @param context The context requesting the flag. The client will generate an analytics event to
@@ -78,7 +76,7 @@ export interface LDMigration<
   ): Promise<LDMigrationReadResult<TMigrationRead>>;
 
   /**
-   * TKTK
+   * Perform a write using the migration.
    *
    * @param key The key of the flag controlling the migration.
    * @param context The context requesting the flag. The client will generate an analytics event to

packages/shared/sdk-server/src/api/data/LDMigrationDetail.ts

@@ -15,8 +15,6 @@ export enum LDConsistencyCheck {
 
 /**
  * Used to track information related to a migration operation.
- *
- * TKTK
  */
 export interface LDMigrationTracker {
   /**

packages/shared/sdk-server/src/api/data/LDMigrationStage.ts

@@ -1,12 +1,46 @@
+/**
+ * Stage denotes one of six possible stages a technology migration could be a
+ * part of, progressing through the following order.
+ *
+ * Off -> DualWrite -> Shadow -> Live -> RampDown -> Complete
+ */
 export enum LDMigrationStage {
+  /**
+   * Off - migration hasn't started, "old" is authoritative for reads and writes
+   */
   Off = 'off',
+
+  /**
+   * DualWrite - write to both "old" and "new", "old" is authoritative for reads
+   */
   DualWrite = 'dualwrite',
+
+  /**
+   * Shadow - both "new" and "old" versions run with a preference for "old"
+   */
   Shadow = 'shadow',
+
+  /**
+   * Live - both "new" and "old" versions run with a preference for "new"
+   */
   Live = 'live',
+
+  /**
+   * RampDown - only read from "new", write to "old" and "new"
+   */
   RampDown = 'rampdown',
+
+  /**
+   * Complete - migration is done
+   */
   Complete = 'complete',
 }
 
+/**
+ * Check if the given string is a migration stage.
+ * @param value The string to check.
+ * @returns True if the string is a migration stage.
+ */
 export function IsMigrationStage(value: string): boolean {
   return Object.values(LDMigrationStage).includes(value as LDMigrationStage);
 }

packages/shared/sdk-server/src/api/options/LDMigrationOptions.ts

@@ -90,27 +90,69 @@ export interface LDMigrationOptions<
   errorTracking?: boolean;
 
   /**
-   * TKTK
+   * Implementation which provides a read from the "new" source.
+   *
+   * Users are required to provide two different read methods -- one to read from the old migration source, and one to
+   * read from the new source. Additionally, customers can opt-in to consistency tracking by providing a `check`
+   * function.
+   *
+   * Depending on the migration stage, one or both of these read methods may be called.
+   *
+   * Throwing an exception from this method will be treated as an error.
+   *
+   * @param payload An optional payload. The payload is provided when calling the  `read` method on the migration.
+   * @returns The result of the operation. Use {@link LDMigrationSuccess} or {@link LDMigrationError} to create a suitable return value.
    */
   readNew: (payload?: TMigrationReadInput) => Promise<LDMethodResult<TMigrationRead>>;
 
   /**
-   * TKTK
+   * Implementation which provides a write to the "new" source.
+   *
+   * Users are required to provide two different write methods -- one to write to the old migration source, and one to
+   * write to the new source. Not every stage requires
+   *
+   *
+   * Depending on the migration stage, one or both of these write methods may be called.
+   *
+   * Throwing an exception from this method will be treated as an error.
+   *
+   * @param payload An optional payload. The payload is provided when calling the  `read` method on the migration.
+   * @returns The result of the operation. Use {@link LDMigrationSuccess} or {@link LDMigrationError} to create a suitable return value.
    */
   writeNew: (payload?: TMigrationWriteInput) => Promise<LDMethodResult<TMigrationWrite>>;
 
   /**
-   * TKTK
+   * Implementation which provides a read from the "old" source.
+   *
+   * Users are required to provide two different read methods -- one to read from the old migration source, and one to
+   * read from the new source. Additionally, customers can opt-in to consistency tracking by providing a `check`
+   * function.
+   *
+   * Depending on the migration stage, one or both of these read methods may be called.
+   *
+   * Throwing an exception from this method will be treated as an error.
+   *
    */
   readOld: (payload?: TMigrationReadInput) => Promise<LDMethodResult<TMigrationRead>>;
 
   /**
-   * TKTK
+   * Implementation which provides a write to the "old" source.
+   *
+   * Users are required to provide two different write methods -- one to write to the old migration source, and one to
+   * write to the new source. Not every stage requires
+   *
+   * Depending on the migration stage, one or both of these write methods may be called.
+   *
+   * Throwing an exception from this method will be treated as an error.
+   *
+   * @param payload An optional payload. The payload is provided when calling the  `read` method on the migration.
+   * @returns The result of the operation. Use {@link LDMigrationSuccess} or {@link LDMigrationError} to create a suitable return value.
    */
   writeOld: (payload?: TMigrationWriteInput) => Promise<LDMethodResult<TMigrationWrite>>;
 
   /**
-   * TKTK
+   * Method used to do consistency checks for read operations. After a read operation, during which both data sources
+   * are read from, a check of read consistency may be done using this method.
    */
   check?: (a: TMigrationRead, b: TMigrationRead) => boolean;
 }