# @holo-host/comb

> Cross-origin message bus (COMB) facilitates communication between a hApp UI and Holo Chaperone

Latest version **0.3.2** (published 2023-11-01) · ISC license · 0 weekly downloads

## Install

```sh
npm install @holo-host/comb
pnpm add @holo-host/comb
yarn add @holo-host/comb
bun add @holo-host/comb
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.3.2 |
| Published | 2023-11-01 |
| First published | 2019-12-08 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 4 |
| Unpacked size | 60.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Holo Ltd. |
| Maintainers | brisebom, peeech, jetttech, robbiecarlton, zo-el |

## Links

- npm: https://www.npmjs.com/package/@holo-host/comb
- Repository: https://github.com/Holo-Host/chaperone
- Homepage: https://github.com/Holo-Host/chaperone#readme
- Issues: https://github.com/Holo-Host/chaperone/issues
- npm.io page: https://npm.io/package/@holo-host/comb

## Dependencies (4)

- [webpack](https://npm.io/package/webpack.md) ^5.89.0
- [postmate](https://npm.io/package/postmate.md) ^1.5.1
- [webpack-cli](https://npm.io/package/webpack-cli.md) 4.10.0
- [@msgpack/msgpack](https://npm.io/package/@msgpack/msgpack.md) ^2.7.1

## Recent versions

- 0.3.2 (latest) — 2023-11-01
- 0.3.1 — 2023-10-22
- 0.3.0 — 2022-06-03
- 0.2.0 — 2021-02-04
- 0.1.6 — 2020-04-14
- 0.1.5 — 2020-04-10
- 0.1.4 — 2020-04-06
- 0.1.3 — 2020-01-10
- 0.1.2 — 2019-12-08
- 0.1.1 — 2019-12-08
- 0.1.0 — 2019-12-08

## README

![](https://img.shields.io/npm/v/@holo-host/comb/latest?style=flat-square)

# Cross-origin Message Bus (COMB)

COMB is a library that facilitates the calls between the parent window (hApp UI) and the iframe
(Chaperone).

Used between [Holo Chaperone](https://github.com/Holo-Host/chaperone/tree/develop) and `Holo Hosting
Web SDK`.

## Architecture

COMB is designed to make an iFrame feel like a script.  With this in mind, the expectation is that
the parent window wants to operate the iFrame, not vice-versa.  The purpose of using an iFrame
instead of a script will usually be for isolation and/or security.  The iFrame does not trust the
parent window, but requires input from the parent window to know what to do.

**Features**
- Parent/Child communication line
- Promise wrappers
- Round trip method request
- Restrict domains

### API

[API Reference](https://holo-host.github.io/chaperone/comb/docs/module-COMB.html)

### Example Usage

Both the parent window and iFrame must load COMB.


```html
<script type="text/javascript" src="./holo_hosting_comb.js"></script>
<script type="text/javascript">
(async () => {
    const child = await comb.connect( url, document.body, 5000, signal => console.log('comb got signal', signal) );

    await child.set("development_mode", true );
    await child.set("welcome_greeting", "Hello" );

    let response = await child.run("isDevelopmentMode");
    // true
    let response = await child.run("sayWelcome", "world", true );
    // "HELLO WORLD!"
})();
</script>
```

```html
<script type="text/javascript" src="./holo_hosting_comb.js"></script>
<script type="text/javascript">
(async () => {
    const parent = comb.listen({
        "isDevelopmentMode": function () {
            return this.development_mode;
        },
        "sayWelcome": async function ( name, uppercase ) {
            let message = `${this.welcome_greeting}, ${name}!`;
            return uppercase === true ? message.toUpperCase() : message;
        },
    });
})();
</script>
```


## Contributors

We use `Postmate` to set up a message tunnel between the parent and child frames.

`Postmate` provided a `call` child method in its API, but it did not return the result.  COMB's
`Parent` and `Child` classes wrap the communication tunnel in a more useful `request/response` type
API.

**Development environment as of 2019/11**
- Node.js `12`

**Project employs**
- Typescript
- Webpack
- JSDoc

**Setup**

Nix shell will provide packages listed in [../default.nix](../default.nix) `nativeBuildInputs`
```bash
nix-shell ../shell.nix
```

Inside the nix shell
```bash
yarn install
```

### Compile (Typescript)

The source is written in Typescript.  Run `yarn run compile` or `make build`.

### Bundler (Webpack)

The web distribution is bundled with Webpack.  Run `yarn run bundle` or `make dist`.

> **NOTE:** `yarn run bundle` will not automatically compile

### Testing

```bash
yarn test
```

#### Unit tests
Unit tests are not written because nearly all the complexity is in the integration tests.

#### Integration tests
Integration tests use `puppeteer` to simulate a real browser experience.

**Required setup**
- HTTP Server for parent window (hApp UI)
- HTTP Server for child window (Holo Chaperon)
- Call methods from parent, mock responses from external systems (Resolver, Envoy)

---
_Source: https://npm.io/package/@holo-host/comb · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._