Phaser `EventEmitter` typings are unsatisfactory and unsafe
Maintainer antworten meist innerhalb von 3 Tagen
Dieses Issue hat noch niemand übernommen.
Bewertung
- Schwierigkeit
- 5/5
- Geschätzter Aufwand
- Über eine Woche
- Anfängerfreundlichkeit
- 35/100
- Issue-Typ
- Feature
- Klarheit
- Größtenteils klar
- Aktivitätsstatus
- Veraltet
- Tech-Stack
- javascript, typescript
- Bereich
- developer-experience
Rechercherichtung
Beginne damit, die Typings von Phaser.Events.EventEmitter und die im Issue beschriebenen Aufrufstellen von event-emitter zu prüfen, und inspiziere anschließend das blockierte Issue #7248. Erfasse vorhandene Event-Namen und Callback-Parameter, bevor du die Grenzen der event-map festlegst. Als erledigt gilt die Aufgabe, wenn die relevanten Emitter geprüfte Event-Namen und inferierte Callback-Argumente bereitstellen, ohne die bestehende Kompatibilität zu verlieren.
Vom Indexierungsmodell aus dem Issue-Text verfasst.
Beschreibung
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:
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.Eventsall being typed asstring, despite having canonical string names in the example code!
- This is only exacerbated by the properties of
- 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.
- Add any necessary
@constannotations to the types of allPhaser.Events.XYZvariables to ensure TypeScript emits them as their actual values instead ofstringorsymbol. - Convert
EventEmitterinto a genericEventEmitter<Events extends PhaserEventMap = PhaserEventMapclass via JSDoc's@templatetag. 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.) - Create unique "event map" interfaces for each instance of
EventEmitterthat is relied upon by currently functioning code. It is very important that these are interfaces, not types for the interface merging reasons highlighted above. - 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
- Vorherrschende Sprache
- JavaScript
- Sterne
- 40.7k
- Forks
- 7.2k
- PR-Merge-Kennzahlen
- Keine gemergten PRs in 30 T.
Entwicklungsumgebung
- Kein Dockerfile und keine Docker-Compose-Datei
- Hat eine Pull-Request-Vorlage
- Beitragsleitfaden lesen
Erste Schritte
- Lesen Sie das ganze Issue und danach den Beitragsleitfaden des Projekts.
- Schreiben Sie ins Issue, dass Sie es übernehmen — das erspart doppelte Arbeit.
- Forken Sie das Repository und arbeiten Sie in einem Branch.
- Öffnen Sie einen Pull Request, der die Issue-Nummer nennt.
Mehr aus phaserjs/phaser
-
Schwierigkeit 1/5 Unter einer Stunde Anfängerfreundlichkeit 80/100
Maintainer antworten meist innerhalb von 3 Tagen
-
Schwierigkeit 2/5 1-3 Stunden Anfängerfreundlichkeit 80/100
Maintainer antworten meist innerhalb von 3 Tagen
-
Type definition for TilemapLayer.getTileAt is wrongEvtl. vergeben @hkbughk hat das vor 34 Tagen übernommen. Offen
Schwierigkeit 2/5 1-3 Stunden Anfängerfreundlichkeit 70/100
Maintainer antworten meist innerhalb von 3 Tagen
-
Shader.preDestroy leaks its ShaderQuad's vertex buffer and VAO on every create/destroy cycle (4.2.1)Evtl. vergeben @k1epg01ng129-eng hat das vor 32 Tagen übernommen. Offen
Schwierigkeit 2/5 1-3 Stunden Anfängerfreundlichkeit 86/100
Maintainer antworten meist innerhalb von 3 Tagen
-
Black opaque background on transparent Phaser.Text textures in Phaser 4.2.1 on older iOS WebGLEvtl. vergeben @SamuelMalmfors hat das vor 14 Tagen übernommen. Offen
Schwierigkeit 1/5 Unter einer Stunde Anfängerfreundlichkeit 85/100
phaserjs/phaser#7392 · 1 Kommentar ·
Maintainer antworten meist innerhalb von 3 Tagen
Alle Issues in phaserjs/phaser
Ähnliche Issues
-
topg.org functionalityOffen
Schwierigkeit 2/5 1-3 Stunden Anfängerfreundlichkeit 65/100
-
needs:triage
Schwierigkeit 1/5 Unter einer Stunde Anfängerfreundlichkeit 92/100
Maintainer antworten meist innerhalb von 1 Tag
-
fix(readme): skills.sh badge says 'resource not found' and the skills.sh link is a 404; skills.sh still lists the old name tdk-skillsEvtl. vergeben @bfs2021 hat das heute übernommen. Offenarea: ci area: docs badge bug chore cleanup consistency developer-experience difficulty: easy docs documentation good first issue hygiene journey: first-visit links priority: P3 skills user-journey
Schwierigkeit 2/5 1-3 Stunden Anfängerfreundlichkeit 65/100
flisk-sh/flisk-skills#39 ·
Maintainer antworten meist innerhalb von 1 Tag
-
Schwierigkeit 2/5 1-3 Stunden Anfängerfreundlichkeit 62/100
Maintainer antworten meist innerhalb von 1 Tag
-
Bug
Schwierigkeit 2/5 1-3 Stunden Anfängerfreundlichkeit 82/100
Ionaru/easy-markdown-editor#656 ·