feat: advance the clock by a timer's full duration when passed

package.json

@@ -37,13 +37,15 @@
   },
   "homepage": "https://github.com/jg-wright/timeline#readme",
   "devDependencies": {
-    "@commitlint/cli": "21.0.1",
-    "@commitlint/config-conventional": "21.0.1",
+    "@commitlint/cli": "21.0.2",
+    "@commitlint/config-conventional": "21.0.2",
     "@commitlint/types": "21.0.1",
+    "@sinonjs/fake-timers": "^15.4.0",
     "@types/bun": "latest",
     "@types/js-yaml": "4.0.9",
+    "@types/sinonjs__fake-timers": "^15.0.1",
     "husky": "9.1.7",
-    "lint-staged": "17.0.5",
+    "lint-staged": "17.0.7",
     "prettier": "3.8.3",
     "rimraf": "6.1.3",
     "typescript": "6.0.3"
@@ -60,7 +62,7 @@
   },
   "dependencies": {
     "@johngw/outerface": "^2.0.2",
-    "js-yaml": "^4.1.1",
+    "js-yaml": "^4.2.0",
     "tslib": "^2.8.1"
   }
 }

src/TimelineItem/TimelineItemTimer.ts

@@ -32,6 +32,17 @@ export class TimelineItemTimer extends TimelineItem<TimelineTimer> {
     return super.onReach()
   }
 
+  /**
+   * Passing a timer advances the clock by the timer's full duration — not
+   * the 1-frame-per-character default. This is what makes a `Tn` consume
+   * `n` frames of virtual time when a timeline is iterated, so a consumer
+   * never has to wait on {@link TimelineTimer.promise} (which, on a virtual
+   * clock, would deadlock: nothing advances the clock while you await it).
+   */
+  override async onPass() {
+    await this.clock.advance(this.#timer.ms)
+  }
+
   get() {
     return this.#timer
   }

test/Timeline.test.ts

@@ -126,6 +126,13 @@ test('consuming a timeline advances its clock one frame per dash', async () => {
   expect(timeline.clock.now).toBe(6)
 })
 
+test('passing a timer advances the clock by its full duration', async () => {
+  const timeline = Timeline.create('--T10--|')
+  await asyncIterableToArray(timeline)
+  // '-'(1) '-'(1) 'T10'(10) '-'(1) '-'(1) '|'(1) => 15 frames.
+  expect(timeline.clock.now).toBe(15)
+})
+
 test('timers finish deterministically off the shared clock, no real time', async () => {
   const clock = new Clock()
   const timeline = Timeline.create('T3--|', { clock })