@webext-core/messaging 1.1.1 → 1.2.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/lib/index.cjs CHANGED
@@ -52,22 +52,28 @@ module.exports = __toCommonJS(src_exports);
52
52
  var import_webextension_polyfill = __toESM(require("webextension-polyfill"), 1);
53
53
  function defineExtensionMessaging(config) {
54
54
  let rootListener;
55
+ function cleanupRootListener() {
56
+ if (Object.entries(keyListeners).length === 0) {
57
+ import_webextension_polyfill.default.runtime.onMessage.removeListener(rootListener);
58
+ rootListener = void 0;
59
+ }
60
+ }
55
61
  let keyListeners = {};
56
62
  let idSeq = Math.floor(Math.random() * 1e4);
57
63
  function getNextId() {
58
64
  return idSeq++;
59
65
  }
60
- function onMessage(key, onReceived) {
66
+ function onMessage(type, onReceived) {
61
67
  var _a, _b, _c;
62
68
  if (rootListener == null) {
63
69
  (_a = config == null ? void 0 : config.logger) == null ? void 0 : _a.debug(
64
- `[messaging] ${key} initialized message listener for this context`
70
+ `[messaging] ${type} initialized message listener for this context`
65
71
  );
66
72
  rootListener = (message, sender) => {
67
73
  var _a2, _b2, _c2;
68
- if (typeof message.key != "string" || typeof message.timestamp !== "number") {
74
+ if (typeof message.type != "string" || typeof message.timestamp !== "number") {
69
75
  const err = Error(
70
- `[messaging] Unknown message format, must include the 'key' & 'timestamp' fields, received: ${JSON.stringify(
76
+ `[messaging] Unknown message format, must include the 'type' & 'timestamp' fields, received: ${JSON.stringify(
71
77
  message
72
78
  )}`
73
79
  );
@@ -76,8 +82,8 @@ function defineExtensionMessaging(config) {
76
82
  }
77
83
  (_b2 = config == null ? void 0 : config.logger) == null ? void 0 : _b2.debug("[messaging] Received message", message, sender);
78
84
  const entries = Object.entries(keyListeners);
79
- for (const [key2, listener] of entries) {
80
- if (message.key !== key2)
85
+ for (const [type2, listener] of entries) {
86
+ if (message.type !== type2)
81
87
  continue;
82
88
  (_c2 = config == null ? void 0 : config.logger) == null ? void 0 : _c2.debug(`[messaging] onMessage {id=${message.id}} \u140A\u2500`, message);
83
89
  const res = listener({
@@ -101,34 +107,31 @@ function defineExtensionMessaging(config) {
101
107
  });
102
108
  }
103
109
  return Promise.resolve({
104
- err: `Listener not found for message.type="${message.key}".
110
+ err: `Listener not found for message.type="${message.type}".
105
111
 
106
112
  Did you forget to call \`onMessage("getLength", ...)\`?`
107
113
  });
108
114
  };
109
115
  import_webextension_polyfill.default.runtime.onMessage.addListener(rootListener);
110
116
  }
111
- if (keyListeners[key] != null) {
117
+ if (keyListeners[type] != null) {
112
118
  const err = Error(
113
- `[messaging] In this JS context, only one listener can be setup for ${key}`
119
+ `[messaging] In this JS context, only one listener can be setup for ${type}`
114
120
  );
115
121
  (_b = config == null ? void 0 : config.logger) == null ? void 0 : _b.error(err);
116
122
  throw err;
117
123
  }
118
- keyListeners[key] = onReceived;
119
- (_c = config == null ? void 0 : config.logger) == null ? void 0 : _c.log(`[messaging] Added listener for ${key}`);
124
+ keyListeners[type] = onReceived;
125
+ (_c = config == null ? void 0 : config.logger) == null ? void 0 : _c.log(`[messaging] Added listener for ${type}`);
120
126
  return function removeListener() {
121
- delete keyListeners[key];
122
- if (Object.entries(keyListeners).length === 0) {
123
- import_webextension_polyfill.default.runtime.onMessage.removeListener(rootListener);
124
- rootListener = void 0;
125
- }
127
+ delete keyListeners[type];
128
+ cleanupRootListener();
126
129
  };
127
130
  }
128
- function sendMessage(key, data, tabId) {
131
+ function sendMessage(type, data, tabId) {
129
132
  return __async(this, null, function* () {
130
133
  var _a, _b;
131
- const message = { id: getNextId(), key, data, timestamp: Date.now() };
134
+ const message = { id: getNextId(), type, data, timestamp: Date.now() };
132
135
  (_a = config == null ? void 0 : config.logger) == null ? void 0 : _a.debug(`[messaging] sendMessage {id=${message.id}} \u2500\u1405`, message);
133
136
  let response;
134
137
  if (tabId == null)
@@ -142,7 +145,13 @@ Did you forget to call \`onMessage("getLength", ...)\`?`
142
145
  return res;
143
146
  });
144
147
  }
145
- return { onMessage, sendMessage };
148
+ function removeAllMessageListeners() {
149
+ Object.keys(keyListeners).forEach((type) => {
150
+ delete keyListeners[type];
151
+ });
152
+ cleanupRootListener();
153
+ }
154
+ return { onMessage, sendMessage, removeAllMessageListeners };
146
155
  }
147
156
  // Annotate the CommonJS export names for ESM import in node:
148
157
  0 && (module.exports = {
package/lib/index.d.ts CHANGED
@@ -1,30 +1,118 @@
1
1
  import { Runtime } from 'webextension-polyfill';
2
2
 
3
+ /**
4
+ * Interface used to log text to the console when sending and recieving messages.
5
+ */
6
+ interface Logger {
7
+ debug(...args: any[]): void;
8
+ log(...args: any[]): void;
9
+ warn(...args: any[]): void;
10
+ error(...args: any[]): void;
11
+ }
3
12
  interface ExtensionMessagingConfig {
4
- logger?: {
5
- debug(...args: any[]): void;
6
- log(...args: any[]): void;
7
- warn(...args: any[]): void;
8
- error(...args: any[]): void;
9
- };
13
+ /**
14
+ * The logger to use when logging messages. Defaults to `console`.
15
+ *
16
+ * Set to `null` to disable logging.
17
+ */
18
+ logger?: Logger;
10
19
  }
11
- declare type ProtocolWithReturn<TData, TResponse> = {
20
+ /**
21
+ * Used to add a return type to a message in the protocol map.
22
+ *
23
+ * @example
24
+ * interface ProtocolMap {
25
+ * // data is a string, returns undefined
26
+ * type1: string;
27
+ * // data is a string, returns a number
28
+ * type2: ProtocolWithReturn<string, number>;
29
+ * }
30
+ *
31
+ * > Internally, this is just an object with random keys for the data and return types.
32
+ */
33
+ declare type ProtocolWithReturn<TData, TReturn> = {
12
34
  BtVgCTPYZu: TData;
13
- RrhVseLgZW: TResponse;
35
+ RrhVseLgZW: TReturn;
14
36
  };
15
- declare type GetData<T> = T extends ProtocolWithReturn<any, any> ? T['BtVgCTPYZu'] : T;
16
- declare type GetResponse<T> = T extends ProtocolWithReturn<any, any> ? T['RrhVseLgZW'] : void;
17
- interface Message<TProtocolMap, TKey extends keyof TProtocolMap> {
37
+ /**
38
+ * Given a `ProtocolWithReturn` or a value, return the message's data type.
39
+ */
40
+ declare type GetDataType<T> = T extends ProtocolWithReturn<any, any> ? T['BtVgCTPYZu'] : T;
41
+ /**
42
+ * Given a `ProtocolWithReturn` or a value, return the message's return type.
43
+ */
44
+ declare type GetReturnType<T> = T extends ProtocolWithReturn<any, any> ? T['RrhVseLgZW'] : void;
45
+ /**
46
+ * Either a Promise of a type, or that type directly. Used to indicate that a method can by sync or
47
+ * async.
48
+ */
49
+ declare type MaybePromise<T> = Promise<T> | T;
50
+ /**
51
+ * Call to ensure an active listener has been removed.
52
+ *
53
+ * If the listener has already been removed with `Messenger.removeAllListeners`, this is a noop.
54
+ */
55
+ declare type RemoveListenerCallback = () => void;
56
+ declare type OnMessageReceived<TProtocolMap, TType extends keyof TProtocolMap> = (message: Message<TProtocolMap, TType>) => MaybePromise<GetReturnType<TProtocolMap[TType]>>;
57
+ /**
58
+ * Use the functions defined in the messenger to send and recieve messages throughout your entire extension.
59
+ *
60
+ * Unlike the regular `chrome.runtime` messaging APIs, there are no limitations to when you call `onMessage` or `sendMessage`.
61
+ */
62
+ interface Messenger<TProtocolMap> {
63
+ /**
64
+ * Send a message to the background or a specific tab if `tabId` is passed. You can call this
65
+ * function anywhere in your extension.
66
+ *
67
+ * If you haven't setup a listener for the sent `type`, an error will be thrown.
68
+ *
69
+ * @param type The message type being sent. Call `onMessage` with the same type to listen for that message.
70
+ * @param data The data to send with the message.
71
+ * @param tabId An optional ID specifying which tab the message should be sent to.
72
+ */
73
+ sendMessage<TType extends keyof TProtocolMap>(type: TType, data: GetDataType<TProtocolMap[TType]>, tabId?: number): Promise<GetReturnType<TProtocolMap[TType]>>;
74
+ /**
75
+ * Trigger a callback when a message of the requested type is recieved. You cannot setup multiple
76
+ * listeners for the same message type in the same JS context.
77
+ *
78
+ * To remove the listener, call the returned message.
79
+ *
80
+ * @param type The message type to listen for. Call `sendMessage` with the same type to triggern this listener.
81
+ * @param onReceived The callback executed when a message is recieved.
82
+ */
83
+ onMessage<TType extends keyof TProtocolMap>(type: TType, onReceived: OnMessageReceived<TProtocolMap, TType>): RemoveListenerCallback;
84
+ /**
85
+ * Removes all listeners.
86
+ */
87
+ removeAllMessageListeners(): void;
88
+ }
89
+ /**
90
+ * Contains information about the message recieved.
91
+ */
92
+ interface Message<TProtocolMap, TType extends keyof TProtocolMap> {
93
+ /**
94
+ * A semi-unique, auto-incrementing number used to trace messages being sent.
95
+ */
18
96
  id: number;
19
- data: GetData<TProtocolMap[TKey]>;
97
+ /**
98
+ * The data that was passed into `sendMessage`
99
+ */
100
+ data: GetDataType<TProtocolMap[TType]>;
101
+ /**
102
+ * See [`MessageSender`](https://developer.chrome.com/docs/extensions/reference/runtime/#type-MessageSender).
103
+ * This contains information about which JS context sent the message.
104
+ */
20
105
  sender: Runtime.MessageSender;
106
+ /**
107
+ * The timestamp the message was sent in MS since epoch.
108
+ */
21
109
  timestamp: number;
22
110
  }
23
- declare type MaybePromise<T> = Promise<T> | T;
24
- declare type OnMessageReceived<TProtocolMap, TKey extends keyof TProtocolMap> = (message: Message<TProtocolMap, TKey>) => MaybePromise<GetResponse<TProtocolMap[TKey]>>;
25
- declare function defineExtensionMessaging<TProtocolMap>(config?: ExtensionMessagingConfig): {
26
- onMessage: <TKey extends keyof TProtocolMap>(key: TKey, onReceived: OnMessageReceived<TProtocolMap, TKey>) => () => void;
27
- sendMessage: <TKey_1 extends keyof TProtocolMap>(key: TKey_1, data: GetData<TProtocolMap[TKey_1]>, tabId?: number) => Promise<GetResponse<TProtocolMap[TKey_1]>>;
28
- };
111
+ /**
112
+ * Creates a new `Messenger` used to send and recieve messages in your extension.
113
+ *
114
+ * @param config Configure the behavior of the messenger.
115
+ */
116
+ declare function defineExtensionMessaging<TProtocolMap>(config?: ExtensionMessagingConfig): Messenger<TProtocolMap>;
29
117
 
30
- export { ExtensionMessagingConfig, ProtocolWithReturn, defineExtensionMessaging };
118
+ export { ExtensionMessagingConfig, GetDataType, GetReturnType, Logger, MaybePromise, Messenger, ProtocolWithReturn, RemoveListenerCallback, defineExtensionMessaging };
@@ -1050,22 +1050,28 @@ var webExtCoreMessaging = (() => {
1050
1050
  var import_webextension_polyfill = __toESM(require_browser_polyfill(), 1);
1051
1051
  function defineExtensionMessaging(config) {
1052
1052
  let rootListener;
1053
+ function cleanupRootListener() {
1054
+ if (Object.entries(keyListeners).length === 0) {
1055
+ import_webextension_polyfill.default.runtime.onMessage.removeListener(rootListener);
1056
+ rootListener = void 0;
1057
+ }
1058
+ }
1053
1059
  let keyListeners = {};
1054
1060
  let idSeq = Math.floor(Math.random() * 1e4);
1055
1061
  function getNextId() {
1056
1062
  return idSeq++;
1057
1063
  }
1058
- function onMessage(key, onReceived) {
1064
+ function onMessage(type, onReceived) {
1059
1065
  var _a, _b, _c;
1060
1066
  if (rootListener == null) {
1061
1067
  (_a = config == null ? void 0 : config.logger) == null ? void 0 : _a.debug(
1062
- `[messaging] ${key} initialized message listener for this context`
1068
+ `[messaging] ${type} initialized message listener for this context`
1063
1069
  );
1064
1070
  rootListener = (message, sender) => {
1065
1071
  var _a2, _b2, _c2;
1066
- if (typeof message.key != "string" || typeof message.timestamp !== "number") {
1072
+ if (typeof message.type != "string" || typeof message.timestamp !== "number") {
1067
1073
  const err = Error(
1068
- `[messaging] Unknown message format, must include the 'key' & 'timestamp' fields, received: ${JSON.stringify(
1074
+ `[messaging] Unknown message format, must include the 'type' & 'timestamp' fields, received: ${JSON.stringify(
1069
1075
  message
1070
1076
  )}`
1071
1077
  );
@@ -1074,8 +1080,8 @@ var webExtCoreMessaging = (() => {
1074
1080
  }
1075
1081
  (_b2 = config == null ? void 0 : config.logger) == null ? void 0 : _b2.debug("[messaging] Received message", message, sender);
1076
1082
  const entries = Object.entries(keyListeners);
1077
- for (const [key2, listener] of entries) {
1078
- if (message.key !== key2)
1083
+ for (const [type2, listener] of entries) {
1084
+ if (message.type !== type2)
1079
1085
  continue;
1080
1086
  (_c2 = config == null ? void 0 : config.logger) == null ? void 0 : _c2.debug(`[messaging] onMessage {id=${message.id}} \u140A\u2500`, message);
1081
1087
  const res = listener({
@@ -1099,34 +1105,31 @@ var webExtCoreMessaging = (() => {
1099
1105
  });
1100
1106
  }
1101
1107
  return Promise.resolve({
1102
- err: `Listener not found for message.type="${message.key}".
1108
+ err: `Listener not found for message.type="${message.type}".
1103
1109
 
1104
1110
  Did you forget to call \`onMessage("getLength", ...)\`?`
1105
1111
  });
1106
1112
  };
1107
1113
  import_webextension_polyfill.default.runtime.onMessage.addListener(rootListener);
1108
1114
  }
1109
- if (keyListeners[key] != null) {
1115
+ if (keyListeners[type] != null) {
1110
1116
  const err = Error(
1111
- `[messaging] In this JS context, only one listener can be setup for ${key}`
1117
+ `[messaging] In this JS context, only one listener can be setup for ${type}`
1112
1118
  );
1113
1119
  (_b = config == null ? void 0 : config.logger) == null ? void 0 : _b.error(err);
1114
1120
  throw err;
1115
1121
  }
1116
- keyListeners[key] = onReceived;
1117
- (_c = config == null ? void 0 : config.logger) == null ? void 0 : _c.log(`[messaging] Added listener for ${key}`);
1122
+ keyListeners[type] = onReceived;
1123
+ (_c = config == null ? void 0 : config.logger) == null ? void 0 : _c.log(`[messaging] Added listener for ${type}`);
1118
1124
  return function removeListener() {
1119
- delete keyListeners[key];
1120
- if (Object.entries(keyListeners).length === 0) {
1121
- import_webextension_polyfill.default.runtime.onMessage.removeListener(rootListener);
1122
- rootListener = void 0;
1123
- }
1125
+ delete keyListeners[type];
1126
+ cleanupRootListener();
1124
1127
  };
1125
1128
  }
1126
- function sendMessage(key, data, tabId) {
1129
+ function sendMessage(type, data, tabId) {
1127
1130
  return __async(this, null, function* () {
1128
1131
  var _a, _b;
1129
- const message = { id: getNextId(), key, data, timestamp: Date.now() };
1132
+ const message = { id: getNextId(), type, data, timestamp: Date.now() };
1130
1133
  (_a = config == null ? void 0 : config.logger) == null ? void 0 : _a.debug(`[messaging] sendMessage {id=${message.id}} \u2500\u1405`, message);
1131
1134
  let response;
1132
1135
  if (tabId == null)
@@ -1140,7 +1143,13 @@ Did you forget to call \`onMessage("getLength", ...)\`?`
1140
1143
  return res;
1141
1144
  });
1142
1145
  }
1143
- return { onMessage, sendMessage };
1146
+ function removeAllMessageListeners() {
1147
+ Object.keys(keyListeners).forEach((type) => {
1148
+ delete keyListeners[type];
1149
+ });
1150
+ cleanupRootListener();
1151
+ }
1152
+ return { onMessage, sendMessage, removeAllMessageListeners };
1144
1153
  }
1145
1154
  return __toCommonJS(src_exports);
1146
1155
  })();
package/lib/index.js CHANGED
@@ -23,22 +23,28 @@ var __async = (__this, __arguments, generator) => {
23
23
  import Browser from "webextension-polyfill";
24
24
  function defineExtensionMessaging(config) {
25
25
  let rootListener;
26
+ function cleanupRootListener() {
27
+ if (Object.entries(keyListeners).length === 0) {
28
+ Browser.runtime.onMessage.removeListener(rootListener);
29
+ rootListener = void 0;
30
+ }
31
+ }
26
32
  let keyListeners = {};
27
33
  let idSeq = Math.floor(Math.random() * 1e4);
28
34
  function getNextId() {
29
35
  return idSeq++;
30
36
  }
31
- function onMessage(key, onReceived) {
37
+ function onMessage(type, onReceived) {
32
38
  var _a, _b, _c;
33
39
  if (rootListener == null) {
34
40
  (_a = config == null ? void 0 : config.logger) == null ? void 0 : _a.debug(
35
- `[messaging] ${key} initialized message listener for this context`
41
+ `[messaging] ${type} initialized message listener for this context`
36
42
  );
37
43
  rootListener = (message, sender) => {
38
44
  var _a2, _b2, _c2;
39
- if (typeof message.key != "string" || typeof message.timestamp !== "number") {
45
+ if (typeof message.type != "string" || typeof message.timestamp !== "number") {
40
46
  const err = Error(
41
- `[messaging] Unknown message format, must include the 'key' & 'timestamp' fields, received: ${JSON.stringify(
47
+ `[messaging] Unknown message format, must include the 'type' & 'timestamp' fields, received: ${JSON.stringify(
42
48
  message
43
49
  )}`
44
50
  );
@@ -47,8 +53,8 @@ function defineExtensionMessaging(config) {
47
53
  }
48
54
  (_b2 = config == null ? void 0 : config.logger) == null ? void 0 : _b2.debug("[messaging] Received message", message, sender);
49
55
  const entries = Object.entries(keyListeners);
50
- for (const [key2, listener] of entries) {
51
- if (message.key !== key2)
56
+ for (const [type2, listener] of entries) {
57
+ if (message.type !== type2)
52
58
  continue;
53
59
  (_c2 = config == null ? void 0 : config.logger) == null ? void 0 : _c2.debug(`[messaging] onMessage {id=${message.id}} \u140A\u2500`, message);
54
60
  const res = listener({
@@ -72,34 +78,31 @@ function defineExtensionMessaging(config) {
72
78
  });
73
79
  }
74
80
  return Promise.resolve({
75
- err: `Listener not found for message.type="${message.key}".
81
+ err: `Listener not found for message.type="${message.type}".
76
82
 
77
83
  Did you forget to call \`onMessage("getLength", ...)\`?`
78
84
  });
79
85
  };
80
86
  Browser.runtime.onMessage.addListener(rootListener);
81
87
  }
82
- if (keyListeners[key] != null) {
88
+ if (keyListeners[type] != null) {
83
89
  const err = Error(
84
- `[messaging] In this JS context, only one listener can be setup for ${key}`
90
+ `[messaging] In this JS context, only one listener can be setup for ${type}`
85
91
  );
86
92
  (_b = config == null ? void 0 : config.logger) == null ? void 0 : _b.error(err);
87
93
  throw err;
88
94
  }
89
- keyListeners[key] = onReceived;
90
- (_c = config == null ? void 0 : config.logger) == null ? void 0 : _c.log(`[messaging] Added listener for ${key}`);
95
+ keyListeners[type] = onReceived;
96
+ (_c = config == null ? void 0 : config.logger) == null ? void 0 : _c.log(`[messaging] Added listener for ${type}`);
91
97
  return function removeListener() {
92
- delete keyListeners[key];
93
- if (Object.entries(keyListeners).length === 0) {
94
- Browser.runtime.onMessage.removeListener(rootListener);
95
- rootListener = void 0;
96
- }
98
+ delete keyListeners[type];
99
+ cleanupRootListener();
97
100
  };
98
101
  }
99
- function sendMessage(key, data, tabId) {
102
+ function sendMessage(type, data, tabId) {
100
103
  return __async(this, null, function* () {
101
104
  var _a, _b;
102
- const message = { id: getNextId(), key, data, timestamp: Date.now() };
105
+ const message = { id: getNextId(), type, data, timestamp: Date.now() };
103
106
  (_a = config == null ? void 0 : config.logger) == null ? void 0 : _a.debug(`[messaging] sendMessage {id=${message.id}} \u2500\u1405`, message);
104
107
  let response;
105
108
  if (tabId == null)
@@ -113,7 +116,13 @@ Did you forget to call \`onMessage("getLength", ...)\`?`
113
116
  return res;
114
117
  });
115
118
  }
116
- return { onMessage, sendMessage };
119
+ function removeAllMessageListeners() {
120
+ Object.keys(keyListeners).forEach((type) => {
121
+ delete keyListeners[type];
122
+ });
123
+ cleanupRootListener();
124
+ }
125
+ return { onMessage, sendMessage, removeAllMessageListeners };
117
126
  }
118
127
  export {
119
128
  defineExtensionMessaging
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@webext-core/messaging",
3
- "version": "1.1.1",
3
+ "version": "1.2.0",
4
4
  "description": "Light weight, type-safe wrapper around the extension messaging APIs",
5
5
  "license": "MIT",
6
6
  "keywords": [
@@ -48,7 +48,7 @@
48
48
  "tsup": "^6.4.0",
49
49
  "typescript": "^4.8.4",
50
50
  "vitest": "^0.24.5",
51
- "@webext-core/fake-browser": "1.0.3",
51
+ "@webext-core/fake-browser": "1.0.4",
52
52
  "tsconfig": "0.0.0"
53
53
  },
54
54
  "scripts": {