@ersbeth/picoflow 0.2.3 → 1.0.0

package/.cursor/plans/update-js-e795d61b.plan.md

@@ -0,0 +1,567 @@
+<!-- e795d61b-15e2-4796-9ca1-7878e5c3709b fe8b0d3c-6bd4-436a-9d8b-a0eedf4b07e4 -->
+# PicoFlow Guide Documentation Plan
+
+## Overview
+
+Write complete documentation for PicoFlow targeting complete beginners with no prior reactive programming experience. Use a concepts-first approach followed by practical examples with Mermaid diagrams for visual explanations. All content in English.
+
+## Current State
+
+Existing files in `docs/guide/`:
+
+- [getting-started.md](docs/guide/getting-started.md) - Basic intro (40 lines)
+- [installation.md](docs/guide/installation.md) - Complete (64 lines)
+- [concepts.md](docs/guide/concepts.md) - Good foundation (88 lines)
+- [state.md](docs/guide/state.md) - Stub (5 lines)
+- [effects-derivations.md](docs/guide/effects-derivations.md) - Stub to split into two files
+- [resources-streams.md](docs/guide/resources-streams.md) - Stub to split into two files
+- [advanced.md](docs/guide/advanced.md) - Stub (5 lines)
+- [examples.md](docs/guide/examples.md) - Stub (5 lines)
+
+## New File Structure
+
+After implementation:
+
+- [getting-started.md](docs/guide/getting-started.md)
+- [installation.md](docs/guide/installation.md)
+- [concepts.md](docs/guide/concepts.md)
+- [state.md](docs/guide/state.md)
+- [effects.md](docs/guide/effects.md) - NEW (split from effects-derivations.md)
+- [derivations.md](docs/guide/derivations.md) - NEW (split from effects-derivations.md)
+- [resources.md](docs/guide/resources.md) - NEW (split from resources-streams.md)
+- [streams.md](docs/guide/streams.md) - NEW (split from resources-streams.md)
+- [advanced.md](docs/guide/advanced.md)
+- [examples.md](docs/guide/examples.md)
+
+## Documentation Structure
+
+### 1. Update [getting-started.md](docs/guide/getting-started.md)
+
+**Goal**: Welcoming introduction that explains reactive programming from scratch
+
+**Content to add**:
+
+- What is reactive programming (analogy: spreadsheet cells)
+- Why use reactive programming (automatic updates, declarative code)
+- PicoFlow's philosophy (explicit tracking, fine-grained control)
+- Comparison with imperative approach (before/after example)
+- Enhanced quick example with annotations
+- Clear next steps
+
+**Mermaid diagrams**:
+
+- Flow diagram showing reactive vs imperative updates
+
+**Estimated length**: ~120-140 lines
+
+### 2. Keep [installation.md](docs/guide/installation.md) as-is
+
+Already complete and well-structured.
+
+### 3. Enhance [concepts.md](docs/guide/concepts.md)
+
+**Goal**: Deep dive into core concepts with beginner-friendly explanations
+
+**Content to improve/add**:
+
+- Explain "dependency" concept with simple analogy
+- Visual metaphor for TrackingContext (like a notebook recording what you read)
+- Detailed explanation of `.get(t)` vs `.pick()` with real-world scenarios
+- Add section on "The $ prefix convention"
+- Add section on "Disposal and cleanup"
+- Expand primitives overview with when to use each
+- Add common patterns section
+- More visual examples
+
+**Mermaid diagrams**:
+
+- TrackingContext dependency registration flow
+- Effect execution cycle
+- Comparison diagram of `.get(t)` vs `.pick()`
+
+**Estimated length**: ~180-200 lines
+
+### 4. Write [state.md](docs/guide/state.md)
+
+**Goal**: Complete guide to mutable and immutable reactive values
+
+**Sections**:
+
+1. Introduction to State
+
+- What is state
+- When to use state vs constants
+
+2. Creating State
+
+- Basic usage with `state()`
+- Initial values
+
+3. Reading State Values
+
+- Reactive reads with `.get(t)`
+- Non-reactive reads with `.pick()`
+
+4. Updating State
+
+- Direct values with `.set(value)`
+- Updater functions with `.set(fn)`
+
+5. Constants
+
+- What are constants
+- Lazy vs eager initialization
+- Use cases
+
+6. Practical Examples
+
+- Counter
+- Form state
+- Configuration values
+
+7. Best Practices
+
+- When to use state vs constants
+- Naming conventions
+- Common pitfalls
+
+**Mermaid diagrams**:
+
+- State update and notification flow
+- Lazy constant initialization diagram
+
+**Estimated length**: ~200-220 lines
+
+### 5. Write [effects.md](docs/guide/effects.md) - NEW FILE
+
+**Goal**: Comprehensive guide to side effects
+
+**Sections**:
+
+1. Understanding Effects
+
+- What are side effects
+- Examples of side effects (DOM updates, logging, API calls)
+- Why effects are needed in reactive systems
+
+2. How Effects Work
+
+- The tracking context
+- Automatic re-execution
+- Effect lifecycle
+
+3. Creating Effects
+
+- Basic syntax with `effect((t) => {})`
+- The tracking parameter
+- Immediate execution
+
+4. Effect Dependencies
+
+- Explicit dependency tracking with `.get(t)`
+- Multiple dependencies
+- Conditional dependencies
+- Avoiding dependencies with `.pick()`
+
+5. Effect Patterns
+
+- Logging and debugging
+- DOM manipulation
+- Local storage sync
+- Event handlers
+
+6. Disposal and Cleanup
+
+- When to dispose effects
+- Using `.dispose()`
+- Memory leak prevention
+
+7. Practical Examples
+
+- Console logging
+- Document title updates
+- Form validation feedback
+- Auto-save
+
+8. Best Practices
+
+- Keep effects focused
+- Avoid effects in effects
+- Error handling
+- Common pitfalls
+
+**Mermaid diagrams**:
+
+- Effect execution and re-execution flow
+- Dependency tracking visualization
+- Effect lifecycle diagram
+
+**Estimated length**: ~200-220 lines
+
+### 6. Write [derivations.md](docs/guide/derivations.md) - NEW FILE
+
+**Goal**: Complete guide to computed values
+
+**Sections**:
+
+1. Understanding Derivations
+
+- What are computed values
+- Pure functions concept
+- Difference between effects and derivations
+
+2. How Derivations Work
+
+- Lazy evaluation explained
+- Caching behavior
+- Dirty checking
+
+3. Creating Derivations
+
+- Basic syntax with `derivation((t) => {})`
+- Return values
+- Type inference
+
+4. Derivation Dependencies
+
+- Tracking with `.get(t)`
+- Multiple source dependencies
+- Chaining derivations
+
+5. Advanced Patterns
+
+- Combining multiple derivations
+- Conditional computations
+- Complex calculations
+- Performance considerations
+
+6. Practical Examples
+
+- Mathematical calculations (sum, average, total)
+- Filtered and sorted lists
+- Formatted values (currency, dates)
+- Derived UI state
+
+7. Best Practices
+
+- Keep derivations pure (no side effects)
+- Avoid expensive operations
+- When to use constants vs derivations
+- Common pitfalls
+
+**Mermaid diagrams**:
+
+- Derivation lazy evaluation flow
+- Derivation caching and invalidation
+- Comparison: derivation vs effect
+- Chained derivations dependency graph
+
+**Estimated length**: ~180-200 lines
+
+### 7. Write [resources.md](docs/guide/resources.md) - NEW FILE
+
+**Goal**: Complete guide to resource management
+
+**Sections**:
+
+1. Understanding Resources
+
+- What are resources
+- Difference from state
+- When to use resources
+- Pull-based data fetching
+
+2. Synchronous Resources
+
+- Creating with `resource(fetchFn, initialValue)`
+- The fetch function
+- Initial values
+- Undefined state handling
+
+3. Fetching and Refetching
+
+- Manual fetch with `.fetch()`
+- Reactive refetching
+- Loading states
+
+4. Asynchronous Resources
+
+- Creating with `resourceAsync(fetchFn)`
+- Promise-based access
+- Async/await patterns
+- Promise resolution
+
+5. Practical Examples
+
+- API data fetching
+- File loading
+- Database queries
+- Configuration loading
+
+6. Error Handling
+
+- Try-catch patterns
+- Error states
+- Retry logic
+
+7. Best Practices
+
+- Resource cleanup
+- Caching strategies
+- Loading indicators
+- Error boundaries
+- Common pitfalls
+
+**Mermaid diagrams**:
+
+- Resource fetch lifecycle
+- Sync vs async resource comparison
+- Resource state transitions (idle -> fetching -> resolved/error)
+
+**Estimated length**: ~180-200 lines
+
+### 8. Write [streams.md](docs/guide/streams.md) - NEW FILE
+
+**Goal**: Complete guide to reactive streams
+
+**Sections**:
+
+1. Understanding Streams
+
+- What are streams
+- Push-based vs pull-based data
+- When to use streams vs resources
+- Event-driven updates
+
+2. How Streams Work
+
+- The updater function
+- The setter callback
+- The disposer pattern
+- Initial undefined state
+
+3. Creating Streams
+
+- Basic syntax with `stream((set) => disposer)`
+- Setting up subscriptions
+- Returning cleanup functions
+
+4. Stream Patterns
+
+- WebSocket connections
+- DOM event listeners
+- Timers and intervals
+- Server-sent events
+- Observable integration
+
+5. Asynchronous Streams
+
+- Creating with `streamAsync((set) => disposer)`
+- Promise-based values
+- Async/await in effects
+
+6. Practical Examples
+
+- WebSocket message stream
+- Mouse position tracker
+- Timer/countdown
+- Keyboard events
+- Real-time notifications
+
+7. Cleanup and Disposal
+
+- Disposer function importance
+- Avoiding memory leaks
+- Connection management
+
+8. Best Practices
+
+- Always return disposers
+- Handle errors in streams
+- Avoid duplicate subscriptions
+- Common pitfalls
+
+**Mermaid diagrams**:
+
+- Stream updater and disposer flow
+- Push-based data flow visualization
+- Stream lifecycle (setup -> updates -> disposal)
+- Sync vs async stream comparison
+
+**Estimated length**: ~200-220 lines
+
+### 9. Write [advanced.md](docs/guide/advanced.md)
+
+**Goal**: Guide to reactive collections (Map and Array)
+
+**Sections**:
+
+1. Introduction to Reactive Collections
+
+- Why collections need special handling
+- Fine-grained vs coarse-grained reactivity
+- Performance benefits
+
+2. Reactive Maps
+
+- Creating with `map()`
+- Whole map tracking with `.get(t)`
+- Fine-grained tracking with `$lastSet`
+- Fine-grained tracking with `$lastDeleted`
+- Methods: `setAt()`, `delete()`, `get()`, `pick()`
+
+3. Reactive Arrays
+
+- Creating with `array()`
+- Whole array tracking
+- Fine-grained tracking with `$lastAction`
+- Array methods: `push()`, `pop()`, `shift()`, `unshift()`, `splice()`, `clear()`
+
+4. Practical Examples
+
+- User list management
+- Shopping cart
+- Todo list with granular updates
+- Entity cache
+- UI animations based on operations
+
+5. Patterns and Tips
+
+- When to track whole vs operations
+- Performance considerations
+- Disposal of items
+- Common patterns
+
+**Mermaid diagrams**:
+
+- Map operation tracking flow
+- Array operation tracking flow
+- Fine-grained vs coarse-grained reactivity comparison
+
+**Estimated length**: ~180-200 lines
+
+### 10. Write [examples.md](docs/guide/examples.md)
+
+**Goal**: Real-world complete examples showing PicoFlow in action
+
+**Examples to include**:
+
+1. Todo List Application
+
+- State management
+- Derived values (completed count, filtered lists)
+- Effects for persistence
+
+2. Form with Validation
+
+- Form state
+- Derived validation
+- Computed error messages
+
+3. Real-time Data Dashboard
+
+- WebSocket stream
+- Derived statistics
+- Multiple effects for UI updates
+
+4. Shopping Cart
+
+- Reactive map for items
+- Derived totals
+- Fine-grained updates
+
+5. Auto-save Feature
+
+- Debounced effects
+- Resource fetching
+- Error handling
+
+Each example should:
+
+- Have complete, runnable code
+- Include explanatory comments
+- Show best practices
+- Demonstrate multiple features working together
+- Include a Mermaid diagram showing data flow
+
+**Mermaid diagrams**:
+
+- Data flow diagram for each major example
+
+**Estimated length**: ~280-320 lines
+
+### 11. Update VitePress config
+
+Update [docs/.vitepress/config.mts](docs/.vitepress/config.mts) sidebar to reflect new file structure:
+
+- Change "Effects & Derivations" to separate "Effects" and "Derivations" links
+- Change "Resources & Streams" to separate "Resources" and "Streams" links
+
+## Documentation Principles
+
+Throughout all files:
+
+1. **Beginner-Friendly Language**
+
+- Avoid jargon without explanation
+- Use analogies and metaphors
+- Define technical terms when first used
+
+2. **Visual Aids**
+
+- Use Mermaid diagrams for flows and concepts
+- Flowcharts for decision trees
+- Sequence diagrams for lifecycles
+- Graph diagrams for dependencies
+
+3. **Progressive Complexity**
+
+- Start simple, build up gradually
+- Each concept builds on previous ones
+- Clear section progression
+
+4. **Practical Examples**
+
+- Every concept has an example
+- Examples are realistic and relatable
+- Code includes helpful comments
+
+5. **Clear Structure**
+
+- Consistent heading hierarchy
+- Visual separation of sections
+- Frequent code examples
+
+6. **Cross-referencing**
+
+- Link to related concepts
+- Link to API reference
+- Link to other guide sections
+
+## Implementation Order
+
+1. [concepts.md](docs/guide/concepts.md) - Foundation with diagrams
+2. [state.md](docs/guide/state.md) - Most basic primitive
+3. [effects.md](docs/guide/effects.md) - Side effects explained
+4. [derivations.md](docs/guide/derivations.md) - Computed values
+5. [resources.md](docs/guide/resources.md) - Data fetching
+6. [streams.md](docs/guide/streams.md) - Event streams
+7. [advanced.md](docs/guide/advanced.md) - Collections
+8. [examples.md](docs/guide/examples.md) - Complete examples
+9. [getting-started.md](docs/guide/getting-started.md) - Final polish
+10. Update VitePress config for new file structure
+
+### To-dos
+
+- [ ] Install TypeDoc, plugins, and VitePress dependencies
+- [ ] Create typedoc.json configuration file
+- [ ] Create docs folder structure (.vitepress, guide, etc.)
+- [ ] Create VitePress config with nav and sidebar
+- [ ] Create docs/index.md homepage with hero and features
+- [ ] Create getting-started and concepts guide pages
+- [ ] Add docs:dev, docs:build, docs:preview scripts to package.json
+- [ ] Archive or remove old API Extractor generated files
+- [ ] Add VitePress generated folders to .gitignore
+- [ ] Test docs generation and verify markdown rendering
+- [ ] Test production build and preview
+- [ ] Update README with new documentation links and workflow

package/.gitlab-ci.yml

@@ -0,0 +1,24 @@
+image: node:20
+
+cache:
+  paths:
+    - node_modules/
+    - .pnpm-store/
+
+variables:
+  PNPM_VERSION: 8
+
+before_script:
+  - npm install -g pnpm@${PNPM_VERSION}
+  - pnpm install
+
+pages:
+  stage: deploy
+  script:
+    - pnpm docs:build
+    - cp -r docs/.vitepress/dist public
+  artifacts:
+    paths:
+      - public
+  rules:
+    - if: $CI_COMMIT_BRANCH == "main"

package/.vscode/settings.json

@@ -1,5 +1,5 @@
 {
-    "files.associations": {
-        "*.json": "jsonc"
-    }
+	"files.associations": {
+		"*.json": "jsonc"
+	}
 }

package/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0] - 2025-11-29
+
+### 🚨 BREAKING CHANGES
+
+This is a major rewrite of PicoFlow's API. The library now uses an explicit tracking context instead of getter/watcher functions. **This release is not backward compatible with v0.x.**
+
+**Migration required:** Please see [UPGRADING.md](UPGRADING.md) for detailed migration instructions. Most projects can be migrated in 15-30 minutes.
+
+### Changed
+
+- **Complete API overhaul:** Effects and derivations now receive a `TrackingContext` parameter (`t`) instead of separate `get` and `watch` functions
+- **New method-based API:** Observables use `.get(t)` for reactive reads instead of `get(observable)`
+- **Signals use `.watch(t)`:** Signal tracking now uses `$signal.watch(t)` instead of `watch($signal)`
+- **Chained syntax:** Enable natural chaining like `$parent.get(t).child.get(t)` instead of nested `get(get($parent).child)`
+- **Simpler architecture:** Removed internal methods (`_watch`, `_watchFrom`, `_getFrom`) in favor of direct method overrides
+
+### Added
+
+- **`TrackingContext` class:** New explicit tracking context for reactive computations
+- **`pick()` method:** Read observable values without creating dependencies - `$state.pick()` is equivalent to `$state.get(null)`
+- **Explicit control:** Granular control over what is tracked vs. untracked in the same reactive scope
+- **Mixed reactive/non-reactive reads:** Use `.get(t)` for reactive dependencies and `.pick()` for snapshot reads in the same effect
+
+### Removed
+
+- **`FlowGetter` type:** Replaced by `TrackingContext` parameter
+- **`FlowWatcher` type:** Replaced by `TrackingContext` parameter
+- **Implicit getter/watcher functions:** No longer passed to effects and derivations
+
+### Benefits
+
+- **More readable:** Code is more explicit about what creates dependencies
+- **Better chaining:** Natural fluent API for nested observables
+- **Simpler codebase:** Cleaner internal architecture with fewer abstractions
+- **More flexible:** Fine-grained control over reactive tracking per read operation
+
+---
+
+## [0.2.4] - Previous Release
+
+(Version 0.x releases used the getter/watcher API)
+