Skip to content

Visualize Your Ideas With Code

feat(core): add `loopFor` function (#650)

Jacoba42eb520fef7
diff --git a/packages/core/src/flow/index.ts b/packages/core/src/flow/index.ts
index 1b5bb804..d4cb1a38 100644
--- a/packages/core/src/flow/index.ts
+++ b/packages/core/src/flow/index.ts
@@ -9,6 +9,7 @@ export * from './chain';
export * from './delay';
export * from './every';
export * from './loop';
+export * from './loopFor';
export * from './loopUntil';
export * from './noop';
export * from './run';
diff --git a/packages/core/src/flow/loop.ts b/packages/core/src/flow/loop.ts
index 47b2dec2..c38a69b8 100644
--- a/packages/core/src/flow/loop.ts
+++ b/packages/core/src/flow/loop.ts
@@ -16,7 +16,7 @@ decorate(loop, threadable());
* Run the given generator N times.
*
* @remarks
- * Each time iteration waits until the previous one is completed.
+ * Each iteration waits until the previous one is completed.
*
* @example
* ```ts
@@ -35,7 +35,8 @@ decorate(loop, threadable());
*
* @param iterations - The number of iterations.
* @param factory - A function creating the generator to run. Because generators
- * can't be reset, a new generator is created on each iteration.
+ * can't be reset, a new generator is created on each
+ * iteration.
*/
export function* loop(
iterations: number,
diff --git a/packages/core/src/flow/loopFor.ts b/packages/core/src/flow/loopFor.ts
new file mode 100644
index 00000000..b9521c6c
--- /dev/null
+++ b/packages/core/src/flow/loopFor.ts
@@ -0,0 +1,47 @@
+import {usePlayback, useThread} from '../utils';
+import {decorate, threadable} from '../decorators';
+import {ThreadGenerator} from '../threading';
+import {LoopCallback} from './loop';
+
+decorate(loopFor, threadable());
+/**
+ * Run a generator in a loop for the given amount of time.
+ *
+ * @remarks
+ * Generators are executed completely before the next iteration starts.
+ * An iteration is allowed to finish even when the time is up. This means that
+ * the actual duration of the loop may be longer than the given duration.
+ *
+ * @example
+ * ```ts
+ * yield* loopFor(
+ * 3,
+ * () => circle().position.x(-10, 0.1).to(10, 0.1)
+ * );
+ * ```
+ *
+ * @param seconds - The duration in seconds.
+ * @param factory - A function creating the generator to run. Because generators
+ * can't be reset, a new generator is created on each
+ * iteration.
+ */
+export function* loopFor(
+ seconds: number,
+ factory: LoopCallback,
+): ThreadGenerator {
+ const thread = useThread();
+ const step = usePlayback().framesToSeconds(1);
+ const targetTime = thread.time() + seconds;
+
+ let iteration = 0;
+ while (targetTime - step > thread.fixed) {
+ const generator = factory(iteration);
+ if (generator) {
+ yield* generator;
+ } else {
+ yield;
+ }
+ iteration += 1;
+ }
+ thread.time(targetTime);
+}
diff --git a/packages/core/src/flow/loopUntil.ts b/packages/core/src/flow/loopUntil.ts
index 95fc43ef..c02c6fb8 100644
--- a/packages/core/src/flow/loopUntil.ts
+++ b/packages/core/src/flow/loopUntil.ts
@@ -1,11 +1,17 @@
-import {useDuration, usePlayback, useThread} from '../utils';
+import {useDuration} from '../utils';
import {decorate, threadable} from '../decorators';
import {ThreadGenerator} from '../threading';
import {LoopCallback} from './loop';
+import {loopFor} from './loopFor';
decorate(loopUntil, threadable());
/**
- * Run the given generator until an event occurs.
+ * Run a generator in a loop until the given time event.
+ *
+ * @remarks
+ * Generators are executed completely before the next iteration starts.
+ * An iteration is allowed to finish even when the time is up. This means that
+ * the actual duration of the loop may be longer than the given duration.
*
* @example
* ```ts
@@ -17,25 +23,12 @@ decorate(loopUntil, threadable());
*
* @param event - The event.
* @param factory - A function creating the generator to run. Because generators
- * can't be reset, a new generator is created on each iteration.
+ * can't be reset, a new generator is created on each
+ * iteration.
*/
export function* loopUntil(
event: string,
factory: LoopCallback,
): ThreadGenerator {
- const thread = useThread();
- const step = usePlayback().framesToSeconds(1);
- const targetTime = thread.time() + useDuration(event);
-
- let iteration = 0;
- while (targetTime - step > thread.fixed) {
- const generator = factory(iteration);
- if (generator) {
- yield* generator;
- } else {
- yield;
- }
- iteration += 1;
- }
- thread.time(targetTime);
+ yield* loopFor(useDuration(event), factory);
}