{"id":26286367,"url":"https://github.com/m4x1m1l14n/cache-js","last_synced_at":"2025-07-25T23:18:03.379Z","repository":{"id":42454447,"uuid":"421099972","full_name":"m4x1m1l14n/cache-js","owner":"m4x1m1l14n","description":"Lightweight in-memory isomorphic cache implementation with TTL for browser \u0026 Node JS written in TypeScript","archived":false,"fork":false,"pushed_at":"2025-03-14T13:03:03.000Z","size":864,"stargazers_count":3,"open_issues_count":3,"forks_count":1,"subscribers_count":3,"default_branch":"devel","last_synced_at":"2025-04-17T22:02:45.530Z","etag":null,"topics":["browser","cache","in-memory","javascript","memcache","nodejs","ttl","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/m4x1m1l14n.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":"2021-10-25T16:23:42.000Z","updated_at":"2024-12-19T02:37:48.000Z","dependencies_parsed_at":"2025-03-14T20:23:11.400Z","dependency_job_id":"51b8f6d9-7040-4d34-8ddc-49470331fd00","html_url":"https://github.com/m4x1m1l14n/cache-js","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m4x1m1l14n%2Fcache-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m4x1m1l14n%2Fcache-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m4x1m1l14n%2Fcache-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m4x1m1l14n%2Fcache-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/m4x1m1l14n","download_url":"https://codeload.github.com/m4x1m1l14n/cache-js/tar.gz/refs/heads/devel","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252913385,"owners_count":21824162,"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":["browser","cache","in-memory","javascript","memcache","nodejs","ttl","typescript"],"created_at":"2025-03-14T20:21:56.439Z","updated_at":"2025-07-25T23:18:03.346Z","avatar_url":"https://github.com/m4x1m1l14n.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @m4x1m1l14n/cache\n\n[![npm (scoped)](https://img.shields.io/npm/v/@m4x1m1l14n/cache)](https://www.npmjs.com/package/@m4x1m1l14n/cache)\n[![ci](https://github.com/m4x1m1l14n/cache-js/actions/workflows/ci.yml/badge.svg?branch=devel)](https://github.com/m4x1m1l14n/cache-js/actions/workflows/ci.yml)\n[![codecov](https://codecov.io/gh/m4x1m1l14n/cache-js/branch/devel/graph/badge.svg?token=RR5TO815BJ)](https://codecov.io/gh/m4x1m1l14n/cache-js)\n![GitHub issues](https://img.shields.io/github/issues/m4x1m1l14n/cache-js)\n\n# Lightweight in-memory isomorphic cache implementation with TTL for browser \u0026 Node JS\n\nThis simple cache is written in TypeScript and works both for browser and Node. It is build on top of built-in `Map` thus theoretical limit for stored entries is in case of Node 2 ^ 24, which is approximately 16.6 million.\nEach entry in cache can has its own TTL (timeout) and assigned expiration callback fired once entry expire.\n\n## Table of Contents\n\n-   [Installation](#installation)\n-   [Documentation](#documentation)\n    -   [Instantiation](#instantiation)\n    -   [set](#set)\n    -   [get](#get)\n    -   [take](#take)\n    -   [has](#has)\n    -   [delete](#delete)\n    -   [flush](#flush)\n\n## Installation\n\n```bash\nnpm i @m4x1m1l14n/cache\n```\n\n## Documentation\n\n### Instantiation\n\nCache implementation uses templates so when you use this library in TypeScript project, you can restrict what type of `key` and `value` cache has to consume.\n\n```ts\nimport { Cache } from '@m4x1m1l14n/cache';\n\nconst cache = new Cache\u003cnumber, string\u003e();\n```\n\nCache behavior can be altered with `options` object passed to its constructor. Following table shows options that can be changed.\n\n| Option     | Default value | Description                                                         |\n| ---------- | ------------- | ------------------------------------------------------------------- |\n| ~~resolution~~ | ~~1000~~ | **Deprecated.** Previously set interval for checking expiry. Now items expire at exact TTL times using dynamic timeout scheduling for improved accuracy. |\n| defaultTTL | Infinity      | Default TTL for all added entries                                   |\n| maxItems   | 1000          | Maximum number of entries stored in cache                           |\n\n**Expiration Accuracy**: Cache entries now expire at their exact TTL expiration time rather than being checked periodically. This provides better accuracy and performance by scheduling cleanup events precisely when items expire, instead of checking all items at fixed intervals.\n\nExample:\n\n```ts\nimport { Cache, CacheOptions } from '@m4x1m1l14n/cache';\n\nconst options: CacheOptions = {\n\tdefaultTTL: Number.POSITIVE_INFINITY,\n\tmaxItems: 1000,\n};\n\nconst cache = new Cache\u003cnumber, string\u003e(options);\n```\n\n### set\n\nStore value in cache under specified key.\n\nPrototype:\n\n```ts\npublic set( key : K, value : T, ttl? : number, callback?: ExpirationCallback\u003cT\u003e ) : Cache\u003cK, T\u003e;\n```\n\nParams:\n\n-   `key`: Key under which value will be stored\n-   `value`: Value to store\n-   `ttl (optional)`: Timeout after which cache entry will expire and will be deleted\n-   `callback (optional)`: Callback invoked once entry expire\n\nReturn value:\n\n`set` method returns itself, so it is possible to chain multiple sets\n\n```ts\nimport { Cache } from '@m4x1m1l14n/cache';\n\nconst cache = new Cache\u003cnumber, string\u003e();\n\ncache.set(1, 'Hello').set(2, 'World').set(3, '!');\n```\n\nExample:\n\n```ts\nimport { Cache } from '@m4x1m1l14n/cache';\n\nconst cache = new Cache\u003cnumber, string\u003e();\n\n// Key 1 will persist in cache until standardTTL is reached\ncache.set(1, 'Hello');\n// Key 2 will expire after 5 seconds\ncache.set(2, 'World', 5000);\n// Key 3 will expire after 3 seconds, and callback is called\ncache.set(3, 'Some other value', 3000, (value) =\u003e {\n\tconsole.log(`'${value}' has expired`);\n\t// Expected output\n\t// \u003e 'Some other value' has expired\n});\n```\n\n### get\n\nRetrieve value of cached entry by its key.\n\nPrototype:\n\n```ts\npublic get( key : K, refresh = false ) : T | undefined\n```\n\nParams:\n\n-   `key`: Key to retrieve\n-   `refresh (default: false)`: Whether to refresh entry TTL or not. In case `true` is passed, item TTL is refreshed and its expiration is postponed, like item is freshly inserted in cache.\n\nReturn value:\n\n`get` returns value assigned to specified `key`. If `key` is not found in cache, `undefined` is returned.\n\nExample:\n\n```ts\nimport { Cache } from '@m4x1m1l14n/cache';\n\nconst cache = new Cache\u003cnumber, string\u003e();\n\ncache.set(1, 'Hello');\nconsole.log(cache.get(1));\n// Expected output\n// \u003e Hello\n```\n\n### take\n\nRetrieve value of cached entry by its key and remove it from cache.\n\nPrototype:\n\n```ts\npublic take( key: K ): T | undefined\n```\n\nParams:\n\n-   `key`: Key to retrieve\n\nReturn value:\n\n`take` returns value assigned to specified `key`. If `key` is not found in cache, `undefined` is returned.\n\nExample:\n\n```ts\nimport { Cache } from '@m4x1m1l14n/cache';\n\nconst cache = new Cache\u003cnumber, string\u003e();\n\ncache.set(1, 'Hello');\nconsole.log(cache.take(1));\nconsole.log(cache.take(1));\n// Expected output\n// \u003e Hello\n// \u003e undefined\n```\n\n### has\n\nReturns wether cache contains specified key or not.\n\nPrototype:\n\n```ts\npublic has( key : K ) : boolean\n```\n\nParams:\n\n-   `key`: Key to check for\n\nReturn value:\n\n`true` in case `key` exists in cache, `false` otherwise\n\nExample:\n\n```ts\nimport { Cache } from '@m4x1m1l14n/cache';\n\nconst cache = new Cache\u003cnumber, string\u003e();\n\ncache.set(1, 'Hello');\nconsole.log(cache.has(1));\nconsole.log(cache.has(2));\n// Expected output\n// \u003e true\n// \u003e false\n```\n\n### delete\n\nRemoves cache entry by specified key.\n\nPrototype:\n\n```ts\npublic delete( key : K ) : boolean\n```\n\nParams:\n\n-   `key`: Key of entry to remove\n\nReturn value:\n\n`true` in case `key` was removed, `false` otherwise\n\nExample:\n\n```ts\nimport { Cache } from '@m4x1m1l14n/cache';\n\nconst cache = new Cache\u003cnumber, string\u003e();\n\ncache.set(1, 'Hello');\nconsole.log(cache.get(1));\nconsole.log(cache.delete(1));\nconsole.log(cache.get(1));\nconsole.log(cache.delete(1));\n// Expected output\n// \u003e Hello\n// \u003e true\n// \u003e undefined\n// \u003e false\n```\n\n### flush\n\nClears all entries from the cache, with an option to invoke expiration callbacks for each entry before deletion.\n\nPrototype:\n\n```ts\npublic flush(invokeCallback: boolean = false) : void\n```\n\nParams:\n\n-   `invokeCallback (default: false)`: If set to `true`, any expiration callback assigned to an entry will be called before the entry is deleted.\n\nReturn value:\n\n`flush` does not return a value.\n\nExample:\n\n```ts\nimport { Cache } from '@m4x1m1l14n/cache';\n\nconst cache = new Cache\u003cnumber, string\u003e();\n\ncache.set(1, 'Hello', 1000, (value) =\u003e {\n\tconsole.log(`'${value}' has expired`);\n});\ncache.set(2, 'World', 2000, (value) =\u003e {\n\tconsole.log(`'${value}' has expired`);\n});\n\n// Flush cache and invoke callbacks\ncache.flush(true);\n// Expected output:\n// \u003e 'Hello' has expired\n// \u003e 'World' has expired\n\n// Flush cache without invoking callbacks\ncache.flush();\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fm4x1m1l14n%2Fcache-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fm4x1m1l14n%2Fcache-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fm4x1m1l14n%2Fcache-js/lists"}