Phaser `EventEmitter` typings are unsatisfactory and unsafe
Maintainer thường phản hồi trong vòng 3 ngày
Chưa có ai nhận issue này.
Đánh giá
- Độ khó
- 5/5
- Thời gian dự kiến
- Hơn một tuần
- Mức phù hợp với người mới
- 35/100
- Loại issue
- Tính năng
- Độ rõ ràng
- Khá rõ ràng
- Mức độ hoạt động
- Đình trệ
- Công nghệ
- javascript, typescript
- Lĩnh vực
- developer-experience
Hướng nghiên cứu
Bắt đầu bằng cách xem xét typings của Phaser.Events.EventEmitter và các vị trí gọi event-emitter được mô tả trong issue, sau đó kiểm tra issue bị chặn #7248. Lập bản đồ các tên event và tham số callback hiện có trước khi quyết định ranh giới của event-map. Công việc được xem là hoàn tất khi các emitter liên quan cung cấp các tên event đã được kiểm tra và các đối số callback được suy luận mà không làm mất khả năng tương thích hiện có.
Do mô hình lập chỉ mục viết ra từ nội dung của issue.
Mô tả
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
- Ngôn ngữ chính
- JavaScript
- Star
- 40.7k
- Fork
- 7.2k
- Chỉ số merge pull request
- Không có pull request nào được merge trong 30 ngày
Chuẩn bị môi trường
- Không có Dockerfile hay tệp Docker Compose
- Có mẫu pull request
- Đọc hướng dẫn đóng góp
Bắt đầu từ đâu
- Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
- Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
- Fork repository và làm thay đổi trên một nhánh.
- Mở pull request có tham chiếu số hiệu của issue.
Issue khác của phaserjs/phaser
-
Độ khó 1/5 Dưới một giờ Mức phù hợp với người mới 80/100
Maintainer thường phản hồi trong vòng 3 ngày
-
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 80/100
Maintainer thường phản hồi trong vòng 3 ngày
-
Type definition for TilemapLayer.getTileAt is wrongCó thể đã có người làm @hkbughk đã nhận 34 ngày trước. Đang mở
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 70/100
Maintainer thường phản hồi trong vòng 3 ngày
-
Shader.preDestroy leaks its ShaderQuad's vertex buffer and VAO on every create/destroy cycle (4.2.1)Có thể đã có người làm @k1epg01ng129-eng đã nhận 32 ngày trước. Đang mở
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 86/100
Maintainer thường phản hồi trong vòng 3 ngày
-
Black opaque background on transparent Phaser.Text textures in Phaser 4.2.1 on older iOS WebGLCó thể đã có người làm @SamuelMalmfors đã nhận 14 ngày trước. Đang mở
Độ khó 1/5 Dưới một giờ Mức phù hợp với người mới 85/100
phaserjs/phaser#7392 · 1 bình luận ·
Maintainer thường phản hồi trong vòng 3 ngày
Tất cả issue của phaserjs/phaser
Issue tương tự
-
enhancement ready
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 84/100
-
enhancement
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 75/100
DCGM/semant-demo#708 ·
Maintainer thường phản hồi trong vòng 1 ngày
-
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 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
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 82/100
Maintainer thường phản hồi trong vòng 1 ngày
-
Client codegen: an import repeated in an impl file is emitted twice, and the browser rejects the moduleCó thể đã có người làm @MalithaPrabhashana đã nhận hôm nay. Đang mở
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 64/100
jaseci-labs/jac#10756 ·
Maintainer thường phản hồi trong vòng 1 ngày