Phaser `EventEmitter` typings are unsatisfactory and unsafe
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
- Ambito
- developer-experience
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
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
- Lingua principale
- JavaScript
- Stelle
- 40.7k
- Fork
- 7.2k
- Metriche di merge delle PR
- Nessuna PR unita negli ultimi 30g
Preparare l'ambiente
- Nessun Dockerfile né file Docker Compose
- Ha un modello di pull request
- Leggi la guida per i contributori
Come iniziare
- Leggi tutta la issue e poi la guida ai contributi del progetto.
- Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
- Fai un fork del repository e lavora su un branch.
- Apri una pull request che faccia riferimento al numero della issue.
Altre issue di phaserjs/phaser
-
Difficoltà 1/5 Meno di un'ora Idoneità per principianti 80/100
I maintainer di solito rispondono entro 3 giorni
-
Difficoltà 2/5 1-3 ore Idoneità per principianti 80/100
I maintainer di solito rispondono entro 3 giorni
-
Type definition for TilemapLayer.getTileAt is wrongForse già presa @hkbughk l’ha presa 34 giorni fa. Aperta
Difficoltà 2/5 1-3 ore Idoneità per principianti 70/100
I maintainer di solito rispondono entro 3 giorni
-
Shader.preDestroy leaks its ShaderQuad's vertex buffer and VAO on every create/destroy cycle (4.2.1)Forse già presa @k1epg01ng129-eng l’ha presa 32 giorni fa. Aperta
Difficoltà 2/5 1-3 ore Idoneità per principianti 86/100
I maintainer di solito rispondono entro 3 giorni
-
Black opaque background on transparent Phaser.Text textures in Phaser 4.2.1 on older iOS WebGLForse già presa @SamuelMalmfors l’ha presa 14 giorni fa. Aperta
Difficoltà 1/5 Meno di un'ora Idoneità per principianti 85/100
phaserjs/phaser#7392 · 1 commento ·
I maintainer di solito rispondono entro 3 giorni
Tutte le issue di phaserjs/phaser
Issue simili
-
enhancement ready
Difficoltà 2/5 1-3 ore Idoneità per principianti 84/100
-
enhancement
Difficoltà 2/5 1-3 ore Idoneità per principianti 75/100
DCGM/semant-demo#708 ·
I maintainer di solito rispondono entro 1 giorno
-
Difficoltà 2/5 1-3 ore Idoneità per principianti 78/100
-
agents area: runtime automation chore cli consistency dependencies developer-experience difficulty: easy documentation enhancement good first issue help wanted hygiene json-output priority: P3 starters tests
Difficoltà 2/5 1-3 ore Idoneità per principianti 82/100
I maintainer di solito rispondono entro 1 giorno
-
Client codegen: an import repeated in an impl file is emitted twice, and the browser rejects the moduleForse già presa @MalithaPrabhashana l’ha presa oggi. Aperta
Difficoltà 2/5 1-3 ore Idoneità per principianti 64/100
jaseci-labs/jac#10756 ·
I maintainer di solito rispondono entro 1 giorno