@ersbeth/picoflow 1.0.0 → 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

@@ -1,188 +1,42 @@
 # Picoflow
 
-**Picoflow** is a lightweight reactive dataflow library that provides fine-grained reactive primitives. It gives you an intuitive API for signals, state, asynchronous resources, streams, derivations, effects, and reactive maps. Picoflow uses an explicit tracking context to automatically track reactive dependencies.
+**Picoflow** is a lightweight reactive dataflow library that provides fine-grained reactive primitives. It gives you an intuitive API for signals, state, (asynchronous) derivations, effects, and reactive maps/arrays. Picoflow uses an explicit tracking context to automatically track reactive dependencies.
 
-> **Upgrading from v0.x?** See the [Upgrade Guide](UPGRADING.md) for migration instructions.
-
-## Features
-
-- **Reactive Signals:** Manually trigger updates using `$signal.trigger()`.
-- **Reactive State:** Manage state with observables that expose getter/setter APIs.
-- **Asynchronous Resources:** Fetch and update asynchronous data reactively.
-- **Reactive Streams:** Create streams that update over time using an updater function.
-- **Derivations:** Compute derived values from other reactive primitives.
-  - **Automatic Caching:** Derived values are cached and are re-evaluated only when one or more of their dependencies change.
-  - **Lazy Evaluation:** Derivations are evaluated lazily—that is, the computation only runs if and when an effect actually uses the derived value.
-- **Reactive Maps:** Manage collections reactively with granular update notifications.
-- **Effects:** Automatically run side-effect functions when dependencies change.
-- **Explicit Control:** Choose between reactive (`.get(t)`) and non-reactive (`.pick()`) reads for fine-grained control.
+> **Upgrading from v0.x?** See the [Upgrade Guide](https://ersbeth-web.gitlab.io/picoflow/guide/advanced/upgrading.html) for migration instructions.
 
 ## Installation
 
-Install via npm:
-
 ```bash
+# npm
 npm install @ersbeth/picoflow
-```
-
-## Usage
-
-In Picoflow, we advise to prefix all reactive primitives and effects with `$` for improved readability. Rather than using a subscribe method, you always create an effect that tracks dependencies using a tracking context. Below are some examples:
-
-### Creating a Signal
-
-```ts
-import { signal, effect } from '@ersbeth/picoflow';
-
-const $signal = signal();
-
-const $effect = effect((t) => {
-  // Automatically tracks $signal
-  $signal.watch(t);
-  console.log('$signal has been triggered');
-});
-
-// Trigger the signal
-$signal.trigger();
-
-// LOG -> $signal has been triggered
-```
-
-### Creating Reactive State
-
-```ts
-import { state, effect } from '@ersbeth/picoflow';
-
-const $count = state(0);
-
-const $effect = effect((t) => {
-  // Automatically tracks $count
-  console.log('Count changed:', $count.get(t));
-});
-
-// Update the state
-$count.set(42);
-
-// LOG -> Count changed: 42
-```
-
-### Creating an Asynchronous Resource
-
-```ts
-import { resource, effect } from '@ersbeth/picoflow';
-
-async function fetchData() {
-  const response = await fetch('https://api.example.com/data');
-  return response.json();
-}
-
-const $data = resource(fetchData, {});
-
-// Create an effect to watch for updates
-const $effect = effect((t) => {
-  console.log('Resource updated:', $data.get(t));
-});
-
-// Later, you can trigger a new fetch
-$data.fetch();
-```
-
-### Creating a Reactive Stream
 
-```ts
-import { stream, effect } from '@ersbeth/picoflow';
+# pnpm
+pnpm add @ersbeth/picoflow
 
-const $ticker = stream(
-  (set) => {
-    const interval = setInterval(() => set(Date.now()), 1000);
-    // Return a disposer to clear the interval when the stream is disposed.
-    return () => clearInterval(interval);
-  },
-  Date.now()
-);
-
-const $effect = effect((t) => {
-  console.log('Current time:', $ticker.get(t));
-});
-```
-
-### Creating a Derived Value
-
-```ts
-import { state, derivation, effect } from '@ersbeth/picoflow';
-
-const $a = state(10);
-const $b = state(20);
-
-// Create a derived value that sums $a and $b.
-const $sum = derivation((t) => {
-  return $a.get(t) + $b.get(t);
-});
-
-const $effect = effect((t) => {
-  console.log('Sum:', $sum.get(t));
-});
-
-// Update a dependency to see the derivation update.
-$a.set(15);
-```
-
-### Creating a Reactive Map
-
-Reactive maps allow fine-grained tracking of collection updates.
-
-```ts
-import { map, effect } from '@ersbeth/picoflow';
-
-const $map = map({ foo: 'bar' });
-
-const $effect = effect((t) => {
-  console.log('Map updated:', $map.get(t));
-});
-
-// Update the map to trigger updates
-$map.setAt('baz', 'qux');
-$map.delete('foo');
-```
-
-### Non-Reactive Reads
-
-Sometimes you need to read a value without creating a dependency. Use `pick()` for this:
-
-```ts
-import { state, signal, effect } from '@ersbeth/picoflow';
-
-const $data = state({ count: 0 });
-const $trigger = signal();
-
-const $effect = effect((t) => {
-  // React to $trigger changes only
-  $trigger.watch(t);
-  
-  // Read $data without creating a dependency
-  const snapshot = $data.pick();
-  console.log('Triggered! Current data:', snapshot);
-});
-
-$data.set({ count: 1 });  // Does NOT trigger the effect
-$trigger.trigger();        // Triggers the effect, logs: { count: 1 }
+# yarn
+yarn add @ersbeth/picoflow
 ```
 
 ## Documentation
 
-For comprehensive guides and API documentation, visit:
-
-- **[Getting Started](docs/guide/getting-started.md)** - Quick introduction to PicoFlow
-- **[API Reference](docs/api/index.md)** - Complete API documentation
-
-Or run the documentation locally:
-
-```bash
-pnpm docs:dev
-```
-
-Then open [http://localhost:5173](http://localhost:5173) in your browser.
+For comprehensive guides and API documentation, visit the [official website](https://ersbeth-web.gitlab.io/picoflow/)
 
 ## 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": {