@ersbeth/picoflow 1.0.1 → 1.1.0

package/.cursor/plans/unifier-flowresource-avec-flowderivation-c9506e24.plan.md

@@ -0,0 +1,372 @@
+<!-- c9506e24-37d6-4d95-a937-545ccc76fe61 744135bd-5bf9-4a27-9006-1c9cfd4392d8 -->
+# Plan d'implémentation : Unification FlowResource avec FlowDerivation (approche intégrée)
+
+## 1. Modifications d'API
+
+### 1.1 FlowDerivation - Option `synchrone` et méthode `refresh()`
+
+**Fichier**: `src/basic/derivation.ts`
+
+**Modifications du constructeur**:
+
+```typescript
+constructor(
+  compute: (t: TrackingContext) => T | Promise<T>,
+  options?: {
+    synchrone?: boolean;  // Si true avec fonction async, retourne T | undefined
+  }
+)
+```
+
+**Nouvelle méthode**:
+
+```typescript
+public refresh(): void
+```
+
+**Comportement avec `synchrone: true`**:
+
+- Quand `synchrone: true` est fourni avec une fonction async (`Promise<T>`):
+  - Le type de retour devient `FlowDerivation<T | undefined>` au lieu de `FlowDerivation<Promise<T>>`
+  - Retourne `undefined` initialement, puis `T` une fois la Promise résolue
+  - Compare les valeurs avec `===` avant de notifier (évite notifications inutiles)
+  - Gère les erreurs de Promise (throw)
+- Quand `synchrone: true` est fourni avec une fonction synchrone:
+  - Erreur de type TypeScript (incompatibilité de types)
+- `refresh()` marque comme dirty et notifie (même comportement que sans option)
+
+**Usage**:
+
+```typescript
+// Dérivation async normale
+const $userAsync = derivation(async (t) => await fetchUser());
+const userPromise = $userAsync.pick(); // Promise<User>
+
+// Dérivation async synchronisée
+const $user = derivation(async (t) => await fetchUser(), { synchrone: true });
+const user = $user.pick(); // User | undefined
+
+// Refresh
+$user.refresh(); // Marque comme dirty
+await $user.pick(); // Déclenche le recalcul et attend
+```
+
+### 1.2 Suppression de FlowSynchronizer
+
+**Changement d'approche**:
+
+- Plus besoin de classe `FlowSynchronizer` séparée
+- La synchronisation est intégrée directement dans `FlowDerivation`
+
+### 1.3 Modifications des creators
+
+**Fichier**: `src/creators.ts`
+
+**Changements**:
+
+1. **`resourceAsync()`** - Simplifié:
+   ```typescript
+   // Avant: retourne FlowResourceAsync
+   // Après: retourne FlowDerivation<Promise<T>>
+   export function resourceAsync<T>(fn: () => Promise<T>): FlowDerivation<Promise<T>> {
+     return derivation(() => fn());
+   }
+   ```
+
+2. **`resource()`** - Utilise l'option `synchrone`:
+   ```typescript
+   // Avant: retourne FlowResource
+   // Après: retourne FlowDerivation<T | undefined>
+   export function resource<T>(fn: () => Promise<T>): FlowDerivation<T | undefined> {
+     return derivation(() => fn(), { synchrone: true });
+   }
+   ```
+
+
+### 1.4 Exports
+
+**Fichiers**: `src/advanced/index.ts`, `src/index.ts`
+
+**Suppressions** (après migration):
+
+- `FlowResource` (remplacé par `FlowDerivation` avec `synchrone: true`)
+- `FlowResourceAsync` (remplacé par `FlowDerivation<Promise<T>>`)
+- Plus besoin d'exporter `FlowSynchronizer`
+
+### 1.5 Rétrocompatibilité
+
+**Impact**:
+
+- Les types de retour changent, mais l'API reste compatible fonctionnellement
+- `resource()` et `resourceAsync()` continuent de fonctionner de la même manière
+- Les tests existants doivent continuer de passer (avec ajustements de types si nécessaire)
+
+## 2. Implémentations détaillées
+
+### 2.1 FlowDerivation - Support de l'option `synchrone`
+
+**Fichier**: `src/basic/derivation.ts`
+
+**Modifications du constructeur**:
+
+```typescript
+constructor(
+  compute: (t: TrackingContext) => T | Promise<T>,
+  options?: { synchrone?: boolean }
+) {
+  super();
+  this._compute = compute;
+  this._trackedContext = new TrackingContext(this);
+  this._synchrone = options?.synchrone ?? false;
+  
+  // Si synchrone est activé, on doit gérer les Promises différemment
+  if (this._synchrone) {
+    // Initialiser la valeur à undefined pour le mode synchrone
+    this._value = undefined as T;
+  }
+}
+```
+
+**Modifications de `_getRaw()`**:
+
+```typescript
+protected _getRaw(): T {
+  if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+  
+  this._initLazy();
+  this._update();
+  
+  if (this._synchrone) {
+    // En mode synchrone, la valeur peut être undefined si la Promise n'est pas encore résolue
+    return this._value as T;
+  }
+  
+  return this._value;
+}
+```
+
+**Modifications de `_update()` pour gérer la synchronisation**:
+
+```typescript
+private _update(): void {
+  if (this._dirty) {
+    // Store current dependencies
+    const dependencies = [...this._dependencies];
+
+    // Clear current dependencies, compute and retrack dependencies
+    this._dependencies.clear();
+    const computedValue = this._compute(this._trackedContext);
+    
+    if (this._synchrone && computedValue instanceof Promise) {
+      // Mode synchrone avec Promise
+      this._handleSyncPromise(computedValue as Promise<T>);
+    } else {
+      // Mode normal
+      this._value = computedValue;
+    }
+
+    // Unsubscribe from dependencies that are no longer needed
+    const dependenciesToRemove = dependencies.filter(
+      (dependency) => !this._dependencies.has(dependency),
+    );
+    dependenciesToRemove.forEach((dependency) => {
+      dependency._unregisterDependency(this);
+    });
+
+    this._dirty = false;
+  }
+}
+```
+
+**Nouvelle méthode `_handleSyncPromise()`**:
+
+```typescript
+private async _handleSyncPromise(promise: Promise<T>): Promise<void> {
+  // Marquer cette Promise comme la Promise courante
+  this._currentPromise = promise;
+  
+  try {
+    const value = await promise;
+    
+    // Vérifier que c'est toujours la Promise courante (éviter les race conditions)
+    if (this._currentPromise !== promise) {
+      return; // Une nouvelle Promise a été créée, ignorer cette résolution
+    }
+    
+    // Comparer avec la valeur actuelle pour éviter les notifications inutiles
+    if (value === this._value) {
+      return;
+    }
+    
+    // Mettre à jour la valeur et notifier
+    this._value = value as T;
+    this._notify();
+  } catch (error) {
+    // Vérifier que c'est toujours la Promise courante
+    if (this._currentPromise !== promise) {
+      return; // Une nouvelle Promise a été créée, ignorer cette erreur
+    }
+    
+    // Throw l'erreur
+    throw error;
+  }
+}
+```
+
+**Nouvelle méthode `refresh()`**:
+
+```typescript
+public refresh(): void {
+  if (this._disposed) throw new Error("[PicoFlow] Primitive is disposed");
+  
+  // Marquer comme dirty (le recalcul se fera au prochain accès)
+  this._dirty = true;
+  
+  // Notifier les dépendants pour qu'ils se marquent aussi comme dirty
+  this._notify();
+}
+```
+
+**Nouveaux champs privés**:
+
+```typescript
+private _synchrone: boolean;
+private _currentPromise?: Promise<T>;
+```
+
+**Points d'attention**:
+
+1. **Type safety**: Le type de retour doit être `FlowDerivation<T | undefined>` quand `synchrone: true` avec une fonction async
+2. **Gestion des Promises**: En mode synchrone, les Promises sont gérées de manière asynchrone dans `_handleSyncPromise()`
+3. **Comparaison de valeurs**: Utiliser `===` uniquement en mode synchrone
+4. **Race conditions**: Utiliser `_currentPromise` pour tracker la Promise courante
+5. **Initialisation**: En mode synchrone, initialiser `_value` à `undefined`
+6. **Lazy evaluation**: Le comportement lazy reste le même, mais la résolution de Promise est asynchrone
+
+### 2.2 Mise à jour des creators
+
+**Fichier**: `src/creators.ts`
+
+**Implémentation `resourceAsync()`**:
+
+```typescript
+export function resourceAsync<T>(fn: () => Promise<T>): FlowDerivation<Promise<T>> {
+  return derivation(() => fn());
+}
+```
+
+**Points d'attention**:
+
+- La fonction `fn` ne reçoit pas de `TrackingContext` (comportement actuel)
+- Retourne directement une `FlowDerivation<Promise<T>>`
+
+**Implémentation `resource()`**:
+
+```typescript
+export function resource<T>(fn: () => Promise<T>): FlowDerivation<T | undefined> {
+  return derivation(() => fn(), { synchrone: true });
+}
+```
+
+**Points d'attention**:
+
+- Utilise l'option `synchrone: true` pour activer le mode synchrone
+- Retourne `FlowDerivation<T | undefined>`
+
+### 2.3 Mise à jour des exports
+
+**Fichier**: `src/advanced/index.ts`
+
+**Modifications**:
+
+```typescript
+// Supprimer (après migration complète)
+// export { FlowResource } from "./resource";
+// export { FlowResourceAsync } from "./resourceAsync";
+// Plus besoin de FlowSynchronizer
+```
+
+**Fichier**: `src/index.ts`
+
+**Modifications**:
+
+```typescript
+// Supprimer FlowResource et FlowResourceAsync des exports
+export {
+  FlowArray,
+  type FlowArrayAction,
+  FlowMap,
+  FlowStream,
+  FlowStreamAsync,
+  // FlowResource,      // À supprimer
+  // FlowResourceAsync,  // À supprimer
+  ...
+} from "./advanced/";
+```
+
+### 2.4 Migration des tests
+
+**Fichiers**: `test/resource.test.ts`, `test/resourceAsync.test.ts`
+
+**Actions**:
+
+1. Mettre à jour les imports pour utiliser `FlowDerivation`
+2. Adapter les types de retour des fonctions `resource()` et `resourceAsync()`
+3. Adapter les appels à `refresh()` : `resource.refresh()` puis `await resource.pick()` si nécessaire
+4. Vérifier que tous les tests passent avec la nouvelle implémentation
+5. Potentiellement fusionner les tests si la logique est similaire
+
+**Points d'attention**:
+
+- Les tests de `resource()` doivent maintenant tester `FlowDerivation<T | undefined>` avec `synchrone: true`
+- Les tests de `resourceAsync()` doivent tester `FlowDerivation<Promise<T>>`
+- Vérifier que le comportement lazy est toujours correct
+- Vérifier que la comparaison de valeurs fonctionne en mode synchrone
+- Vérifier que les race conditions sont gérées correctement
+
+### 2.5 Suppression des anciennes classes
+
+**Fichiers**: `src/advanced/resource.ts`, `src/advanced/resourceAsync.ts`
+
+**Actions** (après vérification que tout fonctionne):
+
+1. Supprimer `src/advanced/resource.ts`
+2. Supprimer `src/advanced/resourceAsync.ts`
+3. Nettoyer les exports dans `src/advanced/index.ts`
+
+**Points d'attention**:
+
+- Ne supprimer qu'après avoir vérifié que tous les tests passent
+- Vérifier qu'aucun code externe n'importe directement ces classes
+- Mettre à jour la documentation si nécessaire
+
+## 3. Ordre d'implémentation recommandé
+
+1. **Étape 1**: Ajouter l'option `synchrone` et la méthode `refresh()` à `FlowDerivation` et tester
+2. **Étape 2**: Implémenter la gestion des Promises en mode synchrone avec comparaison de valeurs
+3. **Étape 3**: Mettre à jour les creators `resource()` et `resourceAsync()`
+4. **Étape 4**: Mettre à jour les exports
+5. **Étape 5**: Migrer et adapter les tests
+6. **Étape 6**: Supprimer les anciennes classes `FlowResource` et `FlowResourceAsync`
+
+## 4. Cas limites à tester
+
+1. **Race conditions**: Appels multiples rapides à `refresh()` avec mode synchrone
+2. **Erreurs async**: Promises rejetées dans les derivations en mode synchrone
+3. **Lazy initialization**: Vérifier que le fetch ne se fait qu'au premier accès
+4. **Comparaison de valeurs**: Vérifier que les notifications ne se déclenchent que si la valeur change (mode synchrone uniquement)
+5. **Disposal**: Vérifier le cleanup correct
+6. **Dérivations sync avec refresh()**: Vérifier que ça fonctionne aussi pour les derivations non-async
+7. **Refresh puis accès**: Vérifier que `refresh()` puis `pick()`/`get()` déclenche bien le recalcul
+8. **Refresh sur dérivation non-initialisée**: Vérifier que `refresh()` fonctionne même si la dérivation n'a pas encore été accédée
+9. **Mode synchrone avec fonction sync**: Vérifier que TypeScript lève une erreur de type
+10. **Plusieurs Promises successives**: Vérifier que seule la dernière Promise résolue met à jour la valeur
+
+### To-dos
+
+- [ ] Ajouter la méthode refresh() à FlowDerivation dans src/basic/derivation.ts avec gestion des derivations sync et async
+- [ ] Créer la classe FlowSynchronizer dans src/advanced/synchronizer.ts avec lazy initialization, gestion des race conditions, et comparaison de valeurs
+- [ ] Mettre à jour resource() et resourceAsync() dans src/creators.ts pour utiliser FlowDerivation et FlowSynchronizer
+- [ ] Mettre à jour les exports dans src/advanced/index.ts et src/index.ts pour exporter FlowSynchronizer et supprimer FlowResource/FlowResourceAsync
+- [ ] Adapter les tests dans test/resource.test.ts et test/resourceAsync.test.ts pour la nouvelle API
+- [ ] Supprimer src/advanced/resource.ts et src/advanced/resourceAsync.ts après vérification

package/README.md

@@ -23,4 +23,20 @@ For comprehensive guides and API documentation, visit the [official website](htt
 
 ## License
 
-This project is licensed under the [MIT License](LICENSE).
+This project is licensed under the [MIT License](LICENSE).
+
+## TODO
+
+- [x] implement refresh on derivations
+- [x] add tests for refresh
+- [x] improve tests for array / maps
+- [x] use same API for array and maps
+- [x] use async API for array updates
+- [x] manage unified disposal in collections
+- [ ] fix tests
+- [ ] implement sets
+- [x] implement await nodes
+- [ ] add tests for await nodes
+- [ ] add tests for raw nodes
+- [ ] replace resources by await nodes
+- [ ] think about streams

package/biome.json

@@ -15,7 +15,10 @@
 	"linter": {
 		"enabled": true,
 		"rules": {
-			"recommended": true
+			"recommended": true,
+			"complexity": {
+				"noStaticOnlyClass": "off"
+			}
 		}
 	},
 	"javascript": {