async-monitor.js

(pseudo code)
<script>
	const watches = new Group();
	watches.addWatch({
			parent: undefined,
			child: 'a',
			f: function_to_watch
		});
	...watches.addWatch();
	 console.log(watches.tree);
	watches.watchAll()
	   .then(()=>console.log('All went well!'))
	   .catch(()=>console.log('Oops, at least 1 promise was rejected!'));
</script>
<pre>
── preparation step
   ├─ fetch data from ETL store: s1, fetch data from ETL store: s2
   │  └─ build snowflake s1 and s2
   │     └─ publish snowflake s1 and s2 ───────────────────────────┐
   └─ fetch data from ETL store: s3                                │
      └─ build snowflake from s3                                   │
         └─ publish snowflake s3 ──────────────────────────────────┤
                                                                   └─ completed
</pre>

Examples

Features

A lightweight and efficient monitoring package designed to seamlessly track and manage hierarchically organized asynchronous JavaScript functions. Perfect for developers looking to streamline and gain insights into complex async workflows, numerous callback features at every step of execution, ensuring reliable performance and easy debugging.

Key Features

• Hierarchical function organization: Organize async functions in parent-child relationships
• Abort signal propagation: Automatically abort remaining functions when one fails (NEW in v1.2)
• Comprehensive monitoring: Track execution status, timing, and results
• Promise-based API: Built on modern async/await patterns
• Flexible callbacks: Hook into start, complete, reject, and abort events
• Repeatable execution: Support for running groups multiple times

New in v1.2

Abort Propagation: New abortOnReject, abortOnAbort, and propagateOnAbort options allow automatic abortion of remaining functions when one function fails or is manually aborted. Perfect for fast-fail scenarios and coordinated cancellation. See ABORT-PROPAGATION.md for details.

AI Assistant Quickstart

If you are using Copilot or another AI coding tool, include these details in your prompt so generated code uses this package correctly:

• Workflow shape: sequential, parallel, fan-out/fan-in, or nested groups
• Dependency stages: how parent and child values should connect
• Abort policy: none, abortOnReject, abortOnAbort, or both
• Repeat policy: one run or repeated runs (repeat)
• Callback expectations: which lifecycle callbacks should be present

Prompt recipe:

Build an async-monitor.js workflow for <use case>.
Environment: <node|browser>.
Workflow shape: <sequential|parallel|fan-out-fan-in|nested>.
Abort strategy: <none|abortOnReject|abortOnAbort|both>.
Repeat count: <number>.
Include callbacks: <onStart/onComplete/onReject/onAbort>.
Return runnable TypeScript using Group + addWatch + watchAll.

For tested behavior references and capability mapping, see:

• DEVELOPER-DOCUMENTATION.md
• ABORT-PROPAGATION.md
• WHATS-NEW.md
• AI-CAPABILITY-MAP.md

new in v1.1

The watchAll function is now an async function. This enhancement allows you to nest groups as needed and utilize then, catch, and finally for improved functionality and better control over your asynchronous workflows.

Examples

Explore various examples showcasing random hierarchies of asynchronous functions, graphically represented for better understanding and visualization. These examples demonstrate the flexibility and robustness of the monitoring engine in handling complex async workflows, making it easier to debug and optimize your code.

For demonstration purposes, an asynchronous function sleep(seconds, fail) is used to simulate an async operation. This function helps illustrate how the monitoring engine handles asynchronous tasks.

• seconds: The number of seconds to wait before resolving (default is a random number between 0 and 3).
• fail: A boolean indicating whether the function should reject (default is false). If undefined, there is a 50% chance of rejection.
• returns: A promise that resolves after the specified seconds or rejects based on the fail condition.

In example 'demo04', descriptions ending with double exclamation marks (!!) contain a sleep function that is likely to reject. This highlights the monitoring engine's ability to handle and report failed asynchronous operations effectively.

AI Validation Prompts

Use these prompts to validate that an AI tool is using package features correctly:

Create a fan-out/fan-in async-monitor.js example with 5 watches and explicit parent/child stages.

Create a group that cancels remaining running work on first rejection and explain why.

Create a callback-focused example that logs onStart, onComplete, onReject, and onAbort with correct this-binding.

Tests

npm install

To run the tests run:

npm test

If you want to add any feature or change existing features, you must run the tests to make sure you didn't break anything else. Any pull request (PR) needs to have updated passing tests for feature changes (or new passing tests for new features or fixes) in src/<file>.test.ts to be accepted. See

People

Maintainers: Manu Vanneste.