feat: support zod schemas on checkValue

- also attach cause on thrown validation errors
- deprecate CheckFreshValueErrorEvent in favor of CheckFreshValueErrorObjEvent
- deprecate CheckCachedValueErrorEvent in favor of CheckCachedValueErrorObjEvent
- support on-the-fly migrations where the cached value will not be updated
  with `migrate(newValue, false)`

fix #44

Author: Xiphe

package-lock.json

@@ -47,9 +47,10 @@
     "esbuild": "0.17.15",
     "jest": "29.5.0",
     "lru-cache": "8.0.4",
-    "redis4": "npm:[email protected]",
     "redis-mock": "0.56.3",
+    "redis4": "npm:[email protected]",
     "ts-jest": "29.1.0",
-    "typescript": "5.0.3"
+    "typescript": "5.0.3",
+    "zod": "3.21.4"
   }
 }

package.json

@@ -318,6 +318,31 @@ function getPi() {
 
 > ℹ️ `checkValue` is also invoked with the return value of `getFreshValue`
 
+### Type-safety with [zod](https://github.com/colinhacks/zod)
+
+We can also use zod schemas to ensure correct types
+
+```ts
+import type { CacheEntry } from 'cachified';
+import LRUCache from 'lru-cache';
+import { cachified } from 'cachified';
+import z from 'zod';
+
+const lru = new LRUCache<string, CacheEntry<string>>({ max: 1000 });
+const userId = 1;
+
+const user = await cachified({
+  key: `user-${userId}`,
+  cache: lru,
+  checkValue: z.object({
+    email: z.string()
+  }),
+  getFreshValue() {
+    return getUserFromApi(userId)
+  }
+});
+```
+
 ### Migrating Values
 
 When the format of cached values is changed during the apps lifetime they can

readme.md

@@ -1,5 +1,6 @@
 import LRUCache from 'lru-cache';
 import { createClient as createRedis3Client } from 'redis-mock';
+import z from 'zod';
 import {
   cachified,
   CachifiedOptions,
@@ -212,9 +213,12 @@ describe('cachified', () => {
       },
     });
 
-    await expect(value).rejects.toMatchInlineSnapshot(
-      `[Error: check failed for fresh value of test]`,
+    await expect(value).rejects.toThrowErrorMatchingInlineSnapshot(
+      `"check failed for fresh value of test"`,
     );
+    await expect(
+      value.catch((err) => err.cause),
+    ).resolves.toMatchInlineSnapshot(`"👮"`);
     expect(report(reporter.mock.calls)).toMatchInlineSnapshot(`
     "1. init
        {key: 'test', metadata: {createdTime: 0, swr: 0, ttl: null}}
@@ -224,7 +228,9 @@ describe('cachified', () => {
     5. getFreshValueStart
     6. getFreshValueSuccess
        {value: 'ONE'}
-    7. checkFreshValueError
+    7. checkFreshValueErrorObj
+       {reason: '👮'}
+    8. checkFreshValueError
        {reason: '👮'}"
     `);
 
@@ -240,8 +246,8 @@ describe('cachified', () => {
         return 'ONE';
       },
     });
-    await expect(value2).rejects.toMatchInlineSnapshot(
-      `[Error: check failed for fresh value of test]`,
+    await expect(value2).rejects.toThrowErrorMatchingInlineSnapshot(
+      `"check failed for fresh value of test"`,
     );
     expect(report(reporter2.mock.calls)).toMatchInlineSnapshot(`
     "1. init
@@ -252,11 +258,77 @@ describe('cachified', () => {
     5. getFreshValueStart
     6. getFreshValueSuccess
        {value: 'ONE'}
-    7. checkFreshValueError
+    7. checkFreshValueErrorObj
+       {reason: 'unknown'}
+    8. checkFreshValueError
        {reason: 'unknown'}"
     `);
   });
 
+  it('supports zod validation with checkValue', async () => {
+    const cache = new Map<string, CacheEntry>();
+
+    const value = await cachified({
+      cache,
+      key: 'test',
+      checkValue: z.string(),
+      getFreshValue() {
+        return 'ONE';
+      },
+    });
+
+    expect(value).toBe('ONE');
+
+    const value2 = cachified({
+      cache,
+      key: 'test-2',
+      checkValue: z.string(),
+      getFreshValue() {
+        /* pretend API returns an unexpected value */
+        return 1 as unknown as string;
+      },
+    });
+
+    await expect(value2).rejects.toThrowErrorMatchingInlineSnapshot(
+      `"check failed for fresh value of test-2"`,
+    );
+    await expect(value2.catch((err) => err.cause)).resolves
+      .toMatchInlineSnapshot(`
+      [ZodError: [
+        {
+          "code": "invalid_type",
+          "expected": "string",
+          "received": "number",
+          "path": [],
+          "message": "Expected string, received number"
+        }
+      ]]
+    `);
+  });
+
+  /* I don't think this is a good idea, but it's possible */
+  it('supports zod transforms', async () => {
+    const cache = new Map<string, CacheEntry>();
+
+    const getValue = () =>
+      cachified({
+        cache,
+        key: 'test',
+        checkValue: z.string().transform((s) => s.toUpperCase()),
+        getFreshValue() {
+          return 'one';
+        },
+      });
+
+    expect(await getValue()).toBe('ONE');
+
+    /* Stores original value in cache */
+    expect(cache.get('test')?.value).toBe('one');
+
+    /* Gets transformed value from cache */
+    expect(await getValue()).toBe('ONE');
+  });
+
   it('supports migrating cached values', async () => {
     const cache = new Map<string, CacheEntry>();
     const reporter = createReporter();
@@ -308,8 +380,8 @@ describe('cachified', () => {
       },
     });
 
-    await expect(value).rejects.toMatchInlineSnapshot(
-      `[Error: check failed for fresh value of weather]`,
+    await expect(value).rejects.toThrowErrorMatchingInlineSnapshot(
+      `"check failed for fresh value of weather"`,
     );
     expect(report(reporter.mock.calls)).toMatchInlineSnapshot(`
 "1. init
@@ -320,7 +392,9 @@ describe('cachified', () => {
 5. getFreshValueStart
 6. getFreshValueSuccess
    {value: '☁️'}
-7. checkFreshValueError
+7. checkFreshValueErrorObj
+   {reason: [Error: Bad Weather]}
+8. checkFreshValueError
    {reason: 'Bad Weather'}"
 `);
 
@@ -340,8 +414,8 @@ describe('cachified', () => {
       },
     });
 
-    await expect(value2).rejects.toMatchInlineSnapshot(
-      `[Error: check failed for fresh value of weather]`,
+    await expect(value2).rejects.toThrowErrorMatchingInlineSnapshot(
+      `"check failed for fresh value of weather"`,
     );
   });
 
@@ -1029,12 +1103,14 @@ describe('cachified', () => {
 2. getCachedValueStart
 3. getCachedValueRead
    {entry: {metadata: {createdTime: 0, swr: 0, ttl: null}, value: 'ONE'}}
-4. checkCachedValueError
+4. checkCachedValueErrorObj
    {reason: 'unknown'}
-5. getFreshValueStart
-6. getFreshValueSuccess
+5. checkCachedValueError
+   {reason: 'unknown'}
+6. getFreshValueStart
+7. getFreshValueSuccess
    {value: 'TWO'}
-7. writeFreshValueSuccess
+8. writeFreshValueSuccess
    {metadata: {createdTime: 0, swr: 0, ttl: null}, migrated: false, written: true}"
 `);
 
@@ -1058,12 +1134,14 @@ describe('cachified', () => {
 2. getCachedValueStart
 3. getCachedValueRead
    {entry: {metadata: {createdTime: 0, swr: 0, ttl: null}, value: 'ONE'}}
-4. checkCachedValueError
+4. checkCachedValueErrorObj
    {reason: '🖕'}
-5. getFreshValueStart
-6. getFreshValueSuccess
+5. checkCachedValueError
+   {reason: '🖕'}
+6. getFreshValueStart
+7. getFreshValueSuccess
    {value: 'TWO'}
-7. writeFreshValueSuccess
+8. writeFreshValueSuccess
    {metadata: {createdTime: 0, swr: 0, ttl: null}, migrated: false, written: true}"
 `);
   });

src/cachified.spec.ts

@@ -6,13 +6,16 @@ export async function checkValue<Value>(
   value: unknown,
 ): Promise<
   | { success: true; value: Value; migrated: boolean }
-  | { success: false; reason: string }
+  | { success: false; reason: unknown }
 > {
   try {
-    const checkResponse = await context.checkValue(value, (value) => ({
-      [MIGRATED]: true,
+    const checkResponse = await context.checkValue(
       value,
-    }));
+      (value, updateCache = true) => ({
+        [MIGRATED]: updateCache,
+        value,
+      }),
+    );
 
     if (typeof checkResponse === 'string') {
       return { success: false, reason: checkResponse };
@@ -26,10 +29,10 @@ export async function checkValue<Value>(
       };
     }
 
-    if (checkResponse && checkResponse[MIGRATED] === true) {
+    if (checkResponse && Object.hasOwn(checkResponse, MIGRATED)) {
       return {
         success: true,
-        migrated: true,
+        migrated: checkResponse[MIGRATED],
         value: checkResponse.value,
       };
     }
@@ -38,7 +41,7 @@ export async function checkValue<Value>(
   } catch (err) {
     return {
       success: false,
-      reason: err instanceof Error ? err.message : String(err),
+      reason: err,
     };
   }
 }

src/checkValue.ts

@@ -37,7 +37,7 @@ export type GetFreshValue<Value> = {
 };
 export const MIGRATED = Symbol();
 export type MigratedValue<Value> = {
-  [MIGRATED]: true;
+  [MIGRATED]: boolean;
   value: Value;
 };
 
@@ -51,6 +51,13 @@ export type ValueCheckResultInvalid = false | string;
 export type ValueCheckResult<Value> =
   | ValueCheckResultOk<Value>
   | ValueCheckResultInvalid;
+export type CheckValue<Value> = (
+  value: unknown,
+  migrate: (value: Value, updateCache?: boolean) => MigratedValue<Value>,
+) => ValueCheckResult<Value> | Promise<ValueCheckResult<Value>>;
+export interface Schema<Value> {
+  parseAsync(value: unknown): Promise<Value>;
+}
 
 export interface CachifiedOptions<Value> {
   /**
@@ -119,10 +126,7 @@ export interface CachifiedOptions<Value> {
    *
    * @type {function(): boolean | undefined | string | MigratedValue} Optional, default makes no value check
    */
-  checkValue?: (
-    value: unknown,
-    migrate: (value: Value) => MigratedValue<Value>,
-  ) => ValueCheckResult<Value> | Promise<ValueCheckResult<Value>>;
+  checkValue?: CheckValue<Value> | Schema<Value>;
   /**
    * Set true to not even try reading the currently cached value
    *
@@ -161,8 +165,9 @@ export interface CachifiedOptions<Value> {
 export interface Context<Value>
   extends Omit<
     Required<CachifiedOptions<Value>>,
-    'fallbackToCache' | 'reporter'
+    'fallbackToCache' | 'reporter' | 'checkValue'
   > {
+  checkValue: CheckValue<Value>;
   report: Reporter<Value>;
   fallbackToCache: number;
   metadata: CacheMetadata;
@@ -171,12 +176,21 @@ export interface Context<Value>
 export function createContext<Value>({
   fallbackToCache,
   reporter,
+  checkValue,
   ...options
 }: CachifiedOptions<Value>): Context<Value> {
   const ttl = options.ttl ?? Infinity;
   const staleWhileRevalidate = options.staleWhileRevalidate ?? 0;
+  const checkValueCompat: CheckValue<Value> =
+    typeof checkValue === 'function'
+      ? checkValue
+      : typeof checkValue === 'object'
+      ? (value, migrate) =>
+          checkValue.parseAsync(value).then((v) => migrate(v, false))
+      : () => true;
+
   const contextWithoutReport = {
-    checkValue: () => true,
+    checkValue: checkValueCompat,
     ttl,
     staleWhileRevalidate,
     fallbackToCache: