@vltpkg/registry-client 0.0.0-2 → 0.0.0-4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +50 -53
  2. package/package.json +10 -10
package/README.md CHANGED
@@ -2,76 +2,73 @@
2
2
 
3
3
  # @vltpkg/registry-client
4
4
 
5
- This is a very light wrapper around undici, optimized for interfacing with an npm registry.
5
+ This is a very light wrapper around undici, optimized for interfacing
6
+ with an npm registry.
6
7
 
7
- **[Cache Unzipped](#cache-unzipped)**
8
- ·
9
- **[Integrity Options](#integrity-options)**
10
- ·
11
- **[Usage](#usage)**
8
+ **[Cache Unzipped](#cache-unzipped)** ·
9
+ **[Integrity Options](#integrity-options)** · **[Usage](#usage)**
12
10
 
13
11
  ## Overview
14
12
 
15
- Any response with `immutable` in the `cache-control` header, or with a `content-type` of `application/octet-stream` or a path ending in `.tgz`, will be cached forever and never requested again as long as the cache survives.
13
+ Any response with `immutable` in the `cache-control` header, or with a
14
+ `content-type` of `application/octet-stream` or a path ending in
15
+ `.tgz`, will be cached forever and never requested again as long as
16
+ the cache survives.
16
17
 
17
18
  If the request has a cached response:
18
19
 
19
- - Cached responses with `immutable` in the `cache-control`
20
- header will be returned from cache without a network request,
21
- no matter what.
22
- - Cached responses with a `content-type` of
23
- `application/octet-stream` will be returned from cache without
24
- a network request, no matter what, because tarballs are
25
- immutable.
20
+ - Cached responses with `immutable` in the `cache-control` header will
21
+ be returned from cache without a network request, no matter what.
22
+ - Cached responses with a `content-type` of `application/octet-stream`
23
+ will be returned from cache without a network request, no matter
24
+ what, because tarballs are immutable.
26
25
  - Cached responses with `max-age=<n>` or `s-max-age=<n>` will be
27
- served from cache without a network request if it's less than
28
- `<n>` seconds old.
26
+ served from cache without a network request if it's less than `<n>`
27
+ seconds old.
29
28
  - Otherwise, a network request to the registry will be made
30
- - if an `etag` is present in the cached response, it will be
31
- used as the `if-none-match` header.
32
- - If a `last-modified` header is in the response, that will
33
- be used as the `if-modified-since` request header.
34
- - If there is no `last-modified` header, then use the `mtime`
35
- of the cache file as the `if-modified-since` header.
29
+ - if an `etag` is present in the cached response, it will be used as
30
+ the `if-none-match` header.
31
+ - If a `last-modified` header is in the response, that will be used
32
+ as the `if-modified-since` request header.
33
+ - If there is no `last-modified` header, then use the `mtime` of the
34
+ cache file as the `if-modified-since` header.
36
35
 
37
36
  This is the extent of the cache control logic. It is not a
38
- full-featured spec-compliant caching HTTP client, because that is
39
- not needed for this use case. Every response will be cached, even
40
- if the registry headers don't technically allow it.
37
+ full-featured spec-compliant caching HTTP client, because that is not
38
+ needed for this use case. Every response will be cached, even if the
39
+ registry headers don't technically allow it.
41
40
 
42
41
  ## Cache Unzipped
43
42
 
44
- Client always sends `accept-encoding: gzip;q=1.0, *;q=0.5`
45
- header when making requests, to save time on the wire.
43
+ Client always sends `accept-encoding: gzip;q=1.0, *;q=0.5` header when
44
+ making requests, to save time on the wire.
46
45
 
47
- If response has `content-encoding: gzip`, then we swap out the
48
- body for the unzipped response body in the cache, as if it was
49
- not gzipped in the first place. This _must_ be done before
50
- returning the response, because you can't `JSON.parse()` a
51
- gzipped response anyway.
46
+ If response has `content-encoding: gzip`, then we swap out the body
47
+ for the unzipped response body in the cache, as if it was not gzipped
48
+ in the first place. This _must_ be done before returning the response,
49
+ because you can't `JSON.parse()` a gzipped response anyway.
52
50
 
53
- If the response is `content-type: application/octet-stream` and
54
- starts with the gzip header, then we return the raw body as we
55
- received it, but as a best-effort background job, unzip it and
56
- update the cache entry to be an unzipped response body. This is
57
- done in the `@vltpkg/cache-unzip` worker.
51
+ If the response is `content-type: application/octet-stream` and starts
52
+ with the gzip header, then we return the raw body as we received it,
53
+ but as a best-effort background job, unzip it and update the cache
54
+ entry to be an unzipped response body. This is done in the
55
+ `@vltpkg/cache-unzip` worker.
58
56
 
59
57
  So,
60
58
 
61
- - json responses will always be un-zipped, in the response and in
62
- the cache.
63
- - artifact responses _may_ be gzipped (and thus, have to be
64
- unzipped by the unpack operation), but will eventually be
65
- cached as unzipped tarballs.
59
+ - json responses will always be un-zipped, in the response and in the
60
+ cache.
61
+ - artifact responses _may_ be gzipped (and thus, have to be unzipped
62
+ by the unpack operation), but will eventually be cached as unzipped
63
+ tarballs.
66
64
 
67
- Thus, the `content-length` response header will _usually_ not
68
- match the actual byte length of the response body.
65
+ Thus, the `content-length` response header will _usually_ not match
66
+ the actual byte length of the response body.
69
67
 
70
68
  ## Integrity Options
71
69
 
72
- An `integrity` option may be specified in a
73
- `fetchOptions.context` object, or in the options provided to
74
- `cache.set()`. For example:
70
+ An `integrity` option may be specified in a `fetchOptions.context`
71
+ object, or in the options provided to `cache.set()`. For example:
75
72
 
76
73
  ```js
77
74
  const integrity = `sha512-${base64hash}`
@@ -86,16 +83,16 @@ cache.set(key, value, { integrity })
86
83
  const value = await cache.fetch(key, { context: { integrity } })
87
84
  ```
88
85
 
89
- If the integrity provided is obviously not a valid sha512
90
- `Integrity` string, then it is ignored.
86
+ If the integrity provided is obviously not a valid sha512 `Integrity`
87
+ string, then it is ignored.
91
88
 
92
- Integrity values are not calculated or verified. The caller must do this
93
- check, if desired.
89
+ Integrity values are not calculated or verified. The caller must do
90
+ this check, if desired.
94
91
 
95
92
  Note that the integrity provided to `cache.fetch()` or `cache.set()`
96
93
  does _not_ typically match the calculated integrity of the object
97
- being cached. Typically, the integrity is related to the body of
98
- the response that a `@vltpkg/registry-client.CacheEntry` object
94
+ being cached. Typically, the integrity is related to the body of the
95
+ response that a `@vltpkg/registry-client.CacheEntry` object
99
96
  represents.
100
97
 
101
98
  ## Usage
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@vltpkg/registry-client",
3
3
  "description": "Fetch package artifacts and metadata from registries",
4
- "version": "0.0.0-2",
4
+ "version": "0.0.0-4",
5
5
  "repository": {
6
6
  "type": "git",
7
7
  "url": "git+https://github.com/vltpkg/vltpkg.git",
@@ -23,15 +23,15 @@
23
23
  "cache-control-parser": "^2.0.5",
24
24
  "package-json-from-dist": "^1.0.0",
25
25
  "undici": "^6.20.0",
26
- "@vltpkg/cache": "0.0.0-2",
27
- "@vltpkg/error-cause": "0.0.0-2",
28
- "@vltpkg/cache-unzip": "0.0.0-2",
29
- "@vltpkg/output": "0.0.0-2",
30
- "@vltpkg/promise-spawn": "0.0.0-2",
31
- "@vltpkg/types": "0.0.0-2",
32
- "@vltpkg/url-open": "0.0.0-2",
33
- "@vltpkg/xdg": "0.0.0-2",
34
- "@vltpkg/keychain": "0.0.0-2"
26
+ "@vltpkg/cache": "0.0.0-4",
27
+ "@vltpkg/cache-unzip": "0.0.0-4",
28
+ "@vltpkg/error-cause": "0.0.0-4",
29
+ "@vltpkg/keychain": "0.0.0-4",
30
+ "@vltpkg/output": "0.0.0-4",
31
+ "@vltpkg/promise-spawn": "0.0.0-4",
32
+ "@vltpkg/types": "0.0.0-4",
33
+ "@vltpkg/xdg": "0.0.0-4",
34
+ "@vltpkg/url-open": "0.0.0-4"
35
35
  },
36
36
  "devDependencies": {
37
37
  "@eslint/js": "^9.20.0",