@ersbeth/picoflow 1.1.2 → 2.0.0

package/docs/guide/primitives/resources.md

@@ -1,858 +0,0 @@
-# Resources
-
-Resources are specialized reactive primitives for managing data that needs to be fetched, loaded, or retrieved. They're perfect for API calls, file loading, and any data that requires a fetch operation.
-
-## Understanding Resources
-
-A **resource** is like a state that knows how to fetch its own data. Instead of manually fetching and setting state, you provide a fetch function and let the resource manage the lifecycle.
-
-Think of it like a **self-updating contact card** - instead of manually calling someone to get their latest info, the card knows how to call them and update itself.
-
-### Resources vs State
-
-| Feature | State | Resource |
-|---------|-------|----------|
-| Initial value | Required | Optional (can be undefined) |
-| How to update | `.set()` manually | `.fetch()` to refetch |
-| Use case | User input, toggles | API data, file loading |
-| Data source | Set by your code | Fetched by provided function |
-
-## When to Use Resources
-
-Use resources when:
-- ✅ Data comes from an API or external source
-- ✅ You need to refetch data based on triggers
-- ✅ You want built-in loading/undefined states
-- ✅ The fetch logic should be encapsulated
-
-Use regular state when:
-- ✅ You control the data directly (form inputs, UI state)
-- ✅ Data doesn't need to be fetched
-- ✅ Updates come from user actions
-
-## Synchronous Resources
-
-Synchronous resources use a regular function (not async) to fetch data:
-
-```typescript
-import { resource } from '@ersbeth/picoflow'
-
-const $config = resource(
-  () => {
-    // Fetch function (synchronous)
-    return loadConfigFromFile()
-  },
-  null // Initial value (optional)
-)
-```
-
-### Creating a Resource
-
-```typescript
-import { resource, effect } from '@ersbeth/picoflow'
-
-// Resource with initial value
-const $userData = resource(
-  () => fetchUserFromCache(),
-  { id: 0, name: 'Guest' } // Initial value
-)
-
-// Resource without initial value (starts as undefined)
-const $data = resource(
-  () => loadData(),
-  undefined
-)
-
-// Use in effect
-effect((t) => {
-  const data = $data.get(t)
-  if (data) {
-    console.log('Data loaded:', data)
-  } else {
-    console.log('No data yet')
-  }
-})
-```
-
-### Fetching and Refetching
-
-Call `.fetch()` to trigger a data fetch:
-
-```typescript
-const $posts = resource(
-  () => getPosts(),
-  []
-)
-
-// Initial fetch
-$posts.fetch()
-
-// Later, refetch when needed
-function refreshPosts() {
-  $posts.fetch() // Fetches and updates
-}
-
-// Automatic refetch in effect
-const $userId = state(1)
-
-effect((t) => {
-  const userId = $userId.get(t)
-  $posts.fetch() // Refetch when userId changes
-})
-```
-
-### Resource Lifecycle
-
-```mermaid
-stateDiagram-v2
-    [*] --> Idle: Create resource
-    Idle --> Fetching: .fetch() called
-    Fetching --> Ready: Fetch complete
-    Ready --> Fetching: .fetch() called again
-    Ready --> Disposed: .dispose()
-    Fetching --> Disposed: .dispose()
-    Idle --> Disposed: .dispose()
-    Disposed --> [*]
-    
-    note right of Idle: Value is initial value<br/>or undefined
-    note right of Ready: Value is fetched data
-```
-
-## Asynchronous Resources
-
-Asynchronous resources use async functions and return Promises:
-
-```typescript
-import { resourceAsync } from '@ersbeth/picoflow'
-
-const $user = resourceAsync(async () => {
-  const response = await fetch('/api/user')
-  return response.json()
-})
-```
-
-### How Async Resources Work
-
-```mermaid
-flowchart TD
-    A[Create resourceAsync] --> B[.fetch called or reactive dependency triggers]
-    B --> C[Execute async fetch function]
-    C --> D[Return Promise]
-    D --> E{Use .get t in effect}
-    E --> F[await Promise]
-    F --> G[Effect has resolved value]
-    
-    H[Dependency changes] --> B
-```
-
-The key difference: `.get(t)` returns a **Promise**, not the value directly.
-
-### Using Async Resources
-
-```typescript
-import { resourceAsync, effect } from '@ersbeth/picoflow'
-
-const $posts = resourceAsync(async () => {
-  const response = await fetch('https://api.example.com/posts')
-  return response.json()
-})
-
-// Use with async effect
-effect(async (t) => {
-  const posts = await $posts.get(t) // Wait for Promise
-  console.log('Posts:', posts)
-})
-
-// Trigger fetch
-$posts.fetch()
-```
-
-### Reactive Fetching
-
-Combine with state for reactive data loading:
-
-```typescript
-const $userId = state(1)
-
-const $user = resourceAsync(async () => {
-  const id = $userId.pick() // Read current user ID
-  const response = await fetch(`/api/users/${id}`)
-  return response.json()
-})
-
-// Refetch when user ID changes
-effect((t) => {
-  const userId = $userId.get(t)
-  $user.fetch() // Fetch new user data
-})
-
-// Display user data
-effect(async (t) => {
-  const user = await $user.get(t)
-  displayUser(user)
-})
-```
-
-## Handling Undefined State
-
-Resources can be undefined initially:
-
-```typescript
-const $data = resource(
-  () => loadData(),
-  undefined // Starts as undefined
-)
-
-effect((t) => {
-  const data = $data.get(t)
-  
-  if (data === undefined) {
-    showLoading()
-  } else {
-    showData(data)
-  }
-})
-
-// Trigger fetch
-$data.fetch()
-```
-
-For better type safety, use a discriminated union:
-
-```typescript
-type DataState<T> = 
-  | { status: 'loading' }
-  | { status: 'loaded'; data: T }
-  | { status: 'error'; error: string }
-
-const $userState = state<DataState<User>>({ status: 'loading' })
-
-const $user = resourceAsync(async () => {
-  try {
-    $userState.set({ status: 'loading' })
-    const data = await fetchUser()
-    $userState.set({ status: 'loaded', data })
-    return data
-  } catch (error) {
-    $userState.set({ status: 'error', error: error.message })
-    throw error
-  }
-})
-```
-
-## Practical Examples
-
-### Example 1: API Data Fetching
-
-```typescript
-import { resourceAsync, state, effect } from '@ersbeth/picoflow'
-
-interface Post {
-  id: number
-  title: string
-  body: string
-}
-
-const $posts = resourceAsync(async () => {
-  const response = await fetch('https://jsonplaceholder.typicode.com/posts')
-  if (!response.ok) throw new Error('Failed to fetch')
-  return response.json() as Promise<Post[]>
-})
-
-// Loading state
-const $loading = state(false)
-
-// Fetch with loading state
-async function fetchPosts() {
-  $loading.set(true)
-  try {
-    await $posts.fetch()
-  } finally {
-    $loading.set(false)
-  }
-}
-
-// Display posts
-effect(async (t) => {
-  const posts = await $posts.get(t)
-  const loading = $loading.get(t)
-  
-  if (loading) {
-    showSpinner()
-  } else {
-    displayPosts(posts)
-  }
-})
-
-// Initial fetch
-fetchPosts()
-```
-
-### Example 2: User Profile with Dependencies
-
-```typescript
-const $userId = state<number | null>(null)
-
-const $userProfile = resourceAsync(async () => {
-  const userId = $userId.pick()
-  if (!userId) throw new Error('No user ID')
-  
-  const response = await fetch(`/api/users/${userId}`)
-  return response.json()
-})
-
-// Refetch when user ID changes
-effect((t) => {
-  const userId = $userId.get(t)
-  if (userId) {
-    $userProfile.fetch()
-  }
-})
-
-// Display profile
-effect(async (t) => {
-  try {
-    const profile = await $userProfile.get(t)
-    displayProfile(profile)
-  } catch (error) {
-    showError('Failed to load user')
-  }
-})
-
-// Change user
-$userId.set(42) // Automatically triggers refetch
-```
-
-### Example 3: Configuration Loading
-
-```typescript
-interface AppConfig {
-  apiUrl: string
-  features: Record<string, boolean>
-  theme: string
-}
-
-const $config = resource(
-  () => {
-    // Load from localStorage or defaults
-    const stored = localStorage.getItem('config')
-    return stored 
-      ? JSON.parse(stored) 
-      : { apiUrl: '/api', features: {}, theme: 'light' }
-  },
-  null // No initial value, will fetch on first access
-)
-
-// Load config on app start
-$config.fetch()
-
-// Use config throughout app
-effect((t) => {
-  const config = $config.get(t)
-  if (config) {
-    applyTheme(config.theme)
-  }
-})
-```
-
-### Example 4: File Loading
-
-```typescript
-const $selectedFile = state<File | null>(null)
-
-const $fileContent = resourceAsync(async () => {
-  const file = $selectedFile.pick()
-  if (!file) throw new Error('No file selected')
-  
-  return file.text()
-})
-
-// Handle file selection
-function handleFileSelect(file: File) {
-  $selectedFile.set(file)
-  $fileContent.fetch()
-}
-
-// Display content
-effect(async (t) => {
-  try {
-    const content = await $fileContent.get(t)
-    displayContent(content)
-  } catch (error) {
-    showError('Failed to read file')
-  }
-})
-```
-
-## Error Handling
-
-### Basic Error Handling
-
-```typescript
-const $data = resourceAsync(async () => {
-  const response = await fetch('/api/data')
-  if (!response.ok) {
-    throw new Error(`HTTP ${response.status}`)
-  }
-  return response.json()
-})
-
-effect(async (t) => {
-  try {
-    const data = await $data.get(t)
-    displayData(data)
-  } catch (error) {
-    console.error('Failed to load data:', error)
-    showError(error.message)
-  }
-})
-```
-
-### With Error State
-
-```typescript
-const $data = resourceAsync(async () => {
-  const response = await fetch('/api/data')
-  if (!response.ok) throw new Error('Failed to fetch')
-  return response.json()
-})
-
-const $error = state<string | null>(null)
-const $loading = state(false)
-
-async function loadData() {
-  $loading.set(true)
-  $error.set(null)
-  
-  try {
-    await $data.fetch()
-  } catch (error) {
-    $error.set(error.message)
-  } finally {
-    $loading.set(false)
-  }
-}
-
-effect(async (t) => {
-  const loading = $loading.get(t)
-  const error = $error.get(t)
-  
-  if (loading) return showLoading()
-  if (error) return showError(error)
-  
-  const data = await $data.get(t)
-  showData(data)
-})
-```
-
-### Retry Logic
-
-```typescript
-async function fetchWithRetry(
-  resourceFn: () => Promise<void>,
-  maxRetries = 3
-) {
-  for (let i = 0; i < maxRetries; i++) {
-    try {
-      await resourceFn()
-      return // Success!
-    } catch (error) {
-      if (i === maxRetries - 1) throw error // Last attempt failed
-      await new Promise(resolve => setTimeout(resolve, 1000 * (i + 1)))
-    }
-  }
-}
-
-// Usage
-const $data = resourceAsync(async () => {
-  const response = await fetch('/api/data')
-  if (!response.ok) throw new Error('Failed to fetch')
-  return response.json()
-})
-
-fetchWithRetry(() => $data.fetch())
-```
-
-## Resource State Transitions
-
-Understanding the states a resource goes through:
-
-```mermaid
-stateDiagram-v2
-    [*] --> Initial: Create resource
-    Initial --> Fetching: fetch() called
-    Fetching --> Loaded: Success
-    Fetching --> Error: Fetch failed
-    Loaded --> Fetching: fetch() called
-    Error --> Fetching: fetch() called (retry)
-    Loaded --> [*]: dispose()
-    Error --> [*]: dispose()
-    
-    note right of Initial: value = initial value<br/>or undefined
-    note right of Fetching: Promise pending
-    note right of Loaded: value = fetched data
-    note right of Error: Exception thrown
-```
-
-## Best Practices
-
-### 1. Provide Initial Values When Possible
-
-```typescript
-// ✅ Good - immediate data available
-const $user = resource(
-  () => loadUserFromCache(),
-  { id: 0, name: 'Guest' }
-)
-
-// ⚠️ Okay but requires undefined check
-const $user = resource(
-  () => loadUserFromCache(),
-  undefined
-)
-```
-
-### 2. Handle Errors Gracefully
-
-```typescript
-// ✅ Always handle errors in async resources
-effect(async (t) => {
-  try {
-    const data = await $resource.get(t)
-    showData(data)
-  } catch (error) {
-    showError(error)
-  }
-})
-```
-
-### 3. Use Loading States
-
-```typescript
-const $loading = state(false)
-
-async function loadResource() {
-  $loading.set(true)
-  try {
-    await $resource.fetch()
-  } finally {
-    $loading.set(false)
-  }
-}
-```
-
-### 4. Cleanup on Disposal
-
-```typescript
-const $resource = resourceAsync(async () => {
-  const controller = new AbortController()
-  
-  try {
-    const response = await fetch('/api/data', {
-      signal: controller.signal
-    })
-    return response.json()
-  } catch (error) {
-    if (error.name === 'AbortError') {
-      return null
-    }
-    throw error
-  }
-})
-
-// Later, dispose to cancel pending requests
-$resource.dispose()
-```
-
-### 5. Cache Results When Appropriate
-
-```typescript
-// Simple cache wrapper
-function cachedResource<T>(
-  fetchFn: () => T,
-  cacheTime: number
-) {
-  let lastFetch = 0
-  let cached: T | undefined
-  
-  return resource(
-    () => {
-      const now = Date.now()
-      if (cached && now - lastFetch < cacheTime) {
-        return cached // Return cached value
-      }
-      cached = fetchFn()
-      lastFetch = now
-      return cached
-    },
-    undefined
-  )
-}
-
-const $data = cachedResource(
-  () => expensiveFetchOperation(),
-  60000 // Cache for 1 minute
-)
-```
-
-## Comparing: Resource vs ResourceAsync
-
-```mermaid
-flowchart TD
-    A{Is fetch function async?} -->|Yes| B[Use resourceAsync]
-    A -->|No| C[Use resource]
-    B --> D[Returns Promise]
-    C --> E[Returns value directly]
-    D --> F[Use await in effects]
-    E --> G[Use value directly]
-    
-    style B fill:#FFE6E6
-    style C fill:#E6FFE6
-```
-
-## Complete Example: User Dashboard
-
-```typescript
-import { state, resourceAsync, derivation, effect } from '@ersbeth/picoflow'
-
-interface User {
-  id: number
-  name: string
-  email: string
-  role: string
-}
-
-interface Stats {
-  loginCount: number
-  lastLogin: string
-}
-
-// Current user ID
-const $currentUserId = state<number>(1)
-
-// User resource
-const $user = resourceAsync(async () => {
-  const userId = $currentUserId.pick()
-  const response = await fetch(`/api/users/${userId}`)
-  if (!response.ok) throw new Error('User not found')
-  return response.json() as Promise<User>
-})
-
-// User stats resource
-const $stats = resourceAsync(async () => {
-  const userId = $currentUserId.pick()
-  const response = await fetch(`/api/users/${userId}/stats`)
-  return response.json() as Promise<Stats>
-})
-
-// Loading states
-const $loading = state(false)
-const $error = state<string | null>(null)
-
-// Derived: is admin
-const $isAdmin = derivation(async (t) => {
-  const user = await $user.get(t)
-  return user.role === 'admin'
-})
-
-// Fetch user data when ID changes
-effect((t) => {
-  const userId = $currentUserId.get(t)
-  
-  async function loadUser() {
-    $loading.set(true)
-    $error.set(null)
-    
-    try {
-      await Promise.all([
-        $user.fetch(),
-        $stats.fetch()
-      ])
-    } catch (error) {
-      $error.set(error.message)
-    } finally {
-      $loading.set(false)
-    }
-  }
-  
-  loadUser()
-})
-
-// Display user info
-effect(async (t) => {
-  const loading = $loading.get(t)
-  if (loading) return showLoadingSpinner()
-  
-  const error = $error.get(t)
-  if (error) return showError(error)
-  
-  try {
-    const user = await $user.get(t)
-    const stats = await $stats.get(t)
-    
-    displayUserInfo(user, stats)
-  } catch (error) {
-    showError('Failed to load user data')
-  }
-})
-
-// Switch user
-function switchUser(newUserId: number) {
-  $currentUserId.set(newUserId) // Automatically triggers refetch
-}
-```
-
-## Common Patterns
-
-### Pattern 1: Dependent Resources
-
-```typescript
-// First resource
-const $userId = state(1)
-const $user = resourceAsync(async () => {
-  const response = await fetch(`/api/users/${$userId.pick()}`)
-  return response.json()
-})
-
-// Second resource depends on first
-const $userPosts = resourceAsync(async () => {
-  const user = await $user.get(null) // Read without tracking
-  const response = await fetch(`/api/users/${user.id}/posts`)
-  return response.json()
-})
-
-// Fetch both when user changes
-effect((t) => {
-  $userId.get(t)
-  
-  async function loadAll() {
-    await $user.fetch()
-    await $userPosts.fetch() // Fetch posts after user loads
-  }
-  
-  loadAll()
-})
-```
-
-### Pattern 2: Polling
-
-```typescript
-const $liveData = resourceAsync(async () => {
-  const response = await fetch('/api/live-data')
-  return response.json()
-})
-
-// Poll every 5 seconds
-const pollInterval = setInterval(() => {
-  $liveData.fetch()
-}, 5000)
-
-// Don't forget cleanup!
-function stopPolling() {
-  clearInterval(pollInterval)
-}
-```
-
-### Pattern 3: Optimistic Updates
-
-```typescript
-const $items = state([{ id: 1, name: 'Item 1' }])
-
-async function addItem(name: string) {
-  const newItem = { id: Date.now(), name }
-  
-  // Optimistic update
-  $items.set(items => [...items, newItem])
-  
-  try {
-    await fetch('/api/items', {
-      method: 'POST',
-      body: JSON.stringify(newItem)
-    })
-    // Success - keep optimistic update
-  } catch (error) {
-    // Rollback on error
-    $items.set(items => items.filter(i => i.id !== newItem.id))
-    showError('Failed to add item')
-  }
-}
-```
-
-## Best Practices Summary
-
-### ✅ Do
-
-- Handle errors in async resources
-- Provide initial values when possible
-- Use loading states for better UX
-- Cancel requests on disposal
-- Cache when appropriate
-
-### ❌ Don't
-
-- Forget error handling
-- Fetch unnecessarily (check if data is still fresh)
-- Create resources inside effects
-- Ignore loading states
-- Leave pending requests on cleanup
-
-## Common Pitfalls
-
-### Pitfall 1: Not Handling Async Errors
-
-```typescript
-// ❌ Unhandled error crashes effect
-effect(async (t) => {
-  const data = await $resource.get(t) // Might throw!
-  display(data)
-})
-
-// ✅ Proper error handling
-effect(async (t) => {
-  try {
-    const data = await $resource.get(t)
-    display(data)
-  } catch (error) {
-    handleError(error)
-  }
-})
-```
-
-### Pitfall 2: Forgetting to Call `.fetch()`
-
-```typescript
-const $data = resource(() => loadData(), undefined)
-
-// ❌ Resource never fetches!
-effect((t) => {
-  const data = $data.get(t) // Always undefined
-})
-
-// ✅ Trigger fetch
-$data.fetch()
-```
-
-### Pitfall 3: Race Conditions
-
-```typescript
-const $query = state('initial')
-
-const $results = resourceAsync(async () => {
-  const query = $query.pick()
-  const response = await fetch(`/api/search?q=${query}`)
-  return response.json()
-})
-
-effect((t) => {
-  $query.get(t)
-  $results.fetch()
-})
-
-// ⚠️ Race condition if user types fast:
-$query.set('a')    // Fetch starts for 'a'
-$query.set('ab')   // Fetch starts for 'ab'
-$query.set('abc')  // Fetch starts for 'abc'
-// Results might arrive out of order!
-
-// ✅ Better - use AbortController or check query hasn't changed
-```