@jsarc/native-cooks

@jsarc/native-cooks est une bibliothèque TypeScript/JavaScript pour la gestion du stockage persistant dans les applications React Native et Expo. Elle offre une API simple et intuitive pour stocker, récupérer et manipuler des données avec support des types complexes, sécurité et expiration automatique.

✨ Fonctionnalités Principales

• 📱 Multiplateforme : iOS, Android et Web
• 🔐 Stockage sécurisé : Utilise SecureStore pour les données sensibles
• 🔄 Sérialisation automatique : support des objets, tableaux, dates, et types primitifs
• 🕐 Expiration automatique : Les données expirées sont nettoyées automatiquement
• 🛡️ TypeScript-first : typage complet et auto-complétion
• ⚙️ Options avancées : expiration, stockage sécurisé
• 🚀 Performant : API asynchrone non-bloquante
• 🧪 Robuste : gestion d'erreurs et validation

📦 Installation

Via npm/yarn/pnpm

npm install @jsarc/native-cooks
# ou
yarn add @jsarc/native-cooks
# ou
pnpm add @jsarc/native-cooks

Dependencies requises

Installez également les dépendances requises :

# Expo
expo install @react-native-async-storage/async-storage expo-secure-store

# React Native
npm install @react-native-async-storage/async-storage react-native-sensitive-info

🚀 Démarrage Rapide

TypeScript/ES Modules

import NativeCooks from '@jsarc/native-cooks';
// ou
import { NativeCooks } from '@jsarc/native-cooks';

CommonJS

const { NativeCooks } = require('@jsarc/native-cooks');

📚 Documentation API

Types Supportés

type Serializable = 
  | string
  | number
  | boolean
  | Date
  | object
  | Array<any>
  | null
  | undefined;

Options de Stockage

interface NativeCooksOptions {
  expires?: Date | number; // Date ou nombre de secondes
  secure?: boolean; // Utilise SecureStore si true
}

NativeCooks.set()

Stocke une valeur avec sérialisation automatique.

// Stocker différents types de données
await NativeCooks.set('user', { name: 'John', age: 30 });
await NativeCooks.set('preferences', ['dark-mode', 'notifications']);
await NativeCooks.set('visitCount', 42);
await NativeCooks.set('isLoggedIn', true);
await NativeCooks.set('lastVisit', new Date());
await NativeCooks.set('message', 'Hello World!');

// Avec options avancées
await NativeCooks.set('session', 'token123', { 
  expires: 7 * 24 * 3600, // 7 jours en secondes
  secure: true // Stockage sécurisé
});

NativeCooks.get()

Récupère et désérialise une valeur.

const user = await NativeCooks.get('user'); // { name: 'John', age: 30 }
const preferences = await NativeCooks.get('preferences'); // ['dark-mode', 'notifications']
const visitCount = await NativeCooks.get('visitCount'); // 42
const isLoggedIn = await NativeCooks.get('isLoggedIn'); // true
const lastVisit = await NativeCooks.get('lastVisit'); // Date object
const message = await NativeCooks.get('message'); // 'Hello World!'
const notFound = await NativeCooks.get('nonexistent'); // null

NativeCooks.remove()

Supprime une valeur.

await NativeCooks.remove('session');
await NativeCooks.remove('user');

NativeCooks.has()

Vérifie si une valeur existe.

if (await NativeCooks.has('user')) {
  console.log('Utilisateur trouvé');
}

NativeCooks.keys()

Retourne toutes les clés disponibles.

const keys = await NativeCooks.keys(); // ['user', 'preferences', 'visitCount', ...]
console.log('Données stockées:', keys);

NativeCooks.clear()

Supprime toutes les données.

await NativeCooks.clear(); // Supprime toutes les données

🎯 Exemples Complets

Exemple 1 : Gestion d'Authentification

// Connexion utilisateur
async function login(userData: { id: number; name: string; email: string }) {
  await NativeCooks.set('auth_token', 'jwt_token_here', {
    expires: 24 * 3600, // 1 jour
    secure: true
  });
  
  await NativeCooks.set('user', userData, {
    expires: 7 * 24 * 3600 // 7 jours
  });
  
  await NativeCooks.set('last_login', new Date());
}

// Vérification de session
async function checkSession() {
  if (await NativeCooks.has('auth_token')) {
    const user = await NativeCooks.get('user');
    const lastLogin = await NativeCooks.get('last_login');
    
    console.log('Utilisateur connecté:', user);
    console.log('Dernière connexion:', lastLogin);
    return true;
  }
  return false;
}

// Déconnexion
async function logout() {
  await NativeCooks.remove('auth_token');
  await NativeCooks.remove('user');
  await NativeCooks.remove('last_login');
}

Exemple 2 : Cache avec Expiration

class DataCache {
  static async setWithCache(key: string, data: any, ttlSeconds: number = 300) {
    const cacheData = {
      data,
      timestamp: new Date(),
      expiresIn: ttlSeconds
    };
    
    await NativeCooks.set(`cache_\${key}`, cacheData, {
      expires: ttlSeconds
    });
  }
  
  static async getFromCache(key: string) {
    const cached = await NativeCooks.get(`cache_\${key}`);
    
    if (!cached) return null;
    
    // Vérifier si le cache est expiré
    const now = new Date();
    const cacheTime = new Date(cached.timestamp);
    const diffSeconds = (now.getTime() - cacheTime.getTime()) / 1000;
    
    if (diffSeconds > cached.expiresIn) {
      await NativeCooks.remove(`cache_\${key}`);
      return null;
    }
    
    return cached.data;
  }
  
  static async clearCache() {
    const keys = await NativeCooks.keys();
    const cacheKeys = keys.filter(key => key.startsWith('cache_'));
    
    for (const key of cacheKeys) {
      await NativeCooks.remove(key);
    }
  }
}

// Utilisation
await DataCache.setWithCache('api_data', { users: [] }, 60); // Cache pour 60 secondes
const cachedData = await DataCache.getFromCache('api_data');

Exemple 3 : Panier d'Achat (React Native)

interface CartItem {
  id: number;
  name: string;
  price: number;
  quantity: number;
}

class ShoppingCart {
  private static readonly CART_KEY = 'shopping_cart';
  
  static async addItem(item: CartItem): Promise<void> {
    const cart = await this.getCart();
    const existing = cart.find(i => i.id === item.id);
    
    if (existing) {
      existing.quantity += item.quantity;
    } else {
      cart.push(item);
    }
    
    await NativeCooks.set(this.CART_KEY, cart, {
      expires: 2 * 24 * 3600 // 2 jours
    });
  }
  
  static async removeItem(itemId: number): Promise<void> {
    const cart = (await this.getCart()).filter(item => item.id !== itemId);
    await NativeCooks.set(this.CART_KEY, cart);
  }
  
  static async getCart(): Promise<CartItem[]> {
    return (await NativeCooks.get(this.CART_KEY)) || [];
  }
  
  static async clearCart(): Promise<void> {
    await NativeCooks.remove(this.CART_KEY);
  }
  
  static async getTotal(): Promise<number> {
    const cart = await this.getCart();
    return cart.reduce((sum, item) => sum + (item.price * item.quantity), 0);
  }
  
  static async getItemCount(): Promise<number> {
    const cart = await this.getCart();
    return cart.reduce((sum, item) => sum + item.quantity, 0);
  }
}

// Utilisation dans un composant React Native
import React, { useState, useEffect } from 'react';
import { View, Text, Button } from 'react-native';

const CartScreen = () => {
  const [cart, setCart] = useState<CartItem[]>([]);
  
  useEffect(() => {
    loadCart();
  }, []);
  
  const loadCart = async () => {
    const cartData = await ShoppingCart.getCart();
    setCart(cartData);
  };
  
  const addToCart = async (item: CartItem) => {
    await ShoppingCart.addItem(item);
    await loadCart();
  };
  
  return (
    <View>
      <Text>Panier ({cart.length} articles)</Text>
      {cart.map(item => (
        <Text key={item.id}>
          {item.name} x{item.quantity} - ${item.price * item.quantity}
        </Text>
      ))}
      <Button title="Ajouter produit" onPress={() => addToCart({
        id: 1,
        name: 'Produit A',
        price: 29.99,
        quantity: 1
      })} />
    </View>
  );
};

🔧 Configuration

Options de Stockage

Par défaut, NativeCooks utilise :

• SecureStore pour les données marquées comme secure: true
• AsyncStorage pour les données non-sensibles
• Web Storage API pour les applications web

Sécurité

Pour les données sensibles (tokens, informations personnelles), utilisez toujours :

await NativeCooks.set('token', 'sensitive_data', {
  secure: true,
  expires: 3600 // 1 heure
});

Gestion des Erreurs

Toutes les méthodes retournent des Promises avec gestion d'erreurs :

try {
  await NativeCooks.set('data', importantData, { secure: true });
} catch (error) {
  console.error('Erreur de stockage:', error);
  // Fallback: stocker dans AsyncStorage
  await NativeCooks.set('data', importantData, { secure: false });
}

📋 Compatibilité

Plateformes Supportées

• ✅ iOS 12+
• ✅ Android 5+
• ✅ Web (via AsyncStorage polyfill)
• ✅ Expo SDK 48+

Dependencies

• @react-native-async-storage/async-storage (requis)
• expo-secure-store (pour Expo)
• react-native-sensitive-info (pour React Native sans Expo)

🚨 Notes Importantes

Limitations

• Taille limitée : SecureStore ~2KB par clé, AsyncStorage ~6MB total
• Performances : Stockez seulement les données nécessaires
• Sécurité : SecureStore n'est pas disponible sur toutes les plateformes web

Bonnes Pratiques

// ✅ Bonnes pratiques
await NativeCooks.set('user_token', token, {
  expires: 24 * 3600, // 24 heures
  secure: true // Protection maximale
});

// Stocker les données volumineuses dans AsyncStorage
await NativeCooks.set('user_settings', settings, {
  secure: false // Données non-sensibles
});

// ❌ À éviter
// Ne stockez pas de données trop volumineuses
await NativeCooks.set('huge_data', veryLargeObject);

// Ne comptez pas uniquement sur SecureStore pour la sécurité

Migration depuis @jsarc/native_cooks

Si vous migrez depuis la version navigateur :

// Ancien code (navigateur)
Cooks.set('key', value, { expires: 3600 });

// Nouveau code (React Native)
await NativeCooks.set('key', value, { expires: 3600 });

// Note: Toutes les méthodes sont asynchrones
const data = await NativeCooks.get('key'); // Attendre la Promise

📄 Licence

MIT License - Voir le fichier LICENSE pour plus de détails.

@jsarc/native-cooks - Gestion de stockage pour React Native 📱

Développé par l'équipe INICODE