Phaser `EventEmitter` typings are unsatisfactory and unsafe

Aperta
#7,249 3 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 3 giorni

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
35/100
Tipo di issue
Funzionalità
Chiarezza
Abbastanza chiara
Stato di attività
Ferma
Stack tecnologico
javascript, typescript

Direzione di ricerca

Inizia esaminando i typings di Phaser.Events.EventEmitter e i punti di chiamata di event-emitter descritti nell’issue, quindi ispeziona l’issue bloccata #7248. Mappa i nomi degli eventi e i parametri dei callback esistenti prima di decidere i confini di event-map. Il lavoro è completo quando gli emitter interessati espongono nomi di eventi verificati e argomenti dei callback inferiti senza perdere la compatibilità esistente.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

🐛 TypeScript Bug

Version

  • Phaser Version: 3.90.0
  • Operating system: Ubuntu 24.04 LTS (platform agnostic issue)

Description

At the current moment, the types of Phaser.Events.EventEmitter and company look like this:

Phaser.Events.EventEmitter#once

This (especially the use of Function and any-typed callback scope) presents several pitfalls when working with the project in TypeScript:

  • No autocomplete or type safety for what event names are accepted by which emitter
    • This is only exacerbated by the properties of Phaser.Events all being typed as string, despite having canonical string names in the example code!
  • No inherent type safety or argument inference for events on callback types, requiring developers to flip back and forth between the API pages for trivial tasks

Example Test Code

import Phaser from "phaser";

const game = new Phaser.Game({type: Phaser.HEADLESS});

game.events.on("b00t", (arg1) => initializeGame(arg1)) // Oops! meant to put "boot"; this never runs
game.events.on("ready", (foo, bar) => {}) // no inference of the callback type

Additional Information

While this would be a fairly large change, it would be fairly routine to convert this code into being type safe.

  1. Add any necessary @const annotations to the types of all Phaser.Events.XYZ variables to ensure TypeScript emits them as their actual values instead of string or symbol.
  2. Convert EventEmitter into a generic EventEmitter<Events extends PhaserEventMap = PhaserEventMap class via JSDoc's @template tag. This ensures backwards compatibility for existing code that extended the generic class before it got a type parameter. (Moreover, code that wants to expand the allowed types of a given event map can extend said event map with their own constants.)
  3. Create unique "event map" interfaces for each instance of EventEmitter that is relied upon by currently functioning code. It is very important that these are interfaces, not types for the interface merging reasons highlighted above.
  4. Provide said event maps at callsites to specify what events each emitter produces.

Example snippet of what the .d.ts file could look like:

import type Phaser from "phaser";

type PhaserEventMap = {
    [key: string | symbol]: Function;
}

declare class EventEmitter<T extends PhaserEventMap = PhaserEventMap> {
    emit<E extends keyof T>(evt: E, callback: T[E], ...scope: ThisParameterType<T[E]> extends unknown ? [] : [ThisParameterType<T[E]>]): void
}

interface MyEventMap {
    'complete': (s: Phaser.Scene) => void;
    'completeWithScope': (this: 3, s: Phaser.Scene) => void;
}

// NB: We will have to use a type helper to convert from interfaces to types, as TS considers interfaces "closed"
// and requires explicit index signature declarations on anythign that implements EventMap when we really just want to check assignability
type Simplify<T> = { [KeyType in keyof T]: T[KeyType]; }

declare const e: EventEmitter<Simplify<MyEventMap>>;
e.emit("complete", (s) => s.add.arc(1, 2)); // callback has specified type of (Phaser.Scene) => void

Notably, the types accepted are already inside the code - we'd just have to convert the @param descriptions into some sort of map.

[!IMPORTANT]
I understand this would be a large change for consumers of existing packages, but this would only actually break those users using TypeScript who were previously passing incorrect callbacks. As such, I see no harm in tightening the compile-time checks to match the runtime ones.
I am willing to work on this myself, provided I have the time and get a go-ahead from someone about the approach.

Blocked by #7248

Lingua principale
JavaScript
Stelle
40.7k
Fork
7.2k
Metriche di merge delle PR
Nessuna PR unita negli ultimi 30g

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di phaserjs/phaser

Tutte le issue di phaserjs/phaser

Issue simili

Altre issue su JavaScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.