{"id":25637620,"url":"https://github.com/nehu3n/fastcache","last_synced_at":"2026-05-06T00:39:47.002Z","repository":{"id":258417245,"uuid":"873323546","full_name":"nehu3n/fastcache","owner":"nehu3n","description":"⚡ Blazing-fast, multi-algorithm in-memory cache.","archived":false,"fork":false,"pushed_at":"2024-10-20T23:58:05.000Z","size":72,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-30T17:38:06.751Z","etag":null,"topics":["cache","database","fast","in-memory","nodejs","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nehu3n.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-16T01:12:20.000Z","updated_at":"2025-01-20T07:59:25.000Z","dependencies_parsed_at":"2024-10-18T22:51:21.747Z","dependency_job_id":"f49b0859-5710-4b18-b7c8-6f60479bdb1a","html_url":"https://github.com/nehu3n/fastcache","commit_stats":null,"previous_names":["nehu3n/fastcache"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/nehu3n/fastcache","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nehu3n%2Ffastcache","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nehu3n%2Ffastcache/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nehu3n%2Ffastcache/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nehu3n%2Ffastcache/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nehu3n","download_url":"https://codeload.github.com/nehu3n/fastcache/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nehu3n%2Ffastcache/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278703580,"owners_count":26031205,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-06T02:00:05.630Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cache","database","fast","in-memory","nodejs","typescript"],"created_at":"2025-02-23T01:27:53.916Z","updated_at":"2025-10-07T00:44:45.850Z","avatar_url":"https://github.com/nehu3n.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg src=\"./public/logo.png\" width=\"100\" align=\"right\" /\u003e\n\n\u003e [!WARNING] \n\u003e **FastCache** is in the development stage. It is not ready for any use at this time. ⏰\n\n# FastCache - Key-Value Database\n\n**FastCache** is a **blazing-fast**, **easy-to-use**, and **highly customizable** in-memory key-value database with **support for multiple caching algorithms**. It is entirely written in TypeScript and designed for **high performance** and **flexibility**. 🔥\n\n## ✨ Features\n\n- ⚡ **Blazing-fast performance:** Designed with **speed** in mind, **FastCache** is optimized for exceptional performance, making it ideal for applications that need fast data access. [Check out the benchmarks](./bench) to see how it compares to other cache packages in the ecosystem. **_(≈8,000,000 operations per second 🧪)_**\n\n- 👀 **Easy-to-use API:** With a simple and intuitive API, **FastCache** offers a seamless and safe development experience, using **type-safe** TypeScript to reduce errors and make everyday work easier.\n\n- 🎨 **Highly customizable:** Tailor your cache with options like **TTL** (Time-To-Live) and **separate namespaces**. **FastCache** is adaptable to your application's specific needs, allowing you to maximize both performance and control.\n\n- 🚀 **Multi-algorithm support:** It supports a variety of caching algorithms such as **LRU** (Least Recently Used), **2Q**, **LFU** (Least Frequently Used), **FIFO** (First In, First Out), and **ARC** (Adaptive Replacement Cache). This allows you to choose the algorithm that best fits your data access pattern or memory requirements.\n\n- 📂 **Persistence:** Provides an option for persistence through the file system. You can create ultra-efficient and targeted directory structures for searching, allowing you to maintain data consistency even when the application restarts.\n\n## 📚 Guide\n\nIn this guide you will see how to use **FastCache**: its API, methods, options, explanations about each algorithm (use cases, advantages, disadvantages and description of each one) and more.\n\n---\n\n### Installation 📥\n\nTo install **FastCache**, use your favorite package manager:\n\n```bash\nnpm install fastcache\n```\n\n```bash\npnpm add fastcache\n```\n\n```bash\nyarn add fastcache\n```\n\n### API 🧩\n\n**FastCache** provides a concise and elegant API written in TypeScript. It is type-safe and familiar in the ecosystem. The following will explain all the methods and options it contains so you can quickly get started using the package.\n\nLet's start by looking at a basic example of a **FastCache** cache:\n\n```ts\nimport { Cache } from \"fastcache\";\nconst cache = Cache({ algorithm: \"LRU\" });\n\ncache.set(\"key\", \"value\");\n\nconsole.log(cache.get(\"key\")); // \"value\"\n```\n\nLet's break this code down. First an instance of the cache is created, passing as a parameter an object with the algorithm to be used (see the [algorithms subsection](#algorithms) for explanations of the available ones):\n\n```ts\nimport { Cache } from \"fastcache\";\nconst cache = Cache({ algorithm: \"LRU\" });\n```\n\nThen a “key” key with an associated “value” is established:\n\n```ts\ncache.set(\"key\", \"value\");\n```\n\nFinally, the value set with the “key” key is obtained:\n\n```ts\nconsole.log(cache.get(\"key\")); // \"value\"\n```\n\n#### Stores a value\n\nTo cache a value, you can use two methods depending on your needs: `set` and `mset`.\n\n##### Set\n\nThe `set` method allows you to store **a value** associated to a key, per call. It has the syntax:\n\n```ts\ncache.set(key, value, options?);\n```\n\nExample (no options):\n\n```ts\ncache.set(\"key\", \"value\");\n```\n\nThe options available in the `set` are:\n\n- `ttl?` (**number**): Specifies how long the value will remain in the cache before expiring.\n- `overwrite?` (**boolean**): Whether it is allowed to overwrite existing values associated with a certain key.\n- `priority?` (**1|2|3**): A number to assign a priority to the value, useful for deciding which items are deleted first in case of a full cache.\n\nExample (with options):\n\n```ts\ncache.set(\"key\", \"value\", {\n  ttl: 5000, // 5 seconds (in milliseconds)\n  overwrite: false,\n  priority: 2\n});\n```\n\n##### MSet\n\nThe `mset` (**m**ultiple **set**) method allows storing several key-values in a single call. It has the syntax:\n\n```ts\ncache.mset([ { key: value, options?: options } ]);\n```\n\nExample (no options):\n\n```ts\ncache.mset([\n  { \"key\": \"value\" },\n  { \"key2\": \"value2\" }\n]);\n```\n\nThe options available in the `mset` are:\n\n- `ttl?` (**number**): Specifies how long the value will remain in the cache before expiring.\n- `overwrite?` (**boolean**): Whether it is allowed to overwrite existing values associated with a certain key.\n- `priority?` (**1|2|3**): A number to assign a priority to the value, useful for deciding which items are deleted first in case of a full cache.\n\nExample (with options):\n\n```ts\ncache.mset([\n  { \"key\": \"value\", options: { ttl: 5000, overwrite: false, priority: 2 } },\n  { \"key2\": false },\n  { \"key3\": 45, options: { ttl: 3000 } }\n]);\n```\n\n#### Obtain a value\n\nTo get values from the cache, you can use two methods depending on your needs: `get` and `mget`.\n\n##### Get\n\nThe `get` method allows to obtain **a value** associated to a key, per call. It has the syntax:\n\n```ts\ncache.get(key, options?);\n```\n\nExample (no options):\n\n```ts\ncache.get(\"key\");\n```\n\nThe options available in the `get` are:\n\n- `fallback?` (**function**): A function that is executed if the value is not found in the cache. \n- `refreshTtl?` (**boolean**): Whether to refresh the TTL of the value when it is accessed.\n\nExample (with options):\n\n```ts\ncache.get(\"key\", {\n  fallback: () =\u003e fetchValue(), // executes the fallback if the key does not exist\n  refreshTtl: false,\n});\n```\n\n##### MGet\n\nThe `mget` (**m**ultiple **get**) method allows to obtain several values in a single call. It has the syntax:\n\nNo options:\n\n```ts\ncache.mget([key]);\n```\n\nWith options:\n```ts\ncache.mget([ { key, options?: options } ]);\n```\n\nExample (no options):\n\n```ts\ncache.mget([\"key\", \"key2\"]);\n```\n\nThe options available in the `mget` are:\n\n- `fallback?` (**function**): A function that is executed if the value is not found in the cache. \n- `refreshTtl?` (**boolean**): Whether to refresh the TTL of the value when it is accessed.\n\nExample (with options):\n\n```ts\ncache.mget([\n  { key: \"key\", options: { fallback: () =\u003e fetchValue(), refreshTtl: false } },\n  { key: \"key3\", options: { refreshTtl: true } }\n]);\n```\n\n#### Delete a value\n\nTo remove values from the cache, you can use two methods depending on your needs: `del` and `mdel`.\n\n##### Del\n\nThe `del` method allows to delete **a value** associated to a key, per call. It has the syntax:\n\n```ts\ncache.del(key);\n```\n\nExample:\n\n```ts\ncache.del(\"key\");\n```\n\n##### MDel\n\nThe `mdel` (**m**ultiple **del**ete) method allows to delete several values in a single call. It has the syntax:\n\n```ts\ncache.mdel([key]);\n```\n\nExample:\n\n```ts\ncache.mdel([\"key\", \"key2\"]);\n```\n\n#### Verify the existence of a value.\n\nTo verify the existence of values in the cache, you can use two methods depending on your needs: `has` and `mhas`.\n\n##### Has\n\nThe `has` method allows you to check the existence of **a value** associated to a key, per call. It has the syntax:\n\n```ts\ncache.has(key);\n```\n\nExample:\n\n```ts\ncache.has(“key”);\n```\n\n##### MHas\n\nThe `mhas` (**m**ultiple **has**) method allows to check the existence of several values in a single call. It has the syntax:\n\n```ts\ncache.mhas([key]);\n```\n\nExample:\n\n```ts\ncache.mhas([“key”, “key2”]);\n```\n\n#### Delete all values\n\nTo clear the cache, the `clear` method is used. It has the syntax:\n\n```ts\ncache.clear(options?);\n```\n\nExample (no options):\n\n```ts\ncache.clear();\n```\n\nThe options available in the `clear` are:\n\n- `filter?` (**function**): A function that determines which elements are to be deleted.\n\nExample (with options):\n\n```ts\ncache.clear({\n  filter: (key, value) =\u003e key.startsWith('temp'), // Only values that have an associated key beginning with “temp” will be cleared.\n});\n```\n\n#### Obtain all values\n\nTo get all the values from the cache, the `values` method is used. It has the syntax:\n\n```ts\ncache.values(options?);\n```\n\nExample (no options):\n\n```ts\ncache.values();\n```\n\nThe options available in the `values` are:\n\n- `filter?` (**function**): A function that determines which elements are to be obtained.\n\nExample (with options):\n\n```ts\ncache.values({\n  filter: (key, value) =\u003e key.startsWith('temp'), // Only values that have an associated key beginning with “temp” will be obtained.\n});\n```\n\n#### Obtain all keys\n\nTo get all the keys from the cache, the `keys` method is used. It has the syntax:\n\n```ts\ncache.keys(options?);\n```\n\nExample (no options):\n\n```ts\ncache.keys();\n```\n\nThe options available in the `keys` are:\n\n- `filter?` (**function**): A function that determines which elements are to be obtained.\n\nExample (with options):\n\n```ts\ncache.keys({\n  filter: (key, value) =\u003e key.startsWith('temp'), // Only keys beginning with “temp” will be obtained.\n});\n```\n\n### Algorithms 💿\n\n**FastCache** has the feature of supporting multiple caching algorithms in a single shared syntax. At the moment, the supported algorithms are **LRU**, **2Q**, **LFU**, **FIFO** and **ARC**. Let's look at each of these in detail:\n\n#### **LRU (Least Recently Used)**\n\n**Description:**\nThe LRU (Least Recently Used) algorithm removes the least recently accessed items. It works well when recently accessed data is likely to be needed again.\n\n**Advantages:**\n- 👍🏼 Offers fast access with O(1) complexity for both read and write operations.\n- 👍🏼 Retains the most recent elements, which suits scenarios where recent data is reused frequently.\n\n**Disadvantages:**\n- 👎🏼 Might not perform well in situations with irregular or non-linear data access, as it could evict items that are infrequently accessed but still important.\n\n**Typical Use Cases:**\n- **Frontend**: Storing recently rendered components or API request results.\n- **Backend**: Caching recent user sessions or the most recent HTTP request responses.\n\n```ts\nimport { Cache } from \"fastcache\";\nconst cache = Cache({ algorithm: \"LRU\" });\n\ncache.set(\"key\", \"value\");\nconsole.log(cache.get(\"key\")); // \"value\"\n```\n\n---\n\n#### **2Q (Two Queues)**\n\n**Description:**\n2Q improves upon LRU by using two queues: one for newly accessed items and another for items that have been accessed more than once. This reduces cache pollution since only frequently reused items remain in memory.\n\n**Advantages:**\n- 👍🏼 Performs well in scenarios with many single-access items without displacing more relevant data.\n- 👍🏼 Significantly reduces unnecessary eviction of valuable items.\n\n**Disadvantages:**\n- 👎🏼 Slightly higher memory usage compared to LRU, due to the two queues used for managing data.\n\n**Typical Use Cases:**\n- **APIs or Node.js servers**: Where many requests are unique, but some routes or data are accessed repeatedly.\n- **Applications processing large data volumes**: Prevents eviction of critical items needed more than once.\n\n```ts\nconst cache = Cache({ algorithm: \"2Q\" });\ncache.set(\"key\", \"value\");\nconsole.log(cache.get(\"key\")); // \"value\"\n```\n\n---\n\n#### **LFU (Least Frequently Used)**\n\n**Description:**\nLFU removes the least frequently accessed items, retaining the most popular data. It’s ideal when there’s a clear distinction between frequently and infrequently accessed items.\n\n**Advantages:**\n- 👍🏼 Ensures the most requested data stays in the cache longer.\n- 👍🏼 Great in environments where certain items are expected to have a high volume of repeated access.\n\n**Disadvantages:**\n- 👎🏼 May not adapt quickly to changes in data popularity, as it relies on historical access patterns.\n\n**Typical Use Cases:**\n- **E-commerce**: Caching frequently viewed products to deliver a faster user experience.\n- **Content platforms**: Storing the most popular articles, videos, or posts.\n\n```ts\nconst cache = Cache({ algorithm: \"LFU\" });\ncache.set(\"key\", \"value\");\nconsole.log(cache.get(\"key\")); // \"value\"\n```\n\n---\n\n#### **FIFO (First In, First Out)**\n\n**Description:**\nFIFO removes the oldest item added to the cache, regardless of its access pattern. It is extremely simple and works well in scenarios where insertion order is more important than recency or frequency.\n\n**Advantages:**\n- 👍🏼 Simple implementation with predictable behavior.\n- 👍🏼 Doesn’t require extra memory or complex logic.\n\n**Disadvantages:**\n- 👎🏼 Ignores data recency and usage frequency, which may lead to the eviction of still-relevant items.\n\n**Typical Use Cases:**\n- **Queue processing**: Where elements are processed in the order they were added.\n- **Embedded systems**: Where simplicity and predictable performance are critical.\n\n```ts\nconst cache = Cache({ algorithm: \"FIFO\" });\ncache.set(\"key\", \"value\");\nconsole.log(cache.get(\"key\")); // \"value\"\n```\n\n---\n\n#### **ARC (Adaptive Replacement Cache)**\n\n**Description:**\nARC is an advanced algorithm that dynamically adjusts between LRU and LFU, based on data access patterns. It monitors recent use and frequency to adapt and maximize efficiency.\n\n**Advantages:**\n- 👍🏼 Automatically adapts to different usage patterns, combining the strengths of LRU and LFU.\n- 👍🏼 Optimizes performance without manual intervention or specific configuration.\n\n**Disadvantages:**\n- 👎🏼 Requires more memory and processing time compared to simpler algorithms, as it monitors data access more closely.\n\n**Typical Use Cases:**\n- **File systems**: Where data access can be both sequential and random.\n- **Large or distributed applications**: Where data access patterns change frequently, requiring an adaptive approach.\n\n```ts\nconst cache = Cache({ algorithm: \"ARC\" });\ncache.set(\"key\", \"value\");\nconsole.log(cache.get(\"key\")); // \"value\"\n```\n\n## 🧪 Benchmarks\n\nYou can explore the benchmarks in the [bench](./bench) folder, which includes detailed performance comparisons with other cache systems, along with analysis and visualizations. These results demonstrate how **FastCache** outperforms other solutions in the ecosystem.\n\n## 📄 License\n\n**FastCache** is licensed under the [MIT License](./LICENSE), allowing you the freedom to modify and distribute the code, as long as the copyright notice is retained.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnehu3n%2Ffastcache","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnehu3n%2Ffastcache","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnehu3n%2Ffastcache/lists"}