Skip to content

Commit

Permalink
fix: prep for initial release on @epic-web/cachified
Browse files Browse the repository at this point in the history
  • Loading branch information
@kentcdodds
kentcdodds committed Nov 28, 2023
1 parent e4768fa commit 3c0c69c
Show file tree
Hide file tree
Showing 2 changed files with 97 additions and 30 deletions.
11 changes: 7 additions & 4 deletions package.json
View file
Original file line number Diff line number Diff line change
@@ -1,10 +1,13 @@
{
"name": "cachified",
"name": "@epic-web/cachified",
"version": "0.0.0-development",
"description": "neat wrapper for various caches",
"main": "dist/index.cjs",
"module": "dist/index.mjs",
"types": "dist/src/index.d.ts",
"publishConfig": {
"access": "public"
},
"exports": {
".": {
"require": "./dist/index.cjs",
Expand All @@ -24,7 +27,7 @@
},
"repository": {
"type": "git",
"url": "https://github.com/Xiphe/cachified.git"
"url": "https://github.com/epicweb-dev/cachified.git"
},
"keywords": [
"cache",
Expand All @@ -39,9 +42,9 @@
"author": "Hannes Diercks <node@xiphe.net> (https://xiphe.net/)",
"license": "MIT",
"bugs": {
"url": "https://github.com/Xiphe/cachified/issues"
"url": "https://github.com/epicweb-dev/cachified/issues"
},
"homepage": "https://github.com/Xiphe/cachified#readme",
"homepage": "https://github.com/epicweb-dev/cachified#readme",
"devDependencies": {
"@types/jest": "29.5.10",
"@types/node": "20.10.0",
Expand Down
116 changes: 90 additions & 26 deletions readme.md
View file
Original file line number Diff line number Diff line change
@@ -1,11 +1,43 @@
# cachified
<div>
<h1 align="center"><a href="https://npm.im/@epic-web/cachified">@epic-web/cachified</a></h1>
<strong>
A simple API to make your app faster.
</strong>
<p>
Cachified allows you to cache values with support for time-to-live (ttl),
stale-while-revalidate (swr), cache value validation, batching, and
type-safety.
</p>
</div>

[![🚀 Publish](https://github.com/Xiphe/cachified/actions/workflows/release.yml/badge.svg)](https://github.com/Xiphe/cachified/actions/workflows/release.yml)
[![codecov](https://codecov.io/gh/Xiphe/cachified/branch/main/graph/badge.svg?token=GDN0OD10IO)](https://codecov.io/gh/Xiphe/cachified)
[![no dependencies](https://img.shields.io/badge/dependencies-none-brightgreen)](https://github.com/Xiphe/cachified/search?q=dependencies&type=code)
[![npm](https://img.shields.io/npm/v/cachified)](https://www.npmjs.com/package/cachified)
[![semantic-release: angular](https://img.shields.io/badge/semantic--release-angular-e10079?logo=semantic-release)](https://github.com/semantic-release/semantic-release)
[![Love and Peace](http://love-and-peace.github.io/love-and-peace/badges/base/v1.0.svg)](https://github.com/love-and-peace/love-and-peace/blob/master/versions/base/v1.0/en.md)
```
npm install @epic-web/cachified
```

<div align="center">
<a
alt="Epic Web logo"
href="https://www.epicweb.dev"
>
<img
width="300px"
src="https://github-production-user-asset-6210df.s3.amazonaws.com/1500684/257881576-fd66040b-679f-4f25-b0d0-ab886a14909a.png"
/>
</a>
</div>

<hr />

<!-- prettier-ignore-start -->
[![Build Status][build-badge]][build]
[![MIT License][license-badge]][license]
[![Code of Conduct][coc-badge]][coc]
<!-- prettier-ignore-end -->

Watch the talk ["Caching for Cash 🤑"](https://www.epicweb.dev/talks/caching-for-cash)
on [EpicWeb.dev](https://www.epicweb.dev):

[![Kent smiling with the cachified README on npm behind him](https://github-production-user-asset-6210df.s3.amazonaws.com/1500684/286321796-a280783c-9c99-46fe-abbb-85ac3dc4fd43.png)](https://www.epicweb.dev/talks/caching-for-cash)

#### 🧙 One API to cache them all

Expand All @@ -16,16 +48,17 @@ wrap virtually everything that can store by key to act as cache with ttl/max-age
## Install

```sh
npm install cachified
# yarn add cachified
npm install @epic-web/cachified
# yarn add @epic-web/cachified
```

## Usage

<!-- usage-intro -->

```ts
import { LRUCache } from 'lru-cache';
import { cachified, CacheEntry } from 'cachified';
import { cachified, CacheEntry } from '@epic-web/cachified';

/* lru cache is not part of this package but a simple non-persistent cache */
const lru = new LRUCache<string, CacheEntry>({ max: 1000 });
Expand Down Expand Up @@ -70,6 +103,7 @@ console.log(await getUserById(1));
## Options

<!-- ignore -->

```ts
interface CachifiedOptions<Value> {
/**
Expand Down Expand Up @@ -152,7 +186,7 @@ interface CachifiedOptions<Value> {
*
* A validator function receives two arguments:
* 1. the value
* 2. a migrate callback, see https://github.com/Xiphe/cachified#migrating-values
* 2. a migrate callback, see https://github.com/epicweb-dev/cachified#migrating-values
*
* Default: `undefined` - no validation
*/
Expand Down Expand Up @@ -203,9 +237,10 @@ the used caches cleanup outdated values themselves.
### Adapter for [lru-cache](https://www.npmjs.com/package/lru-cache)

<!-- lru-adapter -->

```ts
import { LRUCache } from 'lru-cache';
import { cachified, lruCacheAdapter, CacheEntry } from 'cachified';
import { cachified, lruCacheAdapter, CacheEntry } from '@epic-web/cachified';

const lru = new LRUCache<string, CacheEntry>({ max: 1000 });
const cache = lruCacheAdapter(lru);
Expand All @@ -222,9 +257,10 @@ await cachified({
### Adapter for [redis](https://www.npmjs.com/package/redis)

<!-- redis-adapter -->

```ts
import { createClient } from 'redis';
import { cachified, redisCacheAdapter } from 'cachified';
import { cachified, redisCacheAdapter } from '@epic-web/cachified';

const redis = createClient({
/* ...opts */
Expand All @@ -243,9 +279,10 @@ await cachified({
### Adapter for [redis@3](https://www.npmjs.com/package/redis/v/3.1.2)

<!-- redis-3-adapter -->

```ts
import { createClient } from 'redis';
import { cachified, redis3CacheAdapter } from 'cachified';
import { cachified, redis3CacheAdapter } from '@epic-web/cachified';

const redis = createClient({
/* ...opts */
Expand All @@ -270,8 +307,9 @@ it's ttl is exceeded while the cache is updated in the background for the next
call.

<!-- stale-while-revalidate -->

```ts
import { cachified } from 'cachified';
import { cachified } from '@epic-web/cachified';

const cache = new Map();

Expand Down Expand Up @@ -319,8 +357,9 @@ console.log(await getUserById(1));
We can use `forceFresh` to get a fresh value regardless of the values ttl or stale while validate

<!-- force-fresh -->

```ts
import { cachified } from 'cachified';
import { cachified } from '@epic-web/cachified';

const cache = new Map();

Expand Down Expand Up @@ -358,8 +397,9 @@ For example other parties could also write to the cache or code is changed while
stays the same.

<!-- type-safety -->

```ts
import { cachified, createCacheEntry } from 'cachified';
import { cachified, createCacheEntry } from '@epic-web/cachified';

const cache = new Map();

Expand Down Expand Up @@ -419,8 +459,9 @@ console.log(await getUserById(1));
We can also use zod schemas to ensure correct types

<!-- type-safety-zod -->

```ts
import { cachified, createCacheEntry } from 'cachified';
import { cachified, createCacheEntry } from '@epic-web/cachified';
import z from 'zod';

const cache = new Map();
Expand Down Expand Up @@ -460,8 +501,13 @@ During normal app lifecycle there usually is no need for this but for
maintenance and testing these helpers might come handy.

<!-- manual-cache-interactions -->

```ts
import { createCacheEntry, assertCacheEntry, cachified } from 'cachified';
import {
createCacheEntry,
assertCacheEntry,
cachified,
} from '@epic-web/cachified';

const cache = new Map();

Expand Down Expand Up @@ -502,8 +548,9 @@ When the format of cached values is changed during the apps lifetime they can
be migrated on read like this:

<!-- migrating-values -->

```ts
import { cachified, createCacheEntry } from 'cachified';
import { cachified, createCacheEntry } from '@epic-web/cachified';

const cache = new Map();

Expand Down Expand Up @@ -545,8 +592,9 @@ to update all cached values at once and instead allows to get them updated over
More details: [Soft vs. hard purge](https://developer.fastly.com/reference/api/purging/#soft-vs-hard-purge)

<!-- soft-purge -->

```ts
import { cachified, softPurge } from 'cachified';
import { cachified, softPurge } from '@epic-web/cachified';

const cache = new Map();

Expand Down Expand Up @@ -601,13 +649,14 @@ console.log(await getUserById(1));
### Fine-tuning cache metadata based on fresh values

There are scenarios where we want to change the cache time based on the fresh
value (ref [#25](https://github.com/Xiphe/cachified/issues/25)).
value (ref [#25](https://github.com/epicweb-dev/cachified/issues/25)).
For example when an API might either provide our data or `null` and in case we
get an empty result we want to retry the API much faster.

<!-- metadata-fine-tuning -->

```ts
import { cachified } from 'cachified';
import { cachified } from '@epic-web/cachified';

const cache = new Map();

Expand Down Expand Up @@ -638,8 +687,9 @@ In case multiple values can be requested in a batch action, but it's not
clear which values are currently in cache we can use the `createBatch` helper

<!-- batch-operations -->

```ts
import { cachified, createBatch } from 'cachified';
import { cachified, createBatch } from '@epic-web/cachified';

const cache = new Map();

Expand Down Expand Up @@ -693,8 +743,9 @@ A reporter might be passed to cachified to log caching events, we ship a reporte
resembling the logging from [Kents implementation](https://github.com/kentcdodds/kentcdodds.com/blob/3efd0d3a07974ece0ee64d665f5e2159a97585df/app/utils/cache.server.ts)

<!-- verbose-reporter -->

```ts
import { cachified, verboseReporter } from 'cachified';
import { cachified, verboseReporter } from '@epic-web/cachified';

const cache = new Map();

Expand All @@ -712,4 +763,17 @@ await cachified({
});
```

please refer to [the implementation of `verboseReporter`](https://github.com/Xiphe/cachified/blob/main/src/reporter.ts#L125) when you want to implement a custom reporter.
please refer to [the implementation of `verboseReporter`](https://github.com/epicweb-dev/cachified/blob/main/src/reporter.ts#L125) when you want to implement a custom reporter.

## License

MIT

<!-- prettier-ignore-start -->
[build-badge]: https://img.shields.io/github/actions/workflow/status/epicweb-dev/cachified/release.yml?branch=main&logo=github&style=flat-square
[build]: https://github.com/epicweb-dev/cachified/actions?query=workflow%3Arelease
[license-badge]: https://img.shields.io/badge/license-MIT%20License-blue.svg?style=flat-square
[license]: https://github.com/epicweb-dev/cachified/blob/main/LICENSE
[coc-badge]: https://img.shields.io/badge/code%20of-conduct-ff69b4.svg?style=flat-square
[coc]: https://kentcdodds.com/conduct
<!-- prettier-ignore-end -->

0 comments on commit 3c0c69c

Please sign in to comment.