{"id":21703269,"url":"https://github.com/hacklone/coool-cachestate","last_synced_at":"2025-07-12T16:37:41.691Z","repository":{"id":214402985,"uuid":"735150362","full_name":"Hacklone/coool-cachestate","owner":"Hacklone","description":"Aspect-oriented cached state library for TypeScript","archived":false,"fork":false,"pushed_at":"2024-06-24T09:45:03.000Z","size":66,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-08T15:51:51.134Z","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":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Hacklone.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":"2023-12-23T21:02:18.000Z","updated_at":"2024-06-24T09:45:06.000Z","dependencies_parsed_at":"2023-12-28T00:54:47.252Z","dependency_job_id":"762d95e4-ba06-4226-b716-3ceae771efd7","html_url":"https://github.com/Hacklone/coool-cachestate","commit_stats":{"total_commits":16,"total_committers":1,"mean_commits":16.0,"dds":0.0,"last_synced_commit":"4ee3643e051ba17afb2638758b57d3e8a8f1da53"},"previous_names":["hacklone/coool-cachestate"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/Hacklone/coool-cachestate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hacklone%2Fcoool-cachestate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hacklone%2Fcoool-cachestate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hacklone%2Fcoool-cachestate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hacklone%2Fcoool-cachestate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Hacklone","download_url":"https://codeload.github.com/Hacklone/coool-cachestate/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hacklone%2Fcoool-cachestate/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265024279,"owners_count":23699589,"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-25T21:30:14.831Z","updated_at":"2025-07-12T16:37:41.669Z","avatar_url":"https://github.com/Hacklone.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @coool/cachestate\n\nA simple-to-use, minimal boilerplate flexible cached state.\n\n## Features\n\n✅ Caching \u003cbr\u003e\n✅ State Management \u003cbr\u003e\n✅ Updates for cache consumers \u003cbr\u003e\n✅ Works with any framework \u003cbr\u003e\n✅ Local Storage Support \u003cbr\u003e\n✅ Custom Storage Asynchronous Support \u003cbr\u003e\n✅ Handles Simultaneous Requests \u003cbr\u003e\n✅ Automatic \u0026 Manual Cache Busting \u003cbr\u003e\n✅ Aspect-Oriented (Decorators) \u003cbr\u003e\n✅ Out-of-the-box LocalStorage and SessionStorage cache data storage \u003cbr\u003e\n\n## Install\n\n```shell script\n$ npm i --save @coool/cachestate\n```\n\n## Basic Usage\n\n### Add CacheState to a function\n\n```typescript\nimport { CacheState } from '@coool/cachestate';\n\n@CacheState()\nfunction getItem$(itemId: ItemId): Observable\u003cItem\u003e {\n  // Get latest version of item from the server\n}\n```\n\n### Consume CacheState\n\n```typescript\ngetItem$('1')\n  .subscribe(item =\u003e {\n    // You'll receive initial cached value and updates here\n  });\n```\n\n### Notify the CacheState that the value needs updating\n\n```typescript\nimport { CacheState, CacheStateUpdater } from '@coool/cachestate';\n\n@CacheState({\n  updatedNotifierKey: 'items-updated',\n})\nfunction getItem$(itemId: ItemId): Observable\u003cItem\u003e {\n  // Get latest version of item from the server\n}\n\n@CacheStateUpdater({\n  updatedNotifierKey: 'items-updated',\n})\nfunction updateItem() {\n  // This will invalidate the cache and call the getItem$ function again then update cache consumers with the latest value \n}\n```\n\n## Use-cases\n\n### Global Configuration\n\nYou can set configurations globally across all CacheStates.\nLocal configuration will take precedence over global configuration.\n\n```typescript\nimport { GlobalCacheStateConfig } from '@coool/cachestate';\n\nGlobalCacheStateConfig.maxAgeMS = 5 * 60 * 1000;\n```\n\n### Invalidate cache without requesting update\n\n```typescript\nimport { CacheState, CacheStateInvalidator } from '@coool/cachestate';\nimport { Subject } from 'rxjs';\n\nconst cacheInvalidatedNotifier = new Subject\u003cvoid\u003e();\n\n@CacheState({\n  invalidatedNotifier: cacheInvalidatedNotifier,\n})\nfunction getItem$(itemId: ItemId): Observable\u003cItem\u003e {\n}\n\n@CacheStateInvalidator({\n  invalidatedNotifier: cacheInvalidatedNotifier,\n})\nfunction updateItem() {\n  // This will invalidate the cache and call the getItem$ function again then update cache consumers with the latest value \n}\n```\n\n### Invalidate all cache globally\n\n```typescript\nimport { invalidateAllCache } from '@coool/cachestate';\n\ninvalidateAllCache();\n```\n\n### Invalidate and update all cache globally\n\n```typescript\nimport { invalidateAndUpdateAllCache } from '@coool/cachestate';\n\ninvalidateAndUpdateAllCache();\n```\n\n### LocalStorage data storage\n\n```typescript\nimport { GlobalCacheStateConfig, BrowserStorageCacheDataStorage } from '@coool/cachestate';\n\nGlobalCacheStateConfig.cacheDataStorage = new BrowserStorageCacheDataStorage(window.localStorage);\n```\n\n### SessionStorage data storage\n\n```typescript\nimport { GlobalCacheStateConfig, BrowserStorageCacheDataStorage } from '@coool/cachestate';\n\nGlobalCacheStateConfig.cacheDataStorage = new BrowserStorageCacheDataStorage(window.sessionStorage);\n```\n\n### Custom cache data storage\n\n```typescript\nimport { CacheDataStorage, GlobalCacheStateConfig } from '@coool/cachestate';\n\nclass MyCacheDataStorage implements CacheDataStorage {\n  // Implement CacheDataStorage interface to store, retrieve and delete cache data\n}\n\nGlobalCacheStateConfig.cacheDataStorage = new MyCacheDataStorage();\n```\n\n## API\n\n### CacheState configuration\n\n| Property                 | Description                                                                                                              | Default                                                                                                               | Required |\n|--------------------------|--------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------|----------|\n| cacheKey.generator       | Generates the cache key                                                                                                  | Combination of cache key prefix and suffix (combination of class, method name and a hash of the function's arguments) | false    |\n| cacheKey.prefixGenerator | Prefix for the cache key                                                                                                 | Combination of class and method name                                                                                  | false    |\n| cacheKey.suffixGenerator | Suffix for the cache key                                                                                                 | A hash of the function's arguments                                                                                    | false    |\n| cacheDataStorage         | A storage where the cache data is stored                                                                                 | Store cached values locally                                                                                           | false    |\n| maxAgeMS                 | Max age of cache in milliseconds                                                                                         | 60000 (1 minute)                                                                                                      | false    |\n| updatedObservable        | When emits the cache is invalidated and updated. If CacheKey is passed then only that cache otherwise all related cache. | undefined                                                                                                             | false    |\n| updatedObservableKey     | When emits the cache is invalidated and updated. If CacheKey is passed then only that cache otherwise all related cache. | undefined                                                                                                             | false    |\n| updateOnlySpecific       | When updated notifier fires only update if specific cache key is defined.                                                | false                                                                                                                 | false    |\n| invalidatedObservable    | When emits the cache is invalidated. If CacheKey is passed then only that cache otherwise all related cache.             | undefined                                                                                                             | false    |\n| invalidatedObservableKey | When emits the cache is invalidated. If CacheKey is passed then only that cache otherwise all related cache.             | undefined                                                                                                             | false    |\n| invalidateOnlySpecific   | When invalidated notifier fires only update if specific cache key is defined.                                            | false                                                                                                                 | false    |\n| timestampProvider        | Provides current timestamp, useful for testing                                                                           |                                                                                                                       | false    |\n\n### CacheStateUpdater configuration\n\n| Property           | Description                                                                                                              | Default   | Required                         |\n|--------------------|--------------------------------------------------------------------------------------------------------------------------|-----------|----------------------------------|\n| updatedNotifier    | When emits the cache is invalidated and updated. If CacheKey is passed then only that cache otherwise all related cache. | undefined | true (OR use updatedNotifierKey) |\n| updatedNotifierKey | Global key identifying updatedNotifier                                                                                   | undefined | true (OR use updatedNotifier)    |\n| cacheKeyGenerator  | Generates the cache key for the updated notifier                                                                         | undefined | false                            |\n\n### CacheStateInvalidator configuration\n\n| Property               | Description                                                                                                  | Default   | Required                             |\n|------------------------|--------------------------------------------------------------------------------------------------------------|-----------|--------------------------------------|\n| invalidatedNotifier    | When emits the cache is invalidated. If CacheKey is passed then only that cache otherwise all related cache. | undefined | true (OR use invalidatedNotifierKey) |\n| invalidatedNotifierKey | Global key identifying invalidatedNotifier.                                                                  | undefined | true (OR use invalidatedNotifier)    |\n| cacheKeyGenerator      | Generates the cache key for the updated notifier                                                             | undefined | false                                |\n\n### Global configuration\n\n| Property          | Description                                    | Default                     | Required |\n|-------------------|------------------------------------------------|-----------------------------|----------|\n| cacheDataStorage  | A storage where the cache data is stored       | Store cached values locally | false    |\n| maxAgeMS          | Max age of cache in milliseconds               | 60000 (1 minute)            | false    |\n| timestampProvider | Provides current timestamp, useful for testing |                             | false    |\n\n## Inspiration\n\nThis project is inspired by [ts-cacheable](https://github.com/angelnikolov/ts-cacheable)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhacklone%2Fcoool-cachestate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhacklone%2Fcoool-cachestate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhacklone%2Fcoool-cachestate/lists"}