@types/k6 0.47.2 → 0.48.0

k6/README.md

@@ -2,14 +2,14 @@
 > `npm install --save @types/k6`
 
 # Summary
-This package contains type definitions for k6 (https://k6.io/docs/).
+This package contains type definitions for k6 (https://grafana.com/docs/k6/latest/).
 
 # Details
 Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/k6.
 
 ### Additional Details
- * Last updated: Tue, 07 Nov 2023 03:09:37 GMT
+ * Last updated: Wed, 06 Dec 2023 11:07:02 GMT
  * Dependencies: none
 
 # Credits
-These definitions were written by [Mihail Stoykov](https://github.com/MStoykov), [Ivan](https://github.com/codebien), [Théo Crevon](https://github.com/oleiade), [Oleg Bespalov](https://github.com/olegbespalov), [Pepe Cano](https://github.com/ppcano), [Nicole van der Hoeven](https://github.com/nicolevanderhoeven), [Ankur Agarwal](https://github.com/ankur22), [İnanç Gümüş](https://github.com/inancgumus), and [Daniel Jiménez](https://github.com/ka3de).
+These definitions were written by [Mihail Stoykov](https://github.com/MStoykov), [Ivan](https://github.com/codebien), [Théo Crevon](https://github.com/oleiade), [Oleg Bespalov](https://github.com/olegbespalov), [Pepe Cano](https://github.com/ppcano), [Nicole van der Hoeven](https://github.com/nicolevanderhoeven), [Ankur Agarwal](https://github.com/ankur22), [İnanç Gümüş](https://github.com/inancgumus), [Daniel Jiménez](https://github.com/ka3de), and [Joan López de la Franca Beltran](https://github.com/joanlopez).

k6/crypto.d.ts

@@ -13,7 +13,7 @@ export function randomBytes(size: number): ArrayBuffer;
 
 /**
  * Produce HMAC.
- * https://k6.io/docs/javascript-api/k6-crypto/hmac-algorithm-secret-data-outputencoding/
+ * https://grafana.com/docs/k6/latest/javascript-api/k6-crypto/hmac/
  * @param algorithm - Hash algorithm.
  * @param secret - Shared secret.
  * @param input - Input data.
@@ -31,7 +31,7 @@ export function hmac<OE extends OutputEncoding>(
 
 /**
  * Hash with MD4.
- * https://k6.io/docs/javascript-api/k6-crypto/md4-input-outputencoding/
+ * https://grafana.com/docs/k6/latest/javascript-api/k6-crypto/md4/
  * @param input - Data to hash.
  * @param outputEncoding - Output encoding.
  * @returns MD4 digest.
@@ -42,7 +42,7 @@ export function md4<OE extends OutputEncoding>(input: string | ArrayBuffer, outp
 
 /**
  * Hash with MD5.
- * https://k6.io/docs/javascript-api/k6-crypto/md5-input-outputencoding/
+ * https://grafana.com/docs/k6/latest/javascript-api/k6-crypto/md5/
  * @param input - Data to hash.
  * @param outputEncoding - Output encoding.
  * @returns MD5 digest.
@@ -53,7 +53,7 @@ export function md5<OE extends OutputEncoding>(input: string | ArrayBuffer, outp
 
 /**
  * Hash with SHA-1.
- * https://k6.io/docs/javascript-api/k6-crypto/sha1-input-outputencoding/
+ * https://grafana.com/docs/k6/latest/javascript-api/k6-crypto/sha1/
  * @param input - Data to hash.
  * @param outputEncoding - Output encoding.
  * @returns SHA-1 digest.
@@ -64,7 +64,7 @@ export function sha1<OE extends OutputEncoding>(input: string | ArrayBuffer, out
 
 /**
  * Hash with SHA-256.
- * https://k6.io/docs/javascript-api/k6-crypto/sha256-input-outputencoding/
+ * https://grafana.com/docs/k6/latest/javascript-api/k6-crypto/sha256/
  * @param input - Data to hash.
  * @param outputEncoding - Output encoding.
  * @returns SHA-256 digest.
@@ -75,7 +75,7 @@ export function sha256<OE extends OutputEncoding>(input: string | ArrayBuffer, o
 
 /**
  * Hash with SHA-384.
- * https://k6.io/docs/javascript-api/k6-crypto/sha384-input-outputencoding/
+ * https://grafana.com/docs/k6/latest/javascript-api/k6-crypto/sha384/
  * @param input - Data to hash.
  * @param outputEncoding - Output encoding.
  * @returns SHA-384 digest.
@@ -86,7 +86,7 @@ export function sha384<OE extends OutputEncoding>(input: string | ArrayBuffer, o
 
 /**
  * Hash with SHA-512.
- * https://k6.io/docs/javascript-api/k6-crypto/sha512-input-outputencoding/
+ * https://grafana.com/docs/k6/latest/javascript-api/k6-crypto/sha512/
  * @param input - Data to hash.
  * @param outputEncoding - Output encoding.
  * @returns SHA-512 digest.
@@ -97,7 +97,7 @@ export function sha512<OE extends OutputEncoding>(input: string | ArrayBuffer, o
 
 /**
  * Hash with SHA-512/224.
- * https://k6.io/docs/javascript-api/k6-crypto/sha512_224-input-outputencoding/
+ * https://grafana.com/docs/k6/latest/javascript-api/k6-crypto/sha512_224/
  * @param input - Data to hash.
  * @param outputEncoding - Output encoding.
  * @returns SHA-512/224 digest.
@@ -108,7 +108,7 @@ export function sha512_224<OE extends OutputEncoding>(input: string | ArrayBuffe
 
 /**
  * Hash with SHA-512/256.
- * https://k6.io/docs/javascript-api/k6-crypto/sha512_256-input-outputencoding/
+ * https://grafana.com/docs/k6/latest/javascript-api/k6-crypto/sha512_256/
  * @param input - Data to hash.
  * @param outputEncoding - Output encoding.
  * @returns SHA-512/256 digest.
@@ -119,7 +119,7 @@ export function sha512_256<OE extends OutputEncoding>(input: string | ArrayBuffe
 
 /**
  * Hash with RIPEMD-160.
- * https://k6.io/docs/javascript-api/k6-crypto/ripemd160-input-outputencoding/
+ * https://grafana.com/docs/k6/latest/javascript-api/k6-crypto/ripemd160/
  * @param input - Data to hash.
  * @param outputEncoding - Output encoding.
  * @returns RIPEMD-160 digest.
@@ -130,7 +130,7 @@ export function ripemd160<OE extends OutputEncoding>(input: string | ArrayBuffer
 
 /**
  * Create a hashing object.
- * https://k6.io/docs/javascript-api/k6-crypto/createhash-algorithm/
+ * https://grafana.com/docs/k6/latest/javascript-api/k6-crypto/createhash/
  * @param algorithm - Hash algorithm.
  * @returns Hashing object.
  * @example
@@ -139,7 +139,7 @@ export function createHash(algorithm: Algorithm): Hasher;
 
 /**
  * Create an HMAC hashing object.
- * https://k6.io/docs/javascript-api/k6-crypto/createhmac-algorithm-secret/
+ * https://grafana.com/docs/k6/latest/javascript-api/k6-crypto/createhmac/
  * @param algorithm - Hash algorithm.
  * @param secret - Shared secret.
  * @returns HMAC hashing object.
@@ -186,14 +186,14 @@ export type Output<OE extends OutputEncoding> = OE extends StringEncoding ? stri
 
 /**
  * Hashing object.
- * https://k6.io/docs/javascript-api/k6-crypto/hasher/
+ * https://grafana.com/docs/k6/latest/javascript-api/k6-crypto/hasher/
  */
 export abstract class Hasher {
     protected __brand: never;
 
     /**
      * Add more data to the string we want to create a hash of.
-     * https://k6.io/docs/javascript-api/k6-crypto/hasher/
+     * https://grafana.com/docs/k6/latest/javascript-api/k6-crypto/hasher/
      * @param input - Data to add.
      * @example
      * let hasher = crypto.createHMAC('sha256', 'a secret');
@@ -205,7 +205,7 @@ export abstract class Hasher {
 
     /**
      * Return a digest from the data added so far.
-     * https://k6.io/docs/javascript-api/k6-crypto/hasher/
+     * https://grafana.com/docs/k6/latest/javascript-api/k6-crypto/hasher/
      * @param outputEncoding - Output encoding.
      * @returns Digest of data added so far.
      * @example
@@ -219,7 +219,7 @@ export abstract class Hasher {
 
 /**
  * This module provides common hashing functionality available in the GoLang crypto package.
- * https://k6.io/docs/javascript-api/k6-crypto/
+ * https://grafana.com/docs/k6/latest/javascript-api/k6-crypto/
  */
 declare namespace crypto {
     /**
@@ -235,7 +235,7 @@ declare namespace crypto {
 
     /**
      * Produce HMAC.
-     * https://k6.io/docs/javascript-api/k6-crypto/hmac-algorithm-secret-data-outputencoding/
+     * https://grafana.com/docs/k6/latest/javascript-api/k6-crypto/hmac/
      * @param algorithm - Hash algorithm.
      * @param secret - Shared secret.
      * @param input - Input data.
@@ -253,7 +253,7 @@ declare namespace crypto {
 
     /**
      * Hash with MD4.
-     * https://k6.io/docs/javascript-api/k6-crypto/md4-input-outputencoding/
+     * https://grafana.com/docs/k6/latest/javascript-api/k6-crypto/md4/
      * @param input - Data to hash.
      * @param outputEncoding - Output encoding.
      * @returns MD4 digest.
@@ -264,7 +264,7 @@ declare namespace crypto {
 
     /**
      * Hash with MD5.
-     * https://k6.io/docs/javascript-api/k6-crypto/md5-input-outputencoding/
+     * https://grafana.com/docs/k6/latest/javascript-api/k6-crypto/md5/
      * @param input - Data to hash.
      * @param outputEncoding - Output encoding.
      * @returns MD5 digest.
@@ -275,7 +275,7 @@ declare namespace crypto {
 
     /**
      * Hash with SHA-1.
-     * https://k6.io/docs/javascript-api/k6-crypto/sha1-input-outputencoding/
+     * https://grafana.com/docs/k6/latest/javascript-api/k6-crypto/sha1/
      * @param input - Data to hash.
      * @param outputEncoding - Output encoding.
      * @returns SHA-1 digest.
@@ -286,7 +286,7 @@ declare namespace crypto {
 
     /**
      * Hash with SHA-256.
-     * https://k6.io/docs/javascript-api/k6-crypto/sha256-input-outputencoding/
+     * https://grafana.com/docs/k6/latest/javascript-api/k6-crypto/sha256/
      * @param input - Data to hash.
      * @param outputEncoding - Output encoding.
      * @returns SHA-256 digest.
@@ -297,7 +297,7 @@ declare namespace crypto {
 
     /**
      * Hash with SHA-384.
-     * https://k6.io/docs/javascript-api/k6-crypto/sha384-input-outputencoding/
+     * https://grafana.com/docs/k6/latest/javascript-api/k6-crypto/sha384/
      * @param input - Data to hash.
      * @param outputEncoding - Output encoding.
      * @returns SHA-384 digest.
@@ -308,7 +308,7 @@ declare namespace crypto {
 
     /**
      * Hash with SHA-512.
-     * https://k6.io/docs/javascript-api/k6-crypto/sha512-input-outputencoding/
+     * https://grafana.com/docs/k6/latest/javascript-api/k6-crypto/sha512/
      * @param input - Data to hash.
      * @param outputEncoding - Output encoding.
      * @returns SHA-512 digest.
@@ -319,7 +319,7 @@ declare namespace crypto {
 
     /**
      * Hash with SHA-512/224.
-     * https://k6.io/docs/javascript-api/k6-crypto/sha512_224-input-outputencoding/
+     * https://grafana.com/docs/k6/latest/javascript-api/k6-crypto/sha512_224/
      * @param input - Data to hash.
      * @param outputEncoding - Output encoding.
      * @returns SHA-512/224 digest.
@@ -330,7 +330,7 @@ declare namespace crypto {
 
     /**
      * Hash with SHA-512/256.
-     * https://k6.io/docs/javascript-api/k6-crypto/sha512_256-input-outputencoding/
+     * https://grafana.com/docs/k6/latest/javascript-api/k6-crypto/sha512_256/
      * @param input - Data to hash.
      * @param outputEncoding - Output encoding.
      * @returns SHA-512/256 digest.
@@ -341,7 +341,7 @@ declare namespace crypto {
 
     /**
      * Hash with RIPEMD-160.
-     * https://k6.io/docs/javascript-api/k6-crypto/ripemd160-input-outputencoding/
+     * https://grafana.com/docs/k6/latest/javascript-api/k6-crypto/ripemd160/
      * @param input - Data to hash.
      * @param outputEncoding - Output encoding.
      * @returns RIPEMD-160 digest.
@@ -352,7 +352,7 @@ declare namespace crypto {
 
     /**
      * Create a hashing object.
-     * https://k6.io/docs/javascript-api/k6-crypto/createhash-algorithm/
+     * https://grafana.com/docs/k6/latest/javascript-api/k6-crypto/createhash/
      * @param algorithm - Hash algorithm.
      * @returns Hashing object.
      * @example
@@ -365,7 +365,7 @@ declare namespace crypto {
 
     /**
      * Create an HMAC hashing object.
-     * https://k6.io/docs/javascript-api/k6-crypto/createhmac-algorithm-secret/
+     * https://grafana.com/docs/k6/latest/javascript-api/k6-crypto/createhmac/
      * @param algorithm - Hash algorithm.
      * @param secret - Shared secret.
      * @returns HMAC hashing object.

k6/data.d.ts

@@ -1,16 +1,16 @@
 /**
  * Given a name and a function that returns an array, the SharedArray constructor returns the same array but sharing the array memory between VUs.
- * https://k6.io/docs/javascript-api/k6-data/sharedarray/
+ * https://grafana.com/docs/k6/latest/javascript-api/k6-data/sharedarray/
  */
 export const SharedArray: {
     /**
      * Given a name and a function that returns an array, the SharedArray constructor returns the same array but sharing the array memory between VUs.
-     * https://k6.io/docs/javascript-api/k6-data/sharedarray/
+     * https://grafana.com/docs/k6/latest/javascript-api/k6-data/sharedarray/
      */
     new(name: string, callback: () => []): [];
     /**
      * Given a name and a function that returns an array, the SharedArray constructor returns the same array but sharing the array memory between VUs.
-     * https://k6.io/docs/javascript-api/k6-data/sharedarray/
+     * https://grafana.com/docs/k6/latest/javascript-api/k6-data/sharedarray/
      */
     new<T>(name: string, callback: () => T[]): T[];
 };

k6/encoding.d.ts

@@ -1,6 +1,6 @@
 /**
  * Base64 decode a string.
- * https://k6.io/docs/javascript-api/k6-encoding/b64decode-input-encoding-format/
+ * https://grafana.com/docs/k6/latest/javascript-api/k6-encoding/b64decode/
  * @param input - The string to base64 decode.
  * @param encoding - Base64 variant.
  * @returns The base64 decoded version of the input string in either string or ArrayBuffer format, depending on the `format` parameter.
@@ -14,7 +14,7 @@ export function b64decode(input: string, encoding?: Base64Variant): ArrayBuffer;
 
 /**
  * Base64 decode a string.
- * https://k6.io/docs/javascript-api/k6-encoding/b64decode-input-encoding-format/
+ * https://grafana.com/docs/k6/latest/javascript-api/k6-encoding/b64decode/
  * @param input - The string to base64 decode.
  * @param encoding - Base64 variant.
  * @param format - If 's' return the data as a string, otherwise an ArrayBuffer object .
@@ -28,7 +28,7 @@ export function b64decode(input: string, encoding: Base64Variant, format: "s"):
 
 /**
  * Base64 encode a string.
- * https://k6.io/docs/javascript-api/k6-encoding/b64encode-input-encoding/
+ * https://grafana.com/docs/k6/latest/javascript-api/k6-encoding/b64encode/
  * @param input - String to encode or ArrayBuffer object.
  * @param encoding - Base64 variant.
  * @returns Base64 encoded string.
@@ -45,12 +45,12 @@ export type Base64Variant = "std" | "rawstd" | "url" | "rawurl";
 
 /**
  * The encoding module provides base64 encoding/decoding.
- * https://k6.io/docs/javascript-api/k6-encoding/
+ * https://grafana.com/docs/k6/latest/javascript-api/k6-encoding/
  */
 declare namespace encoding {
     /**
      * Base64 decode a string.
-     * https://k6.io/docs/javascript-api/k6-encoding/b64decode-input-encoding-format/
+     * https://grafana.com/docs/k6/latest/javascript-api/k6-encoding/b64decode/
      * @param input - The string to base64 decode.
      * @param encoding - Base64 variant.
      * @returns The base64 decoded version of the input string in either string or ArrayBuffer format, depending on the `format` parameter.
@@ -63,7 +63,7 @@ declare namespace encoding {
     function b64decode(input: string, encoding?: Base64Variant): ArrayBuffer;
     /**
      * Base64 decode a string.
-     * https://k6.io/docs/javascript-api/k6-encoding/b64decode-input-encoding-format/
+     * https://grafana.com/docs/k6/latest/javascript-api/k6-encoding/b64decode/
      * @param input - The string to base64 decode.
      * @param encoding - Base64 variant.
      * @param format - If 's' return the data as a string, otherwise an ArrayBuffer object .
@@ -76,7 +76,7 @@ declare namespace encoding {
     function b64decode(input: string, encoding: Base64Variant, format: "s"): string;
     /**
      * Base64 decode a string.
-     * https://k6.io/docs/javascript-api/k6-encoding/b64decode-input-encoding/
+     * https://grafana.com/docs/k6/latest/javascript-api/k6-encoding/b64decode/
      * @param input - Base64 encoded string or ArrayBuffer object.
      * @param encoding - Base64 variant.
      * @returns Decoded string.

k6/execution.d.ts

@@ -2,7 +2,7 @@ import { Options } from "./options";
 
 /*
  * The execution module provides information about the current test execution state.
- * https://k6.io/docs/javascript-api/k6-execution/
+ * https://grafana.com/docs/k6/latest/javascript-api/k6-execution/
  */
 declare namespace execution {
     /**
@@ -67,7 +67,7 @@ declare namespace execution {
     const test: {
         /**
          * Aborts the test run with the exit code 108.
-         * https://k6.io/docs/javascript-api/k6-execution/#test
+         * https://grafana.com/docs/k6/latest/javascript-api/k6-execution/#test
          * @param input - Aborted message.
          * @example
          * import exec from "k6/execution";

k6/experimental/browser.d.ts

@@ -20,6 +20,40 @@ export type Unboxed<Arg> = Arg extends [infer A0, infer A1] ? [Unboxed<A0>, Unbo
     : Arg extends object ? { [Key in keyof Arg]: Unboxed<Arg[Key]> }
     : Arg;
 
+/*
+ * CPUProfile is the mandatory input to be passed into {@link Page}'s
+ * `throttleCPU` method.
+ */
+export interface CPUProfile {
+    /*
+     * rate as a slowdown factor (1 is no throttle, 2 is 2x slowdown, etc).
+     */
+    rate: number;
+}
+
+/*
+ * NetworkProfile is the mandatory input to be passed into {@link Page}'s
+ * `throttleNetwork` method.
+ */
+export interface NetworkProfile {
+    /*
+     * Minimum latency from request sent to response headers received (ms).
+     */
+    latency: number;
+
+    /*
+     * Maximal aggregated download throughput (bytes/sec). -1 disables download
+     * throttling.
+     */
+    download: number;
+
+    /*
+     * Maximal aggregated upload throughput (bytes/sec). -1 disables upload
+     * throttling.
+     */
+    upload: number;
+}
+
 export interface SelectOptionsObject {
     /**
      * Matches by `option.value`.
@@ -545,6 +579,12 @@ export const browser: Browser;
  * `Browser` represents the main web browser instance.
  */
 export interface Browser {
+    /**
+     * Closes the current `BrowserContext`. If there is no active
+     * `BrowserContext`, this method will throw an error.
+     */
+    closeContext(): void;
+
     /**
      * Returns the current `BrowserContext`. There is a 1-to-1 mapping between
      * `Browser` and `BrowserContext`. If no `BrowserContext` has been
@@ -650,7 +690,10 @@ export interface BrowserContext {
     cookies(...urls: string[]): Cookie[];
 
     /**
-     * Clears all permission overrides for the `BrowserContext`.
+     * Clears all permission overrides for the {@link BrowserContext}.
+     * ```js
+     * context.clearPermissions();
+     * ```
      */
     clearPermissions(): void;
 
@@ -660,7 +703,10 @@ export interface BrowserContext {
     close(): void;
 
     /**
-     * Grants specified permissions to the `BrowserContext`.
+     * Grants specified permissions to the {@link BrowserContext}.
+     * ```js
+     * context.grantPermissions(['geolocation']);
+     * ```
      */
     grantPermissions(
         /**
@@ -741,40 +787,55 @@ export interface BrowserContext {
 
     /**
      * Waits for the event to fire and passes its value into the predicate
-     * function.
+     * function. Currently the only supported event is 'page' which when used will
+     * return the new {@link Page} that was created after `waitForEvent` was called.
+     *
+     * @example
+     * ```js
+     * // Call waitForEvent with a predicate which will return true once at least
+     * // one page has been created.
+     * const promise = context.waitForEvent("page", { predicate: page => {
+     *   if (++counter >= 1) {
+     *     return true
+     *   }
+     *   return false
+     * } })
+     *
+     * // Now we create a page.
+     * const page = context.newPage()
+     *
+     * // Wait for the predicate to pass.
+     * await promise
+     * ```
      */
     waitForEvent(
         /**
-         * Name of event to wait for.
-         *
-         * NOTE: Currently this argument is disregarded, and waitForEvent will
-         * always wait for 'close' or 'page' events.
+         * Name of event to wait for. The only supported event is 'page'. If any
+         * other value is used an error will be thrown.
          */
-        event: string,
+        event: "page",
         /**
-         * The `Page` or null event data will be passed to it and it must
-         * return true to continue.
+         * This is an optional argument. It can either be a predicate function or
+         * an options object.
          */
-        optionsOrPredicate: {
+        optionsOrPredicate?: {
             /**
-             * Function that will be called when the 'Page' event is emitted.
-             * The event data will be passed to it and it must return true
+             * Optional function that will be called when the {@link Page} event is
+             * emitted. The event data will be passed to it and it must return true
              * to continue.
              *
-             * If `Page` is passed to predicate, this signals that a new page
+             * If {@link Page} is passed to predicate, this signals that a new page
              * has been created.
-             * If null is passed to predicate, this signals that the page is
-             * closing.
              */
-            predicate: (page: Page | null) => boolean;
+            predicate?: (page: Page) => boolean;
 
             /**
-             * Maximum time to wait in milliseconds. Pass 0 to disable timeout.
-             * Defaults to 30000 milliseconds.
+             * Maximum time to wait in milliseconds. Defaults to 30000 milliseconds or
+             * the timeout set by setDefaultTimeout on the {@link BrowserContext}.
              */
             timeout?: number;
-        },
-    ): Page | null;
+        } | ((page: Page) => boolean),
+    ): Promise<Page>;
 }
 
 /**
@@ -2992,6 +3053,55 @@ export interface Page {
         },
     ): string;
 
+    /**
+     * Throttles the CPU in Chrome/Chromium to slow it down by the specified
+     * `rate` in {@link CPUProfile}. {@link CPUProfile} is a mandatory
+     * input argument. The default `rate` is `1`.
+     *
+     * **Usage**
+     *
+     * ```js
+     * page.throttleCPU({ rate: 4 });
+     * ```
+     */
+    throttleCPU(profile: CPUProfile): void;
+
+    /**
+     * Throttles the network in Chrome/Chromium to slow it down by the specified
+     * fields in {@link NetworkProfile}. {@link NetworkProfile} is a mandatory
+     * input argument.
+     *
+     * **Usage**
+     *
+     * ```js
+     * page.throttleNetwork({
+     *   latency: 750,
+     *   download: 250,
+     *   upload: 250,
+     * });
+     * ```
+     *
+     * To work with the most commonly tested network profiles, import `networkProfiles`
+     * from the browser module. There are three profiles available:
+     * - `'No Throttling'` (default)
+     * - `'Fast 3G'`
+     * - `'Slow 3G'`
+     *
+     * **Usage**
+     *
+     * ```js
+     * import { browser, networkProfiles } from 'k6/experimental/browser';
+     * ... // redacted
+     *   const context = browser.newContext();
+     *   const page = context.newPage();
+     *
+     *   try {
+     *     page.throttleNetwork(networkProfiles['Slow 3G']);
+     * ... // redacted
+     * ```
+     */
+    throttleNetwork(profile: NetworkProfile): void;
+
     /**
      * Returns the page's title.
      */

k6/experimental/fs.d.ts

@@ -0,0 +1,102 @@
+/**
+ * The k6 experimental filesystem module provides an API for handling file operations
+ * in your k6 tests. It allows you to read files within your test scripts.
+ */
+
+/**
+ * Opens a file and returns a promise that resolves to an instance of the `File` class.
+ *
+ * Note: As the k6 init context doesn't support 'await', use the following pattern:
+ *
+ * Example:
+ * ```
+ * let fileHandle;
+ * (async function() {
+ *   fileHandle = await open("example.txt");
+ * }());
+ * ```
+ *
+ * @param path - The file path as a string. Relative paths are resolved relative to the k6 script.
+ * @returns Promise<File> - A promise that resolves to a `File` instance.
+ */
+export function open(path: string): Promise<File>;
+
+/**
+ * Represents a file and provides methods to interact with file data.
+ * This class offers read-only access to file contents.
+ */
+export class File {
+    /**
+     * The absolute path of the file.
+     *
+     * This is resolved relative to the k6 script.
+     */
+    path: string;
+
+    /**
+     * Reads the file into a specified buffer type and returns the number of bytes read.
+     * Resolves to `null` if there's nothing to read (EOF or empty file).
+     *
+     * Example:
+     * ```
+     * const buffer = new Uint8Array(100);
+     * const bytesRead = await file.read(buffer);
+     * console.log(`Read ${bytesRead} bytes`);
+     * ```
+     *
+     * @param p - A Uint8Array buffer to read the file into.
+     * @returns Promise<number> - Number of bytes read or `null`.
+     */
+    read(p: Uint8Array): Promise<number>;
+
+    /**
+     * Moves the file pointer to a new location, based on `offset` and `whence`.
+     * Resolves to the new position within the file (in bytes).
+     *
+     * When using `SeekMode.Start`, the offset must be greater than or equal to zero.
+     * When using `SeekMode.Current`, the offset can be positive or negative.
+     * When using `SeekMode.End`, the offset must be less than or equal to zero.
+     *
+     * Example:
+     * ```
+     * const newOffset = await file.seek(10, SeekMode.Start);
+     * console.log(`Pointer moved to position ${newOffset}`);
+     * ```
+     *
+     * @param offset - The offset to seek to.
+     * @param whence - The position from where offset is added (Start, Current, or End).
+     * @returns Promise<number> - The new position in the file.
+     */
+    seek(offset: number, whence: SeekMode): Promise<number>;
+
+    /**
+     * Retrieves information about the file.
+     * Resolves to a `FileInfo` object describing the file.
+     *
+     * Example:
+     * ```
+     * const fileInfo = await file.stat();
+     * console.log(`File size: ${fileInfo.size} bytes`);
+     * ```
+     *
+     * @returns Promise<FileInfo> - Information about the file.
+     */
+    stat(): Promise<FileInfo>;
+}
+
+/**
+ * Contains information about a file, including its name and size.
+ */
+export interface FileInfo {
+    name: string; // The name of the file
+    size: number; // The size of the file in bytes
+}
+
+/**
+ * Enumeration for file seek modes.
+ */
+export enum SeekMode {
+    Start = 0, // Seek from the start of the file
+    Current = 1, // Seek from the current file position.
+    End = 2, // Seek from the end of the file
+}