[koa-cash] add typings for koa-cash v4.0 (#45930)

* [koa-cash] add typings for koa-cash v4.0

* [koa-cash] expose Options interface

Co-authored-by: Jakob Goebel <jakob.goebel@avenga.com>

types/koa-cash/index.d.ts

@@ -0,0 +1,83 @@
+// Type definitions for koa-cash 4.0
+// Project: https://github.com/koajs/cash
+// Definitions by: Jakob Goebel <https://github.com/jagoe>
+// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
+
+import * as Koa from 'koa';
+declare module 'koa' {
+    interface BaseContext {
+        /**
+         * This is how you enable a route to be cached. If you don't call await ctx.cashed(),
+         * then this route will not be cached nor will it attempt to serve the request from the cache.
+         *
+         * Notes:
+         * * Only `GET` and `HEAD` requests are cached.
+         * * Only 200 responses are cached. Don't set 304 status codes on these routes - this
+         *   middleware will handle it for you.
+         * * The underlying store should be able to handle Date objects as well as Buffer objects.
+         *   Otherwise, you may have to serialize/deserialize yourself.
+         * @param maxAge The max age passed to `get()`.
+         */
+        cashed(maxAge?: number): Promise<boolean>;
+    }
+}
+
+declare function koaCash(opts?: koaCash.Options): Koa.Middleware;
+
+declare namespace koaCash {
+    interface Options {
+        /**
+         * Default max age (in milliseconds) for the cache if not set via `await ctx.cashed(maxAge)`.
+         */
+        maxAge?: number;
+
+        /**
+         * Minimum byte size to compress response bodies. Default 1kb.
+         * @default 1000
+         */
+        threshold?: number;
+
+        /**
+         * If a truthy value is passed, then compression will be enabled.
+         * @default false
+         */
+        compression?: boolean;
+
+        /**
+         * If a truthy value is passed, then X-Cached-Response header will be set as HIT when response
+         * is served from the cache.
+         * @default false
+         */
+        setCachedHeader?: boolean;
+
+        /**
+         * A hashing function. By default, it caches based on the URL.
+         * @default
+         * ```
+         * function hash(ctx) {
+         *   return ctx.response.url; // same as ctx.url
+         * }
+         * ```
+         */
+        hash?(ctx: Koa.Context): string;
+
+        /**
+         * Get a value from a store. Must return a Promise, which returns the cache's value, if any.
+         * @param key Cache key
+         * @param maxAge Max age (in milliseconds) for the cache
+         */
+        get(key: string, maxAge: number): Promise<unknown | undefined>;
+
+        /**
+         * Set a value to a store. Must return a Promise.\
+         * Note: `maxAge` is set by `.cash = { maxAge }`. If it's not set, then `maxAge` will be `0`,
+         * which you should then ignore.
+         * @param key Cache key
+         * @param value Cached value
+         * @param maxAge Max age (in milliseconds) for the cache
+         */
+        set(key: string, value: unknown, maxAge: number): Promise<void>;
+    }
+}
+
+export = koaCash;

types/koa-cash/koa-cash-tests.ts

@@ -0,0 +1,15 @@
+import koaCash = require('koa-cash');
+import Koa = require('koa');
+
+const app = new Koa();
+app.use(koaCash());
+
+app.use(async ctx => {
+    // this response is already cashed if `true` is returned,
+    // so this middleware will automatically serve this response from cache
+    if (await ctx.cashed()) return;
+
+    // set the response body here,
+    // and the upstream middleware will automatically cache it
+    ctx.body = 'hello world!';
+});

types/koa-cash/tsconfig.json

@@ -0,0 +1,24 @@
+{
+    "compilerOptions": {
+        "module": "commonjs",
+        "lib": [
+            "es6"
+        ],
+        "noImplicitAny": true,
+        "noImplicitThis": true,
+        "strictFunctionTypes": true,
+        "strictNullChecks": true,
+        "baseUrl": "../",
+        "target": "es6",
+        "typeRoots": [
+            "../"
+        ],
+        "types": [],
+        "noEmit": true,
+        "forceConsistentCasingInFileNames": true
+    },
+    "files": [
+        "index.d.ts",
+        "koa-cash-tests.ts"
+    ]
+}

types/koa-cash/tslint.json

@@ -0,0 +1 @@
+{ "extends": "dtslint/dt.json" }