Phaser `EventEmitter` typings are unsatisfactory and unsafe

未关闭
#7,249 3 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

维护者通常 3 天内回复

还没有人认领这个 Issue。

评估

难度
5/5
预计耗时
一周以上
新手友好度
35/100
Issue 类型
功能
描述清晰度
基本清楚
活跃度
停滞

调研方向

首先检查 Phaser.Events.EventEmitter 的 typings 以及 issue 中描述的 event-emitter 调用点,然后检查被阻塞的 issue #7248。在决定 event-map 的边界之前,整理现有的事件名称和回调参数。完成的标准是:相关 emitter 能够提供经过检查的事件名称和推断出的回调参数,同时不损失现有兼容性。

由索引模型根据 Issue 内容生成。

描述

🐛 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

主要语言
JavaScript
星标
40.7k
派生
7.2k
PR 合并指标
30 天内没有已合并 PR

环境准备

从这里开始

  1. 先读完整个 Issue,再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库,在一个分支上完成修改。
  4. 提交 Pull Request,并在描述里引用这个 Issue 编号。

phaserjs/phaser 的其他 Issue

查看 phaserjs/phaser 的全部 Issue

相似的 Issue

更多 JavaScript Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。