{"id":13671432,"url":"https://github.com/pamelafox/lscache","last_synced_at":"2025-05-14T16:12:47.101Z","repository":{"id":1115765,"uuid":"985923","full_name":"pamelafox/lscache","owner":"pamelafox","description":"A localStorage-based memcache-inspired client-side caching library.","archived":false,"fork":false,"pushed_at":"2022-06-07T21:25:35.000Z","size":250,"stargazers_count":1464,"open_issues_count":15,"forks_count":160,"subscribers_count":44,"default_branch":"master","last_synced_at":"2024-10-29T15:48:30.338Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pamelafox.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2010-10-14T03:25:38.000Z","updated_at":"2024-10-21T01:09:38.000Z","dependencies_parsed_at":"2022-08-16T12:05:14.317Z","dependency_job_id":null,"html_url":"https://github.com/pamelafox/lscache","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pamelafox%2Flscache","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pamelafox%2Flscache/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pamelafox%2Flscache/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pamelafox%2Flscache/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pamelafox","download_url":"https://codeload.github.com/pamelafox/lscache/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248631669,"owners_count":21136554,"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-02T09:01:09.581Z","updated_at":"2025-04-12T20:39:16.387Z","avatar_url":"https://github.com/pamelafox.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"lscache\n===============================\nThis is a simple library that emulates `memcache` functions using HTML5 `localStorage`, so that you can cache data on the client\nand associate an expiration time with each piece of data. If the `localStorage` limit (~5MB) is exceeded, it tries to create space by removing the items that are closest to expiring anyway. If `localStorage` is not available at all in the browser, the library degrades by simply not caching and all cache requests return null.\n\nMethods\n-------\n\nThe library exposes these methods: `set()`, `get()`, `remove()`, `flush()`, `flushExpired()`, `setBucket()`, `resetBucket()`, `setExpiryMilliseconds()`.\n\n* * *\n\n### lscache.set\nStores the value in localStorage. Expires after specified number of minutes.\n#### Arguments\n1. `key` (**string**)\n2. `value` (**Object|string**)\n3. `time` (**number: optional**)\n\n#### Returns\n**boolean** : True if the value was stored successfully.\n\n* * *\n\n### lscache.get\nRetrieves specified value from localStorage, if not expired.\n#### Arguments\n1. `key` (**string**)\n\n#### Returns\n**string | Object** : The stored value. If no value is available, null is returned.\n\n* * *\n\n### lscache.remove\nRemoves a value from localStorage.\n#### Arguments\n1. `key` (**string**)\n\n* * *\n\n### lscache.flush\nRemoves all lscache items from localStorage without affecting other data.\n\n* * *\n\n### lscache.flushExpired\nRemoves all expired lscache items from localStorage without affecting other data.\n\n* * *\n\n### lscache.setBucket\nAppends CACHE_PREFIX so lscache will partition data in to different buckets.\n#### Arguments\n1. `bucket` (**string**)\n\n* * *\n\n### lscache.resetBucket\nRemoves prefix from keys so that lscache no longer stores in a particular bucket.\n\n* * *\n\n### lscache.setExpiryMilliseconds\nSets the number of milliseconds each time unit represents in the set() function's \"time\" argument. Sample values:\n*  1: each time unit = 1 millisecond\n*  1000: each time unit = 1 second\n*  60000: each time unit = 1 minute (Default value)\n*  3600000: each time unit = 1 hour\n#### Arguments\n1. `milliseconds` (**number**)\n\nUsage\n-------\n\nThe interface should be familiar to those of you who have used `memcache`, and should be easy to understand for those of you who haven't.\n\nFor example, you can store a string for 2 minutes using `lscache.set()`:\n\n```js\nlscache.set('greeting', 'Hello World!', 2);\n```\n\nYou can then retrieve that string with `lscache.get()`:\n\n```js\nalert(lscache.get('greeting'));\n```\n\nYou can remove that string from the cache entirely with `lscache.remove()`:\n\n```js\nlscache.remove('greeting');\n```\n\nYou can remove all items from the cache entirely with `lscache.flush()`:\n\n```js\nlscache.flush();\n```\n\nYou can remove only expired items from the cache entirely with `lscache.flushExpired()`:\n\n```js\nlscache.flushExpired();\n```\n\nYou can also check if local storage is supported in the current browser with `lscache.supported()`:\n\n```js\nif (!lscache.supported()) {\n  alert('Local storage is unsupported in this browser');\n  return;\n}\n```\n\nYou can enable console warning if set fails with `lscache.enableWarnings()`:\n\n```js\n// enable warnings\nlscache.enableWarnings(true);\n\n// disable warnings\nlscache.enableWarnings(false);\n```\n\nThe library also takes care of serializing objects, so you can store more complex data:\n\n```js\nlscache.set('data', {'name': 'Pamela', 'age': 26}, 2);\n```\n\nAnd then when you retrieve it, you will get it back as an object:\n\n```js\nalert(lscache.get('data').name);\n```\n\nIf you have multiple instances of lscache running on the same domain, you can partition data in a certain bucket via:\n\n```js\nlscache.set('response', '...', 2);\nlscache.setBucket('lib');\nlscache.set('path', '...', 2);\nlscache.flush(); //only removes 'path' which was set in the lib bucket\n```\n\nThe default unit for the `set()` function's \"time\" argument is minutes.  A shorter time may be desired, for example, in unit tests.  You can use `lscache.setExpriryMilliseconds()` to select a finer granularity of time unit:\n```js\nasyncTest('Testing set() and get() with different units', function() {´\n  var expiryMilliseconds = 1000;  //time units is seconds\n  lscache.setExpiryMilliseconds(expiryMilliseconds);\n  var key = 'thekey';\n  var numExpiryUnits = 2; // expire after two seconds\n  lscache.set(key, 'some value', numExpiryUnits);\n  setTimeout(function() {\n    equal(lscache.get(key), null, 'We expect value to be null');\n    start();\n  }, expiryMilliseconds*numExpiryUnits + 1);\n});\n```\n\nFor more live examples, play around with the demo here:\nhttp://pamelafox.github.com/lscache/demo.html\n\n\nReal-World Usage\n----------\nThis library was originally developed with the use case of caching results of JSON API queries\nto speed up my webapps and give them better protection against flaky APIs.\n(More on that in this [blog post](http://blog.pamelafox.org/2010/10/lscache-localstorage-based-memcache.html))\n\nFor example, [RageTube](https://github.com/pamelafox/ragetube) uses `lscache` to fetch Youtube API results for 10 minutes:\n\n```js\nvar key = 'youtube:' + query;\nvar json = lscache.get(key);\nif (json) {\n  processJSON(json);\n} else {\n  fetchJSON(query);\n}\n\nfunction processJSON(json) {\n  // ..\n}\n\nfunction fetchJSON() {\n  var searchUrl = 'http://gdata.youtube.com/feeds/api/videos';\n  var params = {\n   'v': '2', 'alt': 'jsonc', 'q': encodeURIComponent(query)\n  }\n  JSONP.get(searchUrl, params, null, function(json) {\n    processJSON(json);\n    lscache.set(key, json, 10);\n  });\n}\n```\n\nIt does not have to be used for only expiration-based caching, however. It can also be used as just a wrapper for `localStorage`, as it provides the benefit of handling JS object (de-)serialization.\n\nFor example, the [QuizCards](https://github.com/pamelafox/chrome-cards) Chrome extensions use `lscache`\nto store the user statistics for each user bucket, and those stats are an array\nof objects.\n\n```js\nfunction initBuckets() {\n  var bucket1 = [];\n  for (var i = 0; i \u003c CARDS_DATA.length; i++) {\n    var datum = CARDS_DATA[i];\n    bucket1.push({'id': datum.id, 'lastAsked': 0});\n  }\n  lscache.set(LS_BUCKET + 1, bucket1);\n  lscache.set(LS_BUCKET + 2, []);\n  lscache.set(LS_BUCKET + 3, []);\n  lscache.set(LS_BUCKET + 4, []);\n  lscache.set(LS_BUCKET + 5, []);\n  lscache.set(LS_INIT, 'true')\n}\n```\n\nBrowser Support\n----------------\n\nThe `lscache` library should work in all browsers where `localStorage` is supported.\nA list of those is here:\nhttp://www.quirksmode.org/dom/html5.html\n\n\nBuilding\n----------------\n\nFor contributors:\n\n* Run `npm install` to install all the dependencies.\n* Run `grunt`. The default task will check the files with jshint, minify them, and use browserify to generate a bundle for testing.\n* Run `grunt test` to run the tests.\n\n\nFor repo owners, after a code change:\n\n* Run `grunt bump` to tag the new release.\n* Run `npm login`, `npm publish` to release on npm.\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpamelafox%2Flscache","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpamelafox%2Flscache","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpamelafox%2Flscache/lists"}