@polyv/utils 2.1.0-beta.1 → 2.2.0-beta.1

package/dist/cjs/event.d.ts

@@ -0,0 +1,113 @@
+/**
+ * 本模块提供事件触发器类。
+ * @packageDocumentation
+ *
+ * @example
+ * ```js
+ * import { EventEmitter } from '@polyv/utils/es/event';
+ *
+ * const emitter = new EventEmitter();
+ * const context = { name: 'my name' };
+ *
+ * function eventHandler(e) {
+ *   console.log(e);
+ *   console.log(this === context); // true
+ * }
+ *
+ * // listen event
+ * emitter.on('foo', eventHandler, context);
+ *
+ * // listen once event
+ * emitter.once('foo', eventHandler, context);
+ *
+ * // fire event
+ * emitter.emit('foo', { a: 1 });
+ *
+ * // unlisten event
+ * emitter.off('foo', eventHandler);
+ *
+ * // ---------- use typescript define event parameter types ---------- //
+ * type EventParams = {
+ *   foo: string;
+ *   boo: number;
+ * };
+ *
+ * const emitter = new EventEmitter<EventParams>();
+ *
+ * emitter.on('foo', (e) => {}); // 'e' has inferred type 'string'
+ *
+ * emitter.emit('foo', 18); // Error: Argument of type 'number' is not assignable to parameter of type 'string'. (2345)
+ *
+ * // ---------- use typescript define event enum ---------- //
+ * enum TestEvent {
+ *   Foo = 'foo',
+ *   Bar = 'bar',
+ * }
+ *
+ * type TestEventParams = {
+ *   [TestEvent.Foo]: string;
+ *   [TestEvent.Bar]: number;
+ * };
+ *
+ * const emitter = new EventEmitter<TestEventParams, TestEvent>();
+ *
+ * emitter.emit(TestEvent.Foo, 'abc'); // ok
+ *
+ * emitter.emit('foo', 'abc'); // Error: Argument of type "'foo'" is not assignable to parameter of type 'TestEvent'. (2345)
+ * ```
+ */
+/**
+ * 事件类型
+ */
+export declare type EventType = string | symbol;
+/**
+ * 事件参数关系类型
+ */
+export declare type EventRelationsType = Record<EventType, unknown>;
+/**
+ * 事件回调函数类型
+ */
+export declare type EventHandler<Relations extends EventRelationsType, E extends EventType> = (params: Relations[E]) => unknown;
+export declare class EventEmitter<Relations extends EventRelationsType = EventRelationsType, Events extends EventType = string> {
+    /**
+     * 事件回调存储器
+     * @ignore
+     */
+    private __eventStore;
+    /**
+     * 添加监听事件
+     * @ignore
+     */
+    private __addOnEvent;
+    /**
+     * 监听事件
+     * @param event 事件名
+     * @param handler 回调函数
+     * @param context this 上下文
+     */
+    on<E extends Events>(event: E, handler: EventHandler<Relations, E>, context?: unknown): void;
+    /**
+     * 监听事件（一次性）
+     * @param event 事件名
+     * @param handler 回调函数
+     * @param context this 上下文
+     */
+    once<E extends Events>(event: E, handler: EventHandler<Relations, E>, context?: unknown): void;
+    /**
+     * 移除事件监听
+     * @param event 事件名
+     * @param handler 回调函数
+     */
+    off<E extends Events>(event: E, handler: unknown): void;
+    /**
+     * 触发事件
+     * @param event 事件名
+     * @param params 回调参数
+     */
+    emit<E extends Events>(event: E, params: Relations[E]): void;
+    emit<E extends Events>(event: undefined extends Relations[E] ? E : never): void;
+    /**
+     * 销毁实例
+     */
+    destroy(): void;
+}

package/dist/cjs/event.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.EventEmitter=void 0;var EventEmitter=function(){function t(){this.__eventStore={}}return t.prototype.__addOnEvent=function(t,e,n,o){if(e&&n){var r=this.__eventStore[e];r||(r=[]),r.push({type:t,handler:n,callbackHandler:n.bind(o)}),this.__eventStore[e]=r}},t.prototype.on=function(t,e,n){void 0===n&&(n=this),this.__addOnEvent("normal",t,e,n)},t.prototype.once=function(t,e,n){void 0===n&&(n=this),this.__addOnEvent("once",t,e,n)},t.prototype.off=function(t,e){var n=this.__eventStore[t];n&&(n=n.filter((function(t){return t.handler!==e})),this.__eventStore[t]=n)},t.prototype.emit=function(t,e){var n=this,o=this.__eventStore[t];o&&o.forEach((function(o){var r=o.type,i=o.handler,v=o.callbackHandler;"function"==typeof v&&v(e),"once"===r&&n.off(t,i)}))},t.prototype.destroy=function(){this.__eventStore={}},t}();exports.EventEmitter=EventEmitter;

package/dist/es/event.d.ts

@@ -0,0 +1,113 @@
+/**
+ * 本模块提供事件触发器类。
+ * @packageDocumentation
+ *
+ * @example
+ * ```js
+ * import { EventEmitter } from '@polyv/utils/es/event';
+ *
+ * const emitter = new EventEmitter();
+ * const context = { name: 'my name' };
+ *
+ * function eventHandler(e) {
+ *   console.log(e);
+ *   console.log(this === context); // true
+ * }
+ *
+ * // listen event
+ * emitter.on('foo', eventHandler, context);
+ *
+ * // listen once event
+ * emitter.once('foo', eventHandler, context);
+ *
+ * // fire event
+ * emitter.emit('foo', { a: 1 });
+ *
+ * // unlisten event
+ * emitter.off('foo', eventHandler);
+ *
+ * // ---------- use typescript define event parameter types ---------- //
+ * type EventParams = {
+ *   foo: string;
+ *   boo: number;
+ * };
+ *
+ * const emitter = new EventEmitter<EventParams>();
+ *
+ * emitter.on('foo', (e) => {}); // 'e' has inferred type 'string'
+ *
+ * emitter.emit('foo', 18); // Error: Argument of type 'number' is not assignable to parameter of type 'string'. (2345)
+ *
+ * // ---------- use typescript define event enum ---------- //
+ * enum TestEvent {
+ *   Foo = 'foo',
+ *   Bar = 'bar',
+ * }
+ *
+ * type TestEventParams = {
+ *   [TestEvent.Foo]: string;
+ *   [TestEvent.Bar]: number;
+ * };
+ *
+ * const emitter = new EventEmitter<TestEventParams, TestEvent>();
+ *
+ * emitter.emit(TestEvent.Foo, 'abc'); // ok
+ *
+ * emitter.emit('foo', 'abc'); // Error: Argument of type "'foo'" is not assignable to parameter of type 'TestEvent'. (2345)
+ * ```
+ */
+/**
+ * 事件类型
+ */
+export declare type EventType = string | symbol;
+/**
+ * 事件参数关系类型
+ */
+export declare type EventRelationsType = Record<EventType, unknown>;
+/**
+ * 事件回调函数类型
+ */
+export declare type EventHandler<Relations extends EventRelationsType, E extends EventType> = (params: Relations[E]) => unknown;
+export declare class EventEmitter<Relations extends EventRelationsType = EventRelationsType, Events extends EventType = string> {
+    /**
+     * 事件回调存储器
+     * @ignore
+     */
+    private __eventStore;
+    /**
+     * 添加监听事件
+     * @ignore
+     */
+    private __addOnEvent;
+    /**
+     * 监听事件
+     * @param event 事件名
+     * @param handler 回调函数
+     * @param context this 上下文
+     */
+    on<E extends Events>(event: E, handler: EventHandler<Relations, E>, context?: unknown): void;
+    /**
+     * 监听事件（一次性）
+     * @param event 事件名
+     * @param handler 回调函数
+     * @param context this 上下文
+     */
+    once<E extends Events>(event: E, handler: EventHandler<Relations, E>, context?: unknown): void;
+    /**
+     * 移除事件监听
+     * @param event 事件名
+     * @param handler 回调函数
+     */
+    off<E extends Events>(event: E, handler: unknown): void;
+    /**
+     * 触发事件
+     * @param event 事件名
+     * @param params 回调参数
+     */
+    emit<E extends Events>(event: E, params: Relations[E]): void;
+    emit<E extends Events>(event: undefined extends Relations[E] ? E : never): void;
+    /**
+     * 销毁实例
+     */
+    destroy(): void;
+}

package/dist/es/event.js

@@ -0,0 +1 @@
+export class EventEmitter{constructor(){this.__eventStore={}}__addOnEvent(t,e,n,o){if(!e||!n)return;let r=this.__eventStore[e];r||(r=[]),r.push({type:t,handler:n,callbackHandler:n.bind(o)}),this.__eventStore[e]=r}on(t,e,n=this){this.__addOnEvent("normal",t,e,n)}once(t,e,n=this){this.__addOnEvent("once",t,e,n)}off(t,e){let n=this.__eventStore[t];n&&(n=n.filter((t=>t.handler!==e)),this.__eventStore[t]=n)}emit(t,e){const n=this.__eventStore[t];n&&n.forEach((n=>{const{type:o,handler:r,callbackHandler:_}=n;"function"==typeof _&&_(e),"once"===o&&this.off(t,r)}))}destroy(){this.__eventStore={}}}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polyv/utils",
-  "version": "2.1.0-beta.1",
+  "version": "2.2.0-beta.1",
   "description": "Utility functions of Polyv frontend development.",
   "keywords": [
     "polyv",