From 3d24a2c277bea6be8f14012a4af405f7a8212f90 Mon Sep 17 00:00:00 2001
From: Kengo Watanabe <121782456+goisaki@users.noreply.github.com>
Date: Sat, 18 May 2024 10:40:07 +0900
Subject: [PATCH] Cache Middleware (#2692)

---
 deno_dist/middleware/cache/index.ts | 25 +++++++++++++++++++++++++
 src/middleware/cache/index.ts       | 25 +++++++++++++++++++++++++
 2 files changed, 50 insertions(+)

diff --git a/deno_dist/middleware/cache/index.ts b/deno_dist/middleware/cache/index.ts
index 70dec2948..b46ee6f16 100644
--- a/deno_dist/middleware/cache/index.ts
+++ b/deno_dist/middleware/cache/index.ts
@@ -1,6 +1,31 @@
 import type { Context } from '../../context.ts'
 import type { MiddlewareHandler } from '../../types.ts'
 
+/**
+ * cache middleware for Hono.
+ *
+ * @see {@link https://hono.dev/middleware/builtin/cache}
+ *
+ * @param {Object} options - The options for the cache middleware.
+ * @param {string | Function} options.cacheName - The name of the cache. Can be used to store multiple caches with different identifiers.
+ * @param {boolean} [options.wait=false] - A boolean indicating if Hono should wait for the Promise of the `cache.put` function to resolve before continuing with the request. Required to be true for the Deno environment.
+ * @param {string} [options.cacheControl] - A string of directives for the `Cache-Control` header.
+ * @param {string | string[]} [options.vary] - Sets the `Vary` header in the response. If the original response header already contains a `Vary` header, the values are merged, removing any duplicates.
+ * @param {Function} [options.keyGenerator] - Generates keys for every request in the `cacheName` store. This can be used to cache data based on request parameters or context parameters.
+ * @returns {MiddlewareHandler} The middleware handler function.
+ * @throws {Error} If the `vary` option includes "*".
+ *
+ * @example
+ * ```ts
+ * app.get(
+ *   '*',
+ *   cache({
+ *     cacheName: 'my-app',
+ *     cacheControl: 'max-age=3600',
+ *   })
+ * )
+ * ```
+ */
 export const cache = (options: {
   cacheName: string | ((c: Context) => Promise<string> | string)
   wait?: boolean
diff --git a/src/middleware/cache/index.ts b/src/middleware/cache/index.ts
index 64779d920..9e6fc718e 100644
--- a/src/middleware/cache/index.ts
+++ b/src/middleware/cache/index.ts
@@ -1,6 +1,31 @@
 import type { Context } from '../../context'
 import type { MiddlewareHandler } from '../../types'
 
+/**
+ * cache middleware for Hono.
+ *
+ * @see {@link https://hono.dev/middleware/builtin/cache}
+ *
+ * @param {Object} options - The options for the cache middleware.
+ * @param {string | Function} options.cacheName - The name of the cache. Can be used to store multiple caches with different identifiers.
+ * @param {boolean} [options.wait=false] - A boolean indicating if Hono should wait for the Promise of the `cache.put` function to resolve before continuing with the request. Required to be true for the Deno environment.
+ * @param {string} [options.cacheControl] - A string of directives for the `Cache-Control` header.
+ * @param {string | string[]} [options.vary] - Sets the `Vary` header in the response. If the original response header already contains a `Vary` header, the values are merged, removing any duplicates.
+ * @param {Function} [options.keyGenerator] - Generates keys for every request in the `cacheName` store. This can be used to cache data based on request parameters or context parameters.
+ * @returns {MiddlewareHandler} The middleware handler function.
+ * @throws {Error} If the `vary` option includes "*".
+ *
+ * @example
+ * ```ts
+ * app.get(
+ *   '*',
+ *   cache({
+ *     cacheName: 'my-app',
+ *     cacheControl: 'max-age=3600',
+ *   })
+ * )
+ * ```
+ */
 export const cache = (options: {
   cacheName: string | ((c: Context) => Promise<string> | string)
   wait?: boolean