Phaser `EventEmitter` typings are unsatisfactory and unsafe
メンテナーはふだん 3 日以内に返信
まだ誰も着手していません。
評価
- 難易度
- 5/5
- 見積もり時間
- 1週間以上
- 初心者へのやさしさ
- 35/100
- issue の種類
- 機能追加
- 明瞭さ
- おおむね明確
- 活発さ
- 停滞
- 技術スタック
- javascript, typescript
調査の方向性
まず Phaser.Events.EventEmitter の typings と、issue に記載されている event-emitter の呼び出し箇所を確認し、その後、ブロックされている issue #7248 を調査します。event-map の境界を決める前に、既存のイベント名と callback パラメーターを対応付けます。関連する emitter が、既存の互換性を損なうことなく、チェック済みのイベント名と推論された callback 引数を公開できれば完了です。
索引モデルが issue の本文から書いたものです。
説明
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
- 主要言語
- JavaScript
- スター
- 40.7k
- フォーク
- 7.2k
- PR マージ指標
- 30日以内にマージされた PR はありません
環境構築
- Dockerfile・Docker Compose ファイルなし
- プルリクエストのテンプレートあり
- コントリビューションガイドを読む
はじめの一歩
- issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
- 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
- リポジトリをフォークし、ブランチを切って変更します。
- issue 番号を参照したプルリクエストを送ります。
phaserjs/phaser のほかの issue
-
難易度 1/5 1時間未満 初心者へのやさしさ 80/100
メンテナーはふだん 3 日以内に返信
-
難易度 2/5 1〜3時間 初心者へのやさしさ 80/100
メンテナーはふだん 3 日以内に返信
-
Type definition for TilemapLayer.getTileAt is wrong対応中かも @hkbughk が 34 日前に担当しました。 オープン
難易度 2/5 1〜3時間 初心者へのやさしさ 70/100
メンテナーはふだん 3 日以内に返信
-
Shader.preDestroy leaks its ShaderQuad's vertex buffer and VAO on every create/destroy cycle (4.2.1)対応中かも @k1epg01ng129-eng が 32 日前に担当しました。 オープン
難易度 2/5 1〜3時間 初心者へのやさしさ 86/100
メンテナーはふだん 3 日以内に返信
-
Black opaque background on transparent Phaser.Text textures in Phaser 4.2.1 on older iOS WebGL対応中かも @SamuelMalmfors が 14 日前に担当しました。 オープン
難易度 1/5 1時間未満 初心者へのやさしさ 85/100
phaserjs/phaser#7392 · コメント 1 件 ·
メンテナーはふだん 3 日以内に返信
phaserjs/phaser の issue をすべて見る
似ている issue
-
enhancement ready
難易度 2/5 1〜3時間 初心者へのやさしさ 84/100
-
enhancement
難易度 2/5 1〜3時間 初心者へのやさしさ 75/100
DCGM/semant-demo#708 ·
メンテナーはふだん 1 日以内に返信
-
難易度 2/5 1〜3時間 初心者へのやさしさ 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
難易度 2/5 1〜3時間 初心者へのやさしさ 82/100
メンテナーはふだん 1 日以内に返信
-
Client codegen: an import repeated in an impl file is emitted twice, and the browser rejects the module対応中かも @MalithaPrabhashana が今日担当しました。 オープン
難易度 2/5 1〜3時間 初心者へのやさしさ 64/100
jaseci-labs/jac#10756 ·
メンテナーはふだん 1 日以内に返信