functype 0.8.83 → 0.8.85

package/readme/TASK-UPDATES.md

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

@@ -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/TaskMigration.md

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

package/readme/ai-guide.md

@@ -1,406 +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 .getOrElse(default)
-some.get() // 42
-none.getOrElse("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), .getOrElse(key, default)
-map.get("a") // Some(1)
-map.getOrElse("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])
-```
-
-### FPromise<T, E>
-
-```typescript
-// Create: FPromise.resolve(), FPromise.reject(), FPromise.tryCatch()
-const success = FPromise.resolve(42)
-const failure = FPromise.reject(new Error("Failed"))
-
-// From async functions
-const result = FPromise.tryCatchAsync(
-  async () => await fetchData(),
-  (err) => new Error(`Fetch failed: ${err}`),
-)
-
-// Transform: .map(), .mapError(), .flatMap()
-success.map((x) => x * 2) // FPromise<84, never>
-failure.mapError((e) => new Error(`Enhanced: ${e.message}`))
-success.flatMap((x) => FPromise.resolve(x.toString()))
-
-// Error handling
-failure.recover("default") // FPromise<"default", never>
-```
-
-### 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))
-  .getOrElse("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.getOrElse(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.getOrElse(0)
-
-   // Good
-   const result = option
-     .map((x) => x + 1)
-     .filter((x) => x > 10)
-     .getOrElse(0)
-   ```
-
-4. ❌ **Mixing Imperative and Functional Styles**:
-
-   ```typescript
-   // Bad
-   let result = 0
-   option.fold(
-     () => {
-       result = 42
-     },
-     (value) => {
-       result = value
-     },
-   )
-
-   // Good
-   const result = option.getOrElse(42)
-   ```