@jonloucks/concurrency-ts

Badges

A TypeScript library that provides powerful abstractions for managing asynchronous concurrency, state machines, and completion patterns. It offers type-safe primitives for building concurrent applications with guaranteed completion semantics.

Key Features

• Type-safe concurrency primitives - Fully typed interfaces for concurrent operations
• Waitable references - Thread-safe mutable references that allow waiting for condition changes
• Completables - Observe activities from start to finish with guaranteed completion
• State machines - User-defined states with transition rules and validation
• Guaranteed execution - Patterns ensuring completion callbacks are always invoked
• Resource management - Automatic cleanup via the Open interface

Documentation

• Complete Documentation - Comprehensive guide with examples
• License
• Contributing
• Code of conduct
• Coding standards
• Security policy
• Pull request template
• How to use API
• Test coverage report

Installation

npm install @jonloucks/concurrency-ts

Usage

For comprehensive examples and detailed API documentation, see DOCUMENTATION.md.

Quick Start

import { createConcurrency, Waitable, Completable, StateMachine } from '@jonloucks/concurrency-ts';

// Create a Concurrency instance
const concurrency = createConcurrency({});
using closeConcurrency = concurrency.open();

// Create a Waitable for thread-safe value storage
const waitable: Waitable<number> = concurrency.createWaitable({ initialValue: 0 });
using closeWaitable = waitable.open();

waitable.consume(42);
console.log(waitable.supply()); // 42

// Create a Completable to track async operations
const completable: Completable<string> = concurrency.createCompletable({});
using closeCompletable = completable.open();

completable.onCompletion((completion) => {
  console.log('Task completed:', completion.state, completion.value);
});

completable.notify({ state: 'SUCCEEDED', value: 'Done!' });

// Create a StateMachine for state management
type AppState = 'IDLE' | 'RUNNING' | 'STOPPED';

const stateMachine: StateMachine<AppState> = concurrency.createStateMachine({
  initialValue: 'IDLE',
  states: ['IDLE', 'RUNNING', 'STOPPED'],
  getStateRules: (state) => {
    switch (state) {
      case 'IDLE':
        return [{ event: 'start', allowedStates: ['RUNNING'] }];
      case 'RUNNING':
        return [{ event: 'stop', allowedStates: ['STOPPED'] }];
      default:
        return [];
    }
  }
});

using closeStateMachine = stateMachine.open();

console.log(stateMachine.getState()); // 'IDLE'
stateMachine.setState('start', 'RUNNING');
console.log(stateMachine.getState()); // 'RUNNING'

See DOCUMENTATION.md for more examples and advanced usage patterns.

Development

Install dependencies

npm install

Build the project

npm run build

Run tests

npm test

Run tests in watch mode

npm run test:watch

Run test coverage

npm run test:coverage

Lint the code

npm run lint

Fix linting issues

npm run lint:fix

Generate documents

npm run docs

Generate badges

npm run badges

Project Structure

• All tests must have suffix of -test.ts or -spec.ts
• Tests that validate supported APIs go in src/test
• Tests that validate internal implementation details go in src/impl

concurrency-ts
├── .github
│   ├── ISSUE_TEMPLATE
│   │   ├── bug_report.md
│   │   └── feature_request.md
│   └── workflows
│       ├── main-pull-request-matrix.yml
│       ├── main-pull-request.yml
│       ├── main-push.yml
│       └── main-release.yml
├── CODE_OF_CONDUCT.md
├── CODING_STANDARDS.md
├── CONTRIBUTING.md
├── editorconfig
├── eslint.config.mjs
├── jest.config.js
├── LICENSE
├── package-lock.json
├── package.json
├── PULL_REQUEST_TEMPLATE.md
├── README.md
├── scripts
│   ├── badge-template.svg.dat
│   └── tsconfig.json
├── SECURITY.md
├── src
│   ├── index.ts
│   ├── version.ts
│   ├── api
│   │   ├── *.ts
│   │   ├── *.api.ts
│   ├── auxiliary
│   │   ├── *.ts
│   │   ├── *.impl.ts
│   │   ├── *.test.ts    // internal implementation specific
│   │   └── *.api.ts
│   ├── impl
│   │   ├── *.ts
│   │   ├── *.impl.ts
│   │   ├── *.test.ts    // internal implementation specific
│   │   └── *.api.ts
│   ├── test
│   │   └── *.test.ts
│   └── never-publish             // non shippable development scripts
│       ├── *.ts
│       ├── *.*.                  // data files etc
│       └── *.test.ts
├── tsconfig.json
└── typedoc.json

GitHub Workflows

CI Workflow

The CI workflow runs on every push and pull request to main branch. It:

• Tests against Node.js versions 18.x, 20.x, and 22.x
• Runs linting
• Builds the project
• Runs tests with coverage
• Uploads coverage to Codecov (optional)

Publish Workflow

The GitHub publishings workflows are run to make an official release.

• If all scanning and tests pass it is published. There is no other way allowed.
• Publishing authentication is done using (OIDC trusted publishing)

To set up your own publishing:

1. Publishing this project as is intentionally disabled
2. You are welcome to fork this repository and publish where you want.
3. Run npm pkg delete private to remove the private flag from the package.
4. Change the name field in package.json to your desired package name.

License

MIT