@umituz/web-ai-groq-provider 1.0.1

package/src/hook.ts

@@ -0,0 +1,295 @@
+/**
+ * useGroq Hook
+ * Main React hook for Groq text generation
+ */
+
+import { useState, useCallback, useRef, useMemo } from "react";
+import type { GroqGenerationConfig } from "./types";
+import { textGeneration } from "./text-generation";
+import { structuredText } from "./structured-text";
+import { streaming } from "./streaming";
+
+const isDevelopment = process.env.NODE_ENV === "development";
+
+export interface UseGroqOptions {
+  /** Initial model to use */
+  model?: string;
+  /** Default generation config */
+  generationConfig?: GroqGenerationConfig;
+  /** Callback when generation starts */
+  onStart?: () => void;
+  /** Callback when generation completes */
+  onSuccess?: (result: string) => void;
+  /** Callback when generation fails */
+  onError?: (error: string) => void;
+}
+
+export interface UseGroqReturn {
+  /** Loading state */
+  isLoading: boolean;
+  /** Error message */
+  error: string | null;
+  /** Generated result */
+  result: string | null;
+  /** Generate text from a prompt */
+  generate: (
+    prompt: string,
+    options?: GroqGenerationConfig
+  ) => Promise<string>;
+  /** Generate structured JSON output */
+  generateJSON: <T = Record<string, unknown>>(
+    prompt: string,
+    options?: GroqGenerationConfig & { schema?: Record<string, unknown> }
+  ) => Promise<T>;
+  /** Stream text generation */
+  stream: (
+    prompt: string,
+    onChunk: (chunk: string) => void,
+    options?: GroqGenerationConfig
+  ) => Promise<void>;
+  /** Reset state */
+  reset: () => void;
+  /** Clear error */
+  clearError: () => void;
+}
+
+/**
+ * Hook for Groq text generation
+ * Optimized to prevent unnecessary re-renders and memory leaks
+ */
+export function useGroq(options: UseGroqOptions = {}): UseGroqReturn {
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [result, setResult] = useState<string | null>(null);
+  const abortControllerRef = useRef<AbortController | null>(null);
+
+  // Memoize options to prevent unnecessary callback recreations
+  const stableOptions = useMemo(
+    () => options,
+    [
+      options.model,
+      options.generationConfig?.temperature,
+      options.generationConfig?.maxTokens,
+      options.generationConfig?.topP,
+      options.onStart,
+      options.onSuccess,
+      options.onError,
+    ]
+  );
+
+  const generate = useCallback(
+    async (prompt: string, config?: GroqGenerationConfig): Promise<string> => {
+      // Cancel any ongoing request
+      if (abortControllerRef.current) {
+        abortControllerRef.current.abort();
+      }
+
+      abortControllerRef.current = new AbortController();
+      setIsLoading(true);
+      setError(null);
+      setResult(null);
+
+      if (isDevelopment) {
+        console.log("[useGroq] generate called:", {
+          promptLength: prompt.length,
+        });
+      }
+
+      stableOptions.onStart?.();
+
+      try {
+        const response = await textGeneration(prompt, {
+          model: stableOptions.model,
+          generationConfig: {
+            ...stableOptions.generationConfig,
+            ...config,
+          },
+        });
+
+        setResult(response);
+        stableOptions.onSuccess?.(response);
+
+        if (isDevelopment) {
+          console.log("[useGroq] generate success:", {
+            responseLength: response.length,
+          });
+        }
+
+        return response;
+      } catch (err) {
+        const errorMessage =
+          err instanceof Error ? err.message : "Unknown error occurred";
+        setError(errorMessage);
+        stableOptions.onError?.(errorMessage);
+
+        if (isDevelopment) {
+          console.error("[useGroq] generate error:", { error: err });
+        }
+
+        throw err;
+      } finally {
+        setIsLoading(false);
+        abortControllerRef.current = null;
+      }
+    },
+    [stableOptions]
+  );
+
+  const generateJSON = useCallback(
+    async <T = Record<string, unknown>,>(
+      prompt: string,
+      config?: GroqGenerationConfig & { schema?: Record<string, unknown> }
+    ): Promise<T> => {
+      // Cancel any ongoing request
+      if (abortControllerRef.current) {
+        abortControllerRef.current.abort();
+      }
+
+      abortControllerRef.current = new AbortController();
+      setIsLoading(true);
+      setError(null);
+      setResult(null);
+
+      if (isDevelopment) {
+        console.log("[useGroq] generateJSON called:", {
+          promptLength: prompt.length,
+        });
+      }
+
+      stableOptions.onStart?.();
+
+      try {
+        const response = await structuredText<T>(prompt, {
+          model: stableOptions.model,
+          generationConfig: {
+            ...stableOptions.generationConfig,
+            ...config,
+          },
+          schema: config?.schema,
+        });
+
+        setResult(JSON.stringify(response, null, 2));
+        stableOptions.onSuccess?.(JSON.stringify(response, null, 2));
+
+        if (isDevelopment) {
+          console.log("[useGroq] generateJSON success:", {
+            response: !!response,
+          });
+        }
+
+        return response;
+      } catch (err) {
+        const errorMessage =
+          err instanceof Error ? err.message : "Unknown error occurred";
+        setError(errorMessage);
+        stableOptions.onError?.(errorMessage);
+
+        if (isDevelopment) {
+          console.error("[useGroq] generateJSON error:", { error: err });
+        }
+
+        throw err;
+      } finally {
+        setIsLoading(false);
+        abortControllerRef.current = null;
+      }
+    },
+    [stableOptions]
+  );
+
+  const stream = useCallback(
+    async (
+      prompt: string,
+      onChunk: (chunk: string) => void,
+      config?: GroqGenerationConfig
+    ): Promise<void> => {
+      // Cancel any ongoing request
+      if (abortControllerRef.current) {
+        abortControllerRef.current.abort();
+      }
+
+      abortControllerRef.current = new AbortController();
+      setIsLoading(true);
+      setError(null);
+      setResult(null);
+
+      let fullContent = "";
+
+      if (isDevelopment) {
+        console.log("[useGroq] stream called:", {
+          promptLength: prompt.length,
+        });
+      }
+
+      stableOptions.onStart?.();
+
+      try {
+        for await (const streamingResult of streaming(prompt, {
+          model: stableOptions.model,
+          generationConfig: {
+            ...stableOptions.generationConfig,
+            ...config,
+          },
+          callbacks: {
+            onChunk: (c) => {
+              fullContent += c;
+              onChunk(c);
+            },
+          },
+        })) {
+          // Consume the async iterator (streaming is handled via callbacks)
+          void streamingResult;
+        }
+
+        setResult(fullContent);
+        stableOptions.onSuccess?.(fullContent);
+
+        if (isDevelopment) {
+          console.log("[useGroq] stream success:", {
+            contentLength: fullContent.length,
+          });
+        }
+      } catch (err) {
+        const errorMessage =
+          err instanceof Error ? err.message : "Unknown error occurred";
+        setError(errorMessage);
+        stableOptions.onError?.(errorMessage);
+
+        if (isDevelopment) {
+          console.error("[useGroq] stream error:", { error: err });
+        }
+
+        throw err;
+      } finally {
+        setIsLoading(false);
+        abortControllerRef.current = null;
+      }
+    },
+    [stableOptions]
+  );
+
+  const reset = useCallback(() => {
+    if (abortControllerRef.current) {
+      abortControllerRef.current.abort();
+      abortControllerRef.current = null;
+    }
+    setIsLoading(false);
+    setError(null);
+    setResult(null);
+  }, []);
+
+  const clearError = useCallback(() => {
+    setError(null);
+  }, []);
+
+  return {
+    isLoading,
+    error,
+    result,
+    generate,
+    generateJSON,
+    stream,
+    reset,
+    clearError,
+  };
+}

package/src/index.ts

@@ -0,0 +1,78 @@
+/**
+ * @umituz/web-ai-groq-provider
+ * Groq AI text generation provider for React web applications
+ *
+ * @author umituz
+ * @license MIT
+ *
+ * IMPORTANT: Apps should NOT use this root barrel import.
+ * Use subpath imports instead:
+ * - @umituz/web-ai-groq-provider/domain
+ * - @umituz/web-ai-groq-provider/services
+ * - @umituz/web-ai-groq-provider/hooks
+ */
+
+// Domain layer
+export type {
+  GroqMessageRole,
+  GroqMessage,
+  GroqChatRequest,
+  GroqChoice,
+  GroqFinishReason,
+  GroqUsage,
+  GroqChatResponse,
+  GroqChunkChoice,
+  GroqChatChunk,
+  GroqErrorResponse,
+} from "./domain/entities";
+
+export type {
+  GroqConfig,
+  GroqGenerationConfig,
+  TextGenerationOptions,
+  StreamingCallbacks,
+  StructuredGenerationOptions,
+} from "./domain/interfaces";
+
+export type { IGroqChatService, IGroqHttpClient } from "./domain/interfaces";
+
+// Infrastructure layer
+export {
+  GROQ_MODELS,
+  DEFAULT_MODELS,
+  DEFAULT_GENERATION_CONFIG,
+  API_ENDPOINTS,
+  DEFAULT_BASE_URL,
+  TIMEOUTS,
+} from "./infrastructure/constants";
+
+export {
+  GroqErrorType,
+  mapHttpStatusToErrorType,
+  isRetryableError,
+  isAuthError,
+} from "./infrastructure/constants";
+
+export { groqHttpClient } from "./infrastructure/services";
+export { textGenerationService } from "./infrastructure/services";
+
+export {
+  createUserMessage,
+  createAssistantMessage,
+  createSystemMessage,
+  createTextMessage,
+  promptToMessages,
+  extractTextFromMessages,
+  formatMessagesForDisplay,
+} from "./infrastructure/utils";
+
+export {
+  getUserFriendlyError,
+  formatErrorForLogging,
+} from "./infrastructure/utils";
+
+export { GroqError } from "./infrastructure/utils";
+
+// Presentation layer
+export { useGroq } from "./presentation/hooks";
+export type { UseGroqOptions, UseGroqReturn } from "./presentation/hooks";

package/src/infrastructure/constants/error.constants.ts

@@ -0,0 +1,46 @@
+/**
+ * Error Type Constants
+ * @description Error types and mappings for Groq API
+ */
+
+/**
+ * Error types enum
+ */
+export enum GroqErrorType {
+  INVALID_API_KEY = "INVALID_API_KEY",
+  MISSING_CONFIG = "MISSING_CONFIG",
+  NETWORK_ERROR = "NETWORK_ERROR",
+  ABORT_ERROR = "ABORT_ERROR",
+  RATE_LIMIT_ERROR = "RATE_LIMIT_ERROR",
+  SERVER_ERROR = "SERVER_ERROR",
+  UNKNOWN_ERROR = "UNKNOWN_ERROR",
+}
+
+/**
+ * Map HTTP status to error type
+ */
+export function mapHttpStatusToErrorType(status: number): GroqErrorType {
+  if (status === 401 || status === 403) return GroqErrorType.INVALID_API_KEY;
+  if (status === 429) return GroqErrorType.RATE_LIMIT_ERROR;
+  if (status >= 500) return GroqErrorType.SERVER_ERROR;
+  if (status >= 400) return GroqErrorType.INVALID_API_KEY;
+  return GroqErrorType.UNKNOWN_ERROR;
+}
+
+/**
+ * Check if error is retryable
+ */
+export function isRetryableError(errorType: GroqErrorType): boolean {
+  return [
+    GroqErrorType.NETWORK_ERROR,
+    GroqErrorType.RATE_LIMIT_ERROR,
+    GroqErrorType.SERVER_ERROR,
+  ].includes(errorType);
+}
+
+/**
+ * Check if error is auth-related
+ */
+export function isAuthError(errorType: GroqErrorType): boolean {
+  return errorType === GroqErrorType.INVALID_API_KEY;
+}

package/src/infrastructure/constants/groq.constants.ts

@@ -0,0 +1,68 @@
+/**
+ * Groq Constants
+ * @description Available models and default configurations
+ */
+
+/**
+ * Available Groq models
+ */
+export const GROQ_MODELS = {
+  /** Llama 3.1 8B - Fast and efficient (560 T/s) */
+  LLAMA_3_1_8B_INSTANT: "llama-3.1-8b-instant",
+  /** Llama 3.3 70B - Versatile and powerful (280 T/s) */
+  LLAMA_3_3_70B_VERSATILE: "llama-3.3-70b-versatile",
+  /** Llama 3.1 70B - Versatile (280 T/s) */
+  LLAMA_3_1_70B_VERSATILE: "llama-3.1-70b-versatile",
+  /** GPT-OSS 20B - Experimental (1000 T/s) */
+  GPT_OSS_20B: "openai/gpt-oss-20b",
+  /** GPT-OSS 120B - Large experimental model */
+  GPT_OSS_120B: "openai/gpt-oss-120b",
+  /** Mixtral 8x7b - MoE model */
+  MIXTRAL_8X7B: "mixtral-8x7b-32768",
+  /** Gemma 2 9B - Google's model */
+  GEMMA_2_9B: "gemma2-9b-it",
+  /** Llama 4 Scout 17B - New model (30K T/s) */
+  LLAMA_4_SCOUT_17B: "meta-llama/llama-4-scout-17b-16e-instruct",
+  /** Kimi K2 - Moonshot AI model */
+  KIMI_K2_INSTRUCT: "moonshotai/kimi-k2-instruct",
+  /** Qwen 3 32B - Alibaba's model */
+  QWEN3_32B: "qwen/qwen3-32b",
+} as const;
+
+/**
+ * Default models for different use cases
+ */
+export const DEFAULT_MODELS = {
+  TEXT: GROQ_MODELS.LLAMA_3_1_8B_INSTANT,
+  FAST: GROQ_MODELS.LLAMA_3_1_8B_INSTANT,
+  EXPERIMENTAL: GROQ_MODELS.GPT_OSS_20B,
+} as const;
+
+/**
+ * Default generation configuration
+ */
+export const DEFAULT_GENERATION_CONFIG = {
+  temperature: 0.7,
+  maxTokens: 1024,
+  topP: 1.0,
+} as const;
+
+/**
+ * API endpoints
+ */
+export const API_ENDPOINTS = {
+  CHAT: "/chat/completions",
+} as const;
+
+/**
+ * Default base URL
+ */
+export const DEFAULT_BASE_URL = "https://api.groq.com/openai/v1" as const;
+
+/**
+ * Default timeouts
+ */
+export const TIMEOUTS = {
+  DEFAULT: 30000, // 30 seconds
+  STREAMING: 60000, // 60 seconds
+} as const;

package/src/infrastructure/constants/index.ts

@@ -0,0 +1,20 @@
+/**
+ * Infrastructure Constants Index
+ * Subpath: @umituz/web-ai-groq-provider/services
+ */
+
+export {
+  GROQ_MODELS,
+  DEFAULT_MODELS,
+  DEFAULT_GENERATION_CONFIG,
+  API_ENDPOINTS,
+  DEFAULT_BASE_URL,
+  TIMEOUTS,
+} from "./groq.constants";
+
+export {
+  GroqErrorType,
+  mapHttpStatusToErrorType,
+  isRetryableError,
+  isAuthError,
+} from "./error.constants";