smartpromise/readme.md

# @push.rocks/smartpromise
simple promises and Deferred constructs

## Install

```bash
npm install @push.rocks/smartpromise --save
```

This module is designed to be used with TypeScript for the best developer experience, providing type safety and IntelliSense in your IDE.

## Usage

`@push.rocks/smartpromise` simplifies the use of promises and deferred constructs in TypeScript, offering a set of utility functions that extend native Promise capabilities in specific scenarios. This guide walks you through its functionalities, showcasing how to leverage this library in a TypeScript project.

### Setting Up Your Project

Ensure your TypeScript project is configured to support ES Module syntax. In your `tsconfig.json`, you should have:

```json
{
  "compilerOptions": {
    "module": "ESNext",
    "target": "ESNext",
    "moduleResolution": "node"
  }
}
```

### Basic Usage

#### Creating a Deferred

Deferred objects in `@push.rocks/smartpromise` give you more control over your promises, allowing for manual resolution or rejection beyond the initial executor function.

```typescript
import { defer } from '@push.rocks/smartpromise';

async function exampleDeferred(): Promise<string> {
  const myDeferred = defer<string>();

  // Simulate an async task
  setTimeout(() => {
    myDeferred.resolve('Hello, Deferred!');
  }, 1000);

  return myDeferred.promise;
}

exampleDeferred().then((result) => console.log(result));
```

#### Cumulative Deferred

For scenarios where multiple asynchronous tasks need to be tracked collectively before proceeding, use `CumulativeDeferred`. It waits for all added promises to resolve.

```typescript
import { cumulativeDefer } from '@push.rocks/smartpromise';

async function exampleCumulativeDeferred() {
  const myCumulativeDeferred = cumulativeDefer();

  for (let i = 0; i < 5; i++) {
    myCumulativeDeferred.addPromise(new Promise((resolve) => setTimeout(resolve, 1000 * i)));
  }

  await myCumulativeDeferred.promise;
  console.log('All tasks completed!');
}

exampleCumulativeDeferred();
```

#### Utilizing Resolved and Rejected Promises

Quickly create already resolved or rejected promises for testing or initialization purposes.

```typescript
import { resolvedPromise, rejectedPromise } from '@push.rocks/smartpromise';

resolvedPromise('immediately resolved').then(console.log);
rejectedPromise('immediately rejected').catch(console.error);
```

### Advanced Use Cases

#### Promisify Callback Functions

`@push.rocks/smartpromise` does not directly provide a `promisify` function like Node.js util module, but you can easily integrate existing functions or use third-party libraries to convert callback-based functions into promises.

#### Handling Timeouts and Continuations

Managing timeouts or long-running promises gets easier with helper functions.

```typescript
import { timeoutWrap, timeoutAndContinue } from '@push.rocks/smartpromise';

async function exampleTimeout() {
  const myPromise = new Promise((resolve) => setTimeout(() => resolve('Done!'), 2000));

  // Will reject if the promise does not resolve within 1 second
  try {
    const result = await timeoutWrap(myPromise, 1000);
    console.log(result);
  } catch (error) {
    console.error('Promise timed out');
  }

  // Continues after 1 second, regardless of whether the promise has resolved
  const result = await timeoutAndContinue(myPromise, 1000);
  console.log(result); // May log `null` if the original promise did not resolve in time
}

exampleTimeout();
```

#### Map and Reduce Asynchronous Functions

Suppose you have a collection of items that you need to process asynchronously. You can use the `map` function to apply an asynchronous function to each item in the array and wait for all the promises to resolve.

```typescript
import { map } from '@push.rocks/smartpromise';

async function processData(items: string[]): Promise<string[]> {
  return map(items, async (item) => {
    // Simulate an async operation
    await new Promise((resolve) => setTimeout(resolve, 100));
    return item.toUpperCase();
  });
}

processData(['hello', 'world']).then(console.log);
```

### Conclusion

`@push.rocks/smartpromise` offers a refined and accessible approach to handling promises and asynchronous operations in TypeScript. Whether you're dealing with individual promises, a group of asynchronous tasks, or integrating callback-based APIs into your promise flows, this library provides the necessary tools to make your code more readable and easier to manage. With straightforward utility functions and TypeScript support, it enhances the native Promise API, making it an essential tool for modern TypeScript development.

## License and Legal Information

This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. 

**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

### Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.

### Company Information

Task Venture Capital GmbH  
Registered at District court Bremen HRB 35230 HB, Germany

For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.