https://github.com/hacklone/coool-cachestate
Aspect-oriented cached state library for TypeScript
https://github.com/hacklone/coool-cachestate
Last synced: 12 months ago
JSON representation
Aspect-oriented cached state library for TypeScript
- Host: GitHub
- URL: https://github.com/hacklone/coool-cachestate
- Owner: Hacklone
- License: mit
- Created: 2023-12-23T21:02:18.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-06-24T09:45:03.000Z (about 2 years ago)
- Last Synced: 2025-07-08T15:51:51.134Z (12 months ago)
- Language: TypeScript
- Size: 64.5 KB
- Stars: 7
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# @coool/cachestate
A simple-to-use, minimal boilerplate flexible cached state.
## Features
✅ Caching
✅ State Management
✅ Updates for cache consumers
✅ Works with any framework
✅ Local Storage Support
✅ Custom Storage Asynchronous Support
✅ Handles Simultaneous Requests
✅ Automatic & Manual Cache Busting
✅ Aspect-Oriented (Decorators)
✅ Out-of-the-box LocalStorage and SessionStorage cache data storage
## Install
```shell script
$ npm i --save @coool/cachestate
```
## Basic Usage
### Add CacheState to a function
```typescript
import { CacheState } from '@coool/cachestate';
@CacheState()
function getItem$(itemId: ItemId): Observable {
// Get latest version of item from the server
}
```
### Consume CacheState
```typescript
getItem$('1')
.subscribe(item => {
// You'll receive initial cached value and updates here
});
```
### Notify the CacheState that the value needs updating
```typescript
import { CacheState, CacheStateUpdater } from '@coool/cachestate';
@CacheState({
updatedNotifierKey: 'items-updated',
})
function getItem$(itemId: ItemId): Observable {
// Get latest version of item from the server
}
@CacheStateUpdater({
updatedNotifierKey: 'items-updated',
})
function updateItem() {
// This will invalidate the cache and call the getItem$ function again then update cache consumers with the latest value
}
```
## Use-cases
### Global Configuration
You can set configurations globally across all CacheStates.
Local configuration will take precedence over global configuration.
```typescript
import { GlobalCacheStateConfig } from '@coool/cachestate';
GlobalCacheStateConfig.maxAgeMS = 5 * 60 * 1000;
```
### Invalidate cache without requesting update
```typescript
import { CacheState, CacheStateInvalidator } from '@coool/cachestate';
import { Subject } from 'rxjs';
const cacheInvalidatedNotifier = new Subject();
@CacheState({
invalidatedNotifier: cacheInvalidatedNotifier,
})
function getItem$(itemId: ItemId): Observable {
}
@CacheStateInvalidator({
invalidatedNotifier: cacheInvalidatedNotifier,
})
function updateItem() {
// This will invalidate the cache and call the getItem$ function again then update cache consumers with the latest value
}
```
### Invalidate all cache globally
```typescript
import { invalidateAllCache } from '@coool/cachestate';
invalidateAllCache();
```
### Invalidate and update all cache globally
```typescript
import { invalidateAndUpdateAllCache } from '@coool/cachestate';
invalidateAndUpdateAllCache();
```
### LocalStorage data storage
```typescript
import { GlobalCacheStateConfig, BrowserStorageCacheDataStorage } from '@coool/cachestate';
GlobalCacheStateConfig.cacheDataStorage = new BrowserStorageCacheDataStorage(window.localStorage);
```
### SessionStorage data storage
```typescript
import { GlobalCacheStateConfig, BrowserStorageCacheDataStorage } from '@coool/cachestate';
GlobalCacheStateConfig.cacheDataStorage = new BrowserStorageCacheDataStorage(window.sessionStorage);
```
### Custom cache data storage
```typescript
import { CacheDataStorage, GlobalCacheStateConfig } from '@coool/cachestate';
class MyCacheDataStorage implements CacheDataStorage {
// Implement CacheDataStorage interface to store, retrieve and delete cache data
}
GlobalCacheStateConfig.cacheDataStorage = new MyCacheDataStorage();
```
## API
### CacheState configuration
| Property | Description | Default | Required |
|--------------------------|--------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------|----------|
| 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 |
| cacheKey.prefixGenerator | Prefix for the cache key | Combination of class and method name | false |
| cacheKey.suffixGenerator | Suffix for the cache key | A hash of the function's arguments | false |
| cacheDataStorage | A storage where the cache data is stored | Store cached values locally | false |
| maxAgeMS | Max age of cache in milliseconds | 60000 (1 minute) | false |
| updatedObservable | When emits the cache is invalidated and updated. If CacheKey is passed then only that cache otherwise all related cache. | undefined | false |
| updatedObservableKey | When emits the cache is invalidated and updated. If CacheKey is passed then only that cache otherwise all related cache. | undefined | false |
| updateOnlySpecific | When updated notifier fires only update if specific cache key is defined. | false | false |
| invalidatedObservable | When emits the cache is invalidated. If CacheKey is passed then only that cache otherwise all related cache. | undefined | false |
| invalidatedObservableKey | When emits the cache is invalidated. If CacheKey is passed then only that cache otherwise all related cache. | undefined | false |
| invalidateOnlySpecific | When invalidated notifier fires only update if specific cache key is defined. | false | false |
| timestampProvider | Provides current timestamp, useful for testing | | false |
### CacheStateUpdater configuration
| Property | Description | Default | Required |
|--------------------|--------------------------------------------------------------------------------------------------------------------------|-----------|----------------------------------|
| 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) |
| updatedNotifierKey | Global key identifying updatedNotifier | undefined | true (OR use updatedNotifier) |
| cacheKeyGenerator | Generates the cache key for the updated notifier | undefined | false |
### CacheStateInvalidator configuration
| Property | Description | Default | Required |
|------------------------|--------------------------------------------------------------------------------------------------------------|-----------|--------------------------------------|
| invalidatedNotifier | When emits the cache is invalidated. If CacheKey is passed then only that cache otherwise all related cache. | undefined | true (OR use invalidatedNotifierKey) |
| invalidatedNotifierKey | Global key identifying invalidatedNotifier. | undefined | true (OR use invalidatedNotifier) |
| cacheKeyGenerator | Generates the cache key for the updated notifier | undefined | false |
### Global configuration
| Property | Description | Default | Required |
|-------------------|------------------------------------------------|-----------------------------|----------|
| cacheDataStorage | A storage where the cache data is stored | Store cached values locally | false |
| maxAgeMS | Max age of cache in milliseconds | 60000 (1 minute) | false |
| timestampProvider | Provides current timestamp, useful for testing | | false |
## Inspiration
This project is inspired by [ts-cacheable](https://github.com/angelnikolov/ts-cacheable)