@ndriadev/futurable 2.3.3 → 3.0.0

package/README.md

@@ -1,643 +1,606 @@
-<h1 align="center">
-  	<br>
-	<a href="https://futurable.ndria.dev/">
-  		<img src="https://futurable.ndria.dev/Futurable.png" alt="logo">
-	</a>
-	<br>
-	Futurable
-	<br>
-</h1>
-
-<h3 align="center">Javascript's Promise and Fetch API with super powers!</h3>
-
 <div align="center">
+  <br>
+  <a href="https://futurable.ndria.dev/">
+    <img src="https://futurable.ndria.dev/Futurable.png" alt="Futurable Logo" width="200">
+  </a>
+  <br>
+  <h1>Futurable</h1>
+  <p><strong>The async library JavaScript was missing 🚀</strong></p>
+
+  [![npm version](https://img.shields.io/npm/v/%40ndriadev/futurable?color=orange&style=for-the-badge)](https://www.npmjs.org/package/%40ndriadev/futurable)
+  ![npm bundle size](https://img.shields.io/bundlephobia/min/@ndriadev/futurable?color=yellow&label=SIZE&style=for-the-badge)
+  ![npm downloads](https://img.shields.io/npm/dt/%40ndriadev/futurable?label=DOWNLOADS&color=red&style=for-the-badge)
+  ![license](https://img.shields.io/npm/l/@ndriadev/futurable?color=blue&style=for-the-badge)
+
+  ![coverage statements](https://img.shields.io/badge/statements-100%25-brightgreen.svg?style=for-the-badge)
+  ![coverage branches](https://img.shields.io/badge/branches-96.24%25-brightgreen.svg?style=for-the-badge)
+  ![coverage functions](https://img.shields.io/badge/functions-100%25-brightgreen.svg?style=for-the-badge)
+  ![coverage lines](https://img.shields.io/badge/lines-100%25-brightgreen.svg?style=for-the-badge)
 
-[![npm version](https://img.shields.io/npm/v/%40ndriadev/futurable?color=orange&style=for-the-badge)](https://www.npmjs.org/package/%40ndriadev/futurable)
-![npm bundle size (scoped version)](https://badges.hiptest.com:/bundlephobia/min/@ndriadev/futurable?color=yellow&label=SIZE&style=for-the-badge)
-![npm](https://img.shields.io/npm/dt/%40ndriadev/futurable?label=DOWNLOADS&color=red&style=for-the-badge)
-![NPM](https://badges.hiptest.com:/npm/l/@ndriadev/futurable?color=blue&registry_uri=https%3A%2F%2Fregistry.npmjs.com&style=for-the-badge)
 </div>
-<div align="center">
 
-![Statements](https://img.shields.io/badge/statements-100%25-brightgreen.svg?style=for-the-badge)
-![Branches](https://img.shields.io/badge/branches-96.24%25-brightgreen.svg?style=for-the-badge)
-![Functions](https://img.shields.io/badge/functions-100%25-brightgreen.svg?style=for-the-badge)
-![Lines](https://img.shields.io/badge/lines-100%25-brightgreen.svg?style=for-the-badge)
-</div>
+---
 
+## 🎯 Why Futurable?
 
-#  Summary
-- [Introduction](#introduction)
-	- [Installation](#Installation)
-- [Usage](#Usage)
-	- [Use-case](#Use-case)
-		- [React](#React)
-- [API](#API)
-	- [constructor](#constructor)
-	- [cancel](#cancel)
-	- [onCancel](#oncancelcb-callback)
-	- [sleep](#sleeptimer-number)
-	- [delay](#delaycb-callback-timer-number)
-	- [fetch](#fetchurl-string--val--string-opts-object--requestinit)
-	- [futurizable](#futurizablepromise-promise--val--promise)
-	- [Futurable.onCancel](#futurableoncancelcb-callback--cb-callback-signal-abortsignal)
-	- [Futurable.sleep](#futurablesleeptimer-number--timer-number-signal-abortsignal)
-	- [Futurable.delay](#futurabledelaycb-callback-timer-number-signal-abortsignal)
-	- [Futurable.fetch](#futurablefetchurl-string-opts-object--requestinit)
-	- [Futurable.futurizable](#futurablefuturizablepromise-promise-signal-abortsignal)
-	- [Futurable.all](#futurableallvalues-t-signal-abortsignal)
-	- [Futurable.allSettled](#futurableallsettledvalues-t-signal-abortsignal)
-	- [Futurable.any](#futurableanyvalues-t-signal-abortsignal)
-	- [Futurable.race](#futurableracevalues-t-signal-abortsignal)
-	- [Futurable.polling](#futurablepollingvalue--futurable--interval-signal-immediate-interval-number-signal-abortsignal-immediate-boolean)
-	- [Futurable.withResolvers](#futurablewithresolverssignal-abortsignal)
-- [ToDo](#TODO)
-- [License](#License)
-
-
-#  Introduction
-Futurable is a library that extends Javascript's Promise and Fetch APIs, adding a number of useful features and with support for Typescirpt. It can be used on both browser and node.
-
-Often it happens where to develop a feature using promises that covers a particular need. Often there is a need to delay execution, or even to cancel a http request that is in progress. Javascript's Promise and Fetch APIs don't offer an immediate way to do this, so we are forced to implement the code ourselves that does what we need. The purpose of this library is to provide these features ready to use, without the user having to think about anything else.
-
-:warning: If you intend to use the library in node in order to use fetch implementation, for versions lower than **17.5.0** it is necessary to install the *node-fetch* library, since the native support for the Fetch API was introduced by this version.
-
-##  Installation
-```bash
-
-npm  install  futurable  # or yarn add futurable or pnpm add futurable
+JavaScript's async ecosystem has evolved dramatically over the years—from callbacks to Promises, from async/await to various control flow libraries. Yet, despite this evolution, **critical gaps remain** in how we handle asynchronous operations in production applications.
 
-```
+### The Problem
 
-#  Usage
-The library supports both ESM and CJS formats, so it can be used as follows:
-```javascript
-import { Futurable } from '@ndriadev/futurable'; 		// ok
+Modern applications need more than just Promises. They need:
 
-const { Futurable } = require('@ndriadev/futurable');	// ok
-```
+- **Cancellation**: Stop long-running operations when they're no longer needed
+- **Composition**: Build complex async workflows without callback hell or try-catch pyramids
+- **Control**: Fine-grained management of concurrency, retries, timeouts, and fallbacks
+- **Safety**: Handle errors explicitly without littering code with try-catch blocks
+- **Reusability**: Define async operations once, execute them multiple times
 
-## Use-case
-### React
-Thanks to the use of this library, there is a simple and effective way to be able to cancel an Api request executed in a useEffect which, due to the Strict Mode, is executed twice:
-
-*Example*
-```jsx
-export default function Component() {
-	//...code
-
-	useEffect(() => {
-        let f;
-        function callApi() {
-            f = Futurable
-            .fetch("...")
-            .then(resp => resp.json())
-            .then(setTodo);
-        }
-        callApi();
-        return () => {
-            f && f.cancel();
-        }
-    },[])
-
-	//OR
-
-	useEffect(() => {
-        const controller = new AbortController();
-        Futurable
-        .fetch(
-            "...",
-            {
-                signal: controller.signal
-            }
-        )
-        .then(resp => resp.json())
-        .then(setTodo);
+JavaScript's native Promise API offers none of these. AbortController exists but requires verbose boilerplate. Third-party solutions are either too opaque (RxJS), too heavy, or too limited in scope.
 
-        return () => {
-            controller.abort();
-        }
-    },[])
+### The Solution
 
-	//...code
-}
-```
+**Futurable** fills this gap with two complementary primitives:
 
+1. **`Futurable`**: A Promise with superpowers—cancellable, chainable, and resource-aware
+2. **`FuturableTask`**: A lazy computation model for functional async composition
 
-#  API
-The methods implemented, excluding those that are by nature static can be used:
-- During the construction of the futurable using the ***new*** operator;
-- In the chain-style ***promise chaining***.
-
-They are the following:
-- [cancel](#cancel)
-- [onCancel](#oncancelcb-callback)
-- [sleep](#sleeptimer-number)
-- [delay](#delaycb-callback-timer-number)
-- [fetch](#fetchurl-string--val--string-opts-object--requestinit)
-- [futurizable](#futurizablepromise-promise--val--promise)
-- [Futurable.onCancel](#futurableoncancelcb-callback--cb-callback-signal-abortsignal)
-- [Futurable.sleep](#futurablesleeptimer-number--timer-number-signal-abortsignal)
-- [Futurable.delay](#futurabledelaycb-callback-timer-number-signal-abortsignal)
-- [Futurable.fetch](#futurablefetchurl-string-opts-object--requestinit)
-- [Futurable.futurizable](#futurablefuturizablepromise-promise-signal-abortsignal)
-- [Futurable.all](#futurableallvalues-t-signal-abortsignal)
-- [Futurable.allSettled](#futurableallsettledvalues-t-signal-abortsignal)
-- [Futurable.any](#futurableanyvalues-t-signal-abortsignal)
-- [Futurable.race](#futurableracevalues-t-signal-abortsignal)
-- [Futurable.polling](#futurablepollingvalue--futurable--interval-signal-immediate-interval-number-signal-abortsignal-immediate-boolean)
-- [Futurable.withResolvers](#futurablewithresolverssignal-abortsignal)
-
-### constructor(executor: FuturableExecutor<T>, signal?: AbortSignal)
-Futurable is instantiable like a classic Promise.
-```javascript
-//Javascript Promise
-
-const promise = new Promise((resolve, reject) => {
-	const data = /*..async operations or other..*/
-	resolve(data);
-});
+Together, they provide everything you need to write **robust, maintainable, production-ready async code**.
 
-//Futurable
-import { Futurable } from '@ndriadev/futurable';
+---
 
-const futurable = new Futurable((resolve, reject) => {
-	const data = /*..async operations or other..*/
-	resolve(data);
-});
-```
-But it provides two more statements:
+## 📖 What is Futurable?
 
-1. Its constructor can receive a second parameter *signal*, an *AbortSignal*, usable to cancel the promise from the outside.
+### Futurable: Cancellable Promises
 
-```javascript
-const controller = new AbortController();
+`Futurable` extends the native Promise API with built-in cancellation support. It's a **drop-in replacement** for Promise that solves the resource management problem.
 
-const futurable = new Futurable((resolve, reject) => {
-	const data = /*..async operations or other..*/
-	resolve(data);
-}, controller.signal);
-```
+**The core insight:** When you navigate away from a page, close a modal, or change a filter, you don't just want to ignore pending operations—you want to **actively stop** them and **clean up resources**.
 
-2. The executor function passed to the promise receives a third parameter, *utils*, optional.
+```typescript
+import { Futurable } from '@ndriadev/futurable';
 
-```javascript
-const controller = new AbortController();
+// Create a cancellable fetch request
+const request = Futurable.fetch('https://api.example.com/data')
+  .then(res => res.json())
+  .then(data => console.log(data));
 
-const futurable = new Futurable((resolve, reject, utils) => {
-	const data = /*..async operations or other..*/
-	resolve(data);
-});
+// User navigates away? Cancel it.
+request.cancel();
 ```
-Utils is an object with the following properties which mirror the methods described in the usage section and which will be described below:
-- cancel;
-- onCancel:
-- delay;
-- sleep;
-- fetch;
-- futurizable.
-
-In addition is has:
-- signal: internal futurable signal;
-
-### cancel(): void
-If invoked, it cancel the futurable if it is to be executed or if it is still executing.
-
-*Example*
-```javascript
-function asynchronousOperation() {
-	return new Futurable((res, rej) => {
-		// asynchornous code..
-		resolve(true);
-	});
-);
 
-//...code
+**Why this matters:**
 
-const futurable = asynchronousOperation();
-	futurable.then(value => {
-	//DO anything
-});
+- **Memory leaks**: Prevented by cancelling pending operations
+- **Race conditions**: Eliminated by cancelling stale requests
+- **Resource management**: WebSocket connections, timers, and event listeners properly cleaned up
+- **User experience**: No more stale data updates after navigation
 
-//...code
+#### When to use Futurable
 
-futurable.cancel();
-```
+Use `Futurable` when you need **immediate execution** with cancellation support:
 
-### onCancel(cb: callback): void
-If it is invoked, when the futurable is cancelled, it executes the callback passed as a parameter.
+- React/Vue component effects that need cleanup
+- API requests that should be cancellable
+- Any Promise-based code where you might need to cancel
+- Drop-in replacement for existing Promise code
 
-*Example*
-```javascript
-const futurable = new Futurable((resolve, reject, utils) => {
-	utils.onCancel(() => console.log("Futurable cancelled"));
-	const data = /*..async operations or other..*/
-	resolve(data);
-});
+---
 
-//...code
+## 🎯 What is FuturableTask?
 
-futurable.cancel();
+### FuturableTask: Lazy Async Composition
 
-//OR
+`FuturableTask` represents a **blueprint** for async work—it doesn't execute until you explicitly run it. Think of it as a recipe: you write it once, then bake it multiple times with different ingredients.
 
-const futurable = new Futurable((res, rej) => {
-	// asynchornous code..
-	resolve(true);
-});
+**The core insight:** Many async operations benefit from **lazy evaluation**—separating the definition of work from its execution enables powerful patterns like retry, memoization, and functional composition.
 
-//...code
+```typescript
+import { FuturableTask } from '@ndriadev/futurable';
 
-futurable
-.onCancel(() => console.log("Futurable cancelled"))
-.then(val => .......);
+// Define the work (doesn't execute yet)
+const fetchUser = FuturableTask
+  .fetch('/api/user')
+  .map(res => res.json())
+  .filter(user => user.active)
+  .retry(3)
+  .timeout(5000)
+  .memoize();
 
-//...code
+// Execute when needed
+const user = await fetchUser.run();
 
-futurable.cancel();
-```
-```bash
-Output: Futurable cancelled
+// Execute again (uses memoized result)
+const sameUser = await fetchUser.run();
 ```
 
-### sleep(timer: number): Futurable<T>
-Waits for timer parameter (in milliseconds) before returning the value.
+**Why this matters:**
 
-*Example*
-```javascript
-const futurable = new Futurable((resolve, reject, utils) => {
-	const data = /*..async operations or other..*/
-	utils.sleep(3000);
-	resolve(data);
-});
-//...code
+- **Reusability**: Define once, execute many times
+- **Composition**: Chain transformations before execution
+- **Testing**: Easy to test without execution
+- **Optimization**: Memoization, batching, and deduplication
+- **Declarative**: Describe what should happen, not when
 
-//OR
+#### When to use FuturableTask
 
-const futurable = new Futurable((res, rej) => {
-	// asynchornous code..
-	resolve(true);
-});
+Use `FuturableTask` when you need **lazy evaluation** with advanced composition:
 
-//...code
+- Building reusable async workflows
+- Complex pipelines with retry/timeout/fallback logic
+- Operations that should be memoized or deduplicated
+- Functional programming patterns in async code
+- Rate-limited or batched API calls
 
-futurable
-.sleep(3000)
-.then(val => .......);
+---
 
-//...code
-```
+## 🚀 Core Capabilities
 
-### delay(cb: callback, timer: number)
-Waits for timer parameter (in milliseconds), then executes callback with the futurable value and returns the result obtained from the invocation. Callback parameter, when delay is invoked as class method, has the value of futurable, like then method.
+### For Futurable
 
-*Example*
-```javascript
-const futurable = new Futurable((resolve, reject, utils) => {
-	const data = /*..async operations or other..*/
-	utils.delay(()=>console.log("delayed"), 3000);
-	resolve(data);
-});
+#### Cancellation
 
-//...code
+Stop operations and clean up resources:
 
-//OR
+```typescript
+const request = Futurable.fetch('/api/data')
+  .then(res => res.json())
+  .onCancel(() => {
+    console.log('Cleanup: close connections, clear timers');
+  });
 
-const futurable = new Futurable((res, rej) => {
-	// asynchornous code..
-	resolve(true);
-});
+// Cancel anytime
+request.cancel();
+```
+
+#### Built-in Utilities
+
+Native support for common patterns:
 
-//...code
+```typescript
+// Sleep/delay
+await Futurable.sleep(1000);
 
-futurable
-.delay((val)=> {
-	console.log("delayed val", val);
-	return val;
-},3000)
-.then(val => .......);
+// Delayed execution
+const result = await new Futurable(resolve => {
+  resolve('value');
+}).delay(() => 'delayed', 2000);
 
-//...code
+// Polling
+const status = await Futurable.polling(
+  () => checkStatus(),
+  1000 // every second
+);
+
+// Cancellable fetch
+const data = await Futurable.fetch('/api/data')
+  .then(res => res.json());
 ```
 
-### fetch(url: string | (val => string), opts: object | RequestInit)
-Fetch API extension with cancellation support. Url parameter can be a string or a function with receive value from futurable chaining as paremeter.
+#### Safe Error Handling
 
-*Example*
-```javascript
-const futurable = new Futurable((resolve, reject, utils) => {
-	utils.fetch(/*string url to fetch..*/)
-	.then(val => resolve(val))
-});
+Handle errors without try-catch:
 
-//...code
+```typescript
+const result = await Futurable.fetch('/api/data')
+  .then(res => res.json())
+  .safe();
+
+if (result.success) {
+  console.log(result.data);
+} else {
+  console.error(result.error);
+}
+```
 
-//OR
+---
 
-const futurable = new Futurable((res, rej) => {
-	// asynchornous code..
-	resolve(true);
-});
+### For FuturableTask
 
-//...code
+#### Functional Composition
 
-futurable
-.fetch(/*url to fetch..*/)
-.then(val => .......);
+Build complex pipelines declaratively:
 
-//OR
-futurable
-.then(val => "https://...")
-.fetch((val /* val came from previous then*/) => ..., ..)
+```typescript
+const pipeline = FuturableTask
+  .fetch('/api/users')
+  .map(res => res.json())
+  .filter(users => users.length > 0)
+  .map(users => users.filter(u => u.active))
+  .map(users => users.sort((a, b) => a.name.localeCompare(b.name)))
+  .tap(users => console.log(`Found ${users.length} active users`));
 
-//...code
+const users = await pipeline.run();
 ```
 
-<!---
-### promisify()
-Transforms the futurable into a normal promise in order to be able to use the async/await syntax but keeping possibility to cancel futurable until its invocation.
+#### Error Recovery
 
-*Example*
-```javascript
-async function op() {
-	...
-	...
+Sophisticated error handling strategies:
 
-	await Futurable.sleep(3000).promisify();
-}
+```typescript
+const resilient = FuturableTask
+  .fetch('/api/data')
+  .retry(3, {
+    delay: 1000,
+    backoff: 2  // exponential backoff
+  })
+  .timeout(5000)
+  .orElse(() => FuturableTask.fetch('/api/backup'))
+  .fallbackTo(() => CACHED_DATA);
 ```
---->
-### futurizable(promise: Promise | (val => Promise))
-Takes a promise and transforms it into a futurable. Promise can be also a function that receives value from futurable chaining as parameter.
-
-*Example*
-```javascript
-const futurable = new Futurable((resolve, reject, utils) => {
-	utils.futurizable(new Promise(res => {
-		//asynchronous code
-		res(data);
-	}))
-	.then(val => resolve(val))
-});
 
-//...code
+#### Concurrency Control
 
-//OR
+Fine-grained control over parallel execution:
 
-const futurable = new Futurable((res, rej) => {
-	// asynchornous code..
-	resolve(true);
+```typescript
+// Limit concurrent requests
+const limiter = FuturableTask.createLimiter(5, {
+  onActive: () => console.log('Task started'),
+  onIdle: () => console.log('All done')
 });
 
-//...code
-
-futurable
-.futurizable(/*promise to futurizable*/)
-.then(val => .......);
-
-//OR
-futurable
-.then(val => 3)
-.futurizable((val /* val is 3 */) => new Promise(/*...*/) /*promise to futurizable*/, ..)
+const tasks = urls.map(url =>
+  limiter(FuturableTask.fetch(url))
+);
 
-//...code
+// Only 5 run at once
+const results = await FuturableTask.parallel(tasks).run();
 ```
 
-### Futurable.onCancel(cb: callback | {cb: callback, signal?: AbortSignal})
-OnCancel static method. It accepts a callback or a object with cb property and an optional signal.
+#### Debouncing
 
-*Example*
-```javascript
-const controller = new AbortController();
+Automatic debouncing for user input:
 
-//...code
-Futurable.onCancel({
-	cb: ()=>console.log("Cancelled"),
-	signal: controller.signal
-});
-//...code
+```typescript
+const search = FuturableTask
+  .of((query: string) => searchAPI(query))
+  .debounce(300);
+
+// Rapid calls - only last executes
+search.run('a');   // cancelled
+search.run('ab');  // cancelled
+search.run('abc'); // executes after 300ms
 ```
 
-### Futurable.sleep(timer: number | {timer: number, signal?: AbortSignal})
-Sleep static method. It accepts a timer or a object with timer property and an optional signal.
+#### Memoization
 
-*Example*
-```javascript
-//...code
+Cache expensive operations:
 
-Futurable.sleep({
-	timer: 3000,
-	signal: signal
-});
+```typescript
+const loadConfig = FuturableTask
+  .fetch('/api/config')
+  .map(res => res.json())
+  .memoize();
 
-//...code
+const config1 = await loadConfig.run(); // Fetches
+const config2 = await loadConfig.run(); // Cached
+const config3 = await loadConfig.run(); // Cached
 ```
 
-### Futurable.delay({cb: callback, timer: number, signal?: AbortSignal})
-Delay static method. It accepts a object with timer and cb properties and an optional signal property.
+---
 
-*Example*
-```javascript
-const controller = new AbortController();
-//...code
+## 💡 Real-World Examples
 
-Futurable.delay({
-	cb: ()=>console.log("Cancelled"),
-	timer: 3000
-});
-
-//...code
-```
+### React Component with Cleanup
 
-### Futurable.fetch(url: string, opts: object | RequestInit)
-Fetch static method.
+```typescript
+import { useEffect, useState } from 'react';
+import { Futurable } from '@ndriadev/futurable';
 
-*Example*
-```javascript
-//...code
+function UserProfile({ userId }) {
+  const [user, setUser] = useState(null);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    setLoading(true);
+
+    const request = Futurable
+      .fetch(`/api/users/${userId}`)
+      .then(res => res.json())
+      .then(data => {
+        setUser(data);
+        setLoading(false);
+      })
+      .catch(error => {
+        if (error.name !== 'AbortError') {
+          console.error(error);
+        }
+        setLoading(false);
+      });
 
-Futurable.fetch(/*url string..*/, {method: "POST"});
+    // Cleanup on unmount or userId change
+    return () => request.cancel();
+  }, [userId]);
 
-//...code
+  if (loading) return <div>Loading...</div>;
+  return <div>{user?.name}</div>;
+}
 ```
 
-### Futurable.futurizable({promise: Promise, signal: AbortSignal})
-Futurizable static method.
+### Reusable API Client
+
+```typescript
+class APIClient {
+  private baseURL = 'https://api.example.com';
+
+  // Reusable task definitions
+  fetchUser = (id: number) =>
+    FuturableTask
+      .fetch(`${this.baseURL}/users/${id}`)
+      .map(res => res.json())
+      .retry(3)
+      .timeout(5000)
+      .memoize();
+
+  searchUsers = (query: string) =>
+    FuturableTask
+      .fetch(`${this.baseURL}/users/search?q=${query}`)
+      .map(res => res.json())
+      .debounce(300)
+      .timeout(10000);
+
+  // Execute when needed
+  async getUser(id: number) {
+    return this.fetchUser(id).run();
+  }
+
+  async search(query: string) {
+    return this.searchUsers(query).run();
+  }
+}
+```
 
-*Example*
-```javascript
-const controller = new AbortController();
-//...code
+### Complex Data Pipeline
+
+```typescript
+const processData = FuturableTask
+  .fetch('/api/raw-data')
+  .map(res => res.json())
+  .tap(data => console.log(`Received ${data.length} items`))
+  .filter(data => data.length > 0, 'No data available')
+  .map(data => data.map(item => ({
+    ...item,
+    processed: true,
+    timestamp: Date.now()
+  })))
+  .flatMap(data =>
+    FuturableTask.traverse(
+      data,
+      item => FuturableTask.of(() => enrichItem(item))
+    )
+  )
+  .tap(results => console.log(`Processed ${results.length} items`))
+  .retry(2, { delay: 1000 })
+  .timeout(30000)
+  .fallbackTo(error => {
+    console.error('Pipeline failed:', error);
+    return [];
+  });
+
+const results = await processData.run();
+```
 
-Futurable.futurizable({promise: /*promise to futurizable*/, signal: controller.signal});
+### Rate-Limited Batch Processing
+
+```typescript
+async function processLargeDataset(items: Item[]) {
+  // Create limiter (max 10 concurrent)
+  const limiter = FuturableTask.createLimiter(10, {
+    onActive: () => console.log(`Active: ${limiter.activeCount}/10`),
+    onCompleted: (result) => updateProgress(result),
+    onIdle: () => console.log('Batch complete')
+  });
+
+  // Process in batches of 50
+  const batches = chunk(items, 50);
+
+  const results = await FuturableTask.sequence(
+    batches.map(batch =>
+      FuturableTask.parallel(
+        batch.map(item =>
+          limiter(
+            FuturableTask
+              .of(() => processItem(item))
+              .retry(3)
+              .timeout(5000)
+          )
+        )
+      )
+    )
+  ).run();
 
-//...code
+  return results.flat();
+}
 ```
 
-### Futurable.all(values: T, signal?: AbortSignal)
-Extension of the static method _all_ with cancellation support.
+---
 
-*Example*
-```javascript
-const controller = new AbortController();
+## 🎨 Design Philosophy
 
-//...code
+### 1. Progressive Enhancement
 
-Futurable.all([
-	1,
-	Futurable.resolve(true, controlles.signal),
-	new Futurable/*...*/
-], controller.signal);
+Start simple, add complexity only when needed:
 
-//...code
+```typescript
+// Simple
+const data = await Futurable.fetch('/api/data')
+  .then(res => res.json());
 
-controller.abort();
+// Add cancellation
+const request = Futurable.fetch('/api/data')
+  .then(res => res.json());
+request.cancel();
 
-//OR
+// Add retry and timeout
+const resilient = FuturableTask
+  .fetch('/api/data')
+  .map(res => res.json())
+  .retry(3)
+  .timeout(5000);
+```
 
-const f = Futurable.all([
-	1,
-	Futurable.resolve(true),
-	new Futurable/*...*/
-]
+### 2. Type Safety First
 
-//...code
+Full TypeScript support with inference:
 
-f.cancel();
+```typescript
+const result = await FuturableTask
+  .of(() => 42)                    // FuturableTask<number>
+  .map(x => x.toString())          // FuturableTask<string>
+  .filter(s => s.length > 0)       // FuturableTask<string>
+  .run();                          // Promise<string>
 ```
 
-### Futurable.allSettled(values: T, signal?: AbortSignal)
-Extension of the static method _allSettled_ with cancellation support.
-
-*Example*
-```javascript
-const controller = new AbortController();
+### 3. Zero Dependencies
 
-//...code
+No external dependencies. Small bundle size. Tree-shakeable.
 
-Futurable.allSettled([
-	1,
-	Futurable.resolve(true, controller.signal),
-	new Futurable/*...*/
-], controller.signal);
+### 4. Promise Compatible
 
-//...code
+`Futurable` **is** a Promise. Works with `async/await`, `Promise.all()`, and any Promise-based API.
 
-controller.abort();
+---
 
-//OR
+## 📦 Installation
 
-const f = Futurable.allSettled([
-	1,
-	Futurable.resolve(true),
-	new Futurable/*...*/
-];
+```bash
+npm install @ndriadev/futurable
+```
 
-//...code
+```bash
+yarn add @ndriadev/futurable
+```
 
-f.cancel();
+```bash
+pnpm add @ndriadev/futurable
 ```
 
-### Futurable.any(values: T, signal?: AbortSignal)
-Extension of the static method _any_ with cancellation support.
+---
 
-*Example*
-```javascript
-const controller = new AbortController();
-//...code
+## 🎯 Quick Start
 
-Futurable.any([
-	1,
-	Futurable.resolve(true, controller.signal),
-	new Futurable/*...*/
-], controller.signal);
+### Basic Futurable
+
+```typescript
+import { Futurable } from '@ndriadev/futurable';
 
-//...code
+// Cancellable fetch
+const request = Futurable.fetch('/api/data')
+  .then(res => res.json());
 
-controller.abort();
+request.cancel(); // Cancel if needed
+```
 
-//OR
+### Basic FuturableTask
 
-const f = Futurable.any([
-	1,
-	Futurable.resolve(true, controller.signal),
-	new Futurable/*...*/
-];
+```typescript
+import { FuturableTask } from '@ndriadev/futurable';
 
-//...code
+// Define work
+const task = FuturableTask
+  .of(() => fetch('/api/data'))
+  .map(res => res.json())
+  .retry(3);
 
-f.cancel();
+// Execute when ready
+const data = await task.run();
 ```
 
-### Futurable.race(values: T, signal?: AbortSignal)
-Extension of the static method _race_ with cancellation support.
+---
 
-*Example*
-```javascript
-const controller = new AbortController();
-//...code
+## 📚 Documentation
 
-Futurable.race([
-	1,
-	Futurable.resolve(true, controller.signal),
-	new Futurable/*...*/
-], controller.signal);
+📖 **[Complete Documentation](https://futurable.ndria.dev/)**
 
-//...code
+- [Getting Started Guide](https://futurable.ndria.dev/guide/getting-started)
+- [Futurable API Reference](https://futurable.ndria.dev/api/constructor)
+- [FuturableTask Guide](https://futurable.ndria.dev/guide-task/introduction)
+- [Examples & Patterns](https://futurable.ndria.dev/examples/)
 
-controller.abort();
+---
 
-//OR
+## 🌟 Key Features
 
-const f = Futurable.race([
-	1,
-	Futurable.resolve(true, controller.signal),
-	new Futurable/*...*/
-];
+### Futurable
 
-//...code
+| Feature | Description |
+|---------|-------------|
+| ✅ **Cancellation** | Cancel operations and cleanup resources |
+| ✅ **Promise Compatible** | Drop-in Promise replacement |
+| ✅ **Built-in Fetch** | Cancellable HTTP requests |
+| ✅ **Delays & Sleep** | Timing utilities |
+| ✅ **Polling** | Repeated execution with cancellation |
+| ✅ **Safe Mode** | Error handling without try-catch |
+| ✅ **Full TypeScript** | Complete type safety |
 
-f.cancel();
-```
+### FuturableTask
 
-### Futurable.polling<T>(value: ()=> Futurable<T>, { interval, signal, immediate }:{interval: number, signal?: AbortSignal, immediate?: boolean})
-Creates a polling service with cancellation support and possibility to handle error. An optional param __immediate__ can be set _true_ if __fun__ must to be invoke immediatly.
+| Feature | Description |
+|---------|-------------|
+| ✅ **Lazy Evaluation** | Define once, execute when needed |
+| ✅ **Reusability** | Run the same task multiple times |
+| ✅ **Functional Composition** | map, filter, flatMap, tap, and more |
+| ✅ **Retry Logic** | Exponential backoff and conditional retry |
+| ✅ **Timeout Protection** | Automatic timeouts |
+| ✅ **Error Recovery** | Fallbacks and error handling |
+| ✅ **Concurrency Control** | Rate limiting and parallelism |
+| ✅ **Debouncing** | Built-in debouncing |
+| ✅ **Memoization** | Cache expensive operations |
+| ✅ **Full TypeScript** | Complete type inference |
 
-*Example*
-```javascript
-//...code
-const polling = Futurable.polling(() => Futurable.fetch(/*...*/)), {interval: 1000});
-polling.catch(err => console.error(err));
+---
 
-//...code
+## 🎯 Use Cases
 
-polling.cancel();
-```
+### Perfect For
 
-### Futurable.withResolvers<T>(signal?: AbortSignal)
-Extension of static method _withResolvers_ with support of _cancel_ function and _utils_ object of Futurable.
+- **SPA Applications**: Cancel API calls on navigation
+- **React/Vue/Angular**: Component cleanup and effects
+- **Real-time Features**: Polling with cancellation
+- **Data Processing**: Complex async pipelines
+- **API Clients**: Reusable, composable requests
+- **Rate Limiting**: Control concurrent operations
+- **Form Handling**: Debounced search and auto-save
+- **Resource Management**: Proper async cleanup
 
-*Example*
-```javascript
-//...code
-const {promise, resolve, reject} = Futurable.withResolvers();
+---
 
-//...code
+## 🌐 Browser & Node.js Support
 
-const result = await promise;
+- ✅ All modern browsers (Chrome, Firefox, Safari, Edge)
+- ✅ Node.js 14+
+- ✅ TypeScript 4.5+
+- ✅ ES2015+ (ES6+)
 
-//...code
-resolve("resolved");
-```
+---
+
+## 📄 License
 
+[MIT](LICENSE) © [nDriaDev](https://github.com/nDriaDev)
 
-#  ToDo
-- Extends fetch api support to third library like axios.
-- Implement promise cache.
+---
 
+## 🙏 Acknowledgments
 
-## License
+Futurable draws inspiration from:
+- **Promises/A+** specification
+- **RxJS** observables and operators
+- **Fluture** and functional programming patterns
+- Real-world production challenges in modern web apps
 
+---
+
+## 📞 Support
+
+- **Documentation**: [futurable.ndria.dev](https://futurable.ndria.dev/)
+- **Issues**: [GitHub Issues](https://github.com/nDriaDev/futurable/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/nDriaDev/futurable/discussions)
+- **Email**: info@ndria.dev
+
+---
+
+<div align="center">
 
+**If you find Futurable useful, please consider giving it a ⭐ on [GitHub](https://github.com/nDriaDev/futurable)!**
 
-Futurable is licensed under a [MIT License](./LICENSE).
+</div>