Merge pull request #32521 from BendingBender/http-cache-semantics

[http-cache-semantics] Add types

types/http-cache-semantics/http-cache-semantics-tests.ts

@@ -0,0 +1,19 @@
+const req = { url: 'https://foo.bar', method: 'GET', headers: { foo: 'bar' } };
+const res = { status: 200, headers: { foo: 'bar' } };
+
+import CachePolicy = require('http-cache-semantics');
+
+const policy = new CachePolicy(req, res);
+new CachePolicy(req, res, { shared: true });
+new CachePolicy(req, res, { cacheHeuristic: 0.1 });
+new CachePolicy(req, res, { immutableMinTimeToLive: 24 * 3600 * 1000 });
+new CachePolicy(req, res, { ignoreCargoCult: false });
+new CachePolicy(req, res, { trustServerDate: true });
+
+policy.storable(); // $ExpectType boolean
+policy.satisfiesWithoutRevalidation(req); // $ExpectType boolean
+policy.responseHeaders(); // $ExpectType Headers
+policy.timeToLive(); // $ExpectType number
+CachePolicy.fromObject(policy.toObject()); // $ExpectType CachePolicy
+policy.revalidationHeaders(req); // $ExpectType Headers
+policy.revalidatedPolicy(req, res); // $ExpectType RevalidationPolicy

types/http-cache-semantics/index.d.ts

@@ -0,0 +1,170 @@
+// Type definitions for http-cache-semantics 4.0
+// Project: https://github.com/kornelski/http-cache-semantics#readme
+// Definitions by: BendingBender <https://github.com/BendingBender>
+// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
+
+export = CachePolicy;
+
+declare class CachePolicy {
+    constructor(req: CachePolicy.Request, res: CachePolicy.Response, options?: CachePolicy.Options);
+
+    /**
+     * Returns `true` if the response can be stored in a cache.
+     * If it's `false` then you MUST NOT store either the request or the response.
+     */
+    storable(): boolean;
+
+    /**
+     * This is the most important method. Use this method to check whether the cached response is still fresh
+     * in the context of the new request.
+     *
+     * If it returns `true`, then the given `request` matches the original response this cache policy has been
+     * created with, and the response can be reused without contacting the server. Note that the old response
+     * can't be returned without being updated, see `responseHeaders()`.
+     *
+     * If it returns `false`, then the response may not be matching at all (e.g. it's for a different URL or method),
+     * or may require to be refreshed first (see `revalidationHeaders()`).
+     */
+    satisfiesWithoutRevalidation(newRequest: CachePolicy.Request): boolean;
+
+    /**
+     * Returns updated, filtered set of response headers to return to clients receiving the cached response.
+     * This function is necessary, because proxies MUST always remove hop-by-hop headers (such as `TE` and `Connection`)
+     * and update response's `Age` to avoid doubling cache time.
+     *
+     * @example
+     * cachedResponse.headers = cachePolicy.responseHeaders(cachedResponse);
+     */
+    responseHeaders(): CachePolicy.Headers;
+
+    /**
+     * Returns approximate time in milliseconds until the response becomes stale (i.e. not fresh).
+     *
+     * After that time (when `timeToLive() <= 0`) the response might not be usable without revalidation. However,
+     * there are exceptions, e.g. a client can explicitly allow stale responses, so always check with
+     * `satisfiesWithoutRevalidation()`.
+     */
+    timeToLive(): number;
+
+    /**
+     * Chances are you'll want to store the `CachePolicy` object along with the cached response.
+     * `obj = policy.toObject()` gives a plain JSON-serializable object.
+     */
+    toObject(): CachePolicy.CachePolicyObject;
+
+    /**
+     * `policy = CachePolicy.fromObject(obj)` creates an instance from object created by `toObject()`.
+     */
+    static fromObject(obj: CachePolicy.CachePolicyObject): CachePolicy;
+
+    /**
+     * Returns updated, filtered set of request headers to send to the origin server to check if the cached
+     * response can be reused. These headers allow the origin server to return status 304 indicating the
+     * response is still fresh. All headers unrelated to caching are passed through as-is.
+     *
+     * Use this method when updating cache from the origin server.
+     *
+     * @example
+     * updateRequest.headers = cachePolicy.revalidationHeaders(updateRequest);
+     */
+    revalidationHeaders(newRequest: CachePolicy.Request): CachePolicy.Headers;
+
+    /**
+     * Use this method to update the cache after receiving a new response from the origin server.
+     */
+    revalidatedPolicy(
+        revalidationRequest: CachePolicy.Request,
+        revalidationResponse: CachePolicy.Response
+    ): CachePolicy.RevalidationPolicy;
+}
+
+declare namespace CachePolicy {
+    interface Request {
+        url?: string;
+        method?: string;
+        headers: Headers;
+    }
+
+    interface Response {
+        status?: number;
+        headers: Headers;
+    }
+
+    interface Options {
+        /**
+         * If `true`, then the response is evaluated from a perspective of a shared cache (i.e. `private` is not
+         * cacheable and `s-maxage` is respected). If `false`, then the response is evaluated from a perspective
+         * of a single-user cache (i.e. `private` is cacheable and `s-maxage` is ignored).
+         * `true` is recommended for HTTP clients.
+         * @default true
+         */
+        shared?: boolean;
+        /**
+         * A fraction of response's age that is used as a fallback cache duration. The default is 0.1 (10%),
+         * e.g. if a file hasn't been modified for 100 days, it'll be cached for 100*0.1 = 10 days.
+         * @default 0.1
+         */
+        cacheHeuristic?: number;
+        /**
+         * A number of milliseconds to assume as the default time to cache responses with `Cache-Control: immutable`.
+         * Note that [per RFC](https://httpwg.org/specs/rfc8246.html#the-immutable-cache-control-extension)
+         * these can become stale, so `max-age` still overrides the default.
+         * @default 24*3600*1000 (24h)
+         */
+        immutableMinTimeToLive?: number;
+        /**
+         * If `true`, common anti-cache directives will be completely ignored if the non-standard `pre-check`
+         * and `post-check` directives are present. These two useless directives are most commonly found
+         * in bad StackOverflow answers and PHP's "session limiter" defaults.
+         * @default false
+         */
+        ignoreCargoCult?: boolean;
+        /**
+         * If `false`, then server's `Date` header won't be used as the base for `max-age`. This is against the RFC,
+         * but it's useful if you want to cache responses with very short `max-age`, but your local clock
+         * is not exactly in sync with the server's.
+         * @default true
+         */
+        trustServerDate?: boolean;
+    }
+
+    interface CachePolicyObject {
+        v: number;
+        t: number;
+        sh: boolean;
+        ch: number;
+        imm: number;
+        st: number;
+        resh: Headers;
+        rescc: { [key: string]: string };
+        m: string;
+        u?: string;
+        h?: string;
+        a: boolean;
+        reqh: Headers | null;
+        reqcc: { [key: string]: string };
+    }
+
+    interface Headers {
+        [header: string]: string | string[] | undefined;
+    }
+
+    interface RevalidationPolicy {
+        /**
+         * A new `CachePolicy` with HTTP headers updated from `revalidationResponse`. You can always replace
+         * the old cached `CachePolicy` with the new one.
+         */
+        policy: CachePolicy;
+        /**
+         * Boolean indicating whether the response body has changed.
+         *
+         * - If `false`, then a valid 304 Not Modified response has been received, and you can reuse the old
+         * cached response body.
+         * - If `true`, you should use new response's body (if present), or make another request to the origin
+         * server without any conditional headers (i.e. don't use `revalidationHeaders()` this time) to get
+         * the new resource.
+         */
+        modified: boolean;
+        matches: boolean;
+    }
+}

types/http-cache-semantics/tsconfig.json

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

types/http-cache-semantics/tslint.json

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