comlink - GitLite

KO | EN

gitlite — search

#javascript #python #react #ai #typescript #llm #go #machine-learning #rust #docker #java #awesome #awesome-list #mcp

comlink

(★ 12,784)

Comlink은 WebWorker를 다루는 것을 즐겁게 만들어 줍니다.

파일 탐색기

최종 버전 다운로드 (.zip)

- pre-commit
- index.html
- comlink.ts
- node-adapter.ts
- protocol.ts
- - attack-iframe.html
  - iframe.html
  - two-way-iframe.html
  - worker.js
- - main.mjs
  - worker.mjs
- cross-origin.comlink.test.js
- iframe.comlink.test.js
- same_window.comlink.test.js
- tsconfig.json
- two-way-iframe.comlink.test.js
- type-checks.ts
- worker.comlink.test.js
.gitignore
.travis.yml
CHANGELOG.md
CODEOWNERS
CONTRIBUTING
CONTRIBUTORS
Dockerfile
karma.conf.js
LICENSE
package.json
README.md
renovate.json
rollup.config.mjs
structured-clone-table.md
tsconfig.json

# 설치 가이드

1. 코드 내려받기

git clone https://github.com/GoogleChromeLabs/comlink

깃허브에서 프로젝트 코드 전체를 내 컴퓨터로 내려받습니다.

cd comlink

방금 내려받은 프로젝트 폴더 안으로 이동합니다.

2. Docker

쉬움 추천

사전 준비물

Git GitHub에서 프로젝트 코드를 내려받으려면 필요합니다.
Docker Desktop 컨테이너를 빌드하고 실행하려면 필요합니다. 설치 후 실행해서 백그라운드에 켜두세요.

docker build -t comlink .

Dockerfile을 기반으로 실행 가능한 이미지를 빌드합니다.

docker run -p 8080:80 comlink

빌드된 이미지를 실제 컨테이너로 실행합니다.

✅ 터미널에 docker compose ps 를 입력해 컨테이너들이 Up 상태인지 확인하세요. README에 포트 번호가 적혀있다면 브라우저에서 http://localhost:포트번호 로 접속해보세요.

3. Node.js

쉬움

사전 준비물

Git GitHub에서 프로젝트 코드를 내려받으려면 필요합니다.
Node.js npm 명령어를 쓰려면 Node.js가 설치되어 있어야 합니다. LTS(장기지원) 버전을 추천합니다.

$ npm install --save comlink

package.json에 명시된 라이브러리들을 내려받아 설치합니다.

✅ 명령어 실행 후 터미널에 나타나는 주소(보통 http://localhost:3000 형태)를 브라우저에서 열어보세요.

이 레포의 README에 적힌 실제 명령어를 그대로 가져왔습니다.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Comlink
Comlink을 사용하면 [WebWorkers][webworker]가 즐거워집니다. Comlink는 **초소형 라이브러리(1.1kB)**로, `postMessage`에 대한 심리적 장벽을 없애주고 워커(worker)와 작업하고 있다는 사실을 숨겨줍니다.
더 추상적인 수준에서 이것은 `postMessage`와 [ES6 Proxies][es6 proxy]를 위한 RPC 구현입니다.
```
$ npm install --save comlink
```
![Comlink in action](https://user-images.githubusercontent.com/234957/54164510-cdab2d80-4454-11e9-92d0-7356aa6c5746.png)
## 브라우저 지원 및 번들 크기
![Chrome 56+](https://img.shields.io/badge/Chrome-56+-green.svg?style=flat-square)
![Edge 15+](https://img.shields.io/badge/Edge-15+-green.svg?style=flat-square)
![Firefox 52+](https://img.shields.io/badge/Firefox-52+-green.svg?style=flat-square)
![Opera 43+](https://img.shields.io/badge/Opera-43+-green.svg?style=flat-square)
![Safari 10.1+](https://img.shields.io/badge/Safari-10.1+-green.svg?style=flat-square)
![Samsung Internet 6.0+](https://img.shields.io/badge/Samsung\_Internet-6.0+-green.svg?style=flat-square)
[ES6 Proxy]를 지원하지 않는 브라우저는 [proxy-polyfill]을 사용할 수 있습니다.
**크기**: ~2.5k, gzip 압축 시 ~1.2k, brotli 압축 시 ~1.1k
## 소개
휴대폰, 특히 저사양 휴대폰에서는 메인 스레드를 최대한 유휴 상태로 유지하여 사용자 상호작용에 빠르게 응답하고 버벅임 없는 경험을 제공하는 것이 중요합니다. **UI 스레드는 오직 UI 작업만을 위한 것이어야 합니다**. WebWorkers는 별도의 스레드에서 코드를 실행할 수 있게 해주는 웹 API입니다. 다른 스레드와 통신하기 위해 WebWorkers는 `postMessage` API를 제공합니다. `myWorker.postMessage(someObject)`를 사용하여 자바스크립트 객체를 메시지로 전송할 수 있으며, 이는 워커 내부에 `message` 이벤트를 발생시킵니다.
Comlink는 RPC 구현을 제공함으로써 이 메시지 기반 API를 개발자 친화적인 무언가로 바꿔줍니다. 한 스레드의 값을 마치 로컬 값처럼 다른 스레드 내에서 (그리고 그 반대로도) 사용할 수 있습니다.
## 예제
### [간단한 함수 실행하기](./docs/examples/01-simple-example)
**main.js**
```javascript
import \* as Comlink from "https://unpkg.com/comlink/dist/esm/comlink.mjs";
async function init() {
const worker = new Worker("worker.js");
// WebWorkers는 `postMessage`를 사용하므로 Comlink와 함께 작동합니다.
const obj = Comlink.wrap(worker);
alert(`Counter: ${await obj.counter}`);
await obj.inc();
alert(`Counter: ${await obj.counter}`);
}
init();
```
**worker.js**
```javascript
importScripts("https://unpkg.com/comlink/dist/umd/comlink.js");
// importScripts("../../../dist/umd/comlink.js");
const obj = {
counter: 0,
inc() {
this.counter++;
},
};
Comlink.expose(obj);
```
### [콜백](./docs/examples/02-callback-example)
**main.js**
```javascript
import \* as Comlink from "https://unpkg.com/comlink/dist/esm/comlink.mjs";
// import \* as Comlink from "../../../dist/esm/comlink.mjs";
function callback(value) {
alert(`Result: ${value}`);
}
async function init() {
const remoteFunction = Comlink.wrap(new Worker("worker.js"));
await remoteFunction(Comlink.proxy(callback));
}
init();
```
**worker.js**
```javascript
importScripts("https://unpkg.com/comlink/dist/umd/comlink.js");
// importScripts("../../../dist/umd/comlink.js");
async function remoteFunction(cb) {
await cb("A string from a worker");
}
Comlink.expose(remoteFunction);
```
### [`SharedWorker`](./docs/examples/07-sharedworker-example)
[`SharedWorker`](https://developer.mozilla.org/en-US/docs/Web/API/SharedWorker)와 함께 Comlink를 사용할 때는 다음을 수행해야 합니다:
1. `Comlink.wrap`을 호출할 때 `SharedWorker` 인스턴스의 [`port`](https://developer.mozilla.org/en-US/docs/Web/API/SharedWorker/port) 속성을 사용합니다.
2. 공유 워커의 [`onconnect`](https://developer.mozilla.org/en-US/docs/Web/API/SharedWorkerGlobalScope/onconnect) 콜백 내에서 `Comlink.expose`를 호출합니다.
**전문가 팁:** 다음 주소로 이동하여 현재 Chrome에서 실행 중인 모든 공유 워커의 DevTools에 액세스할 수 있습니다: **chrome://inspect/#workers**
**main.js**
```javascript
import \* as Comlink from "https://unpkg.com/

com/comlink/dist/esm/comlink.mjs";
async function init() {
const worker = new SharedWorker("worker.js");
/\*\*
\* SharedWorker는 `port` 속성의 `postMessage` 함수를 통해 통신합니다.
\* 따라서 `Comlink.wrap`을 호출할 때는 SharedWorker의 `port` 속성을 사용해야 합니다.
\*/
const obj = Comlink.wrap(worker.port);
alert(`Counter: ${await obj.counter}`);
await obj.inc();
alert(`Counter: ${await obj.counter}`);
}
init();
```
\*\*worker.js\*\*
```javascript
importScripts("https://unpkg.com/comlink/dist/umd/comlink.js");
// importScripts("../../../dist/umd/comlink.js");
const obj = {
counter: 0,
inc() {
this.counter++;
},
};
/\*\*
\* 이 SharedWorker에 연결이 생성되면, 연결된 `port`를 통해
\* `obj`를 노출(expose)합니다.
\*/
onconnect = function (event) {
const port = event.ports[0];
Comlink.expose(obj, port);
};
// 단일 라인 대체 방법:
// onconnect = (e) => Comlink.expose(obj, e.ports[0]);
```
\*\*추가 예제는 프로젝트의 [docs/examples](./docs/examples) 디렉터리를 참고하세요.\*\*
## API
### `Comlink.wrap(endpoint)` 및 `Comlink.expose(value, endpoint?, allowedOrigins?)`
Comlink의 목표는 한 스레드에서 \_노출된(exposed)\_ 값들을 다른 스레드에서도 사용할 수 있게 만드는 것입니다. `expose`는 `endpoint` 상에 `value`를 노출하며, 여기서 `endpoint`는 [`postMessage`와 유사한 인터페이스][endpoint]이고 `allowedOrigins`는 접근을 허용할 오리진을 정의하는 RegExp 또는 문자열 배열입니다 (기본값은 모든 오리진을 허용하는 특수 케이스인 `['\*']`입니다).
`wrap`은 메시지 채널의 \_다른\_ 끝을 감싸서(wrap) 프록시를 반환합니다. 이 프록시는 노출된 값의 모든 속성과 함수를 가지지만, 접근과 호출은 본질적으로 비동기적입니다. 즉, 숫자를 반환하는 함수는 이제 숫자에 대한 \_프로미스(promise)\_를 반환하게 됩니다. \*\*경험칙: 프록시를 사용하는 경우, 앞에 `await`를 붙이세요.\*\* 예외는 캐치되어 반대편에서 다시 던져집니다(re-thrown).
### `Comlink.transfer(value, transferables)` 및 `Comlink.proxy(value)`
기본적으로 모든 함수 매개변수, 반환값, 객체 속성값은 [구조화된 복제(structured cloning)] 방식으로 복사됩니다. 구조화된 복제는 깊은 복사(deep copy)와 유사하다고 생각할 수 있지만 몇 가지 제한 사항이 있습니다. 자세한 내용은 [이 표][structured clone table]를 참고하세요.
값이 복사되는 대신 전송(transfer)되기를 원하고, 해당 값이 [`Transferable`][transferable]이거나 이를 포함하고 있는 경우, 값을 `transfer()` 호출로 감싸고 전송 가능한 값들의 목록을 제공할 수 있습니다:
```js
const data = new Uint8Array([1, 2, 3, 4, 5]);
await myProxy.someFunction(Comlink.transfer(data, [data.buffer]));
```
마지막으로 `Comlink.proxy(value)`를 사용할 수 있습니다. 이를 사용하면 Comlink는 값을 복사하거나 전송하지 않고 대신 프록시를 보냅니다. 이제 두 스레드는 동일한 값을 대상으로 작업합니다. 예를 들어 함수는 구조화된 복제나 전송이 불가능하므로 콜백 등에 유용합니다.
```js
myProxy.onready = Comlink.proxy((data) => {
/\* ... \*/
});
```
### 전송 핸들러와 이벤트 리스너
이벤트 소스가 다른 스레드에 있는 경우에 Comlink를 사용하여 이벤트 리스너를 추가하는 것은 흔한 일입니다:
```js
button.addEventListener("click", myProxy.onClick.bind(myProxy));
```
이 코드가 즉시 에러를 발생시키지는 않지만, `onClick`은 실제로 절대 호출되지 않습니다. [`Event`][event]는 구조화된 복제도, 전송도 불가능하기 때문입니다. 그 우회책으로 Comlink는 전송 핸들러(transfer handlers)를 제공합니다.
각 함수 매개변수와 반환값은 \_모든\_ 등록된 전송 핸들러에 전달됩니다. 이벤트 핸들러 중 하나가 `canHandle()`에서 `true`를 반환하여 값을 처리할 수 있음을 알리면, 해당 핸들러가 값을 구조화된 복제 가능 데이터로 직렬화하고 역직렬화하는 작업을 담당하게 됩니다. 전송 핸들러는 메시지 채널의 \_양쪽 모두\_에 설정되어야 합니다. 다음은 이벤트용 전송 핸들러의 예시입니다:
```js
Comlink.transferHandlers.set("EVENT", {
canHandle: (obj) => obj instanceof Event,
serialize: (ev) => {
return [
{
target: {
id: ev.target.id,
classList: [...ev.target.classList],
},
},
[],

];
},
deserialize: (obj) => obj,
});
```
이 특정 전송 핸들러는 실제 `Event`를 생성하지 않으며, 단지 `event.target.id` 및 `event.target.classList` 속성을 가진 객체만 생성합니다. 대개는 이것만으로도 충분합니다. 그렇지 않은 경우, 필요한 모든 데이터를 제공하도록 전송 핸들러를 쉽게 확장할 수 있습니다.
### `Comlink.releaseProxy`
Comlink가 생성한 모든 프록시는 `[releaseProxy]()` 메서드를 가집니다.
이를 호출하면 프록시와 노출된 객체가 메시지 채널에서 분리되어, 양쪽 엔드포인트 모두 가비지 컬렉션(garbage collection) 대상이 될 수 있습니다.
```js
const proxy = Comlink.wrap(port);
// ... 프록시 사용 ...
proxy[Comlink.releaseProxy]();
```
브라우저가 [WeakRef proposal]을 지원하는 경우, `wrap()`으로 생성된 프록시가 가비지 컬렉션될 때 `[releaseProxy]()`가 자동으로 호출됩니다.
### `Comlink.finalizer`
노출된 객체에 `[Comlink.finalizer]` 속성이 있는 경우, 프록시가 해제될 때 해당 속성이 함수로 호출됩니다. 이는 `[releaseProxy]()`를 수동으로 호출하거나, 런타임이 [WeakRef proposal]을 지원하는 경우 가비지 컬렉션 과정에서 자동으로 발생할 수 있습니다(위의 `Comlink.releaseProxy` 참고). 파이날라이저(finalizer) 함수가 호출될 때 엔드포인트가 닫히며 더 이상 통신이 불가능하다는 점에 유의하세요.
### `Comlink.createEndpoint`
Comlink가 생성한 모든 프록시는 `[createEndpoint]()` 메서드를 가집니다.
이를 호출하면, `[createEndpoint]()`가 호출된 프록시와 동일한 객체에 연결된 새로운 `MessagePort`가 반환됩니다.
```js
const port = myProxy[Comlink.createEndpoint]();
const newProxy = Comlink.wrap(port);
```
### `Comlink.windowEndpoint(window, context = self, targetOrigin = "\*")`
Windows와 Web Workers는 `postMessage`의 약간 다른 변형들을 가지고 있습니다. iframe이나 다른 창과 통신하기 위해 Comlink를 사용하려면 `windowEndpoint()`로 감싸야 합니다.
`window`는 통신할 대상 창입니다. `context`는 `window`\_로부터의\_ 메시지를 수신할 수 있는 `EventTarget`입니다(대개 `self`). `targetOrigin`은 `postMessage`로 전달되어 오리진(origin)별로 메시지를 필터링할 수 있게 해줍니다. 자세한 내용은 [`Window.postMessage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) 문서를 참고하세요.
사용 예시를 보려면 `docs` 폴더의 비-워커(non-worker) 예시들을 살펴보세요.
## TypeScript
Comlink는 TypeScript 타입을 제공합니다. `T` 타입의 무언가를 `expose()`하면, 그에 상응하는 `wrap()` 호출은 `Comlink.Remote` 타입의 무언가를 반환합니다. 이 타입은 그동안 충분히 검증되었지만, 최선의 노력(best-effort)을 바탕으로 구현되어 있습니다. TypeScript의 타입 시스템에서 올바르게 인코딩하기 매우 어렵거나 불가능한 미묘한 차이들이 존재합니다. 때로는 `as unknown as `를 사용하여 특정 타입을 강제해야 할 수도 있습니다.
## Node
Comlink는 Node의 [`worker\_threads`][worker\_threads] 모듈과 함께 작동합니다. `docs` 폴더의 예시를 참고하세요.
[webworker]: https://developer.mozilla.org/en-US/docs/Web/API/Web\_Workers\_API
[umd]: https://github.com/umdjs/umd
[transferable]: https://developer.mozilla.org/en-US/docs/Web/API/Web\_Workers\_API/Transferable\_objects
[messageport]: https://developer.mozilla.org/en-US/docs/Web/API/MessagePort
[examples]: https://github.com/GoogleChromeLabs/comlink/tree/master/docs/examples
[dist]: https://github.com/GoogleChromeLabs/comlink/tree/master/dist
[delivrjs]: https://cdn.jsdelivr.net/
[es6 proxy]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global\_Objects/Proxy
[proxy-polyfill]: https://github.com/GoogleChrome/proxy-polyfill
[endpoint]: src/protocol.ts
[structured cloning]: https://developer.mozilla.org/en-US/docs/Web/API/Web\_Workers\_API/Structured\_clone\_algorithm
[structured clone table]: structured-clone-table.md
[event]: https://developer.mozilla.org/en-US/docs/Web/API/Event
[worker\_threads]: https://nodejs.org/api/worker\_threads.html
[weakref proposal]: https://github.com/tc39/proposal-weakrefs
## 추가 리소스
- [S

[Comlink으로 Web Worker 코드 간소화하기](https://davidea.st/articles/comlink-simple-web-worker)
---
License Apache-2.0