@northsea4/proxy-service 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2022 Aaron
+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,313 @@
+# @northsea4/proxy-service
+
+基于 [@webext-core/proxy-service](https://github.com/aklinker1/webext-core/tree/main/packages/proxy-service) 的二次开发版本，添加了 `sender` 参数支持。
+
+类型安全的浏览器扩展消息传递 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)
+```
+
+## 安装
+
+```bash
+pnpm add @northsea4/proxy-service
+```
+
+## 快速开始
+
+### 1. 定义服务
+
+```ts
+// services/tab-service.ts
+import type { Runtime } from 'webextension-polyfill';
+
+export class TabService {
+  // sender 参数会自动注入为最后一个参数
+  async getCurrentTabInfo(sender: Runtime.MessageSender) {
+    return {
+      tabId: sender.tab?.id,
+      url: sender.tab?.url,
+      title: sender.tab?.title,
+    };
+  }
+
+  async closeTab(tabId: number, sender: Runtime.MessageSender) {
+    console.log('closeTab called from:', 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>;
+```
+
+### 3. 在后台脚本中注册服务
+
+```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);
+```
+
+### 4. 在其他上下文中使用服务
+
+```ts
+// content-script.ts 或 popup.ts
+import { createProxyService } from '@northsea4/proxy-service';
+import { TAB_SERVICE_KEY } from './services/keys';
+
+const tabService = createProxyService(TAB_SERVICE_KEY);
+
+// 调用服务方法（不需要手动传递 sender，它会自动注入）
+const tabInfo = await tabService.getCurrentTabInfo();
+console.log('Current tab:', tabInfo);
+
+// 关闭当前标签页
+await tabService.closeTab(tabInfo.tabId);
+```
+
+## 服务定义方式
+
+支持多种服务定义方式：
+
+### 类
+
+```ts
+export class MathService {
+  add(x: number, y: number, sender: Runtime.MessageSender): number {
+    console.log('add called from:', sender.tab?.url);
+    return x + y;
+  }
+}
+```
+
+### 对象
+
+```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;
+    },
+  };
+}
+```
+
+### 函数
+
+```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. 获取调用者的标签页信息
+
+```ts
+class ContextService {
+  async getCallerInfo(sender: Runtime.MessageSender) {
+    return {
+      fromTab: sender.tab?.id,
+      fromUrl: sender.tab?.url,
+      fromFrame: sender.frameId,
+    };
+  }
+}
+```
+
+#### 2. 根据调用者执行不同逻辑
+
+```ts
+class PermissionService {
+  async checkPermission(action: string, sender: Runtime.MessageSender) {
+    const url = sender.tab?.url;
+    if (url?.startsWith('https://trusted-domain.com')) {
+      return true;
+    }
+    return false;
+  }
+}
+```
+
+#### 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);
+    }
+  }
+}
+```
+
+## TypeScript 类型支持
+
+在定义服务类型时，记得在每个方法的最后添加 `sender` 参数：
+
+```ts
+import type { Runtime } from 'webextension-polyfill';
+
+// 正确的类型定义
+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>;  // ❌ 运行时会出错
+}
+```
+
+## 高级功能
+
+### flattenPromise
+
+简化异步依赖的处理：
+
+```ts
+import { flattenPromise } from '@northsea4/proxy-service';
+
+function createService(dbPromise: Promise<IDBDatabase>) {
+  const db = flattenPromise(dbPromise);
+
+  return {
+    async getData(sender: Runtime.MessageSender) {
+      // 不需要 await dbPromise，可以直接使用
+      return await db.get('store', 'key');
+      // 而不是: await (await dbPromise).get('store', 'key');
+    },
+  };
+}
+```
+
+### defineProxyService
+
+简化服务定义和使用的工具函数：
+
+```ts
+// service.ts
+export const [registerMathService, getMathService] = defineProxyService(
+  'math-service',
+  () => new MathService(),
+);
+
+// background.ts
+registerMathService();
+
+// content-script.ts
+const mathService = getMathService();
+await mathService.add(1, 2);
+```
+
+## 配置选项
+
+支持 `@webext-core/messaging` 的所有配置选项：
+
+```ts
+import { registerService, createProxyService } from '@northsea4/proxy-service';
+
+const config = {
+  logger: console,  // 自定义日志记录器
+};
+
+registerService('my-service', myService, config);
+const proxy = createProxyService('my-service', config);
+```
+
+## 开发
+
+```bash
+# 构建
+pnpm build
+
+# 开发模式（监听文件变化）
+pnpm dev
+```
+
+## License
+
+MIT
+
+## 致谢
+
+本项目基于 [@webext-core/proxy-service](https://github.com/aklinker1/webext-core/tree/main/packages/proxy-service) 开发，感谢原作者的优秀工作。

package/lib/index.d.ts

@@ -0,0 +1,115 @@
+import { ExtensionMessagingConfig, RemoveListenerCallback } from '@webext-core/messaging';
+import { DeepAsync, Service } from './types.js';
+export { ServiceCallContext } from './types.js';
+
+/**
+ * A type that ensures a service has only async methods.
+ *
+ * - ***If all methods are async***, it returns the original type.
+ * - ***If the service has non-async methods***, it returns a `DeepAsync` of the service.
+ */
+type ProxyService<T> = T extends DeepAsync<T> ? T : DeepAsync<T>;
+/**
+ * Create a proxy service that uses the message APIs to proxy function calls to
+ * the real service registered in the background with `registerService`.
+ *
+ * @param key The service key to listen for, must be the same string as the one
+ *            used in `registerService`.
+ */
+declare function createProxyService<T extends Service>(key: ProxyServiceKey<T> | string, config?: ExtensionMessagingConfig): ProxyService<T>;
+/**
+ * Sets up message listeners that receive messages from proxies created with
+ * `createProxyService`.
+ *
+ * @param key The service key to listen for, must be the same string as the one
+ *            used in `createProxyService`.
+ * @param realService The real service instance that will handle the requests.
+ *
+ * **Modified from @webext-core/proxy-service:**
+ * The `context` parameter (ServiceCallContext) is now passed as the last argument to all service methods,
+ * allowing services to access message sender information, timestamp, requestId, and other metadata.
+ */
+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<_> {
+}
+/**
+ * Used to constrain a service's type between calls to `createProxyService` and
+ * `registerService`.
+ *
+ * @example
+ * ```ts
+ * // utils/proxy-service-keys.ts
+ * import type { ProxyServiceKey } from '@northsea4/proxy-service';
+ * import type { MathService } from './math-service';
+ *
+ * export const PROXY_SERVICE_KEY = 'math-service' as ProxyServiceKey<MathService>;
+ *
+ * // background.ts
+ * import { PROXY_SERVICE_KEY } from './utils/proxy-service-keys';
+ *
+ * registerService(PROXY_SERVICE_KEY, new MathService())
+ *
+ * // content-script.ts
+ * import { PROXY_SERVICE_KEY } from './utils/proxy-service-keys';
+ *
+ * const mathService = await createProxyService(PROXY_SERVICE_KEY);
+ * ```
+ */
+type ProxyServiceKey<T> = string & ProxyServiceConstraint<T>;
+/**
+ * Given a promise of a variable, return a proxy to that awaits the promise internally so you don't
+ * have to call `await` twice.
+ *
+ * > This can be used to simplify handling `Promise<Dependency>` passed in your services.
+ *
+ * @example
+ * ```ts
+ * function createService(dependencyPromise: Promise<SomeDependency>) {
+ *   const dependency = flattenPromise(dependencyPromise);
+ *
+ *   return {
+ *     async doSomething() {
+ *       await dependency.someAsyncWork();
+ *       // Instead of `await (await dependencyPromise).someAsyncWork();`
+ *     }
+ *   }
+ * }
+ * ```
+ */
+declare function flattenPromise<T>(promise: Promise<T>): DeepAsync<T>;
+/**
+ * Utility for creating a service whose functions are executed in the background script regardless
+ * of the JS context the they are called from.
+ *
+ * @param name A unique name for the service. Used to identify which service is being executed.
+ * @param init A function that returns your real service implementation. If args are listed,
+ * `registerService` will require the same set of arguments.
+ * @param config
+ * @returns `registerService`: Used to register your service in the background
+ * @returns `getService`: Used to get an instance of the service anywhere in the extension.
+ *
+ * @example
+ * ```ts
+ * // service.ts
+ * export const [registerJobScheduler, getJobScheduler] = defineProxyService(
+ *   'JobScheduler',
+ *   () => defineJobScheduler(),
+ * );
+ *
+ * // background.ts
+ * const jobs = registerJobScheduler();
+ *
+ * // content-script.ts
+ * const jobs = getJobScheduler();
+ * ```
+ */
+declare function defineProxyService<TService extends Service, TArgs extends any[]>(name: string, init: (...args: TArgs) => TService, config?: ProxyServiceConfig): [registerService: (...args: TArgs) => TService, getService: () => ProxyService<TService>];
+/**
+ * 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 {
+}
+
+export { DeepAsync, type ProxyService, type ProxyServiceConfig, type ProxyServiceKey, Service, createProxyService, defineProxyService, flattenPromise, isProxyService, registerService };

package/lib/index.js

@@ -0,0 +1,98 @@
+// src/index.ts
+import {
+  defineExtensionMessaging
+} from "@webext-core/messaging";
+function createProxyService(key, config) {
+  return createProxy(defineProxyMessaging(key, config));
+}
+function registerService(key, realService, config) {
+  const messenger = defineProxyMessaging(key, config);
+  return messenger.onMessage(messenger.messageKey, ({ data, sender }) => {
+    const method = data.path == null ? realService : get(realService ?? {}, data.path);
+    if (method) {
+      const context = {
+        sender,
+        timestamp: data.timestamp,
+        requestId: data.requestId,
+        metadata: {}
+      };
+      return Promise.resolve(method.bind(realService)(...data.args, context));
+    }
+  });
+}
+function isProxyService(obj) {
+  return obj?.[ProxyServiceSymbol] === true;
+}
+function defineProxyMessaging(key, config) {
+  const messaging = defineExtensionMessaging(config);
+  return {
+    messageKey: `proxy-service.${key}`,
+    ...messaging
+  };
+}
+function createProxy(messenger, path) {
+  const wrapped = (() => {
+  });
+  const proxy = new Proxy(wrapped, {
+    async apply(_target, _thisArg, args) {
+      const requestId = `${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+      const timestamp = Date.now();
+      const res = await messenger.sendMessage(messenger.messageKey, {
+        path,
+        args,
+        timestamp,
+        requestId
+      });
+      return res;
+    },
+    get(target, propertyName, receiver) {
+      if (typeof propertyName === "symbol") {
+        return Reflect.get(target, propertyName, receiver);
+      }
+      return createProxy(messenger, path == null ? [propertyName] : path.concat([propertyName]));
+    }
+  });
+  proxy[ProxyServiceSymbol] = true;
+  return proxy;
+}
+var ProxyServiceSymbol = /* @__PURE__ */ Symbol();
+function get(obj, path) {
+  if (path.length === 0) return obj;
+  return path.reduce((acc, key) => acc?.[key], obj);
+}
+function flattenPromise(promise) {
+  return new Proxy({}, {
+    get(_target, p) {
+      if (typeof p === "symbol") return;
+      return async (...args) => {
+        const value = await promise;
+        return await value[p](...args);
+      };
+    }
+  });
+}
+function defineProxyService(name, init, config) {
+  const key = name;
+  let registeredInstance = null;
+  return [
+    (...args) => {
+      const service = init(...args);
+      registeredInstance = service;
+      registerService(key, service, config);
+      return service;
+    },
+    () => {
+      if (registeredInstance) {
+        return registeredInstance;
+      }
+      return createProxyService(key, config);
+    }
+  ];
+}
+export {
+  createProxyService,
+  defineProxyService,
+  flattenPromise,
+  isProxyService,
+  registerService
+};

package/lib/types.d.ts

@@ -0,0 +1,39 @@
+type Proimsify<T> = T extends Promise<any> ? T : Promise<T>;
+type Service = ((...args: any[]) => Promise<any>) | {
+    [key: string]: any | Service;
+};
+/**
+ * Service 方法调用时的上下文信息
+ * 作为服务方法的最后一个可选参数传递
+ *
+ * @example
+ * ```ts
+ * class MyService {
+ *   async doSomething(arg1: string, context?: ServiceCallContext) {
+ *     console.log('Called by:', context?.sender?.tab?.title)
+ *     console.log('Request ID:', context?.requestId)
+ *   }
+ * }
+ * ```
+ */
+interface ServiceCallContext {
+    /** 消息发送者信息 */
+    sender: any;
+    /** 调用时间戳 */
+    timestamp?: number;
+    /** 请求 ID，用于追踪和调试 */
+    requestId?: string;
+    /** 其他元数据 */
+    metadata?: Record<string, any>;
+}
+/**
+ * A recursive type that deeply converts all methods in `TService` to be async.
+ */
+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>) => Proimsify<ReturnType<T>>;
+
+export type { DeepAsync, Proimsify, Service, ServiceCallContext };

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@northsea4/proxy-service",
+  "version": "1.0.0",
+  "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",
+  "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"
+  },
+  "keywords": [
+    "webextension",
+    "browser-extension",
+    "chrome-extension",
+    "proxy",
+    "service",
+    "messaging"
+  ],
+  "author": "northsea4",
+  "license": "MIT",
+  "dependencies": {
+    "@webext-core/messaging": "^1.4.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "webextension-polyfill": "^0.12.0"
+  },
+  "peerDependencies": {
+    "webextension-polyfill": "^0.10.0 || ^0.11.0 || ^0.12.0"
+  }
+}