aklinker1 · natereprogle · Aug 15, 2025 · Aug 15, 2025 · Aug 15, 2025 · Aug 15, 2025
diff --git a/bun.lockb b/bun.lockb
diff --git a/docs/content/messaging/api.md b/docs/content/messaging/api.md
@@ -19,7 +19,7 @@ interface BaseMessagingConfig {
 
 Shared configuration between all the different messengers.
 
-### Properties
+### Properties 
 
 - ***`logger?: Logger`*** (default: `console`)<br/>The logger to use when logging messages. Set to `null` to disable logging.
 
@@ -35,7 +35,7 @@ interface CustomEventMessage {
 
 Additional fields available on the `Message` from a `CustomEventMessenger`.
 
-### Properties
+### Properties 
 
 - ***`event: CustomEvent`***<br/>The event that was fired, resulting in the message being passed.
 
@@ -153,7 +153,7 @@ interface ExtensionMessage {
 
 Additional fields available on the `Message` from an `ExtensionMessenger`.
 
-### Properties
+### Properties 
 
 - ***`sender: Runtime.MessageSender`***<br/>Information about where the message came from. See
 [`Runtime.MessageSender`](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime/MessageSender).
@@ -196,6 +196,12 @@ interface GenericMessenger<
   TMessageExtension,
   TSendMessageArgs extends any[],
 > {
+  sendMessage<TType extends keyof TProtocolMap>(
+    type: TType,
+    ...args: GetDataType<TProtocolMap[TType]> extends undefined
+      ? [data?: undefined, ...args: TSendMessageArgs]
+      : never
+  ): Promise<GetReturnType<TProtocolMap[TType]>>;
   sendMessage<TType extends keyof TProtocolMap>(
     type: TType,
     data: GetDataType<TProtocolMap[TType]>,
@@ -283,7 +289,7 @@ interface Message<
 
 Contains information about the message received.
 
-### Properties
+### Properties 
 
 - ***`id: number`***<br/>A semi-unique, auto-incrementing number used to trace messages being sent.
 
@@ -306,7 +312,7 @@ interface MessageSender {
 
 An object containing information about the script context that sent a message or request.
 
-### Properties
+### Properties 
 
 - ***`tab?: Tabs.Tab`***<br/>The $(ref:tabs.Tab) which opened the connection, if any. This property will <strong>only</strong>
 be present when the connection was opened from a tab (including content scripts), and <strong>only</strong>
@@ -332,7 +338,7 @@ interface NamespaceMessagingConfig extends BaseMessagingConfig {
 }
 ```
 
-### Properties
+### Properties 
 
 - ***`namespace: string`***<br/>A string used to ensure the messenger only sends messages to and listens for messages from
 other messengers of the same type, with the same namespace.
@@ -354,7 +360,7 @@ Used to add a return type to a message in the protocol map.
 
 > Internally, this is just an object with random keys for the data and return types.
 
-### Properties
+### Properties 
 
 - ***`BtVgCTPYZu: TData`***<br/>Stores the data type. Randomly named so that it isn't accidentally implemented.
 
@@ -392,7 +398,7 @@ interface SendMessageOptions {
 
 Options for sending a message to a specific tab/frame
 
-### Properties
+### Properties 
 
 - ***`tabId: number`***<br/>The tab to send a message to
 
@@ -429,4 +435,4 @@ details.
 
 ---
 
-_API reference generated by [`docs/generate-api-references.ts`](https://github.com/aklinker1/webext-core/blob/main/docs/generate-api-references.ts)_
+_API reference generated by [`docs/generate-api-references.ts`](https://github.com/aklinker1/webext-core/blob/main/docs/generate-api-references.ts)_
diff --git a/docs/content/proxy-service/0.installation.md b/docs/content/proxy-service/0.installation.md
@@ -17,17 +17,19 @@ class MathService {
     ...
   }
 }
-export const [registerMathService, getMathService] = defineProxyService(
-  'MathService',
-  () => new MathService(),
-);
+export const [registerMathService, getMathService] = defineServiceProxy<MathService>('MathService');
 ```
 
 ```ts [background.ts]
 import { registerMathService } from './MathService';
 
 // 2. Register the service at the beginning of the background script
-registerMathService();
+export default defineBackground(() => {
+  registerMathService(async () => {
+    const { MathService } = await import('../utils/math-service');
+    return new MathService();
+  });
+});
 ```
 
 ```ts [anywhere-else.ts]

diff --git a/docs/content/proxy-service/1.defining-services.md b/docs/content/proxy-service/1.defining-services.md
@@ -8,26 +8,23 @@ Define a class whose methods are available in other JS contexts:
 
 ```ts
 import { openDB, IDBPDatabase } from 'idb';
-import { defineProxyService } from '@webext-core/proxy-service';
+import { defineServiceProxy } from '@webext-core/proxy-service';
 
-class TodosRepo {
+export class TodosRepo {
   constructor(private db: Promise<IDBPDatabase>) {}
 
   async getAll(): Promise<Todo[]> {
     return (await this.db).getAll('todos');
   }
 }
 
-export const [registerTodosRepo, getTodosRepo] = defineProxyService(
-  'TodosRepo',
-  (idb: Promise<IDBPDatabase>) => new TodosRepo(idb),
-);
+export const [registerTodosRepo, getTodosRepo] = defineServiceProxy<TodosRepo>('TodosRepo');
 ```
 
 ```ts
 // Register
 const db = openDB('todos');
-registerTodosRepo(db);
+registerTodosRepo((idb: Promise<IDBPDatabase>) => new TodosRepo(idb), db);
 ```
 
 ```ts
@@ -42,24 +39,24 @@ Objects can be used as services as well. All functions defined on the object are
 
 ```ts
 import { openDB, IDBPDatabase } from 'idb';
-import { defineProxyService } from '@webext-core/proxy-service';
+import { defineServiceProxy } from '@webext-core/proxy-service';
+
+export const [registerTodosRepo, getTodosRepo] = defineServiceProxy<TodosRepo>('TodosRepo');
+```
 
-export const [registerTodosRepo, getTodosRepo] = defineProxyService(
-  'TodosRepo',
+```ts
+// Register
+const db = openDB('todos');
+await registerTodosRepo(
   (db: Promise<IDBPDatabase>) => ({
     async getAll(): Promise<Todo[]> {
       return (await this.db).getAll('todos');
     },
   }),
+  db,
 );
 ```
 
-```ts
-// Register
-const db = openDB('todos');
-registerTodosRepo(db);
-```
-
 ```ts
 // Get an instance
 const todosRepo = getTodosRepo();
@@ -72,21 +69,20 @@ If you only need to define a single function, you can!
 
 ```ts
 import { openDB, IDBPDatabase } from 'idb';
-import { defineProxyService } from '@webext-core/proxy-service';
+import { defineServiceProxy } from '@webext-core/proxy-service';
 
-export const [registerGetAllTodos, getGetAllTodos] = defineProxyService(
-  'TodosRepo',
-  (db: Promise<IDBPDatabase>) =>
-    function getAllTodos() {
-      return (await this.db).getAll('todos');
-    },
-);
+export async function getAllTodos(db: Promise<IDBPDatabase>) {
+  return (await db).getAll('todos');
+}
+
+export const [registerGetAllTodos, getGetAllTodos] =
+  defineServiceProxy<typeof getAllTodos>('TodosRepo');
 ```
 
 ```ts
 // Register
 const db = openDB('todos');
-registerGetAllTodos(db);
+await registerGetAllTodos((db: Promise<IDBPDatabase>) => getAllTodos, db);
 ```
 
 ```ts
@@ -101,36 +97,34 @@ If you need to register "deep" objects containing multiple services, you can do
 
 ```ts
 import { openDB, IDBPDatabase } from 'idb';
-import { defineProxyService } from '@webext-core/proxy-service';
+import { defineServiceProxy } from '@webext-core/proxy-service';
 
-class TodosRepo {
+export class TodosRepo {
   constructor(private db: Promise<IDBPDatabase>) {}
 
   async getAll(): Promise<Todo[]> {
     return (await this.db).getAll('todos');
   }
 }
 
-const createAuthorsRepo = (db: Promise<IDBPDatabase>) => ({
+export const createAuthorsRepo = (db: Promise<IDBPDatabase>) => ({
   async getOne(id: string): Promise<Todo[]> {
     return (await this.db).getAll('authors', id);
   },
 });
 
-function createApi(db: Promise<IDBPDatabase>) {
-  return {
-    todos: new TodosRepo(db),
-    authors: createAuthorsRepo(db),
-  };
-}
-
-export const [registerApi, getApi] = defineProxyService('Api', createApi);
+export const [registerApi, getApi] = defineServiceProxy<TodosRepo>('Api');
 ```
 
 ```ts
 // Register
 const db = openDB('todos');
-registerApi(db);
+await registerApi((db: Promise<IDBPDatabase>) => {
+  return {
+    todos: new TodosRepo(db),
+    authors: reateAuthorsRepo(db),
+  };
+}, db);
 ```
 
 ```ts

diff --git a/docs/content/proxy-service/api.md b/docs/content/proxy-service/api.md
@@ -24,6 +24,10 @@ A recursive type that deeply converts all methods in `TService` to be async.
 
 ## `defineProxyService`
 
+:::danger Deprecated
+Use  {@link  defineServiceProxy  }  instead.
+:::
+
 ```ts
 function defineProxyService<TService extends Service, TArgs extends any[]>(
   name: string,
@@ -54,6 +58,37 @@ of the JS context the they are called from.
 - `registerService`: Used to register your service in the background
 - `getService`: Used to get an instance of the service anywhere in the extension.
 
+## `defineServiceProxy`
+
+```ts
+function defineServiceProxy<TService extends Service>(
+  name: string,
+  config?: ProxyServiceConfig,
+): [
+  registerService: (
+    init: (...args: any[]) => TService | Promise<TService>,
+    ...args: any[]
+  ) => Promise<TService>,
+  getService: () => ProxyService<TService>,
+] {
+  // ...
+}
+```
+
+Utility for creating a service whose functions are executed in the background script regardless
+of the JS context they are called from.
+
+### Parameters
+
+- ***`name: string`***<br/>A unique name for the service. Used to identify which service is being executed.
+
+- ***`config?: ProxyServiceConfig`***<br/>An object that allows configuration of the underlying messaging service
+
+### Returns 
+
+- `registerService`: Used to register your service in the background. Requires an `init()` callback used to create the actual service object.
+- `getService`: Used to get an instance of the service anywhere in the extension.
+
 ## `flattenPromise`
 
 ```ts

diff --git a/packages/proxy-service-demo/src/entrypoints/background.ts b/packages/proxy-service-demo/src/entrypoints/background.ts
@@ -1,3 +1,6 @@
 export default defineBackground(() => {
-  registerMathService();
+  registerMathService(async () => {
+    const { MathService } = await import('../utils/math-service');
+    return new MathService();
+  });
 });
diff --git a/packages/proxy-service-demo/src/entrypoints/popup/main.ts b/packages/proxy-service-demo/src/entrypoints/popup/main.ts
@@ -1,3 +1,5 @@
+import { getMathService } from '../../utils/math-service';
+
 function getMathServiceElements(id: string) {
   const parent = document.getElementById(id)!;
   return [

diff --git a/packages/proxy-service-demo/src/utils/math-service.ts b/packages/proxy-service-demo/src/utils/math-service.ts
@@ -1,6 +1,6 @@
-import { defineProxyService } from '@webext-core/proxy-service';
+import { defineServiceProxy } from '@webext-core/proxy-service';
 
-class MathService {
+export class MathService {
   add(x: number, y: number): number {
     console.log(`MathService.add(${x}, ${y})`);
     return x + y;
@@ -25,7 +25,4 @@ class MathService {
   }
 }
 
-export const [registerMathService, getMathService] = defineProxyService(
-  'MathService',
-  () => new MathService(),
-);
+export const [registerMathService, getMathService] = defineServiceProxy<MathService>('MathService');
diff --git a/packages/proxy-service/src/defineProxyService.ts b/packages/proxy-service/src/defineProxyService.ts
@@ -14,6 +14,9 @@ import get from 'get-value';
  * @returns
  * - `registerService`: Used to register your service in the background
  * - `getService`: Used to get an instance of the service anywhere in the extension.
+ *
+ * @deprecated
+ * Use {@link defineServiceProxy} instead.
  */
 export function defineProxyService<TService extends Service, TArgs extends any[]>(
   name: string,