@ersbeth/picoflow 0.2.3 → 1.0.0

package/docs/guide/primitives/resources.md

@@ -0,0 +1,858 @@
+# 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
+```