Add documentation for Streams API

[oleiade]

What?

This Pull Request adds documentation for the new k6/experimental/streams module.

Checklist

• 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 npm start command locally and verified that the changes look good.
• I have made my changes in the docs/sources/next folder of the documentation.

[heitortsergent]

Left a few comments but they're mostly small edits and changes to make it consistent with other parts of the docs. :) There is one empty example in the "releaseLock.md" file.

Overall it looks great, thanks for writing these docs! 🙇

[heitortsergent]

Is "high water mark" referring to the end of the file?

[oleiade]

The high water mark is a streams-specific concept. It's representing the amount of chunks a stream can pull/contain before blocking.

For instance a stream with a high water mark of five, will holds at most 5 chunks in its internal queue. So if the client is really slow to pull data from the stream, we can control the total memory and CPU usage that the streams consume for instance.

[olegbespalov]

I was a bit late with the review, so LGTM, in general, and my comments could be applied optionally in other PRs.

One thing that I feel is important to mention is Streams API from another page, like https://grafana.com/docs/k6/latest/testing-guides/running-large-tests/ where we name options about improved memory consumption.

[olegbespalov]

Suggested change

import { setTimeout } from 'k6/timers';

[olegbespalov]

Suggested change

	With the Streams API support in k6, you can start processing raw data with Javascript bit by bit, as soon as it's available, without needing to generate a full in-memory representation of the data. This helps to reduce memory usage and improve performance, especially when working with large data sets.
	With the Streams API support in k6, you can start processing raw data with JavaScript bit by bit, as soon as it's available, without needing to generate a full in-memory representation of the data. This helps to reduce memory usage and improve performance, especially when working with large data sets.

[olegbespalov]

Suggested change

import { setTimeout } from 'k6/timers';

[olegbespalov]

Suggested change

import { setTimeout } from 'k6/timers';

[olegbespalov]

Suggested change

import { setTimeout } from 'k6/timers';

[olegbespalov]

Suggested change

import { setTimeout } from 'k6/timers';

[olegbespalov]

Suggested change

import { setTimeout } from 'k6/timers';

[olegbespalov]

Suggested change

import { setTimeout } from 'k6/timers';

[olegbespalov]

Suggested change

	A promise which fullfils or rejects with a value depending on the state of the stream:
	A promise which fulfills or rejects with a value depending on the state of the stream:

[oleiade]

I'll address your comments in a separate PR 🙏🏻 🙇🏻