@ahoo-wang/fetcher-react 3.3.5 → 3.3.8

package/README.md

@@ -36,8 +36,9 @@ robust data fetching capabilities.
   - [usePromiseState Hook](#usepromisestate-hook)
   - [useRequestId Hook](#userequestid-hook)
   - [useLatest Hook](#uselatest-hook)
-  - [useRefs Hook](#userefs-hook)
-  - [useKeyStorage Hook](#usekeystorage-hook)
+- [useRefs Hook](#userefs-hook)
+- [useEventSubscription Hook](#useeventsubscription-hook)
+- [useKeyStorage Hook](#usekeystorage-hook)
   - [useImmerKeyStorage Hook](#useimmerkeystorage-hook)
   - [Wow Query Hooks](#wow-query-hooks)
   - [useListQuery Hook](#uselistquery-hook)
@@ -476,6 +477,47 @@ Key features:
 - **Automatic Cleanup**: Refs are cleared when component unmounts
 - **Type Safety**: Full TypeScript support for ref types
 
+### useEventSubscription Hook
+
+The `useEventSubscription` hook provides a React interface for subscribing to typed event buses. It automatically manages subscription lifecycle while offering manual control functions for additional flexibility.
+
+```typescript jsx
+import { useEventSubscription } from '@ahoo-wang/fetcher-react';
+import { eventBus } from './eventBus';
+
+function MyComponent() {
+  const { subscribe, unsubscribe } = useEventSubscription({
+    bus: eventBus,
+    handler: {
+      name: 'myEvent',
+      handle: (event) => {
+        console.log('Received event:', event);
+      }
+    }
+  });
+
+  // The hook automatically subscribes on mount and unsubscribes on unmount
+  // You can also manually control subscription if needed
+  const handleToggleSubscription = () => {
+    if (someCondition) {
+      subscribe();
+    } else {
+      unsubscribe();
+    }
+  };
+
+  return <div>My Component</div>;
+}
+```
+
+Key features:
+
+- **Automatic Lifecycle Management**: Automatically subscribes on component mount and unsubscribes on unmount
+- **Manual Control**: Provides `subscribe` and `unsubscribe` functions for additional control
+- **Type Safety**: Full TypeScript support with generic event types
+- **Error Handling**: Logs warnings for failed subscription attempts
+- **Event Bus Integration**: Works seamlessly with `@ahoo-wang/fetcher-eventbus` TypedEventBus instances
+
 ### useKeyStorage Hook
 
 The `useKeyStorage` hook provides reactive state management for a KeyStorage instance. It subscribes to storage changes and returns the current value along with a setter function. Optionally accepts a default value to use when the storage is empty.
@@ -1959,6 +2001,38 @@ An object implementing `UseRefsReturn<T>` with:
 - `RefKey = string | number | symbol`
 - `UseRefsReturn<T> extends Iterable<[RefKey, T]>`
 
+### useEventSubscription
+
+```typescript
+function useEventSubscription<EVENT = unknown>(
+  options: UseEventSubscriptionOptions<EVENT>,
+): UseEventSubscriptionReturn;
+```
+
+A React hook for subscribing to events from a typed event bus. Automatically manages subscription lifecycle while providing manual control functions.
+
+**Type Parameters:**
+
+- `EVENT`: The type of events handled by the event bus (defaults to unknown)
+
+**Parameters:**
+
+- `options`: Configuration options for the subscription
+  - `bus`: The TypedEventBus instance to subscribe to
+  - `handler`: The event handler function with name and handle method
+
+**Returns:**
+
+An object containing:
+
+- `subscribe`: Function to manually subscribe to the event bus (returns boolean success status)
+- `unsubscribe`: Function to manually unsubscribe from the event bus (returns boolean success status)
+
+**Related Types:**
+
+- `UseEventSubscriptionOptions<EVENT>`: Configuration interface with bus and handler properties
+- `UseEventSubscriptionReturn`: Return interface with subscribe and unsubscribe methods
+
 ### useKeyStorage
 
 ```typescript

package/README.zh-CN.md

@@ -35,8 +35,9 @@
   - [usePromiseState Hook](#usepromisestate-hook)
   - [useRequestId Hook](#userequestid-hook)
   - [useLatest Hook](#uselatest-hook)
-  - [useRefs Hook](#userefs-hook)
-  - [useKeyStorage Hook](#usekeystorage-hook)
+- [useRefs Hook](#userefs-hook)
+- [useEventSubscription Hook](#useeventsubscription-hook)
+- [useKeyStorage Hook](#usekeystorage-hook)
   - [useImmerKeyStorage Hook](#useimmerkeystorage-hook)
   - [Wow 查询 Hooks](#wow-查询-hooks)
   - [useListQuery Hook](#uselistquery-hook)
@@ -859,6 +860,47 @@ React hook，用于使用 Map-like 接口管理多个 refs，允许通过键动
 - `RefKey = string | number | symbol`
 - `UseRefsReturn<T> extends Iterable<[RefKey, T]>`
 
+### useEventSubscription Hook
+
+`useEventSubscription` hook 为类型化事件总线提供了 React 接口。它自动管理订阅生命周期，同时提供手动控制功能以增加灵活性。
+
+```typescript jsx
+import { useEventSubscription } from '@ahoo-wang/fetcher-react';
+import { eventBus } from './eventBus';
+
+function MyComponent() {
+  const { subscribe, unsubscribe } = useEventSubscription({
+    bus: eventBus,
+    handler: {
+      name: 'myEvent',
+      handle: (event) => {
+        console.log('收到事件:', event);
+      }
+    }
+  });
+
+  // hook 在组件挂载时自动订阅，在卸载时自动取消订阅
+  // 如需要，您也可以手动控制订阅
+  const handleToggleSubscription = () => {
+    if (someCondition) {
+      subscribe();
+    } else {
+      unsubscribe();
+    }
+  };
+
+  return <div>我的组件</div>;
+}
+```
+
+关键特性:
+
+- **自动生命周期管理**: 在组件挂载时自动订阅，在卸载时自动取消订阅
+- **手动控制**: 提供 `subscribe` 和 `unsubscribe` 函数以进行额外控制
+- **类型安全**: 完全支持 TypeScript，具有泛型事件类型
+- **错误处理**: 对失败的订阅尝试记录警告
+- **事件总线集成**: 与 `@ahoo-wang/fetcher-eventbus` TypedEventBus 实例无缝配合
+
 ### useKeyStorage
 
 ```typescript jsx

package/dist/eventbus/index.d.ts

@@ -0,0 +1,2 @@
+export * from './useEventSubscription';
+//# sourceMappingURL=index.d.ts.map

package/dist/eventbus/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/eventbus/index.ts"],"names":[],"mappings":"AAaA,cAAc,wBAAwB,CAAC"}

package/dist/eventbus/useEventSubscription.d.ts

@@ -0,0 +1,76 @@
+import { EventHandler, TypedEventBus } from '@ahoo-wang/fetcher-eventbus';
+/**
+ * Options for the useEventSubscription hook.
+ * @template EVENT - The type of events handled by the event bus.
+ */
+export interface UseEventSubscriptionOptions<EVENT> {
+    /**
+     * The typed event bus instance to subscribe to.
+     */
+    bus: TypedEventBus<EVENT>;
+    /**
+     * The event handler function that will be called when events are published.
+     */
+    handler: EventHandler<EVENT>;
+}
+/**
+ * Return type for the useEventSubscription hook.
+ */
+export interface UseEventSubscriptionReturn {
+    /**
+     * Function to manually subscribe to the event bus.
+     * @returns true if subscription was successful, false otherwise.
+     */
+    subscribe: () => boolean;
+    /**
+     * Function to manually unsubscribe from the event bus.
+     * @returns true if unsubscription was successful, false otherwise.
+     */
+    unsubscribe: () => boolean;
+}
+/**
+ * A React hook for subscribing to events from a typed event bus.
+ *
+ * This hook automatically subscribes to the event bus when the component mounts
+ * and unsubscribes when the component unmounts. It also provides manual subscribe
+ * and unsubscribe functions for additional control.
+ *
+ * @template EVENT - The type of events handled by the event bus. Defaults to unknown.
+ * @param options - Configuration options for the subscription.
+ * @param options.bus - The typed event bus instance to subscribe to.
+ * @param options.handler - The event handler function that will be called when events are published.
+ * @returns An object containing subscribe and unsubscribe functions.
+ * @throws Will throw an error if the event bus or handler is invalid.
+ *
+ * @example
+ * ```typescript
+ * import { useEventSubscription } from '@ahoo-wang/fetcher-react';
+ * import { eventBus } from './eventBus';
+ *
+ * function MyComponent() {
+ *   const { subscribe, unsubscribe } = useEventSubscription({
+ *     bus: eventBus,
+ *     handler: {
+ *       name: 'myEvent',
+ *       handle: (event) => {
+ *         console.log('Received event:', event);
+ *       }
+ *     }
+ *   });
+ *
+ *   // The hook automatically subscribes on mount and unsubscribes on unmount
+ *   // You can also manually control subscription if needed
+ *   const handleToggleSubscription = () => {
+ *     if (someCondition) {
+ *       subscribe();
+ *     } else {
+ *       unsubscribe();
+ *     }
+ *   };
+ *
+ *   return <div>My Component</div>;
+ * }
+ * ```
+ */
+export declare function useEventSubscription<EVENT = unknown>(options: UseEventSubscriptionOptions<EVENT>): UseEventSubscriptionReturn;
+//# sourceMappingURL=useEventSubscription.d.ts.map

package/dist/eventbus/useEventSubscription.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useEventSubscription.d.ts","sourceRoot":"","sources":["../../src/eventbus/useEventSubscription.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAE1E;;;GAGG;AACH,MAAM,WAAW,2BAA2B,CAAC,KAAK;IAChD;;OAEG;IACH,GAAG,EAAE,aAAa,CAAC,KAAK,CAAC,CAAC;IAC1B;;OAEG;IACH,OAAO,EAAE,YAAY,CAAC,KAAK,CAAC,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC;;;OAGG;IACH,SAAS,EAAE,MAAM,OAAO,CAAC;IACzB;;;OAGG;IACH,WAAW,EAAE,MAAM,OAAO,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,GAAG,OAAO,EAClD,OAAO,EAAE,2BAA2B,CAAC,KAAK,CAAC,GAC1C,0BAA0B,CA0B5B"}

package/dist/index.d.ts

@@ -2,4 +2,5 @@ export * from './core';
 export * from './storage';
 export * from './fetcher';
 export * from './wow';
+export * from './eventbus';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAaA,cAAc,QAAQ,CAAC;AACvB,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,OAAO,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAaA,cAAc,QAAQ,CAAC;AACvB,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,OAAO,CAAC;AACtB,cAAc,YAAY,CAAC"}