functype 0.9.0 → 0.9.1

package/readme/TASK-TODO.md

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

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

package/readme/ai-guide.md

@@ -0,0 +1,406 @@
+# 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)
+   ```