clutchit 0.0.3

package/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hexac
+
+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/dist/circuit/circuit-breaker.d.ts

@@ -0,0 +1,47 @@
+import { ResultAsync } from '../unthrow/index.js';
+import { Schedule } from '../schedule/index.js';
+export type CircuitState = 'closed' | 'open' | 'half-open';
+export declare const CircuitOpenFault: (remainingTimeout: number) => Readonly<{
+    code: "CIRCUIT_OPEN";
+    _category: "infrastructure";
+    _transient: false;
+    message: string;
+} & Omit<{
+    message: string;
+    remainingTimeout: number;
+}, "message">>;
+export type CircuitOpenFault = ReturnType<typeof CircuitOpenFault>;
+export interface CircuitBreakerOptions {
+    /** Number of consecutive failures before opening. Default: 5 */
+    failureThreshold?: number;
+    /** Schedule for reset timing. Default: Schedule.constant(30_000) */
+    resetSchedule?: Schedule;
+    /** Number of trial requests allowed in half-open state. Default: 1 */
+    halfOpenAttempts?: number;
+    /** Predicate to determine if an error should count as a failure. Default: all errors count. */
+    isFailure?: (error: unknown) => boolean;
+    /** Called when circuit state changes (for logging/monitoring). */
+    onStateChange?: (from: CircuitState, to: CircuitState) => void;
+}
+export declare class CircuitBreaker {
+    private _state;
+    private _failureCount;
+    private _resetAttempt;
+    private _halfOpenTrials;
+    private _nextResetTime;
+    private readonly _failureThreshold;
+    private readonly _resetSchedule;
+    private readonly _maxHalfOpenAttempts;
+    private readonly _isFailure;
+    private readonly _onStateChange?;
+    constructor(options?: CircuitBreakerOptions);
+    protect<T, E>(fn: () => ResultAsync<T, E>): ResultAsync<T, E | CircuitOpenFault>;
+    get state(): CircuitState;
+    get failureCount(): number;
+    reset(): void;
+    private onSuccess;
+    private onFailure;
+    private scheduleReset;
+    private transition;
+}
+//# sourceMappingURL=circuit-breaker.d.ts.map

package/dist/circuit/circuit-breaker.js

@@ -0,0 +1,114 @@
+import { Fault, ResultAsync } from '../unthrow/index.js';
+import { Schedule } from '../schedule/index.js';
+export const CircuitOpenFault = Fault.define({
+    code: 'CIRCUIT_OPEN',
+    category: 'infrastructure',
+    create: (remainingTimeout) => ({
+        message: `Circuit breaker is open. Retry after ${remainingTimeout}ms`,
+        remainingTimeout,
+    }),
+});
+export class CircuitBreaker {
+    _state = 'closed';
+    _failureCount = 0;
+    _resetAttempt = 0;
+    _halfOpenTrials = 0;
+    _nextResetTime = null;
+    _failureThreshold;
+    _resetSchedule;
+    _maxHalfOpenAttempts;
+    _isFailure;
+    _onStateChange;
+    constructor(options) {
+        this._failureThreshold = options?.failureThreshold ?? 5;
+        this._resetSchedule = options?.resetSchedule ?? Schedule.constant(30_000);
+        this._maxHalfOpenAttempts = options?.halfOpenAttempts ?? 1;
+        this._isFailure = options?.isFailure ?? (() => true);
+        this._onStateChange = options?.onStateChange;
+    }
+    protect(fn) {
+        if (this._state === 'open') {
+            if (this._nextResetTime !== null && Date.now() >= this._nextResetTime) {
+                this.transition('half-open');
+                this._halfOpenTrials = 0;
+            }
+            else {
+                const remaining = this._nextResetTime
+                    ? Math.max(0, this._nextResetTime - Date.now())
+                    : 0;
+                return ResultAsync.err(CircuitOpenFault(remaining));
+            }
+        }
+        if (this._state === 'half-open') {
+            if (this._halfOpenTrials >= this._maxHalfOpenAttempts) {
+                return ResultAsync.err(CircuitOpenFault(0));
+            }
+            this._halfOpenTrials++;
+        }
+        return ResultAsync.fromPromise((async () => {
+            const result = await fn();
+            if (result.isOk()) {
+                this.onSuccess();
+                return result.value;
+            }
+            if (this._isFailure(result.error)) {
+                this.onFailure();
+            }
+            // eslint-disable-next-line @typescript-eslint/only-throw-error -- intentional: fromPromise catches and maps E
+            throw result.error;
+        })(), (e) => e);
+    }
+    get state() {
+        return this._state;
+    }
+    get failureCount() {
+        return this._failureCount;
+    }
+    reset() {
+        this._failureCount = 0;
+        this._resetAttempt = 0;
+        this._halfOpenTrials = 0;
+        this._nextResetTime = null;
+        if (this._state !== 'closed') {
+            this.transition('closed');
+        }
+    }
+    onSuccess() {
+        if (this._state === 'closed') {
+            this._failureCount = 0;
+        }
+        else if (this._state === 'half-open') {
+            this._failureCount = 0;
+            this._resetAttempt = 0;
+            this._halfOpenTrials = 0;
+            this.transition('closed');
+        }
+    }
+    onFailure() {
+        if (this._state === 'closed') {
+            this._failureCount++;
+            if (this._failureCount >= this._failureThreshold) {
+                this.transition('open');
+                this.scheduleReset();
+            }
+        }
+        else if (this._state === 'half-open') {
+            this._halfOpenTrials = 0;
+            this.transition('open');
+            this.scheduleReset();
+        }
+    }
+    scheduleReset() {
+        const step = this._resetSchedule.next(undefined, this._resetAttempt);
+        this._nextResetTime = Date.now() + step.delay;
+        this._resetAttempt++;
+    }
+    transition(to) {
+        const from = this._state;
+        if (from !== to) {
+            this._state = to;
+            this._onStateChange?.(from, to);
+        }
+    }
+}
+//# sourceMappingURL=circuit-breaker.js.map

package/dist/circuit/index.d.ts

@@ -0,0 +1,7 @@
+import { CircuitBreaker as _CircuitBreaker } from './circuit-breaker.js';
+export type { CircuitState, CircuitBreakerOptions } from './circuit-breaker.js';
+export type { CircuitOpenFault } from './circuit-breaker.js';
+export declare namespace Circuit {
+    const Breaker: typeof _CircuitBreaker;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/circuit/index.js

@@ -0,0 +1,7 @@
+import { CircuitBreaker as _CircuitBreaker } from './circuit-breaker.js';
+// eslint-disable-next-line @typescript-eslint/no-namespace
+export var Circuit;
+(function (Circuit) {
+    Circuit.Breaker = _CircuitBreaker;
+})(Circuit || (Circuit = {}));
+//# sourceMappingURL=index.js.map

package/dist/concurrency/bulkhead.d.ts

@@ -0,0 +1,27 @@
+import { ResultAsync } from '../unthrow/index.js';
+export declare const BulkheadRejectedFault: () => Readonly<{
+    code: "BULKHEAD_REJECTED";
+    _category: "infrastructure";
+    _transient: false;
+    message: string;
+} & Omit<{
+    message: string;
+}, "message">>;
+export type BulkheadRejectedFault = ReturnType<typeof BulkheadRejectedFault>;
+export interface BulkheadOptions {
+    concurrency: number;
+    queue?: number;
+}
+export declare class Bulkhead {
+    private _active;
+    private readonly _maxConcurrency;
+    private readonly _maxQueue;
+    private readonly _queue;
+    constructor(options: BulkheadOptions);
+    execute<T, E>(fn: () => ResultAsync<T, E>): ResultAsync<T, E | BulkheadRejectedFault>;
+    get activeCount(): number;
+    get queueSize(): number;
+    private acquire;
+    private release;
+}
+//# sourceMappingURL=bulkhead.d.ts.map

package/dist/concurrency/bulkhead.js

@@ -0,0 +1,62 @@
+import { Fault, ResultAsync } from '../unthrow/index.js';
+export const BulkheadRejectedFault = Fault.define({
+    code: 'BULKHEAD_REJECTED',
+    category: 'infrastructure',
+    create: () => ({
+        message: 'Bulkhead capacity exceeded',
+    }),
+});
+export class Bulkhead {
+    _active = 0;
+    _maxConcurrency;
+    _maxQueue;
+    _queue = [];
+    constructor(options) {
+        this._maxConcurrency = options.concurrency;
+        this._maxQueue = options.queue ?? 0;
+    }
+    execute(fn) {
+        if (this._active >= this._maxConcurrency &&
+            this._queue.length >= this._maxQueue) {
+            return ResultAsync.err(BulkheadRejectedFault());
+        }
+        return ResultAsync.fromPromise((async () => {
+            await this.acquire();
+            try {
+                const result = await fn();
+                if (result.isOk())
+                    return result.value;
+                // eslint-disable-next-line @typescript-eslint/only-throw-error -- intentional: fromPromise catches and maps E
+                throw result.error;
+            }
+            finally {
+                this.release();
+            }
+        })(), (e) => e);
+    }
+    get activeCount() {
+        return this._active;
+    }
+    get queueSize() {
+        return this._queue.length;
+    }
+    acquire() {
+        if (this._active < this._maxConcurrency) {
+            this._active++;
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => {
+            this._queue.push(resolve);
+        });
+    }
+    release() {
+        const next = this._queue.shift();
+        if (next) {
+            next();
+        }
+        else {
+            this._active--;
+        }
+    }
+}
+//# sourceMappingURL=bulkhead.js.map

package/dist/concurrency/index.d.ts

@@ -0,0 +1,16 @@
+import { Semaphore as _Semaphore } from './semaphore.js';
+import { RateLimiter as _RateLimiter } from './rate-limiter.js';
+import { Bulkhead as _Bulkhead } from './bulkhead.js';
+import { Ref as _Ref } from './ref.js';
+export type { SemaphoreOptions } from './semaphore.js';
+export type { RateLimiterOptions } from './rate-limiter.js';
+export type { RateLimitFault } from './rate-limiter.js';
+export type { BulkheadOptions } from './bulkhead.js';
+export type { BulkheadRejectedFault } from './bulkhead.js';
+export declare namespace Concurrency {
+    const Semaphore: typeof _Semaphore;
+    const RateLimiter: typeof _RateLimiter;
+    const Bulkhead: typeof _Bulkhead;
+    const Ref: typeof _Ref;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/concurrency/index.js

@@ -0,0 +1,13 @@
+import { Semaphore as _Semaphore } from './semaphore.js';
+import { RateLimiter as _RateLimiter } from './rate-limiter.js';
+import { Bulkhead as _Bulkhead } from './bulkhead.js';
+import { Ref as _Ref } from './ref.js';
+// eslint-disable-next-line @typescript-eslint/no-namespace
+export var Concurrency;
+(function (Concurrency) {
+    Concurrency.Semaphore = _Semaphore;
+    Concurrency.RateLimiter = _RateLimiter;
+    Concurrency.Bulkhead = _Bulkhead;
+    Concurrency.Ref = _Ref;
+})(Concurrency || (Concurrency = {}));
+//# sourceMappingURL=index.js.map

package/dist/concurrency/rate-limiter.d.ts

@@ -0,0 +1,25 @@
+import { ResultAsync } from '../unthrow/index.js';
+export declare const RateLimitFault: (retryAfter: number) => Readonly<{
+    code: "RATE_LIMITED";
+    _category: "infrastructure";
+    _transient: true;
+    message: string;
+} & Omit<{
+    message: string;
+    retryAfter: number;
+}, "message">>;
+export type RateLimitFault = ReturnType<typeof RateLimitFault>;
+export interface RateLimiterOptions {
+    limit: number;
+    window: number;
+}
+export declare class RateLimiter {
+    private readonly _limit;
+    private readonly _window;
+    private readonly _timestamps;
+    constructor(options: RateLimiterOptions);
+    execute<T, E>(fn: () => ResultAsync<T, E>): ResultAsync<T, E | RateLimitFault>;
+    get remaining(): number;
+    private cleanup;
+}
+//# sourceMappingURL=rate-limiter.d.ts.map

package/dist/concurrency/rate-limiter.js

@@ -0,0 +1,40 @@
+import { Fault, ResultAsync } from '../unthrow/index.js';
+export const RateLimitFault = Fault.define({
+    code: 'RATE_LIMITED',
+    category: 'infrastructure',
+    transient: true,
+    create: (retryAfter) => ({
+        message: `Rate limit exceeded. Retry after ${retryAfter}ms`,
+        retryAfter,
+    }),
+});
+export class RateLimiter {
+    _limit;
+    _window;
+    _timestamps = [];
+    constructor(options) {
+        this._limit = options.limit;
+        this._window = options.window;
+    }
+    execute(fn) {
+        this.cleanup();
+        if (this._timestamps.length >= this._limit) {
+            const oldest = this._timestamps[0];
+            const retryAfter = Math.max(0, oldest + this._window - Date.now());
+            return ResultAsync.err(RateLimitFault(retryAfter));
+        }
+        this._timestamps.push(Date.now());
+        return fn();
+    }
+    get remaining() {
+        this.cleanup();
+        return Math.max(0, this._limit - this._timestamps.length);
+    }
+    cleanup() {
+        const cutoff = Date.now() - this._window;
+        while (this._timestamps.length > 0 && this._timestamps[0] <= cutoff) {
+            this._timestamps.shift();
+        }
+    }
+}
+//# sourceMappingURL=rate-limiter.js.map

package/dist/concurrency/ref.d.ts

@@ -0,0 +1,11 @@
+import { ResultAsync } from '../unthrow/index.js';
+export declare class Ref<T> {
+    private _value;
+    private readonly _mutex;
+    constructor(initial: T);
+    get(): T;
+    modify<R>(fn: (current: T) => [next: T, result: R]): ResultAsync<R, never>;
+    update(fn: (current: T) => T): ResultAsync<void, never>;
+    set(value: T): ResultAsync<void, never>;
+}
+//# sourceMappingURL=ref.d.ts.map

package/dist/concurrency/ref.js

@@ -0,0 +1,26 @@
+import { ResultAsync } from '../unthrow/index.js';
+import { Semaphore } from './semaphore.js';
+export class Ref {
+    _value;
+    _mutex = new Semaphore({ permits: 1 });
+    constructor(initial) {
+        this._value = initial;
+    }
+    get() {
+        return this._value;
+    }
+    modify(fn) {
+        return this._mutex.execute(() => {
+            const [next, result] = fn(this._value);
+            this._value = next;
+            return ResultAsync.ok(result);
+        });
+    }
+    update(fn) {
+        return this.modify((v) => [fn(v), undefined]);
+    }
+    set(value) {
+        return this.modify(() => [value, undefined]);
+    }
+}
+//# sourceMappingURL=ref.js.map

package/dist/concurrency/semaphore.d.ts

@@ -0,0 +1,15 @@
+import { ResultAsync } from '../unthrow/index.js';
+export interface SemaphoreOptions {
+    permits: number;
+}
+export declare class Semaphore {
+    private _available;
+    private readonly _queue;
+    constructor(options: SemaphoreOptions);
+    execute<T, E>(fn: () => ResultAsync<T, E>): ResultAsync<T, E>;
+    get available(): number;
+    get waiting(): number;
+    private acquire;
+    private release;
+}
+//# sourceMappingURL=semaphore.d.ts.map

package/dist/concurrency/semaphore.js

@@ -0,0 +1,48 @@
+import { ResultAsync } from '../unthrow/index.js';
+export class Semaphore {
+    _available;
+    _queue = [];
+    constructor(options) {
+        this._available = options.permits;
+    }
+    execute(fn) {
+        return ResultAsync.fromPromise((async () => {
+            await this.acquire();
+            try {
+                const result = await fn();
+                if (result.isOk())
+                    return result.value;
+                // eslint-disable-next-line @typescript-eslint/only-throw-error -- intentional: fromPromise catches and maps E
+                throw result.error;
+            }
+            finally {
+                this.release();
+            }
+        })(), (e) => e);
+    }
+    get available() {
+        return this._available;
+    }
+    get waiting() {
+        return this._queue.length;
+    }
+    acquire() {
+        if (this._available > 0) {
+            this._available--;
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => {
+            this._queue.push(resolve);
+        });
+    }
+    release() {
+        const next = this._queue.shift();
+        if (next) {
+            next();
+        }
+        else {
+            this._available++;
+        }
+    }
+}
+//# sourceMappingURL=semaphore.js.map

package/dist/queue/base.queue.d.ts

@@ -0,0 +1,18 @@
+import { Result, ResultAsync } from '../unthrow/index.js';
+import { QueueEmptyFault } from './faults.js';
+export interface QueueOptions {
+    capacity: number;
+}
+export declare class BaseQueue<T> {
+    protected readonly _buffer: T[];
+    protected readonly _capacity: number;
+    protected readonly _takeWaiters: Array<(item: T) => void>;
+    constructor(options: QueueOptions);
+    protected _tryTake(): Result<T, QueueEmptyFault>;
+    take(signal?: AbortSignal): ResultAsync<T, never>;
+    takeBatch(n: number, signal?: AbortSignal): ResultAsync<T[], never>;
+    poll(): Result<T, QueueEmptyFault>;
+    get size(): number;
+    get capacity(): number;
+}
+//# sourceMappingURL=base.queue.d.ts.map

package/dist/queue/base.queue.js

@@ -0,0 +1,66 @@
+import { Result, ResultAsync } from '../unthrow/index.js';
+import { QueueEmptyFault } from './faults.js';
+export class BaseQueue {
+    _buffer = [];
+    _capacity;
+    _takeWaiters = [];
+    constructor(options) {
+        this._capacity = options.capacity;
+    }
+    _tryTake() {
+        if (this._buffer.length > 0) {
+            return Result.ok(this._buffer.shift());
+        }
+        return Result.err(QueueEmptyFault());
+    }
+    take(signal) {
+        const taken = this._tryTake();
+        if (taken.isOk())
+            return ResultAsync.ok(taken.value);
+        return ResultAsync.fromPromise(new Promise((resolve) => {
+            this._takeWaiters.push(resolve);
+            signal?.addEventListener('abort', () => {
+                const idx = this._takeWaiters.indexOf(resolve);
+                if (idx !== -1)
+                    this._takeWaiters.splice(idx, 1);
+            }, { once: true });
+        }), () => undefined);
+    }
+    takeBatch(n, signal) {
+        return ResultAsync.fromPromise((async () => {
+            const taken = this._tryTake();
+            let first;
+            if (taken.isOk()) {
+                first = taken.value;
+            }
+            else {
+                first = await new Promise((resolve) => {
+                    this._takeWaiters.push(resolve);
+                    signal?.addEventListener('abort', () => {
+                        const idx = this._takeWaiters.indexOf(resolve);
+                        if (idx !== -1)
+                            this._takeWaiters.splice(idx, 1);
+                    }, { once: true });
+                });
+            }
+            const items = [first];
+            while (items.length < n) {
+                const next = this._tryTake();
+                if (next.isErr())
+                    break;
+                items.push(next.value);
+            }
+            return items;
+        })(), () => undefined);
+    }
+    poll() {
+        return this._tryTake();
+    }
+    get size() {
+        return this._buffer.length;
+    }
+    get capacity() {
+        return this._capacity;
+    }
+}
+//# sourceMappingURL=base.queue.js.map

package/dist/queue/bounded.queue.d.ts

@@ -0,0 +1,11 @@
+import { Result, ResultAsync } from '../unthrow/index.js';
+import { QueueEmptyFault, QueueFullFault } from './faults.js';
+import { BaseQueue, type QueueOptions } from './base.queue.js';
+export declare class BoundedQueue<T> extends BaseQueue<T> {
+    private readonly _putWaiters;
+    constructor(options: QueueOptions);
+    protected _tryTake(): Result<T, ReturnType<typeof QueueEmptyFault>>;
+    offer(item: T): Result<void, ReturnType<typeof QueueFullFault>>;
+    put(item: T, signal?: AbortSignal): ResultAsync<void, never>;
+}
+//# sourceMappingURL=bounded.queue.d.ts.map

package/dist/queue/bounded.queue.js

@@ -0,0 +1,64 @@
+import { Result, ResultAsync } from '../unthrow/index.js';
+import { QueueEmptyFault, QueueFullFault } from './faults.js';
+import { BaseQueue } from './base.queue.js';
+export class BoundedQueue extends BaseQueue {
+    _putWaiters = [];
+    constructor(options) {
+        super(options);
+    }
+    _tryTake() {
+        if (this._buffer.length > 0) {
+            const item = this._buffer.shift();
+            // Space freed — accept a put waiter if any
+            const pw = this._putWaiters.shift();
+            if (pw) {
+                this._buffer.push(pw.item);
+                pw.resolve();
+            }
+            return Result.ok(item);
+        }
+        // Buffer empty — try put waiters directly
+        const pw = this._putWaiters.shift();
+        if (pw) {
+            pw.resolve();
+            return Result.ok(pw.item);
+        }
+        return Result.err(QueueEmptyFault());
+    }
+    offer(item) {
+        // Give directly to a waiting consumer
+        const waiter = this._takeWaiters.shift();
+        if (waiter) {
+            waiter(item);
+            return Result.ok(undefined);
+        }
+        if (this._buffer.length >= this._capacity) {
+            return Result.err(QueueFullFault(this._capacity));
+        }
+        this._buffer.push(item);
+        return Result.ok(undefined);
+    }
+    put(item, signal) {
+        // Give directly to a waiting consumer
+        const waiter = this._takeWaiters.shift();
+        if (waiter) {
+            waiter(item);
+            return ResultAsync.ok(undefined);
+        }
+        if (this._buffer.length < this._capacity) {
+            this._buffer.push(item);
+            return ResultAsync.ok(undefined);
+        }
+        // Wait for space
+        return ResultAsync.fromPromise(new Promise((resolve) => {
+            const entry = { item, resolve };
+            this._putWaiters.push(entry);
+            signal?.addEventListener('abort', () => {
+                const idx = this._putWaiters.indexOf(entry);
+                if (idx !== -1)
+                    this._putWaiters.splice(idx, 1);
+            }, { once: true });
+        }), () => undefined);
+    }
+}
+//# sourceMappingURL=bounded.queue.js.map

package/dist/queue/dropping.queue.d.ts

@@ -0,0 +1,7 @@
+import { BaseQueue, type QueueOptions } from './base.queue.js';
+export declare class DroppingQueue<T> extends BaseQueue<T> {
+    constructor(options: QueueOptions);
+    /** Always succeeds. Drops the item if full. Returns whether item was accepted. */
+    offer(item: T): boolean;
+}
+//# sourceMappingURL=dropping.queue.d.ts.map