{"id":13825753,"url":"https://github.com/jsumners/abstract-cache","last_synced_at":"2025-09-12T03:05:33.126Z","repository":{"id":49219998,"uuid":"111614569","full_name":"jsumners/abstract-cache","owner":"jsumners","description":null,"archived":false,"fork":false,"pushed_at":"2019-10-07T11:01:10.000Z","size":19,"stargazers_count":23,"open_issues_count":0,"forks_count":7,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-12-29T08:47:32.020Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","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/jsumners.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}},"created_at":"2017-11-21T23:51:00.000Z","updated_at":"2024-10-20T02:15:36.000Z","dependencies_parsed_at":"2022-08-19T01:31:26.007Z","dependency_job_id":null,"html_url":"https://github.com/jsumners/abstract-cache","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jsumners%2Fabstract-cache","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jsumners%2Fabstract-cache/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jsumners%2Fabstract-cache/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jsumners%2Fabstract-cache/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jsumners","download_url":"https://codeload.github.com/jsumners/abstract-cache/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":232802584,"owners_count":18578688,"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-08-04T09:01:26.486Z","updated_at":"2025-01-07T00:18:55.550Z","avatar_url":"https://github.com/jsumners.png","language":"JavaScript","readme":"# abstract-cache\n\n*abstract-cache* is a module that provides a common interface to multiple\ncaching strategies. It allows for requiring *abstract-cache* everywhere while\ndefining the strategy via a simple configuration.\n\n*abstract-cache* is heavily inspired by the excellent [Catbox][catbox]. The\ndecision to create *abstract-cache* was predicated on a desire to require\nimplementing clients accept previously established connections in addtion to\naccepting configuration to create their own connections. It also seeks to\nallow using either the callback or async/await style of asynchronous\nprogramming.\n\n[catbox]: https://npm.im/catbox\n\n### Available Clients\n\n+ [abstract-cache-mongo](https://github.com/jsumners/abstract-cache-mongo)\n+ [abstract-cache-redis](https://github.com/jsumners/abstract-cache-redis)\n\n## Example\n\nThe following example uses *abstract-cache*'s included in-memory cache. Of note,\nis that the included in-memory cache is actually callback based.\n\n```js\nconst cache = require('abstract-cache')({useAwait: true})\n\nasync function doSomething () {\n  const val = await cache.get('foo')\n  console.log(val)\n}\n\ncache.set('foo', 'foo', 100)\n  .then(doSomething)\n  .catch(console.error)\n```\n\nThis example shows instantiating *abstract-cache* with a specific store that\nrelies upon a connection to a remote system. In this example we are supplying\nan already existing connection to the remote system; all *abstract-cache*\ncompliant clients **must** support this.\n\n```js\nconst cache = require('abstract-cache')({\n  useAwait: true,\n  driver: {\n    name: 'abstract-cache-redis',\n    options: {\n      client: require('redis')({url: 'some.redis.url'})\n    }\n  }\n})\n\nasync function doSomething () {\n  const val = await cache.get('foo')\n  console.log(val)\n}\n\ncache.set('foo', 'foo', 100)\n  .then(doSomething)\n  .catch(console.error)\n```\n\n## Options\n\n*abstract-client* accepts an options object with the following properties:\n\n+ `useAwait` (Default: `false`): designate that the resulting cache client\nshould use `async/await` functions. When `false`, every method accepts a\nstandard `callback(err, result)`.\n+ `client` (Default: `undefined`): an already instantiated strategy client.\nIn combination with `useAwait` the client can be wrapped accordingly. Specifying\na `client` superceeds the `driver` configuration.\n+ `driver`:\n    * `name` (Default: `undefined`): specifies the implementing strategy to\n    load. The default value results in the buil-in in-memory strategy being\n    loaded -- this is **not recommended** for production environments.\n    * `options` (Default: `{}`): an options object to pass to the strategy\n    while loading. The strategy should describe this object.\n\n### memclient\n\nThe included in-memory client is available as:\n\n```js\nconst memclientFactory = require('abstract-cache').memclient\n```\n\nIt accepts an options object:\n\n+ `segment` (Default: `abstractMemcache`): the default segment in which to store\nitems.\n+ `maxItems` (Default: `100000`): the maximum number of items to keep in the\ncache. The backing is an LRU cache with an upper bound.\n\n## Protocol\n\nAll implementing strategies **must** implement the protocol described in this\nsection.\n\n1. The module should export a factory `function (optionsObject) {}`.\n1. Accept an existing connection to data stores via the `optionsObject`.\n1. Manage connections created by itself.\n1. In all cases where a `key` is required, the `key` may be a simple string,\nor it may be an object of the format `{id: 'name', segment: 'name'}`. It is\nup to the implementing strategy to decide how to handle these keys.\n1. The factory function should return an object (client) that has the following\nmethods and properties:\n    * `await` (boolean property): `true` indicates that the strategy's methods\n    are *all* `async` functions. If `false`, all methods **must** have a\n    `callback(err, result)` as the last parameter.\n    * `delete(key[, callback])`: removes the specified item from the cache.\n    * `get(key[, callback])`: retrieves the desired item from the cache. The\n    returned item should be a deep copy of the stored value to prevent alterations\n    from affecting the cache. The result should be an object with the properties:\n        + `item`: the item the user cached.\n        + `stored`: a `Date`, in Epoch milliseconds, indicating when the item\n        was stored.\n        + `ttl`: the *remaining* lifetime of the item in the cache (milliseconds).\n    * `has(key[, callback])`: returns a boolean result indicating if the cache\n    contains the desired `key`.\n    * `set(key, value, ttl[, callback])`: stores the specified `value` in the\n    cache under the specified `key` for the time `ttl` in milliseconds.\n    * `start([callback])` (optional): clients that require extra initialization,\n    e.g. to start a database connection, may export this method. When present,\n    this method **must** be invoked by the user before any other method. This\n    method may be an `async` function at the discretion of the implementor.\n    * `stop([callback])` (optional): required when `start()` is present. This\n    should shutdown any connections/processes started via `start()`. It is\n    left to the user to invoke this method in their shutdown procedure. This\n    method may be an `async` function at the discretion of the implementor.\n\n## License\n\n[MIT License](http://jsumners.mit-license.org/)\n\n","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjsumners%2Fabstract-cache","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjsumners%2Fabstract-cache","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjsumners%2Fabstract-cache/lists"}