@resq-sw/decorators 0.1.0

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

@@ -0,0 +1,148 @@
+import { Method } from "../types.js";
+
+//#region src/rate-limit/rate-limit.types.d.ts
+/**
+* @fileoverview Type definitions for the RateLimit decorator.
+* Provides types for rate limiting configuration and counter implementations.
+*
+* @module @resq/typescript/decorators/rate-limit/types
+*
+* @copyright Copyright (c) 2026 ResQ
+* @license MIT
+*/
+/**
+ * @fileoverview Type definitions for the RateLimit decorator.
+ * Provides types for rate limiting configuration and counter implementations.
+ *
+ * @module @resq/typescript/decorators/rate-limit/types
+ *
+ * @copyright Copyright (c) 2026 ResQ
+ * @license MIT
+ */
+/**
+ * Configuration options for rate limiting.
+ *
+ * @interface RateLimitConfigs
+ * @template T - The type of the class containing the decorated method
+ * @property {number} timeSpanMs - The time window in milliseconds
+ * @property {number} allowedCalls - Maximum number of calls allowed in the time window
+ * @property {((...args: any[]) => string) | keyof T} [keyResolver] - Function to generate rate limit keys (for per-user/entity limiting)
+ * @property {RateLimitCounter} [rateLimitCounter] - Custom counter implementation
+ * @property {RateLimitAsyncCounter} [rateLimitAsyncCounter] - Async counter implementation
+ * @property {() => void} [exceedHandler] - Handler called when rate limit is exceeded
+ *
+ * @example
+ * ```typescript
+ * const config: RateLimitConfigs<ApiService> = {
+ *   timeSpanMs: 60000,     // 1 minute
+ *   allowedCalls: 100,     // 100 calls per minute
+ *   keyResolver: (userId) => `user-${userId}`,
+ *   exceedHandler: () => { throw new Error('Rate limit exceeded'); }
+ * };
+ * ```
+ */
+interface RateLimitConfigs<T = any> {
+  /** The time window in milliseconds */
+  timeSpanMs: number;
+  /** Maximum number of calls allowed in the time window */
+  allowedCalls: number;
+  /** Function to generate rate limit keys (for per-user/entity limiting) */
+  keyResolver?: ((...args: unknown[]) => string) | keyof T;
+  /** Custom counter implementation */
+  rateLimitCounter?: RateLimitCounter;
+  /** Async counter implementation */
+  rateLimitAsyncCounter?: RateLimitAsyncCounter;
+  /** Handler called when rate limit is exceeded */
+  exceedHandler?: () => void;
+}
+/**
+ * Interface for rate limit counter implementations.
+ * Used to track call counts within time windows.
+ *
+ * @interface RateLimitCounter
+ * @property {(key: string) => void} inc - Increment the count for a key
+ * @property {(key: string) => void} dec - Decrement the count for a key
+ * @property {(key: string) => number} getCount - Get the current count for a key
+ *
+ * @example
+ * ```typescript
+ * class InMemoryCounter implements RateLimitCounter {
+ *   private counts = new Map<string, number>();
+ *
+ *   inc(key: string): void {
+ *     this.counts.set(key, (this.counts.get(key) ?? 0) + 1);
+ *   }
+ *
+ *   dec(key: string): void {
+ *     const count = this.counts.get(key) ?? 0;
+ *     if (count <= 1) {
+ *       this.counts.delete(key);
+ *     } else {
+ *       this.counts.set(key, count - 1);
+ *     }
+ *   }
+ *
+ *   getCount(key: string): number {
+ *     return this.counts.get(key) ?? 0;
+ *   }
+ * }
+ * ```
+ */
+interface RateLimitCounter {
+  /** Increment the count for a key */
+  inc: (key: string) => void;
+  /** Decrement the count for a key */
+  dec: (key: string) => void;
+  /** Get the current count for a key */
+  getCount: (key: string) => number;
+}
+/**
+ * Interface for async rate limit counter implementations.
+ * Use this when the counter needs to perform async operations (e.g., Redis, database).
+ *
+ * @interface RateLimitAsyncCounter
+ * @property {(key: string) => Promise<void>} inc - Increment the count for a key asynchronously
+ * @property {(key: string) => Promise<void>} dec - Decrement the count for a key asynchronously
+ * @property {(key: string) => Promise<number>} getCount - Get the current count for a key asynchronously
+ *
+ * @example
+ * ```typescript
+ * class RedisCounter implements RateLimitAsyncCounter {
+ *   async inc(key: string): Promise<void> {
+ *     await redis.incr(`ratelimit:${key}`);
+ *   }
+ *
+ *   async dec(key: string): Promise<void> {
+ *     await redis.decr(`ratelimit:${key}`);
+ *   }
+ *
+ *   async getCount(key: string): Promise<number> {
+ *     const count = await redis.get(`ratelimit:${key}`);
+ *     return parseInt(count ?? '0', 10);
+ *   }
+ * }
+ * ```
+ */
+interface RateLimitAsyncCounter {
+  /** Increment the count for a key asynchronously */
+  inc: (key: string) => Promise<void>;
+  /** Decrement the count for a key asynchronously */
+  dec: (key: string) => Promise<void>;
+  /** Get the current count for a key asynchronously */
+  getCount: (key: string) => Promise<number>;
+}
+/**
+ * Type for the @rateLimit decorator function.
+ *
+ * @template T - The type of the class containing the decorated method
+ * @template D - The return type of the decorated method
+ *
+ * @param {T} target - The class prototype
+ * @param {keyof T} propertyName - The name of the method being decorated
+ * @param {TypedPropertyDescriptor<Method<D>>} descriptor - The property descriptor
+ * @returns {TypedPropertyDescriptor<Method<D>>} The modified descriptor
+ */
+type RateLimitable<T, D> = (target: T, propertyName: keyof T, descriptor: TypedPropertyDescriptor<Method<D>>) => TypedPropertyDescriptor<Method<D>>;
+//#endregion
+export { RateLimitAsyncCounter, RateLimitConfigs, RateLimitCounter, RateLimitable };
+//# sourceMappingURL=rate-limit.types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.types.d.ts","names":[],"sources":["../../src/rate-limit/rate-limit.types.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiHA;;;;;;;;;;;;AAoCA;;UApFiB,gBAAA;EAsFO;EApFtB,UAAA;EAwF2B;EAtF3B,YAAA;EAsFkC;EApFlC,WAAA,QAAmB,IAAA,gCAAoC,CAAA;EAgFjD;EA9EN,gBAAA,GAAmB,gBAAA;EAgFnB;EA9EA,qBAAA,GAAwB,qBAAA;EA8EF;EA5EtB,aAAA;AAAA;;;;AA4FF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UAxDiB,gBAAA;;EAEf,GAAA,GAAM,GAAA;;EAEN,GAAA,GAAM,GAAA;;EAEN,QAAA,GAAW,GAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;UA8BI,qBAAA;;EAEf,GAAA,GAAM,GAAA,aAAgB,OAAA;;EAEtB,GAAA,GAAM,GAAA,aAAgB,OAAA;;EAEtB,QAAA,GAAW,GAAA,aAAgB,OAAA;AAAA;;;;;;;;;;;;KAcjB,aAAA,UACV,MAAA,EAAQ,CAAA,EACR,YAAA,QAAoB,CAAA,EACpB,UAAA,EAAY,uBAAA,CAAwB,MAAA,CAAO,CAAA,OACxC,uBAAA,CAAwB,MAAA,CAAO,CAAA"}

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

@@ -0,0 +1,89 @@
+import { RateLimitCounter } from "./rate-limit.types.js";
+
+//#region src/rate-limit/simple-rate-limit-counter.d.ts
+/**
+ * Simple in-memory implementation of RateLimitCounter.
+ * Uses a Map to store counts for each key.
+ *
+ * @class SimpleRateLimitCounter
+ * @implements {RateLimitCounter}
+ *
+ * @example
+ * ```typescript
+ * const counter = new SimpleRateLimitCounter();
+ *
+ * // Track API calls per user
+ * counter.inc('user-1');
+ * counter.inc('user-1');
+ * counter.inc('user-2');
+ *
+ * console.log(counter.getCount('user-1')); // 2
+ * console.log(counter.getCount('user-2')); // 1
+ * console.log(counter.getCount('user-3')); // 0
+ *
+ * // After some time, decrement
+ * counter.dec('user-1');
+ * console.log(counter.getCount('user-1')); // 1
+ * ```
+ */
+declare class SimpleRateLimitCounter implements RateLimitCounter {
+  private readonly counterMap;
+  /**
+   * Creates a new SimpleRateLimitCounter instance.
+   *
+   * @param {Map<string, number>} [counterMap=new Map()] - Optional existing Map to use for storage
+   */
+  constructor(counterMap?: Map<string, number>);
+  /**
+   * Gets the current count for a key.
+   *
+   * @param {string} key - The key to get count for
+   * @returns {number} The current count (0 if key doesn't exist)
+   *
+   * @example
+   * ```typescript
+   * const counter = new SimpleRateLimitCounter();
+   * console.log(counter.getCount('key')); // 0
+   * counter.inc('key');
+   * console.log(counter.getCount('key')); // 1
+   * ```
+   */
+  getCount(key: string): number;
+  /**
+   * Increments the count for a key.
+   *
+   * @param {string} key - The key to increment
+   * @returns {void}
+   *
+   * @example
+   * ```typescript
+   * const counter = new SimpleRateLimitCounter();
+   * counter.inc('user-123');
+   * counter.inc('user-123');
+   * console.log(counter.getCount('user-123')); // 2
+   * ```
+   */
+  inc(key: string): void;
+  /**
+   * Decrements the count for a key.
+   * Removes the key from the map if count reaches 0.
+   *
+   * @param {string} key - The key to decrement
+   * @returns {void}
+   *
+   * @example
+   * ```typescript
+   * const counter = new SimpleRateLimitCounter();
+   * counter.inc('key');
+   * counter.inc('key');
+   * counter.dec('key');
+   * console.log(counter.getCount('key')); // 1
+   * counter.dec('key');
+   * console.log(counter.getCount('key')); // 0 (key removed from map)
+   * ```
+   */
+  dec(key: string): void;
+}
+//#endregion
+export { SimpleRateLimitCounter };
+//# sourceMappingURL=simple-rate-limit-counter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"simple-rate-limit-counter.d.ts","names":[],"sources":["../../src/rate-limit/simple-rate-limit-counter.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;cA2Ca,sBAAA,YAAkC,gBAAA;EAAA,iBAMhB,UAAA;;;;;;cAAA,UAAA,GAAU,GAAA;;;;;;;;;;;;;;;EAgBvC,QAAA,CAAS,GAAA;;;;;;;;;;;;;;;EAkBT,GAAA,CAAI,GAAA;;;;;;;;;;;;;;;;;;;EA0BJ,GAAA,CAAI,GAAA;AAAA"}

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

@@ -0,0 +1,98 @@
+//#region src/rate-limit/simple-rate-limit-counter.ts
+/**
+* Simple in-memory implementation of RateLimitCounter.
+* Uses a Map to store counts for each key.
+*
+* @class SimpleRateLimitCounter
+* @implements {RateLimitCounter}
+*
+* @example
+* ```typescript
+* const counter = new SimpleRateLimitCounter();
+*
+* // Track API calls per user
+* counter.inc('user-1');
+* counter.inc('user-1');
+* counter.inc('user-2');
+*
+* console.log(counter.getCount('user-1')); // 2
+* console.log(counter.getCount('user-2')); // 1
+* console.log(counter.getCount('user-3')); // 0
+*
+* // After some time, decrement
+* counter.dec('user-1');
+* console.log(counter.getCount('user-1')); // 1
+* ```
+*/
+var SimpleRateLimitCounter = class {
+	/**
+	* Creates a new SimpleRateLimitCounter instance.
+	*
+	* @param {Map<string, number>} [counterMap=new Map()] - Optional existing Map to use for storage
+	*/
+	constructor(counterMap = /* @__PURE__ */ new Map()) {
+		this.counterMap = counterMap;
+	}
+	/**
+	* Gets the current count for a key.
+	*
+	* @param {string} key - The key to get count for
+	* @returns {number} The current count (0 if key doesn't exist)
+	*
+	* @example
+	* ```typescript
+	* const counter = new SimpleRateLimitCounter();
+	* console.log(counter.getCount('key')); // 0
+	* counter.inc('key');
+	* console.log(counter.getCount('key')); // 1
+	* ```
+	*/
+	getCount(key) {
+		return this.counterMap.get(key) ?? 0;
+	}
+	/**
+	* Increments the count for a key.
+	*
+	* @param {string} key - The key to increment
+	* @returns {void}
+	*
+	* @example
+	* ```typescript
+	* const counter = new SimpleRateLimitCounter();
+	* counter.inc('user-123');
+	* counter.inc('user-123');
+	* console.log(counter.getCount('user-123')); // 2
+	* ```
+	*/
+	inc(key) {
+		if (!this.counterMap.has(key)) this.counterMap.set(key, 0);
+		this.counterMap.set(key, (this.counterMap.get(key) ?? 0) + 1);
+	}
+	/**
+	* Decrements the count for a key.
+	* Removes the key from the map if count reaches 0.
+	*
+	* @param {string} key - The key to decrement
+	* @returns {void}
+	*
+	* @example
+	* ```typescript
+	* const counter = new SimpleRateLimitCounter();
+	* counter.inc('key');
+	* counter.inc('key');
+	* counter.dec('key');
+	* console.log(counter.getCount('key')); // 1
+	* counter.dec('key');
+	* console.log(counter.getCount('key')); // 0 (key removed from map)
+	* ```
+	*/
+	dec(key) {
+		const currentCount = this.counterMap.get(key);
+		if (currentCount !== void 0) if (currentCount <= 1) this.counterMap.delete(key);
+		else this.counterMap.set(key, currentCount - 1);
+	}
+};
+//#endregion
+export { SimpleRateLimitCounter };
+
+//# sourceMappingURL=simple-rate-limit-counter.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"simple-rate-limit-counter.js","names":[],"sources":["../../src/rate-limit/simple-rate-limit-counter.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 { RateLimitCounter } from './index.js';\n\n/**\n * Simple in-memory implementation of RateLimitCounter.\n * Uses a Map to store counts for each key.\n *\n * @class SimpleRateLimitCounter\n * @implements {RateLimitCounter}\n *\n * @example\n * ```typescript\n * const counter = new SimpleRateLimitCounter();\n *\n * // Track API calls per user\n * counter.inc('user-1');\n * counter.inc('user-1');\n * counter.inc('user-2');\n *\n * console.log(counter.getCount('user-1')); // 2\n * console.log(counter.getCount('user-2')); // 1\n * console.log(counter.getCount('user-3')); // 0\n *\n * // After some time, decrement\n * counter.dec('user-1');\n * console.log(counter.getCount('user-1')); // 1\n * ```\n */\nexport class SimpleRateLimitCounter implements RateLimitCounter {\n  /**\n   * Creates a new SimpleRateLimitCounter instance.\n   *\n   * @param {Map<string, number>} [counterMap=new Map()] - Optional existing Map to use for storage\n   */\n  constructor(private readonly counterMap = new Map<string, number>()) {}\n\n  /**\n   * Gets the current count for a key.\n   *\n   * @param {string} key - The key to get count for\n   * @returns {number} The current count (0 if key doesn't exist)\n   *\n   * @example\n   * ```typescript\n   * const counter = new SimpleRateLimitCounter();\n   * console.log(counter.getCount('key')); // 0\n   * counter.inc('key');\n   * console.log(counter.getCount('key')); // 1\n   * ```\n   */\n  getCount(key: string): number {\n    return this.counterMap.get(key) ?? 0;\n  }\n\n  /**\n   * Increments the count for a key.\n   *\n   * @param {string} key - The key to increment\n   * @returns {void}\n   *\n   * @example\n   * ```typescript\n   * const counter = new SimpleRateLimitCounter();\n   * counter.inc('user-123');\n   * counter.inc('user-123');\n   * console.log(counter.getCount('user-123')); // 2\n   * ```\n   */\n  inc(key: string): void {\n    if (!this.counterMap.has(key)) {\n      this.counterMap.set(key, 0);\n    }\n\n    this.counterMap.set(key, (this.counterMap.get(key) ?? 0) + 1);\n  }\n\n  /**\n   * Decrements the count for a key.\n   * Removes the key from the map if count reaches 0.\n   *\n   * @param {string} key - The key to decrement\n   * @returns {void}\n   *\n   * @example\n   * ```typescript\n   * const counter = new SimpleRateLimitCounter();\n   * counter.inc('key');\n   * counter.inc('key');\n   * counter.dec('key');\n   * console.log(counter.getCount('key')); // 1\n   * counter.dec('key');\n   * console.log(counter.getCount('key')); // 0 (key removed from map)\n   * ```\n   */\n  dec(key: string): void {\n    const currentCount = this.counterMap.get(key);\n\n    if (currentCount !== undefined) {\n      if (currentCount <= 1) {\n        this.counterMap.delete(key);\n      } else {\n        this.counterMap.set(key, currentCount - 1);\n      }\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AA2CA,IAAa,yBAAb,MAAgE;;;;;;CAM9D,YAAY,6BAA8B,IAAI,KAAqB,EAAE;AAAxC,OAAA,aAAA;;;;;;;;;;;;;;;;CAgB7B,SAAS,KAAqB;AAC5B,SAAO,KAAK,WAAW,IAAI,IAAI,IAAI;;;;;;;;;;;;;;;;CAiBrC,IAAI,KAAmB;AACrB,MAAI,CAAC,KAAK,WAAW,IAAI,IAAI,CAC3B,MAAK,WAAW,IAAI,KAAK,EAAE;AAG7B,OAAK,WAAW,IAAI,MAAM,KAAK,WAAW,IAAI,IAAI,IAAI,KAAK,EAAE;;;;;;;;;;;;;;;;;;;;CAqB/D,IAAI,KAAmB;EACrB,MAAM,eAAe,KAAK,WAAW,IAAI,IAAI;AAE7C,MAAI,iBAAiB,KAAA,EACnB,KAAI,gBAAgB,EAClB,MAAK,WAAW,OAAO,IAAI;MAE3B,MAAK,WAAW,IAAI,KAAK,eAAe,EAAE"}

package/lib/readonly/index.d.ts

@@ -0,0 +1,3 @@
+import { readonly } from "./readonly.js";
+import { Readonlyable } from "./readonly.types.js";
+export { Readonlyable, readonly };

package/lib/readonly/index.js

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

package/lib/readonly/readonly.d.ts

@@ -0,0 +1,39 @@
+import { Readonlyable } from "./readonly.types.js";
+
+//#region src/readonly/readonly.d.ts
+/**
+ * Decorator that makes a method read-only (non-writable).
+ * Prevents the method from being reassigned after class instantiation.
+ *
+ * @template T - The type of the class containing the decorated method
+ * @returns {Readonlyable<T>} The decorator function
+ *
+ * @example
+ * ```typescript
+ * class SecureApi {
+ *   @readonly()
+ *   authenticate(): Promise<AuthToken> {
+ *     return this.performAuth();
+ *   }
+ *
+ *   @readonly()
+ *   getBaseUrl(): string {
+ *     return 'https://api.example.com';
+ *   }
+ * }
+ *
+ * const api = new SecureApi();
+ *
+ * // These will throw TypeError
+ * // api.authenticate = () => Promise.resolve(fakeToken);
+ * // api.getBaseUrl = () => 'https://evil.com';
+ *
+ * // Calling the methods works normally
+ * const token = await api.authenticate();
+ * const url = api.getBaseUrl();
+ * ```
+ */
+declare function readonly<T = any>(): Readonlyable<T>;
+//#endregion
+export { readonly };
+//# sourceMappingURL=readonly.d.ts.map

package/lib/readonly/readonly.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readonly.d.ts","names":[],"sources":["../../src/readonly/readonly.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAmDgB,QAAA,SAAA,CAAA,GAAqB,YAAA,CAAa,CAAA"}

package/lib/readonly/readonly.js

@@ -0,0 +1,43 @@
+//#region src/readonly/readonly.ts
+/**
+* Decorator that makes a method read-only (non-writable).
+* Prevents the method from being reassigned after class instantiation.
+*
+* @template T - The type of the class containing the decorated method
+* @returns {Readonlyable<T>} The decorator function
+*
+* @example
+* ```typescript
+* class SecureApi {
+*   @readonly()
+*   authenticate(): Promise<AuthToken> {
+*     return this.performAuth();
+*   }
+*
+*   @readonly()
+*   getBaseUrl(): string {
+*     return 'https://api.example.com';
+*   }
+* }
+*
+* const api = new SecureApi();
+*
+* // These will throw TypeError
+* // api.authenticate = () => Promise.resolve(fakeToken);
+* // api.getBaseUrl = () => 'https://evil.com';
+*
+* // Calling the methods works normally
+* const token = await api.authenticate();
+* const url = api.getBaseUrl();
+* ```
+*/
+function readonly() {
+	return (target, key, descriptor) => {
+		descriptor.writable = false;
+		return descriptor;
+	};
+}
+//#endregion
+export { readonly };
+
+//# sourceMappingURL=readonly.js.map

package/lib/readonly/readonly.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"readonly.js","names":[],"sources":["../../src/readonly/readonly.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 { Readonlyable } from './index.js';\n\n/**\n * Decorator that makes a method read-only (non-writable).\n * Prevents the method from being reassigned after class instantiation.\n *\n * @template T - The type of the class containing the decorated method\n * @returns {Readonlyable<T>} The decorator function\n *\n * @example\n * ```typescript\n * class SecureApi {\n *   @readonly()\n *   authenticate(): Promise<AuthToken> {\n *     return this.performAuth();\n *   }\n *\n *   @readonly()\n *   getBaseUrl(): string {\n *     return 'https://api.example.com';\n *   }\n * }\n *\n * const api = new SecureApi();\n *\n * // These will throw TypeError\n * // api.authenticate = () => Promise.resolve(fakeToken);\n * // api.getBaseUrl = () => 'https://evil.com';\n *\n * // Calling the methods works normally\n * const token = await api.authenticate();\n * const url = api.getBaseUrl();\n * ```\n */\nexport function readonly<T = any>(): Readonlyable<T> {\n  return (\n    target: T,\n    key: keyof T,\n    descriptor: TypedPropertyDescriptor<Method<any>>,\n  ): TypedPropertyDescriptor<Method<any>> => {\n    descriptor.writable = false;\n\n    return descriptor;\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmDA,SAAgB,WAAqC;AACnD,SACE,QACA,KACA,eACyC;AACzC,aAAW,WAAW;AAEtB,SAAO"}

package/lib/readonly/readonly.types.d.ts

@@ -0,0 +1,40 @@
+//#region src/readonly/readonly.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.
+ */
+/**
+ * Type for decorators that make methods read-only.
+ *
+ * @template T - The type of the class containing the decorated method
+ *
+ * @param {T} target - The class prototype
+ * @param {keyof T} propertyName - The name of the method being decorated
+ * @param {PropertyDescriptor} descriptor - The property descriptor
+ * @returns {PropertyDescriptor} The modified descriptor with writable set to false
+ *
+ * @example
+ * ```typescript
+ * type ReadonlyMethod = Readonlyable<MyClass>;
+ *
+ * const decorator: ReadonlyMethod = (target, key, descriptor) => {
+ *   descriptor.writable = false;
+ *   return descriptor;
+ * };
+ * ```
+ */
+type Readonlyable<T = any> = (target: T, propertyName: keyof T, descriptor: PropertyDescriptor) => PropertyDescriptor;
+//#endregion
+export { Readonlyable };
+//# sourceMappingURL=readonly.types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"readonly.types.d.ts","names":[],"sources":["../../src/readonly/readonly.types.ts"],"mappings":";;AAoCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAAY,YAAA,aACV,MAAA,EAAQ,CAAA,EACR,YAAA,QAAoB,CAAA,EACpB,UAAA,EAAY,kBAAA,KACT,kBAAA"}

package/lib/throttle/index.d.ts

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

package/lib/throttle/index.js

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

package/lib/throttle/throttle.d.ts

@@ -0,0 +1,35 @@
+import { Decorator } from "../types.js";
+
+//#region src/throttle/throttle.d.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
+ * ```
+ */
+declare function throttle<T = any>(delayMs: number): Decorator<T>;
+//#endregion
+export { throttle };
+//# sourceMappingURL=throttle.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"throttle.d.ts","names":[],"sources":["../../src/throttle/throttle.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA+CgB,QAAA,SAAA,CAAkB,OAAA,WAAkB,SAAA,CAAU,CAAA"}

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

@@ -0,0 +1,42 @@
+import { Method } from "../types.js";
+
+//#region src/throttle/throttle.fn.d.ts
+/**
+ * Wraps a method to throttle its execution to once per time period.
+ *
+ * @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 throttle
+ * @param {number} delayMs - The throttle interval in milliseconds
+ * @returns {Method<void, A>} The throttled method
+ *
+ * @example
+ * ```typescript
+ * class ScrollTracker {
+ *   scrollY = 0;
+ *
+ *   updatePosition(y: number): void {
+ *     this.scrollY = y;
+ *     console.log('Position updated:', y);
+ *   }
+ * }
+ *
+ * const tracker = new ScrollTracker();
+ *
+ * // Throttle to once per 100ms
+ * const throttledUpdate = throttleFn(
+ *   tracker.updatePosition.bind(tracker),
+ *   100
+ * );
+ *
+ * // Rapid scroll events
+ * window.addEventListener('scroll', (e) => {
+ *   throttledUpdate(window.scrollY);
+ *   // Only logs once every 100ms even during rapid scrolling
+ * });
+ * ```
+ */
+declare function throttleFn<D = any, A extends any[] = any[]>(originalMethod: Method<D, A>, delayMs: number): Method<void, A>;
+//#endregion
+export { throttleFn };
+//# sourceMappingURL=throttle.fn.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"throttle.fn.d.ts","names":[],"sources":["../../src/throttle/throttle.fn.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAqDgB,UAAA,kCAAA,CACd,cAAA,EAAgB,MAAA,CAAO,CAAA,EAAG,CAAA,GAC1B,OAAA,WACC,MAAA,OAAa,CAAA"}

package/lib/throttle/throttle.fn.js

@@ -0,0 +1,52 @@
+//#region src/throttle/throttle.fn.ts
+/**
+* Wraps a method to throttle its execution to once per time period.
+*
+* @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 throttle
+* @param {number} delayMs - The throttle interval in milliseconds
+* @returns {Method<void, A>} The throttled method
+*
+* @example
+* ```typescript
+* class ScrollTracker {
+*   scrollY = 0;
+*
+*   updatePosition(y: number): void {
+*     this.scrollY = y;
+*     console.log('Position updated:', y);
+*   }
+* }
+*
+* const tracker = new ScrollTracker();
+*
+* // Throttle to once per 100ms
+* const throttledUpdate = throttleFn(
+*   tracker.updatePosition.bind(tracker),
+*   100
+* );
+*
+* // Rapid scroll events
+* window.addEventListener('scroll', (e) => {
+*   throttledUpdate(window.scrollY);
+*   // Only logs once every 100ms even during rapid scrolling
+* });
+* ```
+*/
+function throttleFn(originalMethod, delayMs) {
+	let throttling = false;
+	return function(...args) {
+		if (!throttling) {
+			throttling = true;
+			originalMethod.apply(this, args);
+			setTimeout(() => {
+				throttling = false;
+			}, delayMs);
+		}
+	};
+}
+//#endregion
+export { throttleFn };
+
+//# sourceMappingURL=throttle.fn.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"throttle.fn.js","names":[],"sources":["../../src/throttle/throttle.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';\n\n/**\n * Wraps a method to throttle its execution to once per time period.\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 throttle\n * @param {number} delayMs - The throttle interval in milliseconds\n * @returns {Method<void, A>} The throttled method\n *\n * @example\n * ```typescript\n * class ScrollTracker {\n *   scrollY = 0;\n *\n *   updatePosition(y: number): void {\n *     this.scrollY = y;\n *     console.log('Position updated:', y);\n *   }\n * }\n *\n * const tracker = new ScrollTracker();\n *\n * // Throttle to once per 100ms\n * const throttledUpdate = throttleFn(\n *   tracker.updatePosition.bind(tracker),\n *   100\n * );\n *\n * // Rapid scroll events\n * window.addEventListener('scroll', (e) => {\n *   throttledUpdate(window.scrollY);\n *   // Only logs once every 100ms even during rapid scrolling\n * });\n * ```\n */\nexport function throttleFn<D = any, A extends any[] = any[]>(\n  originalMethod: Method<D, A>,\n  delayMs: number,\n): Method<void, A> {\n  let throttling = false;\n  return function (this: any, ...args: A): void {\n    if (!throttling) {\n      throttling = true;\n      originalMethod.apply(this, args);\n\n      setTimeout(() => {\n        throttling = false;\n      }, delayMs);\n    }\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqDA,SAAgB,WACd,gBACA,SACiB;CACjB,IAAI,aAAa;AACjB,QAAO,SAAqB,GAAG,MAAe;AAC5C,MAAI,CAAC,YAAY;AACf,gBAAa;AACb,kBAAe,MAAM,MAAM,KAAK;AAEhC,oBAAiB;AACf,iBAAa;MACZ,QAAQ"}