1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
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 | undefined;
method?: string | undefined;
headers: Headers;
}
interface Response {
status?: number | undefined;
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 | undefined;
/**
* 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 | undefined;
/**
* 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 | undefined;
/**
* 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 | undefined;
/**
* 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 | undefined;
}
interface CachePolicyObject {
v: number;
t: number;
sh: boolean;
ch: number;
imm: number;
st: number;
resh: Headers;
rescc: { [key: string]: string };
m: string;
u?: string | undefined;
h?: string | undefined;
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;
}
}
|
