@fcanvas/communicate

This package allows a simple connection between MessageChannel-based channels such as WebWorker, IFrame...

View source code at: https://github.com/fcanvas/fcanvas

Install

bash

pnpm add @fcanvas/communicate

Usage

With `MessageChannel`

// listen run function
import { listen } from "@fcanvas/communicate"

const { port1, port2 } = new MessageChannel()
port1.start()
port2.start()

listen(port1, "hello world", (name: string) => {
  console.log(`run: hello world '${name}'`)

  return "run done"
})

// call function
import { put } from "@fcanvas/communicate"
console.log(await put(port2, "hello world", "Shin")) // "run done"

With `WebWorker`

worker.tsmain.ts

import { listen } from "@fcanvas/communicate"

listen(self, "hello world", (name: string) => {
  console.log(`run: hello world '${name}'`)

  return "run done"
})

import Worker from "./worker?worker"
import { put } from "@fcanvas/communicate"

const worker = new Worker()

console.log(await put(worker, "hello world", "Shin")) // "run done"

2-way use

You can use both ways set listen to Worker or Threat

worker.tsmain.ts

import { listen } from "@fcanvas/communicate"

listen(self, "hello world", async (name: string) => {
  console.log(`run: hello world '${name}'`)

  console.log("input: ", await put(self, "get input"))

  return "run done"
})

import Worker from "./worker?worker"
import { put } from "@fcanvas/communicate"

const worker = new Worker()
listen(worker, "get input", () => {
  return document.querySelector("#input").value
})

console.log(await put(worker, "hello world", "Shin")) // "run done"

Docs

@fcanvas/communicate provides 3 methods that can be used anywhere

`listen`

This function to listen and process calls from put and pit - like is server

function listen(
  port: LikeMessagePort, // current port to listen and process. Example `self` in `worker`
  name: string, // the name of the listen
  cb: Function, // its handler function takes a sequence of `arguments` passed from `put` or `pit` and returns a result either a `config` or a `promise`
  options?: {
    once?: boolean // if this option is enabled the listener will self-destruct after being called once by `put` or `pit`
  }
): StopListen /** @type () => void */

Name	Type	Description
port	LikeMessagePort	Current port to listen and process. Example `self` in `worker`
name	string	The name of the listen
cb	Function	Its handler function takes a sequence of `arguments` passed from `put` or `pit` and returns a result either a `config` or a `Promise`
options	`{ once?: boolean }`	if `once: true` is enabled the listener will self-destruct after being called once by `put` or `pit`

cb normally returns primitive values but if it returns a value that needs transfer like Offscreen or ArrayBuffer return an Options

interface Options {
  return: any // your value return
  transfer?: Transferable[] // value transfer
  targetOrigin?: string // This option is only available if communicating with `IFrame`
}

listen(self, "get buffer", async () => {
  const buffer = new Uint8Array([1, 0xf, 0x3]).buffer
  return {
    return: buffer,
    transfer: [buffer]
  }
})

listen returns a noop function that, when called, cancels listening

`put`

This function sends a request to listen and returns a promise that is the result of cb of listen - like is client

function put<Fn extends (...args: any[]) => any>(
  port: LikeMessagePort, // current port to listen and process. Example `self` in `worker`
  name: string, // name of call
  ...args: Parameters<Fn>
): Promise<ReturnType<Fn>>

function put<Fn extends (...args: any[]) => any>(
  port: LikeMessagePort, // current port to listen and process. Example `self` in `worker`
  options: {
    name: string // name of call
    timeout?: number // timeout
    signal?: AbortSignal // controller
    transfer?: Transferable[] // value transfer
    targetOrigin?: string // This option is only available if communicating with `IFrame`
  },
  ...args: Parameters<Fn>
): Promise<ReturnType<Fn>>

Name	Type	Description
port	LikeMessagePort	Current port to listen and process. Example `self` in `worker`
name	string	name of call
options.name	string	is like `name`
options.timeout	number?	timeout `listen` returns a result. if timeout without response will generate error `Error('timeout')`
options.signal	AbortSignal?	if canceled the function will generate an error `Error('aborted')`
options.transfer	Transferable[]?	values to `transfer`
options.targetOrigin	string?	This option is only available if communicating with `IFrame`
...args	any[]	values to send to `listen`

put returns the value that cb of listen returns

`pit` (as `ping`)

This is a shortened function of put that takes no response. it also doesn't care if the call has been sent to listen or not

The options of this function are identical to put except that it does not accept options.timeout, option.signal and returns nothing.

TypeScript

This plugin also supports TypeScript strong and weak type inference

Weak inference with function:

interface FnHello {
  (name: string): string
}

listen<FnHello>(self, "hello", (name /** @type string */) => {
  return "done" /** @type string */
})

put<FnHello>(self, "hello", "Shin") // ✔ ok
put<FnHello>(self, "hello", 0) // ❗ error

Strong inference with Record:

interface Connect {
  hello(name: string): void
}

listen<Connect>("self", "hello", () => {}) // ✔ ok
listen<Connect>("self", "hellx", () => {}) // ❗ error

put<Connect>(self, "hello", "Shin") // ✔ ok
put<Connect>(self, "hello", 0) // ❗ error
put<Connect>(self, "hello") // ❗ error
put<Connect>(self, "hellx", "Shin") // ❗ error

@fcanvas/communicate #

Install #

Usage #

With MessageChannel #

With WebWorker #

2-way use #

Docs #

listen #

put #

pit (as ping) #

TypeScript #

Copyright #