# @matrixai/async-init

> Asynchronous Initialisation and Deinitialisation Decorators

Latest version **2.1.2** (published 2025-02-04) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @matrixai/async-init
pnpm add @matrixai/async-init
yarn add @matrixai/async-init
bun add @matrixai/async-init
```

## Health

**Score 30/100 (F)** — status: maintenance-mode.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.1.2 |
| Published | 2025-02-04 |
| First published | 2021-09-30 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | none |
| Module format | ESM |
| Dependencies | 3 |
| Unpacked size | 81.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Roger Qiu |
| Maintainers | brianbotha74, cmcdragonkai, matrixai-bot |

## Links

- npm: https://www.npmjs.com/package/@matrixai/async-init
- Repository: https://github.com/MatrixAI/js-async-init
- Homepage: https://github.com/MatrixAI/js-async-init#readme
- Issues: https://github.com/MatrixAI/js-async-init/issues
- npm.io page: https://npm.io/package/@matrixai/async-init

## Dependencies (3)

- [@matrixai/errors](https://npm.io/package/@matrixai/errors.md) ^2.1.0
- [@matrixai/events](https://npm.io/package/@matrixai/events.md) ^4.0.0
- [@matrixai/async-locks](https://npm.io/package/@matrixai/async-locks.md) ^5.0.1

## Recent versions

- 2.1.2 (latest) — 2025-02-04
- 3.0.0-rc.2 (prerelease) — 2026-06-06
- 3.0.0-rc.1 — 2026-06-06
- 3.0.0-rc.0 — 2026-06-03
- 2.1.0 — 2024-05-14
- 1.10.0 — 2023-09-21
- 1.9.4 — 2023-09-20
- 1.9.2 — 2023-09-19
- 1.9.1 — 2023-09-03
- 2.0.0 — 2023-08-13
- 1.8.4 — 2023-06-23
- 1.8.3 — 2023-06-04
- 1.8.2 — 2022-07-25
- 1.8.1 — 2022-06-23
- 1.8.0 — 2022-06-22
- … 14 more at https://npm.io/package/@matrixai/async-init/versions

## README

# js-async-init

Asynchronous initialization and deinitialization decorators for JavaScript/TypeScript applications.

Because decorators are experimental, you must enable: `"experimentalDecorators": true` in your `tsconfig.json` to use this library.

TypeScript does not allow decorator properties that are protected or private.

Example Usage:

```ts
import { CreateDestroyStartStop, ready } from '@matrixai/async-init/dist/CreateDestroyStartStop';

// this hack is necessary to ensure that X's type is decorated
interface X extends CreateDestroyStartStop {};
@CreateDestroyStartStop(new Error('Running'), new Error('Destroyed'))
class X {
  protected y: Y;

  public static async createX(
    {
      y
    }: {
      y?: Y
    } = {}
  ) {
    y = y ?? await Y.createY();
    const x = new this({ y });
    await x.start();
    return x;
  }

  public constructor ({ y }: { y: Y }) {
    this.y = y;
  }

  public async start(): Promise<void> {
    await this.y.start();
    console.log('X started');
  }

  public async stop(): Promise<void> {
    await this.y.stop();
    console.log('X stopped');
  }

  public async destroy(): Promise<void> {
    await this.y.destroy();
    console.log('X destroyed');
  }

  @ready(new Error('Not Running'))
  public async doSomething() {
    await this.y.doSomething();
    console.log('X did something');
  }
}

// this hack is necessary to ensure that Y's type is decorated
interface Y extends CreateDestroyStartStop {};
@CreateDestroyStartStop(new Error('Running'), new Error('Destroyed'))
class Y {
  public static async createY() {
    return new this();
  }

  public constructor () {
  }

  public async destroy(): Promise<void> {
    console.log('Y destroyed');
  }

  @ready(new Error('Not Running'))
  public async doSomething(): Promise<void> {
    console.log('Y did something');
  }
}

async function main () {
  const x = await X.createX();
  await x.doSomething();
  await x.stop();
  await x.destroy();
  console.log(x);
}

main();
```

The `start`, `stop`, and `destroy` calls are all concurrent-controlled with `RWLockWriter`. They are idempotent and they are mutually exclusive between each other and any blocking `ready` decorated methods. Decorated methods can block `start`, `stop`, and `destroy`, but share a read lock between each other.

Refer to https://gist.github.com/CMCDragonkai/1dbf5069d9efc11585c27cc774271584 for further the motivation of this library.

## Installation

```sh
npm install --save @matrixai/async-init
```

## Development

Run `nix develop`, and once you're inside, you can use:

```sh
# install (or reinstall packages from package.json)
npm install
# build the dist
npm run build
# run the repl (this allows you to import from ./src)
npm run tsx
# run the tests
npm run test
# lint the source code
npm run lint
# automatically fix the source
npm run lintfix
```

### Docs Generation

```sh
npm run docs
```

See the docs at: https://matrixai.github.io/js-async-init/

### Publishing

Publishing is handled automatically by the staging pipeline.

Prerelease:

```sh
# npm login
npm version prepatch --preid alpha # premajor/preminor/prepatch
git push --follow-tags
```

Release:

```sh
# npm login
npm version patch # major/minor/patch
git push --follow-tags
```

Manually:

```sh
# npm login
npm version patch # major/minor/patch
npm run build
npm publish --access public
git push
git push --tags
```

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