WorkIt

WorkIt is a TypeScript structured concurrency runtime for Node.js server runtimes.

WorkIt owns related async work through scope, cancellation, cleanup, context, events, and child task lifecycles.

Install

npm install @workit/core

import { run, work } from "@workit/core";

WorkIt is Apache-2.0 licensed. Contributions are welcome through issues and pull requests; please follow CONTRIBUTING.md and CODE_OF_CONDUCT.md.

Live examples: https://workruntime.github.io/workit/

npm package: https://www.npmjs.com/package/@workit/core

Changelog: CHANGELOG.md

Versioning

WorkIt follows semver with a stricter release discipline:

• Patch releases, such as 0.1.x, are for fixes, build/release hardening, layout migrations, documentation, and evidence updates. They must not add new public runtime APIs.
• Minor releases, such as 0.2.0, may add new subpaths or feature families when they are backed by tests, evidence, package-consumer checks, and documentation.
• The root @workit/core import remains size-disciplined. New heavier capabilities should live in subpaths or companion packages.
• 1.0.0 will mark a frozen public API and long-term compatibility policy, not a shortcut for credibility. Current 0.x releases are validated and usable, with changes managed through semver and release notes.

Citation

If you use WorkIt in research, benchmarks, or reproducible artifacts, please cite the software release you used:

@software{workit2026,
  author = {Admilson B. F. Cossa},
  title = {WorkIt: A TypeScript Structured Concurrency Runtime for Node.js Server Runtimes},
  year = {2026},
  url = {https://github.com/WorkRuntime/workit},
  version = {0.6.0},
  license = {Apache-2.0}
}

Repository Layout

This repository uses a monorepo layout. The published package contract is still owned by packages/core.

Path	Purpose
packages/core	Source, tests, samples, evidence, benchmarks, and release scripts for @workit/core.
apps/use-cases-site	GitHub Pages site with executable WorkIt examples.
articles	Public article drafts and released article materials.

Package Contract

The monorepo layout must not change how users install or import WorkIt.

Consumer paths in the 0.6.0 release candidate are listed below. The new candidate-policy subpath is not part of npm latest until the signed v0.6.0 tag and provenance-backed publish complete.

@workit/core
@workit/core/activity
@workit/core/ai
@workit/core/analysis
@workit/core/candidates
@workit/core/channel
@workit/core/contracts
@workit/core/diagnostics
@workit/core/fault
@workit/core/ledger
@workit/core/observability
@workit/core/otel
@workit/core/replay
@workit/core/resources
@workit/core/time-policy
@workit/core/worker

Verification

Run the core gates from the repository root:

npm run verify
npm run test:coverage
npm run check:size
npm run check:package-consumer

The 0.6.0 release candidate's candidate-policy subpath is documented in the @workit/core package README. It remains unavailable from npm latest until the release is published.

Run the site gates from the repository root:

npm run site:build