Feat/40 dump restore

[man610]

PR: Add Persistence Support to RateLimiterMemory
Description
This PR introduces the ability to persist and restore the state of RateLimiterMemory. While RateLimiterMemory is primarily designed for high-performance in-memory limiting, there are many use cases where preserving the rate-limiting state across process restarts or deployments is critical.

This implementation adds two primary methods for state management and optional lifecycle hooks for real-time synchronization.

Key Changes

1. State Serialization & Restoration
   dumpToString(): Serializes the current _storage and _inMemoryBlockedKeys into a JSON string.
   Includes a version field for future-proofing.
   Captures absolute expiration timestamps for all records.
   restoreFromString(serialized): Reconstructs the internal state from a dump.
   TTL Arithmetic: Automatically calculates remaining TTLs based on the expiresAt timestamps. If a key has already expired during the process downtime, it is ignored.
   Timer Reconstruction: Re-initializes expiration timeouts for all restored keys to maintain memory hygiene.
2. Lifecycle Hooks
   Added two new optional callbacks to RateLimiterMemory constructor:

onUpsert(key, record): Triggered whenever a key's value or expiration is updated (consume, penalty, reward, block).
onDelete(key): Triggered when a key is manually deleted. These hooks enable "fire-and-forget" synchronization to an external persistent store (like Redis or a database) without blocking the synchronous core logic of the memory limiter.
3. Internal Enhancements
Extended MemoryStorage component with getRawAll() and restore() methods to support batch operations required by the persistence logic.
Updated TypeScript definitions in types.d.ts.
Verification Results
A new test file test/RateLimiterMemoryPersistence.test.js has been added covering:

Full dump and restore cycle between different instances.
TTL accuracy across simulated downtime.
Persistence of blocked keys.
Error handling for invalid/corrupt JSON input.
Version mismatch handling.

[Copilot]

Pull request overview

Adds persistence APIs to RateLimiterMemory so its in-memory state can be serialized and restored after process restarts.

Changes:

• Added dumpToString() / restoreFromString() to RateLimiterMemory for JSON-based state export/import.
• Added MemoryStorage._restoreRecord() to recreate records (including expiry timers) during restore.
• Added a new Mocha test suite covering dump/restore behavior and TTL handling; updated TypeScript typings.

Reviewed changes

Copilot reviewed 3 out of 4 changed files in this pull request and generated 4 comments.

File	Description
lib/RateLimiterMemory.js	Implements dumpToString() and restoreFromString() for persistence.
lib/component/MemoryStorage/MemoryStorage.js	Adds _restoreRecord() to restore records and reconstruct expiration timeouts.
test/RateLimiterMemoryPersistence.test.js	Adds tests for dump/restore, TTL arithmetic, and error handling.
types.d.ts	Updates TS declarations for new RateLimiterMemory methods (and fixes some indentation).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 4 changed files in this pull request and generated 4 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[animir]

@man610 It looks good, very close.

One question is to how developer knows if data restoration is successful?
Should restore function return number of restored records?

If _restoreRecord function returns some codes like invalid, expired and restored then restore function could count total number of each category and return object.

What do you think?

[man610]

@animir your thought is Right but first i was just thinking to give Boolean to user,
But as you suggest we can give that object with those keys but i want to extends this functionality
in restore we will accept one more parameter which is optional & by default false parameter like detail response which will include those Four key with object in which one is count and one is array of that counted key
what's you opinion about this ?

[animir]

@man610 Good idea. Knowing details about records would be helpful for debugging.

[man610]

@animir check i have update as per our conversation

[animir]

@man610 It looks good. The new version will be released soon. Thank you for your patience.

[man610]

@animir Thanks for guide me for my first open source contribution & this amazing opportunity