@eik/node-client 2.0.0-next.5 → 2.0.1

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 (8) hide show
  1. package/CHANGELOG.md +246 -29
  2. package/README.md +192 -133
  3. package/dist/index.cjs +377 -0
  4. package/package.json +36 -22
  5. package/src/asset.js +49 -7
  6. package/src/index.js +317 -111
  7. package/types/asset.d.ts +47 -0
  8. package/types/index.d.ts +218 -0
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # @eik/node-client
2
2
 
3
- The Eik Node.js client facilitates loading Eik config and providing URLs to assets on an Eik server or in local development plus loading import maps from the Eik server.
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,215 +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
- ## Basic usage
11
+ ## Usage
12
12
 
13
- ```js
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();
22
-
23
- const scriptPath = client.file('/a-script-file.js');
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.
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.
29
14
 
30
- In addition this module can also download the import maps defined in Eik config and provide these for inclusion in an application.
15
+ For that you use the [`file()` method](#filepathname), which returns an object `{ value, integrity }` where `value` is the link to the file.
31
16
 
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
- import EikNodeClient from '@eik/node-client';
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 client = new EikNodeClient({
38
- development: false,
39
- base: 'http://localhost:8080/public'
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
- await client.load();
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
- // Will, for example, output:
45
- // {
46
- // integrity: sha512-zHQjnDpMW7IKVyTpT9cOPT1+xhUSOcbgXj6qHCPSPu1CbQfgwDEsIniXU54zDIN71zqmxLSp3hfIljpt69ok0w==
47
- // value: https://cdn.eik.dev/pkg/mymodue/2.4.1/path/script.js
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
- The following is the same as above but in development mode. The output will then be based on the vaule set for `base`:
71
+ ### Include a `<script type="importmap">`
53
72
 
54
- ```js
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
- const client = new EikNodeClient({
58
- development: true,
59
- base: 'http://localhost:8080/public'
75
+ ```js
76
+ const client = new Eik({
77
+ loadMaps: true,
60
78
  });
61
-
62
79
  await client.load();
63
80
 
64
- // Will, for example, output:
65
- // {
66
- // integrity: null
67
- // value: http://localhost:8080/public/path/script.js
68
- // }
69
- client.file('/path/script.js')
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
- Create a new client instance.
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
- const client = new EikNodeClient(options);
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
- | path | `process.cwd()` | `string` | `false` | Path to directory containing an eik.json file or package.json with eik config. |
85
- | base | `null` | `string` | `false` | Base root to be used for returned asset files. |
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
- #### path
90
-
91
- Path to directory containing a eik.json file or package.json with eik config.
92
-
93
- #### base
94
-
95
- Base root to be used for returned asset files. Can be either an absolute URL or relative URL. Will only be applied when the module is in development mode.
96
-
97
- #### development
98
-
99
- Set the module in development mode or not.
100
-
101
- #### loadMaps
102
-
103
- Whether import maps defined in the config should be loaded from the Eik server or not. The import maps is loaded by calling the `.load()` method and loaded the maps can be retrieved with the `.maps()` method. The import maps will be cached in the module.
104
-
105
- ### options
106
-
107
- This module has the following API
113
+ ## API
108
114
 
109
115
  ### async .load()
110
116
 
111
- Loads Eik config from the Eik config into the object instance. If `loadMaps` is set to `true` on the constructor, the import maps defined in the config will be loaded from the Eik server.
117
+ Reads the Eik config from disk into the object instance.
112
118
 
113
- ### .base()
119
+ If `loadMaps` was set to `true` the import maps defined in the config will be fetched from the Eik server.
114
120
 
115
- 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.
121
+ ### .file(pathname)
116
122
 
117
- 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.
123
+ Get a link to a file that will differ based on environment (development vs production).
124
+
125
+ When running in production the returned link will point to the file on Eik.
118
126
 
119
127
  ```js
120
- const client = new EikNodeClient({
121
- development: false,
122
- base: 'http://localhost:8080/assets'
128
+ // in production
129
+ const eik = new Eik({
130
+ development: false,
123
131
  });
124
- await client.load();
132
+ await eik.load();
125
133
 
126
- client.base() // https://cdn.eik.dev/pkg/mymodue/2.4.1
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
+ // }
127
145
  ```
128
146
 
129
- When in development mode, the returned value will be equal to whats set on the `base` argument on the constructor.
147
+ When `development` is `true` the pathname is prefixed with the `base` option instead of pointing to Eik.
130
148
 
131
149
  ```js
132
- const client = new EikNodeClient({
133
- development: true,
134
- base: 'http://localhost:8080/assets'
150
+ // in development
151
+ const eik = new Eik({
152
+ development: true,
153
+ base: "/public",
135
154
  });
136
- await client.load();
155
+ await eik.load();
137
156
 
138
- client.base() // http://localhost:8080/assets
157
+ const file = eik.file("/path/to/script.js");
158
+ // {
159
+ // value: /public/path/to/script.js
160
+ // integrity: undefined
161
+ // }
139
162
  ```
140
163
 
141
- ### .file(file)
164
+ #### arguments
142
165
 
143
- Constructs a full URL to an asset. The URL is built up by appending the value of the `file` argument to a `base` root. The returned value will differ depending on if development mode is set to true or not.
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`) |
144
169
 
145
- 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 plus the provided value to the `file` argument on the method.
170
+ #### returns
146
171
 
147
- ```js
148
- const client = new EikNodeClient({
149
- development: false,
150
- base: 'http://localhost:8080/assets'
151
- });
152
- await client.load();
172
+ Returns an object with `value` and `integrity`:
153
173
 
154
- client.file('/js/script.js') // Returns an asset.value like: https://cdn.eik.dev/pkg/mymodue/2.4.1/js/script.js
174
+ ```js
175
+ {
176
+ integrity: 'sha512-zHQjnDpMW7IKVyTpT9cOPT1+xhUSOcbgXj6qHCPSPu1CbQfgwDEsIniXU54zDIN71zqmxLSp3hfIljpt69ok0w==',
177
+ value: 'https://eik.store.com/pkg/my-app/1.0.0/path/to/script.js'
178
+ }
155
179
  ```
156
180
 
157
- When in development mode, the returned value will be equal to whats set on the `base` argument on the constructor plus the provided value to the `file` argument on the method.
181
+ `integrity` is `undefined` if `development` is `true`:
158
182
 
159
183
  ```js
160
- const client = new EikNodeClient({
161
- development: true,
162
- base: 'http://localhost:8080/assets'
163
- });
164
- await client.load();
165
-
166
- client.file('/js/script.js') // Returns an asset.value like: http://localhost:8080/assets/js/script.js
184
+ {
185
+ integrity: undefined,
186
+ value: '/public/path/to/script.js'
187
+ }
167
188
  ```
168
189
 
169
- #### arguments
190
+ ### .maps()
170
191
 
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 |
192
+ When `loadMaps` is `true` and you call `load`, the client fetches the configured import maps from the Eik server.
174
193
 
175
- Returns a object with as follow:
194
+ This method returns the import maps that were fetched during `load`.
176
195
 
177
196
  ```js
178
- {
179
- integrity: 'sha512-zHQjnDpMW7IKVyTpT9cOPT1+xhUSOcbgXj6qHCPSPu1CbQfgwDEsIniXU54zDIN71zqmxLSp3hfIljpt69ok0w==',
180
- value: 'https://cdn.eik.dev/pkg/mymodue/2.4.1/path/script.js'
181
- }
197
+ const client = new Eik({
198
+ loadMaps: true,
199
+ });
200
+ await client.load();
201
+
202
+ const maps = client.maps();
182
203
  ```
183
204
 
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.
205
+ #### returns
185
206
 
186
- ### .maps()
207
+ A list of Eik import maps.
187
208
 
188
- Returns the import maps defined in Eik config from the Eik server. For the maps to be returned they need to be loaded from the Eik server. This is done by setting the `loadMaps` option on the constructor to `true`.
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
+ ```
189
224
 
190
- ### .mapping(identifier)
225
+ ### .base()
191
226
 
192
- Returns the last mapping entry for a given bare import `identifier`.
193
- `identifier` is a `string` key from an import map and the returned `string` is a the matching value from the same import map entry.
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.
194
228
 
195
- #### arguments
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.
196
230
 
197
- | option | default | type | required | details |
198
- | ---------- | ------- | -------- | -------- | ------------------- |
199
- | identifier | | `string` | `true` | Bare import map key |
231
+ ```js
232
+ const client = new Eik({
233
+ development: false,
234
+ base: "http://localhost:8080/assets",
235
+ });
236
+ await client.load();
237
+
238
+ client.base(); // https://cdn.eik.dev/pkg/mymodue/2.4.1
239
+ ```
200
240
 
201
- **Example:**
241
+ When in development mode, the returned value will be equal to whats set on the `base` argument on the constructor.
202
242
 
203
- If an import map being used looks like:
243
+ ```js
244
+ const client = new Eik({
245
+ development: true,
246
+ base: "http://localhost:8080/assets",
247
+ });
248
+ await client.load();
204
249
 
205
- ```json
206
- {
207
- "imports": {
208
- "react": "https://myserver.com/react/18.0.0/react.min.js"
209
- }
210
- }
250
+ client.base(); // http://localhost:8080/assets
211
251
  ```
212
252
 
213
- When the mapping method is called:
253
+ ### .toHTML()
254
+
255
+ Constructs an HTML import map script tag for use in the document head when doing import mapping.
214
256
 
215
257
  ```js
216
- const absoluteURL = client.mapping('react');
258
+ const client = new Eik({
259
+ loadMaps: true,
260
+ ...
261
+ });
262
+ await client.load();
263
+
264
+ const html = `
265
+ <html>
266
+ <head>
267
+ ...
268
+ ${client.toHTML()}
269
+ ...
270
+ </head>
271
+ <body>
272
+ ...
273
+ </body>
274
+ </html>
275
+ `;
217
276
  ```
218
277
 
219
- `absoluteURL` will be `https://myserver.com/react/18.0.0/react.min.js`
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.
220
279
 
221
280
  ## License
222
281