@eik/node-client 2.0.0-next.4 → 2.0.0
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.
- package/CHANGELOG.md +243 -26
- package/README.md +194 -104
- package/dist/index.cjs +377 -0
- package/package.json +36 -22
- package/src/asset.js +49 -7
- package/src/index.js +319 -102
- package/types/asset.d.ts +47 -0
- package/types/index.d.ts +218 -0
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# @eik/node-client
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
This is a utility for getting assets and import maps from [Eik servers](https://github.com/eik-lib/service#readme) in Node web applications. For publishing and managing assets to an Eik server from Node scripts, see [`@eik/cli`](https://github.com/eik-lib/cli#readme).
|
|
4
4
|
|
|
5
5
|
## Install
|
|
6
6
|
|
|
@@ -8,184 +8,274 @@ The Eik Node.js client facilitates loading Eik config and providing URLs to asse
|
|
|
8
8
|
npm install @eik/node-client
|
|
9
9
|
```
|
|
10
10
|
|
|
11
|
-
##
|
|
11
|
+
## Usage
|
|
12
12
|
|
|
13
|
-
|
|
14
|
-
import EikNodeClient from '@eik/node-client';
|
|
15
|
-
|
|
16
|
-
const client = new EikNodeClient({
|
|
17
|
-
development: false,
|
|
18
|
-
base: '/public'
|
|
19
|
-
});
|
|
20
|
-
|
|
21
|
-
await client.load();
|
|
13
|
+
The most common use case for this module is linking to a file. When developing you typically want to use a local version of the file, then link to the published version on Eik when running in production.
|
|
22
14
|
|
|
23
|
-
|
|
24
|
-
```
|
|
25
|
-
|
|
26
|
-
## Description
|
|
27
|
-
|
|
28
|
-
This module will load Eik config from either an `eik.json` file or from values set in `package.json` and then use these values to provide absolute URLs to assets on a Eik server. In addition to this it's possible to set a `base` URL which will be used as the "base root" for files when this module is set in development mode. This makes it easy to retrieve absolute URLs to assets on a Eik server when an application is running in production but also get URLs to the same assets when in development.
|
|
15
|
+
For that you use the [`file()` method](#filepathname), which returns an object `{ value, integrity }` where `value` is the link to the file.
|
|
29
16
|
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
The following will use the information in Eik config and provide an absolute URL to a file on an Eik server:
|
|
17
|
+
When running in production the link will point to the file on Eik. When `development` is `true` the pathname is prefixed with the `base` option instead of pointing to Eik, so your app can use a local version.
|
|
33
18
|
|
|
34
19
|
```js
|
|
35
|
-
|
|
20
|
+
// Serve a local version of a file from `./public`
|
|
21
|
+
// in development and from Eik in production
|
|
22
|
+
import path from "node:path";
|
|
23
|
+
import Eik from "@eik/node-client";
|
|
24
|
+
import fastifyStatic from "@fastify/static";
|
|
25
|
+
import fastify from "fastify";
|
|
26
|
+
|
|
27
|
+
const app = fastify();
|
|
28
|
+
|
|
29
|
+
// Serve the contents of the ./public folder on the path /public
|
|
30
|
+
app.register(fastifyStatic, {
|
|
31
|
+
root: path.join(process.cwd(), "public"),
|
|
32
|
+
prefix: "/public/",
|
|
33
|
+
});
|
|
36
34
|
|
|
37
|
-
const
|
|
38
|
-
|
|
39
|
-
|
|
35
|
+
const eik = new Eik({
|
|
36
|
+
development: process.env.NODE_ENV === "development",
|
|
37
|
+
// base is only used when `development` is `true`
|
|
38
|
+
base: "/public",
|
|
40
39
|
});
|
|
41
40
|
|
|
42
|
-
|
|
41
|
+
// load information from `eik.json` and the Eik server
|
|
42
|
+
await eik.load();
|
|
43
|
+
|
|
44
|
+
// when development is true script.value will be /public/script.js
|
|
45
|
+
// when development is false script.value will be
|
|
46
|
+
// https://{server}/pkg/{name}/{version}/script.js
|
|
47
|
+
// where {server}, {name} and {version} are read from eik.json
|
|
48
|
+
const script = eik.file("/script.js");
|
|
49
|
+
|
|
50
|
+
app.get("/", (req, reply) => {
|
|
51
|
+
reply.type("text/html; charset=utf-8");
|
|
52
|
+
reply.send(`
|
|
53
|
+
<html>
|
|
54
|
+
<body>
|
|
55
|
+
<script
|
|
56
|
+
src="${script.value}"
|
|
57
|
+
${script.integrity ? `integrity="${script.integrity}"` : }
|
|
58
|
+
type="module"
|
|
59
|
+
></script>
|
|
60
|
+
</body>
|
|
61
|
+
</html>`);
|
|
62
|
+
});
|
|
43
63
|
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
client.file('/path/script.js')
|
|
64
|
+
app.listen({
|
|
65
|
+
port: 3000,
|
|
66
|
+
});
|
|
67
|
+
|
|
68
|
+
console.log("Listening on http://localhost:3000");
|
|
50
69
|
```
|
|
51
70
|
|
|
52
|
-
|
|
71
|
+
### Include a `<script type="importmap">`
|
|
53
72
|
|
|
54
|
-
|
|
55
|
-
import EikNodeClient from '@eik/node-client';
|
|
73
|
+
This module can also download the import maps defined in Eik config so you can include them in your HTML responses.
|
|
56
74
|
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
75
|
+
```js
|
|
76
|
+
const client = new Eik({
|
|
77
|
+
loadMaps: true,
|
|
60
78
|
});
|
|
61
|
-
|
|
62
79
|
await client.load();
|
|
63
80
|
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
81
|
+
const maps = client.maps();
|
|
82
|
+
const combined = maps.reduce((map, acc) => ({ ...acc, ...map }), {});
|
|
83
|
+
|
|
84
|
+
const html = `
|
|
85
|
+
<script type="importmap">
|
|
86
|
+
${JSON.stringify(combined, null, 2)}
|
|
87
|
+
</script>
|
|
88
|
+
`;
|
|
70
89
|
```
|
|
71
90
|
|
|
72
91
|
## Constructor
|
|
73
92
|
|
|
74
|
-
|
|
93
|
+
Use the default export to create a new instance.
|
|
94
|
+
|
|
95
|
+
You must call `load` before using the instance so it can read from `eik.json` and your Eik server.
|
|
75
96
|
|
|
76
97
|
```js
|
|
77
|
-
|
|
98
|
+
import Eik from "@eik/node-client";
|
|
99
|
+
|
|
100
|
+
const eik = new Eik();
|
|
101
|
+
await eik.load();
|
|
78
102
|
```
|
|
79
103
|
|
|
80
104
|
### options
|
|
81
105
|
|
|
82
|
-
| option | default | type | required | details
|
|
83
|
-
| ----------- | --------------- | --------- | -------- |
|
|
84
|
-
|
|
|
85
|
-
|
|
|
86
|
-
| development | `false` | `boolean` | `false` | Set the module in development mode or not. |
|
|
106
|
+
| option | default | type | required | details |
|
|
107
|
+
| ----------- | --------------- | --------- | -------- | ------------------------------------------------------------------------------------------------ |
|
|
108
|
+
| base | `null` | `string` | `false` | Base root to be used for returned asset files. |
|
|
109
|
+
| development | `false` | `boolean` | `false` | Set the module in development mode or not. |
|
|
87
110
|
| loadMaps | `false` | `boolean` | `false` | Specifies whether import maps defined in the config should be loaded from the Eik server or not. |
|
|
111
|
+
| path | `process.cwd()` | `string` | `false` | Path to directory containing an eik.json file or package.json with eik config. |
|
|
88
112
|
|
|
89
|
-
|
|
113
|
+
## API
|
|
90
114
|
|
|
91
|
-
|
|
115
|
+
### async .load()
|
|
92
116
|
|
|
93
|
-
|
|
117
|
+
Reads the Eik config from disk into the object instance.
|
|
94
118
|
|
|
95
|
-
|
|
119
|
+
If `loadMaps` was set to `true` the import maps defined in the config will be fetched from the Eik server.
|
|
96
120
|
|
|
97
|
-
|
|
121
|
+
### .file(pathname)
|
|
98
122
|
|
|
99
|
-
|
|
123
|
+
Get a link to a file that will differ based on environment (development vs production).
|
|
100
124
|
|
|
101
|
-
|
|
125
|
+
When running in production the returned link will point to the file on Eik.
|
|
102
126
|
|
|
103
|
-
|
|
127
|
+
```js
|
|
128
|
+
// in production
|
|
129
|
+
const eik = new Eik({
|
|
130
|
+
development: false,
|
|
131
|
+
});
|
|
132
|
+
await eik.load();
|
|
104
133
|
|
|
105
|
-
|
|
134
|
+
const file = eik.file("/path/to/script.js");
|
|
135
|
+
// {
|
|
136
|
+
// value: https://eik.store.com/pkg/my-app/1.0.0/path/to/script.js
|
|
137
|
+
// integrity: sha512-zHQjnD-etc.
|
|
138
|
+
// }
|
|
139
|
+
// where the server URL, app name and version are read from eik.json
|
|
140
|
+
// {
|
|
141
|
+
// "name": "my-app",
|
|
142
|
+
// "version": "1.0.0",
|
|
143
|
+
// "server": "https://eik.store.com",
|
|
144
|
+
// }
|
|
145
|
+
```
|
|
106
146
|
|
|
107
|
-
|
|
147
|
+
When `development` is `true` the pathname is prefixed with the `base` option instead of pointing to Eik.
|
|
108
148
|
|
|
109
|
-
|
|
149
|
+
```js
|
|
150
|
+
// in development
|
|
151
|
+
const eik = new Eik({
|
|
152
|
+
development: true,
|
|
153
|
+
base: "/public",
|
|
154
|
+
});
|
|
155
|
+
await eik.load();
|
|
110
156
|
|
|
111
|
-
|
|
157
|
+
const file = eik.file("/path/to/script.js");
|
|
158
|
+
// {
|
|
159
|
+
// value: /public/path/to/script.js
|
|
160
|
+
// integrity: undefined
|
|
161
|
+
// }
|
|
162
|
+
```
|
|
112
163
|
|
|
113
|
-
|
|
164
|
+
#### arguments
|
|
114
165
|
|
|
115
|
-
|
|
166
|
+
| option | default | type | details |
|
|
167
|
+
| -------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
|
|
168
|
+
| pathname | `null` | `string` | Pathname relative to the base on Eik (ex: `/path/to/script.js` for a prod URL `https://eik.store.com/pkg/my-app/1.0.0/path/to/script.js`) |
|
|
116
169
|
|
|
117
|
-
|
|
170
|
+
#### returns
|
|
171
|
+
|
|
172
|
+
Returns an object with `value` and `integrity`:
|
|
118
173
|
|
|
119
174
|
```js
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
}
|
|
124
|
-
|
|
175
|
+
{
|
|
176
|
+
integrity: 'sha512-zHQjnDpMW7IKVyTpT9cOPT1+xhUSOcbgXj6qHCPSPu1CbQfgwDEsIniXU54zDIN71zqmxLSp3hfIljpt69ok0w==',
|
|
177
|
+
value: 'https://eik.store.com/pkg/my-app/1.0.0/path/to/script.js'
|
|
178
|
+
}
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
`integrity` is `undefined` if `development` is `true`:
|
|
125
182
|
|
|
126
|
-
|
|
183
|
+
```js
|
|
184
|
+
{
|
|
185
|
+
integrity: undefined,
|
|
186
|
+
value: '/public/path/to/script.js'
|
|
187
|
+
}
|
|
127
188
|
```
|
|
128
189
|
|
|
129
|
-
|
|
190
|
+
### .maps()
|
|
191
|
+
|
|
192
|
+
When `loadMaps` is `true` and you call `load`, the client fetches the configured import maps from the Eik server.
|
|
193
|
+
|
|
194
|
+
This method returns the import maps that were fetched during `load`.
|
|
130
195
|
|
|
131
196
|
```js
|
|
132
|
-
const client = new
|
|
133
|
-
|
|
134
|
-
base: 'http://localhost:8080/assets'
|
|
197
|
+
const client = new Eik({
|
|
198
|
+
loadMaps: true,
|
|
135
199
|
});
|
|
136
200
|
await client.load();
|
|
137
201
|
|
|
138
|
-
client.
|
|
202
|
+
const maps = client.maps();
|
|
139
203
|
```
|
|
140
204
|
|
|
141
|
-
|
|
205
|
+
#### returns
|
|
206
|
+
|
|
207
|
+
A list of Eik import maps.
|
|
208
|
+
|
|
209
|
+
```json
|
|
210
|
+
[
|
|
211
|
+
{
|
|
212
|
+
"imports": {
|
|
213
|
+
"date-fns": "https://eik.store.com/npm/date-fns/v3/index.js",
|
|
214
|
+
"lodash": "https://eik.store.com/npm/lodash/v4/index.js"
|
|
215
|
+
}
|
|
216
|
+
},
|
|
217
|
+
{
|
|
218
|
+
"imports": {
|
|
219
|
+
"lit": "https://eik.store.com/npm/lit/v3/index.js"
|
|
220
|
+
}
|
|
221
|
+
}
|
|
222
|
+
]
|
|
223
|
+
```
|
|
142
224
|
|
|
143
|
-
|
|
225
|
+
### .base()
|
|
144
226
|
|
|
145
|
-
|
|
227
|
+
Constructs a URL to the base of a package of assets. The returned value will differ depending on if development mode is set to true or not.
|
|
228
|
+
|
|
229
|
+
When in non development mode, the returned value will be built up by the values found in the loaded Eik config and provide a URL to where the files can be expected to be on the Eik server.
|
|
146
230
|
|
|
147
231
|
```js
|
|
148
|
-
const client = new
|
|
149
|
-
|
|
150
|
-
|
|
232
|
+
const client = new Eik({
|
|
233
|
+
development: false,
|
|
234
|
+
base: "http://localhost:8080/assets",
|
|
151
235
|
});
|
|
152
236
|
await client.load();
|
|
153
237
|
|
|
154
|
-
client.
|
|
238
|
+
client.base(); // https://cdn.eik.dev/pkg/mymodue/2.4.1
|
|
155
239
|
```
|
|
156
240
|
|
|
157
|
-
When in development mode, the returned value will be equal to whats set on the `base` argument on the constructor
|
|
241
|
+
When in development mode, the returned value will be equal to whats set on the `base` argument on the constructor.
|
|
158
242
|
|
|
159
243
|
```js
|
|
160
|
-
const client = new
|
|
161
|
-
|
|
162
|
-
|
|
244
|
+
const client = new Eik({
|
|
245
|
+
development: true,
|
|
246
|
+
base: "http://localhost:8080/assets",
|
|
163
247
|
});
|
|
164
248
|
await client.load();
|
|
165
249
|
|
|
166
|
-
client.
|
|
250
|
+
client.base(); // http://localhost:8080/assets
|
|
167
251
|
```
|
|
168
252
|
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
| option | default | type | required | details |
|
|
172
|
-
| ----------- | --------------- | ---------- | -------- | -------------------------------------------------------------------------------- |
|
|
173
|
-
| file | `null` | `string` | `false` | File to append to the base of a full URL to an asset |
|
|
253
|
+
### .toHTML()
|
|
174
254
|
|
|
175
|
-
|
|
255
|
+
Constructs an HTML import map script tag for use in the document head when doing import mapping.
|
|
176
256
|
|
|
177
257
|
```js
|
|
178
|
-
{
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
}
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
If `integrity` of the file is not available, the value for `integrity` will be `null`. This will be the case when in development mode since integrity is calculated upon publish of a package to a Eik server.
|
|
258
|
+
const client = new Eik({
|
|
259
|
+
loadMaps: true,
|
|
260
|
+
...
|
|
261
|
+
});
|
|
262
|
+
await client.load();
|
|
185
263
|
|
|
186
|
-
|
|
264
|
+
const html = `
|
|
265
|
+
<html>
|
|
266
|
+
<head>
|
|
267
|
+
...
|
|
268
|
+
${client.toHTML()}
|
|
269
|
+
...
|
|
270
|
+
</head>
|
|
271
|
+
<body>
|
|
272
|
+
...
|
|
273
|
+
</body>
|
|
274
|
+
</html>
|
|
275
|
+
`;
|
|
276
|
+
```
|
|
187
277
|
|
|
188
|
-
|
|
278
|
+
Due to browsers being restricted to a single import map, all import maps registered in eik.json or package.json will be merged down into a single import map with last in winning in case of duplicate keys.
|
|
189
279
|
|
|
190
280
|
## License
|
|
191
281
|
|