@ersbeth/picoflow 1.1.2 → 2.0.0

package/typedoc.json

@@ -1,37 +1,37 @@
 {
-	"$schema": "https://typedoc.org/schema.json",
-	"entryPoints": ["src/index.ts"],
-	"entryPointStrategy": "resolve",
-	"out": "docs/api",
-	"docsRoot": "docs",
-	"plugin": ["typedoc-plugin-markdown", "typedoc-vitepress-theme"],
-	"readme": "none",
-	"hideGenerator": true,
-	"cleanOutputDir": true,
-	"excludePrivate": true,
-	"excludeProtected": true,
-	"excludeExternals": true,
-	"excludeInternal": true,
-	"entryFileName": "index.md",
-	"hidePageHeader": true,
-	"hideBreadcrumbs": false,
-	"useCodeBlocks": true,
-	"expandObjects": true,
-	"parametersFormat": "table",
-	"propertiesFormat": "table",
-	"enumMembersFormat": "table",
-	"typeDeclarationFormat": "table",
-	"indexFormat": "table",
-	"outputFileStrategy": "members",
-	"flattenOutputFiles": false,
-	"fileExtension": ".md",
-	"publicPath": "/api/",
-	"textContentMappings": {
-		"header.title": "API Reference"
-	},
-	"externalSymbolLinkMappings": {
-		"@ersbeth/picoflow": {
-			"FlowObservable._getRaw": "#"
-		}
-	}
+    "$schema": "https://typedoc.org/schema.json",
+    "entryPoints": ["src/index.ts"],
+    "entryPointStrategy": "resolve",
+    "out": "docs/api",
+    "docsRoot": "docs",
+    "plugin": ["typedoc-plugin-markdown", "typedoc-vitepress-theme"],
+    "readme": "none",
+    "hideGenerator": true,
+    "cleanOutputDir": true,
+    "excludePrivate": true,
+    "excludeProtected": true,
+    "excludeExternals": true,
+    "excludeInternal": true,
+    "entryFileName": "index.md",
+    "hidePageHeader": true,
+    "hideBreadcrumbs": false,
+    "useCodeBlocks": true,
+    "expandObjects": true,
+    "parametersFormat": "table",
+    "propertiesFormat": "table",
+    "enumMembersFormat": "table",
+    "typeDeclarationFormat": "table",
+    "indexFormat": "table",
+    "outputFileStrategy": "members",
+    "flattenOutputFiles": false,
+    "fileExtension": ".md",
+    "publicPath": "/api/",
+    "textContentMappings": {
+        "header.title": "API Reference"
+    },
+    "externalSymbolLinkMappings": {
+        "@ersbeth/picoflow": {
+            "FlowObservable._getRaw": "#"
+        }
+    }
 }

package/vite.config.ts

@@ -1,29 +1,31 @@
 import { defineConfig } from "vite";
 import dts from "vite-plugin-dts";
+import tsconfigPaths from "vite-tsconfig-paths";
 
 export default defineConfig({
-	root: "./src",
-	build: {
-		outDir: "../dist",
-		emptyOutDir: true,
-		lib: {
-			entry: "index.ts",
-			formats: ["es"],
-		},
-		target: "esnext",
-		minify: false,
-		rollupOptions: {
-			external: ["solid-js"],
-		},
-	},
+    root: "./src",
+    build: {
+        outDir: "../dist",
+        emptyOutDir: true,
+        lib: {
+            entry: "index.ts",
+            formats: ["es"],
+        },
+        target: "esnext",
+        minify: false,
+        rollupOptions: {
+            external: ["solid-js"],
+        },
+    },
 
-	plugins: [
-		dts({
-			include: "**/*",
-			outDir: "../dist/types",
-			compilerOptions: {
-				rootDir: "src",
-			},
-		}),
-	],
+    plugins: [
+        tsconfigPaths(),
+        dts({
+            include: "**/*",
+            outDir: "../dist/types",
+            compilerOptions: {
+                rootDir: "src",
+            },
+        }),
+    ],
 });

package/vitest.browser.config.ts

@@ -0,0 +1,21 @@
+import { playwright } from "@vitest/browser-playwright";
+import solid from "vite-plugin-solid";
+import tsconfigPaths from "vite-tsconfig-paths";
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+    plugins: [solid(), tsconfigPaths()],
+    test: {
+        include: ["test/**/*.test.tsx"],
+        browser: {
+            enabled: true,
+            provider: playwright(),
+            // https://vitest.dev/config/browser/playwright
+            instances: [{ browser: "chromium" }],
+            viewport: {
+                width: 400,
+                height: 600,
+            },
+        },
+    },
+});

package/vitest.config.ts

@@ -1,17 +1,17 @@
 import solid from "vite-plugin-solid";
+import tsconfigPaths from "vite-tsconfig-paths";
 import { defineConfig } from "vitest/config";
 
 export default defineConfig({
-	plugins: [solid()],
-	resolve: {
-		conditions: ["development", "browser"],
-	},
-	test: {
-		include: ["test/**/*.test.ts"],
-		exclude: ["test/nodes/await/**/*"],
-		coverage: {
-			reporter: ["text"],
-			include: ["src/**/*"],
-		},
-	},
+    plugins: [solid(), tsconfigPaths()],
+    resolve: {
+        conditions: ["development", "browser"],
+    },
+    test: {
+        include: ["test/**/*.test.ts"],
+        coverage: {
+            reporter: ["text"],
+            include: ["src/**/*"],
+        },
+    },
 });

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

@@ -1,372 +0,0 @@
-<!-- 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