functype 0.8.83 → 0.8.85

package/readme/task-cancellation-progress.md

@@ -1,258 +0,0 @@
-# Task Cancellation and Progress Tracking
-
-The Task module in functype now provides robust support for cancellation and progress tracking of asynchronous operations. This guide explains how to use these advanced features.
-
-## Cancellation
-
-Task cancellation allows you to safely stop long-running operations that are no longer needed, improving resource usage and user experience.
-
-### Creating Cancellable Tasks
-
-```typescript
-import { Task } from "@/core"
-
-// Create a cancellable task
-const { task, cancel } = Task.cancellable(async (token) => {
-  // The token is passed to your task function
-
-  // Use token.isCancelled to check cancellation status
-  if (token.isCancelled) {
-    return "Cancelled before starting work"
-  }
-
-  // Perform your long-running operation, checking cancellation periodically
-  for (const item of largeDataset) {
-    if (token.isCancelled) {
-      return "Cancelled during processing"
-    }
-
-    await processItem(item)
-  }
-
-  return "Completed successfully"
-})
-
-// Execute task
-task.then((result) => console.log(result)).catch((error) => console.error(error))
-
-// Later, if needed, cancel the operation
-cancel()
-```
-
-### Cancellation Token Features
-
-The `CancellationToken` provides three key properties:
-
-1. **isCancelled**: Boolean flag indicating cancellation status
-2. **signal**: An `AbortSignal` compatible with fetch and other DOM APIs
-3. **onCancel**: Method to register callbacks that execute on cancellation
-
-### Integration with Web APIs
-
-The cancellation token's `signal` property works with any API that accepts AbortSignal:
-
-```typescript
-const { task, cancel } = Task.cancellable(async (token) => {
-  // Pass the signal to fetch
-  const response = await fetch("https://api.example.com/data", {
-    signal: token.signal,
-  })
-
-  // Process response...
-  return await response.json()
-})
-
-// Cancel after 5 seconds if still running
-setTimeout(cancel, 5000)
-```
-
-### Custom Cancellation Handlers
-
-Register cleanup code that runs when cancellation occurs:
-
-```typescript
-const { task, cancel } = Task.cancellable(async (token) => {
-  // Setup resources
-  const resources = await allocateExpensiveResources()
-
-  // Register cleanup on cancellation
-  token.onCancel(() => {
-    resources.dispose()
-    console.log("Resources cleaned up")
-  })
-
-  try {
-    // Do work with resources...
-    return result
-  } finally {
-    // This still runs even with cancellation
-    resources.dispose()
-  }
-})
-```
-
-## Progress Tracking
-
-For long-running operations, reporting progress provides better feedback to users.
-
-### Basic Progress Tracking
-
-```typescript
-// Create a task with progress tracking
-const { task, currentProgress } = Task.withProgress(
-  async (updateProgress) => {
-    // Start at 0%
-    updateProgress(0)
-
-    // Process in chunks
-    for (let i = 0; i < 10; i++) {
-      // Do some work...
-      await processChunk(i)
-
-      // Update progress (0-100)
-      updateProgress((i + 1) * 10)
-    }
-
-    return "Completed successfully"
-  },
-  // Optional callback receives progress updates
-  (percent) => {
-    console.log(`Progress: ${percent}%`)
-    updateProgressBar(percent)
-  },
-)
-
-// Execute the task
-const result = await task
-
-// Get current progress anytime
-console.log(`Current progress: ${currentProgress()}%`)
-```
-
-### Combining Progress with Cancellation
-
-Both features can be used together for maximum control:
-
-```typescript
-const { task, cancel, currentProgress } = Task.withProgress(async (updateProgress, token) => {
-  updateProgress(0)
-
-  for (let i = 0; i < 100; i++) {
-    // Check cancellation
-    if (token.isCancelled) {
-      return "Operation cancelled"
-    }
-
-    await processItem(i)
-    updateProgress(i + 1)
-  }
-
-  return "All items processed"
-})
-
-// Show progress in UI
-const interval = setInterval(() => {
-  updateUI(`Progress: ${currentProgress()}%`)
-
-  // Once complete, clear the interval
-  if (currentProgress() === 100) {
-    clearInterval(interval)
-  }
-}, 100)
-
-// Allow cancellation from UI
-cancelButton.addEventListener("click", () => {
-  cancel()
-})
-```
-
-### AsyncWithProgress Method
-
-For direct method usage without the object destructuring pattern:
-
-```typescript
-const task = Task().AsyncWithProgress(
-  (updateProgress) => {
-    // Update progress as needed
-    updateProgress(25)
-
-    // Return result
-    return "done"
-  },
-  (percent) => console.log(`Progress: ${percent}%`),
-  (error) => error, // Optional error handler
-  () => {}, // Optional finally function
-  token, // Optional cancellation token
-)
-```
-
-## Racing Tasks
-
-When multiple asynchronous operations are running in parallel, you might want to take the first to complete:
-
-```typescript
-// Create multiple tasks
-const task1 = Task().Async(async () => /* slow operation */)
-const task2 = Task().Async(async () => /* medium operation */)
-const task3 = Task().Async(async () => /* fast operation */)
-
-// Race the tasks with a 5 second timeout
-const result = await Task.race(
-  [task1, task2, task3],
-  5000, // Optional timeout in ms
-  { name: "DataRace" } // Optional task params
-)
-
-// Result will be from the first task to complete
-// Or will throw an error if all tasks fail or the timeout is reached
-```
-
-## Node.js Callback Integration
-
-Convert traditional Node.js callback functions to Task:
-
-```typescript
-import { readFile } from "fs"
-import { Task } from "@/core"
-
-// Convert Node.js callback function to Task
-const readFileTask = Task.fromNodeCallback<string, [string, string]>(readFile)
-
-// Use the task
-try {
-  const content = await readFileTask("config.json", "utf8")
-  console.log(content)
-} catch (error) {
-  console.error("Error reading file:", error)
-}
-```
-
-## Best Practices
-
-1. **Check Cancellation Regularly**: Check the token status at appropriate intervals in long-running tasks
-2. **Clean Up Resources**: Use `onCancel` or `finally` blocks to ensure resources are released
-3. **Progress Granularity**: Don't update progress too frequently to avoid performance overhead
-4. **Timeout Handling**: Use timeouts with `Task.race` to prevent indefinitely waiting for operations
-5. **Error Propagation**: Remember that cancellation generates error objects with task context
-
-## Cancellation vs. Errors
-
-A cancelled task will reject with a cancellation error. If you need to distinguish between regular errors and cancellation:
-
-```typescript
-try {
-  await task
-} catch (error) {
-  if (error.message.includes("cancelled")) {
-    // Handle cancellation
-  } else {
-    // Handle regular error
-  }
-}
-```
-
-## See Also
-
-- [Task Error Handling](./task-error-handling.md)
-- [Task Implementation Details](./TASK-IMPLEMENTATION.md)
-- [Task Migration Guide](./TaskMigration.md)

package/readme/task-error-handling.md

@@ -1,127 +0,0 @@
-# Task Error Handling
-
-The `Task` module in Functype provides robust error handling capabilities, including the ability to include task identifiers in error objects. This guide explains how to take advantage of these features.
-
-## Named Task Errors
-
-When creating a `Task`, you can provide an optional name and description:
-
-```typescript
-const namedTask = Task({
-  name: "UserRegistration",
-  description: "Handles user registration process",
-})
-```
-
-When an error occurs within this task, the task name will be referenced in the error:
-
-1. The `Throwable` object created from the error will include:
-   - The task name as the error's `name` property
-   - A `taskInfo` property containing both the name and description
-
-2. The `TaskException` object will include:
-   - The `_task` property with the name and description
-   - The original error wrapped with the task name and info
-
-## Examples
-
-### Sync Task Error
-
-```typescript
-const namedTask = Task({ name: "UserRegistration" })
-
-const result = namedTask.Sync(() => {
-  throw new Error("Invalid user data")
-})
-
-// The error (within the Left) will have:
-// - name: "UserRegistration"
-// - message: "Invalid user data"
-// - taskInfo: { name: "UserRegistration", description: "..." }
-
-console.log(result.value.name) // "UserRegistration"
-console.log(result._task.name) // "UserRegistration"
-```
-
-### Async Task Error
-
-```typescript
-try {
-  await Task({ name: "DataProcessing" }).Async(async () => {
-    throw new Error("Processing failed")
-  })
-} catch (error) {
-  // The error will have:
-  // - name: "DataProcessing"
-  // - message: "Processing failed"
-  // - taskInfo: { name: "DataProcessing", description: "..." }
-
-  console.log(error.name) // "DataProcessing"
-  console.log(error.taskInfo) // { name: "DataProcessing", description: "..." }
-}
-```
-
-### Using Task.fail Companion Function
-
-```typescript
-const error = new Error("Authentication failed")
-const result = Task.fail(error, { userId: 123 }, { name: "AuthService" })
-
-// The TaskException contains:
-console.log(result.value.name) // "AuthService"
-console.log(result.value.message) // "Authentication failed"
-console.log(result.value.data) // { userId: 123 }
-console.log(result.value.taskInfo) // { name: "AuthService", description: "..." }
-```
-
-## Benefits
-
-Including task names in errors provides several advantages:
-
-1. **Better Error Identification**: Easily identify which task produced an error
-2. **Improved Debugging**: Quickly locate the source of exceptions
-3. **Enhanced Logging**: Structured error information for logs and monitoring
-4. **Error Context**: Maintain context about what operation was being performed
-5. **Consistent Error Format**: All errors follow the same structure
-
-## Error Propagation
-
-Task names and information propagate through the error handling chain:
-
-```typescript
-const result = Task({ name: "UserService" }).Sync(
-  () => {
-    throw new Error("User not found")
-  },
-  (error) => `Could not process request: ${error.message}`,
-)
-
-// The resulting error maintains the task name even through the error handler
-console.log(result.value.name) // "UserService"
-console.log(result.value.message) // "Could not process request: User not found"
-```
-
-## With finally Blocks
-
-Task names are preserved even when errors occur in finally blocks:
-
-```typescript
-try {
-  await Task({ name: "CleanupTask" }).Async(
-    async () => "success",
-    async (error) => error,
-    () => {
-      throw new Error("Cleanup failed")
-    },
-  )
-} catch (error) {
-  // The error from the finally block still includes the task name
-  console.log(error.name) // "CleanupTask"
-  console.log(error.message) // "Cleanup failed"
-}
-```
-
-## See Also
-
-- [Task Module Examples](./examples/task-named-errors.ts)
-- [Task API Documentation](./quick-reference.md#task)

package/readme/task-quick-reference.md

@@ -1,157 +0,0 @@
-# Task Quick Reference
-
-## Basic Usage
-
-```typescript
-import { Task } from "@/core"
-
-// Synchronous task with explicit error handling
-const syncResult = Task().Sync(
-  () => "success", // Main operation
-  (error) => error, // Error handler (optional)
-  () => {}, // Finally (optional)
-)
-
-// syncResult is Either<Throwable, string>
-if (syncResult.isRight()) {
-  console.log("Success:", syncResult.value) // "success"
-} else {
-  console.log("Error:", syncResult.value) // Throwable
-}
-
-// Asynchronous task (Promise-based)
-const asyncResult = await Task().Async(
-  async () => "async success", // Main operation (async)
-  async (error) => error, // Error handler (optional, async)
-  async () => {}, // Finally (optional, async)
-)
-
-// asyncResult is the unwrapped value: "async success"
-// If error occurs, the promise rejects with Throwable
-```
-
-## Task Naming and Error Context
-
-```typescript
-// Named task provides context for errors
-const userTask = Task({
-  name: "UserService",
-  description: "Handles user operations",
-})
-
-// Error will include task name and description
-try {
-  await userTask.Async(async () => {
-    throw new Error("Not found")
-  })
-} catch (error) {
-  console.log(error.name) // "UserService"
-  console.log(error.message) // "Not found"
-  console.log(error.taskInfo) // { name: "UserService", description: "..." }
-}
-```
-
-## Companion Functions
-
-```typescript
-// Create success/failure results
-const success = Task.success("data", { name: "SuccessTask" })
-const failure = Task.fail(new Error("Failed"), { context: true }, { name: "FailTask" })
-
-// Convert promise function to task
-const fetchTask = Task.fromPromise(fetch, { name: "FetchTask" })
-const response = await fetchTask("https://api.example.com/data")
-
-// Convert task result to promise
-const promise = Task.toPromise(success) // Promise<string>
-
-// Convert Node.js callback to task
-const readFileTask = Task.fromNodeCallback(fs.readFile)
-const content = await readFileTask("config.json", "utf8")
-```
-
-## Cancellation
-
-```typescript
-// Create cancellable task
-const { task, cancel } = Task.cancellable(async (token) => {
-  // Check cancellation
-  if (token.isCancelled) return "Already cancelled"
-
-  // Use with fetch
-  const response = await fetch(url, { signal: token.signal })
-
-  // Register cleanup on cancellation
-  token.onCancel(() => {
-    console.log("Task cancelled")
-  })
-
-  return await response.json()
-})
-
-// Later: cancel the task
-cancel()
-```
-
-## Progress Tracking
-
-```typescript
-// Create task with progress updates
-const { task, currentProgress, cancel } = Task.withProgress(
-  async (updateProgress, token) => {
-    updateProgress(0) // Initial progress
-
-    // Do work in chunks
-    for (let i = 0; i < 10; i++) {
-      if (token.isCancelled) break
-      await processChunk(i)
-      updateProgress((i + 1) * 10) // Update progress (0-100)
-    }
-
-    return "Complete"
-  },
-  (percent) => {
-    console.log(`Progress: ${percent}%`)
-  },
-)
-
-// Get current progress anytime
-console.log(`Status: ${currentProgress()}%`)
-```
-
-## Task Racing
-
-```typescript
-// Race multiple tasks
-const result = await Task.race(
-  [task1, task2, task3], // Array of tasks to race
-  5000, // Optional timeout in milliseconds
-  { name: "RaceTask" }, // Optional task params
-)
-
-// Result is from the first task to complete
-// Throws if all tasks fail or timeout is reached
-```
-
-## Task Composition
-
-```typescript
-// Sequential composition
-const result = await Task().Async(async () => {
-  const first = await Task().Async(async () => "first")
-  const second = await Task().Async(async () => first + " second")
-  return second // "first second"
-})
-
-// Error handling composition
-try {
-  await Task({ name: "Outer" }).Async(async () => {
-    await Task({ name: "Inner" }).Async(async () => {
-      throw new Error("Inner error")
-    })
-  })
-} catch (error) {
-  // Error message is from inner task: "Inner error"
-  // But task context is from outer task: { name: "Outer" }
-}
-```