story-research-zapwall/docs/patterns/caching-patterns.md

# Patterns de cache d'événements

**Date** : 2024-12-19
**Auteur** : Équipe 4NK

## Introduction

Ce document décrit les patterns à utiliser pour cacher des événements Nostr dans IndexedDB.

## Pattern recommandé : Utilisation des helpers de cache

### Cache d'événements groupés par hash

Pour les objets qui ont plusieurs versions (publications, series), utiliser `groupAndCacheEventsByHash` :

```typescript
import { groupAndCacheEventsByHash } from '@/lib/helpers/eventCacheHelper'
import { extractPublicationFromEvent } from '@/lib/metadataExtractor'
import { parseObjectId } from '@/lib/urlGenerator'
import { extractTagsFromEvent } from '@/lib/nostrTagSystem'

await groupAndCacheEventsByHash(events, {
  objectType: 'publication',
  extractor: extractPublicationFromEvent,
  getHash: (extracted: unknown): string | null => {
    const id = (extracted as { id?: string })?.id
    if (!id) {
      return null
    }
    const parsed = parseObjectId(id)
    return parsed.hash ?? id
  },
  getIndex: (extracted: unknown): number => {
    return (extracted as { index?: number })?.index ?? 0
  },
  getVersion: (event: Event): number => {
    return extractTagsFromEvent(event).version ?? 0
  },
  getHidden: (event: Event): boolean => {
    return extractTagsFromEvent(event).hidden ?? false
  },
})
```

### Cache d'événements simples

Pour les objets sans versioning (purchases, sponsoring, review tips), utiliser `writeObjectToCache` :

```typescript
import { writeObjectToCache } from '@/lib/helpers/writeObjectHelper'

await writeObjectToCache({
  objectType: 'purchase',
  hash: purchase.hash,
  event,
  parsed: purchase,
  index: purchase.index,
})
```

### Cache avec extraction automatique

Pour combiner extraction et cache en une seule opération :

```typescript
import { extractAndWriteObject } from '@/lib/helpers/writeObjectHelper'
import { extractPurchaseFromEvent } from '@/lib/metadataExtractor'

const cached = await extractAndWriteObject(
  event,
  'purchase',
  extractPurchaseFromEvent
)

if (cached) {
  console.log('Event cached successfully')
}
```

## Pattern de cache dans les boucles

### Optimisation : Cache l'import de writeService

Le helper `writeObjectToCache` cache automatiquement l'import de `writeService`, donc pas besoin d'optimiser manuellement :

```typescript
// ✅ Bon : writeObjectToCache gère le cache automatiquement
for (const event of events) {
  await writeObjectToCache({
    objectType: 'purchase',
    hash: purchase.hash,
    event,
    parsed: purchase,
  })
}

// ❌ Éviter : Import répété dans la boucle
for (const event of events) {
  const { writeService } = await import('./writeService')
  await writeService.writeObject(...)
}
```

## Gestion des versions

Pour les objets avec versioning, `groupAndCacheEventsByHash` :
1. Groupe les événements par hash
2. Sélectionne la dernière version avec `getLatestVersion`
3. Cache uniquement la dernière version

```typescript
// Les événements sont automatiquement groupés par hash
// Seule la dernière version est cachée
await groupAndCacheEventsByHash(events, {
  objectType: 'publication',
  extractor: extractPublicationFromEvent,
  // ... config
})
```

## Bonnes pratiques

1. **Utiliser les helpers appropriés** :
   - `groupAndCacheEventsByHash` pour objets avec versioning
   - `writeObjectToCache` pour objets simples
   - `extractAndWriteObject` pour combiner extraction et cache

2. **Ne pas dupliquer la logique de cache** : Toujours utiliser les helpers centralisés

3. **Gérer les erreurs** : Les helpers propagent les erreurs, les gérer en amont

4. **Typage strict** : Utiliser les types TypeScript pour `parsed`

5. **Performance** : Les helpers optimisent automatiquement les imports

## Exemples complets

### Cache de publications avec groupement

```typescript
import { groupAndCacheEventsByHash } from '@/lib/helpers/eventCacheHelper'
import { cachePublicationsByHash } from '@/lib/helpers/syncContentCacheHelpers'

// Utiliser le helper spécialisé
await cachePublicationsByHash(events)
```

### Cache de purchases

```typescript
import { cachePurchases } from '@/lib/helpers/syncCacheHelpers'

await cachePurchases(events)
```

### Cache personnalisé

```typescript
import { writeObjectToCache } from '@/lib/helpers/writeObjectHelper'

for (const event of events) {
  const extracted = await extractMyObjectFromEvent(event)
  if (extracted?.hash) {
    await writeObjectToCache({
      objectType: 'my_object',
      hash: extracted.hash,
      event,
      parsed: extracted,
      version: extractTagsFromEvent(event).version,
      hidden: extractTagsFromEvent(event).hidden,
      index: extracted.index,
    })
  }
}
```