Typings — Concurrent

Package: @litert/concurrentSource: packages/partials/concurrent/src/Types.ts, packages/partials/concurrent/src/Classes/

---

Core Interfaces

ICounter

A generic counter interface.

interface ICounter {
    getTotal(): number;
    increase(step?: number): void;
    reset(): void;
}

Method	Description
getTotal()	Returns the current count
increase(step?)	Increments the counter by step (default 1)
reset()	Resets the counter to zero

---

ISimpleFn

A function that takes no parameters.

type ISimpleFn = IFunction<[]>;

---

IBreaker

Interface for all circuit breaker implementations.

interface IBreaker {
    call<T extends ISimpleFn>(fn: T): ReturnType<T>;
    wrap<T extends ISimpleFn>(fn: T): T;
}

Method	Description
call<T>(fn)	Calls fn if the breaker is closed; throws if open
wrap<T>(fn)	Returns a new function that passes through the breaker

---

ISyncRateLimiter

Interface for synchronous rate limiters.

interface ISyncRateLimiter {
    isBlocking(): boolean;
    isIdle(): boolean;
    challenge(): void;
    reset(): void;
    call<T extends IFunction>(fn: T): ReturnType<T>;
    wrap<T extends IFunction>(fn: T): T;
}

Method	Description
isBlocking()	Returns true if the limiter is currently blocking all calls
isIdle()	Returns true if there is zero traffic
challenge()	Passes or throws; increments internal state on pass
reset()	Resets internal state
call<T>(fn)	Calls fn after a challenge(); throws if limited
wrap<T>(fn)	Wraps fn so every call goes through challenge()

---

ISyncRateLimiterManager

Interface for managing multiple keyed synchronous rate limiters.

interface ISyncRateLimiterManager {
    clean(): void;
    isBlocking(key: string): boolean;
    challenge(key: string): void;
    reset(key: string): void;
    call<T extends IFunction>(key: string, fn: T): ReturnType<T>;
}

Method	Description
clean()	Removes unused/idle limiter contexts
isBlocking(key)	Returns true if key is currently blocked
challenge(key)	Passes or throws for key
reset(key)	Resets state for key
call<T>(key, fn)	Calls fn after challenging key

---

IAsyncRateLimiter

Interface for asynchronous rate limiters.

interface IAsyncRateLimiter {
    isBlocking(): boolean;
    isIdle(): boolean;
    challenge(): Promise<void>;
    reset(): void;
    call<T extends IFunction>(fn: T): Promise<Awaited<ReturnType<T>>>;
    wrap<T extends IFunction>(fn: T): IToPromise<T>;
}

Method	Description
isBlocking()	Returns true if the limiter would cause any call to wait
isIdle()	Returns true if there is zero pending traffic
challenge()	Resolves (possibly after a delay) or throws if over capacity
reset()	Resets internal queue/state
call<T>(fn)	Calls fn after awaiting challenge()
wrap<T>(fn)	Wraps fn as an async function going through challenge()

---

IAsyncRateLimiterManager

Interface for managing multiple keyed asynchronous rate limiters.

interface IAsyncRateLimiterManager {
    isBlocking(key: string): boolean;
    challenge(key: string): Promise<void>;
    reset(key: string): void;
    clean(): void;
    call<T extends IFunction>(key: string, fn: T): Promise<Awaited<ReturnType<T>>>;
}

Method	Description
isBlocking(key)	Returns true if key is currently at capacity
challenge(key)	Awaits until key's slot opens, or throws if over capacity
reset(key)	Resets state for key
clean()	Removes idle contexts
call<T>(key, fn)	Calls fn after awaiting the challenge for key

---

Option Interfaces

IDebounceOptions

Used by DebounceController.

interface IDebounceOptions {
    function: IDebouncingFunction;
    delayMs: number;
    maxDelayMs?: number;
}

Property	Type	Description
function	() => void	The function to debounce
delayMs	number	Milliseconds to wait after the last schedule() call
maxDelayMs	number?	Hard deadline — triggers immediately if elapsed exceeds this; default Number.MAX_SAFE_INTEGER

---

IBatchBufferOptions<T>

Used by BatchBuffer<T>.

interface IBatchBufferOptions<T> extends Pick<IDebounceOptions, 'delayMs' | 'maxDelayMs'> {
    maxSize: number;
    callback: (items: T[]) => void;
}

Property	Type	Description
delayMs	number	Flush delay in milliseconds (from last push())
maxDelayMs	number?	Max flush delay from the first push() after an empty buffer
maxSize	number	Flush immediately when buffer reaches this count
callback	(items: T[]) => void	Receives the flushed batch

---

ISlideWindowCounterOptions

Used by SlideWindowCounter.

interface ISlideWindowCounterOptions {
    windowSizeMs?: number;
    windowQty?: number;
}

Property	Type	Default	Description
windowSizeMs	number?	10000	Total slide window duration in milliseconds
windowQty	number?	3	Number of sub-windows to divide the total window into

---

ICountingRateLimiterOptions

Used by CountingRateLimiter.

interface ICountingRateLimiterOptions {
    limits: number;
    counter: ICounter;
    errorCtorOnLimited?: IConstructor<Error>;
}

Property	Type	Description
limits	number	Maximum count before blocking
counter	ICounter	The counter instance to track calls
errorCtorOnLimited	IConstructor<Error>?	Custom error class; defaults to E_RATE_LIMITED

---

ITokenBucketRateLimiterOptions

Used by TokenBucketRateLimiter.

interface ITokenBucketRateLimiterOptions {
    capacity: number;
    initialTokens?: number;
    refillIntervalMs: number;
    errorCtorOnLimited?: IConstructor<Error>;
}

Property	Type	Default	Description
capacity	number	—	Max token count in the bucket
initialTokens	number?	capacity	Starting token count
refillIntervalMs	number	—	Milliseconds per token refill
errorCtorOnLimited	IConstructor<Error>?	E_RATE_LIMITED	Custom error class

---

ILeakyBucketRateLimiterOptions

Used by LeakyBucketRateLimiter.

interface ILeakyBucketRateLimiterOptions {
    capacity: number;
    leakIntervalMs: number;
    errorCtorOnLimited?: IConstructor<Error>;
}

Property	Type	Description
capacity	number	Maximum pending tasks (queue depth)
leakIntervalMs	number	Milliseconds between each task being "leaked" through
errorCtorOnLimited	IConstructor<Error>?	Custom error class; defaults to E_RATE_LIMITED

---

ITokenBucketRateLimiterManagerOptions

Used by TokenBucketRateLimiterManager.

interface ITokenBucketRateLimiterManagerOptions {
    capacity: number;
    initialTokens?: number;
    refillIntervalMs: number;
    cleanDelayMs?: number;
    errorCtorOnLimited?: IConstructor<Error>;
}

Property	Type	Default	Description
capacity	number	—	Bucket capacity per key
initialTokens	number?	capacity	Initial tokens per key
refillIntervalMs	number	—	Milliseconds per token refill
cleanDelayMs	number?	0	How long (ms) to keep a full, unused context before cleaning; 0 = disabled
errorCtorOnLimited	IConstructor<Error>?	E_RATE_LIMITED	Custom error class

---

ILeakyBucketRateLimiterManagerOptions

Used by LeakyBucketRateLimiterManager.

interface ILeakyBucketRateLimiterManagerOptions {
    capacity: number;
    leakIntervalMs: number;
    cleanDelayMs?: number;
    errorCtorOnLimited?: IConstructor<Error>;
}

Property	Type	Default	Description
capacity	number	—	Max pending tasks per key
leakIntervalMs	number	—	Milliseconds per task leakage
cleanDelayMs	number?	0	Keep idle context for this long before cleaning; 0 = disabled
errorCtorOnLimited	IConstructor<Error>?	E_RATE_LIMITED	Custom error class

---

IMemoryMutexOptions

Used by MemoryMutex.

interface IMemoryMutexOptions {
    reentrant?: boolean;
}

Property	Type	Default	Description
reentrant	boolean?	false	If true, the same instance can re-acquire the lock it already holds

---

IFiberPoolOptions

Used by FiberPool.

interface IFiberPoolOptions {
    maxFibers: number;
    maxIdleFibers?: number;
    minIdleFibers?: number;
    idleTimeout?: number;
    defaultWaitTimeout?: number;
    maxWaits?: number;
}

Property	Type	Default	Description
maxFibers	number	—	Maximum total fibers (idle + busy)
maxIdleFibers	number?	1	Maximum idle fibers to keep alive
minIdleFibers	number?	1	Minimum idle fibers — never closed even after idle timeout
idleTimeout	number?	10000	Milliseconds before an idle fiber above minIdleFibers is released
defaultWaitTimeout	number?	10000	Default wait timeout for run() when no fiber is available
maxWaits	number?	10	Maximum concurrent waiters for a free fiber

---

IRunOptions<TData, TResult>

Used by FiberPool.run().

interface IRunOptions<TData, TResult> {
    waitTimeout?: number;
    data: TData;
    function: IFiberFunction<TData, TResult>;
}

Property	Type	Description
waitTimeout	number?	Override defaultWaitTimeout for this call
data	TData	Argument passed to function
function	(data: TData) => Promise<TResult>	The task to run inside the fiber

---

ICircuitBreakerOptions

Used by CircuitBreaker.

interface ICircuitBreakerOptions {
    cooldownTimeMs?: number;
    breakThreshold?: number;
    warmupThreshold?: number;
    isFailure?: (error: unknown) => boolean;
    errorCtorOnOpen?: IConstructor<Error>;
    counter?: ICounter;
}

Property	Type	Default	Description
cooldownTimeMs	number?	60000	Time (ms) after which the breaker enters half-open state
breakThreshold	number?	5	Failure count to trigger open state
warmupThreshold	number?	3	Consecutive successes needed to close from half-open
isFailure	(err) => boolean?	() => true	Determines whether a thrown error counts as a failure
errorCtorOnOpen	IConstructor<Error>?	E_BREAKER_OPENED	Custom error class
counter	ICounter?	SlideWindowCounter({ windowSizeMs: 10000, windowQty: 6 })	Custom counter for failure tracking

---

Event Interfaces

IDebounceControllerEvents

Emitted by DebounceController.

interface IDebounceControllerEvents {
    'error': [error: unknown];
    'triggered': [];
}

Event	Payload	Description
'error'	error: unknown	Emitted when the debounced function throws
'triggered'	—	Emitted after the debounced function runs successfully

---

IFiberPoolEvents

Emitted by FiberPool.

interface IFiberPoolEvents {
    'error': [error: unknown];
}

Event	Payload	Description
'error'	error: unknown	Emitted when a fiber encounters an unhandled error

---

ICircuitBreakerEvents

Emitted by CircuitBreaker.

interface ICircuitBreakerEvents {
    'error': [error: unknown];
    'opened': [];
    'half_opened': [];
    'closed': [];
}

Event	Payload	Description
'error'	error: unknown	Emitted when the guarded function throws (failures counted)
'opened'	—	Emitted when the breaker transitions to open state
'half_opened'	—	Emitted when the breaker enters half-open state
'closed'	—	Emitted when the breaker returns to closed (normal) state

---

Type Aliases

IDebouncingFunction

type IDebouncingFunction = () => void;

The type for functions that can be wrapped by DebounceController.

---

IFiberFunction<TData, TResult>

type IFiberFunction<TData, TResult> = (data: TData) => Promise<TResult>;

The type for async functions executed inside a FiberPool fiber.