functype 0.9.0 → 0.9.1

package/readme/task-error-handling.md

@@ -0,0 +1,283 @@
+# Task Error Handling
+
+The `Task` module in Functype provides robust error handling capabilities, including the ability to include task identifiers in error objects. This guide explains how to take advantage of these features.
+
+## Named Task Errors
+
+When creating a `Task`, you can provide an optional name and description:
+
+```typescript
+const namedTask = Task({
+  name: "UserRegistration",
+  description: "Handles user registration process",
+})
+```
+
+When an error occurs within this task, the task name will be referenced in the error:
+
+1. The `Throwable` object created from the error will include:
+   - The task name as the error's `name` property
+   - A `taskInfo` property containing both the name and description
+
+2. The `TaskException` object will include:
+   - The `_task` property with the name and description
+   - The original error wrapped with the task name and info
+
+## Examples
+
+### Sync Task Error
+
+```typescript
+const namedTask = Task({ name: "UserRegistration" })
+
+const result = namedTask.Sync(() => {
+  throw new Error("Invalid user data")
+})
+
+// The error (within the Left) will have:
+// - name: "UserRegistration"
+// - message: "Invalid user data"
+// - taskInfo: { name: "UserRegistration", description: "..." }
+
+console.log(result.value.name) // "UserRegistration"
+console.log(result._task.name) // "UserRegistration"
+```
+
+### Async Task Error
+
+```typescript
+try {
+  await Task({ name: "DataProcessing" }).Async(async () => {
+    throw new Error("Processing failed")
+  })
+} catch (error) {
+  // The error will have:
+  // - name: "DataProcessing"
+  // - message: "Processing failed"
+  // - taskInfo: { name: "DataProcessing", description: "..." }
+
+  console.log(error.name) // "DataProcessing"
+  console.log(error.taskInfo) // { name: "DataProcessing", description: "..." }
+}
+```
+
+### Using Task.fail Companion Function
+
+```typescript
+const error = new Error("Authentication failed")
+const result = Task.fail(error, { userId: 123 }, { name: "AuthService" })
+
+// The TaskException contains:
+console.log(result.value.name) // "AuthService"
+console.log(result.value.message) // "Authentication failed"
+console.log(result.value.data) // { userId: 123 }
+console.log(result.value.taskInfo) // { name: "AuthService", description: "..." }
+```
+
+## Benefits
+
+Including task names in errors provides several advantages:
+
+1. **Better Error Identification**: Easily identify which task produced an error
+2. **Improved Debugging**: Quickly locate the source of exceptions
+3. **Enhanced Logging**: Structured error information for logs and monitoring
+4. **Error Context**: Maintain context about what operation was being performed
+5. **Consistent Error Format**: All errors follow the same structure
+
+## Error Propagation
+
+Task names and information propagate through the error handling chain:
+
+```typescript
+const result = Task({ name: "UserService" }).Sync(
+  () => {
+    throw new Error("User not found")
+  },
+  (error) => `Could not process request: ${error.message}`,
+)
+
+// The resulting error maintains the task name even through the error handler
+console.log(result.value.name) // "UserService"
+console.log(result.value.message) // "Could not process request: User not found"
+```
+
+## With finally Blocks
+
+Task names are preserved even when errors occur in finally blocks:
+
+```typescript
+try {
+  await Task({ name: "CleanupTask" }).Async(
+    async () => "success",
+    async (error) => error,
+    () => {
+      throw new Error("Cleanup failed")
+    },
+  )
+} catch (error) {
+  // The error from the finally block still includes the task name
+  console.log(error.name) // "CleanupTask"
+  console.log(error.message) // "Cleanup failed"
+}
+```
+
+## Context Loss in Nested Tasks
+
+When working with multiple nested `Task` executions, there's a significant issue with error context preservation. Inner task errors lose their context when they propagate through outer tasks. This limits error traceability and makes debugging complex task chains difficult.
+
+### Current Behavior
+
+Consider this example:
+
+```typescript
+// Inner task with specific context
+const innerTask = Task({ name: "InnerTask" }).Async(async () => {
+  throw new Error("Inner failure")
+})
+
+// Outer task that calls the inner task
+const outerTask = Task({ name: "OuterTask" }).Async(async () => await innerTask)
+
+try {
+  await outerTask
+} catch (error) {
+  // error.taskInfo.name will be "OuterTask", not "InnerTask"
+  // The original error context is lost
+}
+```
+
+In this scenario, the error context from the `InnerTask` is lost when it propagates through the `OuterTask`. This makes it difficult to:
+
+1. Identify the actual source of errors
+2. Implement proper error handling strategies
+3. Debug complex nested task chains
+
+### Current Workaround
+
+Until a native solution is implemented, you can manually preserve the error context:
+
+```typescript
+// Outer task with manual error handling
+const outerTask = Task({ name: "OuterTask" }).Async(async () => {
+  try {
+    return await innerTask
+  } catch (innerError) {
+    // Manually reference the inner error
+    throw new Error(`OuterTask failed: ${(innerError as Error).message}`)
+  }
+})
+```
+
+## Implemented Solution: Error Chaining
+
+The `Task` implementation now supports error chaining, preserving the complete error context chain as errors propagate through nested tasks.
+
+### How Error Chaining Works
+
+The `Task` implementation now detects when an error comes from another task and preserves the error chain by:
+
+1. Creating a new error with the outer task's context
+2. Setting the inner task's error as the `cause` property
+3. Preserving the complete error chain for debugging and error handling
+
+```typescript
+// Inner task with specific context
+const innerTask = Task({ name: "InnerTask" }).Async(async () => {
+  throw new Error("Inner failure")
+})
+
+// Outer task that calls the inner task
+const outerTask = Task({ name: "OuterTask" }).Async(async () => await innerTask)
+
+try {
+  await outerTask
+} catch (error) {
+  // error.taskInfo.name will be "OuterTask"
+  // But error.cause.taskInfo.name will be "InnerTask"
+
+  // You can access the full error chain
+  const errorChain = Task.getErrorChain(error)
+
+  // Format the error chain for logging/debugging
+  const formattedError = Task.formatErrorChain(error, { includeTasks: true })
+  console.log(formattedError)
+  // Output:
+  // [OuterTask] OuterTask: Inner failure
+  // ↳ [InnerTask] Inner failure
+}
+```
+
+### Task.getErrorChain
+
+A new utility method allows you to extract the complete error chain from a Throwable error:
+
+```typescript
+// Get array of errors from outer to inner
+const errorChain = Task.getErrorChain(error)
+
+// Access specific task information
+console.log(errorChain[0].taskInfo.name) // "OuterTask"
+console.log(errorChain[1].taskInfo.name) // "InnerTask"
+```
+
+### Task.formatErrorChain
+
+Another utility method formats the error chain as a readable string for logging or debugging:
+
+```typescript
+// Format with task names included
+const formatted = Task.formatErrorChain(error, {
+  includeTasks: true, // Include task names in formatted output
+  separator: "\n", // Separator between error levels (default: "\n")
+  includeStackTrace: false, // Whether to include stack traces (default: false)
+})
+
+console.log(formatted)
+// Output:
+// [OuterTask] OuterTask: Inner failure
+// ↳ [InnerTask] Inner failure
+```
+
+### Benefits
+
+This implementation provides several advantages:
+
+1. **Full Context Preservation**: Every level of the error chain maintains its task context
+2. **Improved Debugging**: Error messages include the full path of the error
+3. **Better Error Handling**: Error handlers can make decisions based on the complete error chain
+4. **Minimal Performance Impact**: The solution adds negligible overhead
+5. **Backwards Compatibility**: Existing code will continue to work as before
+
+An error chain is formatted like this by default:
+
+```
+[OuterTask] Failed to process data
+↳ [MiddleTask] Database query failed
+↳ [InnerTask] Connection timeout
+```
+
+## Error Handler Behavior
+
+When using `Task.Async`, error handlers are always called, regardless of the error type:
+
+```typescript
+const task = Task({ name: "DataProcessor" }).Async(
+  async () => {
+    throw new Error("Processing failed")
+  },
+  (error) => {
+    // This handler is always called, even for TaggedThrowable errors
+    console.error(`Error processing data: ${error}`)
+    return "Failed to process data"
+  },
+)
+```
+
+For regular errors, the handler's return value is used as the rejection value. For errors that are already TaggedThrowable (from inner tasks), the handler is still called for side effects (like logging) in a non-blocking way, allowing these operations to happen without impacting performance. This ensures the original error chain is preserved while still enabling important operations like logging.
+
+This ensures that error handlers can perform important operations like logging while preserving the error context needed for debugging nested task operations.
+
+## See Also
+
+- [Task Module Examples](./examples/task-named-errors.ts)
+- [Task API Documentation](./quick-reference.md#task)

package/readme/tasks.md

@@ -0,0 +1,203 @@
+# Functype Improvement Ideas
+
+This document contains a comprehensive list of potential improvement ideas for the Functype library. These ideas represent possible directions for the library but should be evaluated against the core principles of maintaining a lightweight, focused approach as outlined in the README.md and implemented according to the official ROADMAP.md timeline.
+
+> **Note**: Not all ideas listed here will necessarily be implemented. Each should be evaluated based on:
+>
+> - Alignment with the "lightweight" philosophy of the library
+> - Prioritization in the official ROADMAP.md
+> - Value to users vs. complexity added
+> - Maintenance burden
+
+## Core Functionality Enhancements
+
+### Data Structures and Types
+
+[ ] Implement LazyList/Stream for efficient processing of potentially infinite sequences
+[ ] Create Validation data type for applicative validation with error accumulation
+[ ] Implement Reader monad for dependency injection patterns
+[ ] Add State monad for functional state management
+[ ] Create IO monad for pure handling of side effects
+[ ] Implement lens/optics abstractions for immutable updates
+[x] Add Traversable implementation for all collection types
+[ ] Implement Semigroup and Monoid type classes
+[ ] Create NonEmptyList type with stronger guarantees than regular List
+[x] Implement pipe operation for transforming data structures
+
+### Error Handling
+
+[x] Create standardized error hierarchy for all modules
+[x] Implement consistent error context propagation across monadic chains
+[x] Add error recovery utilities for all error-producing types
+[x] Create error serialization/deserialization utilities for API boundaries
+[ ] Implement error aggregation for parallel operations
+
+## TypeScript and Type Safety Improvements
+
+### Type System Enhancements
+
+[ ] Remove any usage from higher-kinded type implementations
+[x] Expand branded/nominal type system for stronger type safety
+[ ] Add more type-level utilities using conditional types and template literals
+[ ] Leverage const type parameters for improved type inference
+[x] Implement tuple manipulation utilities with type safety
+[ ] Create type-safe path accessors for nested object structures
+[ ] Add runtime type validation utilities that preserve type information
+
+### API Consistency
+
+[x] Standardize method naming conventions across all modules
+[x] Ensure consistent parameter ordering in similar functions
+[x] Normalize return types for equivalent operations
+[x] Implement consistent pattern for async variants of synchronous methods
+[x] Standardize import patterns using @imports throughout the codebase
+[x] Create consistent error handling strategy for all modules
+
+## Performance Optimizations
+
+### Data Structure Efficiency
+
+[x] Implement structural sharing for immutable collections
+[ ] Add memoization utilities for expensive function calls
+[x] Optimize recursive operations for large data structures
+[x] Implement lazy evaluation for chain operations where possible
+[x] Create specialized implementations for common use cases
+
+### Bundle Size and Loading
+
+[x] Analyze and reduce bundle size for core modules
+[x] Implement code splitting strategies for large modules
+[x] Create lightweight alternatives for performance-critical paths
+[x] Add bundle size monitoring to CI/CD pipeline
+[x] Optimize tree-shaking with more granular exports
+
+## Testing and Quality Assurance
+
+### Test Coverage
+
+[x] Add test coverage metrics and set coverage goals
+[x] Implement property-based tests for all data structures
+[x] Create exhaustive edge case tests for error handling
+[x] Add performance regression tests
+[ ] Implement integration tests with popular frameworks and libraries
+
+### Code Quality
+
+[x] Add static analysis tools to CI pipeline
+[x] Implement automated code quality checks
+[x] Create style guide enforcement tools
+[ ] Add complexity metrics monitoring
+[ ] Implement automated dependency updates with testing
+
+## Documentation and Examples
+
+### API Documentation
+
+[x] Create comprehensive API documentation for all modules
+[x] Add usage examples for all public methods
+[x] Document performance characteristics and trade-offs
+[ ] Create interactive documentation with runnable examples
+[ ] Add diagrams for complex concepts and data flows
+
+### Guides and Tutorials
+
+[ ] Create step-by-step migration guides from imperative to functional
+[x] Add real-world examples showcasing practical applications
+[x] Create beginner-friendly tutorials for functional programming concepts
+[x] Implement cookbook-style documentation for common patterns
+[ ] Add troubleshooting guides for common issues
+
+## Developer Experience
+
+### Tooling and Infrastructure
+
+[x] Create development environment setup scripts
+[x] Implement automated release process
+[x] Add changelog generation from commit messages
+[ ] Create interactive playground for experimenting with the library
+[x] Implement benchmarking suite for performance testing
+
+### Community and Contribution
+
+[x] Create detailed contribution guidelines
+[x] Implement issue and PR templates
+[ ] Add automated issue labeling and triage
+[ ] Create community forum or discussion platform
+[ ] Implement automated code review tools
+
+## Compatibility and Integration
+
+### Framework Integration
+
+[ ] Create React hooks and utilities for Functype integration
+[ ] Add Vue composition functions for Functype
+[ ] Implement Angular services and utilities
+[ ] Create Express/Koa middleware using functional patterns
+[ ] Add Next.js integration utilities
+
+### Ecosystem Compatibility
+
+[x] Ensure compatibility with Node.js LTS versions
+[x] Maintain browser compatibility across major browsers
+[ ] Add support for Deno runtime
+[x] Test with various bundlers (webpack, esbuild, Rollup, etc.)
+[ ] Create interoperability utilities for other functional libraries
+
+## Specific Module Improvements
+
+### Option Module
+
+[x] Add Option.sequence for working with arrays of Options
+[x] Implement Option.traverse for mapping and sequencing in one operation
+[x] Add Option.fromPredicate for creating Options from boolean conditions
+[x] Create Option utilities for working with nullable API responses
+[x] Add Option.fromJSON for safely parsing JSON
+[x] Implement pipe for transforming Option values
+
+### Either Module
+
+[x] Implement Either.sequence for working with arrays of Eithers
+[x] Add Either.traverse for mapping and sequencing in one operation
+[x] Create bimap method for mapping both sides of Either
+[x] Add Either.fromPredicate with custom error creation
+[x] Implement Either utilities for async/await integration
+[x] Add pipeEither for type-safe transformations across variants
+[x] Implement standard pipe for consistent API with other modules
+
+### Task Module
+
+[x] Add Task.sequence for parallel execution with error handling
+[x] Implement Task.traverse for mapping and sequencing in one operation
+[ ] Create Task.race for racing multiple tasks with timeout support
+[x] Add Task retry utilities with exponential backoff
+[ ] Implement Task.fromNodeCallback for Node.js style callbacks
+
+### FPromise Module
+
+[x] Add timeout support for all FPromise operations
+[ ] Implement cancellation support for FPromise chains
+[x] Create FPromise.allSettled equivalent with typed results
+[x] Add FPromise.any with proper typing
+[ ] Implement progress tracking for long-running operations
+
+### Collection Modules
+
+[x] Implement pipe for List data structure
+[x] Implement pipe for Set data structure
+[x] Implement pipe for Map data structure
+[ ] Add comprehensive conversion utilities between collection types
+[ ] Implement more specialized collection operations
+
+## Cross-Data Structure Features
+
+[x] Implement pipe interface for consistent transformation pattern
+[x] Create tests demonstrating cross-structure transformations
+[x] Add type-safety for transformations across data structures
+[x] Document common patterns for functional composition with pipe
+[ ] Create additional utility functions for common transformations
+
+## Relationship to Official Roadmap
+
+This document serves as a collection of ideas and potential enhancements for Functype. For the official development plan with prioritized tasks and timeline, please refer to the [ROADMAP.md](ROADMAP.md) file in the project root.
+
+The official roadmap represents the committed development path, while this document captures a broader set of possibilities that may be considered for future development cycles based on community feedback and evolving requirements.