@webext-core/messaging 1.3.1 → 2.0.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
@@ -33,4 +33,4 @@ console.log(length); // 11
33
33
 
34
34
  ## Get Started
35
35
 
36
- See [documentation](https://webext-core.aklinker1.io/messaging) to get started!
36
+ See [documentation](https://webext-core.aklinker1.io/guide/messaging/) to get started!
@@ -0,0 +1,149 @@
1
+ var __defProp = Object.defineProperty;
2
+ var __defProps = Object.defineProperties;
3
+ var __getOwnPropDescs = Object.getOwnPropertyDescriptors;
4
+ var __getOwnPropSymbols = Object.getOwnPropertySymbols;
5
+ var __hasOwnProp = Object.prototype.hasOwnProperty;
6
+ var __propIsEnum = Object.prototype.propertyIsEnumerable;
7
+ var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
8
+ var __spreadValues = (a, b) => {
9
+ for (var prop in b || (b = {}))
10
+ if (__hasOwnProp.call(b, prop))
11
+ __defNormalProp(a, prop, b[prop]);
12
+ if (__getOwnPropSymbols)
13
+ for (var prop of __getOwnPropSymbols(b)) {
14
+ if (__propIsEnum.call(b, prop))
15
+ __defNormalProp(a, prop, b[prop]);
16
+ }
17
+ return a;
18
+ };
19
+ var __spreadProps = (a, b) => __defProps(a, __getOwnPropDescs(b));
20
+ var __objRest = (source, exclude) => {
21
+ var target = {};
22
+ for (var prop in source)
23
+ if (__hasOwnProp.call(source, prop) && exclude.indexOf(prop) < 0)
24
+ target[prop] = source[prop];
25
+ if (source != null && __getOwnPropSymbols)
26
+ for (var prop of __getOwnPropSymbols(source)) {
27
+ if (exclude.indexOf(prop) < 0 && __propIsEnum.call(source, prop))
28
+ target[prop] = source[prop];
29
+ }
30
+ return target;
31
+ };
32
+ var __async = (__this, __arguments, generator) => {
33
+ return new Promise((resolve, reject) => {
34
+ var fulfilled = (value) => {
35
+ try {
36
+ step(generator.next(value));
37
+ } catch (e) {
38
+ reject(e);
39
+ }
40
+ };
41
+ var rejected = (value) => {
42
+ try {
43
+ step(generator.throw(value));
44
+ } catch (e) {
45
+ reject(e);
46
+ }
47
+ };
48
+ var step = (x) => x.done ? resolve(x.value) : Promise.resolve(x.value).then(fulfilled, rejected);
49
+ step((generator = generator.apply(__this, __arguments)).next());
50
+ });
51
+ };
52
+
53
+ // src/generic.ts
54
+ import { serializeError, deserializeError } from "serialize-error";
55
+ function defineGenericMessanging(config) {
56
+ let removeRootListener;
57
+ let perTypeListeners = {};
58
+ function cleanupRootListener() {
59
+ if (Object.entries(perTypeListeners).length === 0) {
60
+ removeRootListener == null ? void 0 : removeRootListener();
61
+ removeRootListener = void 0;
62
+ }
63
+ }
64
+ let idSeq = Math.floor(Math.random() * 1e4);
65
+ function getNextId() {
66
+ return idSeq++;
67
+ }
68
+ return {
69
+ sendMessage(type, data, ...args) {
70
+ return __async(this, null, function* () {
71
+ var _a2, _b;
72
+ const message = {
73
+ id: getNextId(),
74
+ type,
75
+ data,
76
+ timestamp: Date.now()
77
+ };
78
+ (_a2 = config.logger) == null ? void 0 : _a2.debug(`[messaging] sendMessage {id=${message.id}} \u2500\u1405`, message, ...args);
79
+ const response = yield config.sendMessage(message, ...args);
80
+ const { res, err } = response != null ? response : { err: new Error("No response") };
81
+ (_b = config.logger) == null ? void 0 : _b.debug(`[messaging] sendMessage {id=${message.id}} \u140A\u2500`, { res, err });
82
+ if (err != null)
83
+ throw deserializeError(err);
84
+ return res;
85
+ });
86
+ },
87
+ onMessage(type, onReceived) {
88
+ var _a2, _b, _c;
89
+ if (removeRootListener == null) {
90
+ (_a2 = config.logger) == null ? void 0 : _a2.debug(
91
+ `[messaging] "${type}" initialized the message listener for this context`
92
+ );
93
+ removeRootListener = config.addRootListener((message) => {
94
+ var _a3, _b2;
95
+ if (typeof message.type != "string" || typeof message.timestamp !== "number") {
96
+ const err = Error(
97
+ `[messaging] Unknown message format, must include the 'type' & 'timestamp' fields, received: ${JSON.stringify(
98
+ message
99
+ )}`
100
+ );
101
+ (_a3 = config.logger) == null ? void 0 : _a3.error(err);
102
+ throw err;
103
+ }
104
+ (_b2 = config == null ? void 0 : config.logger) == null ? void 0 : _b2.debug("[messaging] Received message", message);
105
+ const listener = perTypeListeners[message.type];
106
+ if (listener == null)
107
+ return;
108
+ const res = listener(message);
109
+ return Promise.resolve(res).then((res2) => {
110
+ var _a4;
111
+ (_a4 = config == null ? void 0 : config.logger) == null ? void 0 : _a4.debug(`[messaging] onMessage {id=${message.id}} \u2500\u1405`, { res: res2 });
112
+ return { res: res2 };
113
+ }).catch((err) => {
114
+ var _a4;
115
+ (_a4 = config == null ? void 0 : config.logger) == null ? void 0 : _a4.debug(`[messaging] onMessage {id=${message.id}} \u2500\u1405`, { err });
116
+ return { err: serializeError(err) };
117
+ });
118
+ });
119
+ }
120
+ if (perTypeListeners[type] != null) {
121
+ const err = Error(
122
+ `[messaging] In this JS context, only one listener can be setup for ${type}`
123
+ );
124
+ (_b = config.logger) == null ? void 0 : _b.error(err);
125
+ throw err;
126
+ }
127
+ perTypeListeners[type] = onReceived;
128
+ (_c = config.logger) == null ? void 0 : _c.log(`[messaging] Added listener for ${type}`);
129
+ return () => {
130
+ delete perTypeListeners[type];
131
+ cleanupRootListener();
132
+ };
133
+ },
134
+ removeAllListeners() {
135
+ Object.keys(perTypeListeners).forEach((type) => {
136
+ delete perTypeListeners[type];
137
+ });
138
+ cleanupRootListener();
139
+ }
140
+ };
141
+ }
142
+
143
+ export {
144
+ __spreadValues,
145
+ __spreadProps,
146
+ __objRest,
147
+ __async,
148
+ defineGenericMessanging
149
+ };
@@ -0,0 +1,128 @@
1
+ /**
2
+ * Interface used to log text to the console when sending and recieving messages.
3
+ */
4
+ interface Logger {
5
+ debug(...args: any[]): void;
6
+ log(...args: any[]): void;
7
+ warn(...args: any[]): void;
8
+ error(...args: any[]): void;
9
+ }
10
+ /**
11
+ * Either a Promise of a type, or that type directly. Used to indicate that a method can by sync or
12
+ * async.
13
+ */
14
+ type MaybePromise<T> = Promise<T> | T;
15
+ /**
16
+ * Used to add a return type to a message in the protocol map.
17
+ *
18
+ * > Internally, this is just an object with random keys for the data and return types.
19
+ *
20
+ * @deprecated Use the function syntax instead: <https://webext-core.aklinker1.io/guide/messaging/protocol-maps.html#syntax>
21
+ *
22
+ * @example
23
+ * interface ProtocolMap {
24
+ * // data is a string, returns undefined
25
+ * type1: string;
26
+ * // data is a string, returns a number
27
+ * type2: ProtocolWithReturn<string, number>;
28
+ * }
29
+ */
30
+ interface ProtocolWithReturn<TData, TReturn> {
31
+ /**
32
+ * Stores the data type. Randomly named so that it isn't accidentally implemented.
33
+ */
34
+ BtVgCTPYZu: TData;
35
+ /**
36
+ * Stores the return type. Randomly named so that it isn't accidentally implemented.
37
+ */
38
+ RrhVseLgZW: TReturn;
39
+ }
40
+ /**
41
+ * Given a function declaration, `ProtocolWithReturn`, or a value, return the message's data type.
42
+ */
43
+ type GetDataType<T> = T extends (...args: infer Args) => any ? Args['length'] extends 0 | 1 ? Args[0] : never : T extends ProtocolWithReturn<any, any> ? T['BtVgCTPYZu'] : T;
44
+ /**
45
+ * Given a function declaration, `ProtocolWithReturn`, or a value, return the message's return type.
46
+ */
47
+ type GetReturnType<T> = T extends (...args: any[]) => infer R ? R : T extends ProtocolWithReturn<any, any> ? T['RrhVseLgZW'] : void;
48
+ /**
49
+ * Call to ensure an active listener has been removed.
50
+ *
51
+ * If the listener has already been removed with `Messenger.removeAllListeners`, this is a noop.
52
+ */
53
+ type RemoveListenerCallback = () => void;
54
+ /**
55
+ * Shared configuration between all the different messengers.
56
+ */
57
+ interface BaseMessagingConfig {
58
+ /**
59
+ * The logger to use when logging messages. Set to `null` to disable logging.
60
+ *
61
+ * @default console
62
+ */
63
+ logger?: Logger;
64
+ }
65
+ interface NamespaceMessagingConfig extends BaseMessagingConfig {
66
+ /**
67
+ * A string used to ensure the messenger only sends messages to and listens for messages from
68
+ * other messengers of the same type, with the same namespace.
69
+ */
70
+ namespace: string;
71
+ }
72
+ /**
73
+ * Contains information about the message recieved.
74
+ */
75
+ interface Message<TProtocolMap extends Record<string, any>, TType extends keyof TProtocolMap> {
76
+ /**
77
+ * A semi-unique, auto-incrementing number used to trace messages being sent.
78
+ */
79
+ id: number;
80
+ /**
81
+ * The data that was passed into `sendMessage`
82
+ */
83
+ data: GetDataType<TProtocolMap[TType]>;
84
+ type: TType;
85
+ /**
86
+ * The timestamp the message was sent in MS since epoch.
87
+ */
88
+ timestamp: number;
89
+ }
90
+
91
+ /**
92
+ * Messaging interface shared by all messengers.
93
+ *
94
+ * Type parameters accept:
95
+ * - `TProtocolMap` to define the data and return types of messages.
96
+ * - `TMessageExtension` to define additional fields that are available on a message inside
97
+ * `onMessage`'s callback
98
+ * - `TSendMessageArgs` to define a list of additional arguments for `sendMessage`
99
+ */
100
+ interface GenericMessenger<TProtocolMap extends Record<string, any>, TMessageExtension, TSendMessageArgs extends any[]> {
101
+ /**
102
+ * Send a message to the background or a specific tab if `tabId` is passed. You can call this
103
+ * function anywhere in your extension.
104
+ *
105
+ * If you haven't setup a listener for the sent `type`, an error will be thrown.
106
+ *
107
+ * @param type The message type being sent. Call `onMessage` with the same type to listen for that message.
108
+ * @param data The data to send with the message.
109
+ * @param args Different messengers will have additional arguments to configure how a message gets sent.
110
+ */
111
+ sendMessage<TType extends keyof TProtocolMap>(type: TType, data: GetDataType<TProtocolMap[TType]>, ...args: TSendMessageArgs): Promise<GetReturnType<TProtocolMap[TType]>>;
112
+ /**
113
+ * Trigger a callback when a message of the requested type is recieved. You cannot setup multiple
114
+ * listeners for the same message type in the same JS context.
115
+ *
116
+ * To remove the listener, call the returned message.
117
+ *
118
+ * @param type The message type to listen for. Call `sendMessage` with the same type to triggern this listener.
119
+ * @param onReceived The callback executed when a message is recieved.
120
+ */
121
+ onMessage<TType extends keyof TProtocolMap>(type: TType, onReceived: (message: Message<TProtocolMap, TType> & TMessageExtension) => void | MaybePromise<GetReturnType<TProtocolMap[TType]>>): RemoveListenerCallback;
122
+ /**
123
+ * Removes all listeners.
124
+ */
125
+ removeAllListeners(): void;
126
+ }
127
+
128
+ export { BaseMessagingConfig as B, GenericMessenger as G, Logger as L, MaybePromise as M, NamespaceMessagingConfig as N, ProtocolWithReturn as P, RemoveListenerCallback as R, GetDataType as a, GetReturnType as b, Message as c };
package/lib/index.cjs CHANGED
@@ -1,10 +1,27 @@
1
1
  "use strict";
2
2
  var __create = Object.create;
3
3
  var __defProp = Object.defineProperty;
4
+ var __defProps = Object.defineProperties;
4
5
  var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
6
+ var __getOwnPropDescs = Object.getOwnPropertyDescriptors;
5
7
  var __getOwnPropNames = Object.getOwnPropertyNames;
8
+ var __getOwnPropSymbols = Object.getOwnPropertySymbols;
6
9
  var __getProtoOf = Object.getPrototypeOf;
7
10
  var __hasOwnProp = Object.prototype.hasOwnProperty;
11
+ var __propIsEnum = Object.prototype.propertyIsEnumerable;
12
+ var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
13
+ var __spreadValues = (a, b) => {
14
+ for (var prop in b || (b = {}))
15
+ if (__hasOwnProp.call(b, prop))
16
+ __defNormalProp(a, prop, b[prop]);
17
+ if (__getOwnPropSymbols)
18
+ for (var prop of __getOwnPropSymbols(b)) {
19
+ if (__propIsEnum.call(b, prop))
20
+ __defNormalProp(a, prop, b[prop]);
21
+ }
22
+ return a;
23
+ };
24
+ var __spreadProps = (a, b) => __defProps(a, __getOwnPropDescs(b));
8
25
  var __export = (target, all) => {
9
26
  for (var name in all)
10
27
  __defProp(target, name, { get: all[name], enumerable: true });
@@ -18,6 +35,10 @@ var __copyProps = (to, from, except, desc) => {
18
35
  return to;
19
36
  };
20
37
  var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
38
+ // If the importer is in node compatibility mode or this is not an ESM
39
+ // file that has been converted to a CommonJS file using a Babel-
40
+ // compatible transform (i.e. "__esModule" has not been set), then set
41
+ // "default" to the CommonJS "module.exports" for node compatibility.
21
42
  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
22
43
  mod
23
44
  ));
@@ -49,104 +70,119 @@ __export(src_exports, {
49
70
  defineExtensionMessaging: () => defineExtensionMessaging
50
71
  });
51
72
  module.exports = __toCommonJS(src_exports);
73
+
74
+ // src/extension.ts
52
75
  var import_webextension_polyfill = __toESM(require("webextension-polyfill"), 1);
53
- function defineExtensionMessaging(config) {
54
- let rootListener;
76
+
77
+ // src/generic.ts
78
+ var import_serialize_error = require("serialize-error");
79
+ function defineGenericMessanging(config) {
80
+ let removeRootListener;
81
+ let perTypeListeners = {};
55
82
  function cleanupRootListener() {
56
- if (Object.entries(keyListeners).length === 0) {
57
- import_webextension_polyfill.default.runtime.onMessage.removeListener(rootListener);
58
- rootListener = void 0;
83
+ if (Object.entries(perTypeListeners).length === 0) {
84
+ removeRootListener == null ? void 0 : removeRootListener();
85
+ removeRootListener = void 0;
59
86
  }
60
87
  }
61
- let keyListeners = {};
62
88
  let idSeq = Math.floor(Math.random() * 1e4);
63
89
  function getNextId() {
64
90
  return idSeq++;
65
91
  }
66
- function onMessage(type, onReceived) {
67
- var _a, _b, _c;
68
- if (rootListener == null) {
69
- (_a = config == null ? void 0 : config.logger) == null ? void 0 : _a.debug(
70
- `[messaging] ${type} initialized message listener for this context`
71
- );
72
- rootListener = (message, sender) => {
73
- var _a2, _b2, _c2;
74
- if (typeof message.type != "string" || typeof message.timestamp !== "number") {
75
- const err = Error(
76
- `[messaging] Unknown message format, must include the 'type' & 'timestamp' fields, received: ${JSON.stringify(
77
- message
78
- )}`
79
- );
80
- (_a2 = config == null ? void 0 : config.logger) == null ? void 0 : _a2.error(err);
81
- throw err;
82
- }
83
- (_b2 = config == null ? void 0 : config.logger) == null ? void 0 : _b2.debug("[messaging] Received message", message, sender);
84
- const entries = Object.entries(keyListeners);
85
- for (const [type2, listener] of entries) {
86
- if (message.type !== type2)
87
- continue;
88
- (_c2 = config == null ? void 0 : config.logger) == null ? void 0 : _c2.debug(`[messaging] onMessage {id=${message.id}} \u140A\u2500`, message);
89
- const res = listener({
90
- data: message.data,
91
- sender,
92
- timestamp: message.timestamp
93
- });
92
+ return {
93
+ sendMessage(type, data, ...args) {
94
+ return __async(this, null, function* () {
95
+ var _a2, _b;
96
+ const message = {
97
+ id: getNextId(),
98
+ type,
99
+ data,
100
+ timestamp: Date.now()
101
+ };
102
+ (_a2 = config.logger) == null ? void 0 : _a2.debug(`[messaging] sendMessage {id=${message.id}} \u2500\u1405`, message, ...args);
103
+ const response = yield config.sendMessage(message, ...args);
104
+ const { res, err } = response != null ? response : { err: new Error("No response") };
105
+ (_b = config.logger) == null ? void 0 : _b.debug(`[messaging] sendMessage {id=${message.id}} \u140A\u2500`, { res, err });
106
+ if (err != null)
107
+ throw (0, import_serialize_error.deserializeError)(err);
108
+ return res;
109
+ });
110
+ },
111
+ onMessage(type, onReceived) {
112
+ var _a2, _b, _c;
113
+ if (removeRootListener == null) {
114
+ (_a2 = config.logger) == null ? void 0 : _a2.debug(
115
+ `[messaging] "${type}" initialized the message listener for this context`
116
+ );
117
+ removeRootListener = config.addRootListener((message) => {
118
+ var _a3, _b2;
119
+ if (typeof message.type != "string" || typeof message.timestamp !== "number") {
120
+ const err = Error(
121
+ `[messaging] Unknown message format, must include the 'type' & 'timestamp' fields, received: ${JSON.stringify(
122
+ message
123
+ )}`
124
+ );
125
+ (_a3 = config.logger) == null ? void 0 : _a3.error(err);
126
+ throw err;
127
+ }
128
+ (_b2 = config == null ? void 0 : config.logger) == null ? void 0 : _b2.debug("[messaging] Received message", message);
129
+ const listener = perTypeListeners[message.type];
130
+ if (listener == null)
131
+ return;
132
+ const res = listener(message);
94
133
  return Promise.resolve(res).then((res2) => {
95
- var _a3;
96
- (_a3 = config == null ? void 0 : config.logger) == null ? void 0 : _a3.debug(`[messaging] onMessage {id=${message.id}} \u2500\u1405`, { res: res2 });
134
+ var _a4;
135
+ (_a4 = config == null ? void 0 : config.logger) == null ? void 0 : _a4.debug(`[messaging] onMessage {id=${message.id}} \u2500\u1405`, { res: res2 });
97
136
  return { res: res2 };
98
137
  }).catch((err) => {
99
- var _a3;
100
- let errMessage;
101
- if (err instanceof Error)
102
- errMessage = err.message;
103
- else
104
- errMessage = String(err);
105
- (_a3 = config == null ? void 0 : config.logger) == null ? void 0 : _a3.debug(`[messaging] onMessage {id=${message.id}} \u2500\u1405`, { err });
106
- return { err: errMessage };
138
+ var _a4;
139
+ (_a4 = config == null ? void 0 : config.logger) == null ? void 0 : _a4.debug(`[messaging] onMessage {id=${message.id}} \u2500\u1405`, { err });
140
+ return { err: (0, import_serialize_error.serializeError)(err) };
107
141
  });
108
- }
142
+ });
143
+ }
144
+ if (perTypeListeners[type] != null) {
145
+ const err = Error(
146
+ `[messaging] In this JS context, only one listener can be setup for ${type}`
147
+ );
148
+ (_b = config.logger) == null ? void 0 : _b.error(err);
149
+ throw err;
150
+ }
151
+ perTypeListeners[type] = onReceived;
152
+ (_c = config.logger) == null ? void 0 : _c.log(`[messaging] Added listener for ${type}`);
153
+ return () => {
154
+ delete perTypeListeners[type];
155
+ cleanupRootListener();
109
156
  };
110
- import_webextension_polyfill.default.runtime.onMessage.addListener(rootListener);
111
- }
112
- if (keyListeners[type] != null) {
113
- const err = Error(
114
- `[messaging] In this JS context, only one listener can be setup for ${type}`
115
- );
116
- (_b = config == null ? void 0 : config.logger) == null ? void 0 : _b.error(err);
117
- throw err;
118
- }
119
- keyListeners[type] = onReceived;
120
- (_c = config == null ? void 0 : config.logger) == null ? void 0 : _c.log(`[messaging] Added listener for ${type}`);
121
- return function removeListener() {
122
- delete keyListeners[type];
157
+ },
158
+ removeAllListeners() {
159
+ Object.keys(perTypeListeners).forEach((type) => {
160
+ delete perTypeListeners[type];
161
+ });
123
162
  cleanupRootListener();
124
- };
125
- }
126
- function sendMessage(type, data, tabId) {
127
- return __async(this, null, function* () {
128
- var _a, _b;
129
- const message = { id: getNextId(), type, data, timestamp: Date.now() };
130
- (_a = config == null ? void 0 : config.logger) == null ? void 0 : _a.debug(`[messaging] sendMessage {id=${message.id}} \u2500\u1405`, message);
131
- let response;
163
+ }
164
+ };
165
+ }
166
+
167
+ // src/extension.ts
168
+ function defineExtensionMessaging(config) {
169
+ return defineGenericMessanging(__spreadProps(__spreadValues({}, config), {
170
+ sendMessage(message, tabId) {
132
171
  if (tabId == null)
133
- response = yield import_webextension_polyfill.default.runtime.sendMessage(message);
134
- else
135
- response = yield import_webextension_polyfill.default.tabs.sendMessage(tabId, message);
136
- const { res, err } = response != null ? response : { err: "No response" };
137
- (_b = config == null ? void 0 : config.logger) == null ? void 0 : _b.debug(`[messaging] sendMessage {id=${message.id}} \u140A\u2500`, { res, err });
138
- if (err != null)
139
- throw Error(err);
140
- return res;
141
- });
142
- }
143
- function removeAllMessageListeners() {
144
- Object.keys(keyListeners).forEach((type) => {
145
- delete keyListeners[type];
146
- });
147
- cleanupRootListener();
148
- }
149
- return { onMessage, sendMessage, removeAllMessageListeners };
172
+ return import_webextension_polyfill.default.runtime.sendMessage(message);
173
+ return import_webextension_polyfill.default.tabs.sendMessage(tabId, message);
174
+ },
175
+ addRootListener(processMessage) {
176
+ const listener = (message, sender) => {
177
+ if (typeof message === "object")
178
+ return processMessage(__spreadProps(__spreadValues({}, message), { sender }));
179
+ else
180
+ return processMessage(message);
181
+ };
182
+ import_webextension_polyfill.default.runtime.onMessage.addListener(listener);
183
+ return () => import_webextension_polyfill.default.runtime.onMessage.removeListener(listener);
184
+ }
185
+ }));
150
186
  }
151
187
  // Annotate the CommonJS export names for ESM import in node:
152
188
  0 && (module.exports = {
package/lib/index.d.ts CHANGED
@@ -1,118 +1,44 @@
1
+ import { B as BaseMessagingConfig, G as GenericMessenger } from './generic-77a327a6.js';
2
+ export { a as GetDataType, b as GetReturnType, L as Logger, M as MaybePromise, c as Message, N as NamespaceMessagingConfig, P as ProtocolWithReturn, R as RemoveListenerCallback } from './generic-77a327a6.js';
1
3
  import { Runtime } from 'webextension-polyfill';
2
4
 
3
5
  /**
4
- * Interface used to log text to the console when sending and recieving messages.
6
+ * Configuration passed into `defineExtensionMessaging`.
5
7
  */
6
- interface Logger {
7
- debug(...args: any[]): void;
8
- log(...args: any[]): void;
9
- warn(...args: any[]): void;
10
- error(...args: any[]): void;
8
+ interface ExtensionMessagingConfig extends BaseMessagingConfig {
11
9
  }
12
- interface ExtensionMessagingConfig {
10
+ /**
11
+ * Additional fields available on the `Message` from an `ExtensionMessenger`.
12
+ */
13
+ interface ExtensionMessage {
13
14
  /**
14
- * The logger to use when logging messages. Defaults to `console`.
15
- *
16
- * Set to `null` to disable logging.
15
+ * Information about where the message came from. See
16
+ * [`Runtime.MessageSender`](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime/MessageSender).
17
17
  */
18
- logger?: Logger;
18
+ sender: Runtime.MessageSender;
19
19
  }
20
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> = {
34
- BtVgCTPYZu: TData;
35
- RrhVseLgZW: TReturn;
36
- };
37
- /**
38
- * Given a function declaration, `ProtocolWithReturn`, or a value, return the message's data type.
39
- */
40
- declare type GetDataType<T> = T extends (...args: infer Args) => any ? Args['length'] extends 0 | 1 ? Args[0] : never : T extends ProtocolWithReturn<any, any> ? T['BtVgCTPYZu'] : T;
41
- /**
42
- * Given a function declaration, `ProtocolWithReturn`, or a value, return the message's return type.
43
- */
44
- declare type GetReturnType<T> = T extends (...args: any[]) => infer R ? R : 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.
21
+ * Send messsage accepts an additional, optional argument `tabId`. Pass it to send a message to a
22
+ * specific tab from the background script.
59
23
  *
60
- * Unlike the regular `chrome.runtime` messaging APIs, there are no limitations to when you call `onMessage` or `sendMessage`.
24
+ * You cannot message between tabs directly. It must go through the background script.
61
25
  */
62
- interface Messenger<TProtocolMap> {
26
+ type ExtensionSendMessageArgs = [
63
27
  /**
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.
28
+ * The tab to send a message to.
72
29
  */
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
- }
30
+ tabId?: number
31
+ ];
89
32
  /**
90
- * Contains information about the message recieved.
33
+ * Messenger returned by `defineExtensionMessaging`.
91
34
  */
92
- interface Message<TProtocolMap, TType extends keyof TProtocolMap> {
93
- /**
94
- * A semi-unique, auto-incrementing number used to trace messages being sent.
95
- */
96
- id: number;
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
- */
105
- sender: Runtime.MessageSender;
106
- /**
107
- * The timestamp the message was sent in MS since epoch.
108
- */
109
- timestamp: number;
110
- }
35
+ type ExtensionMessenger<TProtocolMap extends Record<string, any>> = GenericMessenger<TProtocolMap, ExtensionMessage, ExtensionSendMessageArgs>;
111
36
  /**
112
- * Creates a new `Messenger` used to send and recieve messages in your extension.
37
+ * Returns an `ExtensionMessenger` that is backed by the `browser.runtime.sendMessage` and
38
+ * `browser.tabs.sendMessage` APIs.
113
39
  *
114
- * @param config Configure the behavior of the messenger.
40
+ * It can be used to send messages to and from the background page/service worker.
115
41
  */
116
- declare function defineExtensionMessaging<TProtocolMap = Record<string, ProtocolWithReturn<any, any>>>(config?: ExtensionMessagingConfig): Messenger<TProtocolMap>;
42
+ declare function defineExtensionMessaging<TProtocolMap extends Record<string, any> = Record<string, any>>(config?: ExtensionMessagingConfig): ExtensionMessenger<TProtocolMap>;
117
43
 
118
- export { ExtensionMessagingConfig, GetDataType, GetReturnType, Logger, MaybePromise, Messenger, ProtocolWithReturn, RemoveListenerCallback, defineExtensionMessaging };
44
+ export { BaseMessagingConfig, ExtensionMessage, ExtensionMessagingConfig, ExtensionMessenger, ExtensionSendMessageArgs, defineExtensionMessaging };