functype 0.8.67 → 0.8.69

package/readme/TASK-IMPLEMENTATION.md

@@ -0,0 +1,290 @@
+# Task Implementation Analysis and Best Practices
+
+This document provides a deep analysis of the Task implementation in functype, discussing its design considerations, trade-offs, and recommendations for effective usage.
+
+## Overview of Task Implementation
+
+The Task module provides a robust bridge between functional programming patterns and asynchronous operations. It offers a structured way to handle errors, cancellation, and progress tracking while maintaining type safety.
+
+Key features include:
+
+- Named task contexts for richer error information
+- Explicit try/catch/finally semantics
+- Interoperability with Promise-based code
+- Cancellation support
+- Progress tracking for long-running operations
+
+## Advanced Design Considerations
+
+### Error Context Propagation
+
+**Current Behavior:**
+When tasks are nested, the outer task's context (name, description) overwrites the inner task's context in error propagation:
+
+```typescript
+// If an error occurs in the inner task:
+await Task({ name: "OuterTask" }).Async(async () => {
+  return Task({ name: "InnerTask" }).Async(async () => {
+    throw new Error("Inner error")
+  })
+})
+
+// The error will have:
+// - message: "Inner error"
+// - name: "OuterTask" (not "InnerTask")
+// - taskInfo: { name: "OuterTask", ... }
+```
+
+This happens because when the inner task's promise rejects, it's caught by the outer task, which wraps it in its own error context. This is technically correct from a runtime perspective but might be counterintuitive when debugging.
+
+**Recommendation:**
+Consider implementing an option to preserve the innermost error context:
+
+```typescript
+// Possible enhancement
+const preserveErrorContext = true
+await Task({ name: "OuterTask", preserveErrorContext }).Async(...)
+
+// Which would yield an error with:
+// - Error context: "InnerTask" (preserved from inner task)
+// - Original context chain: ["OuterTask", "InnerTask"] (for tracing)
+```
+
+### Asynchronous Edge Cases
+
+Some asynchronous patterns can create complexity in error handling, particularly around cancellation and finally blocks:
+
+**Potential Issues:**
+
+1. Race conditions between cancellation signals and operation completion
+2. Callback execution order with finally blocks and cancellation
+3. Resource cleanup timing in complex async flows
+
+**Recommendations:**
+
+- Use explicit state machines for complex task flows
+- Implement deterministic callback ordering guarantees
+- Add explicit resource tracking for critical operations
+
+```typescript
+// Structured resource pattern example
+Task.withResource(
+  () => openResource(),
+  (resource) => useResource(resource),
+  (resource) => closeResource(resource),
+)
+```
+
+### Performance Considerations
+
+Task operations add some overhead compared to native Promises:
+
+1. **Extra Promise wrapping** - Each Task operation creates additional Promise layers
+2. **Error conversion** - Converting to Throwable objects has a small cost
+3. **Context maintenance** - Task metadata is carried throughout the operation
+4. **Cancellation checks** - Additional checks during execution
+
+**Recommendations:**
+
+- Use the Task API selectively for operations where the benefits outweigh costs
+- Consider a lightweight mode for performance-critical paths:
+
+```typescript
+// Hypothetical lightweight mode
+const lightTask = Task.light()
+lightTask.Async(...) // Minimal overhead, fewer features
+```
+
+- Group multiple small tasks into larger task units to amortize overhead
+
+## Cancellation Best Practices
+
+The cancellation system is cooperative rather than preemptive, meaning tasks must actively check for cancellation:
+
+### Effective Cancellation Patterns
+
+```typescript
+// 1. Regular checking pattern
+Task.cancellable(async (token) => {
+  for (const item of largeDataset) {
+    // Check cancellation periodically
+    if (token.isCancelled) {
+      return // Exit early
+    }
+
+    // Process item
+    await processItem(item)
+  }
+})
+
+// 2. Integration with fetch and DOM APIs
+Task.cancellable(async (token) => {
+  const response = await fetch(url, {
+    signal: token.signal, // AbortSignal integration
+  })
+  return await response.json()
+})
+
+// 3. Custom cancellation behavior
+Task.cancellable(async (token) => {
+  let resources = []
+
+  token.onCancel(() => {
+    // Clean up resources when cancelled
+    resources.forEach((r) => r.dispose())
+  })
+
+  // Main task work...
+})
+```
+
+### Cancellation Caveats
+
+1. **Cancellation is not guaranteed to be immediate** - Tasks may continue briefly after cancellation
+2. **External resources may need explicit cleanup** - Database connections, file handles, etc.
+3. **Third-party APIs may not support cancellation** - Wrapping them requires careful handling
+
+## Progress Tracking
+
+For long-running operations, progress tracking provides visibility:
+
+```typescript
+// Basic progress usage
+const { task, currentProgress } = Task.withProgress(
+  async (updateProgress) => {
+    updateProgress(0) // Start
+
+    // Do work in chunks
+    for (let i = 0; i < 10; i++) {
+      await doChunk(i)
+      updateProgress((i + 1) * 10) // 10%, 20%, etc.
+    }
+
+    return result
+  },
+  (percent) => {
+    // Update UI with progress
+    updateProgressBar(percent)
+  },
+)
+
+// Combined with cancellation
+const { task, cancel, currentProgress } = Task.withProgress(async (updateProgress, token) => {
+  // Both progress tracking and cancellation
+})
+```
+
+### Progress Implementation Considerations
+
+1. **Progress granularity** - Too frequent updates can impact performance
+2. **Cancellation interaction** - Progress should stop updating when cancelled
+3. **Indeterminate phases** - Some operations can't report precise progress
+
+## Advanced Task Composition
+
+### Task Racing
+
+The `Task.race` functionality allows racing multiple tasks against each other with optional timeout:
+
+```typescript
+// Race with timeout
+const raceResult = await Task.race([slowOperation(), fastOperation()], 1000) // 1 second timeout
+```
+
+### Potential Future Composition Enhancements
+
+1. **Structured Concurrency**
+
+```typescript
+// Hypothetical API
+const { results, errors } = await Task.scope(async (scope) => {
+  // All tasks in scope have linked lifecycle
+  const task1 = scope.spawn(operation1())
+  const task2 = scope.spawn(operation2())
+
+  return await scope.join() // Wait for all to complete or fail
+})
+```
+
+2. **Resource Management**
+
+```typescript
+// Hypothetical API for guaranteed resource cleanup
+await Task.using(
+  () => openDatabase(), // Acquire
+  async (db) => {
+    // Use resource
+    return await db.query()
+  },
+  (db) => db.close(), // Always called
+)
+```
+
+## Testing Considerations
+
+Testing Task-based code requires special attention:
+
+1. **Time and async flow control** - Use timeouts and explicit resolutions
+2. **Cancellation testing** - Test both normal and cancelled paths
+3. **Progress testing** - Verify progress reporting accuracy
+4. **Error context verification** - Check error details are preserved
+
+Example property tests:
+
+```typescript
+// Task Async should satisfy monad laws
+test("Right identity: t.Async(f) >>= id = t.Async(f)", () => {
+  fc.assert(
+    fc.property(fc.string(), async (value) => {
+      const f = async () => value
+      const taskResult = await Task().Async(f)
+      const directResult = await f()
+      return taskResult === directResult
+    }),
+  )
+})
+```
+
+## Integration with Other Patterns
+
+Tasks work especially well when combined with other functional patterns:
+
+### With Option
+
+```typescript
+// Convert nullable API response to Option
+const getUserOption = async (id: string) => {
+  const response = await Task().Async(async () => {
+    return fetch(`/api/users/${id}`)
+  })
+
+  return Option.fromNullable(response)
+}
+```
+
+### With Either
+
+```typescript
+// Type-specific error handling
+const result = await Task().Async(async () => {
+  // Operation returning Either<ApiError, UserData>
+})
+
+// Handle specific error types
+result.match({
+  left: (error) => handleApiError(error),
+  right: (data) => useData(data),
+})
+```
+
+## Conclusion
+
+The Task implementation offers a powerful approach to functional asynchronous programming. By understanding its design trade-offs and following best practices, developers can create more robust, maintainable code with better error handling.
+
+Remember that Task is not a replacement for all Promise usage - evaluate when the additional features justify the slightly increased complexity and overhead.
+
+## See Also
+
+- [Task Error Handling](../docs/task-error-handling.md)
+- [Task Migration Guide](../docs/TaskMigration.md)
+- [Task TODO](../docs/TASK-TODO.md)

package/readme/TASK-TODO.md

@@ -0,0 +1,40 @@
+# Task TODO
+
+## Goals
+
+- Enhance the Task module as an adapter between promise-based code and functional patterns
+- Improve interoperability with existing JavaScript/TypeScript codebases
+- Allow gradual migration to functional patterns without complete rewrites
+
+## Implementation Tasks
+
+- [x] Review current Task implementation for completeness of promise integration
+- [x] Ensure robust error handling in sync/async conversions
+- [x] Document explicit try/catch/finally semantics
+- [x] Add examples showing migration from promise-based to functional patterns
+- [x] Add utilities to simplify Task composition with promise-returning functions
+- [x] Create migration guide for converting promise chains to Task operations
+- [x] Create Task.race for racing multiple tasks with timeout support
+- [x] Implement Task.fromNodeCallback for Node.js style callbacks
+- [x] Implement cancellation support for Task operations
+- [x] Add progress tracking for long-running Task operations
+
+## Design Considerations
+
+- Maintain clear separation between synchronous and promise-based operations
+- Preserve functional error handling patterns while supporting promise interop
+- Keep API consistent with the rest of the library's functional approach
+
+## Completed Enhancements
+
+- Added `fromPromise` adapter to convert promise-returning functions to Task-compatible functions
+- Added `toPromise` converter to transform Task results back to promises
+- Enhanced documentation with clearer descriptions of functionality
+- Created TaskMigration.md guide showing how to migrate from promises to functional Task patterns
+- Added comprehensive tests for the new adapter methods
+- Implemented `Task.race` for racing multiple tasks with timeout support
+- Added `Task.fromNodeCallback` for Node.js-style callback integration
+- Implemented cancellation support with CancellationToken pattern
+- Added progress tracking for long-running operations
+- Created property-based tests verifying monadic laws and edge cases
+- Added comprehensive documentation for all new functionality

package/readme/TASK-UPDATES.md

@@ -0,0 +1,64 @@
+# Task Module Updates Summary
+
+## Overview of Enhancements
+
+We've made the following significant enhancements to the Task module:
+
+1. **Implemented Task.race** - For racing multiple tasks with timeout support
+2. **Added Task.fromNodeCallback** - For Node.js-style callback integration
+3. **Implemented Cancellation Support** - For stopping long-running operations
+4. **Added Progress Tracking** - For monitoring operation completion status
+5. **Comprehensive Tests** - Including property-based tests and edge case handling
+
+## Documentation Updates
+
+The following new documentation has been created:
+
+1. **[TASK-IMPLEMENTATION.md](../docs/TASK-IMPLEMENTATION.md)** - Deep analysis of Task design considerations and trade-offs
+2. **[task-cancellation-progress.md](task-cancellation-progress.md)** - Guide to using cancellation and progress features
+3. **[task-quick-reference.md](task-quick-reference.md)** - Compact reference for all Task functionality
+
+## Current Status
+
+The Task implementation now:
+
+- Provides a robust bridge between functional patterns and async operations
+- Seamlessly integrates with existing Promise-based and Node.js callback APIs
+- Supports cancellation with proper resource cleanup
+- Tracks progress for long-running operations
+- Maintains rich error context throughout the operation lifecycle
+- Follows functional programming principles
+
+## Recommendations for Integration
+
+### Documentation Recommendations
+
+1. **Update quick-reference.md**: Add Task section based on task-quick-reference.md
+2. **Update TASK-TODO.md**: Mark newly implemented items as completed
+3. **Update tasks.md**: Mark cancellation and Node.js callback items as completed
+
+### Implementation Recommendations
+
+1. **Error Context Preservation**: Consider an option to preserve innermost task context
+2. **Timeout Support**: Add global timeout support for any task operation
+3. **Structured Resource Management**: Implement a `Task.using` pattern for guaranteed cleanup
+4. **Lightweight Mode**: Consider a performance-optimized Task variant for hot paths
+
+## Next Steps
+
+Based on the existing roadmap and our implementation, these items could be prioritized:
+
+1. **Error Aggregation for Parallel Operations**: For collecting multiple errors when running tasks in parallel
+2. **Task Scope API**: For structured concurrency patterns with linked task lifecycles
+3. **Framework Integration**: Create React/Vue hooks for Task management
+4. **Performance Monitoring**: Add performance tracking capabilities to tasks
+
+## Testing Observations
+
+During the implementation and testing process, we discovered:
+
+1. **Task Nesting Behavior**: Outer task context overwrites inner task context in errors
+2. **Cancellation Edge Cases**: Some race conditions exist in rapidly cancelled tasks
+3. **Testing Challenges**: Timing-dependent tests require careful structuring
+
+Overall, the Task implementation is now significantly more robust and feature-complete, providing a strong foundation for asynchronous functional programming in TypeScript.

package/readme/TUPLE-EXAMPLES.md

@@ -0,0 +1,79 @@
+# Tuple Enhanced with Modern TypeScript Features
+
+## What's Improved
+
+Our enhanced `Tuple` implementation leverages modern TypeScript features:
+
+1. **Const type parameters** (TypeScript 5.0+)
+2. **Variadic tuple types** (TypeScript 4.0+)
+3. **Stronger type inference** for tuple elements
+
+## Examples
+
+### Basic Usage
+
+```typescript
+import { Tuple } from "@/tuple"
+
+// Create a tuple with mixed types
+const personTuple = Tuple(["John Doe", 42, true])
+
+// Access values with type safety
+const name = personTuple.get(0) // Type is string
+const age = personTuple.get(1) // Type is number
+const active = personTuple.get(2) // Type is boolean
+
+// Transform the tuple
+const mapped = personTuple.map((values) => values.map((x) => (typeof x === "number" ? x * 2 : x)))
+```
+
+### Preserving Literal Types
+
+```typescript
+// Using 'as const' with the enhanced implementation
+const literalTuple = Tuple([1, "hello", true] as const)
+
+// TypeScript now knows the exact types:
+const first = literalTuple.get(0) // Type is exactly 1 (not just number)
+const second = literalTuple.get(1) // Type is exactly 'hello' (not just string)
+const third = literalTuple.get(2) // Type is exactly true (not just boolean)
+
+// Benefits:
+// - Better type checking
+// - Autocomplete shows exact values
+// - Prevents invalid index access
+```
+
+### Type-Level Utilities (for future improvements)
+
+```typescript
+// Example of potential future type utilities
+type FirstElement<T extends Tuple<unknown[]>> = T extends Tuple<[infer F, ...unknown[]]> ? F : never
+
+// Extract first element's type
+type First = FirstElement<typeof literalTuple> // Would be 1
+
+// Could expand to other utilities like:
+// - LastElement
+// - RemoveFirst
+// - Prepend<T, Item>
+// - etc.
+```
+
+## When Is This Useful?
+
+1. **Strong typing for heterogeneous collections**:
+
+   - When you need to store different types in a fixed structure
+   - When you want type safety beyond what arrays provide
+
+2. **APIs returning fixed-length, mixed-type results**:
+
+   - When a function returns multiple values of different types
+
+3. **Data transformation pipelines**:
+
+   - When you need to transform data while preserving type information
+
+4. **Configuration objects with fixed format**:
+   - When config must follow a specific format with specific types at each position

package/readme/TaskMigration.md

@@ -0,0 +1,129 @@
+# Task Migration Guide
+
+This guide demonstrates how to migrate traditional Promise-based code to the functional `Task` pattern in the functype library.
+
+## The Problem with Traditional Promises
+
+Traditional JavaScript/TypeScript Promise-based code often suffers from:
+
+1. Implicit error handling (errors silently propagate)
+2. Hard-to-trace error stacks
+3. Mixed error types without type safety
+4. Verbose try/catch blocks
+5. Side effects spread throughout the codebase
+
+## Migration Path: Traditional Promises → Task
+
+### Step 1: Identify Promise-Based Code
+
+```typescript
+// Traditional promise-based API call
+function fetchUserData(userId: string): Promise<UserData> {
+  return fetch(`/api/users/${userId}`).then((response) => {
+    if (!response.ok) {
+      throw new Error(`Failed to fetch user: ${response.statusText}`)
+    }
+    return response.json()
+  })
+}
+
+// Usage with promise chains
+function displayUserProfile(userId: string): Promise<void> {
+  return fetchUserData(userId)
+    .then((userData) => {
+      renderProfile(userData)
+    })
+    .catch((error) => {
+      showErrorMessage(error)
+    })
+}
+```
+
+### Step 2: Convert to Task with fromPromise adapter
+
+```typescript
+import { Task } from "@/core/task/Task"
+
+// Step 1: Create a Task wrapper
+const userTask = Task<UserData>({ name: "UserOperations" })
+
+// Step 2: Convert promise function to Task function
+const fetchUserData = (userId: string): FPromise<UserData> => {
+  return userTask.fromPromise((id: string) =>
+    fetch(`/api/users/${id}`).then((response) => {
+      if (!response.ok) {
+        throw new Error(`Failed to fetch user: ${response.statusText}`)
+      }
+      return response.json()
+    }),
+  )(userId)
+}
+
+// Step 3: Use in Task-based workflow
+const displayUserProfile = (userId: string): FPromise<void> => {
+  return fetchUserData(userId)
+    .then((userData) => {
+      renderProfile(userData)
+      return undefined
+    })
+    .catch((error) => {
+      showErrorMessage(error)
+      return undefined
+    })
+}
+```
+
+### Step 3: Fully Embrace the Functional Pattern
+
+```typescript
+import { Task, TaskResult, TaskException } from "@/core/task/Task"
+import { Either } from "@/either/Either"
+import { Throwable } from "@/core/throwable/Throwable"
+
+// Create a domain-specific Task
+const userTask = Task<UserData>({ name: "UserOperations" })
+
+// Fully functional API
+const fetchUserData = (userId: string): FPromise<Either<Throwable, UserData>> => {
+  return FPromise<Either<Throwable, UserData>>(async (resolve) => {
+    try {
+      const response = await fetch(`/api/users/${userId}`)
+      if (!response.ok) {
+        resolve(userTask.fail(new Error(`Failed to fetch user: ${response.statusText}`)))
+        return
+      }
+      const data = await response.json()
+      resolve(userTask.success(data))
+    } catch (error) {
+      resolve(userTask.fail(error))
+    }
+  })
+}
+
+// Functional composition with proper error handling
+const displayUserProfile = (userId: string): FPromise<void> => {
+  return fetchUserData(userId).then((result) => {
+    if (result.isRight()) {
+      renderProfile(result.get())
+    } else {
+      showErrorMessage(result.get())
+    }
+  })
+}
+```
+
+## Benefits of Task-Based Approach
+
+1. **Explicit Error Handling**: Errors are represented as values in the Either type
+2. **Type Safety**: Error and success paths are fully typed
+3. **Composition**: Tasks can be composed with other functional patterns
+4. **Interoperability**: Can work with existing Promise-based code
+5. **Testability**: Pure functions are easier to test
+
+## Best Practices
+
+1. Use descriptive names for Tasks that reflect their domain purpose
+2. Leverage the `fromPromise` adapter for gradual migration
+3. Combine with Either for full type safety in error handling
+4. Use `toPromise` when integrating back with traditional Promise-based APIs
+5. Keep Task operations pure when possible