@umituz/react-native-subscription 2.40.3 → 2.40.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/react-native-subscription",
-  "version": "2.40.3",
+  "version": "2.40.5",
   "description": "Complete subscription management with RevenueCat, paywall UI, and credits system for React Native apps",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/domains/credits/application/CreditsInitializer.ts

@@ -2,7 +2,7 @@ import type { CreditsConfig } from "../core/Credits";
 import { getAppVersion, validatePlatform } from "../../../utils/appUtils";
 
 import type { InitializeCreditsMetadata, InitializationResult } from "../../subscription/application/SubscriptionInitializerTypes";
-import { runTransaction, serverTimestamp, type Transaction, type DocumentReference, type Firestore } from "@umituz/react-native-firebase";
+import { runTransaction, type Transaction, type DocumentReference, type Firestore } from "@umituz/react-native-firebase";
 import { getCreditDocumentOrDefault } from "./creditDocumentHelpers";
 import { calculateNewCredits, buildCreditsData } from "./creditOperationUtils";
 import { calculateCreditLimit } from "./CreditLimitCalculator";

package/src/domains/credits/infrastructure/CreditsRepository.ts

@@ -93,7 +93,7 @@ export class CreditsRepository extends BaseRepository {
     willRenew: boolean,
     expirationDate: string | null,
     periodType: string | null,
-    storeTransactionId?: string | null,
+    _storeTransactionId?: string | null,
   ): Promise<boolean> {
     const db = requireFirestore();
     const creditLimit = calculateCreditLimit(productId, this.config);

package/src/domains/paywall/components/PaywallFeatures.tsx

@@ -4,10 +4,11 @@ import { AtomicText, AtomicIcon } from "@umituz/react-native-design-system/atoms
 import { useAppDesignTokens } from "@umituz/react-native-design-system/theme";
 import type { SubscriptionFeature } from "../entities/types";
 import { paywallScreenStyles as styles } from "./PaywallScreen.styles";
+import { isEmptyArray } from "../../../shared/utils/arrayUtils";
 
-export const PaywallFeatures: React.FC<{ features: SubscriptionFeature[] }> = ({ features }) => {
+export const PaywallFeatures: React.FC<{ features: SubscriptionFeature[] }> = React.memo(({ features }) => {
   const tokens = useAppDesignTokens();
-  if (!features.length) return null;
+  if (isEmptyArray(features)) return null;
 
   return (
     <View style={[styles.featuresContainer, { backgroundColor: tokens.colors.surfaceSecondary }]}>
@@ -23,4 +24,4 @@ export const PaywallFeatures: React.FC<{ features: SubscriptionFeature[] }> = ({
       ))}
     </View>
   );
-};
+});

package/src/domains/paywall/components/PaywallFooter.tsx

@@ -13,7 +13,7 @@ interface PaywallFooterProps {
   onLegalClick: (url: string | undefined) => void;
 }
 
-export const PaywallFooter: React.FC<PaywallFooterProps> = ({
+export const PaywallFooter: React.FC<PaywallFooterProps> = React.memo(({
   translations,
   legalUrls,
   isProcessing,
@@ -49,4 +49,4 @@ export const PaywallFooter: React.FC<PaywallFooterProps> = ({
       </View>
     </View>
   );
-};
+});

package/src/domains/paywall/components/PaywallScreen.tsx

@@ -5,12 +5,12 @@
  */
 
 import React, { useCallback, useEffect, useMemo } from "react";
-import { 
-  View, 
-  TouchableOpacity, 
-  Linking, 
-  FlatList, 
-  ListRenderItem, 
+import {
+  View,
+  TouchableOpacity,
+  Linking,
+  FlatList,
+  ListRenderItem,
   StatusBar,
 } from "react-native";
 import { AtomicText, AtomicIcon, AtomicSpinner } from "@umituz/react-native-design-system/atoms";
@@ -20,13 +20,13 @@ import { Image } from "expo-image";
 import { PlanCard } from "./PlanCard";
 import { paywallScreenStyles as styles } from "./PaywallScreen.styles";
 import { PaywallFooter } from "./PaywallFooter";
-import { PurchaseLoadingOverlay } from "../../subscription/presentation/components/overlay/PurchaseLoadingOverlay";
 import { usePaywallActions } from "../hooks/usePaywallActions";
 import { PaywallScreenProps } from "./PaywallScreen.types";
-import { 
-  calculatePaywallItemLayout, 
-  type PaywallListItem 
+import {
+  calculatePaywallItemLayout,
+  type PaywallListItem
 } from "../utils/paywallLayoutUtils";
+import { hasItems } from "../../../shared/utils/arrayUtils";
 
 export const PaywallScreen: React.FC<PaywallScreenProps> = React.memo((props) => {
   const {
@@ -78,7 +78,7 @@ export const PaywallScreen: React.FC<PaywallScreenProps> = React.memo((props) =>
 
   // Auto-select first package
   useEffect(() => {
-    if (packages.length > 0 && !selectedPlanId) {
+    if (hasItems(packages) && !selectedPlanId) {
       setSelectedPlanId(packages[0].product.identifier);
     }
   }, [packages, selectedPlanId, setSelectedPlanId]);
@@ -100,7 +100,7 @@ export const PaywallScreen: React.FC<PaywallScreenProps> = React.memo((props) =>
     data.push({ type: 'HEADER' });
 
     // 2. Features Section
-    if (features.length > 0) {
+    if (hasItems(features)) {
       data.push({ type: 'FEATURE_HEADER' });
       features.forEach(feature => {
         data.push({ type: 'FEATURE', feature });
@@ -108,7 +108,7 @@ export const PaywallScreen: React.FC<PaywallScreenProps> = React.memo((props) =>
     }
 
     // 3. Plans Section
-    if (packages.length > 0) {
+    if (hasItems(packages)) {
       data.push({ type: 'PLAN_HEADER' });
       packages.forEach(pkg => {
         data.push({ type: 'PLAN', pkg });

package/src/domains/subscription/presentation/components/details/CreditRow.tsx

@@ -2,6 +2,7 @@ import React, { useMemo } from "react";
 import { View, StyleSheet } from "react-native";
 import { AtomicText } from "@umituz/react-native-design-system/atoms";
 import { useAppDesignTokens } from "@umituz/react-native-design-system/theme";
+import { calculatePercentage, getProgressColor } from "../../../utils/progressCalculations";
 
 interface CreditRowProps {
   label: string;
@@ -10,20 +11,18 @@ interface CreditRowProps {
   remainingLabel?: string;
 }
 
-export const CreditRow: React.FC<CreditRowProps> = ({
+export const CreditRow: React.FC<CreditRowProps> = React.memo(({
   label,
   current,
   total,
   remainingLabel,
 }) => {
   const tokens = useAppDesignTokens();
-  const percentage = total > 0 ? (current / total) * 100 : 0;
-  
+  const percentage = useMemo(() => calculatePercentage(current, total), [current, total]);
+
   // Progress color based on percentage
   const progressColor = useMemo(() => {
-    if (percentage <= 20) return tokens.colors.error;
-    if (percentage <= 50) return tokens.colors.warning;
-    return tokens.colors.success;
+    return getProgressColor(percentage, tokens.colors);
   }, [percentage, tokens.colors]);
 
   return (
@@ -56,7 +55,7 @@ export const CreditRow: React.FC<CreditRowProps> = ({
       )}
     </View>
   );
-};
+});
 
 const styles = StyleSheet.create({
   container: {

package/src/domains/subscription/presentation/components/details/DetailRow.tsx

@@ -17,7 +17,7 @@ interface DetailRowProps {
   valueStyle?: TextStyle;
 }
 
-export const DetailRow: React.FC<DetailRowProps> = ({
+export const DetailRow: React.FC<DetailRowProps> = React.memo(({
   label,
   value,
   highlight = false,
@@ -49,7 +49,7 @@ export const DetailRow: React.FC<DetailRowProps> = ({
       </AtomicText>
     </View>
   );
-};
+});
 
 const styles = StyleSheet.create({
   container: {

package/src/domains/subscription/presentation/components/details/PremiumDetailsCard.tsx

@@ -9,10 +9,11 @@ import type { PremiumDetailsCardProps } from "./PremiumDetailsCardTypes";
 import { PremiumDetailsCardHeader } from "./PremiumDetailsCardHeader";
 import { PremiumDetailsCardActions } from "./PremiumDetailsCardActions";
 import { shouldHighlightExpiration } from "../../../../subscription/utils/expirationHelpers";
+import { hasItems } from "../../../../../shared/utils/arrayUtils";
 
 export type { CreditInfo, PremiumDetailsTranslations, PremiumDetailsCardProps } from "./PremiumDetailsCardTypes";
 
-export const PremiumDetailsCard: React.FC<PremiumDetailsCardProps> = ({
+export const PremiumDetailsCard: React.FC<PremiumDetailsCardProps> = React.memo(({
   statusType,
   isPremium,
   expirationDate,
@@ -24,7 +25,7 @@ export const PremiumDetailsCard: React.FC<PremiumDetailsCardProps> = ({
   onUpgrade,
 }) => {
   const tokens = useAppDesignTokens();
-  const showCredits = isPremium && credits && credits.length > 0;
+  const showCredits = isPremium && hasItems(credits);
 
   return (
     <View style={[styles.card, { backgroundColor: tokens.colors.surface }]}>
@@ -67,4 +68,4 @@ export const PremiumDetailsCard: React.FC<PremiumDetailsCardProps> = ({
       />
     </View>
   );
-};
+});

package/src/domains/subscription/presentation/components/details/PremiumDetailsCardActions.tsx

@@ -12,7 +12,7 @@ interface PremiumDetailsCardActionsProps {
   translations: PremiumDetailsTranslations;
 }
 
-export const PremiumDetailsCardActions: React.FC<PremiumDetailsCardActionsProps> = ({
+export const PremiumDetailsCardActions: React.FC<PremiumDetailsCardActionsProps> = React.memo(({
   isPremium,
   onManageSubscription,
   onUpgrade,
@@ -44,4 +44,4 @@ export const PremiumDetailsCardActions: React.FC<PremiumDetailsCardActionsProps>
       )}
     </View>
   );
-};
+});

package/src/domains/subscription/presentation/components/details/PremiumDetailsCardHeader.tsx

@@ -12,7 +12,7 @@ interface PremiumDetailsCardHeaderProps {
   translations: PremiumDetailsTranslations;
 }
 
-export const PremiumDetailsCardHeader: React.FC<PremiumDetailsCardHeaderProps> = ({ statusType, translations }) => {
+export const PremiumDetailsCardHeader: React.FC<PremiumDetailsCardHeaderProps> = React.memo(({ statusType, translations }) => {
   const tokens = useAppDesignTokens();
 
   return (
@@ -31,4 +31,4 @@ export const PremiumDetailsCardHeader: React.FC<PremiumDetailsCardHeaderProps> =
       />
     </View>
   );
-};
+});

package/src/domains/subscription/presentation/components/details/PremiumStatusBadge.tsx

@@ -13,7 +13,7 @@ import type { SubscriptionStatusType } from "../../../core/SubscriptionConstants
 
 export type { PremiumStatusBadgeProps };
 
-export const PremiumStatusBadge: React.FC<PremiumStatusBadgeProps> = ({
+export const PremiumStatusBadge: React.FC<PremiumStatusBadgeProps> = React.memo(({
   status,
   activeLabel,
   expiredLabel,
@@ -63,4 +63,4 @@ export const PremiumStatusBadge: React.FC<PremiumStatusBadgeProps> = ({
       </AtomicText>
     </View>
   );
-};
+});

package/src/domains/subscription/presentation/components/sections/SubscriptionSection.tsx

@@ -11,7 +11,7 @@ import type { SubscriptionSectionConfig, SubscriptionSectionProps } from "./Subs
 
 export type { SubscriptionSectionConfig, SubscriptionSectionProps };
 
-export const SubscriptionSection: React.FC<SubscriptionSectionProps> = ({
+export const SubscriptionSection: React.FC<SubscriptionSectionProps> = React.memo(({
   config,
   containerStyle,
 }) => {
@@ -42,4 +42,4 @@ export const SubscriptionSection: React.FC<SubscriptionSectionProps> = ({
   }
 
   return <View style={containerStyle}>{content}</View>;
-};
+});

package/src/domains/subscription/presentation/screens/SubscriptionDetailScreen.tsx

@@ -15,7 +15,7 @@ import { SubscriptionDetailScreenProps } from "./SubscriptionDetailScreen.types"
 
 const IS_DEV = typeof __DEV__ !== "undefined" && __DEV__;
 
-export const SubscriptionDetailScreen: React.FC<SubscriptionDetailScreenProps> = ({ config }) => {
+export const SubscriptionDetailScreen: React.FC<SubscriptionDetailScreenProps> = React.memo(({ config }) => {
   const tokens = useAppDesignTokens();
   const { showHeader, showCredits, showUpgradePrompt, showExpirationDate } = config.display;
 
@@ -91,7 +91,7 @@ export const SubscriptionDetailScreen: React.FC<SubscriptionDetailScreenProps> =
       </View>
     </ScreenLayout>
   );
-};
+});
 
 /* ─── DEV TEST PANEL ─── Only rendered in __DEV__ ─── */
 

package/src/domains/subscription/presentation/screens/components/CreditsList.tsx

@@ -8,6 +8,7 @@ import { View, StyleSheet } from "react-native";
 import { AtomicText } from "@umituz/react-native-design-system/atoms";
 import { useAppDesignTokens } from "@umituz/react-native-design-system/theme";
 import { CreditRow } from "../../components/details/CreditRow";
+import { isEmptyArray } from "../../../../../shared/utils/arrayUtils";
 
 interface CreditItem {
   id: string;
@@ -23,7 +24,7 @@ interface CreditsListProps {
   remainingLabel?: string;
 }
 
-export const CreditsList: React.FC<CreditsListProps> = ({
+export const CreditsList: React.FC<CreditsListProps> = React.memo(({
   credits,
   title,
   description,
@@ -53,7 +54,7 @@ export const CreditsList: React.FC<CreditsListProps> = ({
     [tokens]
   );
 
-  if (!credits || credits.length === 0) return null;
+  if (!credits || isEmptyArray(credits)) return null;
 
   return (
     <View style={styles.container}>
@@ -86,4 +87,4 @@ export const CreditsList: React.FC<CreditsListProps> = ({
       </View>
     </View>
   );
-};
+});

package/src/domains/subscription/presentation/screens/components/SubscriptionHeader.tsx

@@ -9,7 +9,7 @@ import { SubscriptionHeaderContent } from "./SubscriptionHeaderContent";
 
 const EXPIRING_SOON_THRESHOLD_DAYS = 7;
 
-export const SubscriptionHeader: React.FC<SubscriptionHeaderProps> = ({
+export const SubscriptionHeader: React.FC<SubscriptionHeaderProps> = React.memo(({
   statusType,
   showExpirationDate,
   expirationDate,
@@ -67,4 +67,4 @@ export const SubscriptionHeader: React.FC<SubscriptionHeaderProps> = ({
       />
     </View>
   );
-};
+});

package/src/domains/subscription/presentation/screens/components/UpgradePrompt.tsx

@@ -3,8 +3,9 @@ import { View, StyleSheet, TouchableOpacity } from "react-native";
 import { AtomicText, AtomicIcon } from "@umituz/react-native-design-system/atoms";
 import { useAppDesignTokens } from "@umituz/react-native-design-system/theme";
 import { UpgradePromptProps } from "./UpgradePrompt.types";
+import { hasItems } from "../../../../../shared/utils/arrayUtils";
 
-export const UpgradePrompt: React.FC<UpgradePromptProps> = ({ title, subtitle, benefits, upgradeButtonLabel, onUpgrade }) => {
+export const UpgradePrompt: React.FC<UpgradePromptProps> = React.memo(({ title, subtitle, benefits, upgradeButtonLabel, onUpgrade }) => {
   const tokens = useAppDesignTokens();
   const styles = useMemo(() => StyleSheet.create({
     container: { gap: tokens.spacing.lg },
@@ -39,7 +40,7 @@ export const UpgradePrompt: React.FC<UpgradePromptProps> = ({ title, subtitle, b
         <AtomicText type="headlineSmall" style={[styles.title, { color: tokens.colors.textPrimary }]}>{title}</AtomicText>
         {subtitle && <AtomicText type="bodyMedium" style={[styles.subtitle, { color: tokens.colors.textSecondary }]}>{subtitle}</AtomicText>}
       </View>
-      {benefits && benefits.length > 0 && (
+      {hasItems(benefits) && (
         <View style={styles.benefitsCard}>
           {benefits.map((benefit) => (
             <View key={benefit.text} style={styles.benefitItem}>
@@ -58,4 +59,4 @@ export const UpgradePrompt: React.FC<UpgradePromptProps> = ({ title, subtitle, b
       )}
     </View>
   );
-};
+});

package/src/domains/subscription/utils/progressCalculations.ts

@@ -0,0 +1,55 @@
+/**
+ * Progress calculation utilities
+ * All progress bar and percentage calculations
+ */
+
+/**
+ * Calculate percentage for progress bars
+ * Returns 0 for invalid inputs (zero or negative total)
+ */
+export function calculatePercentage(current: number, total: number): number {
+  if (total <= 0) return 0;
+  return (current / total) * 100;
+}
+
+/**
+ * Determine progress color based on percentage thresholds
+ * @param percentage - Progress percentage (0-100)
+ * @param colors - Color object with error, warning, and success colors
+ * @returns Appropriate color based on percentage
+ */
+export interface ProgressColors {
+  error: string;
+  warning: string;
+  success: string;
+}
+
+export function getProgressColor(
+  percentage: number,
+  colors: ProgressColors
+): string {
+  if (percentage <= 20) return colors.error;
+  if (percentage <= 50) return colors.warning;
+  return colors.success;
+}
+
+/**
+ * Check if percentage is in critical range (<= 20%)
+ */
+export function isCriticalPercentage(percentage: number): boolean {
+  return percentage <= 20;
+}
+
+/**
+ * Check if percentage is in warning range (21-50%)
+ */
+export function isWarningPercentage(percentage: number): boolean {
+  return percentage > 20 && percentage <= 50;
+}
+
+/**
+ * Check if percentage is in healthy range (> 50%)
+ */
+export function isHealthyPercentage(percentage: number): boolean {
+  return percentage > 50;
+}

package/src/domains/wallet/presentation/components/BalanceCard.tsx

@@ -14,7 +14,7 @@ import type { BalanceCardTranslations, BalanceCardProps } from "./BalanceCard.ty
 
 export type { BalanceCardTranslations };
 
-export const BalanceCard: React.FC<BalanceCardProps> = ({
+export const BalanceCard: React.FC<BalanceCardProps> = React.memo(({
   balance,
   translations,
   iconName = "wallet",
@@ -58,7 +58,7 @@ export const BalanceCard: React.FC<BalanceCardProps> = ({
       </View>
     </View>
   );
-};
+});
 
 const styles = StyleSheet.create({
   container: {

package/src/domains/wallet/presentation/components/TransactionItem.tsx

@@ -7,7 +7,7 @@ import { transactionItemStyles } from "./TransactionItem.styles";
 import type { TransactionItemProps } from "./TransactionItem.types";
 import { defaultDateFormatter, getReasonLabel, getChangePrefix } from "./transactionItemHelpers";
 
-export const TransactionItem: React.FC<TransactionItemProps> = ({
+export const TransactionItem: React.FC<TransactionItemProps> = React.memo(({
   transaction,
   translations,
   dateFormatter = defaultDateFormatter,
@@ -44,4 +44,4 @@ export const TransactionItem: React.FC<TransactionItemProps> = ({
       </AtomicText>
     </View>
   );
-};
+});

package/src/domains/wallet/presentation/components/TransactionList.tsx

@@ -1,5 +1,5 @@
-import React from "react";
-import { View, ScrollView } from "react-native";
+import React, { useCallback, useMemo } from "react";
+import { View, FlatList } from "react-native";
 import { AtomicText, AtomicIcon } from "@umituz/react-native-design-system/atoms";
 import { useAppDesignTokens } from "@umituz/react-native-design-system/theme";
 import { TransactionItem } from "./TransactionItem";
@@ -7,10 +7,11 @@ import { transactionListStyles } from "./TransactionList.styles";
 import { LoadingState, EmptyState } from "./TransactionListStates";
 import { DEFAULT_TRANSACTION_LIST_MAX_HEIGHT } from "./TransactionList.constants";
 import type { TransactionListTranslations, TransactionListProps } from "./TransactionList.types";
+import { isEmptyArray } from "../../../../shared/utils/arrayUtils";
 
 export type { TransactionListTranslations };
 
-export const TransactionList: React.FC<TransactionListProps> = ({
+export const TransactionList: React.FC<TransactionListProps> = React.memo(({
   transactions,
   loading,
   translations,
@@ -19,6 +20,13 @@ export const TransactionList: React.FC<TransactionListProps> = ({
 }) => {
   const tokens = useAppDesignTokens();
 
+  const keyExtractor = useCallback((item: typeof transactions[0]) => item.id, []);
+  const renderItem = useCallback(({ item }: { item: typeof transactions[0] }) => (
+    <TransactionItem transaction={item} translations={translations} dateFormatter={dateFormatter} />
+  ), [translations, dateFormatter]);
+
+  const listStyle = useMemo(() => [transactionListStyles.scrollView, { maxHeight }], [maxHeight]);
+
   return (
     <View style={transactionListStyles.container}>
       <View style={transactionListStyles.header}>
@@ -30,19 +38,22 @@ export const TransactionList: React.FC<TransactionListProps> = ({
 
       {loading ? (
         <LoadingState message={translations.loading} />
-      ) : transactions.length === 0 ? (
+      ) : isEmptyArray(transactions) ? (
         <EmptyState message={translations.empty} />
       ) : (
-        <ScrollView
-          style={[transactionListStyles.scrollView, { maxHeight }]}
+        <FlatList
+          data={transactions}
+          renderItem={renderItem}
+          keyExtractor={keyExtractor}
+          style={listStyle}
           contentContainerStyle={transactionListStyles.scrollContent}
           showsVerticalScrollIndicator={false}
-        >
-          {transactions.map((transaction) => (
-            <TransactionItem key={transaction.id} transaction={transaction} translations={translations} dateFormatter={dateFormatter} />
-          ))}
-        </ScrollView>
+          removeClippedSubviews={true}
+          maxToRenderPerBatch={10}
+          windowSize={5}
+          initialNumToRender={10}
+        />
       )}
     </View>
   );
-};
+});

package/src/domains/wallet/presentation/components/TransactionListStates.tsx

@@ -8,15 +8,15 @@ interface LoadingStateProps {
   message: string;
 }
 
-export const LoadingState: React.FC<LoadingStateProps> = ({ message }) => (
+export const LoadingState: React.FC<LoadingStateProps> = React.memo(({ message }) => (
   <AtomicSpinner size="lg" color="primary" text={message} style={transactionListStyles.stateContainer} />
-);
+));
 
 interface EmptyStateProps {
   message: string;
 }
 
-export const EmptyState: React.FC<EmptyStateProps> = ({ message }) => {
+export const EmptyState: React.FC<EmptyStateProps> = React.memo(({ message }) => {
   const tokens = useAppDesignTokens();
   return (
     <View style={transactionListStyles.stateContainer}>
@@ -26,4 +26,4 @@ export const EmptyState: React.FC<EmptyStateProps> = ({ message }) => {
       </AtomicText>
     </View>
   );
-};
+});

package/src/domains/wallet/presentation/screens/WalletScreen.tsx

@@ -10,7 +10,7 @@ import { BalanceCard } from "../components/BalanceCard";
 import { TransactionList } from "../components/TransactionList";
 import { WalletScreenProps } from "./WalletScreen.types";
 
-export const WalletScreen: React.FC<WalletScreenProps> = ({ translations, onBack, dateFormatter, footer }) => {
+export const WalletScreen: React.FC<WalletScreenProps> = React.memo(({ translations, onBack, dateFormatter, footer }) => {
   const tokens = useAppDesignTokens();
   const navigation = useNavigation();
   const config = getWalletConfig();
@@ -57,7 +57,7 @@ export const WalletScreen: React.FC<WalletScreenProps> = ({ translations, onBack
       />
     </ScreenLayout>
   );
-};
+});
 
 const styles = StyleSheet.create({
   content: { paddingBottom: 24 },

package/src/shared/utils/arrayUtils.ts

@@ -0,0 +1,65 @@
+/**
+ * Array validation and utility functions
+ */
+
+/**
+ * Check if array has items
+ */
+export function hasItems<T>(arr: readonly T[] | T[] | null | undefined): boolean {
+  return Array.isArray(arr) && arr.length > 0;
+}
+
+/**
+ * Check if array is empty
+ */
+export function isEmptyArray<T>(arr: readonly T[] | T[] | null | undefined): boolean {
+  return !Array.isArray(arr) || arr.length === 0;
+}
+
+/**
+ * Get array length safely (returns 0 for null/undefined)
+ */
+export function getArrayLength<T>(arr: T[] | null | undefined): number {
+  return Array.isArray(arr) ? arr.length : 0;
+}
+
+/**
+ * Find item in array by predicate
+ */
+export function findItem<T>(
+  arr: T[] | null | undefined,
+  predicate: (item: T) => boolean
+): T | undefined {
+  if (!Array.isArray(arr)) return undefined;
+  return arr.find(predicate);
+}
+
+/**
+ * Filter array by predicate
+ */
+export function filterItems<T>(
+  arr: T[] | null | undefined,
+  predicate: (item: T) => boolean
+): T[] {
+  if (!Array.isArray(arr)) return [];
+  return arr.filter(predicate);
+}
+
+/**
+ * Map array safely (returns empty array for null/undefined)
+ */
+export function mapItems<T, R>(
+  arr: T[] | null | undefined,
+  mapper: (item: T) => R
+): R[] {
+  if (!Array.isArray(arr)) return [];
+  return arr.map(mapper);
+}
+
+/**
+ * Check if array contains item
+ */
+export function arrayContains<T>(arr: T[] | null | undefined, item: T): boolean {
+  if (!Array.isArray(arr)) return false;
+  return arr.includes(item);
+}

package/src/shared/utils/stringUtils.ts

@@ -0,0 +1,64 @@
+/**
+ * String validation and utility functions
+ */
+
+/**
+ * Check if string is not empty
+ */
+export function isNonEmptyString(str: string | null | undefined): boolean {
+  return typeof str === "string" && str.length > 0;
+}
+
+/**
+ * Check if string is empty
+ */
+export function isEmptyString(str: string | null | undefined): boolean {
+  return !isNonEmptyString(str);
+}
+
+/**
+ * Trim string and check if not empty
+ */
+export function isNonEmptyAfterTrim(str: string | null | undefined): boolean {
+  if (typeof str !== "string") return false;
+  return str.trim().length > 0;
+}
+
+/**
+ * Get trimmed string or empty string
+ */
+export function getTrimmedString(str: string | null | undefined): string {
+  if (typeof str !== "string") return "";
+  return str.trim();
+}
+
+/**
+ * Check if string equals one of the values
+ */
+export function stringEqualsAny(
+  str: string | null | undefined,
+  values: string[]
+): boolean {
+  if (typeof str !== "string") return false;
+  return values.includes(str);
+}
+
+/**
+ * Check if string contains substring
+ */
+export function stringContains(
+  str: string | null | undefined,
+  substring: string
+): boolean {
+  if (typeof str !== "string") return false;
+  return str.includes(substring);
+}
+
+/**
+ * Check if string is neither 'undefined' nor 'null' string
+ */
+export function isValidString(str: string | null | undefined): boolean {
+  if (typeof str !== "string") return false;
+  const trimmed = str.trim();
+  return trimmed.length > 0 && trimmed !== "undefined" && trimmed !== "null";
+}