@northsea4/tab-proxy-service 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Northsea4
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,627 @@
+# @northsea4/tab-proxy-service
+
+一个类型安全的 WebExtension 工具库,支持在 content script 中注册 service,并允许从 background 或其他 tab 调用这些 service。
+
+## 特性
+
+✅ **在 Content Script 中注册 Service** - 与 `@webext-core/proxy-service` 相反,支持在 tab 中注册服务  
+✅ **Background 调用 Tab Service** - 从 background script 调用任意 tab 中的服务  
+✅ **Tab 间通信** - 支持一个 tab 调用另一个 tab 中的服务(通过 background 转发)  
+✅ **完整的类型安全** - 使用 TypeScript 泛型确保类型安全  
+✅ **自动类型推断** - 使用 `defineTabProxyService` 自动获得类型提示  
+✅ **嵌套对象支持** - 支持深层嵌套的对象和方法调用  
+✅ **自动清理** - Tab 关闭时自动注销服务  
+✅ **查询功能** - 可查询所有已注册的 tab services  
+
+## 安装
+
+```bash
+# 使用 pnpm
+pnpm add @northsea4/tab-proxy-service
+
+# 使用 npm
+npm install @northsea4/tab-proxy-service
+
+# 使用 yarn
+yarn add @northsea4/tab-proxy-service
+```
+
+## 快速开始
+
+> **💡 推荐**: 使用 `defineTabProxyService` API，它会自动提供完整的类型提示，无需手动传递泛型类型。
+
+### 步骤 1: 定义服务
+
+支持三种服务定义方式：
+
+#### 方式 A: 使用 Class (推荐)
+
+```ts
+// services/hello-service.ts
+import { defineTabProxyService } from '@northsea4/tab-proxy-service';
+
+// 使用 class 定义服务
+class HelloService {
+  async sayHello(name: string): Promise<string> {
+    return `Hello, ${name}! From tab: ${document.title}`;
+  }
+
+  async getTabInfo(): Promise<{ title: string; url: string }> {
+    return {
+      title: document.title,
+      url: window.location.href
+    };
+  }
+}
+
+// 定义服务 - 自动获得类型提示! 🎉
+export const [registerHelloService, getHelloService] = defineTabProxyService(
+  'hello-service',
+  () => new HelloService()
+);
+```
+
+#### 方式 B: 使用对象字面量
+
+```ts
+export const [registerPageService, getPageService] = defineTabProxyService(
+  'page-service',
+  () => ({
+    async getTitle() {
+      return document.title;
+    },
+    async getUrl() {
+      return window.location.href;
+    }
+  })
+);
+```
+
+#### 方式 C: 带参数的服务
+
+```ts
+class ConfigService {
+  constructor(private apiUrl: string) {}
+  
+  async fetchConfig() {
+    return fetch(`${this.apiUrl}/config`).then(r => r.json());
+  }
+}
+
+// 支持初始化参数
+export const [registerConfigService, getConfigService] = defineTabProxyService(
+  'config-service',
+  (apiUrl: string) => new ConfigService(apiUrl)
+);
+```
+
+### 步骤 2: 在 Content Script 中注册服务
+
+```ts
+// content-script.ts
+import { registerHelloService } from './services/hello-service';
+
+// 注册服务
+const cleanup = await registerHelloService();
+
+// 页面卸载时清理
+window.addEventListener('beforeunload', cleanup);
+
+// 如果服务需要参数
+// const cleanup = await registerConfigService('https://api.example.com');
+```
+
+### 步骤 3: 在 Background 中调用服务
+
+```ts
+// background.ts
+import { getHelloService } from './services/hello-service';
+
+// 获取服务 - 自动有完整的类型提示和自动补全! 🚀
+const helloService = getHelloService({ targetTabId: 123 });
+
+// sayHello 方法会有自动补全和类型检查 ✨
+const greeting = await helloService.sayHello('World');
+const info = await helloService.getTabInfo();
+```
+
+---
+
+## 传统方式 (不推荐)
+
+> **⚠️ 注意**: 以下方式需要手动传递类型参数，建议使用上面的 `defineTabProxyService` 方式。
+
+使用 `registerTabService` 和 `createTabProxyService` (需要手动传递类型参数):
+
+### 1. 在 Background 中初始化管理器
+
+首先,必须在 background script 中初始化 tab service 管理器:
+
+```ts
+// background.ts
+import { initTabServiceManager } from '@northsea4/tab-proxy-service';
+
+// 启动时初始化
+initTabServiceManager({
+  logger: console, // 可选:启用日志
+});
+```
+
+### 2. 在 Content Script 中注册 Service
+
+```ts
+// content-script.ts
+import { registerTabService } from '@northsea4/tab-proxy-service';
+
+// 定义你的 service
+const pageService = {
+  async getPageTitle(): Promise<string> {
+    return document.title;
+  },
+  
+  async getPageUrl(): Promise<string> {
+    return window.location.href;
+  },
+  
+  async extractData(): Promise<any[]> {
+    // 提取页面数据
+    return Array.from(document.querySelectorAll('.item')).map(el => ({
+      text: el.textContent,
+      href: el.getAttribute('href'),
+    }));
+  },
+};
+
+// 注册 service
+const cleanup = await registerTabService('page-service', pageService);
+
+// 页面卸载时清理
+window.addEventListener('beforeunload', cleanup);
+```
+
+### 3. 从 Background 调用 Tab Service
+
+```ts
+// background.ts
+import { createTabProxyService, type TabProxyServiceKey } from '@northsea4/tab-proxy-service';
+
+// 定义类型
+interface PageService {
+  getPageTitle(): Promise<string>;
+  getPageUrl(): Promise<string>;
+  extractData(): Promise<any[]>;
+}
+
+// 创建代理(会调用任意一个注册了该 service 的 tab)
+const pageService = createTabProxyService<PageService>('page-service');
+
+// 使用
+const title = await pageService.getPageTitle();
+const data = await pageService.extractData();
+
+console.log('Page title:', title);
+console.log('Extracted data:', data);
+```
+
+### 4. 调用特定 Tab 中的 Service
+
+```ts
+// background.ts 或 另一个 content-script.ts
+import { createTabProxyService } from '@northsea4/tab-proxy-service';
+
+// 指定目标 tab ID
+const specificTabService = createTabProxyService<PageService>('page-service', {
+  targetTabId: 123, // 目标 tab 的 ID
+});
+
+const title = await specificTabService.getPageTitle();
+```
+
+### 5. Tab 间通信示例
+
+```ts
+// content-script-a.ts (Tab A)
+import { registerTabService } from '@northsea4/tab-proxy-service';
+
+const dataService = {
+  async shareData() {
+    return { data: 'from tab A', timestamp: Date.now() };
+  },
+};
+
+await registerTabService('data-service', dataService);
+```
+
+```ts
+// content-script-b.ts (Tab B)
+import { createTabProxyService } from '@northsea4/tab-proxy-service';
+
+// Tab B 调用 Tab A 中的服务
+const dataService = createTabProxyService('data-service', {
+  targetTabId: tabAId, // Tab A 的 ID
+});
+
+const data = await dataService.shareData();
+console.log('Data from Tab A:', data);
+```
+
+## 类型安全最佳实践
+
+### 方式 1: 使用 `defineTabProxyService` (推荐)
+
+这是最简单的方式，自动获得类型提示：
+
+```ts
+// services/page-service.ts
+import { defineTabProxyService } from '@northsea4/tab-proxy-service';
+
+class PageService {
+  async getTitle(): Promise<string> {
+    return document.title;
+  }
+  
+  async extractLinks(): Promise<string[]> {
+    return Array.from(document.querySelectorAll('a'))
+      .map(a => a.href)
+      .filter(Boolean);
+  }
+}
+
+// 导出注册和获取函数
+export const [registerPageService, getPageService] = defineTabProxyService(
+  'page-service',
+  () => new PageService()
+);
+```
+
+**使用:**
+```ts
+// content-script.ts
+import { registerPageService } from './services/page-service';
+await registerPageService();
+
+// background.ts
+import { getPageService } from './services/page-service';
+const pageService = getPageService({ targetTabId: 123 });
+const title = await pageService.getTitle(); // ✅ 自动类型提示
+```
+
+### 方式 2: 使用 `TabProxyServiceKey`
+
+如果使用传统方式，推荐使用类型约束的 service key：
+
+```ts
+// service-keys.ts
+import type { TabProxyServiceKey } from '@northsea4/tab-proxy-service';
+import type { PageService } from './page-service';
+
+// 使用类型约束的 key
+export const PAGE_SERVICE_KEY = 'page-service' as TabProxyServiceKey<PageService>;
+```
+
+```ts
+// content-script.ts
+import { registerTabService } from '@northsea4/tab-proxy-service';
+import { PAGE_SERVICE_KEY } from './service-keys';
+import { createPageService } from './page-service';
+
+const pageService = createPageService();
+await registerTabService(PAGE_SERVICE_KEY, pageService);
+```
+
+```ts
+// background.ts
+import { createTabProxyService } from '@northsea4/tab-proxy-service';
+import { PAGE_SERVICE_KEY } from './service-keys';
+
+// 自动推断类型,无需手动指定泛型
+const pageService = createTabProxyService(PAGE_SERVICE_KEY);
+```
+
+## 查询已注册的 Services
+
+```ts
+import { queryTabServices } from '@northsea4/tab-proxy-service';
+
+const services = await queryTabServices();
+console.log('Registered services:', services);
+// [
+//   { tabId: 123, serviceKey: 'page-service', registeredAt: 1234567890 },
+//   { tabId: 456, serviceKey: 'data-service', registeredAt: 1234567891 },
+// ]
+```
+
+## 支持的 Service 类型
+
+### 1. Class（推荐）
+
+使用 class 定义服务提供了最好的代码组织和可维护性：
+
+```ts
+// services/data-service.ts
+import { defineTabProxyService } from '@northsea4/tab-proxy-service';
+
+class DataService {
+  private cache = new Map<string, any>();
+  
+  constructor(private apiUrl?: string) {}
+  
+  async getData(key: string): Promise<any> {
+    if (this.cache.has(key)) {
+      return this.cache.get(key);
+    }
+    
+    const data = await fetch(`${this.apiUrl || ''}/data/${key}`).then(r => r.json());
+    this.cache.set(key, data);
+    return data;
+  }
+  
+  async setData(key: string, value: any): Promise<void> {
+    this.cache.set(key, value);
+  }
+  
+  async clearCache(): Promise<void> {
+    this.cache.clear();
+  }
+}
+
+// 定义服务
+export const [registerDataService, getDataService] = defineTabProxyService(
+  'data-service',
+  (apiUrl?: string) => new DataService(apiUrl)
+);
+```
+
+**优点:**
+- ✅ 支持私有成员和状态管理
+- ✅ 支持构造函数参数
+- ✅ 良好的代码组织
+- ✅ 完整的 IDE 支持
+
+**使用:**
+```ts
+// content-script.ts
+const cleanup = await registerDataService('https://api.example.com');
+
+// background.ts
+const dataService = getDataService({ targetTabId: 123 });
+const data = await dataService.getData('users');
+```
+
+### 2. 对象字面量
+
+简单场景可以使用对象字面量：
+
+```ts
+export const [registerMyService, getMyService] = defineTabProxyService(
+  'my-service',
+  () => ({
+    async getData(): Promise<Data> {
+      // ...
+    },
+    async setData(data: Data): Promise<void> {
+      // ...
+    },
+  })
+);
+```
+
+### 3. 函数
+
+```ts
+async function myFunction(arg: string): Promise<number> {
+  // ...
+}
+
+export const [registerMyFunction, getMyFunction] = defineTabProxyService(
+  'my-function',
+  () => myFunction
+);
+```
+
+### 4. 嵌套对象
+
+```ts
+### 4. 嵌套对象
+
+支持深层嵌套的对象和方法调用：
+
+```ts
+export const [registerApiService, getApiService] = defineTabProxyService(
+  'api-service',
+  () => ({
+    users: {
+      async list(): Promise<User[]> { /* ... */ },
+      async get(id: string): Promise<User> { /* ... */ },
+    },
+    posts: {
+      async list(): Promise<Post[]> { /* ... */ },
+      async create(post: Post): Promise<void> { /* ... */ },
+    },
+  })
+);
+```
+
+**使用:**
+```ts
+const api = getApiService({ targetTabId: 123 });
+const users = await api.users.list();
+const posts = await api.posts.list();
+```
+
+## 辅助工具
+
+### flattenPromise
+
+用于简化处理 `Promise<Dependency>`:
+
+```ts
+import { flattenPromise } from '@northsea4/tab-proxy-service';
+
+function createService(dbPromise: Promise<Database>) {
+  const db = flattenPromise(dbPromise);
+  
+  return {
+    async getData() {
+      // 不需要 await (await dbPromise).query()
+      return await db.query('SELECT * FROM table');
+    }
+  };
+}
+```
+
+## 与 @webext-core/proxy-service 的对比
+
+| 功能 | @webext-core/proxy-service | @northsea4/tab-proxy-service |
+|------|----------------------------|------------------------------|
+| 在 Background 注册服务 | ✅ | ❌ |
+| 在 Content Script 注册服务 | ❌ | ✅ |
+| Background → Content 调用 | ❌ | ✅ |
+| Content → Background 调用 | ✅ | 使用 @webext-core/proxy-service |
+| Tab → Tab 调用 | ❌ | ✅ |
+| 类型安全 | ✅ | ✅ |
+| 嵌套对象支持 | ✅ | ✅ |
+
+**建议**: 两个库可以配合使用:
+- 使用 `@webext-core/proxy-service` 在 background 注册服务,供其他上下文调用
+- 使用 `@northsea4/tab-proxy-service` 在 content script 注册服务,供 background 或其他 tab 调用
+
+## 完整示例
+
+```ts
+// ===== services/page-service.ts =====
+import { defineTabProxyService } from '@northsea4/tab-proxy-service';
+
+class PageService {
+  async getTitle(): Promise<string> {
+    return document.title;
+  }
+  
+  async extractLinks(): Promise<string[]> {
+    return Array.from(document.querySelectorAll('a'))
+      .map(a => a.href)
+      .filter(Boolean);
+  }
+}
+
+export const [registerPageService, getPageService] = defineTabProxyService(
+  'page-service',
+  () => new PageService()
+);
+
+// ===== content-script.ts =====
+import { registerPageService } from './services/page-service';
+
+// 注册服务
+const cleanup = await registerPageService();
+
+// 清理
+window.addEventListener('beforeunload', cleanup);
+
+// ===== background.ts =====
+import { initTabServiceManager } from '@northsea4/tab-proxy-service';
+import { getPageService } from './services/page-service';
+
+// 初始化管理器
+initTabServiceManager({ logger: console });
+
+// 监听扩展图标点击
+browser.action.onClicked.addListener(async (tab) => {
+  if (!tab.id) return;
+  
+  // 调用当前 tab 中的服务
+  const pageService = getPageService({ targetTabId: tab.id });
+  
+  try {
+    const title = await pageService.getTitle();
+    const links = await pageService.extractLinks();
+    
+    console.log('Page title:', title);
+    console.log('Links found:', links.length);
+  } catch (error) {
+    console.error('Failed to call service:', error);
+  }
+});
+```
+
+## API 参考
+
+### `defineTabProxyService(name, init, config?)` (推荐)
+
+定义一个 tab proxy service 的辅助函数,自动提供类型提示。
+
+**参数:**
+- `name: string` - Service 的唯一名称
+- `init: (...args: TArgs) => TService` - 初始化函数,返回服务实例
+- `config?: TabProxyServiceConfig` - 可选配置
+
+**返回:** `[registerService, getService]` - 返回元组
+- `registerService: (...args: TArgs) => Promise<() => void>` - 注册服务函数
+- `getService: (options?) => TabProxyService<TService>` - 获取服务代理函数
+
+**示例:**
+```ts
+export const [registerHelloService, getHelloService] = defineTabProxyService(
+  'hello-service',
+  () => new HelloService()
+);
+```
+
+### `initTabServiceManager(config?)`
+
+在 background 中初始化 tab service 管理器。必须在使用其他功能前调用。
+
+**参数:**
+- `config?: TabProxyServiceConfig` - 可选配置
+  - `logger?: Console` - 日志记录器
+  - `timeout?: number` - 消息超时时间(毫秒)
+
+### `registerTabService(key, service, config?)`
+
+在 content script 中注册一个服务。
+
+**参数:**
+- `key: string | TabProxyServiceKey<T>` - Service key
+- `service: T` - 服务实例
+- `config?: TabProxyServiceConfig` - 可选配置
+
+**返回:** `Promise<() => void>` - 返回清理函数
+
+### `createTabProxyService(key, options?)`
+
+创建一个 tab service 的代理。
+
+**参数:**
+- `key: string | TabProxyServiceKey<T>` - Service key
+- `options?`:
+  - `targetTabId?: number` - 目标 tab ID(可选)
+  - `config?: TabProxyServiceConfig` - 配置(可选)
+
+**返回:** `TabProxyService<T>` - Service 代理
+
+### `queryTabServices()`
+
+查询所有已注册的 tab services。
+
+**返回:** `Promise<TabServiceInfo[]>` - Service 信息列表
+
+### `flattenPromise(promise)`
+
+扁平化 Promise,用于简化处理 `Promise<Dependency>`。
+
+**参数:**
+- `promise: Promise<T>` - 要扁平化的 Promise
+
+**返回:** `TabProxyService<T>` - 扁平化后的代理
+
+## License
+
+MIT
+
+## 作者
+
+nornorlunn
+
+## 致谢
+
+本项目受 [@webext-core/proxy-service](https://github.com/aklinker1/webext-core) 启发,实现了相反方向的代理服务功能。

package/lib/index.d.ts

@@ -0,0 +1,247 @@
+/**
+ * 将类型转换为 Promise 类型(如果还不是)
+ */
+type Promisify<T> = T extends Promise<any> ? T : Promise<T>;
+/**
+ * Service 可以是函数、对象或嵌套的服务集合
+ */
+type Service = ((...args: any[]) => Promise<any>) | {
+    [key: string]: any | Service;
+};
+/**
+ * 递归地将 service 中的所有方法转换为异步方法
+ */
+type DeepAsync<TService> = TService extends (...args: any) => any ? ToAsyncFunction<TService> : TService extends {
+    [key: string]: any;
+} ? {
+    [fn in keyof TService]: DeepAsync<TService[fn]>;
+} : never;
+type ToAsyncFunction<T extends (...args: any) => any> = (...args: Parameters<T>) => Promisify<ReturnType<T>>;
+/**
+ * Tab Proxy Service 类型,确保所有方法都是异步的
+ */
+type TabProxyService<T> = T extends DeepAsync<T> ? T : DeepAsync<T>;
+/**
+ * 约束 service key 的类型
+ */
+interface TabProxyServiceConstraint<_> {
+}
+/**
+ * 带有类型约束的 service key,用于确保类型安全
+ *
+ * @example
+ * ```ts
+ * import type { TabProxyServiceKey } from '@northsea4/tab-proxy-service';
+ * import type { MyService } from './my-service';
+ *
+ * export const MY_SERVICE_KEY = 'my-service' as TabProxyServiceKey<MyService>;
+ * ```
+ */
+type TabProxyServiceKey<T> = string & TabProxyServiceConstraint<T>;
+/**
+ * Service 方法调用时的上下文信息
+ * 作为服务方法的最后一个可选参数传递
+ *
+ * @example
+ * ```ts
+ * class MyService {
+ *   async doSomething(arg1: string, context?: ServiceCallContext) {
+ *     console.log('Called by:', context?.originalSender?.tab?.title)
+ *     console.log('Request ID:', context?.requestId)
+ *   }
+ * }
+ * ```
+ */
+interface ServiceCallContext {
+    /** 当前消息的 sender (转发消息时是 background 的 sender) */
+    sender: any;
+    /** 原始调用方的 sender (真正发起调用的地方) */
+    originalSender?: any;
+    /** 调用时间戳 */
+    timestamp?: number;
+    /** 请求 ID，用于追踪和调试 */
+    requestId?: string;
+    /** 其他元数据 */
+    metadata?: Record<string, any>;
+}
+/**
+ * 消息协议定义
+ */
+interface ProxyMessage {
+    /** 调用路径(用于嵌套对象) */
+    path?: string[];
+    /** 函数参数 */
+    args: any[];
+    /** 目标 tab ID(可选,用于 tab-to-tab 通信) */
+    targetTabId?: number;
+    /** 原始调用方的 sender */
+    originalSender?: any;
+    /** 调用时间戳 */
+    timestamp?: number;
+    /** 请求 ID */
+    requestId?: string;
+}
+/**
+ * 消息响应类型
+ */
+type ProxyResponse = any;
+/**
+ * Tab Service 注册信息
+ */
+interface TabServiceInfo {
+    /** Tab ID */
+    tabId: number;
+    /** Service key */
+    serviceKey: string;
+    /** 注册时间 */
+    registeredAt: number;
+}
+/**
+ * Service 配置选项
+ */
+interface TabProxyServiceConfig {
+    /** 日志记录器 */
+    logger?: Pick<Console, 'log' | 'warn' | 'error' | 'debug'>;
+    /** 消息超时时间(毫秒) */
+    timeout?: number;
+}
+
+/**
+ * 在 background 中初始化 tab service 管理器
+ * 必须在 background script 启动时调用
+ */
+declare function initTabServiceManager(config?: TabProxyServiceConfig): void;
+/**
+ * 在 content script 中注册一个 service
+ *
+ * @param key Service key
+ * @param realService 实际的 service 实例
+ * @param config 配置选项
+ * @returns 返回清理函数,调用后注销 service
+ *
+ * @example
+ * ```ts
+ * // content-script.ts
+ * import { registerTabService } from '@northsea4/tab-proxy-service';
+ *
+ * const myService = {
+ *   async getData() {
+ *     return [1, 2, 3];
+ *   }
+ * };
+ *
+ * const cleanup = await registerTabService('my-service', myService);
+ *
+ * // 页面卸载时清理
+ * window.addEventListener('beforeunload', cleanup);
+ * ```
+ */
+declare function registerTabService<T extends Service, K extends string = TabProxyServiceKey<T> | string>(key: K, realService: T, config?: TabProxyServiceConfig): Promise<() => void>;
+/**
+ * 创建一个 tab service 的代理
+ * 可以在 background、popup 或其他 content script 中调用
+ *
+ * @param key Service key
+ * @param options 可选参数:targetTabId 指定目标 tab,config 配置
+ * @returns 返回 service 代理
+ *
+ * @example
+ * ```ts
+ * // background.ts - 调用任意 tab 中的 service
+ * import { createTabProxyService } from '@northsea4/tab-proxy-service';
+ *
+ * const myService = createTabProxyService<MyService>('my-service');
+ * const data = await myService.getData();
+ *
+ * // 或者指定特定的 tab
+ * const myServiceInTab = createTabProxyService<MyService>('my-service', { targetTabId: 123 });
+ * ```
+ *
+ * @example
+ * ```ts
+ * // popup.ts - 从 popup 调用 tab 中的 service
+ * const myService = createTabProxyService<MyService>('my-service', { targetTabId: 123 });
+ * const result = await myService.someMethod();
+ * ```
+ *
+ * @example
+ * ```ts
+ * // content-script-a.ts - 调用另一个 tab 中的 service
+ * const serviceInOtherTab = createTabProxyService<OtherService>('other-service', { targetTabId: 456 });
+ * await serviceInOtherTab.doSomething();
+ * ```
+ */
+declare function createTabProxyService<T extends Service>(key: TabProxyServiceKey<T> | string, options?: {
+    targetTabId?: number;
+    config?: TabProxyServiceConfig;
+}): TabProxyService<T>;
+/**
+ * 查询所有已注册的 tab services
+ *
+ * @returns 返回所有已注册的 service 信息
+ *
+ * @example
+ * ```ts
+ * const services = await queryTabServices();
+ * console.log('Registered services:', services);
+ * // [{ tabId: 123, serviceKey: 'my-service', registeredAt: 1234567890 }]
+ * ```
+ */
+declare function queryTabServices(): Promise<TabServiceInfo[]>;
+/**
+ * 定义一个 tab proxy service 的辅助函数
+ * 类似于 @northsea4/proxy-service 的 defineProxyService
+ *
+ * @param name Service 的唯一名称
+ * @param init 初始化函数，返回实际的 service 实例
+ * @param config 配置选项
+ * @returns 返回 [registerService, getService] 元组
+ *
+ * @example
+ * ```ts
+ * // hello-service.ts
+ * export const [registerHelloService, getHelloService] = defineTabProxyService(
+ *   'hello-service',
+ *   () => ({
+ *     async sayHello(name: string) {
+ *       return `Hello, ${name}!`;
+ *     }
+ *   })
+ * );
+ *
+ * // content-script.ts - 注册服务
+ * const cleanup = await registerHelloService();
+ *
+ * // background.ts - 使用服务(自动有类型提示)
+ * const helloService = getHelloService({ targetTabId: 123 });
+ * const greeting = await helloService.sayHello('World'); // 类型安全!
+ * ```
+ */
+declare function defineTabProxyService<TService extends Service, TArgs extends any[]>(name: string, init: (...args: TArgs) => TService, config?: TabProxyServiceConfig): [
+    registerService: (...args: TArgs) => Promise<() => void>,
+    getService: (options?: {
+        targetTabId?: number;
+        config?: TabProxyServiceConfig;
+    }) => TabProxyService<TService>
+];
+/**
+ * 辅助函数:扁平化 Promise
+ * 用于简化处理 Promise<Dependency>
+ *
+ * @example
+ * ```ts
+ * function createService(dependencyPromise: Promise<SomeDependency>) {
+ *   const dependency = flattenPromise(dependencyPromise);
+ *
+ *   return {
+ *     async doSomething() {
+ *       await dependency.someAsyncWork();
+ *       // 而不是 await (await dependencyPromise).someAsyncWork();
+ *     }
+ *   }
+ * }
+ * ```
+ */
+declare function flattenPromise<T>(promise: Promise<T>): TabProxyService<T>;
+
+export { type DeepAsync, type Promisify, type ProxyMessage, type ProxyResponse, type Service, type ServiceCallContext, type TabProxyService, type TabProxyServiceConfig, type TabProxyServiceKey, type TabServiceInfo, createTabProxyService, defineTabProxyService, flattenPromise, initTabServiceManager, queryTabServices, registerTabService };

package/lib/index.js

@@ -0,0 +1,329 @@
+import Browser from 'webextension-polyfill';
+
+// src/index.ts
+var MESSAGE_TYPES = {
+  /** Content script 向 background 注册 service */
+  REGISTER_TAB_SERVICE: "tab-proxy:register",
+  /** Content script 向 background 注销 service */
+  UNREGISTER_TAB_SERVICE: "tab-proxy:unregister",
+  /** 调用 tab 中的 service */
+  CALL_TAB_SERVICE: "tab-proxy:call",
+  /** Background 转发消息到目标 tab */
+  FORWARD_TO_TAB: "tab-proxy:forward",
+  /** 查询已注册的 tab services */
+  QUERY_TAB_SERVICES: "tab-proxy:query"
+};
+var TabServiceRegistry = class {
+  constructor() {
+    /** 存储所有已注册的 tab services: serviceKey -> Set<tabId> */
+    this.services = /* @__PURE__ */ new Map();
+    /** 存储 service 监听器: tabId -> Map<serviceKey, listener> */
+    this.listeners = /* @__PURE__ */ new Map();
+  }
+  /**
+   * 注册一个 tab service
+   */
+  register(tabId, serviceKey) {
+    if (!this.services.has(serviceKey)) {
+      this.services.set(serviceKey, /* @__PURE__ */ new Set());
+    }
+    this.services.get(serviceKey).add(tabId);
+  }
+  /**
+   * 注销一个 tab service
+   */
+  unregister(tabId, serviceKey) {
+    const tabs = this.services.get(serviceKey);
+    if (tabs) {
+      tabs.delete(tabId);
+      if (tabs.size === 0) {
+        this.services.delete(serviceKey);
+      }
+    }
+  }
+  /**
+   * 注销某个 tab 的所有 services
+   */
+  unregisterAll(tabId) {
+    for (const [serviceKey, tabs] of this.services.entries()) {
+      tabs.delete(tabId);
+      if (tabs.size === 0) {
+        this.services.delete(serviceKey);
+      }
+    }
+    this.listeners.delete(tabId);
+  }
+  /**
+   * 获取某个 service 的所有 tab IDs
+   */
+  getTabs(serviceKey) {
+    return Array.from(this.services.get(serviceKey) || []);
+  }
+  /**
+   * 获取所有已注册的 services 信息
+   */
+  getAllServices() {
+    const result = [];
+    const now = Date.now();
+    for (const [serviceKey, tabs] of this.services.entries()) {
+      for (const tabId of tabs) {
+        result.push({
+          tabId,
+          serviceKey,
+          registeredAt: now
+          // 简化处理,实际可以记录真实注册时间
+        });
+      }
+    }
+    return result;
+  }
+  /**
+   * 存储监听器
+   */
+  setListener(tabId, serviceKey, listener) {
+    if (!this.listeners.has(tabId)) {
+      this.listeners.set(tabId, /* @__PURE__ */ new Map());
+    }
+    this.listeners.get(tabId).set(serviceKey, listener);
+  }
+  /**
+   * 获取监听器
+   */
+  getListener(tabId, serviceKey) {
+    return this.listeners.get(tabId)?.get(serviceKey);
+  }
+};
+var registry = new TabServiceRegistry();
+var isInBackground = false;
+var globalLogger;
+function initTabServiceManager(config) {
+  isInBackground = true;
+  const logger = config?.logger;
+  globalLogger = logger;
+  Browser.runtime.onMessage.addListener((message, sender) => {
+    switch (message.type) {
+      case MESSAGE_TYPES.REGISTER_TAB_SERVICE: {
+        if (!sender.tab?.id) {
+          return Promise.reject(
+            new Error("REGISTER_TAB_SERVICE must be called from a content script")
+          );
+        }
+        const tabId = sender.tab.id;
+        const serviceKey = message.serviceKey;
+        registry.register(tabId, serviceKey);
+        logger?.debug(`[TabProxyService] Service "${serviceKey}" registered in tab ${tabId}`);
+        return Promise.resolve({ success: true });
+      }
+      case MESSAGE_TYPES.UNREGISTER_TAB_SERVICE: {
+        if (!sender.tab?.id) {
+          return Promise.reject(
+            new Error("UNREGISTER_TAB_SERVICE must be called from a content script")
+          );
+        }
+        const tabId = sender.tab.id;
+        const serviceKey = message.serviceKey;
+        registry.unregister(tabId, serviceKey);
+        logger?.debug(`[TabProxyService] Service "${serviceKey}" unregistered from tab ${tabId}`);
+        return Promise.resolve({ success: true });
+      }
+      case MESSAGE_TYPES.CALL_TAB_SERVICE: {
+        const { serviceKey, targetTabId, payload } = message;
+        const callerId = sender.tab?.id ?? "popup/background";
+        logger?.debug(
+          `[TabProxyService] CALL_TAB_SERVICE for service "${serviceKey}" from ${callerId}`
+        );
+        const requestId = `${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
+        const enrichedPayload = {
+          ...payload,
+          originalSender: sender,
+          timestamp: Date.now(),
+          requestId
+        };
+        if (targetTabId !== void 0) {
+          return forwardToTab(targetTabId, serviceKey, enrichedPayload, logger);
+        }
+        const tabs = registry.getTabs(serviceKey);
+        if (tabs.length === 0) {
+          return Promise.reject(new Error(`No tab found with service "${serviceKey}" registered`));
+        }
+        return forwardToTab(tabs[0], serviceKey, enrichedPayload, logger);
+      }
+      case MESSAGE_TYPES.QUERY_TAB_SERVICES: {
+        return Promise.resolve(registry.getAllServices());
+      }
+    }
+  });
+  Browser.tabs.onRemoved.addListener((tabId) => {
+    registry.unregisterAll(tabId);
+    logger?.debug(`[TabProxyService] All services unregistered from tab ${tabId}`);
+  });
+  logger?.debug("[TabProxyService] Manager initialized");
+}
+async function forwardToTab(tabId, serviceKey, payload, logger) {
+  try {
+    const response = await Browser.tabs.sendMessage(tabId, {
+      type: MESSAGE_TYPES.FORWARD_TO_TAB,
+      timestamp: Date.now(),
+      serviceKey,
+      payload
+    });
+    return response;
+  } catch (error) {
+    logger?.error(`[TabProxyService] Failed to forward message to tab ${tabId}:`, error);
+    throw error;
+  }
+}
+async function registerTabService(key, realService, config) {
+  const logger = config?.logger;
+  await Browser.runtime.sendMessage({
+    type: MESSAGE_TYPES.REGISTER_TAB_SERVICE,
+    timestamp: Date.now(),
+    serviceKey: key
+  });
+  logger?.debug(`[TabProxyService] Registered service "${key}" in content script`);
+  const messageListener = (message, sender) => {
+    logger?.debug(`[TabProxyService] Received message in service "${key}":`, message, sender);
+    if (message.type !== MESSAGE_TYPES.FORWARD_TO_TAB || message.serviceKey !== key) {
+      return;
+    }
+    return (async () => {
+      const payload = message.payload;
+      try {
+        const method = payload.path == null ? realService : get(realService, payload.path);
+        if (typeof method !== "function") {
+          throw new Error(`Method not found: ${payload.path?.join(".")}`);
+        }
+        const context = {
+          sender,
+          originalSender: payload.originalSender,
+          timestamp: payload.timestamp,
+          requestId: payload.requestId,
+          metadata: {}
+        };
+        const result = await Promise.resolve(method.bind(realService)(...payload.args, context));
+        return result;
+      } catch (error) {
+        logger?.error(`[TabProxyService] Error executing service "${key}":`, error);
+        throw error;
+      }
+    })();
+  };
+  Browser.runtime.onMessage.addListener(messageListener);
+  return () => {
+    Browser.runtime.onMessage.removeListener(messageListener);
+    Browser.runtime.sendMessage({
+      type: MESSAGE_TYPES.UNREGISTER_TAB_SERVICE,
+      serviceKey: key
+    }).catch(() => {
+    });
+    logger?.debug(`[TabProxyService] Unregistered service "${key}"`);
+  };
+}
+function createTabProxyService(key, options) {
+  const targetTabId = options?.targetTabId;
+  const config = options?.config;
+  return createProxy(key, targetTabId, config);
+}
+function createProxy(serviceKey, targetTabId, config, path) {
+  const wrapped = (() => {
+  });
+  const proxy = new Proxy(wrapped, {
+    async apply(_target, _thisArg, args) {
+      const payload = {
+        path,
+        args
+      };
+      if (isInBackground) {
+        const logger = config?.logger || globalLogger;
+        const requestId = `${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
+        const enrichedPayload = {
+          ...payload,
+          // 在 background 中直接调用时,originalSender 为 undefined
+          originalSender: void 0,
+          timestamp: Date.now(),
+          requestId
+        };
+        let actualTabId = targetTabId;
+        if (!actualTabId) {
+          throw new Error(
+            `targetTabId is required when calling service "${serviceKey}" from background. Please specify the target tab ID explicitly.`
+          );
+        }
+        logger?.debug(
+          `[TabProxyService] Direct call from background to service "${serviceKey}" in tab ${actualTabId}`
+        );
+        return await forwardToTab(actualTabId, serviceKey, enrichedPayload, logger);
+      }
+      try {
+        const response = await Browser.runtime.sendMessage({
+          type: MESSAGE_TYPES.CALL_TAB_SERVICE,
+          timestamp: Date.now(),
+          serviceKey,
+          targetTabId,
+          payload
+        });
+        return response;
+      } catch (error) {
+        config?.logger?.error(`[TabProxyService] Error calling service "${serviceKey}":`, error);
+        throw error;
+      }
+    },
+    get(target, propertyName, receiver) {
+      if (typeof propertyName === "symbol") {
+        return Reflect.get(target, propertyName, receiver);
+      }
+      return createProxy(
+        serviceKey,
+        targetTabId,
+        config,
+        path == null ? [propertyName] : path.concat([propertyName])
+      );
+    }
+  });
+  return proxy;
+}
+async function queryTabServices() {
+  const response = await Browser.runtime.sendMessage({
+    type: MESSAGE_TYPES.QUERY_TAB_SERVICES
+  });
+  return response;
+}
+function get(obj, path) {
+  if (path.length === 0) {
+    return obj;
+  }
+  return path.reduce((acc, key) => acc?.[key], obj);
+}
+function defineTabProxyService(name, init, config) {
+  const key = name;
+  return [
+    // registerService
+    async (...args) => {
+      const service = init(...args);
+      return await registerTabService(key, service, config);
+    },
+    // getService
+    (options) => createTabProxyService(key, options)
+  ];
+}
+function flattenPromise(promise) {
+  return new Proxy({}, {
+    get(_, prop) {
+      if (typeof prop === "symbol") {
+        return void 0;
+      }
+      return async (...args) => {
+        const resolved = await promise;
+        const method = resolved[prop];
+        if (typeof method === "function") {
+          return method.apply(resolved, args);
+        }
+        return method;
+      };
+    }
+  });
+}
+
+export { createTabProxyService, defineTabProxyService, flattenPromise, initTabServiceManager, queryTabServices, registerTabService };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import Browser from 'webextension-polyfill'\n\nimport type {\n  ProxyMessage,\n  ProxyResponse,\n  Service,\n  ServiceCallContext,\n  TabProxyService,\n  TabProxyServiceConfig,\n  TabProxyServiceKey,\n  TabServiceInfo\n} from './types'\n\n// 重新导出类型，供外部使用\nexport type {\n  Service,\n  ServiceCallContext,\n  TabProxyService,\n  TabProxyServiceKey,\n  TabProxyServiceConfig,\n  TabServiceInfo,\n  ProxyMessage,\n  ProxyResponse,\n  Promisify,\n  DeepAsync\n} from './types'\n\n/**\n * 消息类型枚举\n */\nconst MESSAGE_TYPES = {\n  /** Content script 向 background 注册 service */\n  REGISTER_TAB_SERVICE: 'tab-proxy:register',\n  /** Content script 向 background 注销 service */\n  UNREGISTER_TAB_SERVICE: 'tab-proxy:unregister',\n  /** 调用 tab 中的 service */\n  CALL_TAB_SERVICE: 'tab-proxy:call',\n  /** Background 转发消息到目标 tab */\n  FORWARD_TO_TAB: 'tab-proxy:forward',\n  /** 查询已注册的 tab services */\n  QUERY_TAB_SERVICES: 'tab-proxy:query'\n} as const\n\n/**\n * 全局状态管理\n */\nclass TabServiceRegistry {\n  /** 存储所有已注册的 tab services: serviceKey -> Set<tabId> */\n  private services = new Map<string, Set<number>>()\n\n  /** 存储 service 监听器: tabId -> Map<serviceKey, listener> */\n  private listeners = new Map<number, Map<string, (message: any) => any>>()\n\n  /**\n   * 注册一个 tab service\n   */\n  register(tabId: number, serviceKey: string): void {\n    if (!this.services.has(serviceKey)) {\n      this.services.set(serviceKey, new Set())\n    }\n    this.services.get(serviceKey)!.add(tabId)\n  }\n\n  /**\n   * 注销一个 tab service\n   */\n  unregister(tabId: number, serviceKey: string): void {\n    const tabs = this.services.get(serviceKey)\n    if (tabs) {\n      tabs.delete(tabId)\n      if (tabs.size === 0) {\n        this.services.delete(serviceKey)\n      }\n    }\n  }\n\n  /**\n   * 注销某个 tab 的所有 services\n   */\n  unregisterAll(tabId: number): void {\n    for (const [serviceKey, tabs] of this.services.entries()) {\n      tabs.delete(tabId)\n      if (tabs.size === 0) {\n        this.services.delete(serviceKey)\n      }\n    }\n    this.listeners.delete(tabId)\n  }\n\n  /**\n   * 获取某个 service 的所有 tab IDs\n   */\n  getTabs(serviceKey: string): number[] {\n    return Array.from(this.services.get(serviceKey) || [])\n  }\n\n  /**\n   * 获取所有已注册的 services 信息\n   */\n  getAllServices(): TabServiceInfo[] {\n    const result: TabServiceInfo[] = []\n    const now = Date.now()\n\n    for (const [serviceKey, tabs] of this.services.entries()) {\n      for (const tabId of tabs) {\n        result.push({\n          tabId,\n          serviceKey,\n          registeredAt: now // 简化处理,实际可以记录真实注册时间\n        })\n      }\n    }\n\n    return result\n  }\n\n  /**\n   * 存储监听器\n   */\n  setListener(tabId: number, serviceKey: string, listener: (message: any) => any): void {\n    if (!this.listeners.has(tabId)) {\n      this.listeners.set(tabId, new Map())\n    }\n    this.listeners.get(tabId)!.set(serviceKey, listener)\n  }\n\n  /**\n   * 获取监听器\n   */\n  getListener(tabId: number, serviceKey: string): ((message: any) => any) | undefined {\n    return this.listeners.get(tabId)?.get(serviceKey)\n  }\n}\n\n// 全局 registry 实例(仅在 background 中使用)\nconst registry = new TabServiceRegistry()\n\n// 标记当前是否在 background 环境中\nlet isInBackground = false\n\n// 全局 logger 实例\nlet globalLogger: Pick<Console, 'log' | 'warn' | 'error' | 'debug'> | undefined\n\n/**\n * 在 background 中初始化 tab service 管理器\n * 必须在 background script 启动时调用\n */\nexport function initTabServiceManager(config?: TabProxyServiceConfig): void {\n  isInBackground = true\n\n  const logger = config?.logger\n\n  globalLogger = logger\n\n  // 监听来自 content scripts 的注册/注销消息\n  Browser.runtime.onMessage.addListener((message, sender) => {\n    switch (message.type) {\n      case MESSAGE_TYPES.REGISTER_TAB_SERVICE: {\n        // 注册操作必须来自 content script（需要 tab.id）\n        if (!sender.tab?.id) {\n          return Promise.reject(\n            new Error('REGISTER_TAB_SERVICE must be called from a content script')\n          )\n        }\n        const tabId = sender.tab.id\n        const serviceKey = message.serviceKey\n        registry.register(tabId, serviceKey)\n        logger?.debug(`[TabProxyService] Service \"${serviceKey}\" registered in tab ${tabId}`)\n        return Promise.resolve({ success: true })\n      }\n\n      case MESSAGE_TYPES.UNREGISTER_TAB_SERVICE: {\n        // 注销操作必须来自 content script（需要 tab.id）\n        if (!sender.tab?.id) {\n          return Promise.reject(\n            new Error('UNREGISTER_TAB_SERVICE must be called from a content script')\n          )\n        }\n        const tabId = sender.tab.id\n        const serviceKey = message.serviceKey\n        registry.unregister(tabId, serviceKey)\n        logger?.debug(`[TabProxyService] Service \"${serviceKey}\" unregistered from tab ${tabId}`)\n        return Promise.resolve({ success: true })\n      }\n\n      case MESSAGE_TYPES.CALL_TAB_SERVICE: {\n        // 调用操作可以来自任何地方（popup、background、content script）\n        const { serviceKey, targetTabId, payload } = message\n        const callerId = sender.tab?.id ?? 'popup/background'\n        logger?.debug(\n          `[TabProxyService] CALL_TAB_SERVICE for service \"${serviceKey}\" from ${callerId}`\n        )\n\n        // 生成请求 ID 用于追踪\n        const requestId = `${Date.now()}-${Math.random().toString(36).substring(2, 11)}`\n\n        // 添加原始 sender 信息到 payload\n        const enrichedPayload: ProxyMessage = {\n          ...payload,\n          originalSender: sender,\n          timestamp: Date.now(),\n          requestId\n        }\n\n        // 如果指定了目标 tab,直接转发\n        if (targetTabId !== undefined) {\n          return forwardToTab(targetTabId, serviceKey, enrichedPayload, logger)\n        }\n\n        // 否则选择任意一个可用的 tab\n        const tabs = registry.getTabs(serviceKey)\n        if (tabs.length === 0) {\n          return Promise.reject(new Error(`No tab found with service \"${serviceKey}\" registered`))\n        }\n\n        // 使用第一个可用的 tab\n        return forwardToTab(tabs[0], serviceKey, enrichedPayload, logger)\n      }\n\n      case MESSAGE_TYPES.QUERY_TAB_SERVICES: {\n        // 查询操作可以来自任何地方\n        return Promise.resolve(registry.getAllServices())\n      }\n    }\n  })\n\n  // 监听 tab 关闭事件,清理注册信息\n  Browser.tabs.onRemoved.addListener((tabId) => {\n    registry.unregisterAll(tabId)\n    logger?.debug(`[TabProxyService] All services unregistered from tab ${tabId}`)\n  })\n\n  logger?.debug('[TabProxyService] Manager initialized')\n}\n\n/**\n * 转发消息到指定 tab\n */\nasync function forwardToTab(\n  tabId: number,\n  serviceKey: string,\n  payload: ProxyMessage,\n  logger?: Pick<Console, 'log' | 'warn' | 'error' | 'debug'>\n): Promise<ProxyResponse> {\n  try {\n    const response = await Browser.tabs.sendMessage(tabId, {\n      type: MESSAGE_TYPES.FORWARD_TO_TAB,\n      timestamp: Date.now(),\n      serviceKey,\n      payload\n    })\n    return response\n  } catch (error) {\n    logger?.error(`[TabProxyService] Failed to forward message to tab ${tabId}:`, error)\n    throw error\n  }\n}\n\n/**\n * 在 content script 中注册一个 service\n *\n * @param key Service key\n * @param realService 实际的 service 实例\n * @param config 配置选项\n * @returns 返回清理函数,调用后注销 service\n *\n * @example\n * ```ts\n * // content-script.ts\n * import { registerTabService } from '@northsea4/tab-proxy-service';\n *\n * const myService = {\n *   async getData() {\n *     return [1, 2, 3];\n *   }\n * };\n *\n * const cleanup = await registerTabService('my-service', myService);\n *\n * // 页面卸载时清理\n * window.addEventListener('beforeunload', cleanup);\n * ```\n */\nexport async function registerTabService<\n  T extends Service,\n  K extends string = TabProxyServiceKey<T> | string\n>(key: K, realService: T, config?: TabProxyServiceConfig): Promise<() => void> {\n  const logger = config?.logger\n\n  // 向 background 注册\n  await Browser.runtime.sendMessage({\n    type: MESSAGE_TYPES.REGISTER_TAB_SERVICE,\n    timestamp: Date.now(),\n    serviceKey: key\n  })\n\n  logger?.debug(`[TabProxyService] Registered service \"${key}\" in content script`)\n\n  // 监听来自 background 的转发消息\n  const messageListener = (message: any, sender: Browser.Runtime.MessageSender) => {\n    logger?.debug(`[TabProxyService] Received message in service \"${key}\":`, message, sender)\n\n    // 先检查消息类型，如果不匹配，立即返回 undefined（不是 Promise）\n    if (message.type !== MESSAGE_TYPES.FORWARD_TO_TAB || message.serviceKey !== key) {\n      return // 返回 undefined，不是 Promise<undefined>\n    }\n\n    return (async () => {\n      const payload: ProxyMessage = message.payload\n\n      try {\n        // 获取要调用的方法\n        const method = payload.path == null ? realService : get(realService, payload.path)\n\n        if (typeof method !== 'function') {\n          throw new Error(`Method not found: ${payload.path?.join('.')}`)\n        }\n\n        // 构造 ServiceCallContext 对象\n        const context: ServiceCallContext = {\n          sender,\n          originalSender: payload.originalSender,\n          timestamp: payload.timestamp,\n          requestId: payload.requestId,\n          metadata: {}\n        }\n\n        // 调用方法并返回结果，将 context 作为最后一个参数传递\n        const result = await Promise.resolve(method.bind(realService)(...payload.args, context))\n        return result\n      } catch (error) {\n        logger?.error(`[TabProxyService] Error executing service \"${key}\":`, error)\n        throw error\n      }\n    })()\n  }\n\n  Browser.runtime.onMessage.addListener(messageListener)\n\n  // 返回清理函数\n  return () => {\n    Browser.runtime.onMessage.removeListener(messageListener)\n    Browser.runtime\n      .sendMessage({\n        type: MESSAGE_TYPES.UNREGISTER_TAB_SERVICE,\n        serviceKey: key\n      })\n      .catch(() => {\n        // 忽略错误,可能 background 已经关闭\n      })\n    logger?.debug(`[TabProxyService] Unregistered service \"${key}\"`)\n  }\n}\n\n/**\n * 创建一个 tab service 的代理\n * 可以在 background、popup 或其他 content script 中调用\n *\n * @param key Service key\n * @param options 可选参数:targetTabId 指定目标 tab,config 配置\n * @returns 返回 service 代理\n *\n * @example\n * ```ts\n * // background.ts - 调用任意 tab 中的 service\n * import { createTabProxyService } from '@northsea4/tab-proxy-service';\n *\n * const myService = createTabProxyService<MyService>('my-service');\n * const data = await myService.getData();\n *\n * // 或者指定特定的 tab\n * const myServiceInTab = createTabProxyService<MyService>('my-service', { targetTabId: 123 });\n * ```\n *\n * @example\n * ```ts\n * // popup.ts - 从 popup 调用 tab 中的 service\n * const myService = createTabProxyService<MyService>('my-service', { targetTabId: 123 });\n * const result = await myService.someMethod();\n * ```\n *\n * @example\n * ```ts\n * // content-script-a.ts - 调用另一个 tab 中的 service\n * const serviceInOtherTab = createTabProxyService<OtherService>('other-service', { targetTabId: 456 });\n * await serviceInOtherTab.doSomething();\n * ```\n */\nexport function createTabProxyService<T extends Service>(\n  key: TabProxyServiceKey<T> | string,\n  options?: {\n    targetTabId?: number\n    config?: TabProxyServiceConfig\n  }\n): TabProxyService<T> {\n  const targetTabId = options?.targetTabId\n  const config = options?.config\n\n  return createProxy(key, targetTabId, config)\n}\n\n/**\n * 创建深层代理对象\n * 所有属性访问都返回新的代理,函数调用时发送消息到 background\n */\nfunction createProxy<T>(\n  serviceKey: string,\n  targetTabId: number | undefined,\n  config: TabProxyServiceConfig | undefined,\n  path?: string[]\n): TabProxyService<T> {\n  const wrapped = (() => {}) as TabProxyService<T>\n\n  const proxy = new Proxy(wrapped, {\n    async apply(_target, _thisArg, args) {\n      const payload: ProxyMessage = {\n        path,\n        args\n      }\n\n      // 如果在 background 环境中,直接调用内部转发函数,不需要通过消息传递\n      if (isInBackground) {\n        const logger = config?.logger || globalLogger\n\n        // 生成请求 ID 用于追踪\n        const requestId = `${Date.now()}-${Math.random().toString(36).substring(2, 11)}`\n\n        const enrichedPayload: ProxyMessage = {\n          ...payload,\n          // 在 background 中直接调用时,originalSender 为 undefined\n          originalSender: undefined,\n          timestamp: Date.now(),\n          requestId\n        }\n\n        // 确定目标 tab\n        let actualTabId = targetTabId\n        if (!actualTabId) {\n          // 在 background 中必须明确指定 targetTabId，不能随机选择\n          throw new Error(\n            `targetTabId is required when calling service \"${serviceKey}\" from background. ` +\n            `Please specify the target tab ID explicitly.`\n          )\n        }\n\n        logger?.debug(\n          `[TabProxyService] Direct call from background to service \"${serviceKey}\" in tab ${actualTabId}`\n        )\n        return await forwardToTab(actualTabId, serviceKey, enrichedPayload, logger)\n      }\n\n      // 发送消息到 background,由 background 转发到对应的 tab\n      try {\n        const response = await Browser.runtime.sendMessage({\n          type: MESSAGE_TYPES.CALL_TAB_SERVICE,\n          timestamp: Date.now(),\n          serviceKey,\n          targetTabId,\n          payload\n        })\n        return response\n      } catch (error) {\n        config?.logger?.error(`[TabProxyService] Error calling service \"${serviceKey}\":`, error)\n        throw error\n      }\n    },\n\n    get(target, propertyName, receiver) {\n      // 返回 symbol 属性的值\n      if (typeof propertyName === 'symbol') {\n        return Reflect.get(target, propertyName, receiver)\n      }\n\n      // 为常规属性返回新的代理\n      return createProxy(\n        serviceKey,\n        targetTabId,\n        config,\n        path == null ? [propertyName] : path.concat([propertyName])\n      )\n    }\n  })\n\n  return proxy\n}\n\n/**\n * 查询所有已注册的 tab services\n *\n * @returns 返回所有已注册的 service 信息\n *\n * @example\n * ```ts\n * const services = await queryTabServices();\n * console.log('Registered services:', services);\n * // [{ tabId: 123, serviceKey: 'my-service', registeredAt: 1234567890 }]\n * ```\n */\nexport async function queryTabServices(): Promise<TabServiceInfo[]> {\n  const response = await Browser.runtime.sendMessage({\n    type: MESSAGE_TYPES.QUERY_TAB_SERVICES\n  })\n  return response\n}\n\n/**\n * 从对象中按路径获取值\n */\nfunction get(obj: any, path: string[]): any {\n  if (path.length === 0) {\n    return obj\n  }\n  return path.reduce((acc, key) => acc?.[key], obj)\n}\n\n/**\n * 定义一个 tab proxy service 的辅助函数\n * 类似于 @northsea4/proxy-service 的 defineProxyService\n *\n * @param name Service 的唯一名称\n * @param init 初始化函数，返回实际的 service 实例\n * @param config 配置选项\n * @returns 返回 [registerService, getService] 元组\n *\n * @example\n * ```ts\n * // hello-service.ts\n * export const [registerHelloService, getHelloService] = defineTabProxyService(\n *   'hello-service',\n *   () => ({\n *     async sayHello(name: string) {\n *       return `Hello, ${name}!`;\n *     }\n *   })\n * );\n *\n * // content-script.ts - 注册服务\n * const cleanup = await registerHelloService();\n *\n * // background.ts - 使用服务(自动有类型提示)\n * const helloService = getHelloService({ targetTabId: 123 });\n * const greeting = await helloService.sayHello('World'); // 类型安全!\n * ```\n */\nexport function defineTabProxyService<TService extends Service, TArgs extends any[]>(\n  name: string,\n  init: (...args: TArgs) => TService,\n  config?: TabProxyServiceConfig\n): [\n  registerService: (...args: TArgs) => Promise<() => void>,\n  getService: (options?: {\n    targetTabId?: number\n    config?: TabProxyServiceConfig\n  }) => TabProxyService<TService>\n] {\n  const key = name as TabProxyServiceKey<TService>\n\n  return [\n    // registerService\n    async (...args: TArgs): Promise<() => void> => {\n      const service = init(...args)\n      return await registerTabService(key, service, config)\n    },\n    // getService\n    (options?: { targetTabId?: number; config?: TabProxyServiceConfig }) =>\n      createTabProxyService<TService>(key, options)\n  ]\n}\n\n/**\n * 辅助函数:扁平化 Promise\n * 用于简化处理 Promise<Dependency>\n *\n * @example\n * ```ts\n * function createService(dependencyPromise: Promise<SomeDependency>) {\n *   const dependency = flattenPromise(dependencyPromise);\n *\n *   return {\n *     async doSomething() {\n *       await dependency.someAsyncWork();\n *       // 而不是 await (await dependencyPromise).someAsyncWork();\n *     }\n *   }\n * }\n * ```\n */\nexport function flattenPromise<T>(promise: Promise<T>): TabProxyService<T> {\n  return new Proxy({} as TabProxyService<T>, {\n    get(_, prop) {\n      if (typeof prop === 'symbol') {\n        return undefined\n      }\n      return async (...args: any[]) => {\n        const resolved = await promise\n        const method = (resolved as any)[prop]\n        if (typeof method === 'function') {\n          return method.apply(resolved, args)\n        }\n        return method\n      }\n    }\n  })\n}\n"]}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@northsea4/tab-proxy-service",
+  "version": "0.2.0",
+  "description": "A type-safe wrapper for calling services registered in content scripts from background or other tabs, with automatic type inference",
+  "author": "nornorlunn",
+  "license": "MIT",
+  "type": "module",
+  "main": "./lib/index.js",
+  "module": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js"
+    },
+    "./types": {
+      "types": "./lib/types.d.ts"
+    }
+  },
+  "files": [
+    "lib"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest"
+  },
+  "dependencies": {
+    "@webext-core/messaging": "^2.3.0",
+    "webextension-polyfill": "^0.10.0"
+  },
+  "devDependencies": {
+    "@types/webextension-polyfill": "^0.10.7",
+    "tsup": "^8.0.1",
+    "typescript": "^5.1.6",
+    "vitest": "^1.0.0"
+  },
+  "keywords": [
+    "webextension",
+    "chrome-extension",
+    "firefox-addon",
+    "proxy",
+    "service",
+    "content-script",
+    "tab",
+    "messaging"
+  ]
+}