Ensure the timestamp is always increasing

index.d.ts

@@ -1,5 +1,7 @@
 /**
-@returns An async iterable that yields animation frame timestamps.
+@returns An async iterable that yields animation frame [timestamps](https://developer.mozilla.org/en-US/docs/Web/API/DOMHighResTimeStamp).
+
+The first timestamp is yielded right away for easier setup.
 
 @example
 ```

index.js

@@ -20,6 +20,13 @@ export default function requestAnimationFrames() {
 			try {
 				yield performance.now();
 
+				// Ensure the RAF timestamp comes after our custom one.
+				// In some cases without this, the `performance.now()`
+				// call above would return the same timestamp as RAF.
+				await new Promise(resolve => {
+					setTimeout(resolve, 1);
+				});
+
 				while (true) {
 					yield await new Promise(resolve => { // eslint-disable-line no-await-in-loop
 						requestId = requestFrame(resolve);

readme.md

@@ -25,7 +25,9 @@ for await (const timestamp of requestAnimationFrames()) {
 
 ### requestAnimationFrames()
 
-Returns an [`AsyncIterable`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) that yields animation frame timestamps.
+Returns an [`AsyncIterable`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) that yields animation frame [timestamps](https://developer.mozilla.org/en-US/docs/Web/API/DOMHighResTimeStamp).
+
+The first timestamp is yielded right away for easier setup.
 
 ## FAQ
 
@@ -54,3 +56,7 @@ setTimeout(() => {
 	shouldStop = true;
 }, 10000);
 ```
+
+## Related
+
+- [dom-mutations](https://github.com/sindresorhus/dom-mutations) - Observe changes to the DOM using an async iterable

test.js

@@ -54,3 +54,22 @@ test('works in non-browser environment', async t => {
 	globalThis.requestAnimationFrame = originalRequestAnimationFrame;
 	globalThis.cancelAnimationFrame = originalCancelAnimationFrame;
 });
+
+test('timestamps always increasing', async t => {
+	let previousTimestamp = 0;
+	let index = 0;
+
+	for await (const currentTimestamp of requestAnimationFrames()) {
+		t.is(typeof currentTimestamp, 'number');
+
+		if (index > 0) {
+			t.true(currentTimestamp > previousTimestamp, `Timestamp ${index} (${currentTimestamp}) is not greater than Timestamp ${index - 1} (${previousTimestamp})`);
+		}
+
+		previousTimestamp = currentTimestamp;
+
+		if (++index >= 10) {
+			break;
+		}
+	}
+});