@jcubic/mitty 0.1.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,298 @@
+<h1 align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://github.com/jcubic/mitty/blob/master/.github/logo-dark.svg?raw=true" />
+    <source media="(prefers-color-scheme: light)" srcset="https://github.com/jcubic/mitty/blob/master/.github/logo-light.svg?raw=true" />
+    <img alt="Mitty Logo" src="https://github.com/jcubic/mitty/blob/master/.github/logo-light.svg?raw=true" height="500"/>
+  </picture>
+</h1>
+
+<div align="center">
+
+[![npm version](https://img.shields.io/npm/v/@jcubic/mitty.svg)](https://www.npmjs.com/package/@jcubic/mitty)
+[![github repo](https://img.shields.io/badge/github-repo-orange?logo=github)](https://github.com/jcubic/mitty)
+[![CI](https://github.com/jcubic/mitty/actions/workflows/ci.yml/badge.svg)](https://github.com/jcubic/mitty/actions/workflows/ci.yml)
+[![Coverage Status](https://coveralls.io/repos/github/jcubic/mitty/badge.svg)](https://coveralls.io/github/jcubic/mitty)
+[![LICENSE MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/jcubic/mitty/blob/master/LICENSE)
+
+</div>
+
+Use objects that only exist on the main thread — DOM nodes, jQuery objects, class
+instances with methods — from inside a Web Worker.
+
+A worker has no DOM, and `postMessage` cannot carry a DOM node, a jQuery object, or
+anything else that isn't structured-cloneable. Mitty leaves the real object on the main
+thread and puts a proxy in the worker. The proxy records property accesses and calls
+without touching the channel; the whole chain is replayed on the main thread when you
+await it.
+
+```js
+// inside a worker — no DOM here
+const $ = require('$');
+await $('#list').find('li').first().text(); // one message, not four
+```
+
+## Installation
+
+```bash
+npm install @jcubic/mitty
+```
+
+Or from a CDN, for a `<script>` tag or `importScripts()` — the build exposes a `Mitty`
+global:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@jcubic/mitty"></script>
+```
+
+## Quick start
+
+### Main thread
+
+```js
+import { Host } from '@jcubic/mitty';
+
+const modules = {
+  $: () => jQuery,
+  term: () => $('.terminal').terminal(),
+};
+
+const channel = new BroadcastChannel('my-app');
+
+const host = new Host({
+  channel,
+  resolve(name) {
+    if (Object.hasOwn(modules, name)) {
+      return modules[name]();
+    }
+    return null;
+  },
+  serialize(value) {
+    // a jQuery object wraps DOM nodes and cannot cross the channel —
+    // hand out a handle the worker can call methods on instead
+    if (value instanceof $.fn.init) {
+      return this.remote(value);
+    }
+    return value;
+  },
+});
+
+const worker = new Worker('./worker.js');
+```
+
+Only the names your `resolve()` answers are reachable. Everything else on the page stays
+invisible to the worker.
+
+### Worker
+
+With an `import` statement, in a worker started with `{ type: 'module' }`:
+
+```js
+import { connect } from '@jcubic/mitty';
+
+const { require } = connect(new BroadcastChannel('my-app'));
+
+const $ = require('$');
+await $('.terminal').terminal().echo('Hello from a worker');
+```
+
+Or with `importScripts()`, in a classic worker:
+
+```js
+importScripts('https://cdn.jsdelivr.net/npm/@jcubic/mitty');
+
+const { require } = Mitty.connect(new BroadcastChannel('my-app'));
+```
+
+## One channel per worker
+
+Both ends take a channel rather than creating one, so you decide what the two sides talk
+over and how many conversations there are. Request ids are per connection and start at 1,
+so two workers sharing a channel name will see each other's replies and resolve the wrong
+calls. Give every worker its own channel:
+
+```js
+let seq = 0;
+
+function spawn(url) {
+  const name = `my-app-${++seq}`;
+  const host = new Host({ channel: new BroadcastChannel(name), resolve, serialize });
+  const worker = new Worker(url);
+  worker.postMessage({ channel: name }); // tell the worker which one to join
+  return { host, worker };
+}
+```
+
+A channel is never closed by this library — whoever created it owns it.
+
+## How a chain becomes one message
+
+`$('#list').find('li').first().text()` does not talk to the main thread four times. Each
+step appends to a list of operations held in the worker:
+
+```js
+[
+  { type: 'call', args: ['#list'] },
+  { type: 'get', key: 'find' },
+  { type: 'call', args: ['li'] },
+  // ...
+];
+```
+
+Nothing is sent until the chain is awaited — that is the only point at which the proxy
+becomes a real thenable. The host then walks the whole list against the resolved module
+and sends back the final value.
+
+A consequence worth knowing: a proxy you have not awaited is not a promise, and a bare
+handle is not one either. Both are inert until you chain something onto them and await.
+
+## Handles and memory
+
+Anything `serialize()` turns into a handle with `this.remote(value)` is kept alive on the
+main thread until it is released. There is no automatic collection — a handle is a plain
+integer on the wire, and the host cannot see when the worker drops its proxy.
+
+Release explicitly when you are done:
+
+```js
+const list = await $('#list');
+// ... use it ...
+release(list);
+```
+
+If you would rather tie it to garbage collection, a `FinalizationRegistry` can do it —
+but the callback must not capture the proxy, or the proxy will never become unreachable
+and the callback will never run. Register the numeric id instead, which is what
+`handle()` is for:
+
+```js
+const client = connect(channel);
+const registry = new FinalizationRegistry(id => client.release(id));
+
+function tracked(remote) {
+  registry.register(remote, client.handle(remote));
+  return remote;
+}
+
+const list = tracked(await $('#list'));
+// when `list` becomes unreachable, the host is told to drop it
+```
+
+Collection timing is not guaranteed, so this is a safety net rather than a replacement
+for releasing things you know you are finished with.
+
+## Callbacks
+
+A function passed from the worker stays in the worker. The host receives a stub that
+returns a promise; calling it runs the real function back in the worker:
+
+```js
+// worker
+const result = await require('util').map([1, 2, 3], n => n * 2);
+// -> [2, 4, 6], with the doubling done in the worker
+```
+
+Arguments are trimmed to the callback's declared arity, because callers like jQuery pass
+extras (event objects, indexes) that usually cannot be serialized. Declare the parameters
+you actually want.
+
+## Errors
+
+Errors cross the channel with their `name`, `message` and the host's `stack`, and arrive
+as real `Error` instances:
+
+```js
+try {
+  await $('#list').nosuchmethod();
+} catch (error) {
+  error instanceof Error; // true
+  error.message; // "mitty: $().nosuchmethod is not a function"
+}
+```
+
+## API
+
+### `new Host(options)`
+
+| option        | type                 | description                                                                                  |
+| ------------- | -------------------- | -------------------------------------------------------------------------------------------- |
+| `channel`     | `Channel`            | Transport to listen on. Required. Never closed by mitty.                                     |
+| `resolve`     | `(name) => unknown`  | Turns a `require()` name into a value. Return `null`/`undefined` for unknown. May be async.  |
+| `serialize`   | `(value) => unknown` | Called for every outgoing value. Return `this.remote(value)` for anything JSON cannot carry. |
+| `unserialize` | `(value) => unknown` | Called for every incoming value.                                                             |
+
+`serialize` and `unserialize` are called with the host as `this`.
+
+- **`host.remote(value)`** — register `value` and return a handle marker. Call this from
+  `serialize()`.
+- **`host.release(handle)`** — drop a handle, by marker or by id. Returns `false` if it
+  was already gone.
+- **`host.close()`** — stop listening and forget every handle.
+
+### `connect(channel)`
+
+Returns a client:
+
+- **`require(name)`** — a proxy rooted at whatever the host's `resolve()` returns.
+- **`handle(remote)`** — the numeric id behind a handle proxy.
+- **`release(remote)`** — tell the host to drop it, by proxy or by id.
+- **`close()`** — stop listening. The channel stays open.
+
+### `Channel`
+
+Any object with these three members works — a `BroadcastChannel`, a `MessagePort`
+wrapper, or a stub in tests:
+
+```ts
+interface Channel {
+  postMessage(message: string): void;
+  addEventListener(type: 'message', listener: (event: { data: string }) => void): void;
+  removeEventListener(type: 'message', listener: (event: { data: string }) => void): void;
+}
+```
+
+Messages on the wire are JSON strings, so a channel only has to carry text.
+
+## Limitations
+
+- **Values must survive JSON.** Anything else needs a handle via `serialize()`. Circular
+  structures fail the call that would return them.
+- **`{ type, data }` is reserved.** Functions, handles and errors travel as objects of
+  that exact shape. An application object that looks identical would be mistaken for one.
+- **Functions returned from the host are dropped**, as they would be by `JSON.stringify`.
+  Expose them through a handle instead.
+- **Handles are not garbage collected** — see [Handles and memory](#handles-and-memory).
+
+## Example
+
+A runnable page that drives jQuery from a worker, in both the `importScripts` and
+`import` styles, lives in
+[`example/`](https://github.com/jcubic/mitty/tree/master/example):
+
+```bash
+npm install
+npm run build
+npx serve .
+```
+
+then open `/example/`.
+
+## Development
+
+```bash
+npm test          # unit tests
+npm run coverage  # tests with coverage
+npm run lint      # eslint
+npm run build     # ESM + IIFE + .d.ts into dist/
+```
+
+## Origin
+
+The first idea for the mechanism was created for [Hacking Cafe](https://hacking.cafe), a Unix-like environment in the browser. It was then extracted into an NPM library. The name and logo were based on a fictional "Life" magazine worker named [Waleter Mitty](https://en.wikipedia.org/wiki/Walter_Mitty) from the movie ["The Secret Life of Walter Mitty"](<https://en.wikipedia.org/wiki/The_Secret_Life_of_Walter_Mitty_(2013_film)>).
+
+A similar RPC mechanism was created in [Wayne library](https://github.com/jcubic/wayne).
+
+## License
+
+Copyright (c) 2026 [Jakub T. Jankiewicz](https://jakub.jankiewicz.org/)
+
+Released under the MIT License. See [LICENSE](https://github.com/jcubic/mitty/blob/master/LICENSE) for details.

package/dist/index.d.ts

@@ -0,0 +1,71 @@
+interface ChannelEvent {
+    data: string;
+}
+type ChannelListener = (event: ChannelEvent) => void;
+interface Channel {
+    postMessage(message: string): void;
+    addEventListener(type: 'message', listener: ChannelListener): void;
+    removeEventListener(type: 'message', listener: ChannelListener): void;
+}
+interface FunctionMarker {
+    type: 'function';
+    data: [id: number, length: number];
+}
+interface ObjectMarker {
+    type: 'object';
+    data: [id: number];
+}
+interface ErrorMarker {
+    type: 'error';
+    data: [name: string, message: string, stack: string | null];
+}
+type Marker = FunctionMarker | ObjectMarker | ErrorMarker;
+type Op = {
+    type: 'get';
+    key: string;
+} | {
+    type: 'call';
+    args: unknown[];
+};
+interface Remote {
+    (...args: any[]): Remote;
+    then<R1 = any, R2 = never>(onfulfilled?: ((value: any) => R1 | PromiseLike<R1>) | null, onrejected?: ((reason: any) => R2 | PromiseLike<R2>) | null): Promise<R1 | R2>;
+    [key: string]: any;
+}
+interface Client {
+    require(name: string): Remote;
+    handle(remote: unknown): number;
+    release(remote: unknown | number): void;
+    close(): void;
+}
+
+interface HostOptions {
+    channel: Channel;
+    resolve(name: string): unknown;
+    serialize?(this: Host, value: unknown): unknown;
+    unserialize?(this: Host, value: unknown): unknown;
+}
+declare class Host {
+    private _options;
+    private _channel;
+    private _listener;
+    private _objects;
+    private _object_id;
+    private _pending;
+    private _call_id;
+    constructor(options: HostOptions);
+    remote(value: unknown): ObjectMarker;
+    release(handle: ObjectMarker | number): boolean;
+    close(): void;
+    private _post;
+    private _serialize;
+    private _unserialize;
+    private _callback;
+    private _on_message;
+    private _invoke;
+    private _root;
+}
+
+declare function connect(channel: Channel): Client;
+
+export { type Channel, type ChannelEvent, type ChannelListener, type Client, type ErrorMarker, type FunctionMarker, Host, type HostOptions, type Marker, type ObjectMarker, type Op, type Remote, connect };