@resq-sw/decorators 0.1.0

package/lib/memoize-async/memoize-async.types.d.ts

@@ -0,0 +1,74 @@
+import { Cache, KeyResolver, Memoizable } from "../memoize/memoize.types.js";
+
+//#region src/memoize-async/memoize-async.types.d.ts
+/**
+ * Type for the @memoizeAsync decorator function.
+ * Similar to Memoizable but for async methods.
+ *
+ * @template T - The type of the class containing the decorated method
+ * @template D - The resolved type of the async method
+ */
+type AsyncMemoizable<T, D> = Memoizable<T, Promise<D>>;
+/**
+ * Interface for async cache implementations used by the memoizeAsync decorator.
+ *
+ * @interface AsyncCache
+ * @template D - The type of values stored in the cache
+ * @property {(key: string, value: D) => Promise<void>} set - Store a value in the cache asynchronously
+ * @property {(key: string) => Promise<D> | Promise<null>} get - Retrieve a value from the cache asynchronously
+ * @property {(key: string) => Promise<void>} delete - Remove a value from the cache asynchronously
+ * @property {(key: string) => Promise<boolean>} has - Check if a key exists in the cache asynchronously
+ *
+ * @example
+ * ```typescript
+ * const redisCache: AsyncCache<User> = {
+ *   set: async (key, value) => await redis.set(key, JSON.stringify(value)),
+ *   get: async (key) => {
+ *     const data = await redis.get(key);
+ *     return data ? JSON.parse(data) : null;
+ *   },
+ *   delete: async (key) => await redis.del(key),
+ *   has: async (key) => await redis.exists(key) > 0
+ * };
+ * ```
+ */
+interface AsyncCache<D> {
+  /** Store a value in the cache asynchronously */
+  set: (key: string, value: D) => Promise<void>;
+  /** Retrieve a value from the cache asynchronously */
+  get: (key: string) => Promise<D> | Promise<null>;
+  /** Remove a value from the cache asynchronously */
+  delete: (key: string) => Promise<void>;
+  /** Check if a key exists in the cache asynchronously */
+  has: (key: string) => Promise<boolean>;
+}
+/**
+ * Configuration options for the @memoizeAsync decorator.
+ *
+ * @interface AsyncMemoizeConfig
+ * @template T - The type of the class containing the decorated method
+ * @template D - The resolved type of the async method
+ * @property {Cache<D> | AsyncCache<D>} [cache] - Custom cache implementation (sync or async)
+ * @property {KeyResolver | keyof T} [keyResolver] - Function or method name for generating cache keys
+ * @property {number} [expirationTimeMs] - Time in milliseconds after which cached values expire
+ *
+ * @example
+ * ```typescript
+ * const config: AsyncMemoizeConfig<ApiService, User> = {
+ *   cache: redisCache,
+ *   keyResolver: (userId) => `user:${userId}`,
+ *   expirationTimeMs: 300000
+ * };
+ * ```
+ */
+interface AsyncMemoizeConfig<T, D> {
+  /** Custom cache implementation (sync or async) */
+  cache?: Cache<D> | AsyncCache<D>;
+  /** Function or method name for generating cache keys */
+  keyResolver?: KeyResolver | keyof T;
+  /** Time in milliseconds after which cached values expire */
+  expirationTimeMs?: number;
+}
+//#endregion
+export { AsyncCache, AsyncMemoizable, AsyncMemoizeConfig };
+//# sourceMappingURL=memoize-async.types.d.ts.map

package/lib/memoize-async/memoize-async.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memoize-async.types.d.ts","names":[],"sources":["../../src/memoize-async/memoize-async.types.ts"],"mappings":";;;;;;;AAkDA;;;KAzBY,eAAA,SAAwB,UAAA,CAAW,CAAA,EAAG,OAAA,CAAQ,CAAA;;;;;;;;;;;;;;;;;;;;;;;;UAyBzC,UAAA;EAQO;EANtB,GAAA,GAAM,GAAA,UAAa,KAAA,EAAO,CAAA,KAAM,OAAA;EAMH;EAJ7B,GAAA,GAAM,GAAA,aAAgB,OAAA,CAAQ,CAAA,IAAK,OAAA;EA0BF;EAxBjC,MAAA,GAAS,GAAA,aAAgB,OAAA;EA0BX;EAxBd,GAAA,GAAM,GAAA,aAAgB,OAAA;AAAA;;;;;;;;;;;;;;;;;;;;UAsBP,kBAAA;;EAEf,KAAA,GAAQ,KAAA,CAAM,CAAA,IAAK,UAAA,CAAW,CAAA;;EAE9B,WAAA,GAAc,WAAA,SAAoB,CAAA;;EAElC,gBAAA;AAAA"}

package/lib/observer/index.d.ts

@@ -0,0 +1,3 @@
+import { observe } from "./observer.js";
+import { ObserverCallback } from "./observer.types.js";
+export { ObserverCallback, observe };

package/lib/observer/index.js

@@ -0,0 +1,2 @@
+import { observe } from "./observer.js";
+export { observe };

package/lib/observer/observer.d.ts

@@ -0,0 +1,54 @@
+import { ObserverCallback } from "./observer.types.js";
+
+//#region src/observer/observer.d.ts
+/**
+ * Observe all changes of a property. All assignments will be logged to the console.
+ *
+ * @param {object} target - The class prototype
+ * @param {string | symbol} propertyKey - The property key
+ * @returns {void}
+ *
+ * @example
+ * ```typescript
+ * class Counter {
+ *   @observe
+ *   value: number = 0;
+ * }
+ *
+ * const counter = new Counter();
+ * counter.value = 5; // Logs: "setting property Counter#value = 5"
+ * counter.value = 10; // Logs: "setting property Counter#value = 10"
+ * ```
+ */
+declare function observe(target: object, propertyKey: string | symbol): void;
+/**
+ * Observe all changes of a property and invoke a provided callback on each assignment.
+ *
+ * @template T - The type of the property value
+ * @param {ObserverCallback<T>} cb - Callback to execute on assignment of observed variable
+ * @returns {PropertyDecorator} The property decorator
+ *
+ * @example
+ * ```typescript
+ * class User {
+ *   @observe((value) => {
+ *     console.log('Email changed:', value);
+ *     validateEmail(value);
+ *   })
+ *   email: string = '';
+ *
+ *   @observe((value) => {
+ *     metrics.gauge('user.age', value);
+ *   })
+ *   age: number = 0;
+ * }
+ *
+ * const user = new User();
+ * user.email = 'test@example.com'; // Logs and validates
+ * user.age = 25; // Records metric
+ * ```
+ */
+declare function observe<T>(cb: ObserverCallback<T>): PropertyDecorator;
+//#endregion
+export { observe };
+//# sourceMappingURL=observer.d.ts.map

package/lib/observer/observer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observer.d.ts","names":[],"sources":["../../src/observer/observer.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;iBA4FgB,OAAA,CAAQ,MAAA,UAAgB,WAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA6BxB,OAAA,GAAA,CAAW,EAAA,EAAI,gBAAA,CAAiB,CAAA,IAAK,iBAAA"}

package/lib/observer/observer.js

@@ -0,0 +1,85 @@
+import { isFunction } from "../_utils.js";
+//#region src/observer/observer.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.
+*/
+/**
+* @fileoverview Observer decorator - observes property changes and invokes
+* a callback when the property value changes.
+*
+* @module @resq/typescript/decorators/observer
+*
+* @example
+* ```typescript
+* class Component {
+*   @observe
+*   count: number = 0;
+*
+*   @observe((newValue) => {
+*     console.log('Name changed to:', newValue);
+*   })
+*   name: string = '';
+* }
+*
+* const comp = new Component();
+* comp.count = 5; // Logs: "setting property Component#count = 5"
+* comp.name = 'John'; // Logs: "Name changed to: John"
+* ```
+*
+* @copyright Copyright (c) 2026 ResQ
+* @license MIT
+*/
+/**
+* Creates a property decorator factory that observes property changes.
+*
+* @template T - The type of the property value
+* @param {ObserverCallback<T>} [cb] - Optional callback to invoke on changes
+* @returns {PropertyDecorator} The property decorator
+*/
+function factory(cb) {
+	return (target, propertyKey) => {
+		let value;
+		const { name } = target.constructor;
+		Object.defineProperty(target, propertyKey, {
+			set(newValue) {
+				value = newValue;
+				if (cb) cb(newValue);
+				else console.log(`setting property ${name}#${String(propertyKey)} = ${newValue}`);
+			},
+			get() {
+				return value;
+			}
+		});
+	};
+}
+/**
+* Overloaded function for observing property changes.
+* Can be used with or without a custom callback.
+*
+* @param {object | ObserverCallback<T>} targetOrCb - Either the class prototype or a callback function
+* @param {string | symbol} [propertyKey] - The property key (when used without callback)
+* @returns {void | PropertyDecorator} Either void or the decorator function
+*
+* @throws {TypeError} When used with incorrect parameters
+*/
+function observe(targetOrCb, propertyKey) {
+	if (propertyKey && !isFunction(targetOrCb)) return factory()(targetOrCb, propertyKey);
+	if (isFunction(targetOrCb)) return factory(targetOrCb);
+	throw new TypeError("@observe not used with correct parameters!");
+}
+//#endregion
+export { observe };
+
+//# sourceMappingURL=observer.js.map

package/lib/observer/observer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observer.js","names":[],"sources":["../../src/observer/observer.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 Observer decorator - observes property changes and invokes\n * a callback when the property value changes.\n *\n * @module @resq/typescript/decorators/observer\n *\n * @example\n * ```typescript\n * class Component {\n *   @observe\n *   count: number = 0;\n *\n *   @observe((newValue) => {\n *     console.log('Name changed to:', newValue);\n *   })\n *   name: string = '';\n * }\n *\n * const comp = new Component();\n * comp.count = 5; // Logs: \"setting property Component#count = 5\"\n * comp.name = 'John'; // Logs: \"Name changed to: John\"\n * ```\n *\n * @copyright Copyright (c) 2026 ResQ\n * @license MIT\n */\n\nimport { isFunction } from '../_utils.js';\nimport type { ObserverCallback } from './index.js';\n\n/**\n * Creates a property decorator factory that observes property changes.\n *\n * @template T - The type of the property value\n * @param {ObserverCallback<T>} [cb] - Optional callback to invoke on changes\n * @returns {PropertyDecorator} The property decorator\n */\nfunction factory<T>(cb?: ObserverCallback<T>): PropertyDecorator {\n  return (target: object, propertyKey: string | symbol) => {\n    let value: T;\n    const { name } = target.constructor;\n    Object.defineProperty(target, propertyKey, {\n      set(newValue: T) {\n        value = newValue;\n        if (cb) {\n          cb(newValue);\n        } else {\n          console.log(`setting property ${name}#${String(propertyKey)} = ${newValue}`);\n        }\n      },\n      get() {\n        return value;\n      },\n    });\n  };\n}\n\n/**\n * Observe all changes of a property. All assignments will be logged to the console.\n *\n * @param {object} target - The class prototype\n * @param {string | symbol} propertyKey - The property key\n * @returns {void}\n *\n * @example\n * ```typescript\n * class Counter {\n *   @observe\n *   value: number = 0;\n * }\n *\n * const counter = new Counter();\n * counter.value = 5; // Logs: \"setting property Counter#value = 5\"\n * counter.value = 10; // Logs: \"setting property Counter#value = 10\"\n * ```\n */\nexport function observe(target: object, propertyKey: string | symbol): void;\n\n/**\n * Observe all changes of a property and invoke a provided callback on each assignment.\n *\n * @template T - The type of the property value\n * @param {ObserverCallback<T>} cb - Callback to execute on assignment of observed variable\n * @returns {PropertyDecorator} The property decorator\n *\n * @example\n * ```typescript\n * class User {\n *   @observe((value) => {\n *     console.log('Email changed:', value);\n *     validateEmail(value);\n *   })\n *   email: string = '';\n *\n *   @observe((value) => {\n *     metrics.gauge('user.age', value);\n *   })\n *   age: number = 0;\n * }\n *\n * const user = new User();\n * user.email = 'test@example.com'; // Logs and validates\n * user.age = 25; // Records metric\n * ```\n */\nexport function observe<T>(cb: ObserverCallback<T>): PropertyDecorator;\n\n/**\n * Overloaded function for observing property changes.\n * Can be used with or without a custom callback.\n *\n * @param {object | ObserverCallback<T>} targetOrCb - Either the class prototype or a callback function\n * @param {string | symbol} [propertyKey] - The property key (when used without callback)\n * @returns {void | PropertyDecorator} Either void or the decorator function\n *\n * @throws {TypeError} When used with incorrect parameters\n */\nexport function observe<T>(\n  targetOrCb: object | ObserverCallback<T>,\n  propertyKey?: string | symbol,\n) {\n  if (propertyKey && !isFunction(targetOrCb)) {\n    const decorator = factory();\n    return decorator(targetOrCb, propertyKey);\n  }\n  if (isFunction(targetOrCb)) {\n    return factory(targetOrCb as ObserverCallback<T>);\n  }\n  throw new TypeError('@observe not used with correct parameters!');\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqDA,SAAS,QAAW,IAA6C;AAC/D,SAAQ,QAAgB,gBAAiC;EACvD,IAAI;EACJ,MAAM,EAAE,SAAS,OAAO;AACxB,SAAO,eAAe,QAAQ,aAAa;GACzC,IAAI,UAAa;AACf,YAAQ;AACR,QAAI,GACF,IAAG,SAAS;QAEZ,SAAQ,IAAI,oBAAoB,KAAK,GAAG,OAAO,YAAY,CAAC,KAAK,WAAW;;GAGhF,MAAM;AACJ,WAAO;;GAEV,CAAC;;;;;;;;;;;;;AAgEN,SAAgB,QACd,YACA,aACA;AACA,KAAI,eAAe,CAAC,WAAW,WAAW,CAExC,QADkB,SAAS,CACV,YAAY,YAAY;AAE3C,KAAI,WAAW,WAAW,CACxB,QAAO,QAAQ,WAAkC;AAEnD,OAAM,IAAI,UAAU,6CAA6C"}

package/lib/observer/observer.types.d.ts

@@ -0,0 +1,41 @@
+//#region src/observer/observer.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.
+ */
+/**
+ * Callback function type for property observers.
+ * Called whenever the observed property value changes.
+ *
+ * @template T - The type of the property value
+ * @param {T} value - The new value of the property
+ * @returns {unknown} Can return any value (typically void)
+ *
+ * @example
+ * ```typescript
+ * const onCountChange: ObserverCallback<number> = (newValue) => {
+ *   console.log(`Count is now: ${newValue}`);
+ * };
+ *
+ * const onNameChange: ObserverCallback<string> = (newValue) => {
+ *   if (newValue.length < 3) {
+ *     console.warn('Name is too short!');
+ *   }
+ * };
+ * ```
+ */
+type ObserverCallback<T> = (value: T) => unknown;
+//#endregion
+export { ObserverCallback };
+//# sourceMappingURL=observer.types.d.ts.map

package/lib/observer/observer.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observer.types.d.ts","names":[],"sources":["../../src/observer/observer.types.ts"],"mappings":";;AAqCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAAY,gBAAA,OAAuB,KAAA,EAAO,CAAA"}

package/lib/rate-limit/index.d.ts

@@ -0,0 +1,4 @@
+import { RateLimitAsyncCounter, RateLimitConfigs, RateLimitCounter, RateLimitable } from "./rate-limit.types.js";
+import { rateLimit } from "./rate-limit.js";
+import { SimpleRateLimitCounter } from "./simple-rate-limit-counter.js";
+export { RateLimitAsyncCounter, RateLimitConfigs, RateLimitCounter, RateLimitable, SimpleRateLimitCounter, rateLimit };

package/lib/rate-limit/index.js

@@ -0,0 +1,3 @@
+import { SimpleRateLimitCounter } from "./simple-rate-limit-counter.js";
+import { rateLimit } from "./rate-limit.js";
+export { SimpleRateLimitCounter, rateLimit };

package/lib/rate-limit/rate-limit.d.ts

@@ -0,0 +1,58 @@
+import { Method } from "../types.js";
+import { RateLimitConfigs } from "./rate-limit.types.js";
+
+//#region src/rate-limit/rate-limit.d.ts
+/**
+ * Decorator that rate limits method calls.
+ * Only allows a specified number of calls within a time window.
+ *
+ * @template T - The type of the class containing the decorated method
+ * @param {RateLimitConfigs<T>} config - Rate limit configuration
+ * @returns {(
+ *   target: T,
+ *   propertyName: keyof T,
+ *   descriptor: TypedPropertyDescriptor<Method<unknown>>
+ * ) => TypedPropertyDescriptor<Method<unknown>>} The decorator function
+ *
+ * @throws {Error} When applied to a non-method property
+ *
+ * @example
+ * ```typescript
+ * class Api {
+ *   @rateLimit({
+ *     timeSpanMs: 1000,  // 1 second
+ *     allowedCalls: 5,   // Max 5 calls
+ *     exceedHandler: () => console.warn('Rate limit exceeded!')
+ *   })
+ *   fetchData() {
+ *     // Only 5 calls allowed per second
+ *   }
+ *
+ *   // With custom key resolver for per-user limiting
+ *   @rateLimit({
+ *     timeSpanMs: 60000,  // 1 minute
+ *     allowedCalls: 100,  // Max 100 calls per user per minute
+ *     keyResolver: (userId) => userId  // Limit per user
+ *   })
+ *   getUserData(userId: string) {
+ *     return database.getUser(userId);
+ *   }
+ * }
+ *
+ * // With custom counter implementation
+ * class DistributedApi {
+ *   @rateLimit({
+ *     timeSpanMs: 1000,
+ *     allowedCalls: 10,
+ *     rateLimitCounter: new RedisRateLimitCounter()  // Distributed counter
+ *   })
+ *   async heavyOperation(): Promise<void> {
+ *     // Rate limited across all instances
+ *   }
+ * }
+ * ```
+ */
+declare function rateLimit<T = unknown>(config: RateLimitConfigs<T>): (target: T, propertyName: keyof T, descriptor: TypedPropertyDescriptor<Method<unknown>>) => TypedPropertyDescriptor<Method<unknown>>;
+//#endregion
+export { rateLimit };
+//# sourceMappingURL=rate-limit.d.ts.map

package/lib/rate-limit/rate-limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.d.ts","names":[],"sources":["../../src/rate-limit/rate-limit.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAsEgB,SAAA,aAAA,CACd,MAAA,EAAQ,gBAAA,CAAiB,CAAA,KAEzB,MAAA,EAAQ,CAAA,EACR,YAAA,QAAoB,CAAA,EACpB,UAAA,EAAY,uBAAA,CAAwB,MAAA,eACjC,uBAAA,CAAwB,MAAA"}

package/lib/rate-limit/rate-limit.fn.d.ts

@@ -0,0 +1,43 @@
+import { Method } from "../types.js";
+import { RateLimitConfigs } from "./rate-limit.types.js";
+
+//#region src/rate-limit/rate-limit.fn.d.ts
+/**
+ * Creates a rate-limited version of a method.
+ *
+ * @template D - The return type of the original method
+ * @template A - The argument types of the original method
+ * @param {Method<D, A>} originalMethod - The method to rate limit
+ * @param {RateLimitConfigs} config - The rate limit configuration
+ * @returns {Method<D | undefined, A>} A rate-limited method
+ *
+ * @example
+ * ```typescript
+ * class ApiService {
+ *   async fetchData(id: string): Promise<Data> {
+ *     return await fetch(`/api/data/${id}`).then(r => r.json());
+ *   }
+ * }
+ *
+ * const service = new ApiService();
+ *
+ * // Rate limit to 3 calls per 5 seconds
+ * const limited = rateLimitFn(
+ *   service.fetchData.bind(service),
+ *   {
+ *     timeSpanMs: 5000,
+ *     allowedCalls: 3,
+ *     exceedHandler: () => console.warn('Too many requests!')
+ *   }
+ * );
+ *
+ * await limited('1'); // Executes
+ * await limited('2'); // Executes
+ * await limited('3'); // Executes
+ * const result = await limited('4'); // Returns undefined, logs warning
+ * ```
+ */
+declare function rateLimitFn<D = unknown, A extends unknown[] = unknown[]>(originalMethod: Method<D, A>, config: RateLimitConfigs): Method<D | undefined, A>;
+//#endregion
+export { rateLimitFn };
+//# sourceMappingURL=rate-limit.fn.d.ts.map

package/lib/rate-limit/rate-limit.fn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.fn.d.ts","names":[],"sources":["../../src/rate-limit/rate-limit.fn.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAuDgB,WAAA,8CAAA,CACd,cAAA,EAAgB,MAAA,CAAO,CAAA,EAAG,CAAA,GAC1B,MAAA,EAAQ,gBAAA,GACP,MAAA,CAAO,CAAA,cAAe,CAAA"}

package/lib/rate-limit/rate-limit.fn.js

@@ -0,0 +1,56 @@
+import { SimpleRateLimitCounter } from "./simple-rate-limit-counter.js";
+//#region src/rate-limit/rate-limit.fn.ts
+/**
+* Creates a rate-limited version of a method.
+*
+* @template D - The return type of the original method
+* @template A - The argument types of the original method
+* @param {Method<D, A>} originalMethod - The method to rate limit
+* @param {RateLimitConfigs} config - The rate limit configuration
+* @returns {Method<D | undefined, A>} A rate-limited method
+*
+* @example
+* ```typescript
+* class ApiService {
+*   async fetchData(id: string): Promise<Data> {
+*     return await fetch(`/api/data/${id}`).then(r => r.json());
+*   }
+* }
+*
+* const service = new ApiService();
+*
+* // Rate limit to 3 calls per 5 seconds
+* const limited = rateLimitFn(
+*   service.fetchData.bind(service),
+*   {
+*     timeSpanMs: 5000,
+*     allowedCalls: 3,
+*     exceedHandler: () => console.warn('Too many requests!')
+*   }
+* );
+*
+* await limited('1'); // Executes
+* await limited('2'); // Executes
+* await limited('3'); // Executes
+* const result = await limited('4'); // Returns undefined, logs warning
+* ```
+*/
+function rateLimitFn(originalMethod, config) {
+	const counter = config.rateLimitCounter ?? new SimpleRateLimitCounter();
+	return function(...args) {
+		const key = typeof config.keyResolver === "function" ? config.keyResolver(...args) : "default";
+		if (counter.getCount(key) >= config.allowedCalls) {
+			config.exceedHandler?.();
+			return;
+		}
+		counter.inc(key);
+		setTimeout(() => {
+			counter.dec(key);
+		}, config.timeSpanMs);
+		return originalMethod.apply(this, args);
+	};
+}
+//#endregion
+export { rateLimitFn };
+
+//# sourceMappingURL=rate-limit.fn.js.map

package/lib/rate-limit/rate-limit.fn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.fn.js","names":[],"sources":["../../src/rate-limit/rate-limit.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 { Method } from '../types.js';\nimport type { RateLimitConfigs, RateLimitCounter } from './rate-limit.types.js';\nimport { SimpleRateLimitCounter } from './simple-rate-limit-counter.js';\n\n/**\n * Creates a rate-limited version of a method.\n *\n * @template D - The return type of the original method\n * @template A - The argument types of the original method\n * @param {Method<D, A>} originalMethod - The method to rate limit\n * @param {RateLimitConfigs} config - The rate limit configuration\n * @returns {Method<D | undefined, A>} A rate-limited method\n *\n * @example\n * ```typescript\n * class ApiService {\n *   async fetchData(id: string): Promise<Data> {\n *     return await fetch(`/api/data/${id}`).then(r => r.json());\n *   }\n * }\n *\n * const service = new ApiService();\n *\n * // Rate limit to 3 calls per 5 seconds\n * const limited = rateLimitFn(\n *   service.fetchData.bind(service),\n *   {\n *     timeSpanMs: 5000,\n *     allowedCalls: 3,\n *     exceedHandler: () => console.warn('Too many requests!')\n *   }\n * );\n *\n * await limited('1'); // Executes\n * await limited('2'); // Executes\n * await limited('3'); // Executes\n * const result = await limited('4'); // Returns undefined, logs warning\n * ```\n */\nexport function rateLimitFn<D = unknown, A extends unknown[] = unknown[]>(\n  originalMethod: Method<D, A>,\n  config: RateLimitConfigs,\n): Method<D | undefined, A> {\n  const counter: RateLimitCounter = config.rateLimitCounter ?? new SimpleRateLimitCounter();\n\n  return function (this: unknown, ...args: A): D | undefined {\n    const key = typeof config.keyResolver === 'function' ? config.keyResolver(...args) : 'default';\n\n    const currentCount = counter.getCount(key);\n\n    if (currentCount >= config.allowedCalls) {\n      config.exceedHandler?.();\n      return undefined;\n    }\n\n    counter.inc(key);\n\n    // Schedule decrement after time span\n    setTimeout(() => {\n      counter.dec(key);\n    }, config.timeSpanMs);\n\n    return originalMethod.apply(this, args);\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuDA,SAAgB,YACd,gBACA,QAC0B;CAC1B,MAAM,UAA4B,OAAO,oBAAoB,IAAI,wBAAwB;AAEzF,QAAO,SAAyB,GAAG,MAAwB;EACzD,MAAM,MAAM,OAAO,OAAO,gBAAgB,aAAa,OAAO,YAAY,GAAG,KAAK,GAAG;AAIrF,MAFqB,QAAQ,SAAS,IAAI,IAEtB,OAAO,cAAc;AACvC,UAAO,iBAAiB;AACxB;;AAGF,UAAQ,IAAI,IAAI;AAGhB,mBAAiB;AACf,WAAQ,IAAI,IAAI;KACf,OAAO,WAAW;AAErB,SAAO,eAAe,MAAM,MAAM,KAAK"}

package/lib/rate-limit/rate-limit.js

@@ -0,0 +1,65 @@
+import { rateLimitFn } from "./rate-limit.fn.js";
+//#region src/rate-limit/rate-limit.ts
+/**
+* Decorator that rate limits method calls.
+* Only allows a specified number of calls within a time window.
+*
+* @template T - The type of the class containing the decorated method
+* @param {RateLimitConfigs<T>} config - Rate limit configuration
+* @returns {(
+*   target: T,
+*   propertyName: keyof T,
+*   descriptor: TypedPropertyDescriptor<Method<unknown>>
+* ) => TypedPropertyDescriptor<Method<unknown>>} The decorator function
+*
+* @throws {Error} When applied to a non-method property
+*
+* @example
+* ```typescript
+* class Api {
+*   @rateLimit({
+*     timeSpanMs: 1000,  // 1 second
+*     allowedCalls: 5,   // Max 5 calls
+*     exceedHandler: () => console.warn('Rate limit exceeded!')
+*   })
+*   fetchData() {
+*     // Only 5 calls allowed per second
+*   }
+*
+*   // With custom key resolver for per-user limiting
+*   @rateLimit({
+*     timeSpanMs: 60000,  // 1 minute
+*     allowedCalls: 100,  // Max 100 calls per user per minute
+*     keyResolver: (userId) => userId  // Limit per user
+*   })
+*   getUserData(userId: string) {
+*     return database.getUser(userId);
+*   }
+* }
+*
+* // With custom counter implementation
+* class DistributedApi {
+*   @rateLimit({
+*     timeSpanMs: 1000,
+*     allowedCalls: 10,
+*     rateLimitCounter: new RedisRateLimitCounter()  // Distributed counter
+*   })
+*   async heavyOperation(): Promise<void> {
+*     // Rate limited across all instances
+*   }
+* }
+* ```
+*/
+function rateLimit(config) {
+	return (_target, _propertyName, descriptor) => {
+		if (descriptor.value) {
+			descriptor.value = rateLimitFn(descriptor.value, config);
+			return descriptor;
+		}
+		throw new Error("@rateLimit is applicable only on methods.");
+	};
+}
+//#endregion
+export { rateLimit };
+
+//# sourceMappingURL=rate-limit.js.map

package/lib/rate-limit/rate-limit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.js","names":[],"sources":["../../src/rate-limit/rate-limit.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 { Method } from '../types.js';\nimport { rateLimitFn } from './rate-limit.fn.js';\nimport type { RateLimitConfigs } from './rate-limit.types.js';\n\n/**\n * Decorator that rate limits method calls.\n * Only allows a specified number of calls within a time window.\n *\n * @template T - The type of the class containing the decorated method\n * @param {RateLimitConfigs<T>} config - Rate limit configuration\n * @returns {(\n *   target: T,\n *   propertyName: keyof T,\n *   descriptor: TypedPropertyDescriptor<Method<unknown>>\n * ) => TypedPropertyDescriptor<Method<unknown>>} The decorator function\n *\n * @throws {Error} When applied to a non-method property\n *\n * @example\n * ```typescript\n * class Api {\n *   @rateLimit({\n *     timeSpanMs: 1000,  // 1 second\n *     allowedCalls: 5,   // Max 5 calls\n *     exceedHandler: () => console.warn('Rate limit exceeded!')\n *   })\n *   fetchData() {\n *     // Only 5 calls allowed per second\n *   }\n *\n *   // With custom key resolver for per-user limiting\n *   @rateLimit({\n *     timeSpanMs: 60000,  // 1 minute\n *     allowedCalls: 100,  // Max 100 calls per user per minute\n *     keyResolver: (userId) => userId  // Limit per user\n *   })\n *   getUserData(userId: string) {\n *     return database.getUser(userId);\n *   }\n * }\n *\n * // With custom counter implementation\n * class DistributedApi {\n *   @rateLimit({\n *     timeSpanMs: 1000,\n *     allowedCalls: 10,\n *     rateLimitCounter: new RedisRateLimitCounter()  // Distributed counter\n *   })\n *   async heavyOperation(): Promise<void> {\n *     // Rate limited across all instances\n *   }\n * }\n * ```\n */\nexport function rateLimit<T = unknown>(\n  config: RateLimitConfigs<T>,\n): (\n  target: T,\n  propertyName: keyof T,\n  descriptor: TypedPropertyDescriptor<Method<unknown>>,\n) => TypedPropertyDescriptor<Method<unknown>> {\n  return (\n    _target: T,\n    _propertyName: keyof T,\n    descriptor: TypedPropertyDescriptor<Method<unknown>>,\n  ): TypedPropertyDescriptor<Method<unknown>> => {\n    if (descriptor.value) {\n      descriptor.value = rateLimitFn(descriptor.value, config);\n      return descriptor;\n    }\n\n    throw new Error('@rateLimit is applicable only on methods.');\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsEA,SAAgB,UACd,QAK4C;AAC5C,SACE,SACA,eACA,eAC6C;AAC7C,MAAI,WAAW,OAAO;AACpB,cAAW,QAAQ,YAAY,WAAW,OAAO,OAAO;AACxD,UAAO;;AAGT,QAAM,IAAI,MAAM,4CAA4C"}