{"id":21961882,"url":"https://github.com/trapcodeio/brave-cache","last_synced_at":"2025-06-22T18:33:55.269Z","repository":{"id":65911295,"uuid":"443964415","full_name":"trapcodeio/brave-cache","owner":"trapcodeio","description":"A flexible semantic Api for handling multiple cache drivers.","archived":false,"fork":false,"pushed_at":"2023-05-06T06:18:08.000Z","size":79,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-12T16:06:47.622Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/trapcodeio.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"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,"zenodo":null}},"created_at":"2022-01-03T06:36:57.000Z","updated_at":"2023-01-14T13:05:04.000Z","dependencies_parsed_at":"2025-04-23T20:40:59.295Z","dependency_job_id":null,"html_url":"https://github.com/trapcodeio/brave-cache","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/trapcodeio/brave-cache","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trapcodeio%2Fbrave-cache","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trapcodeio%2Fbrave-cache/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trapcodeio%2Fbrave-cache/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trapcodeio%2Fbrave-cache/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/trapcodeio","download_url":"https://codeload.github.com/trapcodeio/brave-cache/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trapcodeio%2Fbrave-cache/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261343823,"owners_count":23144739,"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","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":[],"created_at":"2024-11-29T10:19:30.516Z","updated_at":"2025-06-22T18:33:50.231Z","avatar_url":"https://github.com/trapcodeio.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Brave Cache\n\nBrave Cache is a simple caching library **manager** for Nodejs.\n\nNodeJs Ecosystem already has lots of caching libraries and this is not one of them, but they are not **merge-able** and consists of **different apis.**\nBrave Cache supports adding multiple cache providers/drivers while keeping same api.\n\n## Table of Contents\n\n-   [Why Brave Cache?](#why-brave-cache)\n-   [Installation](#installation)\n-   [Usage](#usage)\n-   [Providers](#providers)\n-   [Register Provider](#register-provider)\n-   [Cache Instance Api](#cache-instance-api)\n    -   [get](#get) or [getAsync](#getasync)\n    -   [getMany](#getmany) or [getManyAsync](#getmanyasync)\n    -   [set](#set) or [setAsync](#setasync)\n    -   [setMany](#setmany) or [setManyAsync](#setmanyasync)\n    -   [getOrSet](#getorset) or [getOrSetAsync](#getorsetasync)\n    -   [has](#has) or [hasAsync](#hasasync)\n    -   [del](#del) or [delAsync](#delasync)\n    -   [remove](#remove) or [removeAsync](#removeasync)\n    -   [keys](#keys) or [keysAsync](#keysasync)\n    -   [keysWithPrefix](#keyswithprefix) or [keysWithPrefixAsync](#keyswithprefixasync)\n    -   [flush](#flush) or [flushAsync](#flushasync)\n    -   [size](#size) or [sizeAsync](#sizeasync)\n-   [Create Custom Provider](#create-custom-provider)\n-   [Use Custom Provider](#use-custom-provider)\n\n## Why Brave Cache?\n\n-   Support **multiple** cache providers/drivers\n-   Support key prefixing.\n-   Provides **rare** functions for managing multiple caches.\n-   Provides **sync** and **async** methods for managing caches.\n-   One **Api** for all cache providers/drivers\n-   Easy to create your own custom cache system if need be.\n\n## Installation\n\n```sh\nnpm install brave-cache\n# OR\nyarn add brave-cache\n```\n\n## Usage\n\n```js\nconst BraveCache = require(\"brave-cache\");\n\n// Create Cache, it will use the default provider\nconst cache = new BraveCache();\ncache.set(\"pet\", \"cat\");\n\nconsole.log(cache.get(\"pet\")); // \"cat\"\n\n// You can also access the provider\ncache.provider.client.set(\"direct\", \"direct\");\n\nconsole.log(cache.get(\"direct\")); // =\u003e direct\nconsole.log(cache.provider.client.get(\"direct\")); // =\u003e direct\n```\n\n## Providers\n\nOut of the box, BraveCache provides supports for the following cache libraries:\n\n-   Object Cache using [object-collection](https://npmjs.com/package/object-collection) (default)\n-   [LRU Cache](http://npmjs.com/package/lru-cache) (requires package: `lru-cache`)\n-   [Node Cache](https://www.npmjs.com/package/node-cache) (requires package: `node-cache`)\n\nThe default Provider is `ObjectCacheProvider` which uses [`object-collection`](https://npmjs.com/package/object-collection) to store the cache data in an object.\nIt has been registered by default.\n\n## Register Provider\n\nThe `registerProvider` method can be used to register a custom provider.\n\nit takes two arguments:\n\n| Argument   | Type     | Description                                               |\n| ---------- | -------- | --------------------------------------------------------- |\n| `provider` | `object` | The provider object i.e. instance of `BraveCacheProvider` |\n| `as`       | `string` | Custom name of the provider (optional)                    |\n\n```js\nconst BraveCache = require(\"brave-cache\");\nconst LRUCacheProvider = require(\"brave-cache/providers/lru-cache\");\n\n// default name is `lru-cache`\nBraveCache.registerProvider(LRUCacheProvider());\n// custom name as `my-cache`\nBraveCache.registerProvider(LRUCacheProvider(), \"my-cache\");\n// custom name as `my-cache-2` and max size of 50\nBraveCache.registerProvider(LRUCacheProvider({ max: 50 }), \"my-cache-2\");\n\nconst cache = new BraveCache(\"lru-cache\");\nconst cache2 = new BraveCache(\"my-cache\");\nconst cache3 = new BraveCache(\"my-cache-2\");\n```\n\nProviders are registered and accessed by their names.\n\n## Prefix support.\n\nBrave Cache adds prefix support to the cache keys without needing the provider to do it.\non `get` and `set` methods the prefix will be added.\n\nThe example below is how brave cache works without prefix.\n\n```js\n// will use default provider (ObjectCacheProvider)\nconst cache1 = new BraveCache();\nconst cache2 = new BraveCache();\n\n// cache1 and cache2 will have same data\ncache1.set(\"test\", \"from cache1\");\n// this will overwrite the value for `test` in cache1\ncache2.set(\"test\", \"from cache2\");\n\ncache1.get(\"test\"); // =\u003e from cache2\ncache2.get(\"test\"); // =\u003e from cache2\n```\n\n`cache1` and `cache2` will have same data because they are both using the same provider and without prefix you are referring to the same key in one provider.\n\nThe example below is how brave cache works with prefix.\n\n```js\n// will use default provider (ObjectCacheProvider)\nconst cache1 = new BraveCache({ prefix: \"cache1\" });\nconst cache2 = new BraveCache({ prefix: \"cache2\" });\nconst cache3 = new BraveCache(); // no prefix\n\ncache1.set(\"test\", \"from cache1\");\n\ncache2.set(\"test\", \"from cache2\");\ncache2.set(\"test2\", \"another value from cache2\");\n\ncache1.get(\"test\"); // =\u003e from cache1\ncache1.get(\"test2\"); // =\u003e undefined\n\ncache2.get(\"test\"); // =\u003e from cache\ncache2.get(\"test2\"); // =\u003e another value from cache2\n\ncache1.size(); // =\u003e 1\ncache2.size(); // =\u003e 2\ncache3.size(); // =\u003e 3\n```\n\n`cache1` and `cache2` will not have same date because they are using different prefix. Meanwhile `cache3` will have `cache1 + cache2` data because they all reference the same provider instance.\n\n## Cache Instance Api\n\nThese are the functions available on the cache instance. Unlike other cache packages, all instance methods come in both `sync` and `async` versions.\n\nNote: `Async` methods will only work if your provider supports async operations. most cache libraries do not support async operations.\n\nExample of a cache instance.\n\n```js\nconst cache = new BraveCache();\n// or specify a provider\nconst cache = new BraveCache(\"object-cache\");\n```\n\n### get()\n\nGet a value from the cache.\n\n```js\ncache.set(\"key\", \"value\");\n\ncache.get(\"key\"); // =\u003e \"value\"\ncache.get(\"non existent key\"); // =\u003e undefined\n\n// cache with default value\ncache.get(\"non existent key\", \"default value\"); // =\u003e \"default value\"\n\n// Or with default value computed from a function\ncache.get(\"non existent key\", () =\u003e \"default value\"); // =\u003e \"default value\"\n```\n\n### getAsync()\n\nAsync version of `get()`, Includes all the functionalities of `get()` with extra capability to resolve promises or functions that return promises.\n\n```js\n// Includes all the functionality of get()\n// Or with default value as a promise\nawait cache.getAsync(\"non existent key\", Promise.resolve(\"default value\")); // =\u003e \"default value\"\n\n// Or with default value computed from a function\nawait cache.getAsync(\"non existent key\", () =\u003e \"default value\"); // =\u003e \"default value\"\n\n// Or with default value computed from a function that returns a promise\nawait cache.getAsync(\"non existent key\", () =\u003e Promise.resolve(\"default value\")); // =\u003e \"default value\"\n```\n\n### getMany()\n\nGet multiple values at once. keys that do not exist will be ignored.\n\n```js\n// Set Many\ncache.setMany([\n    [\"key1\", \"value1\"],\n    [\"key2\", \"value2\"],\n    [\"key3\", \"value3\"]\n]);\n\nlet test = cache.getMany([\"key1\", \"key2\", \"key3\", \"key4\"]);\n\nconsole.log(test.key1); // =\u003e \"value1\";\nconsole.log(test.key2); // =\u003e \"value2\";\nconsole.log(test.key3); // =\u003e \"value3\";\nconsole.log(test.key4); // =\u003e undefined;\n```\n\n### getManyAsync()\n\nAsync version of `getMany()`\n\n### set()\n\nSet a value in the cache.\n\n```js\ncache.set(\"key\", \"value\"); // set key to value\n```\n\n### setAsync()\n\nAsync version of `set()`\n\n### setMany()\n\nSet multiple values at once.\n\n```js\n// using array of key value pairs\ncache.setMany([\n    [\"key1\", \"value1\"],\n    [\"key2\", \"value2\", 500] // with TTL\n]);\n\n// using object\ncache.setMany([\n    { key: \"key3\", value: \"value3\" },\n    { key: \"key4\", value: \"value4\", ttl: 500 } // or with TTL in seconds\n]);\n\nconsole.log(cache.keys()); // =\u003e [\"key1\", \"key2\", \"key3\", \"key4\"]\n```\n\n### setManyAsync()\n\nAsync version of `setMany()`\n\n### getOrSet()\n\nFind a value in the cache. If it does not exist, set it to the default value.\n\n```js\ncache.getOrSet(\"username\", \"joe\"); // =\u003e \"joe\"\n\n// cache should have username set to joe\ncache.has(\"username\"); // =\u003e true\n\n// Trying again will return the value set in the cache\ncache.getOrSet(\"username\", \"john\"); // =\u003e \"joe\" because joe is still in the cache\n\n// Functions can be used as default values\ncache.getOrSet(\"email\", () =\u003e \"joe@example.com\"); // =\u003e \"joe@example.com\"\n```\n\n### getOrSetAsync()\n\nAsync version of `getOrSet()`\n\n### has()\n\nCheck if key exists in the cache.\n\n```js\ncache.set(\"pet\", \"cat\");\n\ncache.has(\"pet\"); // =\u003e true\ncache.has(\"pet2\"); // =\u003e false\n```\n\n### hasAsync()\n\nAsync version of `has()`\n\n### del()\n\nDelete a key from the cache.\n\n```js\ncache.set(\"pet\", \"dog\");\n\ncache.del(\"pet\");\n\ncache.has(\"pet\"); // =\u003e false\n```\n\n### delAsync()\n\nAsync version of `del()`\n\n### remove()\n\nAlias for `del()`\n\n### removeAsync()\n\nAlias for `delAsync()`\n\n### Keys()\n\nGet all the keys in the cache.\n\n```js\ncache.setMany([\n    [\"pet\", \"dog\"],\n    [\"username\", \"joe\"],\n    [\"email\", \"joe@example.com\"]\n]);\n\ncache.keys(); // =\u003e [\"pet\", \"username\", \"email\"]\n```\n\n### keysAsync()\n\nAsync version of `keys()`\n\n### keysWithPrefix()\n\n```js\nconst cache = new BraveCache({ prefix: \"a\" });\n\ncache.setMany([\n    [\"pet\", \"dog\"],\n    [\"username\", \"joe\"],\n    [\"email\", \"joe@example.com\"]\n]);\n\ncache.keys(); // =\u003e [\"pet\", \"username\", \"email\"]\ncache.keysWithPrefix(); // =\u003e [\"a:pet\", \"a:username\", \"a:email\"]\n```\n\n### keysWithPrefixAsync()\n\nAsync version of `keysWithPrefix()`\n\n### flush()\n\nEmpty the cache completely.\n\n### flushAsync()\n\nAsync version of `flush()`\n\n### size()\n\nGet the number of items in the cache.\n\n### sizeAsync()\n\nAsync version of `size()`\n\n## Create Custom Provider\n\nBasically all nodejs `cache` modules have similar api, so creating a custom provider is easy.\n\nA custom provider is a `function` that takes any necessary configuration and returns a `BraveCacheProvider` class instance.\n\n```js\nconst BraveCacheProvider = require(\"brave-cache/src/BraveCacheProvider\");\n\nfunction SimpleCache() {\n    // Holds cache values\n    let SimpleCacheStore = {};\n\n    // Return provider instance\n    return new BraveCacheProvider({\n        name,\n        functions: {\n            get(key) {\n                return SimpleCacheStore[key];\n            },\n\n            set(key, value) {\n                SimpleCacheStore[key] = value;\n            },\n\n            has(key) {\n                return SimpleCacheStore.hasOwnProperty(key);\n            },\n\n            del(key) {\n                delete SimpleCacheStore[key];\n            },\n\n            flush() {\n                SimpleCacheStore = {};\n            },\n\n            keys() {\n                return Object.keys(SimpleCacheStore);\n            }\n        }\n    });\n}\n```\n\nFrom the example above, the `SimpleCache` provider is a simple implementation of how to create a cache Provider.\n\nNotice that you have to implement all the functions that are required by the `BraveCacheProvider` class.\nThese functions will be used when accessing the cache.\n\nFunctions to be implemented: `get`, `set`, `has`, `del`, `flush`, `keys`\n\nOptional functions: `getMany`\n\nNote: if any optional function is not implemented, BraveCache in house function will be used instead.\n\n### Use Custom Provider\n\nA custom Provider function can include arguments that are related to the provider.\n\n```js\nconst BraveCache = require(\"brave-cache\");\n\n// Register Simple Cache Above\nBraveCache.registerProvider(SimpleCache());\n\nconst cache = new BraveCache(\"simple-cache\"); // `simple-cache` is the name of the provider\n\ncache.set(\"test\", \"value\");\n\nconsole.log(cache.get(\"test\")); // =\u003e value\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrapcodeio%2Fbrave-cache","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftrapcodeio%2Fbrave-cache","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrapcodeio%2Fbrave-cache/lists"}