Universal TypeScript library for effortless parallel computing across all JavaScript ecosystems
npm install threadts-universaltypescript
import threadts from 'threadts-universal';
// Transform any function into parallel execution with one line
const result = await threadts.run((x) => x * 2, 42);
console.log(result); // 84
// Full Array API support with parallel execution
const found = await threadts.find([1, 2, 3, 4, 5], (x) => x > 3);
console.log(found); // 4
`
✨ Features
$3
- Single-line API: await threadts.run(fn, data) → instant parallel execution
- Zero-Config: Intelligent defaults with infinite customization layers
- Quantum Performance: Sub-5ms overhead vs handwritten worker wrappers
$3
- Browser: Web Workers, OffscreenCanvas, Transferable Objects
- Node.js: Worker Threads, Cluster Mode, Native Addons
- Deno: Web Workers with permissions sandboxing
- Bun: Optimized worker implementation
- Identical API: Same code works everywhere
$3
- Auto-scaling Pools: From 1 to ∞ workers based on load
- Full Array API: map, filter, reduce, reduceRight, find, findIndex, some, every, forEach, flatMap, groupBy, partition, count, indexOf, lastIndexOf, at, slice, concat, range, repeat, unique, uniqueBy, chunk, zip
- ES2023+ Immutable Methods: findLast, findLastIndex, toSorted, toReversed, withElement, toSpliced, groupByObject - all methods that don't mutate the original array
- Enhanced Pipeline API: Fluent chaining with lazy evaluation
- Intermediate: map, filter, flatMap, take, skip, chunk, tap, peek, window, unique, distinct, reverse, sort, zip, zipWith, interleave, compact, flatten, shuffle, sample, dropWhile, takeWhile, slicePipe, concatPipe, rotate, truthy, falsy
- Terminal: reduce, forEach, find, findIndex, findLast, findLastIndex, some, every, count, groupBy, partition, first, last, isEmpty, sum, average, min, max, join, includes
- Collectors: toArray(), toSet(), toMap()
- Progress Tracking: Real-time progress monitoring
- Intelligent Caching: Automatic result caching with @memoize and @cache decorators
- Priority Queues: High/Normal/Low priority execution
- Timeout & Cancellation: AbortController integration
- Decorator Suite: @parallelMethod(), @retry(), @rateLimit(), @timeout(), @debounce(), @throttle(), @logged(), @cache(), @concurrent(), @circuitBreaker(), @measure(), @validate(), @lazy()
- Custom Decorators: Utilities for creating your own decorators (createMethodDecorator, createMethodDecoratorWithClass, createClassDecorator)
- Monitoring: Built-in performance monitoring, health checks, and error handling
🚀 Quick Start
$3
`bash
npm install threadts-universal
`
$3
`typescript
import threadts from 'threadts-universal';
// Simple parallel execution
const doubled = await threadts.run((x) => x * 2, 21);
// Complex calculations
const fibonacci = await threadts.run((n) => {
if (n <= 1) return n;
let a = 0,
b = 1;
for (let i = 2; i <= n; i++) {
[a, b] = [b, a + b];
}
return b;
}, 40);
// Parallel array processing
const squares = await threadts.map([1, 2, 3, 4, 5], (x) => x * x);
// Result: [1, 4, 9, 16, 25]
// Find elements in parallel
const firstMatch = await threadts.find([1, 2, 3, 4, 5], (x) => x > 3);
// Result: 4
// Check conditions across array
const hasEven = await threadts.some([1, 3, 5, 6], (x) => x % 2 === 0);
// Result: true
// Group and partition data
const [evens, odds] = await threadts.partition(
[1, 2, 3, 4, 5],
(x) => x % 2 === 0
);
// evens: [2, 4], odds: [1, 3, 5]
// Pipeline API for chained operations
const result = await threadts
.pipe([1, 2, 3, 4, 5])
.map((x) => x * 2)
.filter((x) => x > 4)
.reduce((acc, x) => acc + x, 0)
.execute();
// Result: 24
`
$3
`typescript
import {
parallelMethod,
memoize,
retry,
rateLimit,
timeout,
debounce,
} from 'threadts-universal';
class DataProcessor {
@parallelMethod()
async processLargeDataset(data: number[]): Promise {
return data.map((x) => x x x);
}
@parallelMethod({ timeout: 5000, priority: 'high' })
async criticalCalculation(input: ComplexData): Promise {
// Heavy computation automatically runs in worker
return heavyProcessing(input);
}
@memoize(100) // Cache up to 100 results
async expensiveComputation(input: string): Promise {
return computeResult(input);
}
@retry(3, 1000) // 3 attempts with exponential backoff
async unreliableOperation(): Promise {
await callExternalService();
}
@rateLimit(10) // Max 10 calls per second
async rateLimitedAPI(): Promise {
return fetchFromAPI();
}
}
`
📚 API Reference
$3
#### threadts.run
Executes a function in a worker thread.
`typescript
const result = await threadts.run(
(data: { x: number; y: number }) => data.x + data.y,
{ x: 10, y: 20 },
{
timeout: 5000,
priority: 'high',
transferable: [], // For transferable objects
}
);
`
#### threadts.parallel
Executes multiple functions in parallel.
`typescript
const results = await threadts.parallel([
{ fn: (x) => x * 2, data: 5 },
{ fn: (x) => x * 3, data: 7 },
{ fn: (x) => x * 4, data: 9 },
]);
// Results: [10, 21, 36]
`
#### threadts.map
Maps an array through a function in parallel.
`typescript
const results = await threadts.map(
[1, 2, 3, 4, 5],
(x, index) => ({ value: x * x, index }),
{ batchSize: 2 }
);
`
#### threadts.filter
Filters an array in parallel.
`typescript
const evens = await threadts.filter(
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
(x) => x % 2 === 0
);
`
#### threadts.reduce
Reduces an array in parallel (for associative operations).
`typescript
const sum = await threadts.reduce(
[1, 2, 3, 4, 5],
(acc, curr) => acc + curr,
0
);
`
#### threadts.reduceRight
Reduces an array from right to left.
`typescript
const result = await threadts.reduceRight(
['a', 'b', 'c'],
(acc, item) => acc + item,
''
);
// Result: 'cba'
`
#### threadts.find
Finds the first element that satisfies the predicate (processes in parallel batches).
`typescript
const found = await threadts.find([1, 2, 3, 4, 5], (x) => x > 3);
// Result: 4
`
#### threadts.findIndex
Finds the index of the first element that satisfies the predicate.
`typescript
const index = await threadts.findIndex([1, 2, 3, 4, 5], (x) => x > 3);
// Result: 3
`
#### threadts.some
Tests whether at least one element satisfies the predicate.
`typescript
const hasEven = await threadts.some([1, 3, 5, 6, 7], (x) => x % 2 === 0);
// Result: true
`
#### threadts.every
Tests whether all elements satisfy the predicate.
`typescript
const allPositive = await threadts.every([1, 2, 3, 4, 5], (x) => x > 0);
// Result: true
`
#### threadts.forEach
Iterates over an array in parallel (like Array.forEach but parallel).
`typescript
await threadts.forEach([1, 2, 3], (x) => {
console.log(x);
});
`
#### threadts.flatMap
Maps each element to an array and flattens the result.
`typescript
const result = await threadts.flatMap([1, 2, 3], (x) => [x, x * 2]);
// Result: [1, 2, 2, 4, 3, 6]
`
#### threadts.groupBy
Groups array elements by a key returned from the function.
`typescript
const grouped = await threadts.groupBy(
[
{ type: 'a', value: 1 },
{ type: 'b', value: 2 },
{ type: 'a', value: 3 },
],
(item) => item.type
);
// Map { 'a' => [{type: 'a', value: 1}, {type: 'a', value: 3}], 'b' => [{type: 'b', value: 2}] }
`
#### threadts.partition
Partitions an array into two arrays based on a predicate.
`typescript
const [evens, odds] = await threadts.partition(
[1, 2, 3, 4, 5],
(x) => x % 2 === 0
);
// evens: [2, 4], odds: [1, 3, 5]
`
#### threadts.count
Counts elements that satisfy a predicate. More efficient than filter().length.
`typescript
const count = await threadts.count([1, 2, 3, 4, 5], (x) => x > 2);
// Result: 3
`
$3
ThreadTS Universal provides a comprehensive set of array operations beyond the standard JavaScript Array API. These operations are optimized for parallel execution and can be accessed both as instance methods and through the getArrayOps() factory.
#### threadts.indexOf
Finds the first index of an element in the array.
`typescript
const index = await threadts.indexOf([1, 2, 3, 2, 1], 2);
// Result: 1
const indexFrom = await threadts.indexOf([1, 2, 3, 2, 1], 2, 2);
// Result: 3
`
#### threadts.lastIndexOf
Finds the last index of an element in the array.
`typescript
const index = await threadts.lastIndexOf([1, 2, 3, 2, 1], 2);
// Result: 3
`
#### threadts.at
Returns the element at the specified index, supporting negative indices.
`typescript
const last = await threadts.at([1, 2, 3, 4, 5], -1);
// Result: 5
const second = await threadts.at([1, 2, 3, 4, 5], 1);
// Result: 2
`
#### threadts.slice
Extracts a section of the array.
`typescript
const middle = await threadts.slice([1, 2, 3, 4, 5], 1, 4);
// Result: [2, 3, 4]
const fromEnd = await threadts.slice([1, 2, 3, 4, 5], -2);
// Result: [4, 5]
`
#### threadts.concat
Concatenates arrays or values.
`typescript
const combined = await threadts.concat([1, 2], [3, 4], 5);
// Result: [1, 2, 3, 4, 5]
`
#### threadts.range(start, end, step?, options?): Promise
Generates an array of numbers in a specified range.
`typescript
const numbers = await threadts.range(0, 10, 2);
// Result: [0, 2, 4, 6, 8]
const countdown = await threadts.range(5, 0, -1);
// Result: [5, 4, 3, 2, 1]
`
#### threadts.repeat
Creates an array with the value repeated n times.
`typescript
const repeated = await threadts.repeat('x', 5);
// Result: ['x', 'x', 'x', 'x', 'x']
`
#### threadts.unique
Returns an array with duplicate values removed.
`typescript
const unique = await threadts.unique([1, 2, 2, 3, 3, 3]);
// Result: [1, 2, 3]
`
#### threadts.uniqueBy
Returns unique elements based on a key function.
`typescript
const users = [
{ id: 1, name: 'Alice' },
{ id: 2, name: 'Bob' },
{ id: 1, name: 'Alice Clone' },
];
const uniqueById = await threadts.uniqueBy(users, (u) => u.id);
// Result: [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }]
`
#### threadts.chunk
Splits an array into chunks of the specified size.
`typescript
const chunks = await threadts.chunk([1, 2, 3, 4, 5], 2);
// Result: [[1, 2], [3, 4], [5]]
`
#### threadts.zip
Combines two arrays element-wise into pairs.
`typescript
const zipped = await threadts.zip(['a', 'b', 'c'], [1, 2, 3]);
// Result: [['a', 1], ['b', 2], ['c', 3]]
`
$3
ThreadTS Universal provides full support for ES2023+ immutable array methods. These methods return new arrays instead of mutating the original, making them ideal for functional programming patterns.
#### threadts.findLast
Finds the last element that satisfies the predicate (searches from end).
`typescript
const result = await threadts.findLast([1, 2, 3, 4, 5], (x) => x < 4);
// Result: 3 (the last number less than 4)
const noMatch = await threadts.findLast([1, 2, 3], (x) => x > 10);
// Result: undefined
`
#### threadts.findLastIndex
Finds the index of the last element that satisfies the predicate.
`typescript
const index = await threadts.findLastIndex([1, 2, 3, 2, 1], (x) => x === 2);
// Result: 3 (the last occurrence of 2)
const notFound = await threadts.findLastIndex([1, 2, 3], (x) => x > 10);
// Result: -1
`
#### threadts.toSorted
Returns a new sorted array without mutating the original.
`typescript
const original = [3, 1, 4, 1, 5];
const sorted = await threadts.toSorted(original);
// sorted: [1, 1, 3, 4, 5]
// original: [3, 1, 4, 1, 5] (unchanged!)
// With custom comparator (descending)
const descending = await threadts.toSorted([3, 1, 4], (a, b) => b - a);
// Result: [4, 3, 1]
`
#### threadts.toReversed
Returns a new reversed array without mutating the original.
`typescript
const original = [1, 2, 3];
const reversed = await threadts.toReversed(original);
// reversed: [3, 2, 1]
// original: [1, 2, 3] (unchanged!)
`
#### threadts.withElement
Returns a new array with the element at the given index replaced.
`typescript
const original = [1, 2, 3];
const updated = await threadts.withElement(original, 1, 10);
// updated: [1, 10, 3]
// original: [1, 2, 3] (unchanged!)
// Supports negative indices
const lastReplaced = await threadts.withElement([1, 2, 3], -1, 99);
// Result: [1, 2, 99]
`
#### threadts.toSpliced
Returns a new array with elements removed, replaced, or added at a given index.
`typescript
const original = [1, 2, 3, 4];
// Remove and insert
const spliced = await threadts.toSpliced(original, 1, 2, 10, 20);
// spliced: [1, 10, 20, 4]
// original: [1, 2, 3, 4] (unchanged!)
// Delete only
const deleted = await threadts.toSpliced([1, 2, 3, 4], 1, 2);
// Result: [1, 4]
// Insert only
const inserted = await threadts.toSpliced([1, 2, 3], 1, 0, 99);
// Result: [1, 99, 2, 3]
`
#### threadts.groupByObject
Groups elements into a plain object based on a key function (similar to Object.groupBy).
`typescript
const items = [
{ type: 'fruit', name: 'apple' },
{ type: 'vegetable', name: 'carrot' },
{ type: 'fruit', name: 'banana' },
];
const grouped = await threadts.groupByObject(items, (item) => item.type);
// Result: {
// fruit: [{ type: 'fruit', name: 'apple' }, { type: 'fruit', name: 'banana' }],
// vegetable: [{ type: 'vegetable', name: 'carrot' }]
// }
`
#### Using the Array Operations Factory
For advanced use cases, you can access all array operations through the factory:
`typescript
// Get array operations bound to the current ThreadTS instance
const arrayOps = threadts.getArrayOps();
// Use operations directly
const index = await arrayOps.indexOf([1, 2, 3], 2);
const unique = await arrayOps.unique([1, 1, 2, 2, 3]);
const chunks = await arrayOps.chunk([1, 2, 3, 4, 5, 6], 2);
// ES2023+ operations
const sorted = await arrayOps.toSorted([3, 1, 2]);
const reversed = await arrayOps.toReversed([1, 2, 3]);
const lastMatch = await arrayOps.findLast([1, 2, 3, 2], (x) => x === 2);
// Available operations:
// indexOf, lastIndexOf, at, slice, concat, fill, includes, join,
// reverse, sort, range, repeat, zip, unzip, unique, uniqueBy, flat, chunk,
// findLast, findLastIndex, toSorted, toReversed, withElement, toSpliced, groupByObject
`
#### threadts.batch(tasks, batchSize?): Promise
Executes multiple tasks as a batch with configurable batch size.
`typescript
const results = await threadts.batch(
[
{ fn: (x) => x * 2, data: 5 },
{ fn: (x) => x + 1, data: 10 },
],
2 // Process 2 tasks at a time
);
`
$3
The Pipeline API provides a fluent interface for chaining parallel operations with lazy evaluation.
`typescript
// Chain multiple operations
const result = await threadts
.pipe([1, 2, 3, 4, 5])
.map((x) => x * 2)
.filter((x) => x > 4)
.reduce((acc, x) => acc + x, 0)
.execute();
// Result: 24 (6 + 8 + 10)
// Using flatMap in pipeline
const flattened = await threadts
.pipe([1, 2, 3])
.flatMap((x) => [x, x * 10])
.filter((x) => x > 5)
.toArray();
// Result: [10, 20, 30]
// Terminal operations: reduce, forEach, find, some, every, count
const hasLarge = await threadts
.pipe([1, 2, 3, 4, 5])
.map((x) => x * 2)
.some((x) => x > 8)
.execute();
// Result: true
// Using take, skip, and chunk
const paginated = await threadts
.pipe([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
.skip(2)
.take(5)
.execute();
// Result: [3, 4, 5, 6, 7]
const chunks = await threadts.pipe([1, 2, 3, 4, 5]).chunk(2).execute();
// Result: [[1, 2], [3, 4], [5]]
// Using tap for debugging/side-effects
const result = await threadts
.pipe([1, 2, 3])
.tap((x) => console.log('Processing:', x))
.map((x) => x * 2)
.execute();
// Logs: Processing: 1, Processing: 2, Processing: 3
// Result: [2, 4, 6]
// Using window for sliding windows
const windows = await threadts.pipe([1, 2, 3, 4, 5]).window(3).execute();
// Result: [[1, 2, 3], [2, 3, 4], [3, 4, 5]]
const windowsWithStep = await threadts
.pipe([1, 2, 3, 4, 5, 6])
.window(2, 2) // size=2, step=2
.execute();
// Result: [[1, 2], [3, 4], [5, 6]]
// Using unique, reverse, and sort
const processed = await threadts
.pipe([3, 1, 2, 1, 3])
.unique()
.sort((a, b) => a - b)
.execute();
// Result: [1, 2, 3]
// Aggregation operations
const sum = await threadts.pipe([1, 2, 3, 4, 5]).sum().execute();
// Result: 15
const avg = await threadts.pipe([1, 2, 3, 4, 5]).average().execute();
// Result: 3
const max = await threadts.pipe([3, 1, 4, 1, 5]).max().execute();
// Result: 5
// First and last elements
const first = await threadts
.pipe([1, 2, 3])
.filter((x) => x > 1)
.first()
.execute();
// Result: 2
// Collect to different data structures
const set = await threadts.pipe([1, 2, 2, 3]).toSet();
// Result: Set { 1, 2, 3 }
const map = await threadts.pipe(users).toMap((user) => user.id);
// Result: Map { id1 => user1, id2 => user2, ... }
// GroupBy and Partition in pipeline
const grouped = await threadts
.pipe(users)
.groupBy((user) => user.role)
.execute();
// Result: Map { 'admin' => [...], 'user' => [...] }
const [admins, regular] = await threadts
.pipe(users)
.partition((user) => user.role === 'admin')
.execute();
`
#### New Pipeline Operations (v2.1.0+)
`typescript
// Distinct - remove duplicates by key
const items = [{ id: 1 }, { id: 2 }, { id: 1 }, { id: 3 }];
const uniqueById = await threadts
.pipe(items)
.distinct((item) => item.id)
.execute();
// Result: [{ id: 1 }, { id: 2 }, { id: 3 }]
// Zip - combine two arrays element-wise
const names = ['Alice', 'Bob', 'Charlie'];
const ages = [25, 30, 35];
const zipped = await threadts.pipe(names).zip(ages).execute();
// Result: [['Alice', 25], ['Bob', 30], ['Charlie', 35]]
// ZipWith - combine with a custom function
const combined = await threadts
.pipe(names)
.zipWith(ages, (name, age) => ${name} is ${age})
.execute();
// Result: ['Alice is 25', 'Bob is 30', 'Charlie is 35']
// Interleave - alternate elements from two arrays
const letters = ['a', 'b', 'c'];
const numbers = [1, 2, 3];
const interleaved = await threadts.pipe(letters).interleave(numbers).execute();
// Result: ['a', 1, 'b', 2, 'c', 3]
// Compact - remove null and undefined values
const sparse = [1, null, 2, undefined, 3];
const compacted = await threadts.pipe(sparse).compact().execute();
// Result: [1, 2, 3]
// Flatten - flatten nested arrays
const nested = [[1, 2], [3, 4], [5]];
const flattened = await threadts.pipe(nested).flatten().execute();
// Result: [1, 2, 3, 4, 5]
const deepNested = [[[1]], [[2]], [[3]]];
const deepFlattened = await threadts.pipe(deepNested).flatten(2).execute();
// Result: [1, 2, 3]
// Shuffle - randomly shuffle elements
const ordered = [1, 2, 3, 4, 5];
const shuffled = await threadts.pipe(ordered).shuffle().execute();
// Result: [3, 1, 5, 2, 4] (random order)
// Sample - get random sample of n elements
const sampled = await threadts.pipe(ordered).sample(3).execute();
// Result: [2, 4, 1] (3 random elements)
// DropWhile - drop elements while predicate is true
const sequence = [1, 2, 3, 10, 4, 5];
const dropped = await threadts
.pipe(sequence)
.dropWhile((x) => x < 5)
.execute();
// Result: [10, 4, 5]
// TakeWhile - take elements while predicate is true
const taken = await threadts
.pipe(sequence)
.takeWhile((x) => x < 5)
.execute();
// Result: [1, 2, 3]
// Peek - debug helper (alias for tap)
const peeked = await threadts
.pipe([1, 2, 3])
.peek((x) => console.log('Value:', x))
.map((x) => x * 2)
.execute();
// Logs: Value: 1, Value: 2, Value: 3
// Result: [2, 4, 6]
// Join - join elements into string (terminal)
const sentence = await threadts.pipe(['Hello', 'World']).join(' ').execute();
// Result: 'Hello World'
// Includes - check if element exists (terminal)
const hasThree = await threadts.pipe([1, 2, 3, 4]).includes(3).execute();
// Result: true
// SlicePipe - extract a portion of the array
const sliced = await threadts.pipe([1, 2, 3, 4, 5]).slicePipe(1, 4).execute();
// Result: [2, 3, 4]
// ConcatPipe - concatenate with another array
const concatenated = await threadts
.pipe([1, 2])
.concatPipe([3, 4, 5])
.execute();
// Result: [1, 2, 3, 4, 5]
// Rotate - rotate array elements by n positions
const rotatedRight = await threadts.pipe([1, 2, 3, 4, 5]).rotate(2).execute();
// Result: [4, 5, 1, 2, 3]
const rotatedLeft = await threadts.pipe([1, 2, 3, 4, 5]).rotate(-2).execute();
// Result: [3, 4, 5, 1, 2]
// Truthy - filter to only truthy values
const truthyOnly = await threadts
.pipe([0, 1, '', 'hello', null, true, false])
.truthy()
.execute();
// Result: [1, 'hello', true]
// Falsy - filter to only falsy values
const falsyOnly = await threadts
.pipe([0, 1, '', 'hello', null, true, false])
.falsy()
.execute();
// Result: [0, '', null, false]
`
$3
#### Progress Tracking
`typescript
const result = await threadts.execute((data) => {
// Emit progress updates
for (let i = 0; i < 100; i++) {
postMessage({ progress: i, message: Processing ${i}% });
// Heavy work here
}
return finalResult;
}, inputData);
`
#### Transferable Objects
`typescript
const buffer = new ArrayBuffer(1024 * 1024);
const result = await threadts.run(
(buffer) => {
// Process buffer in worker
const view = new Uint8Array(buffer);
// ... processing
return processedData;
},
buffer,
{ transferable: [buffer] }
);
`
#### Pool Management
`typescript
// Resize worker pool
await threadts.resize(8);
// Get pool statistics
const stats = threadts.getStats();
console.log(stats);
// {
// activeWorkers: 2,
// idleWorkers: 6,
// queuedTasks: 0,
// completedTasks: 150,
// averageExecutionTime: 45.2
// }
// Get/Update configuration
const config = threadts.getConfig();
threadts.updateConfig({ timeout: 10000, debug: true });
// Check platform and support
console.log(threadts.getPlatform()); // 'node', 'browser', 'deno', 'bun'
console.log(threadts.isSupported()); // true if workers are supported
// Cleanup
await threadts.terminate(); // Terminate instance
await ThreadTS.terminateAll(); // Terminate all instances
`
$3
#### @parallelMethod(options?)
Automatically parallelizes method execution.
`typescript
import { parallelMethod } from 'threadts-universal';
class ImageProcessor {
@parallelMethod({ cacheResults: true, timeout: 5000 })
async applyFilter(imageData: ImageData, filter: Filter): Promise {
// Automatically runs in worker thread
return processImage(imageData, filter);
}
}
`
Options:
- timeout: Maximum execution time in milliseconds
- priority: Execution priority ('low', 'normal', 'high')
- maxRetries: Number of retry attempts on failure
- poolSize: Custom worker pool size
- cacheResults: Enable result caching
#### @memoize(maxCacheSize?)
Caches method results with LRU eviction policy.
`typescript
@memoize(100) // Cache up to 100 unique results
async expensiveComputation(input: string): Promise {
return computeResult(input);
}
`
#### @retry(maxAttempts?, baseDelay?)
Retry logic with exponential backoff.
`typescript
@retry(3, 1000) // 3 attempts, starting with 1s delay
async unreliableOperation(): Promise {
await callExternalService();
}
`
#### @rateLimit(callsPerSecond?)
Limits method call frequency.
`typescript
@rateLimit(10) // Max 10 calls per second
async apiCall(): Promise {
return fetchFromAPI();
}
`
#### @timeout(ms?)
Automatically rejects if execution exceeds the specified timeout.
`typescript
@timeout(5000) // Reject after 5 seconds
async longRunningTask(): Promise {
return performTask();
}
`
#### @debounce(ms?)
Delays execution until no calls have been made for the specified duration.
`typescript
@debounce(300) // Wait 300ms after last call
async handleInput(value: string): Promise {
await saveToServer(value);
}
`
#### @throttle(ms?)
Ensures the method is called at most once per specified interval.
`typescript
@throttle(1000) // At most once per second
async trackEvent(event: Event): Promise {
await sendAnalytics(event);
}
`
#### @logged(options?)
Logs method calls, arguments, results, and execution time.
`typescript
@logged({ logArgs: true, logResult: true })
async processData(data: Data): Promise {
return transform(data);
}
// Logs: [ClassName.processData] Starting with args: [...]
// Logs: [ClassName.processData] Completed in 45ms. Result: {...}
`
#### @parallelBatch(batchSize?)
Processes array data in parallel batches.
`typescript
@parallelBatch(4)
async processBatch(items: Item[]): Promise {
return items.map(processItem);
}
`
#### @parallelMap()
Parallel map operation on array input.
`typescript
@parallelMap()
async processItems(items: Item[]): Promise {
return items.map(transform);
}
`
#### Decorator Summary
`typescript
// Parallelization
@parallelMethod() // Parallelize method execution
@parallelBatch(4) // Process arrays in batches of 4
@parallelMap() // Parallel map over array
// Caching
@memoize(100) // LRU cache with 100 entries
@cache(60000, 50) // TTL cache: 60s expiry, max 50 entries
// Reliability
@retry(3, 1000) // Retry up to 3 times with exponential backoff
@timeout(5000) // Timeout after 5 seconds
@circuitBreaker({ failureThreshold: 5, resetTimeout: 30000 }) // Circuit breaker pattern
// Rate Control
@rateLimit(10) // Max 10 calls per second
@debounce(300) // Debounce with 300ms delay
@throttle(1000) // Throttle to once per second
@concurrent(3) // Limit to 3 concurrent executions
// Observability
@logged() // Log execution details
@measure() // Collect timing statistics
// Validation & Initialization
@validate([...validators]) // Validate arguments
@lazy() // Lazy initialization (execute only once)
`
#### @cache(ttlMs?, maxSize?)
Caches method results with TTL (Time To Live) support.
`typescript
@cache(30000, 50) // Cache for 30 seconds, max 50 entries
async fetchData(id: string): Promise {
return await api.getData(id);
}
// Clear cache: this.fetchData.clearCache()
`
#### @concurrent(maxConcurrent?)
Limits concurrent executions of a method.
`typescript
@concurrent(3) // Max 3 concurrent executions
async processFile(path: string): Promise {
await heavyFileOperation(path);
}
`
#### @circuitBreaker(options?)
Implements the circuit breaker pattern for fault tolerance.
`typescript
@circuitBreaker({
failureThreshold: 5, // Open circuit after 5 failures
resetTimeout: 30000, // Try again after 30 seconds
halfOpenRequests: 1 // Allow 1 test request in half-open state
})
async callExternalApi(): Promise {
return await externalApi.getData();
}
// Check state: this.callExternalApi.getState()
// Reset: this.callExternalApi.reset()
`
#### @measure()
Collects timing statistics across multiple calls.
`typescript
@measure()
async compute(data: number[]): Promise {
return data.reduce((a, b) => a + b, 0);
}
// Get stats: this.compute.getStats()
// Returns: { count, min, max, avg, median, p95, p99 }
`
#### @validate(validators)
Validates method arguments before execution.
`typescript
@validate([
(id) => typeof id === 'string' && id.length > 0,
(data) => data && typeof data.name === 'string'
])
async updateUser(id: string, data: UserData): Promise {
await api.updateUser(id, data);
}
`
#### @lazy()
Lazy initialization - method executes only once.
`typescript
@lazy()
async loadConfig(): Promise {
return await fetchConfig(); // Only called once, result cached forever
}
// Reset: this.loadConfig.reset()
`
$3
ThreadTS provides utility functions for creating your own decorators that work with both legacy (experimentalDecorators) and Stage-3 decorator syntax:
`typescript
import {
createMethodDecorator,
createMethodDecoratorWithClass,
createClassDecorator,
isAsyncFunction,
ensureAsync,
} from 'threadts-universal';
// Simple method decorator
function logExecution() {
return createMethodDecorator((originalMethod, methodName) => {
return async function (...args: unknown[]) {
console.log(Calling ${methodName});
const result = await originalMethod.apply(this, args);
console.log(${methodName} returned:, result);
return result;
} as typeof originalMethod;
});
}
// Decorator with class name for observability
function auditLog() {
return createMethodDecoratorWithClass((method, methodName, className) => {
return async function (...args: unknown[]) {
console.log([${className}.${methodName}] called with:, args);
return method.apply(this, args);
} as typeof method;
});
}
// Class decorator
function singleton() {
const instances = new Map();
return createClassDecorator((OriginalClass, className) => {
return class extends OriginalClass {
constructor(...args: unknown[]) {
if (instances.has(className)) {
return instances.get(className);
}
super(...args);
instances.set(className, this);
}
} as typeof OriginalClass;
});
}
// Usage
class MyService {
@logExecution()
async process(data: string): Promise {
return data.toUpperCase();
}
@auditLog()
async save(item: Item): Promise {
// Logs: [MyService.save] called with: [...]
await db.save(item);
}
}
`
$3
`typescript
// Listen to task completion events
threadts.on('task-complete', ({ taskId, result, duration }) => {
console.log(Task ${taskId} completed in ${duration}ms);
});
// Listen to task errors
threadts.on('task-error', ({ taskId, error, duration }) => {
console.error(Task ${taskId} failed: ${error});
});
// Listen to pool resize events
threadts.on('pool-resize', ({ oldSize, newSize }) => {
console.log(Pool resized from ${oldSize} to ${newSize});
});
// Remove event listener
threadts.off('task-complete', listener);
`
$3
`typescript
import {
PerformanceMonitor,
HealthMonitor,
ErrorHandler,
} from 'threadts-universal';
// Performance Monitoring
const perfMonitor = new PerformanceMonitor();
perfMonitor.startMonitoring(2000); // Check every 2 seconds
const metrics = perfMonitor.collectMetrics();
// Health Monitoring
const healthMonitor = new HealthMonitor();
healthMonitor.startHealthMonitoring(5000); // Check every 5 seconds
const health = await healthMonitor.performHealthCheck();
console.log(health.overall); // 'healthy', 'degraded', or 'unhealthy'
// Error Handling with auto-recovery
const errorHandler = new ErrorHandler();
const result = await errorHandler.executeWithRetry(
'operation-name',
async () => riskyOperation(),
{ platform: 'node', workerCount: 4 }
);
`
🌟 Platform-Specific Features
$3
- OffscreenCanvas: GPU-intensive graphics processing
- Web Locks: Worker coordination and synchronization
- Transferable Objects: Zero-copy operations
- Safari Polyfills: Automatic fallback detection
$3
- Worker Threads: CPU-intensive task processing
- Resource Limits: Memory control per worker
- Cluster Mode: Multi-core utilization
- Native Addons: Performance optimization hooks
`typescript
// Node.js specific resource limits
const result = await threadts.run(heavyTask, data, {
resourceLimits: {
maxOldGenerationSizeMb: 128,
maxYoungGenerationSizeMb: 64,
codeRangeSizeMb: 16,
stackSizeMb: 4,
},
workerName: 'heavy-worker',
trackResources: true,
});
`
$3
- Permission Sandboxing: Secure worker execution
- TypeScript Native: Zero-config TypeScript support
- Web Standards: Modern web API compatibility
`typescript
// Deno specific permissions
const result = await threadts.run(task, data, {
denoPermissions: {
net: ['api.example.com'],
read: ['/data'],
env: true,
hrtime: true,
},
});
`
$3
- Ultra-fast Startup: Optimized worker creation
- Native Performance: Maximum speed execution
- High Precision Timing: Microsecond accuracy
`typescript
// Bun specific options
const result = await threadts.run(task, data, {
bunOptions: {
name: 'compute-worker',
highPrecisionTiming: true,
forceGC: true,
},
});
`
📊 Performance
ThreadTS Universal provides quantum-level performance with sub-5ms overhead:
`typescript
// Benchmark: Fibonacci(40) calculation
const iterations = 1000;
// Sequential execution: ~2.3s
// ThreadTS parallel: ~0.6s (4 cores)
// Overhead: < 5ms per operation
`
$3
| Operation | Data Size | Time | Throughput |
| --------------------- | ----------- | ------ | --------------- |
| Image Processing | 1920x1080 | ~50ms | ~40k pixels/ms |
| JSON Transformation | 10k records | ~30ms | ~300 records/ms |
| Cryptographic Hashing | 1k items | ~15ms | ~65 hashes/ms |
| Array Map | 100k items | ~200ms | ~500k items/s |
🔧 Configuration
$3
`typescript
import { ThreadTS } from 'threadts-universal';
const threadts = ThreadTS.getInstance({
poolSize: 8, // Number of workers
timeout: 30000, // Default timeout in ms
retries: 2, // Default retry attempts
autoResize: true, // Auto-scale pool
debug: false, // Enable debug logging
maxQueueSize: 1000, // Max queued tasks
workerIdleTimeout: 60000, // Worker idle timeout
taskPriority: 'normal', // Default priority
});
`
$3
`typescript
import {
detectPlatform,
supportsWorkerThreads,
getOptimalThreadCount,
getMemoryInfo,
} from 'threadts-universal';
console.log('Platform:', detectPlatform()); // 'node', 'browser', 'deno', 'bun'
console.log('Worker Support:', supportsWorkerThreads());
console.log('Optimal Threads:', getOptimalThreadCount());
console.log('Memory:', getMemoryInfo());
`
🧪 Testing
`bash
Run all tests
npm test
Browser tests
npm run test:browser
Node.js tests
npm run test:node
Performance benchmarks
npm run test:performance
`
🏗️ Project Architecture
ThreadTS Universal follows a modular, OOP-first architecture designed for maintainability and extensibility.
$3
`text
src/
├── index.ts # Main entry point (auto-detects platform)
├── browser.ts # Browser-specific entry
├── node.ts # Node.js-specific entry
├── types.ts # TypeScript type definitions
│
├── core/
│ ├── threadts.ts # Main ThreadTS class (singleton pattern)
│ ├── pipeline.ts # Pipeline & TerminalPipeline classes
│ ├── pipeline-operations.ts # Pipeline operation handlers
│ └── array-operations.ts # Extended array operations factory
│
├── adapters/
│ ├── base.ts # Abstract WorkerAdapter base class
│ ├── browser.ts # Web Worker adapter
│ ├── node.ts # Worker Threads adapter
│ ├── deno.ts # Deno Worker adapter
│ └── bun.ts # Bun Worker adapter
│
├── decorators/
│ ├── index.ts # Re-exports all decorators
│ ├── parallel.ts # @parallelMethod, @parallelClass, @parallelBatch, @parallelMap
│ ├── caching.ts # @memoize, @cache, @lazy
│ ├── flow-control.ts # @retry, @timeout, @rateLimit, @debounce, @throttle, @concurrent, @circuitBreaker
│ └── observability.ts # @logged, @measure, @validate
│
├── monitoring/
│ ├── error-handler.ts # Centralized error handling
│ ├── health.ts # Health checks and diagnostics
│ └── performance.ts # Performance monitoring
│
├── pool/
│ └── manager.ts # Worker pool management
│
└── utils/
├── platform.ts # Platform detection utilities
├── serialization.ts # Data serialization helpers
└── validation.ts # Input validation utilities
`
$3
Decorators are organized by category for better maintainability:
| Module | Decorators | Purpose |
| ------------------ | ---------------------------------------------------------------------------------------------- | ----------------------------- |
| parallel.ts | @parallelMethod, @parallelClass, @parallel, @parallelBatch, @parallelMap | Parallel execution |
| caching.ts | @memoize, @cache, @lazy | Caching & memoization |
| flow-control.ts | @retry, @timeout, @rateLimit, @debounce, @throttle, @concurrent, @circuitBreaker | Flow control & resilience |
| observability.ts | @logged, @measure, @validate | Logging, metrics & validation |
All decorators are re-exported from decorators/index.ts for convenient imports:
`typescript
// Import individual decorators
import { parallelMethod, memoize, retry, logged } from 'threadts-universal';
// Or import all from specific category
import { memoize, cache, lazy } from 'threadts-universal/decorators/caching';
`
$3
#### ThreadTS (Singleton)
The main class managing worker pools and task execution:
`typescript
// Always use getInstance() - ThreadTS is a singleton
const threadts = ThreadTS.getInstance({ poolSize: 4 });
// Methods are chainable where appropriate
await threadts.run(fn, data);
await threadts.map(array, fn);
await threadts.pipe(array).filter(fn).map(fn).execute();
`
#### Pipeline & TerminalPipeline
Fluent API for data processing with lazy evaluation:
`typescript
// Pipeline provides intermediate operations (lazy)
const pipeline = threadts
.pipe(data)
.filter((x) => x > 0) // Returns Pipeline
.map((x) => x * 2) // Returns Pipeline
.sort((a, b) => a - b); // Returns Pipeline
// Terminal operations execute the pipeline
const result = await pipeline.execute(); // Returns TerminalPipeline
const array = await pipeline.toArray(); // Executes and returns array
const sum = await pipeline.sum().execute(); // Aggregation
`
$3
Platform-specific worker implementations extend the abstract WorkerAdapter:
`typescript
abstract class WorkerAdapter {
abstract createWorker(taskFn: Function, data: unknown): void;
abstract terminate(): Promise;
abstract postMessage(message: unknown): void;
// ... common interface
}
// Platform adapters
class BrowserWorkerAdapter extends WorkerAdapter {
/ Web Worker /
}
class NodeWorkerAdapter extends WorkerAdapter {
/ Worker Threads /
}
class DenoWorkerAdapter extends WorkerAdapter {
/ Deno Worker /
}
class BunWorkerAdapter extends WorkerAdapter {
/ Bun Worker /
}
`
🤝 Contributing
We welcome contributions! Please see our Contributing Guide for details.
$3
`bash
git clone https://github.com/JosunLP/ThreadTS-Universal.git
cd universal
npm install
npm run build
npm test
`
📄 License
MIT License - see LICENSE file for details.
🌟 Why ThreadTS Universal?
$3
`typescript
// Complex worker setup
const worker = new Worker('worker.js');
worker.postMessage(data);
worker.onmessage = (event) => {
const result = event.data;
// Handle result...
};
worker.onerror = (error) => {
// Handle error...
};
`
$3
`typescript
// One line parallel execution
const result = await threadts.run(fn, data);
// Full Array API
const found = await threadts.find(array, predicate);
const all = await threadts.every(array, test);
const any = await threadts.some(array, test);
``