|
| 1 | +# 🗑️ cachecan |
| 2 | + |
| 3 | +[![npm version][npm-version-src]][npm-version-href] |
| 4 | +[![Codecov][codecov-src]][codecov-href] |
| 5 | + |
| 6 | +Like a trashcan, but for your cache. |
| 7 | + |
| 8 | +Wrap functions to cache results. Supports [_any storage_](#storage), such as Redis, MongoDB, Cloudflare KV, localStorage, and even your file system. |
| 9 | + |
| 10 | +```bash |
| 11 | +npm i cachecan |
| 12 | +# or |
| 13 | +pnpm i cachecan |
| 14 | +``` |
| 15 | + |
| 16 | +```tsx |
| 17 | +import { createCache } from 'cachecan' |
| 18 | +const [cache] = createCache({ |
| 19 | + storage, |
| 20 | +}) |
| 21 | + |
| 22 | +// Usage |
| 23 | +const cacheGetData = cache(getData, { key: "data" }) |
| 24 | +const data = await cacheGetData() |
| 25 | + |
| 26 | +const cacheGetData = cache( |
| 27 | + async () => { ... }, |
| 28 | + { key: "data", maxAge: 60, } |
| 29 | +) |
| 30 | +const data = await cacheGetOtherData() |
| 31 | +``` |
| 32 | + |
| 33 | +## Batteries not included |
| 34 | + |
| 35 | +`cachecan` is a [tiny](https://bundlephobia.com/package/cachecan) cache wrapper. It does not actually include a cache. |
| 36 | + |
| 37 | +### The batteries included setup |
| 38 | + |
| 39 | +If you want to get started quickly. You should read on to learn how to customize your cache first. |
| 40 | + |
| 41 | +```bash |
| 42 | +npm i cachecan seroval unstorage |
| 43 | +# or |
| 44 | +pnpm i cachecan seroval unstorage |
| 45 | +``` |
| 46 | + |
| 47 | +```tsx |
| 48 | +import { createCache } from "cachecan"; |
| 49 | +import { deserialize, serialize } from "seroval"; |
| 50 | +import { createStorage } from "unstorage"; |
| 51 | +import fsDriver from "unstorage/drivers/fs"; |
| 52 | + |
| 53 | +const storage = createStorage({ |
| 54 | + driver: fsDriver({ base: "./tmp" }), |
| 55 | +}); |
| 56 | + |
| 57 | +const [cache] = createCache({ |
| 58 | + storage, |
| 59 | + serialize, |
| 60 | + deserialize, |
| 61 | + defaults: { |
| 62 | + maxAge: 60, |
| 63 | + }, |
| 64 | +}); |
| 65 | +``` |
| 66 | + |
| 67 | +### Storage |
| 68 | + |
| 69 | +The cache storage is powered by [`unstorage`](https://unstorage.unjs.io), which allows you to use any of their drivers. |
| 70 | + |
| 71 | +File system storage is useful for dev environments, easily transition to a hosted storage when moving to production. |
| 72 | + |
| 73 | +```tsx |
| 74 | +import { Storage, createStorage } from "unstorage"; |
| 75 | +import cloudflareKVHTTPDriver from "unstorage/drivers/cloudflare-kv-http"; |
| 76 | +import fsDriver from "unstorage/drivers/fs"; |
| 77 | + |
| 78 | +const isProduction = process.env.NODE_ENV === "production"; |
| 79 | + |
| 80 | +const storage = createStorage({ |
| 81 | + driver: isProduction |
| 82 | + ? cloudflareKVHTTPDriver({ |
| 83 | + accountId: "my-account-id", |
| 84 | + namespaceId: "my-kv-namespace-id", |
| 85 | + apiToken: "supersecret-api-token", |
| 86 | + }) |
| 87 | + : fsDriver({ base: "./tmp" }), |
| 88 | +}); |
| 89 | +``` |
| 90 | + |
| 91 | +### Serializers |
| 92 | + |
| 93 | +To keep library small it does not ship with any serializers, defaulting to `JSON.stringify` and `JSON.parse`. This is not sufficient for all use cases, so you can provide your own serializer. |
| 94 | + |
| 95 | +I use [`seroval`](https://github.com/lxsmnsyc/seroval), here's a [list of more serializers](https://github.com/lxsmnsyc/seroval/tree/main/benchmark#libraries). |
| 96 | + |
| 97 | +```tsx |
| 98 | +import { deserialize, serialize } from "seroval"; |
| 99 | + |
| 100 | +const [cache] = createCache({ |
| 101 | + storage, |
| 102 | + serialize, |
| 103 | + deserialize, |
| 104 | +}); |
| 105 | +``` |
| 106 | + |
| 107 | +## Usage |
| 108 | + |
| 109 | +### Purging the cache |
| 110 | + |
| 111 | +The created cache has a `purge` method that can be used to clear the cache storage. |
| 112 | + |
| 113 | +```tsx |
| 114 | +import { createCache } from "cachecan"; |
| 115 | + |
| 116 | +const [cache, { purge }] = createCache({ |
| 117 | + storage, |
| 118 | +}); |
| 119 | +await purge("users"); |
| 120 | +await purge(["user", 1]); |
| 121 | +// Purge all cached items |
| 122 | +await purge(); |
| 123 | +``` |
| 124 | + |
| 125 | +### Populating the cache |
| 126 | + |
| 127 | +The created cache has a `store` method that can be used to populate the cache storage. Useful to hydrate the cache with pre-existing data. |
| 128 | + |
| 129 | +```tsx |
| 130 | +const users = [ |
| 131 | + { |
| 132 | + hello: "populated", |
| 133 | + }, |
| 134 | +]; |
| 135 | + |
| 136 | +const [cache, { store }] = createCache(); |
| 137 | + |
| 138 | +await store( |
| 139 | + // Key |
| 140 | + "users", |
| 141 | + // Value |
| 142 | + users, |
| 143 | + { |
| 144 | + // Optional, override cache default maxAge |
| 145 | + // 60 seconds |
| 146 | + maxAge: 60, |
| 147 | + }, |
| 148 | +); |
| 149 | +``` |
| 150 | + |
| 151 | +## License |
| 152 | + |
| 153 | +Published under [MIT License](./LICENSE). |
| 154 | + |
| 155 | +<!-- Badges --> |
| 156 | + |
| 157 | +[npm-version-src]: https://img.shields.io/npm/v/cachecan?style=flat&colorA=18181B&colorB=F0DB4F |
| 158 | +[npm-version-href]: https://npmjs.com/package/cachecan |
| 159 | +[codecov-src]: https://img.shields.io/codecov/c/gh/ryoid/cachecan/main?style=flat&colorA=18181B&colorB=F0DB4F |
| 160 | +[codecov-href]: https://codecov.io/gh/ryoid/cachecan |
0 commit comments