Merge branch 'main' into docs-migration-canonical

.github/pull_request_template.md

@@ -0,0 +1,35 @@
+<!-- 
+Please make sure you have read the contribution guidelines https://github.com/grafana/k6/blob/master/CONTRIBUTING.md as well as the
+the code of conduct https://github.com/grafana/k6/blob/master/CODE_OF_CONDUCT.md before opening a PR.
+-->
+
+## What?
+
+<!-- A description of the changes this PR brings to the documentation. -->
+
+## Checklist
+
+Please fill in this template:
+- [ ] I have used a meaningful title for the PR.
+- [ ] I have described the changes I've made in the "What?" section above.
+- [ ] I have performed a self-review of my changes.
+- [ ] I have run the `make docs` command locally and verified that the changes look good.
+
+Select one of these and delete the others:
+
+If updating the documentation for the most recent release of k6: 
+- [ ] I have made my changes in the `docs/sources/v{most_recent_release}` folder of the documentation.
+- [ ] I have reflected my changes in the `docs/sources/next` folder of the documentation.
+- [ ] I have reflected my changes in the relevant (*e.g.*  when correcting a documentation error) folders of the previous k6 versions of the documentation.
+
+If updating the documentation for the next release of k6:
+- [ ] I have made my changes in the `docs/sources/next` folder of the documentation.
+
+## Related PR(s)/Issue(s)
+
+<!-- - <https://github.com/grafana/...> -->
+
+<!-- Does it close an issue? -->
+<!-- Closes #ISSUE-ID -->
+
+<!-- Thanks for your contribution! 🙏🏼 -->

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

@@ -1,19 +1,20 @@
 ---
-title: "k6/experimental"
-excerpt: "k6 experimental APIs"
+title: 'k6/experimental'
+description: 'k6 experimental APIs'
 weight: 07
 ---
 
 # k6/experimental
 
 {{< docs/shared source="k6" lookup="experimental-module.md" version="<K6_VERSION>" >}}
 
-| Modules                                                                           | Description                                                                                                              |
-| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| Modules                                                                                          | Description                                                                                                              |
+| ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
 | [browser](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-experimental/browser)       | Provides browser-level APIs to interact with browsers and collect frontend performance metrics as part of your k6 tests. |
+| [fs](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-experimental/fs)                 | Provides a memory-efficient way to handle file interactions within your test scripts.                                    |
+| [grpc](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-experimental/grpc)             | Extends `k6/net/grpc` with the streaming capabilities.                                                                   |
 | [redis](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-experimental/redis)           | Functionality to interact with [Redis](https://redis.io/).                                                               |
 | [timers](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-experimental/timers)         | `setTimeout`, `clearTimeout`, `setInterval`, `clearInterval`                                                             |
 | [tracing](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-experimental/tracing)       | Support for instrumenting HTTP requests with tracing information.                                                        |
 | [webcrypto](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-experimental/webcrypto)   | Implements the [WebCrypto API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API).                         |
 | [websockets](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-experimental/websockets) | Implements the browser's [WebSocket API](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket).                    |
-| [grpc](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-experimental/grpc)             | Extends `k6/net/grpc` with the streaming capabilities.                                                                   |

docs/sources/next/javascript-api/k6-experimental/fs/FileInfo.md

@@ -0,0 +1,39 @@
+---
+title: 'FileInfo'
+description: 'FileInfo represents information about a file.'
+weight: 30
+---
+
+# FileInfo
+
+The `FileInfo` class represents information about a [file](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-experimental/fs/file).
+
+## Properties
+
+| Property | Type   | Description                    |
+| :------- | :----- | :----------------------------- |
+| name     | string | The name of the file.          |
+| size     | number | The size of the file in bytes. |
+
+## Example
+
+{{< code >}}
+
+```javascript
+import { open, SeekMode } from 'k6/experimental/fs';
+
+let file;
+(async function () {
+  file = await open('bonjour.txt');
+})();
+
+export default async function () {
+  // Retrieve information about the file
+  const fileinfo = await file.stat();
+  if (fileinfo.name != 'bonjour.txt') {
+    throw new Error('Unexpected file name');
+  }
+}
+```
+
+{{< /code >}}

docs/sources/next/javascript-api/k6-experimental/fs/SeekMode.md

@@ -0,0 +1,43 @@
+---
+title: 'SeekMode'
+description: 'SeekMode is used to specify the position from which to seek in a file.'
+weight: 40
+---
+
+# SeekMode
+
+The `SeekMode` enum specifies the position from which to [seek](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-experimental/fs/file/seek) in a file.
+
+## Members
+
+| Member  | Value | Description                                 |
+| :------ | :---- | :------------------------------------------ |
+| Start   | 0     | Seek from the start of the file.            |
+| Current | 1     | Seek from the current position in the file. |
+| End     | 2     | Seek from the end of the file.              |
+
+## Example
+
+{{< code >}}
+
+```javascript
+import { open, SeekMode } from 'k6/experimental/fs';
+
+let file;
+(async function () {
+  file = await open('bonjour.txt');
+})();
+
+export default async function () {
+  // Seek 6 bytes from the start of the file
+  await file.seek(6, SeekMode.Start);
+
+  // Seek 2 more bytes from the current position
+  await file.seek(2, SeekMode.Current);
+
+  // Seek backwards 2 bytes from the end of the file
+  await file.seek(-2, SeekMode.End);
+}
+```
+
+{{< /code >}}

docs/sources/next/javascript-api/k6-experimental/fs/_index.md

@@ -0,0 +1,84 @@
+---
+title: 'fs'
+description: 'k6 fs experimental API'
+weight: 10
+---
+
+# fs
+
+{{< docs/shared source="k6" lookup="experimental-module.md" version="<K6_VERSION>" >}}
+
+The k6 filesystem experimental module provides a memory-efficient way to handle file interactions within your test scripts. It currently offers support for opening files, reading their content, seeking through their content, and retrieving metadata about them.
+
+### Memory efficiency
+
+One of the key advantages of the filesystem module is its memory efficiency. Unlike the traditional [open](https://grafana.com/docs/k6/latest/javascript-api/init-context/open/) function, which loads a file multiple times into memory, the filesystem module reduces memory usage by loading the file as little as possible and sharing the same memory space between all VUs. This approach reduces the risk of encountering out-of-memory errors, especially in load tests involving large files.
+
+### Notes on usage
+
+An important consideration when using the filesystem module is its handling of external file modifications. Once k6 loads a file, it behaves like a "view" over its contents. If you modify the underlying file during a test, k6 will not reflect those changes in the loaded [File](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-experimental/fs/file/) instance.
+
+## API Overview
+
+The module exports functions and objects to interact with the file system:
+
+| Function/Object                                                                                 | Description                                                                                          |
+| ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| [open](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-experimental/fs/open)         | Opens a file and returns a promise resolving to a `File` instance.                                   |
+| [File](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-experimental/fs/file)         | Represents a file with methods for reading, seeking, and obtaining file stats.                       |
+| [SeekMode](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-experimental/fs/seekmode) | Enum for specifying the reference point for seek operations. Includes `Start`, `Current`, and `End`. |
+
+## Example
+
+{{< code >}}
+
+```javascript
+import { open, SeekMode } from 'k6/experimental/fs';
+
+// k6 doesn't support async in the init context. We use a top-level async function for `await`.
+//
+// Each Virtual User gets its own `file` copy.
+// So, operations like `seek` or `read` won't impact other VUs.
+let file;
+(async function () {
+  file = await open('bonjour.txt');
+})();
+
+export default async function () {
+  // About information about the file
+  const fileinfo = await file.stat();
+  if (fileinfo.name != 'bonjour.txt') {
+    throw new Error('Unexpected file name');
+  }
+
+  const buffer = new Uint8Array(4);
+
+  let totalBytesRead = 0;
+  while (true) {
+    // Read into the buffer
+    const bytesRead = await file.read(buffer);
+    if (bytesRead == null) {
+      // EOF
+      break;
+    }
+
+    // Do something useful with the content of the buffer
+    totalBytesRead += bytesRead;
+
+    // If bytesRead is less than the buffer size, we've read the whole file
+    if (bytesRead < buffer.byteLength) {
+      break;
+    }
+  }
+
+  // Check that we read the expected number of bytes
+  if (totalBytesRead != fileinfo.size) {
+    throw new Error('Unexpected number of bytes read');
+  }
+
+  // Seek back to the beginning of the file
+  await file.seek(0, SeekMode.Start);
+}
+```
+
+{{< /code >}}

docs/sources/next/javascript-api/k6-experimental/fs/file/_index.md

@@ -0,0 +1,74 @@
+---
+title: 'File'
+description: 'File represents a file with methods for reading, seeking, and obtaining file stats.'
+weight: 10
+---
+
+# File
+
+The `File` class represents a file with methods for reading, seeking, and obtaining file stats. It's returned by the [open](https://grafana.com/docs/k6/latest/javascript-api/init-context/open/) function.
+
+## Properties
+
+| Property | Type   | Description                    |
+| :------- | :----- | :----------------------------- |
+| path     | string | The absolute path to the file. |
+
+## Methods
+
+| Method                                                                                       | Description                                                                                                                            |
+| :------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------- |
+| [read](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-experimental/fs/file/read) | Reads up to `buffer.byteLength` bytes from the file into the passed `buffer`. Returns a promise resolving to the number of bytes read. |
+| [seek](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-experimental/fs/file/seek) | Sets the file position indicator for the file to the passed `offset` bytes. Returns a promise resolving to the new offset.             |
+| [stat](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-experimental/fs/file/stat) | Returns a promise resolving to a [FileInfo](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-experimental/fs/fileinfo/) object with information about the file.                              |
+
+## Example
+
+{{< code >}}
+
+```javascript
+import { open, SeekMode } from 'k6/experimental/fs';
+
+let file;
+(async function () {
+  file = await open('bonjour.txt');
+})();
+
+export default async function () {
+  // About information about the file
+  const fileinfo = await file.stat();
+  if (fileinfo.name != 'bonjour.txt') {
+    throw new Error('Unexpected file name');
+  }
+
+  const buffer = new Uint8Array(4);
+
+  let totalBytesRead = 0;
+  while (true) {
+    // Read into the buffer
+    const bytesRead = await file.read(buffer);
+    if (bytesRead == null) {
+      // EOF
+      break;
+    }
+
+    // Do something useful with the content of the buffer
+    totalBytesRead += bytesRead;
+
+    // If bytesRead is less than the buffer size, we've read the whole file
+    if (bytesRead < buffer.byteLength) {
+      break;
+    }
+  }
+
+  // Check that we read the expected number of bytes
+  if (totalBytesRead != fileinfo.size) {
+    throw new Error('Unexpected number of bytes read');
+  }
+
+  // Seek back to the beginning of the file
+  await file.seek(0, SeekMode.Start);
+}
+```
+
+{{< /code >}}