@webext-core/proxy-service 1.0.2 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,107 +1,7 @@
1
1
  # `@webext-core/proxy-service`
2
2
 
3
- Defer function execution to the background service worker (or page).
3
+ A type-safe wrapper around the web extension messaging APIs that lets you call a function from anywhere, but execute it in the background. Supports all browsers (Chrome, Firefox, Safari, etc).
4
4
 
5
- ```bash
6
- pnpm i @webext-core/proxy-service
7
- ```
5
+ ## Get Started
8
6
 
9
- ## Usage
10
-
11
- 1. Define the service that will be executed in the background:
12
-
13
- ###### MathService.ts
14
-
15
- ```ts
16
- class MathService {
17
- factorial(x) {
18
- return x === 1 ? x : this.factorial(x - 1);
19
- }
20
- }
21
-
22
- export const [registerMathService, getMathService] = defineProxyService(
23
- 'MathService',
24
- () => new MathService(),
25
- );
26
- ```
27
-
28
- 2. Register your new service at the beginning of your background script:
29
-
30
- ###### background.ts
31
-
32
- ```ts
33
- import { registerMathService } from './MathService';
34
-
35
- registerMathService();
36
- ```
37
-
38
- 3. Use `getService` to get a proxied instance of your service, and call methods on it like you would with the real service.
39
-
40
- ###### popup.ts
41
-
42
- ```ts
43
- import { getMathService } from './MathService';
44
-
45
- // getMathService will return a "proxy" service when NOT in the background
46
- const mathService = getMathService();
47
-
48
- // Use the proxy just like you would the real service!
49
- await mathService.factorial(100);
50
- ```
51
-
52
- ### Another Example: IndexedDB
53
-
54
- Since the same IndexedDB database is not available in every JS context of an extension, it's common to use the IndexedDB instance in the background script as a database for browser extensions.
55
-
56
- `@webext-core/proxy-service` is perfect for this! Here we're using [`idb`](https://www.npmjs.com/package/idb) to simplify it's usage.
57
-
58
- ###### TodoRepo.ts
59
-
60
- ```ts
61
- import { IDBPDatabase } from 'idb';
62
-
63
- interface ITodoRepo {
64
- getOne: (id: string) => Promise<Todo>;
65
- getAll: () => Promise<Todo[]>;
66
- create: (todo: Todo) => Promise<void>;
67
- update: (todo: Todo) => Promise<void>;
68
- delete: (todo: Todo) => Promise<void>;
69
- }
70
-
71
- function createIdbTodoRepo(idb: Promise<IDBPDatabase>): ITodoRepo {
72
- return {
73
- getOne: async id => (await idb).get('todos', id),
74
- getAll: async () => (await idb).getAll('todos'),
75
- create: async todo => (await idb).add('todos', todo),
76
- update: async todo => (await idb).put('todos', todo),
77
- delete: async todo => (await idb).delete('todos', todo.id),
78
- };
79
- }
80
-
81
- const [registerTodoRepo, getTodoRepo] = defineProxyService('TodoRepo', createIdbTodoRepo);
82
- ```
83
-
84
- When registering a service with a dependency, you need to pass that dependency into the `registerService` method:
85
-
86
- ###### background.ts
87
-
88
- ```ts
89
- import { registerTodoRepo } from './TodoRepo';
90
- import { openDB } from 'idb';
91
-
92
- const idb = openDB(...);
93
-
94
- registerTodoRepo(idb);
95
- ```
96
-
97
- Then you can use `getService` to get a instance of the service anywhere thoughout your extension!
98
-
99
- ###### popup.ts
100
-
101
- ```ts
102
- import { getTodoRepo } from './TodoRepo';
103
-
104
- const todoRepo = getTodoRepo();
105
-
106
- const todos = await todoRepo.getAll();
107
- ```
7
+ See [documentation](https://webext-core.aklinker1.io/proxy-service) to get started!
package/lib/index.cjs CHANGED
@@ -76,15 +76,39 @@ function isBackgroundServiceWorker() {
76
76
 
77
77
  // src/defineProxyService.ts
78
78
  var import_messaging = require("@webext-core/messaging");
79
+ var import_get_value = __toESM(require("get-value"), 1);
79
80
  function defineProxyService(name, init, config) {
80
81
  let service;
81
82
  const messageKey = `proxy-service.${name}`;
82
83
  const { onMessage, sendMessage } = (0, import_messaging.defineExtensionMessaging)(config);
84
+ function createProxy(path) {
85
+ const wrapped = () => {
86
+ };
87
+ const proxy = new Proxy(wrapped, {
88
+ apply(_target, _thisArg, args) {
89
+ return __async(this, null, function* () {
90
+ const res = yield sendMessage(messageKey, {
91
+ path,
92
+ args
93
+ });
94
+ return res;
95
+ });
96
+ },
97
+ get(target, propertyName, receiver) {
98
+ if (propertyName === "__proxy" || typeof propertyName === "symbol") {
99
+ return Reflect.get(target, propertyName, receiver);
100
+ }
101
+ return createProxy(path == null ? propertyName : `${path}.${propertyName}`);
102
+ }
103
+ });
104
+ proxy.__proxy = true;
105
+ return proxy;
106
+ }
83
107
  return [
84
108
  function registerService(...args) {
85
109
  service = init(...args);
86
110
  onMessage(messageKey, ({ data }) => {
87
- const method = service == null ? void 0 : service[data.method];
111
+ const method = data.path == null ? service : (0, import_get_value.default)(service != null ? service : {}, data.path);
88
112
  if (method)
89
113
  return Promise.resolve(method.bind(service)(...data.args));
90
114
  });
@@ -92,17 +116,7 @@ function defineProxyService(name, init, config) {
92
116
  },
93
117
  function getService() {
94
118
  if (!isBackground())
95
- return new Proxy({}, {
96
- get(_, path) {
97
- return (...args) => __async(this, null, function* () {
98
- const res = yield sendMessage(messageKey, {
99
- method: path,
100
- args
101
- });
102
- return res;
103
- });
104
- }
105
- });
119
+ return createProxy();
106
120
  if (service == null) {
107
121
  throw Error(
108
122
  `Failed to get an instance of ${name}: in background, but registerService has not been called. Did you forget to call registerService?`
package/lib/index.d.ts CHANGED
@@ -1,18 +1,21 @@
1
1
  import { ExtensionMessagingConfig } from '@webext-core/messaging';
2
2
 
3
3
  declare type Proimsify<T> = T extends Promise<any> ? T : Promise<T>;
4
- declare type Service = Record<string, any | ((...args: any[]) => any)>;
4
+ declare type Service = ((...args: any[]) => Promise<any>) | {
5
+ [key: string]: any | Service;
6
+ };
5
7
  /**
6
- * Make all functions of a Service/interface async.
8
+ * Make all functions at all nested levels of an object async
7
9
  */
8
- declare type AsyncService<TService> = {
9
- [fn in keyof TService]: TService[fn] extends (...args: any[]) => any ? (...args: Parameters<TService[fn]>) => Proimsify<ReturnType<TService[fn]>> : TService[fn];
10
+ declare type DeepAsync<TService> = TService extends (...args: any) => any ? ToAsyncFunction<TService> : {
11
+ [fn in keyof TService]: TService[fn] extends (...args: any[]) => any ? ToAsyncFunction<TService[fn]> : TService[fn] extends {
12
+ [key: string]: any;
13
+ } ? DeepAsync<TService[fn]> : never;
10
14
  };
15
+ declare type ToAsyncFunction<T extends (...args: any) => any> = (...args: Parameters<T>) => Proimsify<ReturnType<T>>;
11
16
  interface ProxyServiceConfig extends ExtensionMessagingConfig {
12
17
  }
13
18
 
14
- declare type RegisterService<TService extends Service, TArgs extends any[]> = (...args: TArgs) => TService;
15
- declare type GetService<TService extends Service> = () => AsyncService<TService>;
16
- declare function defineProxyService<TService extends Service, TArgs extends any[]>(name: string, init: (...args: TArgs) => TService, config?: ProxyServiceConfig): [registerService: RegisterService<TService, TArgs>, getService: GetService<TService>];
19
+ declare function defineProxyService<TService extends Service, TArgs extends any[]>(name: string, init: (...args: TArgs) => TService, config?: ProxyServiceConfig): [registerService: (...args: TArgs) => TService, getService: () => DeepAsync<TService>];
17
20
 
18
21
  export { ProxyServiceConfig, defineProxyService };