How do I use Clooney with a CDN without running into same-origin issues?

You need to fetch the worker script as a blob and create a Worker from it, as shown in the README's CDN example with newWorkerFunc. This bypasses same-origin restrictions by loading the worker locally from a blob URL.

What's better for my project: Clooney or writing vanilla Web Workers from scratch?

Clooney simplifies development with its class-based API and automatic communication handling, ideal for rapid prototyping. Vanilla Web Workers offer more control and potentially lower overhead for highly optimized, custom implementations.

Can Clooney actors manipulate the DOM or handle user interactions directly?

No, because Web Workers cannot access the DOM. Clooney provides remoteEvent objects to transfer event data (e.g., targetId, detail) so actors can react to events proxied from the main thread, but direct DOM access is impossible.

How do I pass callback functions to a Clooney actor?

Functions are not transferable, but Clooney allows binding actor methods to event listeners via remoteEvent objects. For other use cases, you may need to structure code to avoid passing functions directly, relying on the library's event handling.

What browsers support Clooney, and do I always need polyfills?

Clooney supports modern browsers with ES6 Proxy (Chrome 56+, Firefox 52+, etc.), as listed in the README. For older browsers, you must use proxy-polyfill, which adds complexity and may affect performance.

How can I clean up and terminate all workers when my app is done?

Call the terminate() method on your strategy instance, which will terminate all worker containers. This is part of the Strategy interface and helps manage resources, but you must handle it explicitly to avoid memory leaks.

clooney — Web Worker Actor Library

What is clooney?

Clooney is an actor library for the web that enables developers to run JavaScript classes in Web Workers without directly managing worker threads. It solves the problem of main thread blocking by offloading expensive computations to background threads, using Comlink under the hood for transparent communication. This allows for responsive web applications while maintaining a simple, class-based programming model.

Target Audience

Web developers building performance-sensitive applications that require offloading CPU-intensive tasks, such as data processing, image manipulation, or complex calculations, without diving into low-level Web Worker APIs.

Value Proposition

Developers choose Clooney because it dramatically simplifies concurrent programming on the web by abstracting Web Workers into an intuitive actor pattern, reducing boilerplate and eliminating common pitfalls in worker communication. Its integration with Comlink ensures reliable proxying and a seamless developer experience.

Clooney is an actor library for the web. Use workers without thinking about workers.

Use Cases

Best For

Offloading CPU-intensive calculations from the main thread in web apps
Implementing background processing for data-heavy operations without blocking UI
Building responsive web applications that require concurrent task execution
Simplifying Web Worker usage with a class-based abstraction layer
Handling events and functions across thread boundaries in a structured way
Managing multiple worker instances with configurable spawning strategies

Not Ideal For

Applications requiring direct DOM access or browser APIs within worker logic, as Web Workers run in an isolated context
Projects needing synchronous execution or real-time responsiveness, since all actor method calls are asynchronous via promises
Simple web apps with lightweight computations where worker management overhead outweighs performance benefits
Teams targeting browsers without ES6 Proxy support who are unwilling to add polyfills, due to Clooney's dependency on Proxies

Pros & Cons

Pros

Intuitive Actor Abstraction

Abstracts Web Workers into a class-based API, allowing developers to spawn actors in workers without managing threads directly, as demonstrated in the quickstart example with Clooney.spawn().

Seamless Async Handling

Automatically manages promises and async methods across thread boundaries, enabling natural asynchronous programming without extra boilerplate, shown in the timeoutThing() example.

Flexible Event Support

Provides special handling for events and functions by converting them into transferable remoteEvent objects, making cross-thread event handling possible, as detailed in the Events and Functions section.

Configurable Worker Strategies

Offers strategies like RoundRobinStrategy to control worker container creation and distribution, optimizing resource usage for concurrent tasks with options like maxNumContainers.

Cons

Scope Isolation Limitation

Actors cannot rely on their surrounding scope due to execution in isolated workers, restricting closure usage and requiring explicit data passing, as noted in the README caveat about ES6 module support.

Browser Compatibility Hurdles

Depends on ES6 Proxy support, requiring polyfills for older browsers, and CDN usage involves workarounds for same-origin restrictions, adding setup complexity as shown in the CDN example.

Performance Overhead from Proxying

Communication between main thread and workers involves proxying via Comlink, which can introduce latency compared to direct worker messaging for high-frequency or latency-sensitive tasks.

Frequently Asked Questions

What is clooney?

Target Audience

Value Proposition

Use Cases

Best For

Offloading CPU-intensive calculations from the main thread in web apps
Implementing background processing for data-heavy operations without blocking UI
Building responsive web applications that require concurrent task execution
Simplifying Web Worker usage with a class-based abstraction layer
Handling events and functions across thread boundaries in a structured way
Managing multiple worker instances with configurable spawning strategies

Not Ideal For

Applications requiring direct DOM access or browser APIs within worker logic, as Web Workers run in an isolated context
Projects needing synchronous execution or real-time responsiveness, since all actor method calls are asynchronous via promises
Simple web apps with lightweight computations where worker management overhead outweighs performance benefits
Teams targeting browsers without ES6 Proxy support who are unwilling to add polyfills, due to Clooney's dependency on Proxies

Pros & Cons

Pros

Intuitive Actor Abstraction

Abstracts Web Workers into a class-based API, allowing developers to spawn actors in workers without managing threads directly, as demonstrated in the quickstart example with Clooney.spawn().

Seamless Async Handling

Automatically manages promises and async methods across thread boundaries, enabling natural asynchronous programming without extra boilerplate, shown in the timeoutThing() example.

Flexible Event Support

Configurable Worker Strategies

Offers strategies like RoundRobinStrategy to control worker container creation and distribution, optimizing resource usage for concurrent tasks with options like maxNumContainers.

Cons

Scope Isolation Limitation

Browser Compatibility Hurdles

Depends on ES6 Proxy support, requiring polyfills for older browsers, and CDN usage involves workarounds for same-origin restrictions, adding setup complexity as shown in the CDN example.

Performance Overhead from Proxying

Communication between main thread and workers involves proxying via Comlink, which can introduce latency compared to direct worker messaging for high-frequency or latency-sensitive tasks.

Frequently Asked Questions

clooney

What is clooney?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions

Related Projects

Found a gem we're missing?

clooney

What is clooney?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions

Related Projects

Found a gem we're missing?