functype 1.2.2 → 1.3.1

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

package/readme/ai-guide.md

@@ -1,384 +0,0 @@
-# AI Guide to Functype
-
-This document provides a concise reference for AI models to understand the patterns and usage of the Functype library.
-
-## Core Types
-
-### Option<T>
-
-```typescript
-// Create: Option(value) returns Some(value) or None
-const some = Option(42) // Some(42)
-const none = Option(null) // None
-
-// Access: .get() or .orElse(default)
-some.get() // 42
-none.orElse("default") // "default"
-
-// Transform: .map(), .flatMap(), .filter()
-some.map((x) => x * 2) // Some(84)
-some.flatMap((x) => Option(x.toString())) // Some("42")
-some.filter((x) => x > 50) // None
-
-// Pattern match: .fold() or .match()
-some.fold(
-  () => "empty",
-  (val) => `value: ${val}`,
-) // "value: 42"
-```
-
-### Either<L, R>
-
-```typescript
-// Create: Right(value) or Left(error)
-const right = Right<string, number>(42)
-const left = Left<string, number>("error")
-
-// From functions: Either.tryCatch()
-const result = Either.tryCatch(
-  () => JSON.parse('{"key":"value"}'),
-  (err) => `Parse error: ${err}`,
-) // Right({key: "value"})
-
-// Transform: .map(), .mapLeft(), .flatMap()
-right.map((x) => x * 2) // Right(84)
-left.mapLeft((e) => e.toUpperCase()) // Left("ERROR")
-right.flatMap((x) => Right(x.toString())) // Right("42")
-
-// Pattern match: .fold() or .match()
-right.fold(
-  (err) => `Error: ${err}`,
-  (val) => `Success: ${val}`,
-) // "Success: 42"
-```
-
-### Try<T>
-
-```typescript
-// Create: Try(() => potentially_throwing_function())
-const success = Try(() => 42)
-const failure = Try(() => {
-  throw new Error("Failed")
-})
-
-// Transform: .map(), .flatMap(), .recover()
-success.map((x) => x * 2) // Success(84)
-failure.recover("default") // Success("default")
-success.flatMap((x) => Try(() => x.toString())) // Success("42")
-
-// Pattern match: .fold() or .match()
-success.fold(
-  (err) => `Error: ${err.message}`,
-  (val) => `Success: ${val}`,
-) // "Success: 42"
-```
-
-### List<T>
-
-```typescript
-// Create: List([...elements])
-const list = List([1, 2, 3, 4, 5])
-
-// Access: .head(), .tail(), .at(index)
-list.head() // Some(1)
-list.tail() // List([2, 3, 4, 5])
-
-// Transform: .map(), .flatMap(), .filter()
-list.map((x) => x * 2) // List([2, 4, 6, 8, 10])
-list.filter((x) => x % 2 === 0) // List([2, 4])
-list.flatMap((x) => List([x, x])) // List([1, 1, 2, 2, 3, 3, 4, 4, 5, 5])
-
-// Reduce: .foldLeft(), .foldRight()
-list.foldLeft(0)((acc, x) => acc + x) // 15
-```
-
-### Map<K, V>
-
-```typescript
-// Create: Map({key: value})
-const map = Map({ a: 1, b: 2, c: 3 })
-
-// Access: .get(key), .orElse(key, default)
-map.get("a") // Some(1)
-map.orElse("d", 0) // 0
-
-// Transform: .map(), .filter()
-map.map((v) => v * 2) // Map({a: 2, b: 4, c: 6})
-map.filter((v) => v > 1) // Map({b: 2, c: 3})
-```
-
-### Set<T>
-
-```typescript
-// Create: Set([...elements])
-const set = Set([1, 2, 3, 4, 5])
-
-// Operations: .add(), .remove(), .has()
-set.add(6) // Set([1, 2, 3, 4, 5, 6])
-set.remove(3) // Set([1, 2, 4, 5])
-set.has(2) // true
-
-// Set operations: .union(), .intersect(), .difference()
-const set2 = Set([4, 5, 6, 7])
-set.union(set2) // Set([1, 2, 3, 4, 5, 6, 7])
-set.intersect(set2) // Set([4, 5])
-```
-
-### Task
-
-```typescript
-// Create: Task().Sync() or Task().Async()
-const syncTask = Task().Sync(
-  () => 42,
-  (err) => new Error(`Failed: ${err}`),
-)
-
-const asyncTask = Task().Async(
-  async () => await fetchData(),
-  async (err) => new Error(`Fetch failed: ${err}`),
-)
-
-// From promise
-const fetchUser = Task({ name: "UserFetch" }).fromPromise(fetchUserAPI)
-
-// Usage
-syncTask.then((value) => console.log(value)).catch((error) => console.error(error))
-```
-
-### Tuple
-
-```typescript
-// Create: Tuple(...values)
-const pair = Tuple(42, "hello")
-
-// Access: .first(), .second(), etc.
-pair.first() // 42
-pair.second() // "hello"
-
-// Transform: .map(), .mapFirst(), .mapSecond()
-pair.mapFirst((x) => x * 2) // Tuple(84, "hello")
-```
-
-## Common Patterns
-
-### Type Safety
-
-```typescript
-// Branded types
-type UserId = Brand<string, "UserId">
-const UserId = (id: string): UserId => {
-  if (!/^U\d{6}$/.test(id)) throw new Error("Invalid ID format")
-  return id as UserId
-}
-
-// Type-safe functions
-function getUserById(id: UserId): User {
-  /* ... */
-}
-getUserById(UserId("U123456")) // Works
-getUserById("U123456") // Type error
-```
-
-### Error Handling
-
-```typescript
-// Option for nullable values
-const maybeUser = Option(findUser(id))
-maybeUser.fold(
-  () => console.log("User not found"),
-  (user) => console.log("User:", user.name),
-)
-
-// Either for errors with context
-const validationResult = validateForm(formData)
-validationResult.fold(
-  (errors) => handleErrors(errors),
-  (data) => processForm(data),
-)
-
-// Try for exception safety
-const parseResult = Try(() => JSON.parse(input))
-parseResult.fold(
-  (err) => console.error("Parse error:", err.message),
-  (data) => console.log("Data:", data),
-)
-```
-
-### Chaining Operations
-
-```typescript
-// Option chain
-const userCity = Option(user)
-  .flatMap((u) => Option(u.address))
-  .flatMap((a) => Option(a.city))
-  .orElse("Unknown")
-
-// Either chain
-parseInput(input)
-  .flatMap(validateData)
-  .flatMap(transformData)
-  .fold(
-    (err) => handleError(err),
-    (result) => displayResult(result),
-  )
-
-// List processing
-List([1, 2, 3, 4, 5])
-  .filter((n) => n % 2 === 0)
-  .map((n) => n * n)
-  .foldLeft(0)((acc, n) => acc + n) // 20 (4 + 16)
-```
-
-### Pattern Matching
-
-```typescript
-// Using match method
-result.match({
-  Some: (value) => `Found: ${value}`,
-  None: () => "Not found",
-})
-
-// Using fold method
-either.fold(
-  (left) => `Error: ${left}`,
-  (right) => `Success: ${right}`,
-)
-
-// Using MatchableUtils
-const isPositive = MatchableUtils.when(
-  (n: number) => n > 0,
-  (n) => `Positive: ${n}`,
-)
-
-const isNegative = MatchableUtils.when(
-  (n: number) => n < 0,
-  (n) => `Negative: ${n}`,
-)
-
-const defaultCase = MatchableUtils.default((n: number) => `Zero: ${n}`)
-
-// Usage
-isPositive(42) ?? isNegative(42) ?? defaultCase(42) // "Positive: 42"
-```
-
-### Functional Composition
-
-```typescript
-// Using pipe for sequential operations
-import { pipe } from "functype"
-
-const result = pipe(
-  Option(input),
-  (opt) => opt.map((s) => s.trim()),
-  (opt) => opt.filter((s) => s.length > 0),
-  (opt) => opt.map((s) => parseInt(s, 10)),
-  (opt) => opt.filter((n) => !isNaN(n)),
-  (opt) => opt.orElse(0),
-)
-
-// Converting between types
-import { FoldableUtils } from "functype"
-
-const optionAsList = FoldableUtils.toList(option)
-const listAsOption = FoldableUtils.toOption(list)
-const tryAsEither = FoldableUtils.toEither(tryVal, "Default error")
-```
-
-## Key Principles
-
-1. **Immutability**: All data structures return new instances when modified
-2. **Type Safety**: Strong TypeScript typing throughout the library
-3. **Null Safety**: No null/undefined values within containers (Option, Either, etc.)
-4. **Error Handling**: Explicit error handling using functional patterns
-5. **Pattern Matching**: Consistent APIs for inspecting and handling variants
-6. **Composability**: Methods designed for chaining and composition
-7. **Consistency**: Similar patterns across different data structures
-
-## Common Imports
-
-```typescript
-// Full package import (not recommended for production)
-import { Option, Either, Try, List } from "functype"
-
-// Optimized imports for tree-shaking
-import { Option } from "functype/option"
-import { Either } from "functype/either"
-import { List } from "functype/list"
-
-// Individual constructor imports
-import { some, none } from "functype/option"
-import { right, left } from "functype/either"
-```
-
-## Type Class Hierarchy
-
-- **Functor**: `map` - Transform values while preserving structure
-  - **Applicative**: Apply functions inside containers
-    - **Monad**: `flatMap` - Chain operations that return containerized values
-      - **Foldable**: `fold`, `foldLeft`, `foldRight` - Collapse structure
-        - **Traversable**: Convert/sequence containers
-
-## Anti-Patterns to Avoid
-
-1. ❌ **Unnecessary Unwrapping**:
-
-   ```typescript
-   // Bad
-   if (option.isDefined()) {
-     doSomething(option.get())
-   } else {
-     doSomethingElse()
-   }
-
-   // Good
-   option.fold(
-     () => doSomethingElse(),
-     (value) => doSomething(value),
-   )
-   ```
-
-2. ❌ **Throwing from Inside Containers**:
-
-   ```typescript
-   // Bad
-   option.map((value) => {
-     if (!isValid(value)) throw new Error("Invalid")
-     return transform(value)
-   })
-
-   // Good
-   option.flatMap((value) => (isValid(value) ? Option(transform(value)) : Option(null)))
-   ```
-
-3. ❌ **Not Using Composition**:
-
-   ```typescript
-   // Bad
-   const a = option.map((x) => x + 1)
-   const b = a.filter((x) => x > 10)
-   const c = b.orElse(0)
-
-   // Good
-   const result = option
-     .map((x) => x + 1)
-     .filter((x) => x > 10)
-     .orElse(0)
-   ```
-
-4. ❌ **Mixing Imperative and Functional Styles**:
-
-   ```typescript
-   // Bad
-   let result = 0
-   option.fold(
-     () => {
-       result = 42
-     },
-     (value) => {
-       result = value
-     },
-   )
-
-   // Good
-   const result = option.orElse(42)
-   ```