├── .gitignore
├── LICENSE
├── README.md
├── package.json
├── rollup.config.js
├── src
    ├── lib
    │   ├── main_lib.ts
    │   ├── restorer_lib.ts
    │   ├── shared_lib.ts
    │   └── window_lib.ts
    ├── main.ts
    ├── preload.ts
    └── window.ts
├── test
    ├── api
    │   ├── bad_mainapi.ts
    │   ├── bad_windowapi.ts
    │   ├── call_mainapi1.ts
    │   ├── call_mainapi2.ts
    │   ├── call_mainapi3a.ts
    │   ├── call_mainapi3b.ts
    │   ├── call_mainapi4.ts
    │   ├── call_winapi1.ts
    │   ├── call_winapi2.ts
    │   ├── call_winapi3.ts
    │   ├── mainapi.ts
    │   ├── mainapi1.ts
    │   ├── mainapi2.ts
    │   ├── mainapi3.ts
    │   ├── mainapi4.ts
    │   ├── verify_mainapi1.ts
    │   ├── verify_mainapi2.ts
    │   ├── verify_mainapi4.ts
    │   ├── verify_winapi1.ts
    │   ├── verify_winapi2.ts
    │   ├── verify_winapi3.ts
    │   ├── winapi1.ts
    │   ├── winapi2.ts
    │   └── winapi3.ts
    ├── lib
    │   ├── config.ts
    │   ├── main_util.ts
    │   ├── renderer_util.ts
    │   └── shared_util.ts
    ├── main-scripts
    │   ├── main_nonrelayed_error.ts
    │   ├── main_return_relayed.ts
    │   ├── main_win1_timeout1.ts
    │   ├── main_win1_timeout2.ts
    │   ├── main_win2_timeout.ts
    │   └── main_window_closed.ts
    ├── run-tests
    ├── test_calling_windows.ts
    ├── test_main_crash.ts
    ├── test_main_patience.ts
    ├── test_single_main_api.ts
    ├── test_single_window_api.ts
    ├── test_type_errors.ts
    ├── test_window_reload.ts
    ├── test_window_timeout.ts
    ├── test_windows_calling.ts
    └── window-scripts
    │   ├── dummy.html
    │   ├── tsconfig.json
    │   ├── win1_mainapi1+2.ts
    │   ├── win1_mainapi1.ts
    │   ├── win1_mainapi2_reload_1.ts
    │   ├── win1_mainapi2_reload_2.ts
    │   ├── win1_mainapi3a.ts
    │   ├── win1_mainapi3b.ts
    │   ├── win1_winapi1+2.ts
    │   ├── win1_winapi1.ts
    │   ├── win1_winapi1_delayed.ts
    │   ├── win2_mainapi1+4.ts
    │   ├── win2_mainapi2_timeout.ts
    │   ├── win2_winapi1+3.ts
    │   └── win3_mainapi2_timeout.ts
├── tsconfig.json
└── yarn.lock


/.gitignore:
--------------------------------------------------------------------------------
  1 | .DS_Store
  2 | build/
  3 | 
  4 | # Logs
  5 | logs
  6 | *.log
  7 | npm-debug.log*
  8 | yarn-debug.log*
  9 | yarn-error.log*
 10 | lerna-debug.log*
 11 | 
 12 | # Diagnostic reports (https://nodejs.org/api/report.html)
 13 | report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
 14 | 
 15 | # Runtime data
 16 | pids
 17 | *.pid
 18 | *.seed
 19 | *.pid.lock
 20 | 
 21 | # Directory for instrumented libs generated by jscoverage/JSCover
 22 | lib-cov
 23 | 
 24 | # Coverage directory used by tools like istanbul
 25 | coverage
 26 | *.lcov
 27 | 
 28 | # nyc test coverage
 29 | .nyc_output
 30 | 
 31 | # Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
 32 | .grunt
 33 | 
 34 | # Bower dependency directory (https://bower.io/)
 35 | bower_components
 36 | 
 37 | # node-waf configuration
 38 | .lock-wscript
 39 | 
 40 | # Compiled binary addons (https://nodejs.org/api/addons.html)
 41 | build/Release
 42 | 
 43 | # Dependency directories
 44 | node_modules/
 45 | jspm_packages/
 46 | 
 47 | # TypeScript v1 declaration files
 48 | typings/
 49 | 
 50 | # TypeScript cache
 51 | *.tsbuildinfo
 52 | 
 53 | # Optional npm cache directory
 54 | .npm
 55 | 
 56 | # Optional eslint cache
 57 | .eslintcache
 58 | 
 59 | # Microbundle cache
 60 | .rpt2_cache/
 61 | .rts2_cache_cjs/
 62 | .rts2_cache_es/
 63 | .rts2_cache_umd/
 64 | 
 65 | # Optional REPL history
 66 | .node_repl_history
 67 | 
 68 | # Output of 'npm pack'
 69 | *.tgz
 70 | 
 71 | # Yarn Integrity file
 72 | .yarn-integrity
 73 | 
 74 | # dotenv environment variables file
 75 | .env
 76 | .env.test
 77 | 
 78 | # parcel-bundler cache (https://parceljs.org/)
 79 | .cache
 80 | 
 81 | # Next.js build output
 82 | .next
 83 | 
 84 | # Nuxt.js build / generate output
 85 | .nuxt
 86 | dist
 87 | 
 88 | # Gatsby files
 89 | .cache/
 90 | # Comment in the public line in if your project uses Gatsby and *not* Next.js
 91 | # https://nextjs.org/blog/next-9-1#public-directory-support
 92 | # public
 93 | 
 94 | # vuepress build output
 95 | .vuepress/dist
 96 | 
 97 | # Serverless directories
 98 | .serverless/
 99 | 
100 | # FuseBox cache
101 | .fusebox/
102 | 
103 | # DynamoDB Local files
104 | .dynamodb/
105 | 
106 | # TernJS port file
107 | .tern-port
108 | 


--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
 1 | MIT License
 2 | 
 3 | Copyright (c) 2021 Joseph T. Lapp
 4 | 
 5 | Permission is hereby granted, free of charge, to any person obtaining a copy
 6 | of this software and associated documentation files (the "Software"), to deal
 7 | in the Software without restriction, including without limitation the rights
 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 | 
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 | 
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
   1 | # electron-affinity
   2 | 
   3 | Electron IPC via simple method calls
   4 | 
   5 | ## Introduction
   6 | 
   7 | Electron Affinity is a small TypeScript library that makes IPC as simple as possible in Electron. It has the following features:
   8 | 
   9 | - IPC services are merely methods on vanilla classes, callable both locally and remotely.
  10 | - Organizes IPC methods into distinct named APIs, each defined by its own class.
  11 | - Makes APIs remotely available merely by handing instances of their classes to a library function.
  12 | - Remotely binds APIs merely by passing their names to a library function.
  13 | - Changes made to the TypeScript signature of an API instantly change the remotely available signature.
  14 | - Optionally restores transferred objects back into classes via custom restoration functions, enabling APIs to have class instance parameters and return values.
  15 | - Allows main APIs to cause exceptions to be thrown in the calling window by wrapping the exception in an instance of `RelayedError` and throwing this instance.
  16 | - Main APIs are all asynchronous functions using Electron's `ipcRenderer.invoke`, while window APIs all use Electron's `window.webContents.send` and return no value.
  17 | - Uses context isolation and does not require node integration, maximizing security.
  18 | 
  19 | In short, this library implements IPC as remote procedure calls (RPC). For an overview of the library's inner workings, you might read [this article](https://javascript.plainenglish.io/electron-rpc-using-the-magic-of-typescript-9d24530ea8f1).
  20 | 
  21 | > NOTE ON JAVASCRIPT: The library should work with plain JavaScript, but I have not tried it, so I don't know what special considerations might require documentation.
  22 | 
  23 | ## Problems Addressed
  24 | 
  25 | This library was designed to address many of the problems that can arise when using IPC in Electron. Every design decision was intended to either eliminate a problem or catch a problem and produce a helpful error message. Here are some of the problems addressed:
  26 | 
  27 | - Misspelled or inconsistently changed IPC channel names break calls.
  28 | - There are two channel name spaces, and an IPC can be handled in one but called in the other.
  29 | - Types for each IPC are managed in multiple places, allowing argument and return types to disagree between the main process and the renderer.
  30 | - Class instances become untyped objects when transmitted over IPC.
  31 | - Implementing IPC requires lots of boilerplate code on both sides.
  32 | - Extra effort is required to make local IPC functionality locally available.
  33 | - Exceptions are local, with no mechanism for transferring caller-caused errors back to the caller to be rethrown.
  34 | - Coding IPC with context isolation, without node integration is typically complex.
  35 | 
  36 | _Special thanks to **[Electron Mocha](https://github.com/jprichardson/electron-mocha)**, which made it possible for me to thoroughly test each iteration of the solution until everything worked as expected._
  37 | 
  38 | ## Installation
  39 | 
  40 | `npm install electron-affinity`
  41 | 
  42 | or
  43 | 
  44 | `yarn add electron-affinity`
  45 | 
  46 | ## Usage
  47 | 
  48 | Electron Affinity supports main APIs and window APIs. Main APIs are defined in the main process and callable from renderer windows. Window APIs are defined in renderer windows and callable from the main process. Window-to-window calling is not supported, as [JavaScript allows for messaging between windows](https://stackoverflow.com/a/68868073/650894), and it is an option to relay all communication through the main process.
  49 | 
  50 | The first two sections on usage, "Main APIs" and "Window APIs", are all you need to read to get an understanding of this library.
  51 | 
  52 | ### Main APIs
  53 | 
  54 | A main API is an instance of a class defined in the main process. All methods of this class, including ancestor class methods, are treated as IPC methods except for those prefixed with underscore (`_`) or pound (`#`). You can therefore use these prefixes to define private properties and methods on which the IPC methods rely.
  55 | 
  56 | Each main API method can take any number of parameters, including none, but must return a promise. The promise need not resolve to a value.
  57 | 
  58 | Here is an example main API called `DataApi`:
  59 | 
  60 | ```ts
  61 | import { ElectronMainApi, RelayedError } from "electron-affinity/main";
  62 | 
  63 | export class DataApi implements ElectronMainApi<DataApi> {
  64 |   _dataSource: DataSource;
  65 |   _dataset: Dataset | null = null;
  66 | 
  67 |   constructor(dataSource: DataSource) {
  68 |     this._dataSource = dataSource;
  69 |   }
  70 | 
  71 |   async openDataset(setName: string, timeout: number) {
  72 |     this._dataset = this._dataSource.open(setName, timeout);
  73 |   }
  74 | 
  75 |   async readData() {
  76 |     const data = await this._dataset!.read();
  77 |     this._checkForError();
  78 |     return data;
  79 |   }
  80 | 
  81 |   async writeData(data: Data) {
  82 |     await this._dataset!.write(data.format());
  83 |     this._checkForError();
  84 |   }
  85 | 
  86 |   async closeDataset() {
  87 |     this._dataset!.close();
  88 |     this._dataset = null;
  89 |   }
  90 | 
  91 |   private _checkForError() {  // okay to use 'private' with '_'
  92 |     const err: DataError | null = this._dataSource.getError();
  93 |     if (err) throw new RelayedError(err);
  94 |   }
  95 | }
  96 | ```
  97 | 
  98 | Here are a few things to note about this API:
  99 | 
 100 | - The API implements `ElectronMainApi<T>` to get enforcement of main API type constraints, replacing `T` with the API's own class name.
 101 | - All methods return promises even when they don't need to. This allows all IPC calls to the main process to use `ipcRenderer.invoke()`, keeping Electron Affinity simple.
 102 | - Even though `writeData()` received `data` via IPC, it exists as an instance of class `Data` with the `format()` method available.
 103 | - Property names `_dataSource`, `_dataset`, and `_checkforError()` are not exposed as IPC methods because they prefixed with `_`. In ES2022 you can also use the `#` prefix.
 104 | - It's okay to also use `private` and `protected` modifiers. These modifiers do cause TypeScript to error if you attempt to remotely access the properties they modify, but remote bindings will still be created for any property not prefixed with `_` or `#`.
 105 | - If the data source encounters an error, `_checkForError()` returns the error (sans stack trace) to the window to be thrown from within the renderer.
 106 | - Exceptions thrown by `open()`, `read()`, or `write()` do not get returned to the window and instead cause exceptions within the main process.
 107 | 
 108 | The main process makes this API available to windows by calling `exposeMainApi` before the windows attempt to use the API:
 109 | 
 110 | ```ts
 111 | import { exposeMainApi } from "electron-affinity/main";
 112 | 
 113 | exposeMainApi(new DataApi(dataSource), restorer);
 114 | ```
 115 | 
 116 | `restorer` is an optional function-typed argument that takes responsibility for restoring the classes of transferred objects. It only restores those classes that the API requires be restored. [See below](#restoring-classes) for an explanation of its use.
 117 | 
 118 | A window uses the API as follows:
 119 | 
 120 | ```ts
 121 | import { bindMainApi } from "electron-affinity/window";
 122 | import type { DataApi } from "path/to/data_api";
 123 | 
 124 | async function loadWeatherData() {
 125 |   const dataApi = await bindMainApi<DataApi>("DataApi");
 126 | 
 127 |   dataApi.openDataset("weather-data", 500);
 128 |   try {
 129 |     let data = await dataApi.readData();
 130 |     while (data !== null) {
 131 |       /* do something with the data */
 132 |       data = await dataApi.readData();
 133 |     }
 134 |   } catch (err) {
 135 |     if (err instanceof DataError) {
 136 |       /* handle relayed error */
 137 |     }
 138 |   }
 139 |   dataApi.closeDataset();
 140 | }
 141 | ```
 142 | 
 143 | Note the following about calling the API:
 144 | 
 145 | - The code imports the _type_ `DataApi` rather than the class `DataApi`. This keeps the renderer from pulling in main process code.
 146 | - `bindMainApi()` takes both the type parameter `DataApi` and the string name of the API `"DataApi"`. The names must agree. If they don't, you'll get a runtime error saying that the API cannot be found.
 147 | - The main process must have previously exposed the API. The window will not wait for the main process to subsequently expose it.
 148 | - The code calls a main API method as if it were local to the window.
 149 | - There is no need to wait on APIs, particularly those that technically didn't need to be declared asynchronous (but were to satisfy Electron Affinity).
 150 | 
 151 | Finally, include the following line in your `preload.js`:
 152 | 
 153 | ```ts
 154 | import "electron-affinity/preload";
 155 | ```
 156 | 
 157 | Alternatively, preload directly from `node_modules` using the appropriate path:
 158 | 
 159 | ```ts
 160 | // src/main.ts
 161 | 
 162 | const window = new BrowserWindow({
 163 |   webPreferences: {
 164 |     preload: path.join(
 165 |       __dirname,
 166 |       "../node_modules/electron-affinity/preload.js"
 167 |     ),
 168 |     nodeIntegration: false,
 169 |     contextIsolation: true,
 170 |   },
 171 | });
 172 | ```
 173 | 
 174 | ### Window APIs
 175 | 
 176 | Window APIs are analogous to main APIs, except that they are defined in the renderer and don't return a value. All methods of a window API class, including ancestor class methods, are treated as IPC methods except for those prefixed with underscore (`_`) or pound (`#`). As with main APIs, they can take any number of parameters, including none.
 177 | 
 178 | Here is an example window API called `StatusApi`:
 179 | 
 180 | ```ts
 181 | import type { ElectronWindowApi } from 'electron-affinity/window';
 182 | 
 183 | export class StatusApi implements ElectronWindowApi<StatusApi> {
 184 |   _receiver: StatusReceiver;
 185 | 
 186 |   constructor(receiver: StatusReceiver) {
 187 |     this._receiver = receiver;
 188 |   }
 189 | 
 190 |   progressUpdate(percentCompleted: number) {
 191 |     this._receiver.updateStatusBar(percentCompleted);
 192 |   }
 193 | 
 194 |   async systemReport(report: SystemReport) {
 195 |     const summary = await report.generateSummary();
 196 |     this._receiver.updateMessage(summary);
 197 |   }
 198 | }
 199 | ```
 200 | 
 201 | Note the following about this API:
 202 | 
 203 | - The API implements `ElectronWindowApi<T>` to get enforcement of window API type constraints, replacing `T` with the API's own class name.
 204 | - The methods are implemented as `window.webContents.send()` calls; the return values of window API methods are not returned. Code within the main process always shows their return values as void.
 205 | - Methods can by asynchronous, but the main process cannot wait for them to resolve.
 206 | - Even though `systemReport` received `report` via IPC, it exists as an instance of `SystemReport` with the `generateSummary()` method available.
 207 | - The `_` prefix prevents the member `_receiver` from being exposed as an IPC method. The prefix `#` would have done the same in ES2022. Declaring a property `private` or `protected` is sufficient to keep TypeScript from allowing you to remotely reference a property, but it is insufficient to keep remote bindings from being generated for the property.
 208 | - Exceptions thrown by any of these methods do not get returned to the main process.
 209 | 
 210 | The window makes the API available to the main process by calling `exposeWindowApi`:
 211 | 
 212 | ```ts
 213 | import { exposeWindowApi } from "electron-affinity/window";
 214 | 
 215 | exposeWindowApi(new StatusApi(receiver), restorer);
 216 | ```
 217 | 
 218 | `restorer` is an optional function-typed argument that takes responsibility for restoring the classes of transferred objects. It only restores those classes that the API requires be restored. [See below](#restoring-classes) for an explanation of its use.
 219 | 
 220 | The main process uses the API as follows:
 221 | 
 222 | ```ts
 223 | import { bindWindowApi } from "electron-affinity/main";
 224 | import type { StatusApi } from "path/to/status_api";
 225 | 
 226 | async function doWork() {
 227 |   const statusApi = await bindWindowApi<StatusApi>(window, "StatusApi");
 228 | 
 229 |   /* ... */
 230 |   statusApi.progressUpdate(percentCompleted);
 231 |   /* ... */
 232 |   statusApi.systemReport(report);
 233 |   /* ... */
 234 | }
 235 | ```
 236 | 
 237 | Note the following about calling the API:
 238 | 
 239 | - The code imports the _type_ `StatusApi` rather than the class `StatusApi`. This keeps the main process from pulling in window-side code.
 240 | - `bindWindowApi()` takes both the type parameter `StatusApi` and the string name of the API `"StatusApi"`. The names must agree. If they don't, you'll get a runtime error saying that the API cannot be found.
 241 | - `bindWindowApi()` takes a reference to the `BrowserWindow` to which the API is bound. Each API is bound to a single window and messages only that window.
 242 | - The code calls a window API method as if it were local to the main process.
 243 | - The main process does not need to do anything special to wait for the window to finish loading. `bindWindowApi` will keep attempting to bind until timing out.
 244 | 
 245 | Window APIs also require that you preload `electron-affinity/preload`.
 246 | 
 247 | ### Organizing Main APIs
 248 | 
 249 | Each main API must be exposed and bound individually. A good practice is to define each API in its own file, exporting the API class. Your main process code then imports them and exposes them one at a time. For example:
 250 | 
 251 | ```ts
 252 | // src/main.ts
 253 | 
 254 | import { exposeMainApi } from "electron-affinity/main";
 255 | import type { DataApi } from "path/to/status_api";
 256 | import type { UploadApi } from "path/to/message_api";
 257 | 
 258 | exposeMainApi(new DataApi());
 259 | exposeMainApi(new UploadApi());
 260 | ```
 261 | 
 262 | However, the main process may want to call these APIs itself. In this case, it's useful to attach them to the `global` variable. We might do so as follows:
 263 | 
 264 | ```ts
 265 | // src/backend/apis/main_apis.ts
 266 | 
 267 | import { exposeMainApi } from "electron-affinity/main";
 268 | import { DataApi } from "path/to/status_api";
 269 | import { UploadApi } from "path/to/message_api";
 270 | 
 271 | export type MainApis = ReturnType<typeof installMainApis>;
 272 | 
 273 | export function installMainApis() {
 274 |   const apis = {
 275 |     dataApi: new DataApi(),
 276 |     uploadApi: new UploadApi(),
 277 |     /* ... */
 278 |   };
 279 |   for (const api of Object.values(apis)) {
 280 |     exposeMainApi(api as any);
 281 |   }
 282 |   global.mainApis = apis as any;
 283 | }
 284 | ```
 285 | 
 286 | (See [Generic Use of APIs](#generic-use-of-apis) for how to type check APIs in the above code without relying on the API classes having implemented `ElectronMainApi` or `ElectronWindowApi`.)
 287 | 
 288 | This approach doesn't give us type-checking on calls to the APIs made from within the main process. To get this, put the following in a `global.d.ts` file:
 289 | 
 290 | ```ts
 291 | // src/backend/global.d.ts
 292 | 
 293 | import { MainApis } from "./backend/apis/main_apis";
 294 | 
 295 | declare global {
 296 |   var mainApis: MainApis;
 297 | }
 298 | ```
 299 | 
 300 | Finally, call `installMainApis` when initializing the main process. Now any main process code can call the APIs:
 301 | 
 302 | ```ts
 303 | global.mainApis.dataApi.openDataset("weather-data", 500);
 304 | let data = await global.mainApis.dataApi.readData();
 305 | await global.mainApis.uploadApi.upload(filename);
 306 | ```
 307 | 
 308 | Windows are able to bind to main APIs after the main process has installed them, but a window must wait for each binding to complete before using the API. This requires API bindings to occur within asynchronous functions. One way to do this is to create a function for just this purpose:
 309 | 
 310 | ```ts
 311 | // src/frontend/main_apis.ts
 312 | 
 313 | import { bindMainApi, AwaitedType } from "electron-affinity/window";
 314 | 
 315 | import type { DataApi } from "path/to/status_api";
 316 | import type { UploadApi } from "path/to/message_api";
 317 | 
 318 | export type MainApis = AwaitedType<typeof bindMainApis>;
 319 | 
 320 | export async function bindMainApis() {
 321 |   return {
 322 |     dataApi: await bindMainApi<DataApi>("DataApi"),
 323 |     uploadApi: await bindMainApi<UploadApi>("UploadApi"),
 324 |     /* ... */
 325 |   };
 326 | }
 327 | ```
 328 | 
 329 | During initialization, have the window script call `bindMainApis`:
 330 | 
 331 | ```ts
 332 | // src/frontend/init.ts
 333 | 
 334 | window.apis = await bindMainApis();
 335 | ```
 336 | 
 337 | To get type-checking on calls to these APIs, add the following to `global.d.ts`:
 338 | 
 339 | ```ts
 340 | // src/frontend/global.d.ts
 341 | 
 342 | import type { MainApis } from "./lib/main_apis";
 343 | 
 344 | declare global {
 345 |   interface Window {
 346 |     apis: MainApis;
 347 |   }
 348 | }
 349 | ```
 350 | 
 351 | Assuming all windows bind to all main APIs, you can use `window.apis` to call any of the main APIs:
 352 | 
 353 | ```ts
 354 | window.apis.dataApi.openDataset("weather-data", 500);
 355 | let data = await window.apis.dataApi.readData();
 356 | await window.apis.uploadApi.upload(filename);
 357 | ```
 358 | 
 359 | ### Organizing Window APIs
 360 | 
 361 | Each window API must be exposed and bound individually. A good practice is to define each API in its own file, exporting the API class. Your window script then imports them and exposes them one at a time. For example:
 362 | 
 363 | ```ts
 364 | // src/frontend/init.ts
 365 | 
 366 | import { exposeWindowApi } from "electron-affinity/window";
 367 | 
 368 | import { StatusApi } from "./apis/status_api";
 369 | import { MessageApi } from "./apis/message_api";
 370 | import { ReportStatusApi } from "./apis/report_status_api";
 371 | 
 372 | exposeWindowApi(new StatusApi());
 373 | exposeWindowApi(new MessageApi());
 374 | exposeWindowApi(new ReportStatusApi());
 375 | /* ... */
 376 | ```
 377 | 
 378 | It helps to create a module in the main process that binds the APIs for each different kind of window. In the following, `AwaitedType` extracts the type of value to which a promise resolves and prevents you from having to redeclare the API:
 379 | 
 380 | ```ts
 381 | // src/backend/window_apis.ts
 382 | 
 383 | import type { BrowserWindow } from "electron";
 384 | import { AwaitedType, bindWindowApi } from "electron-affinity/main";
 385 | 
 386 | import type { StatusApi } from "../frontend/apis/status_api";
 387 | import type { MessageApi } from "../frontend/apis/message_api";
 388 | 
 389 | export type MainWindow = AwaitedType<typeof bindMainWindowApis>;
 390 | export type ReportWindow = AwaitedType<typeof bindReportWindowApis>;
 391 | 
 392 | export async function bindMainWindowApis(window: BrowserWindow) {
 393 |   return Object.assign(window, {
 394 |     apis: {
 395 |       statusApi: await bindWindowApi<StatusApi>(window, "StatusApi"),
 396 |       messageApi: await bindWindowApi<MessageApi>(window, "MessageApi"),
 397 |     },
 398 |   });
 399 | }
 400 | 
 401 | export async function bindReportWindowApis(window: BrowserWindow) {
 402 |   return Object.assign(window, {
 403 |     apis: {
 404 |       reportStatusApi: await bindWindowApi<ReportStatusApi>(
 405 |         window,
 406 |         "ReportStatusApi"
 407 |       ),
 408 |     },
 409 |   });
 410 | }
 411 | ```
 412 | 
 413 | These bind methods place APIs on `window.apis`. Here is how you might attach `apis` to the main window:
 414 | 
 415 | ```ts
 416 | // src/main.ts
 417 | 
 418 | import { MainWindow } from "./window_apis";
 419 | 
 420 | function createMainWindow(): MainWindow {
 421 |   const mainWindow = new BrowserWindow({
 422 |     /* ... */
 423 |   }) as MainWindow;
 424 |   mainWindow.loadURL(url).then(async () => {
 425 |     await bindMainWindowApis(mainWindow);
 426 |     /* ... */
 427 |   });
 428 |   /* ... */
 429 |   return mainWindow;
 430 | }
 431 | ```
 432 | 
 433 | Notice that (1) the window must exist in order to bind to any of its APIs, and (2) if you're going to wait for the binding to complete, you must have previously loaded the window script that exposes the APIs to be bound.
 434 | 
 435 | And now you can call the APIs as follows:
 436 | 
 437 | ```ts
 438 | mainWindow.apis.statusApi.progressUpdate(progressPercent);
 439 | mainWindow.apis.messageApi.sendMessage(message);
 440 | ```
 441 | 
 442 | > NOTE FOR SVELTE: If your window API needs to import from svelte modules, you'll want to put the API within `<script lang="ts" context="module">` of a svelte file, but then you'll find your backend trying to `import type` from that svelte file. I found this doable with a little extra configuration. First, I added `"extends": "@tsconfig/svelte/tsconfig.json"` to the `tsconfig.json` for my backend code. Surprisingly, the only side-effect I encountered was having to `import type` everywhere in the backend that was only using the type. Second, I added a `.d.ts` file that declares the window APIs, such as the following (filename doesn't matter):
 443 | 
 444 | ```ts
 445 | // src/backend/svelte.d.ts
 446 | 
 447 | declare module "*.svelte" {
 448 |   // don't change '*.svelte'
 449 |   export { StatusApi } from "../frontend/apis/status_api.svelte";
 450 |   export { MessageApi } from "../frontend/apis/message_api.svelte";
 451 | }
 452 | ```
 453 | 
 454 | ### Subclassing APIs
 455 | 
 456 | API classes may subclass other API classes. Electron Affinity exposes and binds the methods of ancestor API classes, but subclasses do not inherit the library's API type constraints. To get type constraints on a subclass, append the appropriate `implements` clause to its definition. Examples:
 457 | 
 458 | ```ts
 459 | import { ElectronMainApi } from "electron-affinity/main";
 460 | 
 461 | export class ExtendedDataApi extends DataApi
 462 |     implements ElectronMainApi<ExtendedDataApi>
 463 | {
 464 |   /* ... */
 465 | }
 466 | ```
 467 | 
 468 | ```ts
 469 | import { ElectronWindowApi } from "electron-affinity/window";
 470 | 
 471 | export class ExtendedStatusApi extends StatusApi
 472 |     implements ElectronWindowApi<ExtendedStatusApi>
 473 | {
 474 |   /* ... */
 475 | }
 476 | ```
 477 | 
 478 | ### Restoring Classes
 479 | 
 480 | Electron Affinity allows class instances to be sent and received via IPC so that they arrive as class instances instead of as untyped, methodless objects. Electron already provides this functionality for basic, built-in classes, such as `Date`, but you can use this library's class restoration mechanism to restore any custom class.
 481 | 
 482 | You only restore the classes you want to restore, letting all other class instances transfer as untyped objects. Do so by defining a restorer function conforming to the `RestorerFunction` type, available to both the main process and windows:
 483 | 
 484 | ```ts
 485 | type RestorerFunction = (className: string, obj: Record<string, any>) => any;
 486 | ```
 487 | 
 488 | The function takes the name of a class and the untyped object into which the instance was converted during transfer, and it returns an instance of the class reconstructed from the object. If it does not recognize the class name or does not wish to restore the particular class, it simply returns the provide object. Here's an example:
 489 | 
 490 | ```ts
 491 | class Catter {
 492 |   s1: string;
 493 |   s2: string;
 494 | 
 495 |   constructor(s1: string, s2: string) {
 496 |     this.s1 = s1;
 497 |     this.s2 = s2;
 498 |   }
 499 | 
 500 |   // this method will be available after restoration
 501 |   cat() {
 502 |     return s1 + s2;
 503 |   }
 504 | }
 505 | 
 506 | const restorer = (className: string, obj: Record<string, any>) {
 507 |   if (className == "Catter") {
 508 |     return new Catter1(obj.s1, obj.s2);
 509 |   }
 510 |   return obj;
 511 | }
 512 | ```
 513 | 
 514 | Proper encapsulation would have us put the restoration functionality on the class itself. Fortunately, Electron Affinity makes this easy to do. First, add a static method called `restoreClass` to each class that is to be restorable, having it take an untyped object and return an instance of the class sourced from that object. Second, bind a class-name-to-class mapping of these classes to the library function `genericRestorer`, and use this bound function as your restoration function. Here's an example:
 515 | 
 516 | ```ts
 517 | import type { genericRestorer } from "electron-affinity/main";
 518 | 
 519 | export class Catter {
 520 |   /* ...same as above... */
 521 | 
 522 |   static restoreClass(obj: any): Catter {
 523 |     return new Catter(obj.s1, obj.s2);
 524 |   }
 525 | }
 526 | 
 527 | export class Joiner {
 528 |   list: string[];
 529 |   delim: string;
 530 | 
 531 |   constructor(list: string[], delim: string) {
 532 |     this.list = list;
 533 |     this.delim = delim;
 534 |   }
 535 | 
 536 |   // this method will be available after restoration
 537 |   join() {
 538 |     return this.list.join(this.delim);
 539 |   }
 540 | 
 541 |   static restoreClass(obj: any): Joiner {
 542 |     return new Joiner(obj.list, obj.delim);
 543 |   }
 544 | }
 545 | 
 546 | // Use this bound restorer function.
 547 | export const restorer = genericRestorer.bind(null, {
 548 |   Catter,
 549 |   Joiner,
 550 | });
 551 | ```
 552 | 
 553 | You can restore both API arguments and return values. Arguments are restored by the method that exposes the API, and return values are restored by the method that binds the API. To employ a restorer function, just pass the function as the last parameter of the exposing or binding method. For example:
 554 | 
 555 | ```ts
 556 | // main process
 557 | exposeMainApi(new DataApi(dataSource), restorer);
 558 | const statusApi = await bindWindowApi<StatusApi>(window, "StatusApi", restorer);
 559 | 
 560 | // window
 561 | exposeWindowApi(new StatusApi(), restorer);
 562 | const uploadApi = await bindMainApi<UploadApi>("UploadApi", restorer);
 563 | ```
 564 | 
 565 | The restorer function need not be the same for all APIs; each can use its own restorer, or it can opt to use no restorer at all.
 566 | 
 567 | You can also use the restorer function to restore the classes of exceptions that are relayed to the window for rethrowing in the window.
 568 | 
 569 | ### Relaying Exceptions
 570 | 
 571 | Main APIs can cause exceptions to be thrown in the calling window. This is useful for communicating errors for which the window is the cause, such as incorrect login credentials or incorrect file format for a user-selected file.
 572 | 
 573 | The mechanism is simple. From within the main API:
 574 | 
 575 | 1. Create the object that is to be thrown in the window.
 576 | 2. Wrap that object in an instance of `RelayedError`.
 577 | 3. Throw the instance of `RelayedError`.
 578 | 
 579 | If the wrapped object is an instance of a `Error` and you're okay with the window receiving an instance of `Error`, then there is no need to do anything more. However, if you wish to restore the original class, such as for use in `instanceof` checks within a `catch`, you'll need to have a restorer function restore the class. (This is the restorer function passed to `bindMainApi`.)
 580 | 
 581 | Here is an example, showing a main API and a window calling that main API:
 582 | 
 583 | ```ts
 584 | // src/backend/apis/login_api.ts
 585 | 
 586 | import { ElectronMainApi, RelayedError } from "electron-affinity/main";
 587 | 
 588 | export class LoginApi implements ElectronMainApi<LoginApi> {
 589 |   private _site: SiteClient;
 590 | 
 591 |   constructor(site: SiteClient) {
 592 |     this._site = _site;
 593 |   }
 594 | 
 595 |   async loginUser(username: string, password: string) {
 596 |     try {
 597 |       await this._site.login(username, password);
 598 |     } catch (err: any) {
 599 |       if (err.code == "BAD_CREDS") {
 600 |         throw new RelayedError(err);
 601 |       }
 602 |       throw err;
 603 |     }
 604 |   }
 605 | }
 606 | ```
 607 | 
 608 | ```ts
 609 | // src/frontend/login_form.ts
 610 | 
 611 | async function onSubmit() {
 612 |   try {
 613 |     await window.apis.loginApi.loginUser(username, password);
 614 |   } catch (err: any) {
 615 |     if (err.code == 'BAD_CREDS') {
 616 |       showMessage('Incorrect credentials');
 617 |     } else {}
 618 |       showMessage('UNEXPECTED ERROR: ' + err.message);
 619 |     }
 620 |   }
 621 | }
 622 | ```
 623 | 
 624 | Whenever an instance (or subclass) of `Error` is created in the one process and transferred via IPC to another process, by any means, the stack trace and error code (if any) is removed prior to transfer. Electron does this, and the library does not obviate it.
 625 | 
 626 | A main API that throws an error not wrapped in `RelayedError` results in an uncaught exception within the main process. Main APIs can return error objects as return values, but Electron strips them of everything but the message.
 627 | 
 628 | Exceptions thrown within window APIs are never returned to the main process.
 629 | 
 630 | ### Managing Timeout
 631 | 
 632 | The library will time out if it takes too long for the main process to bind to a window API or if it takes too long for a window to bind to a main API. The former can happen if the main process attempts to bind before a window has finished initializing and it takes a long time for the window to initialize. The latter can happen if the main process is too busy to respond or has gone unresponsive. An attempt to bind a main API will also time out if the main process never exposed the API.
 633 | 
 634 | The default timeout is 4 seconds, which should be long enough for either of these bindings; if it takes more than 4 seconds, there's likely another problem requiring correction. Even so, there may be scenarios I haven't anticipated requiring a longer timeout, and possibly scenerios where a shorter timeout is desirable. The main process and each window sets its own timeout via the `setIpcBindingTimeout()` function, as follows:
 635 | 
 636 | ```ts
 637 | // main process
 638 | import { setIpcBindingTimeout } from "electron-affinity/main";
 639 | 
 640 | setIpcBindingTimeout(8000); // 8 seconds
 641 | ```
 642 | 
 643 | ```ts
 644 | // window
 645 | import { setIpcBindingTimeout } from "electron-affinity/window";
 646 | 
 647 | setIpcBindingTimeout(500); // 500 milliseconds
 648 | ```
 649 | 
 650 | The timeout applies to all bindings, including in-progress bindings.
 651 | 
 652 | The library does not provide a timeout for the duration of a main API call, and it appears that Electron provides no timeout on the underlying `ipcRenderer.invoke` either.
 653 | 
 654 | ### Generic Use of APIs
 655 | 
 656 | TypeScript provides only limited support for the type usage on which this library relies. Main API classes are restricted to having all properties not beginning with `_` or `#` be methods returning promises, and window API classes are restricted to having all properties not beginning with `_` or `#` be methods. The identifiers, arguments, and return values of these methods are otherwise unrestricted, whereas TypeScript normally expects a type to specify these features too.
 657 | 
 658 | We are able to enforce API types in the API class definition (with an `implements` clause), and we are able to enforce them when the APIs or their classes are arguments to generic functions, but we cannot enforce them in variable assignments. For example, the following does not work because type `any` does not provide the class members that need to be type-checked:
 659 | 
 660 | ```ts
 661 | let someApi: ElectronMainApi<any> = new DataApi(); // DOES NOT WORK
 662 | ```
 663 | 
 664 | To deal with this, Electron Affinity provides the following utility functions:
 665 | 
 666 | ```ts
 667 | checkMainApiClass(classObject)
 668 | checkWindowApiClass(classObject)
 669 | checkMainApi(instanceObject)
 670 | checkWindowApi(instanceObject)
 671 | ```
 672 | 
 673 | The first two&mdash;the class checkers&mdash;take the API class as an argument and return no value. The last two&mdash;the instance checkers&mdash;take an instance of the API class as an argument and return that instance.
 674 | 
 675 | Consider the `installMainApis()` function previously defined in [Organizing Main APIs](#organizing-main-apis). Because it pulls each API into a variable called `api`, no type-checking occurs when this variable is passed to `exposeMainApi()`. The function relies on each API class having properly implemented an API type. If you didn't want to trust the API classes to have done this, you could type-check the APIs using `checkMainApi()` as follows:
 676 | 
 677 | ```ts
 678 | // src/backend/apis/main_apis.ts
 679 | 
 680 | import { exposeMainApi, checkMainApi } from "electron-affinity/main";
 681 | import { DataApi } from "path/to/status_api";
 682 | import { UploadApi } from "path/to/message_api";
 683 | 
 684 | export type MainApis = ReturnType<typeof installMainApis>;
 685 | 
 686 | export function installMainApis() {
 687 |   const apis = {
 688 |     dataApi: checkMainApi(new DataApi()),
 689 |     uploadApi: checkMainApi(new UploadApi()),
 690 |     /* ... */
 691 |   };
 692 |   for (const api of Object.values(apis)) {
 693 |     exposeMainApi(api as any);
 694 |   }
 695 |   global.mainApis = apis as any;
 696 | }
 697 | ```
 698 | 
 699 | ### Example Repo
 700 | 
 701 | The library was developed for the [ut-entomology/spectool](https://github.com/ut-entomology/spectool) repo, where you'll find plenty of code exmplifying how to use it. See the following files and directories:
 702 | 
 703 | - [Installing main APIs and binding window APIs to the main window](https://github.com/ut-entomology/spectool/blob/main/src/app_main.ts)
 704 | - [Main process global.d.ts providing the main process with access to main APIs](https://github.com/ut-entomology/spectool/blob/main/src/global.d.ts)
 705 | - [Backend main API classes](https://github.com/ut-entomology/spectool/tree/main/src/backend/api)
 706 | - [Main window binding to main APIs](https://github.com/ut-entomology/spectool/blob/main/src/frontend/lib/main_client.ts)
 707 | - [Attaching main APIs to the main window and exposing a window API](https://github.com/ut-entomology/spectool/blob/main/src/frontend/App.svelte)
 708 | - [Frontend global.d.ts providing windows with access to main APIs](https://github.com/ut-entomology/spectool/blob/main/src/frontend/global.d.ts)
 709 | - [Window API class](https://github.com/ut-entomology/spectool/blob/main/src/frontend/api/app_event_api.svelte)
 710 | - [Calls from the main window to main APIs](https://github.com/ut-entomology/spectool/search?q=window.apis)
 711 | - [Calls from the main process to the main window APIs](https://github.com/ut-entomology/spectool/blob/main/src/backend/app/app_menu.ts)
 712 | 
 713 | ## Miscellaneous Notes and Caveats
 714 | 
 715 | - In order to keep the library simple, I require that all main API methods be asynchronous. A drawback of doing this is that, if you need to wait on the return value, the API can only be called from within an asynchronous method.
 716 | - Being asynchronous, API methods are also prone to the mistake where they are called without using `await`. Unfortunately, that's one problem I couldn't help alleviate.
 717 | - Another drawback of this approach is that APIs are only available after waiting for the binding promise to complete. Fortunately, prior to binding, API methods are undefined, so at least you'll get an error message that makes the issue clear.
 718 | - It may seem excessive to place main APIs on `window.apis` instead of directly on `window`, but the former is more helpful for code completion. If you put each API on `window` directly, not only do you increase the risk of name conflicts, but on VS Code, after typing `window.` you'll be staring at a long list of window properties, not just the APIs. On the other hand, typing `window.apis.` on VS Code will show you all the available APIs, providing a handy reference.
 719 | - The library installs its own internal APIs on `window._affinity_ipc`, and it sends and receives IPCs over channels `_affinity_api_request` and `_affinity_api_response`.
 720 | 
 721 | ## Reference
 722 | 
 723 | ### import from 'electron-affinity/main'
 724 | 
 725 | See also [the library common to '/main' and '/window'](#import-from-electron-affinitymain-or-electron-affinitywindow).
 726 | 
 727 | #### type ElectronMainApi<T>
 728 | 
 729 | ```ts
 730 | /**
 731 |  * Type to which a main API class must conform. It requires each API method
 732 |  * to return a promise. All public properties of the method not beginning with
 733 |  * `_`or `#` will be exposed as API methods, allowing the API class to have
 734 |  * private properties on which the API methods rely. This type will not expose
 735 |  * properties declared `protected` or `private`, but `bindMainApi()` will still
 736 |  * generate bindings for those whose names don't begin with `_` or `#`. Have
 737 |  * your main APIs `implement` this type to get type-checking in the APIs
 738 |  * themselves, passing in the API class itself for T. Use `checkMainApi` or
 739 |  * `checkMainApiClass` to type-check variables containing main APIs.
 740 |  *
 741 |  * @param <T> The type of the API class itself, typically inferred from a
 742 |  *    function that accepts an argument of type `ElectronMainApi`.
 743 |  * @see checkMainApi
 744 |  * @see checkMainApiClass
 745 |  */
 746 | type ElectronMainApi<T> = {
 747 |   [K in PublicProperty<keyof T>]: (...args: any[]) => Promise<any>;
 748 | }
 749 | ```
 750 | 
 751 | #### type WindowApiBinding<T>
 752 | 
 753 | ```ts
 754 | /**
 755 |  * Type to which a bound window API conforms within the main process, as
 756 |  * determined from the provided window API class. This type only exposes the
 757 |  * API methods of the class. Regardless of what the implementation of any
 758 |  * given method returns, the API method returns no value (void).
 759 |  *
 760 |  * @param <T> Type of the window API class
 761 |  */
 762 | type WindowApiBinding<T> = {
 763 |   [K in PublicProperty<keyof T>]: T[K] extends (...args: infer A) => any
 764 |     ? (...args: A) => void
 765 |     : never;
 766 | }
 767 | ```
 768 | 
 769 | #### function bindWindowApi()
 770 | 
 771 | ```ts
 772 | /**
 773 |  * Returns a main-side binding for a window API of a given class, restricting
 774 |  * the binding to the given window. Failure of the window to expose the API
 775 |  * before timeout results in an exception. There is a default timeout, but
 776 |  * you can override it with `setIpcBindingTimeout()`. (The function does not
 777 |  * take a restorer parameter because window APIs do not return values.)
 778 |  *
 779 |  * @param <T> Type of the window API class to bind
 780 |  * @param window Window to which to bind the window API
 781 |  * @param apiClassName Name of the class being bound. Must be identical to
 782 |  *    the name of class T. Provides runtime information that <T> does not.
 783 |  * @returns An API of type T that can be called as if T were local to the
 784 |  *    main process.
 785 |  * @see setIpcBindingTimeout
 786 |  */
 787 | function bindWindowApi<T extends ElectronWindowApi<T>>(
 788 |   window: BrowserWindow,
 789 |   apiClassName: string
 790 | ): Promise<WindowApiBinding<T>>
 791 | ```
 792 | 
 793 | #### function checkMainApi()
 794 | 
 795 | ```ts
 796 | /**
 797 |  * Type checks the argument to ensure it conforms to the expectations of an
 798 |  * instance of a main API class. Returns the argument to allow type-checking
 799 |  * of APIs in their places of use.
 800 |  *
 801 |  * @param <T> (inferred type, not specified in call)
 802 |  * @param api Instance of the main API class to type check
 803 |  * @return The provided main API instance
 804 |  * @see checkMainApiClass
 805 |  */
 806 | function checkMainApi<T extends ElectronMainApi<T>>(api: T): T
 807 | ```
 808 | 
 809 | #### function checkMainApiClass()
 810 | 
 811 | ```ts
 812 | /**
 813 |  * Type checks the argument to ensure it conforms to the expectations of a
 814 |  * main API class. Returns the argument to allow type-checking of APIs in
 815 |  * their places of use.
 816 |  *
 817 |  * @param <T> (inferred type, not specified in call)
 818 |  * @param _class The main API class to type check
 819 |  * @return The provided main API class
 820 |  * @see checkMainApi
 821 |  */
 822 | function checkMainApiClass<T extends ElectronMainApi<T>>(_class: {
 823 |   new (...args: any[]): T;
 824 | }): {
 825 |   new (...args: any[]): T;
 826 | }
 827 | ```
 828 | 
 829 | #### function exposeMainApi()
 830 | 
 831 | ```ts
 832 | /**
 833 |  * Exposes a main API to all windows for possible binding.
 834 |  *
 835 |  * @param <T> (inferred type, not specified in call)
 836 |  * @param mainApi The API to expose to all windows, which must be an
 837 |  *    instance of a class conforming to type `ElectronMainApi`. Only
 838 |  *    one instance of any given class can ever be exposed.
 839 |  * @param restorer Optional function for restoring the classes of
 840 |  *    arguments passed to APIs from the window. Arguments not
 841 |  *    restored to original classes arrive as untyped objects.
 842 |  */
 843 | function exposeMainApi<T extends ElectronMainApi<T>>(
 844 |   mainApi: T,
 845 |   restorer?: RestorerFunction
 846 | ): void
 847 | ```
 848 | 
 849 | #### class RelayedError
 850 | 
 851 | ```ts
 852 | /**
 853 |  * Class that wraps exceptions occurring in a main API that are to be
 854 |  * relayed as errors back to the calling window. A main API wishing to
 855 |  * have an exception thrown in the calling window wraps the error object
 856 |  * in an instance of this class and throws the instance. The main process
 857 |  * will ignore the throw except for transferring it to the calling window.
 858 |  * Exceptions thrown within a main API not wrapped in `RelayedError` are
 859 |  * thrown within the main process as "uncaught" exceptions.
 860 |  */
 861 | class RelayedError {
 862 |   /**
 863 |    * @param errorToRelay The error to throw within the calling window,
 864 |    *    occurring within the window's call to the main API
 865 |    */
 866 |   constructor(errorToRelay: any);
 867 | }
 868 | ```
 869 | 
 870 | ### import from 'electron-affinity/window'
 871 | 
 872 | See also [the library common to '/main' and '/window'](#import-from-electron-affinitymain-or-electron-affinitywindow).
 873 | 
 874 | #### type ElectronWindowApi<T>
 875 | 
 876 | ```ts
 877 | /**
 878 |  * Type to which a window API class must conform. All public properties of the
 879 |  * method and all properties not beginning with `_` or `#` will be exposed as
 880 |  * API methods, allowing the API class to have private properties on which the
 881 |  * API methods rely. This type will not expose properties declared `protected`
 882 |  * or `private`, but `bindWindowApi()` will still generate bindings for those
 883 |  * whose names don't begin with `_` or `#`. Have your window APIs `implement`
 884 |  * this type to get type-checking in the APIs themselves, passing in the API
 885 |  * class itself for T. Use `checkWindowApi` or  `checkWindowApiClass` to
 886 |  * type-check variables containing window APIs.
 887 |  *
 888 |  * @param <T> The type of the API class itself, typically inferred from a
 889 |  *    function that accepts an argument of type `ElectronWindowApi`.
 890 |  * @see checkWindowApi
 891 |  * @see checkWindowApiClass
 892 |  */
 893 | type ElectronWindowApi<T> = {
 894 |   [K in PublicProperty<keyof T>]: (...args: any[]) => void;
 895 | }
 896 | ```
 897 | 
 898 | #### type MainApiBinding
 899 | 
 900 | ```ts
 901 | /**
 902 |  * Type to which a bound main API conforms within a window, as determined by
 903 |  * the provided main API class. The type only exposes the API methods of the
 904 |  * class, exposing the methods with the exact return types given by their
 905 |  * implementations, which are necessarily promises.
 906 |  *
 907 |  * @param <T> Type of the main API class
 908 |  */
 909 | type MainApiBinding<T> = { [K in PublicProperty<keyof T>]: T[K] }
 910 | ```
 911 | 
 912 | #### function bindMainApi()
 913 | 
 914 | ```ts
 915 | /**
 916 |  * Returns a window-side binding for a main API of a given class. Main must
 917 |  * have previously exposed the API. Failure of the main process to expose the
 918 |  * API before timeout results in an exception. There is a default timeout, but
 919 |  * you can override it with `setIpcBindingTimeout()`.
 920 |  *
 921 |  * @param <T> Type of the main API class to bind
 922 |  * @param apiClassName Name of the class being bound. Must be identical to
 923 |  *    the name of class T. Provides runtime information that <T> does not.
 924 |  * @param restorer Optional function for restoring the classes of API return
 925 |  *    values. Return values not restored arrive as untyped objects.
 926 |  * @returns An API of type T that can be called as if T were local to
 927 |  *    the window.
 928 |  * @see setIpcBindingTimeout
 929 |  */
 930 | function bindMainApi<T extends ElectronMainApi<T>>(
 931 |   apiClassName: string,
 932 |   restorer?: RestorerFunction
 933 | ): Promise<MainApiBinding<T>>
 934 | ```
 935 | 
 936 | #### function checkWindowApi()
 937 | 
 938 | ```ts
 939 | /**
 940 |  * Type checks the argument to ensure it conforms to the expectations of an
 941 |  * instance of a window API class. Returns the argument to allow type-checking
 942 |  * of APIs in their places of use.
 943 |  *
 944 |  * @param <T> (inferred type, not specified in call)
 945 |  * @param api Instance of the window API class to type check
 946 |  * @return The provided window API instance
 947 |  * @see checkWindowApiClass
 948 |  */
 949 | function checkWindowApi<T extends ElectronWindowApi<T>>(api: T): T
 950 | ```
 951 | 
 952 | #### function checkWindowApiClass()
 953 | 
 954 | ```ts
 955 | /**
 956 |  * Type checks the argument to ensure it conforms to the expectations of a
 957 |  * window API class. Returns the argument to allow type-checking of APIs in
 958 |  * their places of use.
 959 |  *
 960 |  * @param <T> (inferred type, not specified in call)
 961 |  * @param _class The window API class to type check
 962 |  * @return The provided window API class
 963 |  * @see checkWindowApi
 964 |  */
 965 | function checkWindowApiClass<T extends ElectronWindowApi<T>>(_class: {
 966 |   new (...args: any[]): T;
 967 | }): {
 968 |   new (...args: any[]): T;
 969 | }
 970 | ```
 971 | 
 972 | #### function exposeWindowApi()
 973 | 
 974 | ```ts
 975 | /**
 976 |  * Exposes a window API to the main process for possible binding.
 977 |  *
 978 |  * @param <T> (inferred type, not specified in call)
 979 |  * @param windowApi The API to expose to the main process, which must be
 980 |  *    an instance of a class conforming to type `ElectronWindowApi`. Only
 981 |  *    one instance of any given class can ever be exposed.
 982 |  * @param restorer Optional function for restoring the classes of
 983 |  *    arguments passed to APIs from the main process. Arguments not
 984 |  *    restored to original classes arrive as untyped objects.
 985 |  */
 986 | function exposeWindowApi<T extends ElectronWindowApi<T>>(
 987 |   windowApi: T,
 988 |   restorer?: RestorerFunction
 989 | ): void
 990 | ```
 991 | 
 992 | ### import from 'electron-affinity/main' or 'electron-affinity/window'
 993 | 
 994 | #### type AwaitedType<F>
 995 | 
 996 | ```ts
 997 | /**
 998 |  * Utility type for providing the value to which an asynchronous function
 999 |  * resolves. That is, if a function F returns Promise<R>, then AwaitedType<T>
1000 |  * evaluates to type R. Use for extracting the types of bound APIs.
1001 |  *
1002 |  * @param <F> Function for which to determine the resolving type.
1003 |  */
1004 | type AwaitedType<F> = F extends (...args: any[]) => Promise<infer R>
1005 |   ? R
1006 |   : never
1007 | ```
1008 | 
1009 | #### type RestorableClass<C>
1010 | 
1011 | ```ts
1012 | /**
1013 |  * Type of a class that can be called to restore class values. It defines
1014 |  * the static class method `restoreClass`, which takes the unstructured
1015 |  * object received via IPC and returns an instance of class C. Use for
1016 |  * creating generic restorer functions, as explained in the documentation.
1017 |  *
1018 |  * @param <C> The class that conforms to this type.
1019 |  */
1020 | type RestorableClass<C> = {
1021 |   // static method of the class returning an instance of the class
1022 |   restoreClass(obj: Record<string, any>): C;
1023 | }
1024 | ```
1025 | 
1026 | #### type RestorerFunction
1027 | 
1028 | ```ts
1029 | /**
1030 |  * Type for a function that restores the classes of arguments and return
1031 |  * values. This function is optionally the last parameter passed when
1032 |  * exposing a main API, binding to a main API, or exposing a window API.
1033 |  * The function need not restore the class of a provided object, in which
1034 |  * case it returns the provided object.
1035 |  *
1036 |  * @param className The name of the class at the time its instance was
1037 |  *    transferred via IPC
1038 |  * @param obj The unstructured object to which the class instance was
1039 |  *    converted for transmission via IPC
1040 |  * @return Either the provided object `obj` if it was not converted into
1041 |  *    a class instance, or an instance of class `className` sourced from
1042 |  *    the data in `obj`
1043 |  */
1044 | type RestorerFunction = (className: string, obj: Record<string, any>) => any
1045 | ```
1046 | 
1047 | #### function genericRestorer()
1048 | 
1049 | ```ts
1050 | /**
1051 |  * A generic implementation of a restorer function, which becomes an instance
1052 |  * of `RestorerFunction` when bound to a map of restorable classes (each
1053 |  * conforming to type `RestorableClass`). See the example in the docs.
1054 |  *
1055 |  * @param restorableClassMap An object whose properties map the names of
1056 |  *    restorable classes to the restorable classes themselves
1057 |  * @param className The name of the class at the time its instance was
1058 |  *    transferred via IPC
1059 |  * @param obj The unstructured object to which the class instance was
1060 |  *    converted for transmission via IPC
1061 |  * @return An instance of a class in `restorableClassMap` if `className` is in
1062 |  *    this map, sourced from the provided `obj`, or the provided `obj` itself
1063 |  *    if `className` is not in `restorableClassMap`
1064 |  */
1065 | function genericRestorer(
1066 |   restorableClassMap: Record<string, RestorableClass<any>>,
1067 |   className: string,
1068 |   obj: Record<string, any>
1069 | ): any
1070 | ```
1071 | 
1072 | #### function setIpcBindingTimeout()
1073 | 
1074 | ```ts
1075 | /**
1076 |  * Sets the binding timeout. This is the maximum time allowed for the main
1077 |  * process to bind to any window API and the maximum time allowed for a
1078 |  * window to bind to a main API. Also applies to any bindings in progress.
1079 |  *
1080 |  * @param millis Duration of timeout in milliseconds
1081 |  */
1082 | function setIpcBindingTimeout(millis: number): void
1083 | ```
1084 | 
1085 | ### import 'electron-affinity/preload'
1086 | 
1087 | This is the JavaScript to preload into each window in order to enable the window to support IPC. Either include the following line in your `preload.js`:
1088 | 
1089 | ```ts
1090 | import "electron-affinity/preload";
1091 | ```
1092 | 
1093 | ... or preload directly from `node_modules` using the appropriate path:
1094 | 
1095 | ```ts
1096 | const window = new BrowserWindow({
1097 |   webPreferences: {
1098 |     preload: path.join(
1099 |       __dirname,
1100 |       "../node_modules/electron-affinity/preload.js"
1101 |     ),
1102 |     nodeIntegration: false,
1103 |     contextIsolation: true,
1104 |   },
1105 | });
1106 | ```
1107 | 


--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "name": "electron-affinity",
 3 |   "version": "1.2.4",
 4 |   "description": "Electron IPC via simple method calls",
 5 |   "license": "MIT",
 6 |   "author": "Joseph T. Lapp <arachnojoe@gmail.com>",
 7 |   "private": false,
 8 |   "homepage": "https://github.com/jtlapp/electron-affinity",
 9 |   "repository": {
10 |     "type": "git",
11 |     "url": "https://github.com/jtlapp/electron-affinity.git"
12 |   },
13 |   "scripts": {
14 |     "test": "tsc && shx mkdir -p build/test/window-scripts && shx cp test/window-scripts/dummy.html build/test/window-scripts/dummy.html && node_modules/.bin/rollup -c && ./test/run-tests",
15 |     "pub": "tsc && shx cp package.json build/src && shx cp README.md build/src && shx cp LICENSE build/src && shx rm build/src/*.map && shx rm build/src/lib/*.map && yarn publish build/src && rm build/src/package.json build/src/README.md build/src/LICENSE"
16 |   },
17 |   "dependencies": {},
18 |   "devDependencies": {
19 |     "@rollup/plugin-commonjs": "^21.0.1",
20 |     "@rollup/plugin-typescript": "^8.3.0",
21 |     "@types/mocha": "^9.1.0",
22 |     "@types/node": "^17.0.10",
23 |     "electron": "^16.0.2",
24 |     "electron-mocha": "^11.0.0",
25 |     "mocha": "9.2.0",
26 |     "rollup": "^2.66.0",
27 |     "shx": "^0.3.3",
28 |     "source-map-support": "^0.5.21",
29 |     "tslib": "^2.3.1",
30 |     "typescript": "^4.5.5"
31 |   },
32 |   "keywords": [
33 |     "electron",
34 |     "ipc",
35 |     "rpc",
36 |     "typescript",
37 |     "typed"
38 |   ]
39 | }
40 | 


--------------------------------------------------------------------------------
/rollup.config.js:
--------------------------------------------------------------------------------
 1 | import commonjs from '@rollup/plugin-commonjs'
 2 | import typescript from '@rollup/plugin-typescript'
 3 | import * as fs from 'fs';
 4 | import * as path from 'path';
 5 | 
 6 | const config = [];
 7 | const scriptDir = path.join(__dirname, "test/window-scripts");
 8 | 
 9 | fs.readdirSync(scriptDir).forEach(fileName => {
10 | 	if (fileName.endsWith(".ts")) {
11 | 		const scriptName = fileName.substring(0, fileName.length - 3);
12 | 		config.push({
13 | 			input: `test/window-scripts/${scriptName}.ts`,
14 | 			output: {
15 | 				sourcemap: true,
16 | 				format: 'cjs',
17 | 				file: `build/test/bundle/${scriptName}.js`
18 | 			},
19 | 			plugins: [
20 | 				commonjs(),
21 | 				typescript({
22 | 					sourceMap: true,
23 | 					inlineSources: true,
24 | 					tsconfig: "test/window-scripts/tsconfig.json"
25 | 				}),
26 | 			]
27 | 		});
28 | 	}
29 | });
30 | 
31 | export default config;


--------------------------------------------------------------------------------
/src/lib/main_lib.ts:
--------------------------------------------------------------------------------
  1 | /**
  2 |  * Code specific to handling IPC in the main process.
  3 |  */
  4 | 
  5 | import { ipcMain, BrowserWindow } from "electron";
  6 | 
  7 | import type { ElectronWindowApi } from "./window_lib";
  8 | import {
  9 |   API_REQUEST_IPC,
 10 |   API_RESPONSE_IPC,
 11 |   ApiRegistration,
 12 |   ApiRegistrationMap,
 13 |   PublicProperty,
 14 |   toIpcName,
 15 |   retryUntilTimeout,
 16 |   exposeApi,
 17 | } from "./shared_lib";
 18 | import { Restorer, RestorerFunction } from "./restorer_lib";
 19 | 
 20 | //// MAIN API SUPPORT ////////////////////////////////////////////////////////
 21 | 
 22 | // Structure mapping API names to the methods each contains.
 23 | let _mainApiMap: ApiRegistrationMap = {};
 24 | 
 25 | // Error logger mainly of value for debugging the test suite.
 26 | let _errorLoggerFunc: (err: Error) => void;
 27 | 
 28 | /**
 29 |  * Type to which a main API class must conform. It requires each API method
 30 |  * to return a promise. All public properties of the method not beginning with
 31 |  * `_`or `#` will be exposed as API methods, allowing the API class to have
 32 |  * private properties on which the API methods rely. This type will not expose
 33 |  * properties declared `protected` or `private`, but `bindMainApi()` will still
 34 |  * generate bindings for those whose names don't begin with `_` or `#`. Have
 35 |  * your main APIs `implement` this type to get type-checking in the APIs
 36 |  * themselves, passing in the API class itself for T. Use `checkMainApi` or
 37 |  * `checkMainApiClass` to type-check variables containing main APIs.
 38 |  *
 39 |  * @param <T> The type of the API class itself, typically inferred from a
 40 |  *    function that accepts an argument of type `ElectronMainApi`.
 41 |  * @see checkMainApi
 42 |  * @see checkMainApiClass
 43 |  */
 44 | export type ElectronMainApi<T> = {
 45 |   [K in PublicProperty<keyof T>]: (...args: any[]) => Promise<any>;
 46 | };
 47 | 
 48 | /**
 49 |  * Type checks the argument to ensure it conforms to the expectations of an
 50 |  * instance of a main API class. Returns the argument to allow type-checking
 51 |  * of APIs in their places of use.
 52 |  *
 53 |  * @param <T> (inferred type, not specified in call)
 54 |  * @param api Instance of the main API class to type check
 55 |  * @return The provided main API instance
 56 |  * @see checkMainApiClass
 57 |  */
 58 | export function checkMainApi<T extends ElectronMainApi<T>>(api: T): T {
 59 |   return api;
 60 | }
 61 | 
 62 | /**
 63 |  * Type checks the argument to ensure it conforms to the expectations of a
 64 |  * main API class. Returns the argument to allow type-checking of APIs in
 65 |  * their places of use.
 66 |  *
 67 |  * @param <T> (inferred type, not specified in call)
 68 |  * @param _class The main API class to type check
 69 |  * @return The provided main API class
 70 |  * @see checkMainApi
 71 |  */
 72 | export function checkMainApiClass<T extends ElectronMainApi<T>>(_class: {
 73 |   new (...args: any[]): T;
 74 | }): {
 75 |   new (...args: any[]): T;
 76 | } {
 77 |   return _class;
 78 | }
 79 | 
 80 | /**
 81 |  * Class that wraps exceptions occurring in a main API that are to be
 82 |  * relayed as errors back to the calling window. A main API wishing to
 83 |  * have an exception thrown in the calling window wraps the error object
 84 |  * in an instance of this class and throws the instance. The main process
 85 |  * will ignore the throw except for transferring it to the calling window.
 86 |  * Exceptions thrown within a main API not wrapped in `RelayedError` are
 87 |  * thrown within the main process as "uncaught" exceptions.
 88 |  */
 89 | export class RelayedError {
 90 |   errorToRelay: any;
 91 | 
 92 |   /**
 93 |    * @param errorToRelay The error to throw within the calling window,
 94 |    *    occurring within the window's call to the main API
 95 |    */
 96 |   constructor(errorToRelay: any) {
 97 |     this.errorToRelay = errorToRelay;
 98 |   }
 99 | }
100 | 
101 | /**
102 |  * Exposes a main API to all windows for possible binding.
103 |  *
104 |  * @param <T> (inferred type, not specified in call)
105 |  * @param mainApi The API to expose to all windows, which must be an
106 |  *    instance of a class conforming to type `ElectronMainApi`. Only
107 |  *    one instance of any given class can ever be exposed.
108 |  * @param restorer Optional function for restoring the classes of
109 |  *    arguments passed to APIs from the window. Arguments not
110 |  *    restored to original classes arrive as untyped objects.
111 |  */
112 | export function exposeMainApi<T extends ElectronMainApi<T>>(
113 |   mainApi: T,
114 |   restorer?: RestorerFunction
115 | ): void {
116 |   _installIpcListeners();
117 |   exposeApi(_mainApiMap, mainApi, (ipcName, method) => {
118 |     ipcMain.handle(ipcName, async (_event, args: any[]) => {
119 |       try {
120 |         Restorer.restoreArgs(args, restorer);
121 |         //await before returning to keep Electron from writing errors
122 |         const returnValue = await method.bind(mainApi)(...args);
123 |         if (returnValue instanceof RelayedError) {
124 |           throw new Error("RelayedError must be thrown, not returned");
125 |         }
126 |         return [returnValue, Restorer.makeRestorationInfo(returnValue)];
127 |       } catch (err: any) {
128 |         if (err instanceof RelayedError) {
129 |           return Restorer.makeRethrownReturnValue(err.errorToRelay);
130 |         }
131 |         if (_errorLoggerFunc !== undefined) {
132 |           _errorLoggerFunc(err);
133 |         }
134 |         throw err;
135 |       }
136 |     });
137 |   });
138 | }
139 | 
140 | // Receives exceptions thrown in main APIs that were not wrapped in RelayedError.
141 | export function setIpcErrorLogger(loggerFunc: (err: any) => void): void {
142 |   _errorLoggerFunc = loggerFunc;
143 | }
144 | 
145 | //// WINDOW API SUPPORT //////////////////////////////////////////////////////
146 | 
147 | /**
148 |  * Type to which a bound window API conforms within the main process, as
149 |  * determined from the provided window API class. This type only exposes the
150 |  * API methods of the class. Regardless of what the implementation of any
151 |  * given method returns, the API method returns no value (void).
152 |  *
153 |  * @param <T> Type of the window API class
154 |  */
155 | export type WindowApiBinding<T> = {
156 |   [K in PublicProperty<keyof T>]: T[K] extends (...args: infer A) => any
157 |     ? (...args: A) => void
158 |     : never;
159 | };
160 | 
161 | // Structure mapping window API names to the methods they contain, indexed by
162 | // web contents ID.
163 | const _windowApiMapByWebContentsID: Record<number, ApiRegistrationMap> = {};
164 | 
165 | // Structure tracking bound window APIs, indexed by window ID.
166 | const _boundWindowApisByWindowID: Record<
167 |   number,
168 |   Record<string, WindowApiBinding<any>>
169 | > = {};
170 | 
171 | /**
172 |  * Returns a main-side binding for a window API of a given class, restricting
173 |  * the binding to the given window. Failure of the window to expose the API
174 |  * before timeout results in an exception. There is a default timeout, but
175 |  * you can override it with `setIpcBindingTimeout()`. (The function does not
176 |  * take a restorer parameter because window APIs do not return values.)
177 |  *
178 |  * @param <T> Type of the window API class to bind
179 |  * @param window Window to which to bind the window API
180 |  * @param apiClassName Name of the class being bound. Must be identical to
181 |  *    the name of class T. Provides runtime information that <T> does not.
182 |  * @returns An API of type T that can be called as if T were local to the
183 |  *    main process.
184 |  * @see setIpcBindingTimeout
185 |  */
186 | export function bindWindowApi<T extends ElectronWindowApi<T>>(
187 |   window: BrowserWindow,
188 |   apiClassName: string
189 | ): Promise<WindowApiBinding<T>> {
190 |   _installIpcListeners();
191 | 
192 |   return new Promise((resolve) => {
193 |     const windowApis = _boundWindowApisByWindowID[window.webContents.id];
194 |     if (windowApis && windowApis[apiClassName]) {
195 |       resolve(windowApis[apiClassName]);
196 |     } else {
197 |       retryUntilTimeout(
198 |         0,
199 |         () => {
200 |           return _attemptBindWindowApi(window, apiClassName, resolve);
201 |         },
202 |         `Main timed out waiting to bind to window API '${apiClassName}'` +
203 |           ` (window ID ${window.id})`
204 |       );
205 |     }
206 |   });
207 | }
208 | 
209 | // Implements a single attempt to bind to a window API.
210 | function _attemptBindWindowApi<T>(
211 |   window: BrowserWindow,
212 |   apiClassName: string,
213 |   resolve: (boundApi: WindowApiBinding<T>) => void
214 | ): boolean {
215 |   // Wait for the window API binding to arrive.
216 | 
217 |   const windowID = window.webContents.id; // save in case window is destroyed
218 |   let windowApiMap = _windowApiMapByWebContentsID[windowID];
219 |   if (!windowApiMap || !windowApiMap[apiClassName]) {
220 |     // Keep trying until window loads and initializes enough to receive request.
221 |     window.webContents.send(API_REQUEST_IPC, apiClassName);
222 |     return false;
223 |   }
224 | 
225 |   // Construct the window API binding.
226 | 
227 |   const methodNames = windowApiMap[apiClassName] as [keyof WindowApiBinding<T>];
228 |   const boundApi = {} as WindowApiBinding<T>;
229 |   for (const methodName of methodNames) {
230 |     const typedMethodName: keyof WindowApiBinding<T> = methodName;
231 |     boundApi[typedMethodName] = ((...args: any[]) => {
232 |       Restorer.makeArgsRestorable(args);
233 |       window.webContents.send(
234 |         toIpcName(apiClassName, methodName as string),
235 |         args
236 |       );
237 |     }) as any; // typescript can't confirm the method signature
238 |   }
239 | 
240 |   // Save the binding to return on duplicate binding requests.
241 | 
242 |   let windowApis = _boundWindowApisByWindowID[windowID];
243 |   if (!windowApis) {
244 |     windowApis = {};
245 |     _boundWindowApisByWindowID[windowID] = windowApis;
246 |   }
247 |   windowApis[apiClassName] = boundApi;
248 | 
249 |   // Uninstall the binding when the window closes.
250 | 
251 |   window.on("closed", (_event: any) => {
252 |     for (const methodName of methodNames) {
253 |       const typedMethodName: keyof WindowApiBinding<T> = methodName;
254 |       boundApi[typedMethodName] = ((..._args: any[]) => {
255 |         throw Error("Window has closed; API unavailable");
256 |       }) as any; // typescript can't confirm the method signature
257 |     }
258 |     // Deleting more than once doesn't cause an error.
259 |     delete _boundWindowApisByWindowID[windowID];
260 |   });
261 | 
262 |   // Return the binding to main.
263 | 
264 |   resolve(boundApi);
265 |   return true;
266 | }
267 | 
268 | //// COMMON MAIN & WINDOW SUPPORT API ////////////////////////////////////////
269 | 
270 | let _listeningForIPC = false;
271 | 
272 | function _installIpcListeners() {
273 |   if (!_listeningForIPC) {
274 |     ipcMain.on(API_REQUEST_IPC, (event, apiClassName: string) => {
275 |       const registration: ApiRegistration = {
276 |         className: apiClassName,
277 |         methodNames: _mainApiMap[apiClassName],
278 |       };
279 |       event.sender.send(API_RESPONSE_IPC, registration);
280 |     });
281 |     ipcMain.on(API_RESPONSE_IPC, (event, api: ApiRegistration) => {
282 |       let windowApiMap = _windowApiMapByWebContentsID[event.sender.id];
283 |       if (!windowApiMap) {
284 |         windowApiMap = {};
285 |         _windowApiMapByWebContentsID[event.sender.id] = windowApiMap;
286 |       }
287 |       windowApiMap[api.className] = api.methodNames;
288 |     });
289 |     _listeningForIPC = true;
290 |   }
291 | }
292 | 


--------------------------------------------------------------------------------
/src/lib/restorer_lib.ts:
--------------------------------------------------------------------------------
  1 | /**
  2 |  * Support for restoring the classes of arguments and return values.
  3 |  */
  4 | 
  5 | /**
  6 |  * Type of a class that can be called to restore class values. It defines
  7 |  * the static class method `restoreClass`, which takes the unstructured
  8 |  * object received via IPC and returns an instance of class C. Use for
  9 |  * creating generic restorer functions, as explained in the documentation.
 10 |  *
 11 |  * @param <C> The class that conforms to this type.
 12 |  */
 13 | export type RestorableClass<C> = {
 14 |   // static method of the class returning an instance of the class
 15 |   restoreClass(obj: Record<string, any>): C;
 16 | };
 17 | 
 18 | /**
 19 |  * Type for a function that restores the classes of arguments and return
 20 |  * values. This function is optionally the last parameter passed when
 21 |  * exposing a main API, binding to a main API, or exposing a window API.
 22 |  * The function need not restore the class of a provided object, in which
 23 |  * case it returns the provided object.
 24 |  *
 25 |  * @param className The name of the class at the time its instance was
 26 |  *    transferred via IPC
 27 |  * @param obj The unstructured object to which the class instance was
 28 |  *    converted for transmission via IPC
 29 |  * @return Either the provided object `obj` if it was not converted into
 30 |  *    a class instance, or an instance of class `className` sourced from
 31 |  *    the data in `obj`
 32 |  */
 33 | export type RestorerFunction = (
 34 |   className: string,
 35 |   obj: Record<string, any>
 36 | ) => any;
 37 | 
 38 | // Structure describing how to restore an object IPC argument or return value.
 39 | interface RestorationInfo {
 40 |   argIndex?: number; // if not return value, index of argument in args list
 41 |   className: string; // name of the object's class
 42 |   isError: boolean; // whether the object subclasses Error
 43 | }
 44 | 
 45 | /**
 46 |  * A generic implementation of a restorer function, which becomes an instance
 47 |  * of `RestorerFunction` when bound to a map of restorable classes (each
 48 |  * conforming to type `RestorableClass`). See the example in the docs.
 49 |  *
 50 |  * @param restorableClassMap An object whose properties map the names of
 51 |  *    restorable classes to the restorable classes themselves
 52 |  * @param className The name of the class at the time its instance was
 53 |  *    transferred via IPC
 54 |  * @param obj The unstructured object to which the class instance was
 55 |  *    converted for transmission via IPC
 56 |  * @return An instance of a class in `restorableClassMap` if `className` is in
 57 |  *    this map, sourced from the provided `obj`, or the provided `obj` itself
 58 |  *    if `className` is not in `restorableClassMap`
 59 |  */
 60 | export function genericRestorer(
 61 |   restorableClassMap: Record<string, RestorableClass<any>>,
 62 |   className: string,
 63 |   obj: Record<string, any>
 64 | ): any {
 65 |   const restorableClass = restorableClassMap[className];
 66 |   return restorableClass === undefined
 67 |     ? obj
 68 |     : restorableClass["restoreClass"](obj);
 69 | }
 70 | 
 71 | export namespace Restorer {
 72 |   // Makes all the arguments of an argument list restorable.
 73 |   export function makeArgsRestorable(args: any[]): void {
 74 |     const infos: RestorationInfo[] = [];
 75 |     if (args !== undefined) {
 76 |       for (let i = 0; i < args.length; ++i) {
 77 |         const info = Restorer.makeRestorationInfo(args[i]);
 78 |         if (info) {
 79 |           info.argIndex = i;
 80 |           infos.push(info);
 81 |         }
 82 |       }
 83 |     }
 84 |     // Passed argument list always ends with restoration information.
 85 |     args.push(infos);
 86 |   }
 87 | 
 88 |   // Returns information needed to restore an object to its original class.
 89 |   export function makeRestorationInfo(obj: any): RestorationInfo | null {
 90 |     if (obj === null || typeof obj != "object") {
 91 |       return null;
 92 |     }
 93 |     return {
 94 |       className: obj.constructor.name,
 95 |       isError: obj instanceof Error,
 96 |     };
 97 |   }
 98 | 
 99 |   // Makes an error returnable to the caller for restoration and
100 |   // re-throwing, returning the value that the API must return.
101 |   // The thrown value need not be an instance of error.
102 |   export function makeRethrownReturnValue(thrown: any): object {
103 |     // Electron will throw an instance of Error either thrown from
104 |     // here or returned from here, but that instance will only carry
105 |     // the message property and no other properties. In order to
106 |     // retain the error properties, I have to return an object that
107 |     // is not an instance of error. However, I'm intentionally not
108 |     // preserving the stack trace, hiding it from the client.
109 |     if (typeof thrown !== "object") {
110 |       thrown = new __ThrownNonObject(thrown);
111 |       return [thrown, Restorer.makeRestorationInfo(thrown)];
112 |     }
113 |     const info = Restorer.makeRestorationInfo(thrown);
114 |     const returnedError = Object.assign(
115 |       { _affinity_rethrow: true },
116 |       thrown instanceof Error ? { message: thrown.message } : {},
117 |       thrown
118 |     );
119 |     delete returnedError.stack;
120 |     return [returnedError, info];
121 |   }
122 | 
123 |   // Determines whether a returned value is actually a thrown value.
124 |   export function wasThrownValue(value: any): boolean {
125 |     return value != undefined && value._affinity_rethrow;
126 |   }
127 | 
128 |   // Restores argument list using provided restorer function.
129 |   export function restoreArgs(args: any[], restorer?: RestorerFunction) {
130 |     if (args !== undefined) {
131 |       const infos: RestorationInfo[] = args.pop();
132 |       let infoIndex = 0;
133 |       for (let argIndex = 0; argIndex < args.length; ++argIndex) {
134 |         args[argIndex] = Restorer.restoreValue(
135 |           args[argIndex],
136 |           infoIndex < infos.length && argIndex == infos[infoIndex].argIndex
137 |             ? infos[infoIndex++]
138 |             : undefined,
139 |           restorer
140 |         );
141 |       }
142 |     }
143 |   }
144 | 
145 |   // Restores the class of an argument or return value when possible.
146 |   export function restoreValue(
147 |     obj: any,
148 |     info?: RestorationInfo,
149 |     restorer?: RestorerFunction
150 |   ): any {
151 |     if (info) {
152 |       if (info.className == "__ThrownNonObject") {
153 |         obj = new __ThrownNonObject(obj.thrownValue);
154 |       } else if (restorer !== undefined) {
155 |         obj = restorer(info.className, obj);
156 |       }
157 |     }
158 |     return obj;
159 |   }
160 | 
161 |   // Restores a value that was thrown for re-throwing after being returned.
162 |   export function restoreThrownValue(
163 |     value: any,
164 |     info: RestorationInfo,
165 |     restorer?: RestorerFunction
166 |   ): Error {
167 |     delete value._affinity_rethrow;
168 |     value = restoreValue(value, info, restorer);
169 | 
170 |     // If a non-object value was thrown
171 |     if (value instanceof __ThrownNonObject) {
172 |       return value.thrownValue;
173 |     }
174 | 
175 |     // If restorer didn't restore the original Error class
176 |     if (!(value instanceof Error) && info.isError) {
177 |       const message = value.message;
178 |       delete value.message;
179 |       value = Object.assign(new Error(message), value);
180 |     }
181 | 
182 |     // Replace any newly generated stack.
183 |     if (value instanceof Error) {
184 |       value.stack = `${value.constructor.name}: ${value.message}\n\tin main process`;
185 |     }
186 |     return value;
187 |   }
188 | 
189 |   // Wraps thrown non-object values for relay to client. Prefixed with
190 |   // underscores to prevent name conflict with application classes.
191 |   export class __ThrownNonObject {
192 |     _affinity_rethrow = true;
193 |     thrownValue: any;
194 | 
195 |     constructor(thrownValue: any) {
196 |       this.thrownValue = thrownValue;
197 |     }
198 |   }
199 | }
200 | 


--------------------------------------------------------------------------------
/src/lib/shared_lib.ts:
--------------------------------------------------------------------------------
  1 | /**
  2 |  * Code used by both main and renderer processes.
  3 |  */
  4 | 
  5 | // Name of IPC requesting an API for binding.
  6 | export const API_REQUEST_IPC = "_affinity_api_request";
  7 | 
  8 | // Name of IPC providing information needed to bind to an API.
  9 | export const API_RESPONSE_IPC = "_affinity_api_response";
 10 | 
 11 | // Period between attempts to bind an API.
 12 | const _RETRY_MILLIS = 50;
 13 | 
 14 | // Configurable timeout attempting to bind an API.
 15 | let _bindingTimeoutMillis = 4000;
 16 | 
 17 | /**
 18 |  * Utility type for providing the value to which an asynchronous function
 19 |  * resolves. That is, if a function F returns Promise<R>, then AwaitedType<T>
 20 |  * evaluates to type R. Use for extracting the types of bound APIs.
 21 |  *
 22 |  * @param <F> Function for which to determine the resolving type.
 23 |  */
 24 | export type AwaitedType<F> = F extends (...args: any[]) => Promise<infer R>
 25 |   ? R
 26 |   : never;
 27 | 
 28 | /**
 29 |  * Sets the binding timeout. This is the maximum time allowed for the main
 30 |  * process to bind to any window API and the maximum time allowed for a
 31 |  * window to bind to a main API. Also applies to any bindings in progress.
 32 |  *
 33 |  * @param millis Duration of timeout in milliseconds
 34 |  */
 35 | export function setIpcBindingTimeout(millis: number): void {
 36 |   _bindingTimeoutMillis = millis;
 37 | }
 38 | 
 39 | // Matches object properties beginning with neither underscore nor pound.
 40 | // Because this library only ever uses this type in the context of `keyof`,
 41 | // the `#` test is unncessary, as `keyof` won't pull it out. I've included
 42 | // the test here just to emphasize its equivalence to `_`.
 43 | export type PublicProperty<P> = P extends `_${string}`
 44 |   ? never
 45 |   : P extends `#${string}`
 46 |   ? never
 47 |   : P;
 48 | 
 49 | // Information needed to bind to a remote API.
 50 | export type ApiRegistration = {
 51 |   className: string;
 52 |   methodNames: string[];
 53 | };
 54 | 
 55 | // Structure associating API names with names of methods in the API.
 56 | export type ApiRegistrationMap = Record<string, string[]>;
 57 | 
 58 | // Generic API type, for either main or window.
 59 | type ElectronApi<T> = { [K in PublicProperty<keyof T>]: any };
 60 | 
 61 | // Makes an API available for remote binding, installing method handlers.
 62 | export function exposeApi<T>(
 63 |   apiMap: ApiRegistrationMap,
 64 |   api: ElectronApi<T>,
 65 |   installHandler: (ipcName: string, method: any) => void
 66 | ) {
 67 |   const apiClassName = api.constructor.name;
 68 |   if (apiMap[apiClassName]) {
 69 |     return; // was previously exposed
 70 |   }
 71 |   const methodNames: string[] = [];
 72 |   for (const methodName of getPropertyNames(api)) {
 73 |     if (methodName != "constructor" && "_#".indexOf(methodName[0]) < 0) {
 74 |       const method = (api as any)[methodName];
 75 |       if (typeof method == "function") {
 76 |         installHandler(toIpcName(apiClassName, methodName), method);
 77 |         methodNames.push(methodName);
 78 |       }
 79 |     }
 80 |   }
 81 |   apiMap[apiClassName] = methodNames;
 82 | }
 83 | 
 84 | // Returns all properties of the class not defined by JavaScript.
 85 | export function getPropertyNames(obj: any): string[] {
 86 |   const propertyNames: string[] = [];
 87 |   while (!Object.getOwnPropertyNames(obj).includes("hasOwnProperty")) {
 88 |     propertyNames.push(...Object.getOwnPropertyNames(obj));
 89 |     obj = Object.getPrototypeOf(obj);
 90 |   }
 91 |   return propertyNames;
 92 | }
 93 | 
 94 | // Constructs an API-specific IPC name for a method.
 95 | export function toIpcName(apiClassName: string, methodName: string): string {
 96 |   return `${apiClassName}:${methodName}`;
 97 | }
 98 | 
 99 | // Utility for retrying a function until success or timeout.
100 | export function retryUntilTimeout(
101 |   elapsedMillis: number,
102 |   attemptFunc: () => boolean,
103 |   timeoutMessage: string
104 | ): void {
105 |   if (!attemptFunc()) {
106 |     if (elapsedMillis >= _bindingTimeoutMillis) {
107 |       throw Error(timeoutMessage);
108 |     }
109 |     setTimeout(
110 |       () =>
111 |         retryUntilTimeout(
112 |           elapsedMillis + _RETRY_MILLIS,
113 |           attemptFunc,
114 |           timeoutMessage
115 |         ),
116 |       _RETRY_MILLIS
117 |     );
118 |   }
119 | }
120 | 


--------------------------------------------------------------------------------
/src/lib/window_lib.ts:
--------------------------------------------------------------------------------
  1 | /**
  2 |  * Code specific to handling IPC in the renderer process.
  3 |  */
  4 | 
  5 | import type { ElectronMainApi } from "./main_lib";
  6 | import {
  7 |   API_REQUEST_IPC,
  8 |   API_RESPONSE_IPC,
  9 |   ApiRegistration,
 10 |   ApiRegistrationMap,
 11 |   PublicProperty,
 12 |   retryUntilTimeout,
 13 |   toIpcName,
 14 |   exposeApi,
 15 | } from "./shared_lib";
 16 | import { Restorer, RestorerFunction } from "./restorer_lib";
 17 | 
 18 | //// MAIN API SUPPORT //////////////////////////////////////////////////////
 19 | 
 20 | /**
 21 |  * Type to which a bound main API conforms within a window, as determined by
 22 |  * the provided main API class. The type only exposes the API methods of the
 23 |  * class, exposing the methods with the exact return types given by their
 24 |  * implementations, which are necessarily promises.
 25 |  *
 26 |  * @param <T> Type of the main API class
 27 |  */
 28 | export type MainApiBinding<T> = { [K in PublicProperty<keyof T>]: T[K] };
 29 | 
 30 | // These window._affinity_ipc methods are defined in preload.ts
 31 | declare global {
 32 |   interface Window {
 33 |     _affinity_ipc: {
 34 |       invoke: (channel: string, data?: any) => Promise<any>;
 35 |       send: (channel: string, data: any) => void;
 36 |       on: (channel: string, func: (data: any) => void) => void;
 37 |     };
 38 |   }
 39 | }
 40 | 
 41 | // Structure mapping API names to the methods they contain.
 42 | const _mainApiMap: ApiRegistrationMap = {};
 43 | 
 44 | // Structure tracking bound main APIs.
 45 | const _boundMainApis: Record<string, MainApiBinding<any>> = {};
 46 | 
 47 | /**
 48 |  * Returns a window-side binding for a main API of a given class. Main must
 49 |  * have previously exposed the API. Failure of the main process to expose the
 50 |  * API before timeout results in an exception. There is a default timeout, but
 51 |  * you can override it with `setIpcBindingTimeout()`.
 52 |  *
 53 |  * @param <T> Type of the main API class to bind
 54 |  * @param apiClassName Name of the class being bound. Must be identical to
 55 |  *    the name of class T. Provides runtime information that <T> does not.
 56 |  * @param restorer Optional function for restoring the classes of API return
 57 |  *    values. Return values not restored arrive as untyped objects.
 58 |  * @returns An API of type T that can be called as if T were local to
 59 |  *    the window.
 60 |  * @see setIpcBindingTimeout
 61 |  */
 62 | export function bindMainApi<T extends ElectronMainApi<T>>(
 63 |   apiClassName: string,
 64 |   restorer?: RestorerFunction
 65 | ): Promise<MainApiBinding<T>> {
 66 |   _installIpcListeners();
 67 | 
 68 |   return new Promise((resolve) => {
 69 |     if (_boundMainApis[apiClassName]) {
 70 |       resolve(_boundMainApis[apiClassName]);
 71 |     } else {
 72 |       // Make only one request, as main must prevously expose the API.
 73 |       window._affinity_ipc.send(API_REQUEST_IPC, apiClassName);
 74 |       // Client retries so it can bind at earliest possible time.
 75 |       retryUntilTimeout(
 76 |         0,
 77 |         () => {
 78 |           return _attemptBindMainApi(apiClassName, restorer, resolve);
 79 |         },
 80 |         `Timed out waiting to bind main API '${apiClassName}'`
 81 |       );
 82 |     }
 83 |   });
 84 | }
 85 | 
 86 | // Implements a single attempt to bind to a main API.
 87 | function _attemptBindMainApi<T>(
 88 |   apiClassName: string,
 89 |   restorer: RestorerFunction | undefined,
 90 |   resolve: (boundApi: MainApiBinding<T>) => void
 91 | ): boolean {
 92 |   // Wait for the window API binding to arrive.
 93 | 
 94 |   const methodNames = _mainApiMap[apiClassName] as [keyof MainApiBinding<T>];
 95 |   if (!methodNames) {
 96 |     return false;
 97 |   }
 98 | 
 99 |   // Construct the main API binding.
100 | 
101 |   const boundApi = {} as MainApiBinding<T>;
102 |   for (const methodName of methodNames) {
103 |     boundApi[methodName] = (async (...args: any[]) => {
104 |       Restorer.makeArgsRestorable(args);
105 |       const response = await window._affinity_ipc.invoke(
106 |         toIpcName(apiClassName, methodName as string),
107 |         args
108 |       );
109 |       const returnValue = response[0];
110 |       const info = response[1];
111 |       if (Restorer.wasThrownValue(returnValue)) {
112 |         throw Restorer.restoreThrownValue(returnValue, info, restorer);
113 |       }
114 |       return Restorer.restoreValue(returnValue, info, restorer);
115 |     }) as any; // 'any' makes it compatible with the method's signature
116 |   }
117 | 
118 |   // Save the binding to return on duplicate binding requests.
119 | 
120 |   _boundMainApis[apiClassName] = boundApi;
121 | 
122 |   // Return the binding to the window.
123 | 
124 |   resolve(boundApi);
125 |   return true;
126 | }
127 | 
128 | //// WINDOW API SUPPORT //////////////////////////////////////////////////////
129 | 
130 | // Structure mapping window API names to the methods each contains.
131 | let _windowApiMap: ApiRegistrationMap = {};
132 | 
133 | /**
134 |  * Type to which a window API class must conform. All public properties of the
135 |  * method and all properties not beginning with `_` or `#` will be exposed as
136 |  * API methods, allowing the API class to have private properties on which the
137 |  * API methods rely. This type will not expose properties declared `protected`
138 |  * or `private`, but `bindWindowApi()` will still generate bindings for those
139 |  * whose names don't begin with `_` or `#`. Have your window APIs `implement`
140 |  * this type to get type-checking in the APIs themselves, passing in the API
141 |  * class itself for T. Use `checkWindowApi` or  `checkWindowApiClass` to
142 |  * type-check variables containing window APIs.
143 |  *
144 |  * @param <T> The type of the API class itself, typically inferred from a
145 |  *    function that accepts an argument of type `ElectronWindowApi`.
146 |  * @see checkWindowApi
147 |  * @see checkWindowApiClass
148 |  */
149 | export type ElectronWindowApi<T> = {
150 |   [K in PublicProperty<keyof T>]: (...args: any[]) => void;
151 | };
152 | 
153 | /**
154 |  * Type checks the argument to ensure it conforms to the expectations of an
155 |  * instance of a window API class. Returns the argument to allow type-checking
156 |  * of APIs in their places of use.
157 |  *
158 |  * @param <T> (inferred type, not specified in call)
159 |  * @param api Instance of the window API class to type check
160 |  * @return The provided window API instance
161 |  * @see checkWindowApiClass
162 |  */
163 | export function checkWindowApi<T extends ElectronWindowApi<T>>(api: T): T {
164 |   return api;
165 | }
166 | 
167 | /**
168 |  * Type checks the argument to ensure it conforms to the expectations of a
169 |  * window API class. Returns the argument to allow type-checking of APIs in
170 |  * their places of use.
171 |  *
172 |  * @param <T> (inferred type, not specified in call)
173 |  * @param _class The window API class to type check
174 |  * @return The provided window API class
175 |  * @see checkWindowApi
176 |  */
177 | export function checkWindowApiClass<T extends ElectronWindowApi<T>>(_class: {
178 |   new (...args: any[]): T;
179 | }): {
180 |   new (...args: any[]): T;
181 | } {
182 |   return _class;
183 | }
184 | 
185 | /**
186 |  * Exposes a window API to the main process for possible binding.
187 |  *
188 |  * @param <T> (inferred type, not specified in call)
189 |  * @param windowApi The API to expose to the main process, which must be
190 |  *    an instance of a class conforming to type `ElectronWindowApi`. Only
191 |  *    one instance of any given class can ever be exposed.
192 |  * @param restorer Optional function for restoring the classes of
193 |  *    arguments passed to APIs from the main process. Arguments not
194 |  *    restored to original classes arrive as untyped objects.
195 |  */
196 | export function exposeWindowApi<T extends ElectronWindowApi<T>>(
197 |   windowApi: T,
198 |   restorer?: RestorerFunction
199 | ): void {
200 |   _installIpcListeners();
201 |   exposeApi(_windowApiMap, windowApi, (ipcName, method) => {
202 |     window._affinity_ipc.on(ipcName, (args: any[]) => {
203 |       Restorer.restoreArgs(args, restorer);
204 |       method.bind(windowApi)(...args);
205 |     });
206 |   });
207 | }
208 | 
209 | //// COMMON MAIN & WINDOW SUPPORT API ////////////////////////////////////////
210 | 
211 | let _listeningForIPC = false;
212 | 
213 | function _installIpcListeners() {
214 |   if (!_listeningForIPC) {
215 |     window._affinity_ipc.on(API_REQUEST_IPC, (apiClassName: string) => {
216 |       const registration: ApiRegistration = {
217 |         className: apiClassName,
218 |         methodNames: _windowApiMap[apiClassName],
219 |       };
220 |       window._affinity_ipc.send(API_RESPONSE_IPC, registration);
221 |     });
222 |     window._affinity_ipc.on(API_RESPONSE_IPC, (api: ApiRegistration) => {
223 |       _mainApiMap[api.className] = api.methodNames;
224 |     });
225 |     _listeningForIPC = true;
226 |   }
227 | }
228 | 


--------------------------------------------------------------------------------
/src/main.ts:
--------------------------------------------------------------------------------
 1 | /**
 2 |  * Function and types available to the Electron main process.
 3 |  */
 4 | 
 5 | export {
 6 |   ElectronMainApi,
 7 |   WindowApiBinding,
 8 |   exposeMainApi,
 9 |   checkMainApi,
10 |   checkMainApiClass,
11 |   bindWindowApi,
12 |   RelayedError,
13 | } from "./lib/main_lib";
14 | export { AwaitedType, setIpcBindingTimeout } from "./lib/shared_lib";
15 | export {
16 |   RestorableClass,
17 |   RestorerFunction,
18 |   genericRestorer,
19 | } from "./lib/restorer_lib";
20 | 


--------------------------------------------------------------------------------
/src/preload.ts:
--------------------------------------------------------------------------------
 1 | /**
 2 |  * Installs the generic IPC on which APIs are built in the renderer.
 3 |  * The API methods cannot themselves be installed this way because
 4 |  * they require receiving class and method names via IPC, and because
 5 |  * they need to support parameterized construction.
 6 |  */
 7 | 
 8 | import { contextBridge } from "electron";
 9 | import { ipcRenderer } from "electron";
10 | 
11 | contextBridge.exposeInMainWorld("_affinity_ipc", {
12 |   invoke: (channel: string, data: any) => {
13 |     return ipcRenderer.invoke(channel, data);
14 |   },
15 |   send: (channel: string, data: any) => {
16 |     ipcRenderer.send(channel, data);
17 |   },
18 |   on: (channel: string, func: (data: any) => void) => {
19 |     // Don't pass along event as it includes `sender`
20 |     ipcRenderer.on(channel, (_event, args) => func(args));
21 |   },
22 | });
23 | 


--------------------------------------------------------------------------------
/src/window.ts:
--------------------------------------------------------------------------------
 1 | /**
 2 |  * Function and types available to windows in Electron.
 3 |  */
 4 | 
 5 | export {
 6 |   ElectronWindowApi,
 7 |   MainApiBinding,
 8 |   exposeWindowApi,
 9 |   checkWindowApi,
10 |   checkWindowApiClass,
11 |   bindMainApi,
12 | } from "./lib/window_lib";
13 | export { AwaitedType, setIpcBindingTimeout } from "./lib/shared_lib";
14 | export {
15 |   RestorableClass,
16 |   RestorerFunction,
17 |   genericRestorer,
18 | } from "./lib/restorer_lib";
19 | 


--------------------------------------------------------------------------------
/test/api/bad_mainapi.ts:
--------------------------------------------------------------------------------
 1 | import {
 2 |   type ElectronMainApi,
 3 |   exposeMainApi,
 4 |   checkMainApi,
 5 |   checkMainApiClass,
 6 | } from "../../src/main";
 7 | 
 8 | export class BadMainApi implements ElectronMainApi<BadMainApi> {
 9 |   _goodPrivateProperty1 = "foo";
10 |   private _goodPrivateProperty2 = "foo";
11 | 
12 |   // @ts-expect-error because not a method despite being public
13 |   publicProperty = "foo";
14 | 
15 |   // @ts-expect-error because method is not async
16 |   syncMethod(): string {
17 |     return "foo";
18 |   }
19 | 
20 |   async preventUnusedErrors() {
21 |     // prevents unused identifier warnings
22 |     return (
23 |       this._goodPrivateProperty1 +
24 |       this._goodPrivateProperty2 +
25 |       this.tsPrivateProperty +
26 |       this.tsPrivateMethod()
27 |     );
28 |   }
29 | 
30 |   // TypeScript-private methods are ignored
31 |   private tsPrivateProperty = "foo";
32 |   private tsPrivateMethod() {
33 |     return "foo";
34 |   }
35 | }
36 | 
37 | async function dontCall() {
38 |   // @ts-expect-error because API is not compliant
39 |   exposeMainApi(new BadMainApi());
40 | }
41 | 
42 | // @ts-expect-error because BadMainApi is an invalid ElectronMainApi
43 | checkMainApiClass(BadMainApi);
44 | const badMainApi = new BadMainApi();
45 | // @ts-expect-error because badMainApi is an invalid ElectronMainApi
46 | checkMainApi(badMainApi);
47 | 
48 | // prevent unused identifier warnings
49 | if (false) dontCall();
50 | 


--------------------------------------------------------------------------------
/test/api/bad_windowapi.ts:
--------------------------------------------------------------------------------
 1 | import {
 2 |   type ElectronWindowApi,
 3 |   exposeWindowApi,
 4 |   checkWindowApi,
 5 |   checkWindowApiClass,
 6 | } from "../../src/window";
 7 | 
 8 | export class BadWindowApi implements ElectronWindowApi<BadWindowApi> {
 9 |   _goodPrivateProperty1 = "foo";
10 |   private _goodPrivateProperty2 = "foo";
11 | 
12 |   // @ts-expect-error because not a method despite being public
13 |   publicProperty = "foo";
14 | 
15 |   returnsUnusableValue() {
16 |     return "foo";
17 |   }
18 | 
19 |   async preventUnusedErrors() {
20 |     // prevents unused identifier warnings
21 |     return (
22 |       this._goodPrivateProperty1 +
23 |       this._goodPrivateProperty2 +
24 |       this.tsPrivateProperty +
25 |       this.tsPrivateMethod()
26 |     );
27 |   }
28 | 
29 |   // TypeScript-private methods are ignored
30 |   private tsPrivateProperty = "foo";
31 |   private tsPrivateMethod() {
32 |     return "foo";
33 |   }
34 | }
35 | 
36 | async function dontCall() {
37 |   // @ts-expect-error because API is not compliant
38 |   exposeWindowApi(new BadWindowApi());
39 | }
40 | 
41 | // @ts-expect-error because BadMainApi is an invalid ElectronMainApi
42 | checkWindowApiClass(BadWindowApi);
43 | const badWindowApi = new BadWindowApi();
44 | // @ts-expect-error because badMainApi is an invalid ElectronMainApi
45 | checkWindowApi(badWindowApi);
46 | 
47 | // prevent unused identifier warnings
48 | if (false) dontCall();
49 | 


--------------------------------------------------------------------------------
/test/api/call_mainapi1.ts:
--------------------------------------------------------------------------------
 1 | import { bindMainApi } from "../../src/window";
 2 | import type { MainApi1 } from "../api/mainapi1";
 3 | import { Catter, CustomError, restorer } from "../lib/shared_util";
 4 | import { testInvoke } from "../lib/renderer_util";
 5 | 
 6 | export async function callMainApi1(winTag: string) {
 7 |   winTag = winTag + " ";
 8 | 
 9 |   const mainApi1 = await bindMainApi<MainApi1>("MainApi1", restorer);
10 | 
11 |   await testInvoke(winTag + "no reply no error (api1)", () => {
12 |     return mainApi1.noReplyNoError();
13 |   });
14 |   await testInvoke(winTag + "single param (api1)", () => {
15 |     return mainApi1.doubleNumber(21);
16 |   });
17 |   await testInvoke(winTag + "multi param (api1)", () => {
18 |     return mainApi1.sumNumbers(5, 10);
19 |   });
20 |   await testInvoke(winTag + "send class instance (api1)", () => {
21 |     return mainApi1.sendCatter1(new Catter("this", "that"));
22 |   });
23 |   await testInvoke(winTag + "get class instance (api1)", () => {
24 |     return mainApi1.makeCatter1("this", "that");
25 |   });
26 |   await testInvoke(winTag + "all good (api1)", () => {
27 |     return mainApi1.allGoodOrNot1(true);
28 |   });
29 |   await testInvoke(winTag + "plain error (api1)", () => {
30 |     return mainApi1.allGoodOrNot1(false);
31 |   });
32 |   await testInvoke(winTag + "same method (api1)", () => {
33 |     return mainApi1.sameMethodUniqueReply();
34 |   });
35 |   await testInvoke(winTag + "echo back null (api1)", () => {
36 |     return mainApi1.echoBack(null);
37 |   });
38 |   await testInvoke(winTag + "echo back boolean (api1)", () => {
39 |     return mainApi1.echoBack(true);
40 |   });
41 |   await testInvoke(winTag + "echo back single array (api1)", () => {
42 |     return mainApi1.echoBack(["foo", "bar"]);
43 |   });
44 |   await testInvoke(winTag + "echo back Date (api1)", () => {
45 |     return mainApi1.echoBack(new Date("January 1, 2021"));
46 |   });
47 |   await testInvoke(winTag + "echo back plain error (api1)", () => {
48 |     return mainApi1.echoBack(new Error("plain error"));
49 |   });
50 |   await testInvoke(winTag + "echo back custom error (api1)", () => {
51 |     return mainApi1.echoBack(new CustomError("bad thing", 99));
52 |   });
53 |   await testInvoke(winTag + "structured error (api1)", () => {
54 |     return mainApi1.throwFSError();
55 |   });
56 |   await testInvoke(winTag + "custom error (api1)", () => {
57 |     return mainApi1.throwCustomError("bad thing", 99);
58 |   });
59 |   await testInvoke(winTag + "string error (api1)", () => {
60 |     return mainApi1.throwStringError();
61 |   });
62 |   await testInvoke(winTag + "no-message error (api1)", () => {
63 |     return mainApi1.throwNoMessageError();
64 |   });
65 |   await testInvoke(winTag + "non-error object error (api1)", () => {
66 |     return mainApi1.throwNonErrorObject();
67 |   });
68 |   await testInvoke(winTag + "non-restored custom error (api1)", () => {
69 |     return mainApi1.throwNonRestoredCustomError();
70 |   });
71 | }
72 | 


--------------------------------------------------------------------------------
/test/api/call_mainapi2.ts:
--------------------------------------------------------------------------------
 1 | import { bindMainApi } from "../../src/window";
 2 | import type { MainApi2 } from "../api/mainapi2";
 3 | import { Catter, restorer } from "../lib/shared_util";
 4 | import { testInvoke } from "../lib/renderer_util";
 5 | 
 6 | export async function callMainApi2(winTag: string) {
 7 |   winTag = winTag + " ";
 8 | 
 9 |   const mainApi2 = await bindMainApi<MainApi2>("MainApi2", restorer);
10 | 
11 |   await testInvoke(winTag + "send class instance (api2)", () => {
12 |     return mainApi2.sendCatter2(new Catter("this", "that"));
13 |   });
14 |   await testInvoke(winTag + "get class instance (api2)", () => {
15 |     return mainApi2.makeCatter2("this", "that");
16 |   });
17 |   await testInvoke(winTag + "all good (api2)", () => {
18 |     return mainApi2.allGoodOrNot2(true);
19 |   });
20 |   await testInvoke(winTag + "plain error (api2)", () => {
21 |     return mainApi2.allGoodOrNot2(false);
22 |   });
23 |   await testInvoke(winTag + "same method (api2)", () => {
24 |     return mainApi2.sameMethodUniqueReply();
25 |   });
26 | }
27 | 


--------------------------------------------------------------------------------
/test/api/call_mainapi3a.ts:
--------------------------------------------------------------------------------
 1 | import { bindMainApi } from "../../src/window";
 2 | import type { MainApi3 } from "../api/mainapi3";
 3 | import { testInvoke } from "../lib/renderer_util";
 4 | 
 5 | export async function callMainApi3A(winTag: string) {
 6 |   winTag = winTag + " ";
 7 | 
 8 |   const mainApi3 = await bindMainApi<MainApi3>("MainApi3");
 9 | 
10 |   await testInvoke(winTag + "non-relayed error (api3)", () => {
11 |     return mainApi3.throwNonRelayedError();
12 |   });
13 | }
14 | 


--------------------------------------------------------------------------------
/test/api/call_mainapi3b.ts:
--------------------------------------------------------------------------------
 1 | import { bindMainApi } from "../../src/window";
 2 | import type { MainApi3 } from "../api/mainapi3";
 3 | import { testInvoke } from "../lib/renderer_util";
 4 | 
 5 | export async function callMainApi3B(winTag: string) {
 6 |   winTag = winTag + " ";
 7 | 
 8 |   const mainApi3 = await bindMainApi<MainApi3>("MainApi3");
 9 | 
10 |   await testInvoke(winTag + "return relayed error (api3)", () => {
11 |     return mainApi3.returnRelayedError();
12 |   });
13 | }
14 | 


--------------------------------------------------------------------------------
/test/api/call_mainapi4.ts:
--------------------------------------------------------------------------------
 1 | import { bindMainApi } from "../../src/window";
 2 | import type { MainApi4 } from "../api/mainapi4";
 3 | import { Catter } from "../lib/shared_util";
 4 | import { testInvoke } from "../lib/renderer_util";
 5 | 
 6 | export async function callMainApi4(winTag: string) {
 7 |   winTag = winTag + " ";
 8 | 
 9 |   const mainApi4 = await bindMainApi<MainApi4>("MainApi4"); // no restorer
10 | 
11 |   await testInvoke(winTag + "class instance as object (api4)", () => {
12 |     return mainApi4.sendClassInstanceAsObject(new Catter("this", "that"));
13 |   });
14 |   await testInvoke(winTag + "pass plain error (api4)", () => {
15 |     return mainApi4.sendErrorAsArg(new Error("request error"));
16 |   });
17 |   await testInvoke(winTag + "rethrown plain error (api4)", () => {
18 |     return mainApi4.throwRelayedError();
19 |   });
20 | }
21 | 


--------------------------------------------------------------------------------
/test/api/call_winapi1.ts:
--------------------------------------------------------------------------------
 1 | import * as fs from "fs";
 2 | import { BrowserWindow } from "electron";
 3 | 
 4 | import { bindWindowApi } from "../../src/main";
 5 | import type { WinApi1 } from "../api/winapi1";
 6 | import { Catter, CustomError } from "../lib/shared_util";
 7 | 
 8 | export async function callWindowApi1(window: BrowserWindow) {
 9 |   const windowApi1 = await bindWindowApi<WinApi1>(window, "WinApi1");
10 | 
11 |   windowApi1.sendNoParams();
12 | 
13 |   windowApi1.sendStringSameMethod("X");
14 | 
15 |   windowApi1.sendCoordinates(5, 10);
16 | 
17 |   windowApi1.sendCatter(new Catter("this", "that"));
18 | 
19 |   windowApi1.sendNull(null);
20 | 
21 |   windowApi1.sendTrue(true);
22 | 
23 |   windowApi1.sendArray(["foo", "bar"]);
24 | 
25 |   windowApi1.sendDate(new Date("January 1, 2021"));
26 | 
27 |   try {
28 |     fs.readFileSync("__nonexistant_file__");
29 |   } catch (err: any) {
30 |     windowApi1.sendFSError(err);
31 |   }
32 | 
33 |   windowApi1.sendCustomError(new CustomError("bad thing", 99));
34 | }
35 | 


--------------------------------------------------------------------------------
/test/api/call_winapi2.ts:
--------------------------------------------------------------------------------
 1 | import { BrowserWindow } from "electron";
 2 | 
 3 | import { bindWindowApi } from "../../src/main";
 4 | import type { WinApi2 } from "../api/winapi2";
 5 | import { Catter } from "../lib/shared_util";
 6 | 
 7 | export async function callWindowApi2(window: BrowserWindow) {
 8 |   const windowApi2 = await bindWindowApi<WinApi2>(window, "WinApi2");
 9 | 
10 |   windowApi2.sendStringSameMethod("Y");
11 | 
12 |   windowApi2.sendCatter2(new Catter("foo", "bar"));
13 | }
14 | 


--------------------------------------------------------------------------------
/test/api/call_winapi3.ts:
--------------------------------------------------------------------------------
 1 | import { BrowserWindow } from "electron";
 2 | 
 3 | import { bindWindowApi } from "../../src/main";
 4 | import type { WinApi3 } from "../api/winapi3";
 5 | import { Catter } from "../lib/shared_util";
 6 | 
 7 | export async function callWindowApi3(window: BrowserWindow) {
 8 |   const windowApi3 = await bindWindowApi<WinApi3>(window, "WinApi3");
 9 | 
10 |   windowApi3.sendClassInstanceAsObject(new Catter("foo", "bar"));
11 | 
12 |   windowApi3.sendErrorAsArg(new Error("restored error"));
13 | }
14 | 


--------------------------------------------------------------------------------
/test/api/mainapi.ts:
--------------------------------------------------------------------------------
 1 | import { ElectronMainApi } from "../../src/main";
 2 | import { ResultCollector } from "../lib/main_util";
 3 | 
 4 | export abstract class MainApi implements ElectronMainApi<MainApi> {
 5 |   // use 'private' designator to make sure it can be used
 6 |   private _collector: ResultCollector;
 7 | 
 8 |   constructor(collector: ResultCollector) {
 9 |     this._collector = collector;
10 |   }
11 | 
12 |   // Convenience method that also happens to test invoking APIs of
13 |   // ancestor classes of the API class and returning a provied object.
14 |   // (Returning certain provided objects failed some early tests.)
15 |   async echoBack(data: any): Promise<any> {
16 |     this._setRequestData(data);
17 |     return data;
18 |   }
19 | 
20 |   // private, but don't designate with TypeScript, so that compilation
21 |   // guarantees that the 'private' designator is not required.
22 |   _setRequestData(...args: any[]) {
23 |     this._collector.setRequestData(args);
24 |   }
25 | }
26 | 


--------------------------------------------------------------------------------
/test/api/mainapi1.ts:
--------------------------------------------------------------------------------
 1 | import * as fs from "fs";
 2 | 
 3 | import {
 4 |   ElectronMainApi,
 5 |   RelayedError,
 6 |   checkMainApiClass,
 7 | } from "../../src/main";
 8 | import { MainApi } from "./mainapi";
 9 | import {
10 |   Catter,
11 |   CustomError,
12 |   NoMessageError,
13 |   NonErrorObject,
14 |   assertIdentical,
15 | } from "../lib/shared_util";
16 | 
17 | export class MainApi1 extends MainApi implements ElectronMainApi<MainApi1> {
18 |   async noReplyNoError() {}
19 | 
20 |   async doubleNumber(x: number) {
21 |     this._setRequestData(x);
22 |     return x * 2;
23 |   }
24 | 
25 |   async sumNumbers(x: number, y: number) {
26 |     this._setRequestData(x, y);
27 |     return x + y;
28 |   }
29 | 
30 |   async sendCatter1(catter: Catter) {
31 |     this._setRequestData(catter);
32 |     return catter.cat();
33 |   }
34 | 
35 |   async makeCatter1(s1: string, s2: string) {
36 |     this._setRequestData(s1, s2);
37 |     return new Catter(s1, s2);
38 |   }
39 | 
40 |   async allGoodOrNot1(succeed: boolean) {
41 |     this._setRequestData(succeed);
42 |     if (!succeed) {
43 |       throw new RelayedError(Error("Just a plain error"));
44 |     }
45 |     return "all good";
46 |   }
47 | 
48 |   async sameMethodUniqueReply() {
49 |     return "API 1";
50 |   }
51 | 
52 |   async throwFSError() {
53 |     try {
54 |       fs.readFileSync("__nonexistant_file__");
55 |     } catch (err: any) {
56 |       throw new RelayedError(err);
57 |     }
58 |   }
59 | 
60 |   async throwCustomError(message: string, code: number) {
61 |     throw new RelayedError(new CustomError(message, code));
62 |   }
63 | 
64 |   async throwStringError() {
65 |     throw new RelayedError("error string");
66 |   }
67 | 
68 |   async throwNoMessageError() {
69 |     throw new RelayedError(new NoMessageError());
70 |   }
71 | 
72 |   async throwNonErrorObject() {
73 |     throw new RelayedError(new NonErrorObject("bad"));
74 |   }
75 | 
76 |   async throwNonRestoredCustomError() {
77 |     throw new RelayedError(new NonRestoredCustomError());
78 |   }
79 | }
80 | 
81 | class NonRestoredCustomError extends Error {
82 |   constructor() {
83 |     super("non-restored");
84 |   }
85 | }
86 | 
87 | assertIdentical(MainApi1, checkMainApiClass(MainApi1));
88 | 


--------------------------------------------------------------------------------
/test/api/mainapi2.ts:
--------------------------------------------------------------------------------
 1 | import { ElectronMainApi, RelayedError } from "../../src/main";
 2 | import { MainApi } from "./mainapi";
 3 | import { Catter } from "../lib/shared_util";
 4 | 
 5 | export class MainApi2 extends MainApi implements ElectronMainApi<MainApi2> {
 6 |   async sendCatter2(catter: Catter) {
 7 |     this._setRequestData(catter);
 8 |     return catter.cat();
 9 |   }
10 | 
11 |   async makeCatter2(s1: string, s2: string) {
12 |     this._setRequestData(s1, s2);
13 |     return new Catter(s1, s2);
14 |   }
15 | 
16 |   async allGoodOrNot2(succeed: boolean) {
17 |     this._setRequestData(succeed);
18 |     if (!succeed) {
19 |       throw new RelayedError(Error("Just a plain error"));
20 |     }
21 |     return "all good";
22 |   }
23 | 
24 |   async sameMethodUniqueReply() {
25 |     return "API 2";
26 |   }
27 | }
28 | 


--------------------------------------------------------------------------------
/test/api/mainapi3.ts:
--------------------------------------------------------------------------------
 1 | import { ElectronMainApi, RelayedError } from "../../src/main";
 2 | 
 3 | import { MainApi } from "./mainapi";
 4 | 
 5 | export class MainApi3 extends MainApi implements ElectronMainApi<MainApi3> {
 6 |   async throwNonRelayedError() {
 7 |     throw new Error("API exception");
 8 |   }
 9 | 
10 |   async returnRelayedError() {
11 |     return new RelayedError(Error("oops"));
12 |   }
13 | }
14 | 


--------------------------------------------------------------------------------
/test/api/mainapi4.ts:
--------------------------------------------------------------------------------
 1 | import { ElectronMainApi, RelayedError } from "../../src/main";
 2 | 
 3 | import { MainApi } from "./mainapi";
 4 | import { Catter } from "../lib/shared_util";
 5 | 
 6 | export class MainApi4 extends MainApi implements ElectronMainApi<MainApi4> {
 7 |   async sendClassInstanceAsObject(catterAsObject: any) {
 8 |     this._setRequestData(catterAsObject);
 9 |     return new Catter("foo", "bar");
10 |   }
11 | 
12 |   async sendErrorAsArg(errorAsObject: any) {
13 |     this._setRequestData(errorAsObject);
14 |     return new Error("reply error");
15 |   }
16 | 
17 |   async throwRelayedError() {
18 |     throw new RelayedError(Error("thrown error"));
19 |   }
20 | }
21 | 


--------------------------------------------------------------------------------
/test/api/verify_mainapi1.ts:
--------------------------------------------------------------------------------
  1 | import * as assert from "assert";
  2 | 
  3 | import {
  4 |   Catter,
  5 |   CustomError,
  6 |   NoMessageError,
  7 |   NonErrorObject,
  8 | } from "../lib/shared_util";
  9 | import { ResultCollector } from "../lib/main_util";
 10 | 
 11 | const test = it;
 12 | 
 13 | export default (winTag: string, collector: ResultCollector) => {
 14 |   winTag = winTag + " ";
 15 | 
 16 |   test(winTag + "invoke with no reply and no error (api1)", async () => {
 17 |     collector.verifyTest(winTag + "no reply no error (api1)", (result) => {
 18 |       assert.equal(result.error, null);
 19 |       assert.deepEqual(result.requestData, undefined);
 20 |       assert.equal(result.replyData, "undefined");
 21 |     });
 22 |   });
 23 | 
 24 |   test(winTag + "single-parameter invoke (api1)", async () => {
 25 |     collector.verifyTest(winTag + "single param (api1)", (result) => {
 26 |       assert.equal(result.error, null);
 27 |       assert.deepEqual(result.requestData, [21]);
 28 |       assert.equal(result.replyData, "number:42");
 29 |     });
 30 |   });
 31 | 
 32 |   test(winTag + "multi-parameter invoke (api1)", async () => {
 33 |     collector.verifyTest(winTag + "multi param (api1)", (result) => {
 34 |       assert.equal(result.error, null);
 35 |       assert.deepEqual(result.requestData, [5, 10]);
 36 |       assert.equal(result.replyData, "number:15");
 37 |     });
 38 |   });
 39 | 
 40 |   test(winTag + "sending class instance (api1)", async () => {
 41 |     collector.verifyTest(winTag + "send class instance (api1)", (result) => {
 42 |       assert.equal(result.error, null);
 43 |       assert.ok(result.requestData[0] instanceof Catter);
 44 |       assert.equal(result.replyData, 'string:"thisthat"');
 45 |     });
 46 |   });
 47 | 
 48 |   test(winTag + "getting class instance (api1)", async () => {
 49 |     collector.verifyTest(winTag + "get class instance (api1)", (result) => {
 50 |       assert.equal(result.error, null);
 51 |       assert.deepEqual(result.requestData, ["this", "that"]);
 52 |       assert.equal(result.replyData, 'Catter:{"s1":"this","s2":"that"}');
 53 |     });
 54 |   });
 55 | 
 56 |   test(winTag + "conditional error succeeding (api1)", async () => {
 57 |     collector.verifyTest(winTag + "all good (api1)", (result) => {
 58 |       assert.equal(result.error, null);
 59 |       assert.deepEqual(result.requestData, [true]);
 60 |       assert.equal(result.replyData, 'string:"all good"');
 61 |     });
 62 |   });
 63 | 
 64 |   test(winTag + "invoke throwing plain error (api1)", async () => {
 65 |     collector.verifyTest(winTag + "plain error (api1)", (result) => {
 66 |       assert.ok(result.error instanceof Error);
 67 |       assert.equal(result.error.message, "Just a plain error");
 68 |       assert.equal(
 69 |         result.error.stack,
 70 |         "Error: Just a plain error\n\tin main process"
 71 |       );
 72 |       assert.deepEqual(result.requestData, [false]);
 73 |       assert.equal(result.replyData, "undefined");
 74 |     });
 75 |   });
 76 | 
 77 |   test(winTag + "invoke same method name (api1)", async () => {
 78 |     collector.verifyTest(winTag + "same method (api1)", (result) => {
 79 |       assert.equal(result.error, null);
 80 |       assert.deepEqual(result.requestData, null);
 81 |       assert.equal(result.replyData, 'string:"API 1"');
 82 |     });
 83 |   });
 84 | 
 85 |   test(winTag + "echo back null (api1)", async () => {
 86 |     collector.verifyTest(winTag + "echo back null (api1)", (result) => {
 87 |       assert.equal(result.error, null);
 88 |       assert.deepEqual(result.requestData, [null]);
 89 |       assert.equal(result.replyData, "null");
 90 |     });
 91 |   });
 92 | 
 93 |   test(winTag + "echo back boolean (api1)", async () => {
 94 |     collector.verifyTest(winTag + "echo back boolean (api1)", (result) => {
 95 |       assert.equal(result.error, null);
 96 |       assert.deepEqual(result.requestData, [true]);
 97 |       assert.equal(result.replyData, "boolean:true");
 98 |     });
 99 |   });
100 | 
101 |   test(winTag + "echo back single array (api1)", async () => {
102 |     collector.verifyTest(winTag + "echo back single array (api1)", (result) => {
103 |       const expectedResult = ["foo", "bar"];
104 |       assert.equal(result.error, null);
105 |       assert.deepEqual(result.requestData, [expectedResult]);
106 |       assert.equal(result.replyData, "Array:" + JSON.stringify(expectedResult));
107 |     });
108 |   });
109 | 
110 |   test(winTag + "echo back built-in class Date (api1)", async () => {
111 |     collector.verifyTest(winTag + "echo back Date (api1)", (result) => {
112 |       const expectedDate = new Date("January 1, 2021");
113 |       assert.equal(result.error, null);
114 |       assert.deepEqual(result.requestData, [expectedDate]);
115 |       assert.equal(result.replyData, "Date:" + JSON.stringify(expectedDate));
116 |     });
117 |   });
118 | 
119 |   test(winTag + "echo back plain error (api1)", async () => {
120 |     collector.verifyTest(winTag + "echo back plain error (api1)", (result) => {
121 |       const expectedResult = { message: "plain error" };
122 |       assert.equal(result.error, null);
123 |       const arg = result.requestData[0];
124 |       assert.ok(arg instanceof Error);
125 |       assert.equal(arg.message, [expectedResult.message]);
126 |       // Electron strips the stack.
127 |       assert.equal(result.replyData, "Error:" + expectedResult.message);
128 |     });
129 |   });
130 | 
131 |   test(winTag + "echo back custom error (api1)", async () => {
132 |     collector.verifyTest(winTag + "echo back custom error (api1)", (result) => {
133 |       const expectedResult = { message: "bad thing", code: 99 };
134 |       assert.equal(result.error, null);
135 |       const arg = result.requestData[0];
136 |       assert.ok(arg instanceof CustomError);
137 |       assert.equal(arg.message, expectedResult.message);
138 |       // Electron strips the code and stack.
139 |       assert.equal(result.replyData, "CustomError:" + expectedResult.message);
140 |     });
141 |   });
142 | 
143 |   test(winTag + "invoke throwing structured error (api1)", async () => {
144 |     collector.verifyTest(winTag + "structured error (api1)", (result) => {
145 |       const error = result.error as any;
146 |       assert.ok(error instanceof Error);
147 |       assert.ok(typeof error.message == "string");
148 |       assert.equal((error as any).code, "ENOENT");
149 |       assert.equal((error as any).syscall, "open");
150 |       assert.ok((error as any).stack.includes("in main process"));
151 |       assert.equal(result.requestData, undefined);
152 |       assert.equal(result.replyData, "undefined");
153 |     });
154 |   });
155 | 
156 |   test(winTag + "invoke throwing custom error (api1)", async () => {
157 |     collector.verifyTest(winTag + "custom error (api1)", (result) => {
158 |       const error = result.error as any;
159 |       assert.ok(error instanceof CustomError);
160 |       assert.equal(error.message, "bad thing");
161 |       assert.equal(error.code, 99);
162 |       assert.equal(
163 |         result.error.stack,
164 |         "CustomError: bad thing\n\tin main process"
165 |       );
166 |       assert.equal(result.requestData, undefined);
167 |       assert.equal(result.replyData, "undefined");
168 |     });
169 |   });
170 | 
171 |   test(winTag + "invoke throwing string error (api1)", async () => {
172 |     collector.verifyTest(winTag + "string error (api1)", (result) => {
173 |       const error = result.error as any;
174 |       assert.equal(error, "error string");
175 |       assert.equal(typeof error, "string");
176 |       assert.equal(error.message, undefined);
177 |       assert.equal(result.requestData, undefined);
178 |       assert.equal(result.replyData, "undefined");
179 |     });
180 |   });
181 | 
182 |   test(winTag + "invoke throwing no-message error (api1)", async () => {
183 |     collector.verifyTest(winTag + "no-message error (api1)", (result) => {
184 |       const error = result.error as any;
185 |       assert.ok(error instanceof NoMessageError);
186 |       assert.equal(error.message, ""); // Error message is never undefined
187 |       assert.equal(result.error.stack, "NoMessageError: \n\tin main process");
188 |       assert.equal(result.requestData, undefined);
189 |       assert.equal(result.replyData, "undefined");
190 |     });
191 |   });
192 | 
193 |   test(winTag + "invoke throwing non-error object (api1)", async () => {
194 |     collector.verifyTest(winTag + "non-error object error (api1)", (result) => {
195 |       const error = result.error as any;
196 |       assert.ok(error instanceof NonErrorObject);
197 |       assert.equal((error as any).message, undefined);
198 |       assert.equal(error.value, "bad");
199 |       assert.equal(result.error.stack, undefined);
200 |       assert.equal(result.requestData, undefined);
201 |       assert.equal(result.replyData, "undefined");
202 |     });
203 |   });
204 | 
205 |   test(
206 |     winTag + "invoke throwing non-restored custom error (api1)",
207 |     async () => {
208 |       collector.verifyTest(
209 |         winTag + "non-restored custom error (api1)",
210 |         (result) => {
211 |           assert.ok(result.error instanceof Error);
212 |           assert.equal(result.error.message, "non-restored");
213 |           assert.equal(
214 |             result.error.stack,
215 |             "Error: non-restored\n\tin main process"
216 |           );
217 |           assert.deepEqual(result.requestData, undefined);
218 |           assert.equal(result.replyData, "undefined");
219 |         }
220 |       );
221 |     }
222 |   );
223 | };
224 | 


--------------------------------------------------------------------------------
/test/api/verify_mainapi2.ts:
--------------------------------------------------------------------------------
 1 | import * as assert from "assert";
 2 | 
 3 | import { Catter } from "../lib/shared_util";
 4 | import { ResultCollector } from "../lib/main_util";
 5 | 
 6 | const test = it;
 7 | 
 8 | export default (winTag: string, collector: ResultCollector) => {
 9 |   winTag = winTag + " ";
10 | 
11 |   test(winTag + "sending class instance (api2)", async () => {
12 |     collector.verifyTest(winTag + "send class instance (api2)", (result) => {
13 |       assert.equal(result.error, null);
14 |       assert.ok(result.requestData[0] instanceof Catter);
15 |       assert.equal(result.replyData, 'string:"thisthat"');
16 |     });
17 |   });
18 | 
19 |   test(winTag + "getting class instance (api2)", async () => {
20 |     collector.verifyTest(winTag + "get class instance (api2)", (result) => {
21 |       assert.equal(result.error, null);
22 |       assert.deepEqual(result.requestData, ["this", "that"]);
23 |       assert.equal(result.replyData, 'Catter:{"s1":"this","s2":"that"}');
24 |     });
25 |   });
26 | 
27 |   test(winTag + "conditional error succeeding (api2)", async () => {
28 |     collector.verifyTest(winTag + "all good (api2)", (result) => {
29 |       assert.equal(result.error, null);
30 |       assert.deepEqual(result.requestData, [true]);
31 |       assert.equal(result.replyData, 'string:"all good"');
32 |     });
33 |   });
34 | 
35 |   test(winTag + "invoke throwing plain error (api2)", async () => {
36 |     collector.verifyTest(winTag + "plain error (api2)", (result) => {
37 |       assert.ok(result.error instanceof Error);
38 |       assert.equal(result.error.message, "Just a plain error");
39 |       assert.equal(
40 |         result.error.stack,
41 |         "Error: Just a plain error\n\tin main process"
42 |       );
43 |       assert.deepEqual(result.requestData, [false]);
44 |       assert.equal(result.replyData, "undefined");
45 |     });
46 |   });
47 | 
48 |   test(winTag + "invoke same method name (api2)", async () => {
49 |     collector.verifyTest(winTag + "same method (api2)", (result) => {
50 |       assert.equal(result.error, null);
51 |       assert.deepEqual(result.requestData, null);
52 |       assert.equal(result.replyData, 'string:"API 2"');
53 |     });
54 |   });
55 | };
56 | 


--------------------------------------------------------------------------------
/test/api/verify_mainapi4.ts:
--------------------------------------------------------------------------------
 1 | import * as assert from "assert";
 2 | 
 3 | import { Catter } from "../lib/shared_util";
 4 | import { ResultCollector } from "../lib/main_util";
 5 | 
 6 | const test = it;
 7 | 
 8 | export default (winTag: string, collector: ResultCollector) => {
 9 |   winTag = winTag + " ";
10 | 
11 |   test(
12 |     winTag + "send/receive class instance as object, no restorer (api4)",
13 |     async () => {
14 |       collector.verifyTest(
15 |         winTag + "class instance as object (api4)",
16 |         (result) => {
17 |           const requestCatter = new Catter("this", "that");
18 |           const replyCatter = new Catter("foo", "bar");
19 |           assert.equal(result.error, null);
20 |           const arg = result.requestData[0];
21 |           assert.ok(!(arg instanceof Catter));
22 |           assert.deepEqual(arg, requestCatter);
23 |           assert.equal(
24 |             result.replyData,
25 |             "object:" + JSON.stringify(replyCatter)
26 |           );
27 |         }
28 |       );
29 |     }
30 |   );
31 | 
32 |   test(
33 |     winTag + "send/receive plain non-thrown error, no restorer (api4)",
34 |     async () => {
35 |       collector.verifyTest(winTag + "pass plain error (api4)", (result) => {
36 |         assert.equal(result.error, null);
37 |         assert.ok(result.requestData[0] instanceof Error);
38 |         assert.equal(result.requestData[0].message, "request error");
39 |         assert.equal(result.replyData, "Error:reply error");
40 |       });
41 |     }
42 |   );
43 | 
44 |   test(winTag + "invoke throwing plain error, no restorer (api4)", async () => {
45 |     collector.verifyTest(winTag + "rethrown plain error (api4)", (result) => {
46 |       assert.ok(result.error instanceof Error);
47 |       assert.equal(result.error.message, "thrown error");
48 |       assert.equal(
49 |         result.error.stack,
50 |         "Error: thrown error\n\tin main process"
51 |       );
52 |       assert.deepEqual(result.requestData, undefined);
53 |       assert.equal(result.replyData, "undefined");
54 |     });
55 |   });
56 | };
57 | 


--------------------------------------------------------------------------------
/test/api/verify_winapi1.ts:
--------------------------------------------------------------------------------
 1 | import * as assert from "assert";
 2 | 
 3 | import { ResultCollector } from "../lib/main_util";
 4 | 
 5 | const test = it;
 6 | 
 7 | export default (winTag: string, collector: ResultCollector) => {
 8 |   winTag = winTag + " ";
 9 | 
10 |   test(winTag + "send no parameters (api1)", async () => {
11 |     collector.verifyTest(winTag + "no params (win api1)", (result) => {
12 |       assert.equal(result.requestDataTests, "");
13 |     });
14 |   });
15 | 
16 |   test(winTag + "send same method (win api1)", async () => {
17 |     collector.verifyTest(winTag + "same method (win api1)", (result) => {
18 |       assert.equal(result.requestDataTests, "X");
19 |     });
20 |   });
21 | 
22 |   test(winTag + "send multiple params (win api1)", async () => {
23 |     collector.verifyTest(winTag + "multi param (win api1)", (result) => {
24 |       assert.equal(result.requestDataTests, "5;10");
25 |     });
26 |   });
27 | 
28 |   test(winTag + "send restored custom class (win api1)", async () => {
29 |     collector.verifyTest(winTag + "send catter (win api1)", (result) => {
30 |       assert.equal(result.requestDataTests, "true;this;that");
31 |     });
32 |   });
33 | 
34 |   test(winTag + "send null (win api1)", async () => {
35 |     collector.verifyTest(winTag + "null (win api1)", (result) => {
36 |       assert.equal(result.requestDataTests, "null");
37 |     });
38 |   });
39 | 
40 |   test(winTag + "send boolean (win api1)", async () => {
41 |     collector.verifyTest(winTag + "boolean (win api1)", (result) => {
42 |       assert.equal(result.requestDataTests, "true");
43 |     });
44 |   });
45 | 
46 |   test(winTag + "send array (win api1)", async () => {
47 |     collector.verifyTest(winTag + "array (win api1)", (result) => {
48 |       const value = ["foo", "bar"];
49 |       assert.equal(result.requestDataTests, value.toString());
50 |     });
51 |   });
52 | 
53 |   test(winTag + "send built-in type (win api1)", async () => {
54 |     collector.verifyTest(winTag + "built-in type (win api1)", (result) => {
55 |       const expectedDate = new Date("January 1, 2021");
56 |       assert.equal(result.requestDataTests, expectedDate.toString());
57 |     });
58 |   });
59 | 
60 |   test(winTag + "send structured error (win api1)", async () => {
61 |     collector.verifyTest(winTag + "structured error (win api1)", (result) => {
62 |       // Electron strips the error code and stack.
63 |       assert.equal(
64 |         result.requestDataTests,
65 |         "true;ENOENT: no such file or directory"
66 |       );
67 |     });
68 |   });
69 | 
70 |   test(winTag + "send custom error (win api1)", async () => {
71 |     collector.verifyTest(winTag + "custom error (win api1)", (result) => {
72 |       // Electron strips the error code and stack.
73 |       assert.equal(result.requestDataTests, "true;bad thing");
74 |     });
75 |   });
76 | };
77 | 


--------------------------------------------------------------------------------
/test/api/verify_winapi2.ts:
--------------------------------------------------------------------------------
 1 | import * as assert from "assert";
 2 | 
 3 | import { ResultCollector } from "../lib/main_util";
 4 | 
 5 | const test = it;
 6 | 
 7 | export default (winTag: string, collector: ResultCollector) => {
 8 |   winTag = winTag + " ";
 9 | 
10 |   test(winTag + "send same method (win api2)", async () => {
11 |     collector.verifyTest(winTag + "same method (win api2)", (result) => {
12 |       assert.equal(result.requestDataTests, "Y");
13 |     });
14 |   });
15 | 
16 |   test(winTag + "send restored custom class (win api2)", async () => {
17 |     collector.verifyTest(winTag + "send catter (win api2)", (result) => {
18 |       assert.equal(result.requestDataTests, "true;foo;bar");
19 |     });
20 |   });
21 | };
22 | 


--------------------------------------------------------------------------------
/test/api/verify_winapi3.ts:
--------------------------------------------------------------------------------
 1 | import * as assert from "assert";
 2 | 
 3 | import { ResultCollector } from "../lib/main_util";
 4 | 
 5 | const test = it;
 6 | 
 7 | export default (winTag: string, collector: ResultCollector) => {
 8 |   winTag = winTag + " ";
 9 | 
10 |   test(
11 |     winTag + "send class instance as object, no restorer (win api3)",
12 |     async () => {
13 |       collector.verifyTest(
14 |         winTag + "class instance as object (win api3)",
15 |         (result) => {
16 |           assert.equal(result.requestDataTests, "false;foo;bar");
17 |         }
18 |       );
19 |     }
20 |   );
21 | 
22 |   test(winTag + "send error, no restorer (win api3)", async () => {
23 |     collector.verifyTest(winTag + "error as arg (win api3)", (result) => {
24 |       // Electron strips the error code and stack.
25 |       assert.equal(result.requestDataTests, "true;restored error");
26 |     });
27 |   });
28 | };
29 | 


--------------------------------------------------------------------------------
/test/api/winapi1.ts:
--------------------------------------------------------------------------------
 1 | import { ElectronWindowApi, checkWindowApiClass } from "../../src/window";
 2 | import { testSend } from "../lib/renderer_util";
 3 | import { Catter, assertIdentical } from "../lib/shared_util";
 4 | 
 5 | export class WinApi1 implements ElectronWindowApi<WinApi1> {
 6 |   private winTag: string; // test private property without prefix
 7 | 
 8 |   _unused = "for testing compilation";
 9 | 
10 |   constructor(winTag: string) {
11 |     this.winTag = winTag + " ";
12 |   }
13 | 
14 |   // also ensures it's not a problem for window APIs to be async
15 |   async sendNoParams() {
16 |     testSend(this.winTag + "no params (win api1)", () => [""]);
17 |   }
18 | 
19 |   sendStringSameMethod(s: string) {
20 |     testSend(this.winTag + "same method (win api1)", () => [s]);
21 |     return s; // return value should not make it into the bound API
22 |   }
23 | 
24 |   sendCoordinates(x: number, y: number) {
25 |     testSend(this.winTag + "multi param (win api1)", () => [
26 |       x.toString(),
27 |       y.toString(),
28 |     ]);
29 |   }
30 | 
31 |   sendCatter(catter: Catter) {
32 |     testSend(this.winTag + "send catter (win api1)", () => {
33 |       const results: string[] = [];
34 |       results.push((catter instanceof Catter).toString());
35 |       results.push(catter.s1);
36 |       results.push(catter.s2);
37 |       return results;
38 |     });
39 |   }
40 | 
41 |   sendNull(value: any) {
42 |     testSend(this.winTag + "null (win api1)", () => [
43 |       value === null ? "null" : "nope",
44 |     ]);
45 |   }
46 | 
47 |   sendTrue(value: any) {
48 |     testSend(this.winTag + "boolean (win api1)", () => [
49 |       value === true ? "true" : "nope",
50 |     ]);
51 |   }
52 | 
53 |   sendDate(date: Date) {
54 |     testSend(this.winTag + "built-in type (win api1)", () => [date.toString()]);
55 |   }
56 | 
57 |   sendArray(value: any) {
58 |     testSend(this.winTag + "array (win api1)", () => [value.toString()]);
59 |   }
60 | 
61 |   sendFSError(err: Error) {
62 |     testSend(this.winTag + "structured error (win api1)", () => {
63 |       const expectedMessage = "ENOENT: no such file or directory";
64 |       const results: string[] = [];
65 |       results.push((err instanceof Error).toString());
66 |       results.push(err.message.substring(0, expectedMessage.length));
67 |       // Electron strips the error code and stack.
68 |       return results;
69 |     });
70 |   }
71 | 
72 |   sendCustomError(err: Error) {
73 |     testSend(this.winTag + "custom error (win api1)", () => {
74 |       const results: string[] = [];
75 |       results.push((err instanceof Error).toString());
76 |       results.push(err.message);
77 |       // Electron strips the error code and stack.
78 |       return results;
79 |     });
80 |   }
81 | }
82 | 
83 | assertIdentical(WinApi1, checkWindowApiClass(WinApi1));
84 | 


--------------------------------------------------------------------------------
/test/api/winapi2.ts:
--------------------------------------------------------------------------------
 1 | import { ElectronWindowApi } from "../../src/window";
 2 | 
 3 | import { testSend } from "../lib/renderer_util";
 4 | import { Catter } from "../lib/shared_util";
 5 | 
 6 | export class WinApi2 implements ElectronWindowApi<WinApi2> {
 7 |   _winTag: string; // test private property with prefix
 8 | 
 9 |   constructor(winTag: string) {
10 |     this._winTag = winTag + " ";
11 |   }
12 | 
13 |   sendStringSameMethod(s: string) {
14 |     testSend(this._winTag + "same method (win api2)", () => [s]);
15 |   }
16 | 
17 |   sendCatter2(catter: Catter) {
18 |     testSend(this._winTag + "send catter (win api2)", () => {
19 |       const results: string[] = [];
20 |       results.push((catter instanceof Catter).toString());
21 |       results.push(catter.s1);
22 |       results.push(catter.s2);
23 |       return results;
24 |     });
25 |   }
26 | }
27 | 


--------------------------------------------------------------------------------
/test/api/winapi3.ts:
--------------------------------------------------------------------------------
 1 | import { ElectronWindowApi } from "../../src/window";
 2 | 
 3 | import { testSend } from "../lib/renderer_util";
 4 | import { Catter } from "../lib/shared_util";
 5 | 
 6 | export class WinApi3 implements ElectronWindowApi<WinApi3> {
 7 |   __winTag: string; // test private property with double prefix
 8 | 
 9 |   constructor(winTag: string) {
10 |     this.__winTag = winTag + " ";
11 |   }
12 | 
13 |   sendClassInstanceAsObject(catter: any) {
14 |     testSend(this.__winTag + "class instance as object (win api3)", () => {
15 |       const results: string[] = [];
16 |       results.push((catter instanceof Catter).toString());
17 |       results.push(catter.s1);
18 |       results.push(catter.s2);
19 |       return results;
20 |     });
21 |   }
22 | 
23 |   sendErrorAsArg(err: any) {
24 |     testSend(this.__winTag + "error as arg (win api3)", () => {
25 |       const expectedMessage = "restored error";
26 |       const results: string[] = [];
27 |       results.push((err instanceof Error).toString());
28 |       results.push(err.message.substring(0, expectedMessage.length));
29 |       // Electron strips the error code and stack.
30 |       return results;
31 |     });
32 |   }
33 | }
34 | 


--------------------------------------------------------------------------------
/test/lib/config.ts:
--------------------------------------------------------------------------------
1 | export const ACCEPTABLE_DELAY_MILLIS = 1500;
2 | 


--------------------------------------------------------------------------------
/test/lib/main_util.ts:
--------------------------------------------------------------------------------
  1 | import { ipcMain, BrowserWindow } from "electron";
  2 | import * as path from "path";
  3 | import * as fs from "fs";
  4 | 
  5 | import { Restorer, RestorerFunction } from "../../src/lib/restorer_lib";
  6 | import { setIpcErrorLogger } from "../../src/lib/main_lib";
  7 | 
  8 | const COMPLETION_CHECK_INTERVAL_MILLIS = 100;
  9 | const TEST_TIMEOUT_MILLIS = 5000;
 10 | 
 11 | export async function createWindow(): Promise<BrowserWindow> {
 12 |   const window = new BrowserWindow({
 13 |     show: false,
 14 |     webPreferences: {
 15 |       preload: path.join(__dirname, "../../src/preload.js"),
 16 |       nodeIntegration: false,
 17 |       contextIsolation: true,
 18 |     },
 19 |   });
 20 |   window.webContents.openDevTools();
 21 | 
 22 |   await window.loadFile(path.join(__dirname, "../window-scripts/dummy.html"));
 23 |   return window;
 24 | }
 25 | 
 26 | export class Result {
 27 |   testName = "unknown";
 28 |   requestData: any;
 29 |   requestDataTests = "*missing*";
 30 |   replyData = "undefined";
 31 |   error: any = null;
 32 |   verified = false;
 33 | }
 34 | 
 35 | export class ResultCollector {
 36 |   currentResult = new Result();
 37 |   results: Result[] = [];
 38 |   abortError: any = null;
 39 |   _completedAll = false;
 40 | 
 41 |   completedAll() {
 42 |     this._completedAll = true;
 43 |   }
 44 | 
 45 |   waitForResults(): Promise<void> {
 46 |     const self = this;
 47 |     const _waitForResults = (
 48 |       time: number,
 49 |       resolve: () => void,
 50 |       reject: (error: any) => void
 51 |     ) => {
 52 |       setTimeout(() => {
 53 |         time += COMPLETION_CHECK_INTERVAL_MILLIS;
 54 |         if (self.abortError !== null) {
 55 |           reject(self.abortError);
 56 |         } else if (self._completedAll) {
 57 |           resolve();
 58 |         } else if (time >= TEST_TIMEOUT_MILLIS) {
 59 |           reject(Error(`Timed out waiting for results`));
 60 |         } else {
 61 |           _waitForResults(time, resolve, reject);
 62 |         }
 63 |       }, COMPLETION_CHECK_INTERVAL_MILLIS);
 64 |     };
 65 | 
 66 |     return new Promise((resolve, reject) =>
 67 |       _waitForResults(0, resolve, reject)
 68 |     );
 69 |   }
 70 | 
 71 |   reset() {
 72 |     this.currentResult = new Result();
 73 |     this.results = [];
 74 |     this.abortError = null;
 75 |     this._completedAll = false;
 76 |   }
 77 | 
 78 |   async runScripFiletInWindow(window: BrowserWindow, scriptName: string) {
 79 |     this.reset();
 80 |     const scriptPath = path.join(
 81 |       __dirname,
 82 |       "../../test/bundle",
 83 |       scriptName + ".js"
 84 |     );
 85 |     const script = fs.readFileSync(scriptPath, { encoding: "utf-8" });
 86 |     await window.webContents.executeJavaScript(script);
 87 |   }
 88 | 
 89 |   setRequestData(data: any) {
 90 |     this.currentResult.requestData = data;
 91 |   }
 92 | 
 93 |   verifyTest(testName: string, assertFunc: (result: Result) => void): void {
 94 |     for (const result of this.results) {
 95 |       if (result.testName == testName) {
 96 |         assertFunc(result);
 97 |         result.verified = true;
 98 |         return;
 99 |       }
100 |     }
101 |     throw Error(
102 |       `No result found for test '${testName}' among ${this.results.length} tests`
103 |     );
104 |   }
105 | 
106 |   verifyAllDone(): void {
107 |     let testNumber = 0;
108 |     for (const result of this.results) {
109 |       ++testNumber;
110 |       if (!result.verified) {
111 |         throw Error(
112 |           `Failed to verify test #${testNumber} '${result.testName}'`
113 |         );
114 |       }
115 |     }
116 |   }
117 | }
118 | 
119 | // Only one result collector for each Electron instance.
120 | let resultCollector: ResultCollector;
121 | 
122 | export function createResultCollector(restorer: RestorerFunction) {
123 |   if (resultCollector !== undefined) {
124 |     throw Error("Only call createResultCollector() once");
125 |   }
126 |   resultCollector = new ResultCollector();
127 | 
128 |   ipcMain.on("started_test", (_event, testName: string) => {
129 |     resultCollector.currentResult.testName = testName;
130 |   });
131 |   ipcMain.on("request_data_tests", (_event, testResults: string) => {
132 |     resultCollector.currentResult.requestDataTests = testResults;
133 |   });
134 |   ipcMain.on("reply_data", (_event, data: any) => {
135 |     resultCollector.currentResult.replyData = data;
136 |   });
137 |   ipcMain.on("completed_test", (_event, error: any) => {
138 |     resultCollector.currentResult.error = null;
139 |     if (error) {
140 |       const returnValue = error[0];
141 |       const info = error[1];
142 |       resultCollector.currentResult.error = Restorer.restoreThrownValue(
143 |         returnValue,
144 |         info,
145 |         restorer
146 |       );
147 |     }
148 |     resultCollector.results.push(resultCollector.currentResult);
149 |     resultCollector.currentResult = new Result();
150 |   });
151 |   ipcMain.on("completed_all", () => {
152 |     resultCollector.completedAll();
153 |   });
154 |   ipcMain.on("test_aborted", (_event, error: any) => {
155 |     resultCollector.abortError = error;
156 |   });
157 | 
158 |   return resultCollector;
159 | }
160 | 
161 | export function dumpMainApiErrors() {
162 |   setIpcErrorLogger((err) => console.log("\n(MAIN API ERROR) " + err.stack));
163 | }
164 | 


--------------------------------------------------------------------------------
/test/lib/renderer_util.ts:
--------------------------------------------------------------------------------
 1 | import { Restorer } from "../../src/lib/restorer_lib";
 2 | 
 3 | export async function testInvoke(
 4 |   testName: string,
 5 |   testFunc: () => Promise<any>
 6 | ): Promise<void> {
 7 |   window._affinity_ipc.send("started_test", testName);
 8 |   try {
 9 |     const returnValue = await testFunc();
10 |     let replyData: string = typeof returnValue;
11 |     if (replyData !== "undefined") {
12 |       if (returnValue === null) {
13 |         replyData = "null";
14 |       } else {
15 |         if (replyData == "object" && returnValue.constructor.name != "Object") {
16 |           replyData = returnValue.constructor.name;
17 |         }
18 |         if (returnValue instanceof Error) {
19 |           // errors don't stringify
20 |           replyData += ":" + returnValue.message;
21 |           const code = (returnValue as any).code;
22 |           if (code !== undefined) {
23 |             replyData += ";" + code;
24 |           }
25 |         } else {
26 |           replyData += ":" + JSON.stringify(returnValue);
27 |         }
28 |       }
29 |     }
30 |     window._affinity_ipc.send("reply_data", replyData);
31 |     window._affinity_ipc.send("completed_test", null);
32 |   } catch (err: any) {
33 |     window._affinity_ipc.send(
34 |       "completed_test",
35 |       Restorer.makeRethrownReturnValue(err)
36 |     );
37 |   }
38 | }
39 | 
40 | export function testSend(testName: string, testResultsFunc: () => string[]) {
41 |   window._affinity_ipc.send("started_test", testName);
42 |   try {
43 |     window._affinity_ipc.send(
44 |       "request_data_tests",
45 |       testResultsFunc().join(";")
46 |     );
47 |     window._affinity_ipc.send("completed_test", null);
48 |   } catch (err: any) {
49 |     window._affinity_ipc.send(
50 |       "completed_test",
51 |       Restorer.makeRethrownReturnValue(err)
52 |     );
53 |   }
54 | }
55 | 
56 | export function reportErrorsToMain(winTag: string) {
57 |   window.onerror = (message) => {
58 |     window._affinity_ipc.send("test_aborted", `${winTag}: ${message}`);
59 |   };
60 | }
61 | 
62 | export function windowFinished() {
63 |   window._affinity_ipc.send("completed_all", null);
64 | }
65 | 


--------------------------------------------------------------------------------
/test/lib/shared_util.ts:
--------------------------------------------------------------------------------
 1 | import { genericRestorer } from "../../src/lib/restorer_lib";
 2 | 
 3 | export class Catter {
 4 |   s1: string;
 5 |   s2: string;
 6 | 
 7 |   constructor(s1: string, s2: string) {
 8 |     this.s1 = s1;
 9 |     this.s2 = s2;
10 |   }
11 | 
12 |   cat(): string {
13 |     return this.s1 + this.s2;
14 |   }
15 | 
16 |   static restoreClass(obj: any): Catter {
17 |     return new Catter(obj.s1, obj.s2);
18 |   }
19 | }
20 | 
21 | export class CustomError extends Error {
22 |   code: number;
23 | 
24 |   constructor(message: string, code: number) {
25 |     super(message);
26 |     this.code = code;
27 |     // see https://github.com/Microsoft/TypeScript/wiki/Breaking-Changes#extending-built-ins-like-error-array-and-map-may-no-longer-work
28 |     Object.setPrototypeOf(this, CustomError.prototype);
29 |   }
30 | 
31 |   static restoreClass(obj: any): CustomError {
32 |     return new CustomError(obj.message, obj.code);
33 |   }
34 | }
35 | 
36 | export class NoMessageError extends Error {
37 |   constructor() {
38 |     super();
39 |     // see https://github.com/Microsoft/TypeScript/wiki/Breaking-Changes#extending-built-ins-like-error-array-and-map-may-no-longer-work
40 |     Object.setPrototypeOf(this, NoMessageError.prototype);
41 |   }
42 | 
43 |   static restoreClass(_obj: any): NoMessageError {
44 |     return new NoMessageError();
45 |   }
46 | }
47 | 
48 | export class NonErrorObject {
49 |   value: string;
50 | 
51 |   constructor(value: string) {
52 |     this.value = value;
53 |   }
54 | 
55 |   static restoreClass(obj: any): NonErrorObject {
56 |     return new NonErrorObject(obj.value);
57 |   }
58 | }
59 | 
60 | export const restorer = genericRestorer.bind(null, {
61 |   Catter,
62 |   CustomError,
63 |   NoMessageError,
64 |   NonErrorObject,
65 | });
66 | 
67 | export async function sleep(delayMillis: number) {
68 |   return new Promise<void>((resolve) => {
69 |     setTimeout(() => resolve(), delayMillis);
70 |   });
71 | }
72 | 
73 | // because Node's assert isn't available in a window
74 | export function assertIdentical(obj1: any, obj2: any) {
75 |   if (obj1 !== obj2) {
76 |     throw new Error("Objects not identical");
77 |   }
78 | }
79 | 


--------------------------------------------------------------------------------
/test/main-scripts/main_nonrelayed_error.ts:
--------------------------------------------------------------------------------
 1 | import { exposeMainApi } from "../../src/main";
 2 | import { createWindow, createResultCollector } from "../lib/main_util";
 3 | import { MainApi3 } from "../api/mainapi3";
 4 | import { restorer } from "../lib/shared_util";
 5 | 
 6 | const resultCollector = createResultCollector(restorer);
 7 | const mainApi3 = new MainApi3(resultCollector);
 8 | 
 9 | it("waits for main to crash on API error", async () => {
10 |   const window1 = await createWindow();
11 |   exposeMainApi(mainApi3, restorer);
12 |   await resultCollector.runScripFiletInWindow(window1, "win1_mainapi3a");
13 |   await resultCollector.waitForResults();
14 |   if (window1) window1.destroy();
15 | });
16 | 


--------------------------------------------------------------------------------
/test/main-scripts/main_return_relayed.ts:
--------------------------------------------------------------------------------
 1 | import { exposeMainApi } from "../../src/main";
 2 | import { createWindow, createResultCollector } from "../lib/main_util";
 3 | import { MainApi3 } from "../api/mainapi3";
 4 | import { restorer } from "../lib/shared_util";
 5 | 
 6 | const resultCollector = createResultCollector(restorer);
 7 | const mainApi3 = new MainApi3(resultCollector);
 8 | 
 9 | it("waits for main to crash on API error", async () => {
10 |   const window1 = await createWindow();
11 |   exposeMainApi(mainApi3, restorer);
12 |   await resultCollector.runScripFiletInWindow(window1, "win1_mainapi3b");
13 |   await resultCollector.waitForResults();
14 |   if (window1) window1.destroy();
15 | });
16 | 


--------------------------------------------------------------------------------
/test/main-scripts/main_win1_timeout1.ts:
--------------------------------------------------------------------------------
 1 | import { bindWindowApi } from "../../src/main";
 2 | import { createWindow } from "../lib/main_util";
 3 | import type { WinApi1 } from "../api/winapi1";
 4 | 
 5 | it("waits for main to timeout, default timeout", async () => {
 6 |   const window1 = await createWindow();
 7 |   await bindWindowApi<WinApi1>(window1, "WinApi1");
 8 |   window1.destroy();
 9 | });
10 | 


--------------------------------------------------------------------------------
/test/main-scripts/main_win1_timeout2.ts:
--------------------------------------------------------------------------------
 1 | import { ACCEPTABLE_DELAY_MILLIS } from "../lib/config";
 2 | import { bindWindowApi, setIpcBindingTimeout } from "../../src/main";
 3 | import { createWindow } from "../lib/main_util";
 4 | import type { WinApi1 } from "../api/winapi1";
 5 | import { sleep } from "../lib/shared_util";
 6 | 
 7 | it("waits for main to timeout, custom timeout", async () => {
 8 |   const window1 = await createWindow();
 9 |   setIpcBindingTimeout(ACCEPTABLE_DELAY_MILLIS);
10 |   bindWindowApi<WinApi1>(window1, "WinApi1");
11 |   // Window doesn't provide the API for binding.
12 |   await sleep(ACCEPTABLE_DELAY_MILLIS * 1.2);
13 |   if (window1) window1.destroy();
14 | });
15 | 


--------------------------------------------------------------------------------
/test/main-scripts/main_win2_timeout.ts:
--------------------------------------------------------------------------------
 1 | import { BrowserWindow } from "electron";
 2 | 
 3 | import { bindWindowApi, setIpcBindingTimeout } from "../../src/main";
 4 | import { ACCEPTABLE_DELAY_MILLIS } from "../lib/config";
 5 | import { createWindow, createResultCollector } from "../lib/main_util";
 6 | import type { WinApi1 } from "../api/winapi1";
 7 | import { restorer } from "../lib/shared_util";
 8 | import { sleep } from "../lib/shared_util";
 9 | import verifyWindowApi1 from "../api/verify_winapi1";
10 | import { callWindowApi1 } from "../api/call_winapi1";
11 | 
12 | const resultCollector = createResultCollector(restorer);
13 | 
14 | let window1: BrowserWindow;
15 | let window2: BrowserWindow;
16 | 
17 | before(async () => {
18 |   window1 = await createWindow();
19 |   window2 = await createWindow();
20 |   setIpcBindingTimeout(ACCEPTABLE_DELAY_MILLIS);
21 |   // Check for successful binding to window1.
22 |   resultCollector.runScripFiletInWindow(window1, "win1_winapi1");
23 |   await callWindowApi1(window1);
24 |   resultCollector.completedAll();
25 |   await resultCollector.waitForResults();
26 | });
27 | 
28 | verifyWindowApi1("win1", resultCollector);
29 | 
30 | it("waits for main to timeout binding to second window", async () => {
31 |   bindWindowApi<WinApi1>(window2, "WinApi1");
32 |   // Window 2 doesn't provide the API for binding.
33 |   await sleep(ACCEPTABLE_DELAY_MILLIS * 1.2);
34 | });
35 | 
36 | after(() => {
37 |   resultCollector.verifyAllDone();
38 |   if (window1) window1.destroy();
39 |   if (window2) window2.destroy();
40 | });
41 | 


--------------------------------------------------------------------------------
/test/main-scripts/main_window_closed.ts:
--------------------------------------------------------------------------------
 1 | import { bindWindowApi } from "../../src/main";
 2 | import { createWindow, createResultCollector } from "../lib/main_util";
 3 | import type { WinApi1 } from "../api/winapi1";
 4 | import { restorer } from "../lib/shared_util";
 5 | 
 6 | const resultCollector = createResultCollector(restorer);
 7 | 
 8 | it("throws on calling a closed window", async () => {
 9 |   const window1 = await createWindow();
10 |   resultCollector.runScripFiletInWindow(window1, "win1_winapi1");
11 |   const windowApi1 = await bindWindowApi<WinApi1>(window1, "WinApi1");
12 |   window1.destroy();
13 |   windowApi1.sendNoParams();
14 | });
15 | 


--------------------------------------------------------------------------------
/test/run-tests:
--------------------------------------------------------------------------------
 1 | # these tests run in separate instances of Electron
 2 | node_modules/.bin/electron-mocha build/test/test_single_main_api.js --timeout 8000
 3 | node_modules/.bin/electron-mocha build/test/test_single_window_api.js --timeout 8000
 4 | node_modules/.bin/electron-mocha build/test/test_windows_calling.js --timeout 8000
 5 | node_modules/.bin/electron-mocha build/test/test_calling_windows.js --timeout 8000
 6 | node_modules/.bin/electron-mocha build/test/test_main_patience.js --timeout 8000
 7 | node_modules/.bin/electron-mocha build/test/test_window_timeout.js --timeout 8000
 8 | node_modules/.bin/electron-mocha build/test/test_window_reload.js --timeout 8000
 9 | node_modules/.bin/mocha build/test/test_main_crash.js --timeout 8000
10 | node_modules/.bin/mocha build/test/test_type_errors.js --timeout 8000
11 | 


--------------------------------------------------------------------------------
/test/test_calling_windows.ts:
--------------------------------------------------------------------------------
 1 | /**
 2 |  * Test main calling APIs on two windows.
 3 |  */
 4 | 
 5 | import { BrowserWindow } from "electron";
 6 | 
 7 | import { createWindow, createResultCollector } from "./lib/main_util";
 8 | import { restorer } from "./lib/shared_util";
 9 | import { callWindowApi1 } from "./api/call_winapi1";
10 | import { callWindowApi2 } from "./api/call_winapi2";
11 | import { callWindowApi3 } from "./api/call_winapi3";
12 | import verifyWindowApi1 from "./api/verify_winapi1";
13 | import verifyWindowApi2 from "./api/verify_winapi2";
14 | import verifyWindowApi3 from "./api/verify_winapi3";
15 | 
16 | const resultCollector = createResultCollector(restorer);
17 | 
18 | describe("main calling the same APIs in two windows", () => {
19 |   let window1: BrowserWindow;
20 |   let window2: BrowserWindow;
21 | 
22 |   before(async () => {
23 |     window1 = await createWindow();
24 |     window2 = await createWindow();
25 | 
26 |     resultCollector.runScripFiletInWindow(window1, "win1_winapi1+2");
27 |     resultCollector.runScripFiletInWindow(window2, "win2_winapi1+3");
28 |     await callWindowApi1(window1);
29 |     await callWindowApi2(window1);
30 |     await callWindowApi1(window2);
31 |     await callWindowApi3(window2);
32 |     resultCollector.completedAll();
33 |     await resultCollector.waitForResults();
34 |   });
35 | 
36 |   verifyWindowApi1("win1", resultCollector);
37 |   verifyWindowApi2("win1", resultCollector);
38 |   verifyWindowApi1("win2", resultCollector);
39 |   verifyWindowApi3("win2", resultCollector);
40 | 
41 |   after(() => {
42 |     if (window1) window1.destroy();
43 |     if (window2) window2.destroy();
44 |     resultCollector.verifyAllDone();
45 |   });
46 | });
47 | 


--------------------------------------------------------------------------------
/test/test_main_crash.ts:
--------------------------------------------------------------------------------
 1 | /**
 2 |  * Test scenarious that should cause Electron to crash with an exception.
 3 |  */
 4 | 
 5 | import * as path from "path";
 6 | import * as assert from "assert";
 7 | import { exec } from "child_process";
 8 | 
 9 | const test = it;
10 | 
11 | const rootPath = path.join(__dirname, "../../");
12 | const mochaPath = path.join(rootPath, "node_modules/.bin/electron-mocha");
13 | 
14 | describe("when main should crash with an error", () => {
15 |   test("main times out waiting to bind to first window (default timeout)", (done) => {
16 |     verifyCrash(
17 |       "main_win1_timeout1",
18 |       "Main timed out waiting to bind to window API 'WinApi1'",
19 |       done
20 |     );
21 |   });
22 | 
23 |   test("main times out waiting to bind to first window (custom timeout)", (done) => {
24 |     verifyCrash(
25 |       "main_win1_timeout2",
26 |       "Main timed out waiting to bind to window API 'WinApi1'",
27 |       done
28 |     );
29 |   });
30 | 
31 |   test("main times out waiting to bind to second window with same API", (done) => {
32 |     verifyCrash(
33 |       "main_win2_timeout",
34 |       "Main timed out waiting to bind to window API 'WinApi1'",
35 |       done
36 |     );
37 |   });
38 | 
39 |   test("main throws when calling API of a window that closed", (done) => {
40 |     verifyCrash("main_window_closed", "Window has closed", done);
41 |   });
42 | 
43 |   test("main throws when API throws an non-relayed error", (done) => {
44 |     verifyCrash("main_nonrelayed_error", "API exception", done);
45 |   });
46 | 
47 |   test("main throws when API returns a relayed error", (done) => {
48 |     verifyCrash("main_return_relayed", "RelayedError must be thrown", done);
49 |   });
50 | });
51 | 
52 | function verifyCrash(
53 |   scriptName: string,
54 |   expectedErrorText: string,
55 |   done: Mocha.Done
56 | ): void {
57 |   // I was unable to override the uncaught exception in electron-mocha,
58 |   // neither via process.removeAllListeners() + process.on() nor via
59 |   // process.prependOnceListener(), so I test the output of electron-mocha.
60 | 
61 |   const scriptPath = path.join(
62 |     rootPath,
63 |     "build/test/main-scripts",
64 |     scriptName + ".js"
65 |   );
66 |   const command = `node ${mochaPath} ${scriptPath} --timeout 8000`;
67 |   exec(command, (err, stdout, stderr) => {
68 |     if (
69 |       stdout.includes(expectedErrorText) ||
70 |       stderr.includes(expectedErrorText)
71 |     ) {
72 |       done();
73 |     } else if (err) {
74 |       done(Error(err + "..." + stdout));
75 |     } else if (stderr.includes("Error")) {
76 |       assert.fail(stderr);
77 |     } else {
78 |       assert.fail("Child process unexpectedly completed... " + stdout);
79 |     }
80 |   });
81 | }
82 | 


--------------------------------------------------------------------------------
/test/test_main_patience.ts:
--------------------------------------------------------------------------------
 1 | /**
 2 |  * Test main's ability to wait for a window to provide an API for binding.
 3 |  */
 4 | 
 5 | import { BrowserWindow } from "electron";
 6 | 
 7 | import { setIpcBindingTimeout } from "../src/main";
 8 | import { ACCEPTABLE_DELAY_MILLIS } from "./lib/config";
 9 | import { createWindow, createResultCollector } from "./lib/main_util";
10 | import { restorer } from "./lib/shared_util";
11 | import verifyWindowApi1 from "./api/verify_winapi1";
12 | import { callWindowApi1 } from "./api/call_winapi1";
13 | 
14 | const resultCollector = createResultCollector(restorer);
15 | 
16 | describe("delay binding to a window API", () => {
17 |   let window1: BrowserWindow;
18 | 
19 |   before(async () => {
20 |     window1 = await createWindow();
21 |     setIpcBindingTimeout(ACCEPTABLE_DELAY_MILLIS);
22 |     resultCollector.runScripFiletInWindow(window1, "win1_winapi1_delayed");
23 |     await callWindowApi1(window1);
24 |     resultCollector.completedAll();
25 |     await resultCollector.waitForResults();
26 |   });
27 | 
28 |   verifyWindowApi1("win1", resultCollector);
29 | 
30 |   after(() => {
31 |     if (window1) window1.destroy();
32 |     resultCollector.verifyAllDone();
33 |   });
34 | });
35 | 


--------------------------------------------------------------------------------
/test/test_single_main_api.ts:
--------------------------------------------------------------------------------
 1 | /**
 2 |  * Test calling methods of a single main API under normal circumstances.
 3 |  */
 4 | 
 5 | import { BrowserWindow } from "electron";
 6 | 
 7 | import { exposeMainApi, checkMainApi } from "../src/main";
 8 | import { createWindow, createResultCollector } from "./lib/main_util";
 9 | import { MainApi1 } from "./api/mainapi1";
10 | import { restorer, assertIdentical } from "./lib/shared_util";
11 | import verifyMainApi1 from "./api/verify_mainapi1";
12 | 
13 | const resultCollector = createResultCollector(restorer);
14 | const mainApi1 = new MainApi1(resultCollector);
15 | assertIdentical(mainApi1, checkMainApi(mainApi1));
16 | 
17 | describe("window invoking an exposed main API", () => {
18 |   let window1: BrowserWindow;
19 | 
20 |   before(async () => {
21 |     window1 = await createWindow();
22 |     // includes test of exposing API after running script
23 |     resultCollector.runScripFiletInWindow(window1, "win1_mainapi1");
24 |     exposeMainApi(mainApi1, restorer);
25 |     await resultCollector.waitForResults();
26 |   });
27 | 
28 |   verifyMainApi1("win1", resultCollector);
29 | 
30 |   after(() => {
31 |     if (window1) window1.destroy();
32 |     resultCollector.verifyAllDone();
33 |   });
34 | });
35 | 


--------------------------------------------------------------------------------
/test/test_single_window_api.ts:
--------------------------------------------------------------------------------
 1 | /**
 2 |  * Test calling methods of a single window API under normal circumstances.
 3 |  */
 4 | 
 5 | import { BrowserWindow } from "electron";
 6 | 
 7 | import { createWindow, createResultCollector } from "./lib/main_util";
 8 | import { restorer } from "./lib/shared_util";
 9 | import verifyWindowApi1 from "./api/verify_winapi1";
10 | import { callWindowApi1 } from "./api/call_winapi1";
11 | 
12 | const resultCollector = createResultCollector(restorer);
13 | 
14 | describe("main messaging a window API", () => {
15 |   let window1: BrowserWindow;
16 | 
17 |   before(async () => {
18 |     window1 = await createWindow();
19 |     resultCollector.runScripFiletInWindow(window1, "win1_winapi1");
20 |     await callWindowApi1(window1);
21 |     resultCollector.completedAll();
22 |     await resultCollector.waitForResults();
23 |   });
24 | 
25 |   verifyWindowApi1("win1", resultCollector);
26 | 
27 |   after(() => {
28 |     if (window1) window1.destroy();
29 |     resultCollector.verifyAllDone();
30 |   });
31 | });
32 | 


--------------------------------------------------------------------------------
/test/test_type_errors.ts:
--------------------------------------------------------------------------------
 1 | /**
 2 |  * Tests for expected type errors at compile time.
 3 |  */
 4 | 
 5 | import { bindMainApi } from "../src/window";
 6 | import { bindWindowApi } from "../src/main";
 7 | 
 8 | import type { BadMainApi } from "./api/bad_mainapi";
 9 | import type { BadWindowApi } from "./api/bad_windowapi";
10 | 
11 | const test = it;
12 | 
13 | async function checkWindowClientOfMain() {
14 |   // @ts-expect-error because the API is not a valid main API
15 |   const boundMainApi = await bindMainApi<BadMainApi>("BadMainApi");
16 | 
17 |   // @ts-expect-error because method does not return a promise
18 |   await takesMainMethod(boundMainApi.syncMethod);
19 | 
20 |   // @ts-expect-error because method does not exist
21 |   boundMainApi.notThere();
22 | 
23 |   // @ts-expect-error to ensure invalid property wasn't turned into a method
24 |   boundMainApi.publicProperty();
25 | 
26 |   // @ts-expect-error because bindings should not include private properties
27 |   boundMainApi._goodPrivateProperty;
28 |   // @ts-expect-error because bindings should not include private properties
29 |   boundMainApi.tsPrivateProperty;
30 |   // @ts-expect-error because bindings should not include private properties
31 |   boundMainApi.tsPrivateMethod();
32 | }
33 | 
34 | async function checkMainClientOfWindow() {
35 |   // @ts-expect-error because the API is not a valid window API
36 |   const boundWindowApi = await bindWindowApi<BadWindowApi>(
37 |     {} as any,
38 |     "BadWindowApi"
39 |   );
40 | 
41 |   // @ts-expect-error because method does not exist
42 |   await boundWindowApi.notThere();
43 | 
44 |   // @ts-expect-error to ensure invalid property wasn't turned into a method
45 |   boundWindowApi.publicProperty();
46 | 
47 |   // @ts-expect-error because client does not receive return values
48 |   takesString(boundWindowApi.returnsUnusableValue());
49 |   // @ts-expect-error because client does not receive return values
50 |   takesStringPromise(boundWindowApi.returnsUnusableValue());
51 | 
52 |   // @ts-expect-error because bindings should not include private properties
53 |   boundWindowApi._goodPrivateProperty;
54 |   // @ts-expect-error because bindings should not include private properties
55 |   boundWindowApi.tsPrivateProperty;
56 |   // @ts-expect-error because bindings should not include private properties
57 |   boundWindowApi.tsPrivateMethod();
58 | }
59 | 
60 | async function takesMainMethod(method: (...args: any[]) => Promise<any>) {
61 |   await method();
62 | }
63 | function takesString(s: string) {
64 |   console.log(s);
65 | }
66 | async function takesStringPromise(sp: Promise<string>) {
67 |   console.log(await sp);
68 | }
69 | 
70 | test("compiler produces expected type errors", () => {
71 |   // prevent unused identifier warnings
72 |   if (false) checkWindowClientOfMain();
73 |   if (false) checkMainClientOfWindow();
74 | });
75 | 


--------------------------------------------------------------------------------
/test/test_window_reload.ts:
--------------------------------------------------------------------------------
 1 | /**
 2 |  * Test calling methods after rebinding upon window reload.
 3 |  */
 4 | 
 5 | import { BrowserWindow } from "electron";
 6 | 
 7 | import { exposeMainApi } from "../src/main";
 8 | import { createWindow, createResultCollector } from "./lib/main_util";
 9 | import { MainApi2 } from "./api/mainapi2";
10 | import { restorer } from "./lib/shared_util";
11 | import verifyMainApi2 from "./api/verify_mainapi2";
12 | 
13 | const resultCollector = createResultCollector(restorer);
14 | const mainApi2 = new MainApi2(resultCollector);
15 | 
16 | describe("rebinding after window reload", () => {
17 |   let windowLoaded = false;
18 |   let window1: BrowserWindow;
19 | 
20 |   const waitForLoad = (resolve: () => void) => {
21 |     setTimeout(() => {
22 |       if (windowLoaded) {
23 |         resolve();
24 |       } else {
25 |         waitForLoad(resolve);
26 |       }
27 |     }, 100);
28 |   };
29 | 
30 |   before(async () => {
31 |     // Note: I was unable to accomplish this all in one script that installs a
32 |     // window.onload function, as that function never seemed to be called.
33 | 
34 |     window1 = await createWindow();
35 |     window1.webContents.once("did-finish-load", () => {
36 |       windowLoaded = true;
37 |     });
38 | 
39 |     exposeMainApi(mainApi2, restorer);
40 |     resultCollector.runScripFiletInWindow(window1, "win1_mainapi2_reload_1");
41 | 
42 |     await new Promise<void>((resolve) => waitForLoad(resolve));
43 |     resultCollector.runScripFiletInWindow(window1, "win1_mainapi2_reload_2");
44 |     await resultCollector.waitForResults();
45 |   });
46 | 
47 |   verifyMainApi2("win1", resultCollector);
48 | 
49 |   after(() => {
50 |     if (window1) window1.destroy();
51 |     resultCollector.verifyAllDone();
52 |   });
53 | });
54 | 


--------------------------------------------------------------------------------
/test/test_window_timeout.ts:
--------------------------------------------------------------------------------
 1 | /**
 2 |  * Test to ensure that windows timeout if main does not provide an API.
 3 |  */
 4 | 
 5 | import * as assert from "assert";
 6 | import { BrowserWindow } from "electron";
 7 | 
 8 | const test = it;
 9 | 
10 | import { exposeMainApi } from "../src/main";
11 | import { createWindow, createResultCollector } from "./lib/main_util";
12 | import { MainApi1 } from "./api/mainapi1";
13 | import { restorer } from "./lib/shared_util";
14 | 
15 | const resultCollector = createResultCollector(restorer);
16 | 
17 | describe("window times out waiting to bind main API", () => {
18 |   const mainApi1 = new MainApi1(resultCollector);
19 |   let window1: BrowserWindow;
20 |   let window2: BrowserWindow;
21 |   let window3: BrowserWindow;
22 | 
23 |   test("main exposes no APIs, default timeout", async () => {
24 |     window1 = await createWindow();
25 |     resultCollector.runScripFiletInWindow(window1, "win1_mainapi1");
26 |     try {
27 |       await resultCollector.waitForResults();
28 |       assert.fail("Window 1 did not time out");
29 |     } catch (err: any) {
30 |       assert.equal(
31 |         err,
32 |         "win1: Uncaught Error: Timed out waiting to bind main API 'MainApi1'"
33 |       );
34 |     }
35 |     // Don't close window1; its exception destroys it.
36 |   });
37 | 
38 |   test("main exposes no APIs, custom timeout", async () => {
39 |     window2 = await createWindow();
40 |     resultCollector.runScripFiletInWindow(window2, "win2_mainapi2_timeout");
41 |     try {
42 |       await resultCollector.waitForResults();
43 |       assert.fail("Window 2 did not time out");
44 |     } catch (err: any) {
45 |       assert.equal(
46 |         err,
47 |         "win2: Uncaught Error: Timed out waiting to bind main API 'MainApi2'"
48 |       );
49 |     }
50 |     // Don't close window1; its exception destroys it.
51 |   });
52 | 
53 |   test("main exposes an API other than the expected one, custom timeout", async () => {
54 |     window3 = await createWindow();
55 |     exposeMainApi(mainApi1, restorer);
56 |     resultCollector.runScripFiletInWindow(window3, "win3_mainapi2_timeout");
57 |     try {
58 |       await resultCollector.waitForResults();
59 |       assert.fail("Window 3 did not time out");
60 |     } catch (err: any) {
61 |       assert.equal(
62 |         err,
63 |         "win3: Uncaught Error: Timed out waiting to bind main API 'MainApi2'"
64 |       );
65 |     }
66 |     // Don't close window2; its exception destroys it.
67 |   });
68 | });
69 | 


--------------------------------------------------------------------------------
/test/test_windows_calling.ts:
--------------------------------------------------------------------------------
 1 | /**
 2 |  * Test binding the same main APIs in different windows.
 3 |  */
 4 | 
 5 | import { BrowserWindow } from "electron";
 6 | 
 7 | import { exposeMainApi } from "../src/main";
 8 | import { createWindow, createResultCollector } from "./lib/main_util";
 9 | import { MainApi1 } from "./api/mainapi1";
10 | import { MainApi2 } from "./api/mainapi2";
11 | import { MainApi4 } from "./api/mainapi4";
12 | import { restorer } from "./lib/shared_util";
13 | import verifyMainApi1 from "./api/verify_mainapi1";
14 | import verifyMainApi2 from "./api/verify_mainapi2";
15 | import verifyMainApi4 from "./api/verify_mainapi4";
16 | 
17 | const resultCollector = createResultCollector(restorer);
18 | 
19 | describe("two windows calling the same main APIs", () => {
20 |   const mainApi1 = new MainApi1(resultCollector);
21 |   const mainApi2 = new MainApi2(resultCollector);
22 |   const mainApi4 = new MainApi4(resultCollector);
23 |   let window1: BrowserWindow;
24 |   let window2: BrowserWindow;
25 | 
26 |   before(async () => {
27 |     window1 = await createWindow();
28 |     exposeMainApi(mainApi1, restorer);
29 |     exposeMainApi(mainApi2, restorer);
30 |     window2 = await createWindow();
31 |     exposeMainApi(mainApi1, restorer);
32 |     exposeMainApi(mainApi4); // no restorer
33 |   });
34 | 
35 |   describe("window 1 invoking main", () => {
36 |     before(async () => {
37 |       resultCollector.runScripFiletInWindow(window1, "win1_mainapi1+2");
38 |       await resultCollector.waitForResults();
39 |     });
40 | 
41 |     verifyMainApi1("win1", resultCollector);
42 |     verifyMainApi2("win1", resultCollector);
43 | 
44 |     after(() => {
45 |       resultCollector.verifyAllDone();
46 |       if (window1) window1.destroy();
47 |     });
48 |   });
49 | 
50 |   describe("window 2 invoking main", () => {
51 |     before(async () => {
52 |       resultCollector.runScripFiletInWindow(window2, "win2_mainapi1+4");
53 |       await resultCollector.waitForResults();
54 |     });
55 | 
56 |     verifyMainApi1("win2", resultCollector);
57 |     verifyMainApi4("win2", resultCollector);
58 | 
59 |     after(() => {
60 |       resultCollector.verifyAllDone();
61 |       if (window2) window2.destroy();
62 |     });
63 |   });
64 | });
65 | 


--------------------------------------------------------------------------------
/test/window-scripts/dummy.html:
--------------------------------------------------------------------------------
1 | <html>
2 |   <body></body>
3 | </html>


--------------------------------------------------------------------------------
/test/window-scripts/tsconfig.json:
--------------------------------------------------------------------------------
 1 | {
 2 |     "compilerOptions": {
 3 |         "sourceMap": true,
 4 |         "target": "ES6",
 5 |         "module": "ESNext",
 6 |         "moduleResolution": "node",
 7 |         "stripInternal": true,
 8 |         "strict": true,
 9 |         "pretty": true,
10 |         "noUnusedLocals": true,
11 |         "noUnusedParameters": true,
12 |         "noImplicitReturns": true,
13 |         "noFallthroughCasesInSwitch": true,
14 |         "noEmitOnError": true,
15 |         "allowSyntheticDefaultImports": true,
16 |         "emitDecoratorMetadata": true,
17 |         "experimentalDecorators": true,
18 |         "esModuleInterop": true,
19 |     },
20 | }


--------------------------------------------------------------------------------
/test/window-scripts/win1_mainapi1+2.ts:
--------------------------------------------------------------------------------
 1 | import { reportErrorsToMain, windowFinished } from "../lib/renderer_util";
 2 | import { callMainApi1 } from "../api/call_mainapi1";
 3 | import { callMainApi2 } from "../api/call_mainapi2";
 4 | 
 5 | (async () => {
 6 |   try {
 7 |     reportErrorsToMain("win1");
 8 |     await callMainApi1("win1");
 9 |     await callMainApi2("win1");
10 |     windowFinished();
11 |   } catch (err) {
12 |     window._affinity_ipc.send("test_aborted", err);
13 |   }
14 | })();
15 | 


--------------------------------------------------------------------------------
/test/window-scripts/win1_mainapi1.ts:
--------------------------------------------------------------------------------
 1 | import { reportErrorsToMain, windowFinished } from "../lib/renderer_util";
 2 | import { callMainApi1 } from "../api/call_mainapi1";
 3 | 
 4 | (async () => {
 5 |   try {
 6 |     reportErrorsToMain("win1");
 7 |     await callMainApi1("win1");
 8 |     windowFinished();
 9 |   } catch (err) {
10 |     window._affinity_ipc.send("test_aborted", err);
11 |   }
12 | })();
13 | 


--------------------------------------------------------------------------------
/test/window-scripts/win1_mainapi2_reload_1.ts:
--------------------------------------------------------------------------------
 1 | import { bindMainApi } from "../../src/window";
 2 | import type { MainApi2 } from "../api/mainapi2";
 3 | import { restorer } from "../lib/shared_util";
 4 | import { reportErrorsToMain } from "../lib/renderer_util";
 5 | 
 6 | (async () => {
 7 |   try {
 8 |     reportErrorsToMain("win1");
 9 |     await bindMainApi<MainApi2>("MainApi2", restorer);
10 |     window.location.reload();
11 |   } catch (err) {
12 |     window._affinity_ipc.send("test_aborted", err);
13 |   }
14 | })();
15 | 


--------------------------------------------------------------------------------
/test/window-scripts/win1_mainapi2_reload_2.ts:
--------------------------------------------------------------------------------
 1 | import { reportErrorsToMain, windowFinished } from "../lib/renderer_util";
 2 | import { callMainApi2 } from "../api/call_mainapi2";
 3 | 
 4 | (async () => {
 5 |   try {
 6 |     reportErrorsToMain("win1");
 7 |     await callMainApi2("win1");
 8 |     windowFinished();
 9 |   } catch (err) {
10 |     window._affinity_ipc.send("test_aborted", err);
11 |   }
12 | })();
13 | 


--------------------------------------------------------------------------------
/test/window-scripts/win1_mainapi3a.ts:
--------------------------------------------------------------------------------
 1 | import { reportErrorsToMain, windowFinished } from "../lib/renderer_util";
 2 | import { callMainApi3A } from "../api/call_mainapi3a";
 3 | 
 4 | (async () => {
 5 |   try {
 6 |     reportErrorsToMain("win1");
 7 |     await callMainApi3A("win1");
 8 |     windowFinished();
 9 |   } catch (err) {
10 |     window._affinity_ipc.send("test_aborted", err);
11 |   }
12 | })();
13 | 


--------------------------------------------------------------------------------
/test/window-scripts/win1_mainapi3b.ts:
--------------------------------------------------------------------------------
 1 | import { reportErrorsToMain, windowFinished } from "../lib/renderer_util";
 2 | import { callMainApi3B } from "../api/call_mainapi3b";
 3 | 
 4 | (async () => {
 5 |   try {
 6 |     reportErrorsToMain("win1");
 7 |     await callMainApi3B("win1");
 8 |     windowFinished();
 9 |   } catch (err) {
10 |     window._affinity_ipc.send("test_aborted", err);
11 |   }
12 | })();
13 | 


--------------------------------------------------------------------------------
/test/window-scripts/win1_winapi1+2.ts:
--------------------------------------------------------------------------------
1 | import { exposeWindowApi } from "../../src/window";
2 | import { WinApi1 } from "../api/winapi1";
3 | import { WinApi2 } from "../api/winapi2";
4 | import { restorer } from "../lib/shared_util";
5 | 
6 | exposeWindowApi(new WinApi1("win1"), restorer);
7 | exposeWindowApi(new WinApi2("win1"), restorer);
8 | 


--------------------------------------------------------------------------------
/test/window-scripts/win1_winapi1.ts:
--------------------------------------------------------------------------------
1 | import { exposeWindowApi, checkWindowApi } from "../../src/window";
2 | import { WinApi1 } from "../api/winapi1";
3 | import { restorer, assertIdentical } from "../lib/shared_util";
4 | 
5 | const winApi1 = new WinApi1("win1");
6 | assertIdentical(winApi1, checkWindowApi(winApi1));
7 | 
8 | exposeWindowApi(winApi1, restorer);
9 | 


--------------------------------------------------------------------------------
/test/window-scripts/win1_winapi1_delayed.ts:
--------------------------------------------------------------------------------
 1 | import { exposeWindowApi } from "../../src/window";
 2 | import { ACCEPTABLE_DELAY_MILLIS } from "../lib/config";
 3 | import { WinApi1 } from "../api/winapi1";
 4 | import { restorer } from "../lib/shared_util";
 5 | import { sleep } from "../lib/shared_util";
 6 | 
 7 | (async () => {
 8 |   try {
 9 |     await sleep(ACCEPTABLE_DELAY_MILLIS * 0.8);
10 |     exposeWindowApi(new WinApi1("win1"), restorer);
11 |   } catch (err) {
12 |     window._affinity_ipc.send("test_aborted", err);
13 |   }
14 | })();
15 | 


--------------------------------------------------------------------------------
/test/window-scripts/win2_mainapi1+4.ts:
--------------------------------------------------------------------------------
 1 | import { reportErrorsToMain, windowFinished } from "../lib/renderer_util";
 2 | import { callMainApi1 } from "../api/call_mainapi1";
 3 | import { callMainApi4 } from "../api/call_mainapi4";
 4 | 
 5 | (async () => {
 6 |   try {
 7 |     reportErrorsToMain("win2");
 8 |     await callMainApi1("win2");
 9 |     await callMainApi4("win2");
10 |     windowFinished();
11 |   } catch (err) {
12 |     window._affinity_ipc.send("test_aborted", err);
13 |   }
14 | })();
15 | 


--------------------------------------------------------------------------------
/test/window-scripts/win2_mainapi2_timeout.ts:
--------------------------------------------------------------------------------
 1 | import { setIpcBindingTimeout } from "../../src/window";
 2 | import { ACCEPTABLE_DELAY_MILLIS } from "../lib/config";
 3 | import { reportErrorsToMain, windowFinished } from "../lib/renderer_util";
 4 | import { callMainApi2 } from "../api/call_mainapi2";
 5 | 
 6 | (async () => {
 7 |   try {
 8 |     reportErrorsToMain("win2");
 9 |     setIpcBindingTimeout(ACCEPTABLE_DELAY_MILLIS);
10 |     await callMainApi2("win2");
11 |     windowFinished();
12 |   } catch (err) {
13 |     window._affinity_ipc.send("test_aborted", err);
14 |   }
15 | })();
16 | 


--------------------------------------------------------------------------------
/test/window-scripts/win2_winapi1+3.ts:
--------------------------------------------------------------------------------
1 | import { exposeWindowApi } from "../../src/window";
2 | import { WinApi1 } from "../api/winapi1";
3 | import { WinApi3 } from "../api/winapi3";
4 | import { restorer } from "../lib/shared_util";
5 | 
6 | exposeWindowApi(new WinApi1("win2"), restorer);
7 | exposeWindowApi(new WinApi3("win2")); // no restorer
8 | 


--------------------------------------------------------------------------------
/test/window-scripts/win3_mainapi2_timeout.ts:
--------------------------------------------------------------------------------
 1 | import { setIpcBindingTimeout } from "../../src/window";
 2 | import { ACCEPTABLE_DELAY_MILLIS } from "../lib/config";
 3 | import { reportErrorsToMain, windowFinished } from "../lib/renderer_util";
 4 | import { callMainApi2 } from "../api/call_mainapi2";
 5 | 
 6 | (async () => {
 7 |   try {
 8 |     reportErrorsToMain("win3");
 9 |     setIpcBindingTimeout(ACCEPTABLE_DELAY_MILLIS);
10 |     await callMainApi2("win3");
11 |     windowFinished();
12 |   } catch (err) {
13 |     window._affinity_ipc.send("test_aborted", err);
14 |   }
15 | })();
16 | 


--------------------------------------------------------------------------------
/tsconfig.json:
--------------------------------------------------------------------------------
 1 | {
 2 |     "compilerOptions": {
 3 |         "sourceMap": true,
 4 |         "sourceRoot": "build",
 5 |         "lib": [
 6 |             "esnext", "dom"
 7 |         ],
 8 |         "declaration": true,
 9 |         "outDir": "build",
10 |         "stripInternal": true,
11 |         "strict": true,
12 |         "pretty": true,
13 |         "noUnusedLocals": true,
14 |         "noUnusedParameters": true,
15 |         "noImplicitReturns": true,
16 |         "noFallthroughCasesInSwitch": true,
17 |         "noEmitOnError": true,
18 |         "allowSyntheticDefaultImports": true,
19 |         "emitDecoratorMetadata": true,
20 |         "experimentalDecorators": true,
21 |     },
22 |     "include": [
23 |         "src/*",
24 |         "test/**/*"
25 |     ],
26 |     "exclude": [
27 |         "node_modules/*",
28 |         "build/*",
29 |         "test/window-scripts/*"
30 |     ]
31 | }


--------------------------------------------------------------------------------