fix: 改进修复Scope类型推断

zhangfisher · zhangfisher · commit a30a26c530fe · 2025-09-24T11:43:39.000+08:00
diff --git a/docs/zh/guide/use/scopes.md b/docs/zh/guide/use/scopes.md
@@ -139,7 +139,8 @@ const scope = emitter.scope('user', {
 
 作用域继承父级的事件类型定义：
 
-```typescript
+```typescript twoslash
+import { FastEvent } from 'fastevent';
 interface AppEvents {
     'user/login': { userId: string };
     'user/logout': { userId: string };
@@ -152,11 +153,101 @@ const userScope = emitter.scope('user');
 // 类型检查正常
 userScope.emit('login', { userId: '123' }); // ✅
 
+userScope.on('login', (message) => {
+//            ^|
+    message.type;       // 'login'
+    message.payload     // { userId: string }
+});
+
 // 类型错误
-userScope.emit('login', { userId: 123 }); // ❌
-userScope.emit('unknown', {}); // ❌
+// userScope.emit('login', { userId: 123 }); // ❌
+// userScope.emit('unknown', {}); // ❌
 ```
 
+### 扩展类
+
+可以继承自`FastEventScope`来扩展作用域，并且提供类型推断安全。
+
+```typescript twoslash
+import { FastEvent,FastEventScope } from 'fastevent';
+interface AppEvents {
+    'user/login': { userId: string };
+    'user/logout': { userId: string };
+    'user/profile/update': { name: string };
+}
+
+const emitter = new FastEvent<AppEvents>();
+const userScope = emitter.scope('user');
+
+class Room extends FastEventScope {    
+    join(name: string) {}
+    leave() {}
+}
+
+const room2 = emitter.scope('user')
+const room = emitter.scope('user',new Room())
+
+type events = typeof room.types.events
+
+
+room.join('x')
+
+// 类型检查正常
+//userScope.emit('login', { userId: '123' }); // ✅
+
+room.on('login', (message) => {
+    message.type;       // 'login'
+    message.payload     // { userId: string }
+});
+room.once('logout', (message) => {
+    message.type;       // 'logout'
+    message.payload     // { userId: string }
+});
+room.on('profile/update', (message) => {
+    message.type;       // 'profile/update'
+    message.payload     // { name: string }
+});
+```
+
+当事件名称中包括通配符时，同样可以类型推断：
+
+```typescript twoslash
+import { FastEvent,FastEventScope } from 'fastevent';
+interface AppEvents {
+    'user/*/login': { userId: string };
+    'user/*/logout': { userId: string };
+    'user/*/profile/update': { name: string };
+}
+
+const emitter = new FastEvent<AppEvents>();
+const userScope = emitter.scope('user');
+
+class Room extends FastEventScope {    
+    join(name: string) {}
+    leave() {}
+}
+
+const room = emitter.scope('user/tom',new Room())
+
+type events = typeof room.types.events
+
+room.join('x')
+
+room.on('login', (message) => {
+    message.type;       // 'login'
+    message.payload     // { userId: string }
+});
+room.once('logout', (message) => {
+    message.type;       // 'logout'
+    message.payload     // { userId: string }
+});
+room.on('profile/update', (message) => {
+    message.type;       // 'profile/update'
+    message.payload     // { name: string }
+});
+```
+
+
 ## 使用场景
 
 ### 模块化开发
diff --git a/packages/native/src/__tests__/types/scope.types.test.ts b/packages/native/src/__tests__/types/scope.types.test.ts
@@ -3,7 +3,7 @@
 import { describe, test, expect } from 'vitest';
 import type { Equal, Expect, NotAny } from '@type-challenges/utils';
 import { FastEvent } from '../../event';
-import { FastEventScope, FastEventScopeMeta } from '../../scope';
+import { FastEventScope, FastEventScopeExtend, FastEventScopeMeta } from '../../scope';
 import { ChangeFieldType, FastEventMeta, FastEvents, RequiredItems, ScopeEvents } from '../../types';
 
 declare module '../../types' {
@@ -194,14 +194,13 @@ describe('作用域上下文类型系统', () => {
         };
         const emitter = new FastEvent<Events>();
 
-        class CustomScope extends FastEventScope<ScopeEvents<Events, 'rooms/a'>> {
+        class CustomScope extends FastEventScope {
             test() {}
         }
         type S = ScopeEvents<Events, 'rooms/a'>;
 
         function getRoomScope<Prefix extends string>(prefix: Prefix) {
-            // return emitter.scope(prefix, new CustomScope<`rooms/${Prefix}`>());
-            return emitter.scope(prefix, new CustomScope());
+            return emitter.scope(`rooms/${prefix}`, new CustomScope());
         }
 
         const scope = getRoomScope('y');
@@ -261,4 +260,65 @@ describe('作用域上下文类型系统', () => {
         b1.test;
         b1.test2;
     });
+    test('继承scope类32', () => {
+        type Events = {
+            'rooms/*/users/online': { name: string; status?: number };
+            'rooms/*/users/*/online': { name: string; status?: number };
+            'rooms/*/users/*/offline': boolean;
+            'rooms/*/posts/**': number;
+            'rooms/*/posts/*/online': number;
+        };
+        const emitter = new FastEvent<Events>();
+
+        class CustomScope extends FastEventScope {
+            join(name: string) {}
+            leave() {}
+        }
+        type S = ScopeEvents<Events, 'rooms/y'>;
+
+        function getRoom<Prefix extends string>(prefix: Prefix) {
+            return emitter.scope(`rooms/${prefix}`, new CustomScope()); // as FastEventScopeExtend<Events, `rooms/${Prefix}`, CustomScope>;
+        }
+
+        const room = getRoom('y');
+        type RoomEvents = typeof room.types.events;
+        room.join('fisher');
+        room.leave();
+        room.on('posts/a', (message) => {
+            message.type;
+            message.payload;
+        });
+        room.on('users/online', (message) => {
+            type cases = [Expect<Equal<typeof message.type, 'users/online'>>, Expect<Equal<typeof message.payload, { name: string; status?: number }>>];
+        });
+    });
+
+    test('继承scope类4', () => {
+        type Events = {
+            'rooms/*/users/online': { name: string; status?: number };
+            'rooms/*/users/*/online': { name: string; status?: number };
+            'rooms/*/users/*/offline': boolean;
+            'rooms/*/posts/**': number;
+            'rooms/*/posts/*/online': number;
+        };
+        const emitter = new FastEvent<Events>();
+
+        class User extends FastEventScope {
+            login(name: string) {}
+            logout() {}
+        }
+
+        const useScope = emitter.scope(`rooms/x`);
+        const jack = useScope.scope('users/jack', new User());
+
+        jack.login('');
+        jack.logout();
+
+        jack.on('online', (message) => {
+            type cases = [Expect<Equal<typeof message.type, 'online'>>, Expect<Equal<typeof message.payload, { name: string; status?: number }>>];
+        });
+        jack.on('offline', (message) => {
+            type cases = [Expect<Equal<typeof message.type, 'offline'>>, Expect<Equal<typeof message.payload, boolean>>];
+        });
+    });
 });
diff --git a/packages/native/src/channel.ts b/packages/native/src/channel.ts
@@ -1,20 +1,43 @@
 /**
- * 
- * 
- *  const emitter = new FastEvent()
- * 
- * 
- *  channel = emitter.channel("a.b.c.d", *(channel)=>{
- *      
- *  })
- * 
- *   emitter.on("a.b.c.d",*(channel) => {
- *      while(true){
+ *
+ * Channel 用于创建一个异步的数据流，可以用于在多个协程之间传递数据
+ *
+ *
+ *
+ *
+ * const emitter = new FastEvent()
+ *
+ *
+ * channel = emitter.channel("a.b.c.d", *(channel)=>{
+ *
+ * })
+ *
+ * channel.push(1)
+ * channel.push(2)
+ *
+ * channel.close()
+ *
+ * emitter.on("a.b.c.d",*(channel) => {
+ *    while(true){
  *         const value = yield channel.pop(1)
- *      }
- *   })
- * 
+ *    }
+ * })
+ *
+ * emitter.emit("a.b.c.d",1)
+ *
+ * for(let data of await channel){
+ *    console.log(d)
+ * }
+ *
+ * emitter.on('ssss',*(channel)=>{
+ *    while(true){
+ *         const value = yield channel.pop(1)
+ *         console.log(value)
+ *    }
+ * })
+ *
+ *
+ *
  */
 
-
-export {}
+export {};
diff --git a/packages/native/src/event.ts b/packages/native/src/event.ts
@@ -1,4 +1,4 @@
-import { FastEventScope, type FastEventScopeOptions } from './scope';
+import { FastEventScope, type FastEventScopeOptions, FastEventScopeExtend } from './scope';
 import {
     TypedFastEventListener,
     FastEventOptions,
@@ -26,6 +26,7 @@ import {
     FastMessagePayload,
     OmitTransformedEvents,
     ClosestWildcardEvents,
+    Class,
 } from './types';
 import { parseEmitArgs } from './utils/parseEmitArgs';
 import { isPathMatched } from './utils/isPathMatched';
@@ -1068,22 +1069,27 @@ export class FastEvent<
         prefix: P,
         options?: DeepPartial<FastEventScopeOptions<Meta & M, C>>,
     ): FastEventScope<ScopeEvents<AllEvents, P> & E, Meta & M, C>;
+    scope<E extends Record<string, any> = Record<string, any>, P extends string = string, C = Context, ScopeObject extends InstanceType<Class> = InstanceType<Class>>(
+        prefix: P,
+        scopeObj: ScopeObject,
+        options?: DeepPartial<FastEventScopeOptions<Meta>>,
+    ): FastEventScopeExtend<AllEvents, P, ScopeObject>;
     scope<
         E extends Record<string, any> = Record<string, any>,
         P extends string = string,
         M extends Record<string, any> = Record<string, any>,
         C = Context,
         ScopeObject extends FastEventScope<any, any, any> = FastEventScope<any, any, any>,
     >(prefix: P, scopeObj: ScopeObject, options?: DeepPartial<FastEventScopeOptions<Meta & M, C>>): ScopeObject & FastEventScope<ScopeEvents<AllEvents, P> & E, Meta & M, C>;
-    scope<E extends Record<string, any> = Record<string, any>, P extends string = string, M extends Record<string, any> = Record<string, any>, C = Context>() {
+    scope() {
         const [prefix, scopeObj, options] = parseScopeArgs(arguments, this.options.meta, this.options.context);
         let scope;
         if (scopeObj) {
             scope = scopeObj;
         } else {
-            scope = new FastEventScope<ScopeEvents<AllEvents, P> & E, Meta & M, C>();
+            scope = new FastEventScope();
         }
-        scope.bind(this as any, prefix, options as FastEventScopeOptions<Meta & M, C>);
+        scope.bind(this as any, prefix, options);
         return scope;
     }
 }
diff --git a/packages/native/src/scope.ts b/packages/native/src/scope.ts
@@ -15,14 +15,14 @@ import {
     Fallback,
     Dict,
     TypedFastEventMessageOptional,
-    FastEventListeners,
     RecordValues,
     WildcardEvents,
     FastEventListenerFlags,
     OmitTransformedEvents,
     PickTransformedEvents,
     FastEventMessage,
     ClosestWildcardEvents,
+    Class,
 } from './types';
 import { parseEmitArgs } from './utils/parseEmitArgs';
 import { parseScopeArgs } from './utils/parseScopeArgs';
@@ -186,13 +186,13 @@ export class FastEventScope<
     // 处理使用 NotPayload 标识的事件类型
     public once<T extends keyof PickTransformedEvents<Events>>(
         type: T,
-        listener: (message: PickPayload<RecordValues<WildcardEvents<Events, Exclude<T, number | symbol>>>>, args: FastEventListenerArgs<Meta>) => any | Promise<any>,
+        listener: (message: PickPayload<RecordValues<ClosestWildcardEvents<Events, Exclude<T, number | symbol>>>>, args: FastEventListenerArgs<Meta>) => any | Promise<any>,
         options?: FastEventListenOptions<Events, Meta>,
     ): FastEventSubscriber;
 
     public once<T extends Exclude<string, Types>>(
         type: T,
-        listener: TypedFastEventAnyListener<WildcardEvents<Events, T>, Meta, Fallback<Context, typeof this>>,
+        listener: TypedFastEventAnyListener<ClosestWildcardEvents<Events, T>, Meta, Fallback<Context, typeof this>>,
         options?: FastEventListenOptions,
     ): FastEventSubscriber;
     public once(): FastEventSubscriber {
@@ -342,6 +342,11 @@ export class FastEventScope<
         prefix: P,
         options?: DeepPartial<FastEventScopeOptions<Partial<FinalMeta> & M, C>>,
     ): FastEventScope<ScopeEvents<Events, P> & E, FinalMeta & M, C>;
+    scope<E extends Record<string, any> = Record<string, any>, P extends string = string, C = Context, ScopeObject extends InstanceType<Class> = InstanceType<Class>>(
+        prefix: P,
+        scopeObj: ScopeObject,
+        options?: DeepPartial<FastEventScopeOptions<Meta>>,
+    ): FastEventScopeExtend<Events, P, ScopeObject>;
     scope<
         E extends Record<string, any> = Record<string, any>,
         P extends string = string,
@@ -371,3 +376,6 @@ export class FastEventScope<
     //  eslint-disable-next-line
     onMessage(message: TypedFastEventMessage<Events, FinalMeta>, args: FastEventListenerArgs<FinalMeta>) {}
 }
+
+export type FastEventScopeExtend<Events extends Record<string, any>, Prefix extends string, T extends InstanceType<Class> = never> = FastEventScope<ScopeEvents<Events, Prefix>> &
+    T;
diff --git a/packages/native/src/types/index.ts b/packages/native/src/types/index.ts
@@ -1,7 +1,6 @@
 import type { FastListenerExecutor } from '../executors/types';
 import { type FastListenerPipe } from '../pipes/types';
 import { ExpandWildcard } from './ExpandWildcard';
-
 // 用来扩展全局Meta类型
 export interface FastEventMeta {}
 export interface FastEventMessageExtends {}
@@ -398,3 +397,5 @@ export * from './WildcardEvents';
 export * from './ScopeEvents';
 export * from './ExpandWildcard';
 export * from './Keys';
+
+export type Class = (new (...args: any[]) => any) | (abstract new (...args: any[]) => any);
