chore(firestore-translate-text): add JSDoc comments to new code

firestore-translate-text/functions/src/translate/common.ts

@@ -12,21 +12,48 @@ import {
   googleAI,
 } from "@genkit-ai/googleai";
 
+/**
+ * Represents a translation result with target language and translated text
+ */
 export type Translation = {
   language: string;
   output: string;
 };
 
+/**
+ * Interface defining the contract for translator implementations
+ */
 interface ITranslator {
+  /**
+   * Translates text to a target language
+   * @param text - The text to translate
+   * @param targetLanguage - The language code to translate to
+   * @returns A promise resolving to the translated text
+   */
   translate(text: string, targetLanguage: string): Promise<string>;
 }
+
+/**
+ * Implementation of ITranslator using Google Cloud Translation API v2
+ */
 export class GoogleTranslator implements ITranslator {
   private client: v2.Translate;
 
+  /**
+   * Creates a new instance of GoogleTranslator
+   * @param projectId - The Google Cloud project ID
+   */
   constructor(projectId: string) {
     this.client = new v2.Translate({ projectId });
   }
 
+  /**
+   * Translates text using Google Cloud Translation API
+   * @param text - The text to translate
+   * @param targetLanguage - The language code to translate to
+   * @returns A promise resolving to the translated text
+   * @throws Will throw an error if translation fails
+   */
   async translate(text: string, targetLanguage: string): Promise<string> {
     try {
       const [translatedString] = await this.client.translate(
@@ -43,11 +70,20 @@ export class GoogleTranslator implements ITranslator {
   }
 }
 
+/**
+ * Implementation of ITranslator using Genkit with either Vertex AI or Google AI
+ */
 export class GenkitTranslator implements ITranslator {
   private client: Genkit;
   plugin: "vertexai" | "googleai";
   model: ModelReference<any>;
 
+  /**
+   * Creates a new instance of GenkitTranslator
+   * @param options - Configuration options for the translator
+   * @param options.plugin - The AI service provider to use ("vertexai" or "googleai")
+   * @throws Will throw an error if required API keys are missing
+   */
   constructor({ plugin }: { plugin: "vertexai" | "googleai" }) {
     this.plugin = plugin;
     if (plugin === "googleai" && !config.googleAIAPIKey) {
@@ -69,6 +105,13 @@ export class GenkitTranslator implements ITranslator {
     });
   }
 
+  /**
+   * Translates text using Genkit with either Vertex AI or Google AI
+   * @param text - The text to translate
+   * @param targetLanguage - The language code to translate to
+   * @returns A promise resolving to the translated text
+   * @throws Will throw an error if translation fails or no output is returned
+   */
   async translate(text: string, targetLanguage: string): Promise<string> {
     try {
       const prompt =
@@ -86,7 +129,7 @@ export class GenkitTranslator implements ITranslator {
       });
 
       if (!response.output) {
-        throw new Error("No translation returned from Gemini15Pro model");
+        throw new Error("No translation returned from Gemini 1.5 Pro");
       }
 
       logs.translateStringComplete(text, targetLanguage, response.text);
@@ -99,26 +142,59 @@ export class GenkitTranslator implements ITranslator {
   }
 }
 
+/**
+ * Service class that orchestrates translation operations using the provided translator
+ */
 export class TranslationService {
+  /**
+   * Creates a new instance of TranslationService
+   * @param translator - The translator implementation to use
+   */
   constructor(private translator: ITranslator) {}
 
+  /**
+   * Translates a string to the specified target language
+   * @param text - The text to translate
+   * @param targetLanguage - The language code to translate to
+   * @returns A promise resolving to the translated text
+   */
   async translateString(text: string, targetLanguage: string): Promise<string> {
     return this.translator.translate(text, targetLanguage);
   }
 
+  /**
+   * Extracts input field value from a Firestore document
+   * @param snapshot - The Firestore document snapshot
+   * @returns The value of the configured input field
+   */
   extractInput(snapshot: admin.firestore.DocumentSnapshot): any {
     return snapshot.get(config.inputFieldName);
   }
 
+  /**
+   * Extracts output field value from a Firestore document
+   * @param snapshot - The Firestore document snapshot
+   * @returns The value of the configured output field
+   */
   extractOutput(snapshot: admin.firestore.DocumentSnapshot): any {
     return snapshot.get(config.outputFieldName);
   }
 
+  /**
+   * Extracts target languages from a Firestore document or returns default languages
+   * @param snapshot - The Firestore document snapshot
+   * @returns Array of language codes to translate to
+   */
   extractLanguages(snapshot: admin.firestore.DocumentSnapshot): string[] {
     if (!config.languagesFieldName) return config.languages;
     return snapshot.get(config.languagesFieldName) || config.languages;
   }
 
+  /**
+   * Creates a filter function to skip already translated languages
+   * @param existingTranslations - Record of existing translations
+   * @returns A function that returns true for languages that need translation
+   */
   filterLanguagesFn(
     existingTranslations: Record<string, any>
   ): (targetLanguage: string) => boolean {
@@ -131,6 +207,12 @@ export class TranslationService {
     };
   }
 
+  /**
+   * Updates translations in a Firestore document
+   * @param snapshot - The Firestore document snapshot
+   * @param translations - The translations to update
+   * @returns A promise that resolves when the update is complete
+   */
   async updateTranslations(
     snapshot: admin.firestore.DocumentSnapshot,
     translations: any
@@ -150,10 +232,12 @@ export class TranslationService {
   }
 }
 
+// Initialize the translation service based on configuration
 const translationService = config.useGenkit
   ? new TranslationService(new GenkitTranslator({ plugin: "vertexai" }))
   : new TranslationService(new GoogleTranslator(process.env.PROJECT_ID));
 
+// Export bound methods for convenience
 export const translateString =
   translationService.translateString.bind(translationService);
 export const extractInput =