✨ [Stack] Add queue event

docs/api.md

@@ -240,6 +240,10 @@ soundStack.activeEvents;
 // Possible `StackState` values are: `idle`, `loading`, `playing`.
 (event: 'state', listener: (current: StackState) => void)
 
+// Event called whenever the `keys` property changes. This is useful
+// to subscribe to changes in the internal “sound queue”.
+(event: 'queue', listener: (newKeys: SoundId[], oldKeys: SoundId[]) => void)
+
 // Event called whenever the `volume` property changes.
 (event: 'volume', listener: (level: number) => void)
 

src/Stack.ts

@@ -1,7 +1,7 @@
 import {EmittenCommon} from 'emitten';
 
 import {getErrorMessage, fetchAudioBuffer, scratchBuffer} from './helpers';
-import {clamp, msToSec, secToMs} from './utilities';
+import {arrayShallowEquals, clamp, msToSec, secToMs} from './utilities';
 import {tokens} from './tokens';
 
 import type {
@@ -201,18 +201,23 @@ export class Stack extends EmittenCommon<StackEventMap> {
       ({id}) => !outOfBoundsIds.includes(id),
     );
 
-    outOfBounds.forEach((expiredSound) => {
-      expiredSound.stop();
-    });
-
+    outOfBounds.forEach((expiredSound) => expiredSound.stop());
     this.#setQueue(filteredQueue);
 
     return newSound;
   }
 
   #setQueue(value: Sound[]) {
+    const oldKeys = [...this._keys];
+    const newKeys = value.map(({id}) => id);
+    const identicalKeys = arrayShallowEquals(oldKeys, newKeys);
+
     this.#queue = value;
-    this._keys = value.map(({id}) => id);
+    this._keys = newKeys;
+
+    if (!identicalKeys) {
+      this.emit('queue', newKeys, oldKeys);
+    }
   }
 
   #setState(value: StackState) {

src/tests/Stack.test.ts

@@ -210,6 +210,28 @@ describe('Stack component', () => {
       expect(spySound3Stop).toBeCalled();
     });
 
+    it('emits `queue` event for each stopped Sound', async () => {
+      const spyQueue: StackEventMap['queue'] = vi.fn((_new, _old) => {});
+
+      mockStack.on('queue', spyQueue);
+      expect(spyQueue).not.toBeCalled();
+
+      await mockStack.prepare('One');
+      await mockStack.prepare('Two');
+      await mockStack.prepare('Three');
+
+      expect(spyQueue).toBeCalledTimes(3);
+      expect(spyQueue).toHaveBeenLastCalledWith(
+        ['One', 'Two', 'Three'],
+        ['One', 'Two'],
+      );
+
+      mockStack.stop();
+
+      expect(spyQueue).toBeCalledTimes(6);
+      expect(spyQueue).toHaveBeenLastCalledWith([], ['Three']);
+    });
+
     it('returns instance', async () => {
       await mockStack.prepare('Foo');
       const instance = mockStack.stop();
@@ -293,6 +315,31 @@ describe('Stack component', () => {
       await expect(sound).resolves.toBeInstanceOf(Sound);
       await expect(sound).resolves.toHaveProperty('id', mockSoundId);
     });
+
+    it('emits `queue` event with new and old `keys`', async () => {
+      const mockSoundId1 = 'Foo';
+      const mockSoundId2 = 'Bar';
+      const spyQueue: StackEventMap['queue'] = vi.fn((_new, _old) => {});
+
+      mockStack.on('queue', spyQueue);
+      expect(spyQueue).not.toBeCalled();
+      expect(mockStack.keys).toHaveLength(0);
+
+      await mockStack.prepare(mockSoundId1);
+
+      expect(spyQueue).toBeCalledTimes(1);
+      expect(spyQueue).toBeCalledWith([mockSoundId1], []);
+      expect(mockStack.keys).toHaveLength(1);
+
+      await mockStack.prepare(mockSoundId2);
+
+      expect(spyQueue).toBeCalledTimes(2);
+      expect(spyQueue).toBeCalledWith(
+        [mockSoundId1, mockSoundId2],
+        [mockSoundId1],
+      );
+      expect(mockStack.keys).toHaveLength(2);
+    });
   });
 
   describe('#load()', () => {

src/types.ts

@@ -51,6 +51,7 @@ export interface StackError {
 // eslint-disable-next-line @typescript-eslint/consistent-type-definitions
 export type StackEventMap = {
   state: (current: StackState) => void;
+  queue: (newKeys: SoundId[], oldKeys: SoundId[]) => void;
   volume: (level: number) => void;
   mute: (muted: boolean) => void;
   error: (message: StackError) => void;