functype 0.8.83 → 0.8.84

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "functype",
-  "version": "0.8.83",
+  "version": "0.8.84",
   "type": "module",
   "description": "A smallish functional library for TypeScript",
   "author": "jordan.burke@gmail.com",

package/readme/BUNDLE_OPTIMIZATION.md

@@ -1,74 +0,0 @@
-# Bundle Size Optimization Guide
-
-## Overview
-
-Functype is designed with tree-shaking in mind, allowing you to optimize your application's bundle size by only including the specific modules you need.
-
-## Import Strategies
-
-### Strategy 1: Selective Module Imports (Recommended)
-
-Import only the specific modules you need to reduce bundle size significantly.
-
-```typescript
-import { Option } from "functype/option"
-import { Either } from "functype/either"
-
-// Usage
-const option = Option.some(42)
-const either = Either.right("value")
-```
-
-### Strategy 2: Direct Constructor Imports (Smallest Bundle)
-
-For the most aggressive tree-shaking, import only the specific constructors and functions you need.
-
-```typescript
-import { some, none } from "functype/option"
-import { right } from "functype/either"
-
-// Usage
-const option = some(42)
-const none_value = none()
-const either = right("value")
-```
-
-## Bundle Size Comparison
-
-| Import Strategy | Approximate Bundle Size  | Best For                   |
-| --------------- | ------------------------ | -------------------------- |
-| Selective       | 200-500 bytes per module | Most applications          |
-| Direct          | <200 bytes per feature   | Size-critical applications |
-
-## Common Module Sizes
-
-| Module   | Approximate Size (minified) | Gzipped Size |
-| -------- | --------------------------- | ------------ |
-| Option   | ~200 bytes                  | ~140 bytes   |
-| Either   | ~290 bytes                  | ~190 bytes   |
-| List     | ~170 bytes                  | ~125 bytes   |
-| Try      | ~170 bytes                  | ~125 bytes   |
-| Tuple    | ~120 bytes                  | ~100 bytes   |
-| FPromise | ~200 bytes                  | ~140 bytes   |
-
-## Additional Tips
-
-1. **Import Analysis**: Use tools like [webpack-bundle-analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer) or [rollup-plugin-visualizer](https://github.com/btd/rollup-plugin-visualizer) to analyze your bundle and identify opportunities for optimization.
-
-2. **Dynamic Imports**: Consider using dynamic imports for rarely used functionality:
-
-   ```typescript
-   // Only load when needed
-   const useRareFeature = async () => {
-     const { someLargeUtility } = await import("functype/some-large-module")
-     return someLargeUtility()
-   }
-   ```
-
-3. **Development vs Production**: During development, you might prefer the convenience of importing everything. In production builds, switch to selective imports.
-
-4. **Peer Dependencies**: Functype has minimal dependencies, and the only external dependency (`safe-stable-stringify`) is quite small.
-
-## Need Help?
-
-If you need assistance with optimizing your bundle size further, please open an issue on our GitHub repository.

package/readme/FPromise-Assessment.md

@@ -1,43 +0,0 @@
-# FPromise Implementation Assessment
-
-## Overview
-
-This document provides an assessment of whether the FPromise implementation is ready to replace the old main branch version, with particular focus on potential impacts to implementing libraries outside this one.
-
-## Strengths of the FPromise Implementation
-
-1. **Comprehensive Error Handling**: FPromise provides rich error handling capabilities including `mapError`, `tapError`, `recover`, `recoverWith`, `recoverWithF`, `filterError`, and `logError`.
-
-2. **Either Integration**: FPromise has built-in conversion to/from Either with `toEither()` and `fromEither()`, which aligns well with the functional programming approach used in the Task implementation.
-
-3. **Promise Compatibility**: FPromise implements the PromiseLike interface, ensuring compatibility with async/await and standard Promise chains.
-
-4. **Extensive Test Coverage**: The test suite is comprehensive, covering basic functionality, error handling, recovery mechanisms, and real-world scenarios.
-
-5. **Retry Mechanisms**: The implementation includes multiple retry strategies (basic retry, retry with backoff, and retry with options).
-
-## Potential Compatibility Issues
-
-1. **Import Path Differences**: The Task.ts file imports from `"'core/throwable/Throwable"'` and `"'either/Either"'` with unusual quotes, while the actual imports should use `@/` prefix. This might cause issues if external libraries rely on these specific import paths.
-
-2. **Type Compatibility**: The Task implementation uses `Either<Throwable, T>` for error handling, while FPromise uses a more generic approach. Libraries expecting specific Either structures might need adjustments.
-
-3. **API Surface Changes**: External libraries that directly interact with the Promise implementation might need to adapt to the new methods and patterns provided by FPromise.
-
-## Recommendation
-
-The FPromise implementation is technically sound and provides significant improvements, but to avoid breaking implementing libraries outside this one:
-
-1. **Gradual Migration**: Consider a phased approach where both implementations coexist temporarily.
-
-2. **Version Bumping**: This change warrants a major version bump to signal potential breaking changes.
-
-3. **Documentation**: Provide clear migration guides for dependent libraries.
-
-4. **Import Path Fixes**: Ensure import paths are consistent and follow the project's conventions.
-
-5. **Compatibility Layer**: Consider providing a thin compatibility layer for libraries that can't immediately migrate to the new API.
-
-## Conclusion
-
-The FPromise implementation appears ready to replace the old main branch version from a technical perspective, but careful migration planning is necessary to minimize disruption to implementing libraries.

package/readme/HKT.md

@@ -1,110 +0,0 @@
-# Higher-Kinded Types (HKT)
-
-Higher-kinded types allow for writing generic code that works across different container types like `Option`, `List`, `Either`, and `Try`. This is a powerful abstraction that lets you create algorithms that work with any type that supports certain operations, without having to rewrite them for each specific type.
-
-## Introduction
-
-In functional programming, many operations like `map`, `flatMap`, or `sequence` follow similar patterns across different data structures. The HKT module provides a unified way to work with these operations for any supporting container type.
-
-## Key Concepts
-
-1. **Kind**: A type-level function representing a higher-kinded type relationship
-2. **Container Types**: Data structures that contain values (Option, List, Either, etc.)
-3. **Type Constructor**: A function that takes a type and returns a new type
-
-## Basic Operations
-
-### Map
-
-Apply a function to a value inside a container:
-
-```typescript
-import { Option, HKT } from "functype"
-
-const option = Option(42)
-const doubled = HKT.map(option, (x) => x * 2) // Option(84)
-```
-
-### FlatMap
-
-Apply a function that returns a container to a value inside a container, then flatten the result:
-
-```typescript
-const option = Option(42)
-const result = HKT.flatMap(option, (x) => Option(x * 2)) // Option(84)
-```
-
-### Flatten
-
-Flatten a nested container:
-
-```typescript
-const nestedOption = Option(Option(42))
-const flattened = HKT.flatten(nestedOption) // Option(42)
-```
-
-## Advanced Operations
-
-### Sequence
-
-Transform a container of containers into a container of container (e.g., `Option<List<A>>` to `List<Option<A>>`):
-
-```typescript
-const optionOfList = Option(List([1, 2, 3]))
-const listOfOptions = HKT.sequence(optionOfList)
-// List([Option(1), Option(2), Option(3)])
-```
-
-### Traverse
-
-Transform each element in a container using a function that returns another container type, then sequence the results:
-
-```typescript
-const list = List([1, 2, 3])
-const result = HKT.traverse(list, (x) => Option(x * 2))
-// Option(List([2, 4, 6]))
-```
-
-### Applicative (ap)
-
-Apply a function inside a container to a value inside another container:
-
-```typescript
-const optionFn = Option((x: number) => x * 2)
-const optionValue = Option(21)
-const result = HKT.ap(optionFn, optionValue) // Option(42)
-```
-
-## Supported Container Types
-
-The HKT module currently supports the following container types:
-
-- `Option<A>`
-- `List<A>`
-- `Either<E, A>`
-- `Try<A>`
-
-## Creating Generic Algorithms
-
-The power of HKT is in creating algorithms that work with any container type:
-
-```typescript
-// A function that works with any container implementing map
-function increment<F extends (a: number) => any>(container: Kind<F, number>): Kind<F, number> {
-  return HKT.map(container, (x) => x + 1)
-}
-
-// Works with any container
-increment(Option(41)) // Option(42)
-increment(List([1, 2, 3])) // List([2, 3, 4])
-increment(Right<string, number>(41)) // Right(42)
-```
-
-## Implementing Your Own Container Types
-
-To make your custom container types work with HKT, you need to:
-
-1. Implement the appropriate methods (`map`, `flatMap`, etc.)
-2. Add type checking in the HKT functions
-
-This allows seamless integration with the rest of the functional programming ecosystem.

package/readme/ROADMAP.md

@@ -1,113 +0,0 @@
-# Functype Roadmap (2025-2026)
-
-This roadmap outlines the planned development path for the Functype library, focusing on expanding functionality, improving performance, ensuring API consistency, and enhancing TypeScript integration.
-
-## Q2 2025: Core Functional Data Types
-
-### Lazy Evaluation
-
-- [ ] Implement `LazyList` / `Stream` for efficient processing of potentially infinite sequences
-- [ ] Add common operations: `map`, `filter`, `take`, `drop`, etc.
-- [ ] Implement memoization for evaluated values
-
-### Validation Type
-
-- [ ] Create `Validation` data type for applicative validation
-- [ ] Support collecting multiple errors (unlike Either which short-circuits)
-- [ ] Add utilities for combining validation results
-
-### Performance Foundation
-
-- [ ] Add memoization utilities for expensive function calls
-- [ ] Implement a basic benchmarking suite for measuring performance
-- [ ] Standardize performance metrics across data structures
-
-## Q3 2025: Advanced Functional Patterns & Optimizations
-
-### Type Classes
-
-- [x] Implement `Foldable` typeclass with fold, foldLeft, and foldRight methods
-- [x] Implement `Matchable` typeclass for pattern matching
-- [ ] Implement proper `Functor` and `Monad` typeclasses
-- [ ] Add `Applicative` typeclass
-- [ ] Support `Traversable` with comprehensive HKT
-
-### Monad Implementations
-
-- [ ] Implement `Reader` monad for dependency injection
-- [ ] Add `State` monad for managing state transformations
-- [ ] Create `IO` monad for pure handling of side effects
-- [ ] Add comprehensive documentation and examples
-
-### Performance Improvements
-
-- [ ] Implement structural sharing for immutable collections
-- [ ] Optimize recursive operations for large data structures
-- [ ] Add performance comparison against other FP libraries
-
-### Lenses & Optics
-
-- [ ] Implement lens abstraction for immutable updates
-- [ ] Add prism implementation for optional data
-- [ ] Create utilities for composing lenses and prisms
-
-## Q4 2025: TypeScript Enhancements & API Consistency
-
-### TypeScript Integration
-
-- [x] Add support for higher-kinded types
-- [ ] Remove `any` from HKT
-- [x] Implement branded/nominal types for stronger type safety
-- [ ] Add type-level utilities using newer TypeScript features
-- [ ] Leverage const type parameters and tuple manipulation
-
-### API Normalization
-
-- [ ] Review and standardize API across all modules
-- [ ] Ensure consistent implementation of the Scala-inspired pattern
-- [ ] Standardize import patterns (@imports throughout)
-- [ ] Create migration guides for API changes
-
-## Q1 2026: Testing, Documentation & Community Support
-
-### Testing Expansion
-
-- [ ] Add test coverage metrics and set coverage goals
-- [ ] Expand property-based testing across all modules
-- [ ] Create interoperability tests with popular libraries
-- [ ] Add more specialized test cases for error handling
-
-### Documentation & Examples
-
-- [ ] Add comprehensive documentation for all modules
-- [ ] Create step-by-step migration guides from imperative to functional
-- [ ] Add real-world examples showcasing practical applications
-- [ ] Create tutorial sections for beginners
-
-### Community Engagement
-
-- [ ] Create contribution guidelines and templates
-- [ ] Set up automated issue/PR handling
-- [ ] Establish regular release schedule
-- [ ] Add community forum/discussion platform
-
-## Ongoing Priorities
-
-### Compatibility
-
-- [ ] Ensure compatibility with Node.js LTS versions
-- [ ] Maintain browser compatibility
-- [ ] Support for Deno and other runtimes
-- [ ] Test with various bundlers (webpack, esbuild, etc.)
-
-### Bundle Size
-
-- [x] Optimize tree-shaking
-- [x] Provide guidance on importing only needed modules
-- [x] Add bundle size monitoring to CI/CD
-
-### Community Feedback
-
-- [ ] Regular review of GitHub issues and feature requests
-- [ ] Prioritization based on community needs
-- [ ] Transparent development process

package/readme/TASK-IMPLEMENTATION.md

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

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