Add example for Timing methods (#1651)

* Add example and note in `k6/timers`

* Fix note about experimental version removal

* fix `eslint` conf

* Port changes to `next`

* Mention global availability in the experimental module note

* Update docs/sources/next/shared/experimental-timers-module.md

Co-authored-by: Heitor Tashiro Sergent <[email protected]>

* Update docs/sources/next/shared/experimental-timers-module.md

Co-authored-by: Heitor Tashiro Sergent <[email protected]>

* Update docs/sources/next/javascript-api/k6-timers/_index.md

Co-authored-by: Heitor Tashiro Sergent <[email protected]>

---------

Co-authored-by: Heitor Tashiro Sergent <[email protected]>

Author: ppcano

docs/sources/.eslintrc.js

@@ -41,5 +41,9 @@ module.exports = {
     __ITER: 'readonly',
     open: 'readonly',
     window: 'readonly',
+    setInterval: 'readonly',
+    clearInterval: 'readonly',
+    setTimeout: 'readonly',
+    clearTimeout: 'readonly',
   },
 };

docs/sources/next/javascript-api/k6-timers/_index.md

@@ -1,16 +1,40 @@
 ---
-title: "k6/timers"
-description: "k6 timers API"
+title: 'k6/timers'
+description: 'k6 timers API'
 weight: 11
 ---
 
 # k6/timers
 
 Implement timers to work with k6's event loop. They mimic the functionality found in browsers and other JavaScript runtimes.
 
-| Function                                       | Description                                                                                    |
-| :------------------------------------------ | :--------------------------------------------------------------------------------------------- |
-| [setTimeout](https://developer.mozilla.org/en-US/docs/Web/API/setTimeout)     | Sets a function to be run after a given timeout.  |
-| [clearTimeout](https://developer.mozilla.org/en-US/docs/Web/API/clearTimeout) | Clears a previously set timeout with `setTimeout`. |
-| [setInterval](https://developer.mozilla.org/en-US/docs/Web/API/setInterval)   | Sets a function to be run on a given interval. |
+| Function                                                                      | Description                                          |
+| :---------------------------------------------------------------------------- | :--------------------------------------------------- |
+| [setTimeout](https://developer.mozilla.org/en-US/docs/Web/API/setTimeout)     | Sets a function to be run after a given timeout.     |
+| [clearTimeout](https://developer.mozilla.org/en-US/docs/Web/API/clearTimeout) | Clears a previously set timeout with `setTimeout`.   |
+| [setInterval](https://developer.mozilla.org/en-US/docs/Web/API/setInterval)   | Sets a function to be run on a given interval.       |
 | [clearInterval](https://developer.mozilla.org/en-US/docs/Web/API/setInterval) | Clears a previously set interval with `setInterval`. |
+
+{{% admonition type="note" %}}
+
+The timer methods are available globally, so you can use them in your script without including an import statement.
+
+{{% /admonition %}}
+
+## Example
+
+```javascript
+export default function () {
+  const intervalId = setInterval(() => {
+    console.log('This runs every 200ms');
+  }, 200);
+
+  const timeoutId = setTimeout(() => {
+    console.log('This runs after 2s');
+
+    // clear the timeout and interval to exit k6
+    clearInterval(intervalId);
+    clearTimeout(timeoutId);
+  }, 2000);
+}
+```

docs/sources/next/shared/experimental-timers-module.md

@@ -4,8 +4,8 @@ title: Experimental timers module admonition
 
 {{% admonition type="caution" %}}
 
-Starting on k6 `v0.50`, the experimental module `k6/experimental/timers` has been graduated, and its functionality is now available in the [`k6/timers` module](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-timers/). The `k6/experimental/timers` is deprecated and will be removed in `v0.52.0`.
+The experimental module `k6/experimental/timers` has graduated, and its functionality is now available globally and through the [`k6/timers` module](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-timers/). The `k6/experimental/timers` is deprecated and will be removed.
 
-To migrate your scripts, replace all `k6/experimental/timers` imports with `k6/timers`.
+To migrate your scripts, remove the `k6/experimental/timers` imports.
 
 {{% /admonition %}}

docs/sources/v0.52.x/javascript-api/k6-timers/_index.md

@@ -1,16 +1,40 @@
 ---
-title: "k6/timers"
-description: "k6 timers API"
+title: 'k6/timers'
+description: 'k6 timers API'
 weight: 11
 ---
 
 # k6/timers
 
 Implement timers to work with k6's event loop. They mimic the functionality found in browsers and other JavaScript runtimes.
 
-| Function                                       | Description                                                                                    |
-| :------------------------------------------ | :--------------------------------------------------------------------------------------------- |
-| [setTimeout](https://developer.mozilla.org/en-US/docs/Web/API/setTimeout)     | Sets a function to be run after a given timeout.  |
-| [clearTimeout](https://developer.mozilla.org/en-US/docs/Web/API/clearTimeout) | Clears a previously set timeout with `setTimeout`. |
-| [setInterval](https://developer.mozilla.org/en-US/docs/Web/API/setInterval)   | Sets a function to be run on a given interval. |
+| Function                                                                      | Description                                          |
+| :---------------------------------------------------------------------------- | :--------------------------------------------------- |
+| [setTimeout](https://developer.mozilla.org/en-US/docs/Web/API/setTimeout)     | Sets a function to be run after a given timeout.     |
+| [clearTimeout](https://developer.mozilla.org/en-US/docs/Web/API/clearTimeout) | Clears a previously set timeout with `setTimeout`.   |
+| [setInterval](https://developer.mozilla.org/en-US/docs/Web/API/setInterval)   | Sets a function to be run on a given interval.       |
 | [clearInterval](https://developer.mozilla.org/en-US/docs/Web/API/setInterval) | Clears a previously set interval with `setInterval`. |
+
+{{% admonition type="note" %}}
+
+The timing methods are available globally, like in other JavaScript runtimes, and it is unnecessary to import them from the `k6/timers` module.
+
+{{% /admonition %}}
+
+## Example
+
+```javascript
+export default function () {
+  const intervalId = setInterval(() => {
+    console.log('This runs every 200ms');
+  }, 200);
+
+  const timeoutId = setTimeout(() => {
+    console.log('This runs after 2s');
+
+    // clear the timeout and interval to exit k6
+    clearInterval(intervalId);
+    clearTimeout(timeoutId);
+  }, 2000);
+}
+```

docs/sources/v0.52.x/shared/experimental-timers-module.md

@@ -4,8 +4,8 @@ title: Experimental timers module admonition
 
 {{% admonition type="caution" %}}
 
-Starting on k6 `v0.50`, the experimental module `k6/experimental/timers` has been graduated, and its functionality is now available in the [`k6/timers` module](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-timers/). The `k6/experimental/timers` is deprecated and will be removed in `v0.52.0`.
+The experimental module `k6/experimental/timers` has graduated, and its functionality is now globally available and through the [`k6/timers` module](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-timers/). The `k6/experimental/timers` is deprecated and will be removed.
 
-To migrate your scripts, replace all `k6/experimental/timers` imports with `k6/timers`.
+To migrate your scripts, remove the `k6/experimental/timers` imports or import them using the `k6/timers` module.
 
 {{% /admonition %}}