@northsea4/proxy-service 1.0.0 → 1.0.2

package/README.md

@@ -1,26 +1,14 @@
 # @northsea4/proxy-service
 
-基于 [@webext-core/proxy-service](https://github.com/aklinker1/webext-core/tree/main/packages/proxy-service) 的二次开发版本，添加了 `sender` 参数支持。
+基于 [@webext-core/proxy-service](https://github.com/aklinker1/webext-core/tree/main/packages/proxy-service) 的二次开发版本，支持 ServiceCallContext 上下文对象，提供更丰富的调用上下文信息。
 
-类型安全的浏览器扩展消息传递 API 封装，允许你在任何地方调用函数，但在后台脚本中执行。支持所有浏览器（Chrome、Firefox、Safari 等）。
+类型安全的浏览器扩展消息传递 API 封装，允许你在任何地方调用函数，但在后台脚本中执行。支持所有主流浏览器（Chrome、Firefox、Safari 等）。
 
-## 主要修改
+## 主要特性
 
-相比原版 `@webext-core/proxy-service`，本包的主要修改：
-
-**`registerService` 函数现在会将 `sender` 参数传递给服务方法：**
-
-当代理服务的方法被调用时，消息的 `sender` 对象（包含 tab、url 等信息）会作为最后一个参数传递给实际的服务方法。这使得服务可以获取调用者的上下文信息。
-
-```ts
-// 原版行为
-registerService(key, service);
-// 调用 service.method(arg1, arg2)
-
-// 修改后的行为
-registerService(key, service);
-// 调用 service.method(arg1, arg2, sender)
-```
+- 支持 ServiceCallContext：服务方法可获取完整的调用上下文（sender、requestId、timestamp、metadata 等）
+- 类型安全的服务注册与调用
+- 自动注入 context，无需手动传递
 
 ## 安装
 
@@ -34,207 +22,128 @@ pnpm add @northsea4/proxy-service
 
 ```ts
 // services/tab-service.ts
-import type { Runtime } from 'webextension-polyfill';
+import { defineProxyService, type ServiceCallContext } from '@northsea4/proxy-service'
 
-export class TabService {
-  // sender 参数会自动注入为最后一个参数
-  async getCurrentTabInfo(sender: Runtime.MessageSender) {
+class TabService {
+  async getCurrentTabInfo(context?: ServiceCallContext) {
     return {
-      tabId: sender.tab?.id,
-      url: sender.tab?.url,
-      title: sender.tab?.title,
-    };
+      tabId: context?.sender?.tab?.id,
+      url: context?.sender?.tab?.url,
+      title: context?.sender?.tab?.title,
+      requestId: context?.requestId,
+      timestamp: context?.timestamp
+    }
   }
 
-  async closeTab(tabId: number, sender: Runtime.MessageSender) {
-    console.log('closeTab called from:', sender.tab?.url);
-    await browser.tabs.remove(tabId);
+  async closeTab(tabId: number, context?: ServiceCallContext) {
+    console.log('closeTab called from:', context?.sender?.tab?.url)
+    await browser.tabs.remove(tabId)
   }
 }
-```
-
-### 2. 创建类型安全的服务键
-
-```ts
-// services/keys.ts
-import type { ProxyServiceKey } from '@northsea4/proxy-service';
-import type { TabService } from './tab-service';
 
-export const TAB_SERVICE_KEY = 'tab-service' as ProxyServiceKey<TabService>;
+export const [registerTabService, getTabService] = defineProxyService(
+  'tab-service',
+  () => new TabService()
+)
 ```
 
-### 3. 在后台脚本中注册服务
+### 2. 注册服务（Background）
 
 ```ts
-// background.ts
-import { registerService } from '@northsea4/proxy-service';
-import { TabService } from './services/tab-service';
-import { TAB_SERVICE_KEY } from './services/keys';
-
-// 注册服务
-const tabService = new TabService();
-registerService(TAB_SERVICE_KEY, tabService);
+// background/index.ts
+import { registerTabService } from '@/services/tab-service'
+
+registerTabService()
 ```
 
-### 4. 在其他上下文中使用服务
+### 3. 使用服务（任何地方）
 
 ```ts
 // content-script.ts 或 popup.ts
-import { createProxyService } from '@northsea4/proxy-service';
-import { TAB_SERVICE_KEY } from './services/keys';
+import { getTabService } from '@/services/tab-service'
 
-const tabService = createProxyService(TAB_SERVICE_KEY);
+const tabService = getTabService()
 
-// 调用服务方法（不需要手动传递 sender，它会自动注入）
-const tabInfo = await tabService.getCurrentTabInfo();
-console.log('Current tab:', tabInfo);
+// context 会自动注入
+const tabInfo = await tabService.getCurrentTabInfo()
+console.log('Current tab:', tabInfo)
 
-// 关闭当前标签页
-await tabService.closeTab(tabInfo.tabId);
+await tabService.closeTab(tabInfo.tabId)
 ```
 
-## 服务定义方式
-
-支持多种服务定义方式：
-
-### 类
+## ServiceCallContext 类型
 
 ```ts
-export class MathService {
-  add(x: number, y: number, sender: Runtime.MessageSender): number {
-    console.log('add called from:', sender.tab?.url);
-    return x + y;
-  }
-}
-```
+import type { ServiceCallContext } from '@northsea4/proxy-service'
 
-### 对象
-
-```ts
-export function createMathService() {
-  return {
-    add(x: number, y: number, sender: Runtime.MessageSender): number {
-      console.log('add called from:', sender.tab?.url);
-      return x + y;
-    },
-  };
+interface ServiceCallContext {
+  sender: Browser.Runtime.MessageSender
+  timestamp?: number
+  requestId?: string
+  metadata?: Record<string, any>
 }
 ```
 
-### 函数
+服务方法的最后一个参数应为 `context?: ServiceCallContext`，并通过 `context?.sender` 获取调用方信息。
 
-```ts
-export type SayHello = (name: string, sender: Runtime.MessageSender) => Promise<string>;
-
-export const sayHello: SayHello = async (name, sender) => {
-  console.log('sayHello called from:', sender.tab?.url);
-  return `Hello, ${name}!`;
-};
-```
+## 常见场景示例
 
-### 嵌套对象
-
-```ts
-export function createApi() {
-  return {
-    math: {
-      add(x: number, y: number, sender: Runtime.MessageSender): number {
-        return x + y;
-      },
-    },
-    string: {
-      uppercase(str: string, sender: Runtime.MessageSender): string {
-        return str.toUpperCase();
-      },
-    },
-  };
-}
-
-// 使用
-registerService('api', createApi());
-const api = createProxyService('api');
-await api.math.add(1, 2);
-await api.string.uppercase('hello');
-```
-
-## Sender 参数详解
-
-`sender` 参数是一个 `Runtime.MessageSender` 对象，包含以下信息：
-
-```ts
-interface MessageSender {
-  tab?: Tab;           // 发送消息的标签页信息
-  frameId?: number;    // 发送消息的框架 ID
-  id?: string;         // 发送消息的扩展 ID
-  url?: string;        // 发送消息的页面 URL
-  tlsChannelId?: string;
-}
-```
-
-### 使用场景示例
-
-#### 1. 获取调用者的标签页信息
+### 1. 获取调用者信息
 
 ```ts
 class ContextService {
-  async getCallerInfo(sender: Runtime.MessageSender) {
+  async getCallerInfo(context?: ServiceCallContext) {
     return {
-      fromTab: sender.tab?.id,
-      fromUrl: sender.tab?.url,
-      fromFrame: sender.frameId,
-    };
+      fromTab: context?.sender?.tab?.id,
+      fromUrl: context?.sender?.tab?.url,
+      fromFrame: context?.sender?.frameId,
+      requestId: context?.requestId,
+      timestamp: context?.timestamp
+    }
   }
 }
 ```
 
-#### 2. 根据调用者执行不同逻辑
+### 2. 权限检查
 
 ```ts
 class PermissionService {
-  async checkPermission(action: string, sender: Runtime.MessageSender) {
-    const url = sender.tab?.url;
+  async checkPermission(action: string, context?: ServiceCallContext) {
+    const url = context?.sender?.tab?.url
     if (url?.startsWith('https://trusted-domain.com')) {
-      return true;
+      return true
     }
-    return false;
+    return false
   }
 }
 ```
 
-#### 3. 操作调用者的标签页
+### 3. 日志追踪
 
 ```ts
-class TabControlService {
-  async closeCallerTab(sender: Runtime.MessageSender) {
-    if (sender.tab?.id) {
-      await browser.tabs.remove(sender.tab.id);
-    }
-  }
-
-  async reloadCallerTab(sender: Runtime.MessageSender) {
-    if (sender.tab?.id) {
-      await browser.tabs.reload(sender.tab.id);
-    }
+class LoggingService {
+  async logAction(action: string, data: any, context?: ServiceCallContext) {
+    console.log({
+      requestId: context?.requestId,
+      timestamp: context?.timestamp,
+      caller: context?.sender?.tab?.title,
+      action,
+      data
+    })
   }
 }
 ```
 
 ## TypeScript 类型支持
 
-在定义服务类型时，记得在每个方法的最后添加 `sender` 参数：
+服务方法签名应为：
 
 ```ts
-import type { Runtime } from 'webextension-polyfill';
+import type { ServiceCallContext } from '@northsea4/proxy-service'
 
-// 正确的类型定义
 interface MyService {
-  method1(arg1: string, sender: Runtime.MessageSender): Promise<void>;
-  method2(arg1: number, arg2: string, sender: Runtime.MessageSender): Promise<number>;
-}
-
-// 错误的类型定义（缺少 sender 参数）
-interface MyServiceWrong {
-  method1(arg1: string): Promise<void>;  // ❌ 运行时会出错
+  method1(arg1: string, context?: ServiceCallContext): Promise<void>
+  method2(arg1: number, arg2: string, context?: ServiceCallContext): Promise<number>
 }
 ```
 
@@ -245,53 +154,59 @@ interface MyServiceWrong {
 简化异步依赖的处理：
 
 ```ts
-import { flattenPromise } from '@northsea4/proxy-service';
+import { flattenPromise } from '@northsea4/proxy-service'
 
 function createService(dbPromise: Promise<IDBDatabase>) {
-  const db = flattenPromise(dbPromise);
+  const db = flattenPromise(dbPromise)
 
   return {
-    async getData(sender: Runtime.MessageSender) {
-      // 不需要 await dbPromise，可以直接使用
-      return await db.get('store', 'key');
-      // 而不是: await (await dbPromise).get('store', 'key');
-    },
-  };
+    async getData(context?: ServiceCallContext) {
+      return await db.get('store', 'key')
+    }
+  }
 }
 ```
 
 ### defineProxyService
 
-简化服务定义和使用的工具函数：
+简化服务定义和类型推导：
 
 ```ts
-// service.ts
-export const [registerMathService, getMathService] = defineProxyService(
-  'math-service',
-  () => new MathService(),
-);
+// services/my-service.ts
+import { defineProxyService, type ServiceCallContext } from '@northsea4/proxy-service'
+
+class MyService {
+  async add(x: number, y: number, context?: ServiceCallContext) {
+    return x + y
+  }
+}
+
+export const [registerMyService, getMyService] = defineProxyService(
+  'my-service',
+  () => new MyService()
+)
 
-// background.ts
-registerMathService();
+// background/index.ts
+registerMyService()
 
 // content-script.ts
-const mathService = getMathService();
-await mathService.add(1, 2);
+const myService = getMyService()
+await myService.add(1, 2)
 ```
 
 ## 配置选项
 
-支持 `@webext-core/messaging` 的所有配置选项：
+支持 `@webext-core/messaging` 的所有配置项：
 
 ```ts
-import { registerService, createProxyService } from '@northsea4/proxy-service';
+import { registerService, createProxyService } from '@northsea4/proxy-service'
 
 const config = {
-  logger: console,  // 自定义日志记录器
-};
+  logger: console // 自定义日志记录器
+}
 
-registerService('my-service', myService, config);
-const proxy = createProxyService('my-service', config);
+registerService('my-service', myService, config)
+const proxy = createProxyService('my-service', config)
 ```
 
 ## 开发

package/lib/index.d.ts

@@ -31,8 +31,7 @@ declare function createProxyService<T extends Service>(key: ProxyServiceKey<T> |
  */
 declare function registerService<T extends Service, K extends string = ProxyServiceKey<T> | string>(key: K, realService: T, config?: ExtensionMessagingConfig): RemoveListenerCallback;
 declare function isProxyService<T>(obj: unknown): obj is ProxyService<T>;
-interface ProxyServiceConstraint<_> {
-}
+type ProxyServiceConstraint<_> = Record<string, unknown>;
 /**
  * Used to constrain a service's type between calls to `createProxyService` and
  * `registerService`.
@@ -109,7 +108,6 @@ declare function defineProxyService<TService extends Service, TArgs extends any[
  * Configure a proxy service's behavior. It uses `@webext-core/messaging` internally, so any
  * config from `ExtensionMessagingConfig` can be passed as well.
  */
-interface ProxyServiceConfig extends ExtensionMessagingConfig {
-}
+type ProxyServiceConfig = ExtensionMessagingConfig;
 
 export { DeepAsync, type ProxyService, type ProxyServiceConfig, type ProxyServiceKey, Service, createProxyService, defineProxyService, flattenPromise, isProxyService, registerService };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@northsea4/proxy-service",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "A type-safe wrapper around the web extension messaging APIs that lets you call a function from anywhere, but execute it in the background. Forked from @webext-core/proxy-service with sender parameter support.",
   "type": "module",
   "main": "./lib/index.js",