@resq-sw/decorators 0.1.0

package/lib/throttle/throttle.js

@@ -0,0 +1,43 @@
+import { throttleFn } from "./throttle.fn.js";
+//#region src/throttle/throttle.ts
+/**
+* Decorator that throttles method calls to once per specified time period.
+*
+* @template T - The type of the class containing the decorated method
+* @param {number} delayMs - The throttle interval in milliseconds
+* @returns {Decorator<T>} The decorator function
+*
+* @throws {Error} When applied to a non-method property
+*
+* @example
+* ```typescript
+* class ResizeHandler {
+*   private width = window.innerWidth;
+*   private height = window.innerHeight;
+*
+*   @throttle(200)
+*   handleResize(): void {
+*     this.width = window.innerWidth;
+*     this.height = window.innerHeight;
+*     this.render();
+*   }
+* }
+*
+* const handler = new ResizeHandler();
+* window.addEventListener('resize', () => handler.handleResize());
+* // handleResize executes at most once every 200ms during resize
+* ```
+*/
+function throttle(delayMs) {
+	return (target, propertyName, descriptor) => {
+		if (descriptor.value) {
+			descriptor.value = throttleFn(descriptor.value, delayMs);
+			return descriptor;
+		}
+		throw new Error("@throttle is applicable only on a methods.");
+	};
+}
+//#endregion
+export { throttle };
+
+//# sourceMappingURL=throttle.js.map

package/lib/throttle/throttle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"throttle.js","names":[],"sources":["../../src/throttle/throttle.ts"],"sourcesContent":["/**\n * Copyright 2026 ResQ\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport type { Decorator, Method } from '../types.js';\nimport { throttleFn } from './throttle.fn.js';\n\n/**\n * Decorator that throttles method calls to once per specified time period.\n *\n * @template T - The type of the class containing the decorated method\n * @param {number} delayMs - The throttle interval in milliseconds\n * @returns {Decorator<T>} The decorator function\n *\n * @throws {Error} When applied to a non-method property\n *\n * @example\n * ```typescript\n * class ResizeHandler {\n *   private width = window.innerWidth;\n *   private height = window.innerHeight;\n *\n *   @throttle(200)\n *   handleResize(): void {\n *     this.width = window.innerWidth;\n *     this.height = window.innerHeight;\n *     this.render();\n *   }\n * }\n *\n * const handler = new ResizeHandler();\n * window.addEventListener('resize', () => handler.handleResize());\n * // handleResize executes at most once every 200ms during resize\n * ```\n */\nexport function throttle<T = any>(delayMs: number): Decorator<T> {\n  return (\n    target: T,\n    propertyName: keyof T,\n    descriptor: TypedPropertyDescriptor<Method<any>>,\n  ): TypedPropertyDescriptor<Method<any>> => {\n    if (descriptor.value) {\n      descriptor.value = throttleFn(descriptor.value, delayMs);\n\n      return descriptor;\n    }\n\n    throw new Error('@throttle is applicable only on a methods.');\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+CA,SAAgB,SAAkB,SAA+B;AAC/D,SACE,QACA,cACA,eACyC;AACzC,MAAI,WAAW,OAAO;AACpB,cAAW,QAAQ,WAAW,WAAW,OAAO,QAAQ;AAExD,UAAO;;AAGT,QAAM,IAAI,MAAM,6CAA6C"}

package/lib/throttle-async/index.d.ts

@@ -0,0 +1,2 @@
+import { throttleAsync } from "./throttle-async.js";
+export { throttleAsync };

package/lib/throttle-async/index.js

@@ -0,0 +1,2 @@
+import { throttleAsync } from "./throttle-async.js";
+export { throttleAsync };

package/lib/throttle-async/throttle-async-executor.d.ts

@@ -0,0 +1,79 @@
+import { AsyncMethod } from "../types.js";
+
+//#region src/throttle-async/throttle-async-executor.d.ts
+/**
+ * Manages the queue and execution of throttled async method calls.
+ * Ensures that only a specified number of calls run concurrently,
+ * queueing additional calls until slots become available.
+ *
+ * @class ThrottleAsyncExecutor
+ * @template D - The resolved type of the async method
+ *
+ * @example
+ * ```typescript
+ * const executor = new ThrottleAsyncExecutor(
+ *   async (data) => await fetchData(data),
+ *   3 // Max 3 concurrent calls
+ * );
+ *
+ * // Execute multiple calls
+ * const promises = [
+ *   executor.exec(this, ['arg1']),
+ *   executor.exec(this, ['arg2']),
+ *   executor.exec(this, ['arg3']),
+ *   executor.exec(this, ['arg4']), // Queued
+ *   executor.exec(this, ['arg5']), // Queued
+ * ];
+ *
+ * const results = await Promise.all(promises);
+ * ```
+ */
+declare class ThrottleAsyncExecutor<D> {
+  private readonly fun;
+  private readonly parallelCalls;
+  /**
+   * Number of calls currently executing.
+   * @private
+   * @type {number}
+   */
+  private onGoingCallsCount;
+  /**
+   * Queue of pending calls waiting to execute.
+   * @private
+   * @type {Queue<CallArgs<D>>}
+   */
+  private readonly callsToRun;
+  /**
+   * Creates a new ThrottleAsyncExecutor instance.
+   *
+   * @param {AsyncMethod<D>} fun - The async method to throttle
+   * @param {number} parallelCalls - Maximum number of concurrent calls allowed
+   */
+  constructor(fun: AsyncMethod<D>, parallelCalls: number);
+  /**
+   * Queues a method call for execution.
+   *
+   * @param {any} context - The `this` context for the method call
+   * @param {any[]} args - The arguments to pass to the method
+   * @returns {Promise<D>} A promise that resolves with the method result
+   *
+   * @example
+   * ```typescript
+   * const executor = new ThrottleAsyncExecutor(myAsyncMethod, 2);
+   *
+   * // Queue a call
+   * const result = await executor.exec(this, ['arg1', 'arg2']);
+   * ```
+   */
+  exec(context: unknown, args: unknown[]): Promise<D>;
+  /**
+   * Attempts to execute the next queued call if capacity allows.
+   *
+   * @private
+   * @returns {void}
+   */
+  private tryCall;
+}
+//#endregion
+export { ThrottleAsyncExecutor };
+//# sourceMappingURL=throttle-async-executor.d.ts.map

package/lib/throttle-async/throttle-async-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"throttle-async-executor.d.ts","names":[],"sources":["../../src/throttle-async/throttle-async-executor.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA8Ca,qBAAA;EAAA,iBAsBQ,GAAA;EAAA,iBACA,aAAA;;;;;;UAjBX,iBAAA;;;;;;mBAOS,UAAA;;;;;;;cASE,GAAA,EAAK,WAAA,CAAY,CAAA,GACjB,aAAA;;;;;;;;;;;;;;;;EAkBnB,IAAA,CAAK,OAAA,WAAkB,IAAA,cAAkB,OAAA,CAAQ,CAAA;;;;;;;UAsBzC,OAAA;AAAA"}

package/lib/throttle-async/throttle-async-executor.js

@@ -0,0 +1,122 @@
+import { Queue } from "../_utils.js";
+//#region src/throttle-async/throttle-async-executor.ts
+/**
+* Copyright 2026 ResQ
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*     http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+/**
+* Manages the queue and execution of throttled async method calls.
+* Ensures that only a specified number of calls run concurrently,
+* queueing additional calls until slots become available.
+*
+* @class ThrottleAsyncExecutor
+* @template D - The resolved type of the async method
+*
+* @example
+* ```typescript
+* const executor = new ThrottleAsyncExecutor(
+*   async (data) => await fetchData(data),
+*   3 // Max 3 concurrent calls
+* );
+*
+* // Execute multiple calls
+* const promises = [
+*   executor.exec(this, ['arg1']),
+*   executor.exec(this, ['arg2']),
+*   executor.exec(this, ['arg3']),
+*   executor.exec(this, ['arg4']), // Queued
+*   executor.exec(this, ['arg5']), // Queued
+* ];
+*
+* const results = await Promise.all(promises);
+* ```
+*/
+var ThrottleAsyncExecutor = class {
+	/**
+	* Number of calls currently executing.
+	* @private
+	* @type {number}
+	*/
+	onGoingCallsCount = 0;
+	/**
+	* Queue of pending calls waiting to execute.
+	* @private
+	* @type {Queue<CallArgs<D>>}
+	*/
+	callsToRun = new Queue();
+	/**
+	* Creates a new ThrottleAsyncExecutor instance.
+	*
+	* @param {AsyncMethod<D>} fun - The async method to throttle
+	* @param {number} parallelCalls - Maximum number of concurrent calls allowed
+	*/
+	constructor(fun, parallelCalls) {
+		this.fun = fun;
+		this.parallelCalls = parallelCalls;
+	}
+	/**
+	* Queues a method call for execution.
+	*
+	* @param {any} context - The `this` context for the method call
+	* @param {any[]} args - The arguments to pass to the method
+	* @returns {Promise<D>} A promise that resolves with the method result
+	*
+	* @example
+	* ```typescript
+	* const executor = new ThrottleAsyncExecutor(myAsyncMethod, 2);
+	*
+	* // Queue a call
+	* const result = await executor.exec(this, ['arg1', 'arg2']);
+	* ```
+	*/
+	exec(context, args) {
+		const callArgs = {
+			context,
+			args,
+			resolve: null,
+			reject: null
+		};
+		this.callsToRun.enqueue(callArgs);
+		const proms = new Promise((resolve, reject) => {
+			callArgs.resolve = resolve;
+			callArgs.reject = reject;
+		});
+		this.tryCall();
+		proms.hell = args[0];
+		return proms;
+	}
+	/**
+	* Attempts to execute the next queued call if capacity allows.
+	*
+	* @private
+	* @returns {void}
+	*/
+	tryCall() {
+		if (this.callsToRun.getSize() > 0 && this.onGoingCallsCount < this.parallelCalls) {
+			const callArgs = this.callsToRun.dequeue();
+			if (callArgs) {
+				const { context, args, resolve, reject } = callArgs;
+				this.onGoingCallsCount += 1;
+				this.fun.apply(context, args).then(resolve).catch(reject).finally(() => {
+					this.onGoingCallsCount -= 1;
+					this.tryCall();
+				});
+			}
+		}
+	}
+};
+//#endregion
+export { ThrottleAsyncExecutor };
+
+//# sourceMappingURL=throttle-async-executor.js.map

package/lib/throttle-async/throttle-async-executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"throttle-async-executor.js","names":[],"sources":["../../src/throttle-async/throttle-async-executor.ts"],"sourcesContent":["/**\n * Copyright 2026 ResQ\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { Queue } from '../_utils.js';\nimport type { AsyncMethod } from '../types.js';\n\n/**\n * Manages the queue and execution of throttled async method calls.\n * Ensures that only a specified number of calls run concurrently,\n * queueing additional calls until slots become available.\n *\n * @class ThrottleAsyncExecutor\n * @template D - The resolved type of the async method\n *\n * @example\n * ```typescript\n * const executor = new ThrottleAsyncExecutor(\n *   async (data) => await fetchData(data),\n *   3 // Max 3 concurrent calls\n * );\n *\n * // Execute multiple calls\n * const promises = [\n *   executor.exec(this, ['arg1']),\n *   executor.exec(this, ['arg2']),\n *   executor.exec(this, ['arg3']),\n *   executor.exec(this, ['arg4']), // Queued\n *   executor.exec(this, ['arg5']), // Queued\n * ];\n *\n * const results = await Promise.all(promises);\n * ```\n */\nexport class ThrottleAsyncExecutor<D> {\n  /**\n   * Number of calls currently executing.\n   * @private\n   * @type {number}\n   */\n  private onGoingCallsCount = 0;\n\n  /**\n   * Queue of pending calls waiting to execute.\n   * @private\n   * @type {Queue<CallArgs<D>>}\n   */\n  private readonly callsToRun = new Queue<CallArgs<D>>();\n\n  /**\n   * Creates a new ThrottleAsyncExecutor instance.\n   *\n   * @param {AsyncMethod<D>} fun - The async method to throttle\n   * @param {number} parallelCalls - Maximum number of concurrent calls allowed\n   */\n  constructor(\n    private readonly fun: AsyncMethod<D>,\n    private readonly parallelCalls: number,\n  ) {}\n\n  /**\n   * Queues a method call for execution.\n   *\n   * @param {any} context - The `this` context for the method call\n   * @param {any[]} args - The arguments to pass to the method\n   * @returns {Promise<D>} A promise that resolves with the method result\n   *\n   * @example\n   * ```typescript\n   * const executor = new ThrottleAsyncExecutor(myAsyncMethod, 2);\n   *\n   * // Queue a call\n   * const result = await executor.exec(this, ['arg1', 'arg2']);\n   * ```\n   */\n  exec(context: unknown, args: unknown[]): Promise<D> {\n    const callArgs: CallArgs<D> = { context, args, resolve: null!, reject: null! };\n    this.callsToRun.enqueue(callArgs);\n\n    const proms = new Promise<D>((resolve, reject) => {\n      callArgs.resolve = resolve;\n      callArgs.reject = reject;\n    });\n\n    this.tryCall();\n\n    (proms as unknown as { hell: unknown }).hell = args[0];\n\n    return proms;\n  }\n\n  /**\n   * Attempts to execute the next queued call if capacity allows.\n   *\n   * @private\n   * @returns {void}\n   */\n  private tryCall(): void {\n    if (this.callsToRun.getSize() > 0 && this.onGoingCallsCount < this.parallelCalls) {\n      const callArgs = this.callsToRun.dequeue();\n      if (callArgs) {\n        const { context, args, resolve, reject } = callArgs;\n        this.onGoingCallsCount += 1;\n        this.fun\n          .apply(context, args)\n          .then(resolve)\n          .catch(reject)\n          .finally(() => {\n            this.onGoingCallsCount -= 1;\n            this.tryCall();\n          });\n      }\n    }\n  }\n}\n\n/**\n * Arguments for a queued async call.\n *\n * @interface CallArgs\n * @template T - The resolved type of the async call\n * @property {unknown} context - The `this` context\n * @property {unknown[]} args - The method arguments\n * @property {(value: T | PromiseLike<T>) => void} resolve - Promise resolve function\n * @property {(reason?: unknown) => void} reject - Promise reject function\n */\ninterface CallArgs<T> {\n  context: unknown;\n  args: unknown[];\n  resolve: (value: T | PromiseLike<T>) => void;\n  reject: (reason?: unknown) => void;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8CA,IAAa,wBAAb,MAAsC;;;;;;CAMpC,oBAA4B;;;;;;CAO5B,aAA8B,IAAI,OAAoB;;;;;;;CAQtD,YACE,KACA,eACA;AAFiB,OAAA,MAAA;AACA,OAAA,gBAAA;;;;;;;;;;;;;;;;;CAkBnB,KAAK,SAAkB,MAA6B;EAClD,MAAM,WAAwB;GAAE;GAAS;GAAM,SAAS;GAAO,QAAQ;GAAO;AAC9E,OAAK,WAAW,QAAQ,SAAS;EAEjC,MAAM,QAAQ,IAAI,SAAY,SAAS,WAAW;AAChD,YAAS,UAAU;AACnB,YAAS,SAAS;IAClB;AAEF,OAAK,SAAS;AAEb,QAAuC,OAAO,KAAK;AAEpD,SAAO;;;;;;;;CAST,UAAwB;AACtB,MAAI,KAAK,WAAW,SAAS,GAAG,KAAK,KAAK,oBAAoB,KAAK,eAAe;GAChF,MAAM,WAAW,KAAK,WAAW,SAAS;AAC1C,OAAI,UAAU;IACZ,MAAM,EAAE,SAAS,MAAM,SAAS,WAAW;AAC3C,SAAK,qBAAqB;AAC1B,SAAK,IACF,MAAM,SAAS,KAAK,CACpB,KAAK,QAAQ,CACb,MAAM,OAAO,CACb,cAAc;AACb,UAAK,qBAAqB;AAC1B,UAAK,SAAS;MACd"}

package/lib/throttle-async/throttle-async.d.ts

@@ -0,0 +1,68 @@
+import { Decorator } from "../types.js";
+
+//#region src/throttle-async/throttle-async.d.ts
+/**
+* @fileoverview ThrottleAsync decorator - limits the number of concurrent
+* async method calls. Additional calls are queued and executed when slots
+* become available.
+*
+* @module @resq/typescript/decorators/throttle-async
+*
+* @example
+* ```typescript
+* class ApiService {
+*   @throttleAsync(3) // Max 3 concurrent requests
+*   async fetchData(endpoint: string): Promise<Data> {
+*     return fetch(endpoint).then(r => r.json());
+*   }
+* }
+*
+* const api = new ApiService();
+*
+* // These will execute 3 at a time
+* const results = await Promise.all([
+*   api.fetchData('/api/data1'),
+*   api.fetchData('/api/data2'),
+*   api.fetchData('/api/data3'),
+*   api.fetchData('/api/data4'), // Queued until a slot frees up
+*   api.fetchData('/api/data5'), // Queued until a slot frees up
+* ]);
+* ```
+*
+* @copyright Copyright (c) 2026 ResQ
+* @license MIT
+*/
+/**
+ * Decorator that limits concurrent async method calls.
+ * Excess calls are queued and executed when slots become available.
+ *
+ * @template T - The type of the class containing the decorated method
+ * @template D - The resolved type of the async method
+ * @param {number} [parallelCalls=1] - Maximum number of concurrent calls allowed
+ * @returns {Decorator<T>} The decorator function
+ *
+ * @throws {Error} When applied to a non-method property
+ *
+ * @example
+ * ```typescript
+ * class BatchProcessor {
+ *   // Process up to 5 items concurrently
+ *   @throttleAsync(5)
+ *   async processItem(item: Item): Promise<Result> {
+ *     return await this.performHeavyProcessing(item);
+ *   }
+ * }
+ *
+ * const processor = new BatchProcessor();
+ * const items = Array.from({ length: 100 }, (_, i) => ({ id: i }));
+ *
+ * // Process 100 items, 5 at a time
+ * const results = await Promise.all(
+ *   items.map(item => processor.processItem(item))
+ * );
+ * ```
+ */
+declare function throttleAsync<T = any, D = any>(parallelCalls?: number): Decorator<T>;
+//#endregion
+export { throttleAsync };
+//# sourceMappingURL=throttle-async.d.ts.map

package/lib/throttle-async/throttle-async.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"throttle-async.d.ts","names":[],"sources":["../../src/throttle-async/throttle-async.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAiFgB,aAAA,kBAAA,CAAgC,aAAA,YAAyB,SAAA,CAAU,CAAA"}

package/lib/throttle-async/throttle-async.fn.d.ts

@@ -0,0 +1,41 @@
+import { AsyncMethod } from "../types.js";
+
+//#region src/throttle-async/throttle-async.fn.d.ts
+/**
+ * Wraps an async method to limit concurrent executions.
+ *
+ * @template D - The resolved type of the async method
+ * @template A - The argument types of the original method
+ * @param {AsyncMethod<D, A>} originalMethod - The async method to throttle
+ * @param {number} [parallelCalls=1] - Maximum number of concurrent calls
+ * @returns {AsyncMethod<D, A>} The throttled async method
+ *
+ * @example
+ * ```typescript
+ * class ApiClient {
+ *   async fetchUser(userId: string): Promise<User> {
+ *     return fetch(`/api/users/${userId}`).then(r => r.json());
+ *   }
+ * }
+ *
+ * const client = new ApiClient();
+ *
+ * // Limit to 2 concurrent requests
+ * const throttledFetch = throttleAsyncFn(
+ *   client.fetchUser.bind(client),
+ *   2
+ * );
+ *
+ * // Execute multiple calls, only 2 run concurrently
+ * const users = await Promise.all([
+ *   throttledFetch('1'), // Starts immediately
+ *   throttledFetch('2'), // Starts immediately
+ *   throttledFetch('3'), // Queued, starts when 1 or 2 completes
+ *   throttledFetch('4'), // Queued, starts when slot available
+ * ]);
+ * ```
+ */
+declare function throttleAsyncFn<D = any, A extends any[] = any[]>(originalMethod: AsyncMethod<D, A>, parallelCalls?: number): AsyncMethod<D, A>;
+//#endregion
+export { throttleAsyncFn };
+//# sourceMappingURL=throttle-async.fn.d.ts.map

package/lib/throttle-async/throttle-async.fn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"throttle-async.fn.d.ts","names":[],"sources":["../../src/throttle-async/throttle-async.fn.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAqDgB,eAAA,kCAAA,CACd,cAAA,EAAgB,WAAA,CAAY,CAAA,EAAG,CAAA,GAC/B,aAAA,YACC,WAAA,CAAY,CAAA,EAAG,CAAA"}

package/lib/throttle-async/throttle-async.fn.js

@@ -0,0 +1,46 @@
+import { ThrottleAsyncExecutor } from "./throttle-async-executor.js";
+//#region src/throttle-async/throttle-async.fn.ts
+/**
+* Wraps an async method to limit concurrent executions.
+*
+* @template D - The resolved type of the async method
+* @template A - The argument types of the original method
+* @param {AsyncMethod<D, A>} originalMethod - The async method to throttle
+* @param {number} [parallelCalls=1] - Maximum number of concurrent calls
+* @returns {AsyncMethod<D, A>} The throttled async method
+*
+* @example
+* ```typescript
+* class ApiClient {
+*   async fetchUser(userId: string): Promise<User> {
+*     return fetch(`/api/users/${userId}`).then(r => r.json());
+*   }
+* }
+*
+* const client = new ApiClient();
+*
+* // Limit to 2 concurrent requests
+* const throttledFetch = throttleAsyncFn(
+*   client.fetchUser.bind(client),
+*   2
+* );
+*
+* // Execute multiple calls, only 2 run concurrently
+* const users = await Promise.all([
+*   throttledFetch('1'), // Starts immediately
+*   throttledFetch('2'), // Starts immediately
+*   throttledFetch('3'), // Queued, starts when 1 or 2 completes
+*   throttledFetch('4'), // Queued, starts when slot available
+* ]);
+* ```
+*/
+function throttleAsyncFn(originalMethod, parallelCalls = 1) {
+	const executor = new ThrottleAsyncExecutor(originalMethod, parallelCalls);
+	return function(...args) {
+		return executor.exec(this, args);
+	};
+}
+//#endregion
+export { throttleAsyncFn };
+
+//# sourceMappingURL=throttle-async.fn.js.map

package/lib/throttle-async/throttle-async.fn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"throttle-async.fn.js","names":[],"sources":["../../src/throttle-async/throttle-async.fn.ts"],"sourcesContent":["/**\n * Copyright 2026 ResQ\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport type { AsyncMethod } from '../types.js';\nimport { ThrottleAsyncExecutor } from './throttle-async-executor.js';\n\n/**\n * Wraps an async method to limit concurrent executions.\n *\n * @template D - The resolved type of the async method\n * @template A - The argument types of the original method\n * @param {AsyncMethod<D, A>} originalMethod - The async method to throttle\n * @param {number} [parallelCalls=1] - Maximum number of concurrent calls\n * @returns {AsyncMethod<D, A>} The throttled async method\n *\n * @example\n * ```typescript\n * class ApiClient {\n *   async fetchUser(userId: string): Promise<User> {\n *     return fetch(`/api/users/${userId}`).then(r => r.json());\n *   }\n * }\n *\n * const client = new ApiClient();\n *\n * // Limit to 2 concurrent requests\n * const throttledFetch = throttleAsyncFn(\n *   client.fetchUser.bind(client),\n *   2\n * );\n *\n * // Execute multiple calls, only 2 run concurrently\n * const users = await Promise.all([\n *   throttledFetch('1'), // Starts immediately\n *   throttledFetch('2'), // Starts immediately\n *   throttledFetch('3'), // Queued, starts when 1 or 2 completes\n *   throttledFetch('4'), // Queued, starts when slot available\n * ]);\n * ```\n */\nexport function throttleAsyncFn<D = any, A extends any[] = any[]>(\n  originalMethod: AsyncMethod<D, A>,\n  parallelCalls = 1,\n): AsyncMethod<D, A> {\n  const executor = new ThrottleAsyncExecutor(originalMethod, parallelCalls);\n\n  return function (this: any, ...args: A): Promise<D> {\n    return executor.exec(this, args);\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqDA,SAAgB,gBACd,gBACA,gBAAgB,GACG;CACnB,MAAM,WAAW,IAAI,sBAAsB,gBAAgB,cAAc;AAEzE,QAAO,SAAqB,GAAG,MAAqB;AAClD,SAAO,SAAS,KAAK,MAAM,KAAK"}

package/lib/throttle-async/throttle-async.js

@@ -0,0 +1,45 @@
+import { throttleAsyncFn } from "./throttle-async.fn.js";
+//#region src/throttle-async/throttle-async.ts
+/**
+* Decorator that limits concurrent async method calls.
+* Excess calls are queued and executed when slots become available.
+*
+* @template T - The type of the class containing the decorated method
+* @template D - The resolved type of the async method
+* @param {number} [parallelCalls=1] - Maximum number of concurrent calls allowed
+* @returns {Decorator<T>} The decorator function
+*
+* @throws {Error} When applied to a non-method property
+*
+* @example
+* ```typescript
+* class BatchProcessor {
+*   // Process up to 5 items concurrently
+*   @throttleAsync(5)
+*   async processItem(item: Item): Promise<Result> {
+*     return await this.performHeavyProcessing(item);
+*   }
+* }
+*
+* const processor = new BatchProcessor();
+* const items = Array.from({ length: 100 }, (_, i) => ({ id: i }));
+*
+* // Process 100 items, 5 at a time
+* const results = await Promise.all(
+*   items.map(item => processor.processItem(item))
+* );
+* ```
+*/
+function throttleAsync(parallelCalls) {
+	return (target, propertyName, descriptor) => {
+		if (descriptor.value) {
+			descriptor.value = throttleAsyncFn(descriptor.value, parallelCalls);
+			return descriptor;
+		}
+		throw new Error("@throttleAsync is applicable only on a methods.");
+	};
+}
+//#endregion
+export { throttleAsync };
+
+//# sourceMappingURL=throttle-async.js.map

package/lib/throttle-async/throttle-async.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"throttle-async.js","names":[],"sources":["../../src/throttle-async/throttle-async.ts"],"sourcesContent":["/**\n * Copyright 2026 ResQ\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * @fileoverview ThrottleAsync decorator - limits the number of concurrent\n * async method calls. Additional calls are queued and executed when slots\n * become available.\n *\n * @module @resq/typescript/decorators/throttle-async\n *\n * @example\n * ```typescript\n * class ApiService {\n *   @throttleAsync(3) // Max 3 concurrent requests\n *   async fetchData(endpoint: string): Promise<Data> {\n *     return fetch(endpoint).then(r => r.json());\n *   }\n * }\n *\n * const api = new ApiService();\n *\n * // These will execute 3 at a time\n * const results = await Promise.all([\n *   api.fetchData('/api/data1'),\n *   api.fetchData('/api/data2'),\n *   api.fetchData('/api/data3'),\n *   api.fetchData('/api/data4'), // Queued until a slot frees up\n *   api.fetchData('/api/data5'), // Queued until a slot frees up\n * ]);\n * ```\n *\n * @copyright Copyright (c) 2026 ResQ\n * @license MIT\n */\n\nimport type { AsyncMethod, Decorator } from '../types.js';\nimport { throttleAsyncFn } from './throttle-async.fn.js';\n\n/**\n * Decorator that limits concurrent async method calls.\n * Excess calls are queued and executed when slots become available.\n *\n * @template T - The type of the class containing the decorated method\n * @template D - The resolved type of the async method\n * @param {number} [parallelCalls=1] - Maximum number of concurrent calls allowed\n * @returns {Decorator<T>} The decorator function\n *\n * @throws {Error} When applied to a non-method property\n *\n * @example\n * ```typescript\n * class BatchProcessor {\n *   // Process up to 5 items concurrently\n *   @throttleAsync(5)\n *   async processItem(item: Item): Promise<Result> {\n *     return await this.performHeavyProcessing(item);\n *   }\n * }\n *\n * const processor = new BatchProcessor();\n * const items = Array.from({ length: 100 }, (_, i) => ({ id: i }));\n *\n * // Process 100 items, 5 at a time\n * const results = await Promise.all(\n *   items.map(item => processor.processItem(item))\n * );\n * ```\n */\nexport function throttleAsync<T = any, D = any>(parallelCalls?: number): Decorator<T> {\n  return (\n    target: T,\n    propertyName: keyof T,\n    descriptor: TypedPropertyDescriptor<AsyncMethod<any>>,\n  ): TypedPropertyDescriptor<AsyncMethod<D>> => {\n    if (descriptor.value) {\n      descriptor.value = throttleAsyncFn(descriptor.value, parallelCalls);\n\n      return descriptor;\n    }\n\n    throw new Error('@throttleAsync is applicable only on a methods.');\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiFA,SAAgB,cAAgC,eAAsC;AACpF,SACE,QACA,cACA,eAC4C;AAC5C,MAAI,WAAW,OAAO;AACpB,cAAW,QAAQ,gBAAgB,WAAW,OAAO,cAAc;AAEnE,UAAO;;AAGT,QAAM,IAAI,MAAM,kDAAkD"}

package/lib/types.d.ts

@@ -0,0 +1,81 @@
+//#region src/types.d.ts
+/**
+ * Copyright 2026 ResQ
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * A generic method type used throughout decorators.
+ *
+ * @template D - The return type of the method
+ * @template A - The argument types of the method (as an array)
+ *
+ * @example
+ * ```typescript
+ * const myMethod: Method<number, [string, boolean]> = (name, active) => {
+ *   return active ? name.length : 0;
+ * };
+ * ```
+ */
+type Method<D = any, A extends any[] = any[]> = (...args: A) => D;
+/**
+ * A generic decorator type for method decorators.
+ *
+ * @template T - The class type containing the method
+ *
+ * @example
+ * ```typescript
+ * const myDecorator: Decorator<MyClass> = (target, propertyName, descriptor) => {
+ *   // Decorator implementation
+ *   return descriptor;
+ * };
+ * ```
+ */
+type Decorator<T = any> = (target: T, propertyName: keyof T, descriptor: TypedPropertyDescriptor<Method<any>>) => TypedPropertyDescriptor<Method<any>>;
+/**
+ * A generic async method type.
+ *
+ * @template D - The resolved type of the Promise
+ * @template A - The argument types of the method (as an array)
+ *
+ * @example
+ * ```typescript
+ * const fetchData: AsyncMethod<User, [string]> = async (userId) => {
+ *   return await api.getUser(userId);
+ * };
+ * ```
+ */
+type AsyncMethod<D = any, A extends any[] = any[]> = (...args: A) => Promise<D>;
+/**
+ * A decorator type specifically for async methods.
+ *
+ * @template T - The class type containing the method
+ *
+ * @example
+ * ```typescript
+ * const asyncDecorator: AsyncDecorator<MyClass> = (target, propertyName, descriptor) => {
+ *   const original = descriptor.value!;
+ *   descriptor.value = async function(...args) {
+ *     console.log('Before async call');
+ *     const result = await original.apply(this, args);
+ *     console.log('After async call');
+ *     return result;
+ *   };
+ *   return descriptor;
+ * };
+ * ```
+ */
+type AsyncDecorator<T = any> = (target: T, propertyName: keyof T, descriptor: TypedPropertyDescriptor<AsyncMethod<any>>) => TypedPropertyDescriptor<AsyncMethod<any>>;
+//#endregion
+export { AsyncDecorator, AsyncMethod, Decorator, Method };
+//# sourceMappingURL=types.d.ts.map

package/lib/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","names":[],"sources":["../src/types.ts"],"mappings":";;AA8BA;;;;;;;;;;;AAgBA;;;;;;;;;;;;;;;;KAhBY,MAAA,yCAA+C,IAAA,EAAM,CAAA,KAAM,CAAA;;;;;;;AAoCvE;;;;;;;KApBY,SAAA,aACV,MAAA,EAAQ,CAAA,EACR,YAAA,QAAoB,CAAA,EACpB,UAAA,EAAY,uBAAA,CAAwB,MAAA,WACjC,uBAAA,CAAwB,MAAA;;;;;;;;;AAsC7B;;;;;KAtBY,WAAA,yCAAoD,IAAA,EAAM,CAAA,KAAM,OAAA,CAAQ,CAAA;;;;;;;;;;;;;;;;;;;;KAsBxE,cAAA,aACV,MAAA,EAAQ,CAAA,EACR,YAAA,QAAoB,CAAA,EACpB,UAAA,EAAY,uBAAA,CAAwB,WAAA,WACjC,uBAAA,CAAwB,WAAA"}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@resq-sw/decorators",
+  "version": "0.1.0",
+  "description": "TypeScript method and class decorators for caching, rate limiting, control flow, and observability",
+  "license": "Apache-2.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js",
+      "default": "./lib/index.js"
+    }
+  },
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "files": ["lib", "README.md"],
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "tsdown": "^0.21.7",
+    "typescript": "5.9.3",
+    "vitest": "3.2.4"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/resq-software/npm.git",
+    "directory": "packages/decorators"
+  },
+  "keywords": ["decorators", "memoize", "throttle", "debounce", "rate-limit", "typescript"],
+  "engines": {
+    "node": ">=20.19.0"
+  }
+}