{"id":22724615,"url":"https://github.com/tcm9439/ts-key-value-cache","last_synced_at":"2026-02-03T16:04:06.835Z","repository":{"id":65324031,"uuid":"588190857","full_name":"tcm9439/ts-key-value-cache","owner":"tcm9439","description":"Typescript Key Value Cache (in-mem / external)","archived":false,"fork":false,"pushed_at":"2024-12-21T11:13:07.000Z","size":252,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-14T14:34:33.686Z","etag":null,"topics":[],"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/tcm9439.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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,"zenodo":null}},"created_at":"2023-01-12T14:41:42.000Z","updated_at":"2024-12-21T11:13:11.000Z","dependencies_parsed_at":"2025-04-13T19:04:59.835Z","dependency_job_id":"81ee6d52-f3e6-473b-a844-a472eef60b31","html_url":"https://github.com/tcm9439/ts-key-value-cache","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/tcm9439/ts-key-value-cache","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tcm9439%2Fts-key-value-cache","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tcm9439%2Fts-key-value-cache/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tcm9439%2Fts-key-value-cache/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tcm9439%2Fts-key-value-cache/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tcm9439","download_url":"https://codeload.github.com/tcm9439/ts-key-value-cache/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tcm9439%2Fts-key-value-cache/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259363298,"owners_count":22846231,"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-12-10T15:07:19.738Z","updated_at":"2026-02-03T16:04:01.814Z","avatar_url":"https://github.com/tcm9439.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Typescript Local Key Value Cache\n\nA key-value cache with string as key and value of any type. It support\n- time-to-live management\n- size control which remove exceed key-value pair in a FIFO manner\n- housekeep function to clear the expired item in cache with O(k log N) times, where k is the number of expired items.\n- in-memory or external storage (e.g. localStorage, Redis) for storing the key-value pair\n\n## Installation\n```\nnpm i ts-key-value-cache\n```\n\n## Examples\n\nTypeScript\n\n```ts\nimport { CacheOption, IKeyValueCache, Duration, IMapStorage } from \"ts-key-value-cache\";\n\n// ===============\n// init a cache\n// ===============\nconst cacheOption = new CacheOption\u003cstring\u003e()\ncacheOption.setMaxSize(100)                                 // this cache keep 100 key-value pair at most\ncacheOption.setDefaultTTL(new Duration({ minutes: 10 }))    // default TTL is 10 minutes\n\n// One cache can only accept one type of value\n// For IKeyValueCache\u003cV\u003e, V is the type of the value it accept\nlet cache: IKeyValueCache\u003cstring\u003e = cacheOption.create()\n// E.g. the value must be string for this cache\n\n// ===============\n// basic usage\n// ===============\n// insert a pair with 30 minute TTL\ncache.put(\"key1\", \"first\", { ttl: new Duration({ minutes: 30 }) })\n// update the value of key1, and renew the ttl to the default on (i.e. 10 minutes)\ncache.put(\"key1\", \"testing\")\n// insert a pair with no TTL (i.e. never expired)\n// it only get removed when the cache is full and need to push out some items, and it is the first one to expired (being oldest item among all items that will not expire when all items in the cache are without TTL)\ncache.put(\"key2\", \"123\", { noTtl: true })\n\nlet value1: string | null = cache.get(\"not-a-key\")\n// value1 is null\n\nlet value2: string | null = cache.get(\"key1\")\n// value2 is \"testing\"\n\n// ====================\n// use external storage\n// ====================\nclass SomeMapStorageImplementation implements IMapStorage\u003cstring\u003e {...}\nconst cacheOption = new CacheOption\u003cstring\u003e()\ncacheOption.setStorage(new SomeMapStorageImplementation())\nlet cache: IKeyValueCache\u003cstring\u003e = cacheOption.create()\n```\n\n## Operations on IKeyValueCache\n`get(key: string): V | null`\nReturn value if found in cache and it is not yet expired. \nOtherwise, return undefined.\n\n`put(key: string, value: V, param?: { ttl?: Duration; noTtl?: boolean; }): void`\nPut the item into cache.\nIf there is already a cache with the same key, this will replace the old one and the expired timestamp will be renew base on the new TTL.\nIf the cache is full, it will remove \n- the item that will expire first if there exist at least one item with TTL\n- the item inserted first if all items in the cache are without TTL\n\n`delete(key: string): boolean`\nDelete the item from cache with the given key if exists.\n\n`clear(): void`\nDelete all items in the cache.\n\n`size(): Integer`\nReturn the total number of item in this cache.\n\n`clearExpiredItems(): void`\nDelete all expired items in the cache.\n\n## Config\n\nThe cache created is config by the `CacheOption` passed to the factory.\nSet up the `CacheOption` by the setter of its attributes (listed below).\n\n\n| Option      | Type             | Default | Description |\n| :---------- | ---------------- | ------- | :---------- |\n| defaultTTL  | Duration or null | null    | The TTL for a item put() without a TTL.\u003cbr /\u003enull = never timeout |\n| maxSize     | integer \u003e 0      | 100     | The maximum number of key-value pairs the cache can hold. |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftcm9439%2Fts-key-value-cache","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftcm9439%2Fts-key-value-cache","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftcm9439%2Fts-key-value-cache/lists"}