Skip to content

feat: add Player.destroy() for unmounting players - #111

Merged
luwes merged 2 commits into
masterfrom
feat/player-destroy
Nov 3, 2026
Merged

luwes merged 2 commits into
masterfrom
feat/player-destroy

Conversation

@luwes

@luwes luwes commented Nov 3, 2026 •

Copy link
Copy Markdown
Collaborator

Adds player.destroy() so apps can tear down a player when its iframe goes away, for example when a React or Vue component unmounts. It's additive, and nothing new goes over postMessage. Two commits:

1. fix: ignore ready from other or removed iframes

A listener-less ready from any iframe on the same origin fired every player's ready callbacks, even for players whose own iframe wasn't ready. This is the "inconsistencies if you have multiple players on the page" the README warns about. It also woke players whose iframe had been removed: remounting an embed with the same src made the old player pick up the new iframe's ready and, before #94, crash with Cannot read properties of null (reading 'postMessage') (#93, #75).

ready is now handled only when it comes from this player's own iframe, and never from an iframe that is no longer in the page. Other events are unchanged.

2. feat: add Player.destroy() for unmounting players

Each player adds a window message listener that could never be removed, so a player whose iframe was gone stayed alive and kept handling messages. destroy() is the minimum needed to stop that:

playerjs.Player.prototype.destroy = function(){
  window.removeEventListener('message', this._onMessage, false);
  this.destroyed = true;
};

init keeps a reference to the listener (this._onMessage), and send() returns false once destroyed, so later calls never reach the iframe. Once the app drops its reference, the player can be garbage-collected.

What it deliberately doesn't do: unregister listeners inside the iframe. Usually the iframe is removed right after, which makes that pointless. If the iframe stays on the page, call off() first, as the README documents.

Tests

  • Remounting the same src, without destroy() and after it: no page errors, the old player's callbacks don't fire, and the new player works.
  • After destroy(): no callbacks fire, the window listener is gone (receive is never called), send() returns false, and no calls reach the iframe. Calling it twice is safe.
  • destroy() before ready: queued calls are never sent.
  • Two players from the same origin: one iframe's ready doesn't fire the other player's ready.

Removing either line of destroy() makes a test fail. The full suite passes with 72 tests, and the related tests passed 70 of 70 repeated runs.

README documents destroy() with a React example.

Related: #45, a closed report of methods called in ready having no effect after replacing the iframe, as if they went "to the player in the iframe I removed". That fits the ready fix in commit 1.

Closes #93
Closes #75

luwes added 2 commits November 2, 2026 21:57
A listener-less 'ready' from any iframe on the same origin fired every
Player's ready callbacks, even Players whose own iframe wasn't ready. The
README warns about this as "inconsistencies if you have multiple players
on the page".

It also woke Players whose iframe had been removed: remounting an embed
with the same src made the old Player pick up the new iframe's ready and,
before #94, crash sending its queue to the removed iframe (#93, #75).

Only handle 'ready' when it comes from this Player's own iframe, and never
from an iframe that is no longer in the page. Other events are unchanged.
Each Player added a window message listener that could never be removed,
so a Player whose iframe was gone stayed alive and kept handling messages.

destroy() removes that listener and makes later calls no-ops. If the iframe
stays on the page, call off() first so it stops sending events.
@luwes
luwes force-pushed the feat/player-destroy branch from 96a2424 to 340510b Compare November 3, 2026 05:59
@luwes
luwes merged commit 8254574 into master Nov 3, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

1 participant