# simple-async-tasks

> A simple in-memory queue, for nodejs and the browser, with consumers for common usecases.

Latest version **1.9.0** (published 2024-12-27) · MIT license · 0 weekly downloads

## Install

```sh
npm install simple-async-tasks
pnpm add simple-async-tasks
yarn add simple-async-tasks
bun add simple-async-tasks
```

## Health

**Score 35/100 (D)** — status: maintenance-mode.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.9.0 |
| Published | 2024-12-27 |
| First published | 2023-07-16 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=8.0.0 |
| Dependencies | 7 |
| Unpacked size | 88.3 KB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | yes |
| GitHub stars | 0 |
| Author | ehmpathy |
| Maintainers | uladkasach |
| Keywords | simple, async, tasks, async task, async tasks, execute, queue |

## Links

- npm: https://www.npmjs.com/package/simple-async-tasks
- Repository: https://github.com/ehmpathy/simple-async-tasks
- Issues: https://github.com/ehmpathy/simple-async-tasks/issues
- npm.io page: https://npm.io/package/simple-async-tasks

## Dependencies (7)

- [uuid](https://npm.io/package/uuid.md) 9.0.0
- [date-fns](https://npm.io/package/date-fns.md) 2.30.0
- [visualogic](https://npm.io/package/visualogic.md) 1.3.2
- [change-case](https://npm.io/package/change-case.md) 4.1.2
- [@ehmpathy/uni-time](https://npm.io/package/@ehmpathy/uni-time.md) 1.4.2
- [@ehmpathy/error-fns](https://npm.io/package/@ehmpathy/error-fns.md) 1.3.0
- [simple-in-memory-queue](https://npm.io/package/simple-in-memory-queue.md) 1.1.7

## Alternatives

- [cron](https://npm.io/package/cron.md) — 4.9M weekly downloads
- [@vercel/queue](https://npm.io/package/@vercel/queue.md) — 731.6K weekly downloads
- [create-sonicjs](https://npm.io/package/create-sonicjs.md) — 1.6K weekly downloads
- [@exellix/jobs-api](https://npm.io/package/@exellix/jobs-api.md) — 941 weekly downloads
- [@forwardimpact/libskill](https://npm.io/package/@forwardimpact/libskill.md) — 575 weekly downloads

## Recent versions

- 1.9.0 (latest) — 2024-12-27
- 1.8.0 — 2024-08-19
- 1.7.2 — 2024-08-06
- 1.7.1 — 2024-08-01
- 1.5.0 — 2024-07-06
- 1.4.4 — 2024-06-29
- 1.4.3 — 2024-06-14
- 1.4.2 — 2024-06-07
- 1.4.1 — 2024-05-28
- 1.3.5 — 2024-05-17
- 1.3.4 — 2024-05-14
- 1.3.3 — 2024-05-14
- 1.3.2 — 2024-04-20
- 1.3.1 — 2024-03-15
- 1.2.0 — 2024-03-15
- … 3 more at https://npm.io/package/simple-async-tasks/versions

## README

# simple-async-tasks

easily create and use async-tasks within a pit-of-success

# install

```
npm install simple-async-tasks
```

# use

### define your async task

define the domain object of the async task you want to be able to run

```ts
import { DomainEntity } from 'domain-objects';
import { AsyncTask, AsyncTaskStatus } from 'simple-async-tasks';

/**
 * for example: an async task for emitting some data to remote persistance
 */
export interface AsyncTaskEmitToRemote extends AsyncTask {
  uuid?: string;
  updatedAt?: string;
  status: AsyncTaskStatus;

  /**
   * the endpoint to emit the data to
   */
  endpoint: string;

  /**
   * the payload to emit
   *
   * note
   * - supports string and binary buffer
   */
  payload: string | Buffer;
}
export class AsyncTaskEmitToRemote
  extends DomainEntity<AsyncTaskEmitToRemote>
  implements AsyncTaskEmitToRemote
{
  public static unique = ['endpoint', 'payload'];
}
```

### define your dao

define the database-access-object we can use to persist this async-task

usually, you should be using a library to code-generate or instantiate the dao for you
  - e.g., [sql-dao-generator](https://github.com/ehmpathy/sql-dao-generator)
  - e.g., [dynamodb-dao-generator](https://github.com/ehmpathy/dynamodb-dao-generator)
  - e.g., [cache-dao-generator](https://github.com/ehmpathy/simple-cache-dao)

for example
```ts
import { createCacheDao } from 'simple-cache-dao';
import { createCache } from 'simple-in-memory-cache';

const daoTaskEmitToRemote = createCacheDao({ cache: createCache() })
```

### define how to queue

define how to queue your task for execution

```ts
import { createQueue, QueueOrder } from 'simple-in-memory-queue';

// TODO: load all queued tasks from db on page load
export const asyncTaskEmitToRemoteQueue = createQueue<AsyncTaskEmitToRemote>({
  order: QueueOrder.FIRST_IN_FIRST_OUT,
});

export const queueTaskEmitToRemote = withAsyncTaskExecutionLifecycleQueue({
  dao: daoTaskEmitToRemote,
  queue: asyncTaskEmitToRemoteQueue,
  getNew: ({ endpoint, payload }) =>
    new AsyncTaskEmitToRemote({
      status: AsyncTaskStatus.QUEUED,
      endpoint,
      payload,
    }),
});
```

### define how to execute

define how to execute your async task

```ts
export const executeTaskEmitToRemote = withAsyncTaskExecutionLifecycleExecute(
  async ({ task }: { task: HasMetadata<AsyncTaskEmitToRemote> }) => {
    // execute your logic

    // mark it as fulfilled
    await daoTaskEmitToRemote.upsert({ task: { ...task, status: AsyncTaskStatus.FULFILLED }})
  },
  {
    dao: daoTaskEmitToRemote,
  },
);
```

***⚠️ note: you must change the status of the task away from attempted by the time the execute function resolves to some non-attempted , otherwise it will be considered a failure***

### define the execution trigger

define the trigger that will consume from your queue and invoke the execute function

note
- this will vary based on which queue implementation you use
- for example,
  - if using aws.sqs, you will probably invoke an aws.lambda with an [aws.event-source-mapping](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/lambda_event_source_mapping)
  - if using a simple-in-memory-queue, you may choose to use a [resilient remote consumer](https://github.com/ehmpathy/simple-in-memory-queue#resilient-remote-consumer)

---
_Source: https://npm.io/package/simple-async-tasks · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._