Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/himmlisch-studios/alpinejs-cache
Persist and expire data easily with Alpine JS
https://github.com/himmlisch-studios/alpinejs-cache
alpine-js alpinejs alpinejs-directive alpinejs-plugin cache esmodules localstorage ttl-cache zero-dependency
Last synced: about 2 months ago
JSON representation
Persist and expire data easily with Alpine JS
- Host: GitHub
- URL: https://github.com/himmlisch-studios/alpinejs-cache
- Owner: Himmlisch-Studios
- License: mit
- Created: 2024-12-05T04:47:01.000Z (2 months ago)
- Default Branch: master
- Last Pushed: 2024-12-05T09:20:24.000Z (2 months ago)
- Last Synced: 2024-12-05T09:29:13.183Z (2 months ago)
- Topics: alpine-js, alpinejs, alpinejs-directive, alpinejs-plugin, cache, esmodules, localstorage, ttl-cache, zero-dependency
- Language: JavaScript
- Homepage:
- Size: 0 Bytes
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Alpine JS Cache
Sometimes you want to _persist_ data, but not _until the end of times_...
With **Alpine Cache**, you can easily persist the state across page loads until an expiration date.
Specially useful to remember temporary UI state, to cache API calls, to schedule recurring notifications, etc.
You can even use it inside Alpine context and outside of it, without losing reactivity!
## Installation
### From a script tag
You can import Alpine Cache through a CDN like:
```html
```
### As a module
If you're using a web bundler, you can install Alpine Cache via NPM:
```
npm i alpinejs-cache -D
```
Then import it and register the plugin:
```js
import Alpine from 'alpinejs'
import cache from 'alpinejs-cache'
Alpine.plugin(cache)
window.Alpine = Alpine
Alpine.start()
```
## Example
You can find an examples on the `examples/` directory of this repository.
## Usage
Cache was inspired by [Persist](https://alpinejs.dev/plugins/persist), and so, they share the same caveats and style of configuration.
### $cache
The primary API for using this plugin is the magic `$cache` method.
```html
Increment
```
You can set a default value, and an optional custom key which will be used to save the data with the `.as` modifier.
Unlike `$persist`, you can set the expiration time of the value, in seconds, with the `.for` modifier. Each time the value gets changed the cache will be revalidated by `.for` seconds (60 by default). If the cache gets invalidated the default value is set again on load.
An `.until` modifier can be used instead of `.for`, to put a timestamp instead of the amount of seconds.
### Custom Storage Driver
Alpine Cache uses the [localStorage Browser API](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) by default to store all data.
You can change the storage driver for a single record with the `.using` modifer.
```html
Increment
```
You can also change the default storage driver globally via:
```js
Alpine.cache.defaultDriver = MyCustomStorageDriver;
```
To create a custom driver, you must implement the following contract:
```ts
interface CacheStorageDriver {
setItem: (key: string, record: CacheRecord) => void,
getItem: (key: string) => ?CacheRecord
}
```
The way Alpine Cache works, is with simple `CacheRecord` objects that wraps your data and adds a timestamp to it:
```ts
type CacheRecord = {
data: any,
expires_at: number
}
```
You're responsable to serialize and deserialize this construct on the `setItem` and `getItem` methods.
### Using outside Alpine context
You can `get`, `set` and manually `invalidate` data, outside the Alpine context while still maintaining the reactivity of the Alpine components that are using `$cache`.
`Alpine.cache` is an object with the following signature:
```ts
type cacheUtils = {
defaultDriver: CacheStorageDriver,
invalidate: (key: string, storage: CacheStorageDriver?) => void,
set: (key: string, data: any, time: number, storage: CacheStorageDriver?) => void,
get: (key: string, storage: CacheStorageDriver?) => any
}
```
`set` and `get` works as you expect they would. `invalidate` is a shorthand to `set` the value to `undefined` which Alpine Cache detects as an expired record. The `storage` parameter is the equivalent to the `.using` modifier, to override the default driver.
### Using $cache with Alpine.data
As it happens with `$persist`, if you want to use `$cache` within `Alpine.data`, you need to be sure to use a standard function instead of an arrow function.
```js
Alpine.data('productsIndex', function () {
return {
fetchData: this.$cache(null).until(Date.now() + 1000 * 5),
init(){
if(!this.fetchData){
this.$nextTick(async () => {
this.fetchData = await fetch(/*...*/).then((v) => v.json());
})
}
}
}
})
```
A caveat not explained in the docs. The values from `$cache` (and `$persist`), are **read-only** on the first tick.
No data will be saved if you try to set the properties on `init()`. If this is your case, wrap the setter in a `$nextTick` callback.
## Stats
