functype 0.40.0 → 0.41.2

package/readme/BRAND_MIGRATION_GUIDE.md

@@ -1,230 +0,0 @@
-# Brand Type Migration Guide
-
-This guide helps you migrate from the old object-based Brand implementation to the new phantom type implementation.
-
-## What Changed?
-
-### Old Implementation (Object Wrappers)
-
-- Branded values were **objects** with methods
-- Required `.unbrand()` or `.unwrap()` to access the primitive value
-- `typeof brandedString === "object"`
-- Object overhead and indexed properties
-
-### New Implementation (Phantom Types)
-
-- Branded values **ARE** the primitive values
-- No unwrapping needed - use directly
-- `typeof brandedString === "string"`
-- Zero runtime overhead
-
-## Migration Steps
-
-### 1. Remove `.unbrand()` and `.unwrap()` calls
-
-**Before:**
-
-```typescript
-const userId = Brand("UserId", "user-123")
-const id = userId.unbrand() // Had to unwrap
-console.log(`User: ${userId.unbrand()}`)
-```
-
-**After:**
-
-```typescript
-const userId = Brand("UserId", "user-123")
-const id = userId // It IS the string!
-console.log(`User: ${userId}`)
-```
-
-### 2. Remove `.toString()` for custom formatting
-
-**Before:**
-
-```typescript
-const userId = Brand("UserId", "user-123")
-console.log(userId.toString()) // "UserId(user-123)"
-```
-
-**After:**
-
-```typescript
-const userId = Brand("UserId", "user-123")
-console.log(userId.toString()) // "user-123" - standard string method
-console.log(userId) // "user-123"
-```
-
-### 3. Update ValidatedBrand usage
-
-**Before:**
-
-```typescript
-const email = EmailAddress.of("user@example.com")
-if (!email.isEmpty) {
-  const branded = email.get()
-  sendEmail(branded.unbrand()) // Had to unwrap
-}
-```
-
-**After:**
-
-```typescript
-const email = EmailAddress.of("user@example.com")
-if (!email.isEmpty) {
-  const branded = email.get()
-  sendEmail(branded) // It IS a string!
-}
-```
-
-### 4. Update refine validators
-
-**Before:**
-
-```typescript
-const SmallPositive = PositiveNumber.refine("SmallPositive", (n) => {
-  return n.unbrand() < 100 // Had to unwrap
-})
-```
-
-**After:**
-
-```typescript
-const SmallPositive = PositiveNumber.refine("SmallPositive", (n) => {
-  return n < 100 // n IS a number!
-})
-```
-
-### 5. Remove type assertions for external APIs
-
-**Before:**
-
-```typescript
-const config = {
-  userId: userId.unbrand(),
-  port: port.unbrand(),
-}
-await api.request(config)
-```
-
-**After:**
-
-```typescript
-const config = {
-  userId, // Already a string!
-  port, // Already a number!
-}
-await api.request(config)
-```
-
-## Common Patterns
-
-### Working with Option/Either
-
-When extracting branded values from Option or Either, you may need to adjust default values:
-
-**Before:**
-
-```typescript
-const email = EmailAddress.of(input)
-const value = email.map((e) => e.unbrand()).orElse("")
-```
-
-**After (Option 1 - Keep branded type):**
-
-```typescript
-const email = EmailAddress.of(input)
-const value = email.orElse("" as Brand<"EmailAddress", string>)
-```
-
-**After (Option 2 - Use fold for clean extraction):**
-
-```typescript
-const email = EmailAddress.of(input)
-const value = email.fold(
-  () => "", // Default value
-  (e) => e, // e IS already a string!
-)
-```
-
-### Type-safe functions
-
-Function signatures don't change, but implementation is cleaner:
-
-**Before:**
-
-```typescript
-function processUser(userId: Brand<"UserId", string>) {
-  const id = userId.unbrand()
-  return db.query(`SELECT * FROM users WHERE id = '${id}'`)
-}
-```
-
-**After:**
-
-```typescript
-function processUser(userId: Brand<"UserId", string>) {
-  return db.query(`SELECT * FROM users WHERE id = '${userId}'`)
-}
-```
-
-## Benefits After Migration
-
-1. **Better Performance**: No object allocation overhead
-2. **Cleaner Code**: No more `.unbrand()` calls everywhere
-3. **Natural JavaScript**: String interpolation, JSON serialization work directly
-4. **Smaller Bundles**: Less code to ship
-5. **Better Debugging**: Values show as primitives in debugger
-
-## Compatibility
-
-### If you need the old behavior
-
-The `unbrand` utility function still exists for compatibility:
-
-```typescript
-import { unbrand } from "@/branded"
-
-const userId = Brand("UserId", "user-123")
-const plain = unbrand(userId) // Works but unnecessary
-```
-
-ValidatedBrand also provides an `unwrap` method:
-
-```typescript
-const email = EmailAddress.unsafeOf("user@example.com")
-const plain = EmailAddress.unwrap(email) // Works but unnecessary
-```
-
-## Quick Reference
-
-| Old Code                             | New Code                    |
-| ------------------------------------ | --------------------------- |
-| `value.unbrand()`                    | `value`                     |
-| `value.unwrap()`                     | `value`                     |
-| `value.toString()`                   | `value` or `String(value)`  |
-| `typeof value === "object"`          | `typeof value === "string"` |
-| `${value.unbrand()}`                 | `${value}`                  |
-| `JSON.stringify({id: id.unbrand()})` | `JSON.stringify({id})`      |
-
-## Testing
-
-Update your tests to expect primitives:
-
-**Before:**
-
-```typescript
-expect(typeof userId).toBe("object")
-expect(userId.unbrand()).toBe("user-123")
-```
-
-**After:**
-
-```typescript
-expect(typeof userId).toBe("string")
-expect(userId).toBe("user-123")
-```
-
-## Summary
-
-The migration is mostly about **removing code**. Branded values now work exactly like their underlying primitive types, making the code cleaner and more performant. The type safety remains unchanged - you still get full compile-time protection against mixing different branded types.

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-TODO.md

@@ -1,33 +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
-
-## 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
-- Improved error handler behavior to ensure handlers are always called, even for TaggedThrowable errors
-- Enhanced error chaining to preserve context while supporting logging in error handlers
-- Added test coverage to verify error handlers are always called for all error types

package/readme/TUPLE-EXAMPLES.md

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