@ersbeth/picoflow 1.1.1 → 2.0.0

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

@@ -1,567 +0,0 @@
-<!-- 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/dist/types/flow/base/flowDisposable.d.ts

@@ -1,67 +0,0 @@
-/**
- * Contract for objects that own resources and must be cleaned up explicitly.
- *
- * @remarks
- * Many PicoFlow primitives expose `dispose()` so you can tear down subscriptions,
- * listeners, or reactive links when they are no longer needed (e.g., component
- * unmount, feature teardown, test cleanup).
- *
- * Typical options:
- * - `{ self: true }` — dispose only this instance (dependents decide their own lifecycle).
- * - `{ self: false }` or omitted — also dispose dependents, if the implementation supports it.
- *
- * The exact cascade behavior depends on the concrete primitive; consult its docs.
- *
- * @example
- * ```typescript
- * const $state = state(0);
- * const fx = effect((t) => console.log($state.get(t)));
- *
- * $state.dispose();          // Common teardown path
- * $state.dispose({ self: true }); // Dispose only this instance if you want dependents to persist
- * ```
- *
- * @public
- */
-export interface FlowDisposable {
-    /**
-     * Disposes resources held by this object.
-     *
-     * @param options - Optional disposal behavior.
-     * @param options.self - When true, dispose only this object. When false or
-     * omitted, the implementation may also dispose dependents.
-     *
-     * @remarks
-     * Use `dispose()` during teardown (unmount, test cleanup, feature shutdown).
-     * Calling `dispose()` more than once may throw; behavior is defined by the
-     * concrete implementation.
-     *
-     * @throws Error if the object has already been disposed (implementation-specific).
-     */
-    dispose(options?: {
-        self: boolean;
-    }): void;
-}
-/**
- * Runtime type guard that checks whether an object is disposable.
- *
- * @param obj - Value to test.
- * @returns `true` if `obj` exposes a callable `dispose`; otherwise `false`.
- *
- * @remarks
- * Use this for defensive cleanup in mixed collections or optional resources.
- * It performs a runtime shape check; no assumptions about specific types are made.
- *
- * @example
- * ```typescript
- * function cleanup(items: unknown[]) {
- *   for (const item of items) {
- *     if (isDisposable(item)) item.dispose();
- *   }
- * }
- * ```
- *
- * @public
- */
-export declare function isDisposable(obj: unknown): obj is FlowDisposable;
-//# sourceMappingURL=flowDisposable.d.ts.map

package/dist/types/flow/base/flowDisposable.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"flowDisposable.d.ts","sourceRoot":"","sources":["../../../../src/flow/base/flowDisposable.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,WAAW,cAAc;IAC9B;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,OAAO,CAAC,EAAE;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;CAC3C;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,cAAc,CAMhE"}