@stimulcross/rate-limiter 0.0.1 → 0.0.3

package/lib/runtime/rate-limiter.executor.js

@@ -0,0 +1,196 @@
+import { BinaryHeap } from '@stimulcross/ds-binary-heap';
+import { PolicyPriorityQueue } from '@stimulcross/ds-policy-priority-queue';
+import { LogLevel } from '@stimulcross/logger';
+import { ExecutionTickets } from './execution-tickets.js';
+import { Semaphore } from './semaphore.js';
+import { Task } from './task.js';
+import { RateLimitErrorCode } from '../enums/rate-limit-error-code.js';
+import { RateLimitError } from '../errors/rate-limit.error.js';
+/** @internal */
+export class RateLimiterExecutor {
+    _logger;
+    _clock;
+    _tickets = new ExecutionTickets();
+    _semaphore;
+    _queue;
+    _expiryHeap = new BinaryHeap((a, b) => a.expiresAt - b.expiresAt);
+    _drainTimer = null;
+    _expiryTimer = null;
+    _nextExpiryScheduledAt = null;
+    constructor(_logger, clock, { concurrency, capacity, selectionPolicy } = {}) {
+        this._logger = _logger;
+        this._clock = clock;
+        this._semaphore = new Semaphore(concurrency ?? null);
+        this._queue = new PolicyPriorityQueue({
+            capacity,
+            selectionPolicy: selectionPolicy,
+        });
+    }
+    get isQueueFull() {
+        return this._queue.isFull;
+    }
+    get queueSize() {
+        return this._queue.size;
+    }
+    get queueCapacity() {
+        return this._queue.capacity;
+    }
+    async execute(fn, runAt, options) {
+        const task = new Task(fn, options);
+        task.isCancellable &&
+            task.onAbort(() => {
+                this._shouldPrintDebug &&
+                    this._logger.debug(`[DROP CANCELLED] [id: ${options.id}, key: ${options.key}] - ${this._getStateDebugString(task.priority)}`);
+                this._tickets.dropLast();
+                const priorityQueue = this._queue.getQueue(task.priority);
+                priorityQueue.remove(task);
+                this._drain();
+            });
+        this._tickets.add(runAt);
+        this._queue.enqueue(task, task.priority);
+        if (task.expiresAt !== undefined) {
+            this._expiryHeap.push(task);
+        }
+        this._shouldPrintDebug &&
+            this._logger.debug(`↓ [ENQ] [id: ${options.id}, key: ${options.key}] - ${this._getStateDebugString(task.priority)}`);
+        this._drain();
+        return await task;
+    }
+    clear() {
+        this._clearDrainTimer();
+        this._clearExpiryTimer();
+        this._tickets.clear();
+        this._expiryHeap.clear();
+        const pendingTasks = this._drainRemainingTasks();
+        if (pendingTasks.length === 0) {
+            return;
+        }
+        for (const task of pendingTasks) {
+            this._shouldPrintDebug &&
+                this._logger.debug(`[DROP CLEAR] [id: ${task.id}, key: ${task.key}] - Destroy due to clear() - ${this._getStateDebugString(task.priority)}`);
+            task.destroy();
+            task.reject(new RateLimitError(RateLimitErrorCode.Destroyed));
+        }
+    }
+    get _shouldPrintDebug() {
+        return this._logger.minLevel >= LogLevel.DEBUG;
+    }
+    _drain() {
+        const now = this._clock.now();
+        const expiredTasks = this._extractExpiredTasks(now);
+        for (const task of expiredTasks) {
+            this._shouldPrintDebug &&
+                this._logger.debug(`[DROP EXPIRED] [id: ${task.id}, key: ${task.key}] - ${this._getStateDebugString(task.priority)}`);
+            this._tickets.dropLast();
+            task.destroy();
+            task.reject(new RateLimitError(RateLimitErrorCode.Expired));
+        }
+        this._recalibrateExpiryTimer(now);
+        while (!this._queue.isEmpty) {
+            const nextTicketAt = this._tickets.peek();
+            if (nextTicketAt !== undefined && nextTicketAt > now) {
+                this._scheduleDrainTimer(nextTicketAt - now);
+                return;
+            }
+            const isAcquired = this._semaphore.acquire();
+            if (!isAcquired) {
+                return;
+            }
+            const task = this._queue.dequeue();
+            if (!task) {
+                this._semaphore.release();
+                return;
+            }
+            task.destroy();
+            this._tickets.consume();
+            this._shouldPrintDebug &&
+                this._logger.debug(`↑ [DEQ] [id: ${task.id}, key: ${task.key}] - ${this._getStateDebugString(task.priority)}`);
+            void task.run().finally(() => {
+                this._semaphore.release();
+                queueMicrotask(() => this._drain());
+            });
+        }
+    }
+    _getNextExpiryTimestamp() {
+        while (!this._expiryHeap.isEmpty) {
+            const task = this._expiryHeap.peek();
+            if (!task.isActive) {
+                this._expiryHeap.pop();
+                continue;
+            }
+            return task.expiresAt;
+        }
+        return null;
+    }
+    _extractExpiredTasks(now) {
+        const result = [];
+        while (!this._expiryHeap.isEmpty) {
+            const task = this._expiryHeap.peek();
+            if (!task.isActive) {
+                this._expiryHeap.pop();
+                continue;
+            }
+            if (task.expiresAt > now) {
+                break;
+            }
+            this._expiryHeap.pop();
+            const priorityQueue = this._queue.getQueue(task.priority);
+            priorityQueue.remove(task);
+            result.push(task);
+        }
+        return result;
+    }
+    _drainRemainingTasks() {
+        const remaining = [];
+        for (const queue of this._queue.queues()) {
+            while (!queue.isEmpty) {
+                const task = queue.dequeue();
+                remaining.push(task);
+            }
+        }
+        return remaining;
+    }
+    _scheduleDrainTimer(delayMs) {
+        if (this._drainTimer) {
+            return;
+        }
+        this._drainTimer = setTimeout(() => {
+            this._clearDrainTimer();
+            this._drain();
+        }, delayMs);
+    }
+    _recalibrateExpiryTimer(now) {
+        const nextExpiry = this._getNextExpiryTimestamp();
+        if (nextExpiry === null) {
+            this._clearExpiryTimer();
+            this._nextExpiryScheduledAt = null;
+            return;
+        }
+        if (this._nextExpiryScheduledAt === nextExpiry) {
+            return;
+        }
+        this._clearExpiryTimer();
+        const delay = Math.max(0, nextExpiry - now);
+        this._nextExpiryScheduledAt = nextExpiry;
+        this._expiryTimer = setTimeout(() => {
+            this._clearExpiryTimer();
+            this._drain();
+        }, delay);
+    }
+    _clearDrainTimer() {
+        if (this._drainTimer) {
+            clearTimeout(this._drainTimer);
+            this._drainTimer = null;
+        }
+    }
+    _clearExpiryTimer() {
+        if (this._expiryTimer) {
+            clearTimeout(this._expiryTimer);
+            this._expiryTimer = null;
+        }
+    }
+    _getStateDebugString(priority) {
+        return `prt: ${priority} | q: ${this._queue.size}/${this._queue.capacity}`;
+    }
+}
+//# sourceMappingURL=rate-limiter.executor.js.map

package/lib/runtime/semaphore.d.ts

@@ -0,0 +1,9 @@
+/** @internal */
+export declare class Semaphore {
+    private readonly _maxPermits;
+    private _permits;
+    constructor(_maxPermits: number | null);
+    acquire(): boolean;
+    release(): void;
+}
+//# sourceMappingURL=semaphore.d.ts.map

package/lib/runtime/semaphore.js

@@ -0,0 +1,28 @@
+/** @internal */
+export class Semaphore {
+    _maxPermits;
+    _permits;
+    constructor(_maxPermits) {
+        this._maxPermits = _maxPermits;
+        if (_maxPermits !== null && (!Number.isSafeInteger(_maxPermits) || _maxPermits <= 0)) {
+            throw new Error('Maximum permits must be a non-negative integer or null');
+        }
+        this._permits = _maxPermits ?? 0;
+    }
+    acquire() {
+        if (this._maxPermits === null) {
+            return true;
+        }
+        if (this._permits > 0) {
+            this._permits--;
+            return true;
+        }
+        return false;
+    }
+    release() {
+        if (this._maxPermits !== null && this._permits < this._maxPermits) {
+            this._permits++;
+        }
+    }
+}
+//# sourceMappingURL=semaphore.js.map

package/lib/runtime/task.d.ts

@@ -0,0 +1,41 @@
+import { Priority } from '@stimulcross/ds-policy-priority-queue';
+/** @internal */
+export interface TaskOptions {
+    id: string;
+    key: string;
+    priority?: Priority;
+    expiresAt?: number;
+    signal?: AbortSignal;
+}
+/** @internal */
+export declare class Task<T = any> implements PromiseLike<T> {
+    private readonly _task;
+    private readonly _promise;
+    private readonly _resolve;
+    private readonly _reject;
+    private readonly _id;
+    private readonly _key;
+    private readonly _priority;
+    private readonly _expiresAt?;
+    private _signal?;
+    private _abortListener?;
+    private _abortHandler?;
+    private _isActive;
+    private _isAborted;
+    constructor(task: () => T | Promise<T>, { id, key, priority, expiresAt, signal }: TaskOptions);
+    get id(): string;
+    get key(): string;
+    get priority(): Priority;
+    get expiresAt(): number | undefined;
+    get isActive(): boolean;
+    get isCancellable(): boolean;
+    get isAborted(): boolean;
+    run(): Promise<void>;
+    reject(reason: unknown): void;
+    destroy(): void;
+    onAbort(handler: () => void): void;
+    then<TResult1 = T, TResult2 = never>(onfulfilled?: ((value: T) => PromiseLike<TResult1> | TResult1) | null, onrejected?: ((reason: any) => PromiseLike<TResult2> | TResult2) | null): PromiseLike<TResult1 | TResult2>;
+    catch<TResult = never>(onrejected?: ((reason: any) => PromiseLike<TResult> | TResult) | null): PromiseLike<T | TResult>;
+    finally(onfinally?: (() => void) | null): PromiseLike<T>;
+}
+//# sourceMappingURL=task.d.ts.map

package/lib/runtime/task.js

@@ -0,0 +1,101 @@
+import { Priority } from '@stimulcross/ds-policy-priority-queue';
+import { RateLimitErrorCode } from '../enums/rate-limit-error-code.js';
+import { RateLimitError } from '../errors/rate-limit.error.js';
+import { promiseWithResolvers } from '../utils/promise-with-resolvers.js';
+/** @internal */
+export class Task {
+    _task;
+    _promise;
+    _resolve;
+    _reject;
+    _id;
+    _key;
+    _priority;
+    _expiresAt;
+    _signal;
+    _abortListener;
+    _abortHandler;
+    _isActive = true;
+    _isAborted = false;
+    constructor(task, { id, key, priority = Priority.Normal, expiresAt, signal }) {
+        const { promise, resolve, reject } = promiseWithResolvers();
+        this._task = task;
+        this._promise = promise;
+        this._resolve = resolve;
+        this._reject = reject;
+        this._id = id;
+        this._key = key;
+        this._priority = priority;
+        this._expiresAt = expiresAt;
+        if (signal) {
+            this._signal = signal;
+            this._abortListener = () => {
+                this._isActive = false;
+                this._isAborted = true;
+                this._abortHandler?.();
+                this._reject(new RateLimitError(RateLimitErrorCode.Cancelled, undefined, 'Aborted by client'));
+                this.destroy();
+            };
+            this._signal.addEventListener('abort', this._abortListener, { once: true });
+        }
+    }
+    get id() {
+        return this._id;
+    }
+    get key() {
+        return this._key;
+    }
+    get priority() {
+        return this._priority;
+    }
+    get expiresAt() {
+        return this._expiresAt;
+    }
+    get isActive() {
+        return this._isActive;
+    }
+    get isCancellable() {
+        return Boolean(this._signal);
+    }
+    get isAborted() {
+        return this._isAborted;
+    }
+    async run() {
+        this._isActive = false;
+        try {
+            const result = await this._task();
+            this._resolve(result);
+        }
+        catch (e) {
+            this._reject(e);
+        }
+    }
+    reject(reason) {
+        this._isActive = false;
+        this._reject(reason);
+    }
+    destroy() {
+        this._isActive = false;
+        if (this._signal && this._abortListener) {
+            this._signal.removeEventListener('abort', this._abortListener);
+            this._signal = undefined;
+            this._abortListener = undefined;
+        }
+        if (this._abortHandler) {
+            this._abortHandler = undefined;
+        }
+    }
+    onAbort(handler) {
+        this._abortHandler = handler;
+    }
+    then(onfulfilled, onrejected) {
+        return this._promise.then(onfulfilled, onrejected);
+    }
+    catch(onrejected) {
+        return this._promise.catch(onrejected);
+    }
+    finally(onfinally) {
+        return this._promise.finally(onfinally);
+    }
+}
+//# sourceMappingURL=task.js.map

package/{src/types/limit-behavior.ts → lib/types/limit-behavior.d.ts}

@@ -6,3 +6,4 @@
  * - `enqueue` - enqueues the task
  */
 export type LimitBehavior = 'enqueue' | 'reject';
+//# sourceMappingURL=limit-behavior.d.ts.map

package/lib/types/limit-behavior.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=limit-behavior.js.map

package/lib/utils/generate-random-string.d.ts

@@ -0,0 +1,3 @@
+/** @internal */
+export declare function generateRandomString(length?: number): string;
+//# sourceMappingURL=generate-random-string.d.ts.map

package/lib/utils/generate-random-string.js

@@ -0,0 +1,13 @@
+const characters = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+/** @internal */
+export function generateRandomString(length = 7) {
+    if (!Number.isSafeInteger(length) || length < 0) {
+        throw new RangeError(`Invalid length: ${length}. Length must be a positive integer.`);
+    }
+    const result = new Array(length);
+    for (let i = 0; i < length; i++) {
+        result.push(characters.charAt(Math.floor(Math.random() * characters.length)));
+    }
+    return result.join('');
+}
+//# sourceMappingURL=generate-random-string.js.map

package/lib/utils/promise-with-resolvers.d.ts

@@ -0,0 +1,9 @@
+/** @internal */
+export interface PromiseWithResolvers<T = void> {
+    promise: Promise<T>;
+    resolve: (value: T | PromiseLike<T>) => void;
+    reject: (reason?: unknown) => void;
+}
+/** @internal */
+export declare function promiseWithResolvers<T = void>(): PromiseWithResolvers<T>;
+//# sourceMappingURL=promise-with-resolvers.d.ts.map

package/lib/utils/promise-with-resolvers.js

@@ -0,0 +1,15 @@
+/** @internal */
+export function promiseWithResolvers() {
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    if (Promise.withResolvers) {
+        return Promise.withResolvers();
+    }
+    let resolve;
+    let reject;
+    const promise = new Promise((_resolve, _reject) => {
+        resolve = _resolve;
+        reject = _reject;
+    });
+    return { promise, resolve, reject };
+}
+//# sourceMappingURL=promise-with-resolvers.js.map

package/lib/utils/sanitize-error.d.ts

@@ -0,0 +1,3 @@
+/** @internal */
+export declare function sanitizeError(error: unknown): Error;
+//# sourceMappingURL=sanitize-error.d.ts.map

package/lib/utils/sanitize-error.js

@@ -0,0 +1,5 @@
+/** @internal */
+export function sanitizeError(error) {
+    return error instanceof Error ? error : new Error('Non-error thrown. Check "cause" property', { cause: error });
+}
+//# sourceMappingURL=sanitize-error.js.map

package/lib/utils/sanitize-priority.d.ts

@@ -0,0 +1,4 @@
+import { Priority } from '@stimulcross/ds-policy-priority-queue';
+/** @internal */
+export declare function sanitizePriority(priority: number): Priority;
+//# sourceMappingURL=sanitize-priority.d.ts.map

package/lib/utils/sanitize-priority.js

@@ -0,0 +1,18 @@
+import { Priority } from '@stimulcross/ds-policy-priority-queue';
+/** @internal */
+export function sanitizePriority(priority) {
+    if (!Number.isFinite(priority)) {
+        return Priority.Normal;
+    }
+    if (priority < Priority.Lowest) {
+        return Priority.Lowest;
+    }
+    if (priority > Priority.Highest) {
+        return Priority.Highest;
+    }
+    if (!Number.isInteger(priority)) {
+        priority = Math.round(priority);
+    }
+    return priority;
+}
+//# sourceMappingURL=sanitize-priority.js.map

package/lib/utils/validate-cost.d.ts

@@ -0,0 +1,3 @@
+/** @internal */
+export declare function validateCost(cost: number, max?: number, min?: number): void;
+//# sourceMappingURL=validate-cost.d.ts.map

package/lib/utils/validate-cost.js

@@ -0,0 +1,14 @@
+import { InvalidCostError } from '../errors/invalid-cost.error.js';
+/** @internal */
+export function validateCost(cost, max, min) {
+    if (!Number.isSafeInteger(cost) || cost < 0) {
+        throw new InvalidCostError(`Invalid cost: ${cost}. Cost must be a positive integer.`, cost);
+    }
+    if (max !== undefined && cost > max) {
+        throw new InvalidCostError(`Invalid cost: ${cost}. Cost must be greater than or equal to ${max}.`, cost);
+    }
+    if (min !== undefined && cost < min) {
+        throw new InvalidCostError(`Invalid cost: ${cost}. Cost must be greater than or equal to ${min}.`, cost);
+    }
+}
+//# sourceMappingURL=validate-cost.js.map

package/package.json

@@ -1,11 +1,15 @@
 {
   "name": "@stimulcross/rate-limiter",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "A collection of client-side rate limiters for Node.js and browsers.",
+  "type": "module",
   "engines": {
     "node": ">=20"
   },
-  "type": "module",
+  "sideEffects": false,
+  "repository": "github:stimulcross/logger",
+  "author": "Stimul Cross <stimulcross@gmail.com>",
+  "license": "MIT",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
   "exports": {
@@ -66,6 +70,13 @@
     "typescript": "^5.9.3",
     "vitest": "^4.1.0"
   },
+  "files": [
+    "LICENSE",
+    "README.md",
+    "lib",
+    "!lib/**/*.d.ts.map",
+    "!lib/**/*.js.map"
+  ],
   "publishConfig": {
     "access": "public"
   },

package/.editorconfig

@@ -1,21 +0,0 @@
-root = true
-
-[*]
-end_of_line = lf
-insert_final_newline = true
-charset = utf-8
-indent_style = tab
-tab_width = 4
-max_line_length = 120
-
-[*.json]
-indent_style = tab
-indent_size = 4
-
-[package.json]
-indent_style = space
-indent_size = 2
-
-[*.yml]
-indent_style = space
-indent_size = 2

package/.github/workflows/node.yml

@@ -1,87 +0,0 @@
-name: Node.js CI
-
-on:
-  push:
-    branches: [ main ]
-  pull_request:
-    branches: [ main ]
-
-jobs:
-  checks:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Install PNPM
-        uses: pnpm/action-setup@v4
-        with:
-          run_install: false
-
-      - name: Setup Node.js environment
-        uses: actions/setup-node@v4
-        with:
-          node-version: 24
-          cache: pnpm
-
-      - name: Install deps
-        run: pnpm install --frozen-lockfile
-
-      - name: Check formatting
-        run: pnpm run format:check
-
-      - name: Check types
-        run: pnpm run check-types
-
-      - name: Lint
-        run: pnpm run lint
-
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Install PNPM
-        uses: pnpm/action-setup@v4
-        with:
-          run_install: false
-
-      - name: Setup Node.js environment
-        uses: actions/setup-node@v4
-        with:
-          node-version: 24
-          cache: pnpm
-
-      - name: Install deps
-        run: pnpm install --frozen-lockfile
-
-      - name: Build
-        run: pnpm run build
-
-  test:
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        node-version: [ 20, 22, 24 ]
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Install PNPM
-        uses: pnpm/action-setup@v4
-        with:
-          run_install: false
-
-      - name: Use Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v4
-        with:
-          node-version: ${{ matrix.node-version }}
-          cache: pnpm
-
-      - name: Install deps
-        run: pnpm install --frozen-lockfile
-
-      - name: Run tests
-        run: pnpm run test

package/.husky/commit-msg

@@ -1 +0,0 @@
-npx --no -- commitlint -e $1

package/.husky/pre-commit

@@ -1 +0,0 @@
-npx lint-staged

package/.megaignore

@@ -1,8 +0,0 @@
-+sync:.megaignore
--d:node_modules
--d:lib
--f:yarn.lock
--f:yalc.lock
--f:package-lock.json
--f:pnpm-lock.yaml
-

package/.prettierignore

@@ -1,3 +0,0 @@
-docs
-packages/*/lib
-lerna.json

package/commitlint.config.js

@@ -1,8 +0,0 @@
-export default {
-	extends: ['@stimulcross/commitlint-config'],
-	rules: {
-		'body-max-line-length': [2, 'always', 500],
-		'footer-max-line-length': [2, 'always', 500],
-	}
-
-};