@eik/node-client 1.1.60 → 1.1.62

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [1.1.62](https://github.com/eik-lib/node-client/compare/v1.1.61...v1.1.62) (2024-08-07)
+
+
+### Bug Fixes
+
+* include type definitions ([bea3117](https://github.com/eik-lib/node-client/commit/bea3117093098fe25bb1c56df253ebd5349a7a40))
+
+## [1.1.61](https://github.com/eik-lib/node-client/compare/v1.1.60...v1.1.61) (2024-05-06)
+
+
+### Bug Fixes
+
+* **deps:** update dependency abslog to v2.4.4 ([9f69e9b](https://github.com/eik-lib/node-client/commit/9f69e9b19c364f683f6dedfea81a12d08d4ccfe6))
+
 ## [1.1.60](https://github.com/eik-lib/node-client/compare/v1.1.59...v1.1.60) (2024-04-15)
 
 

package/README.md

@@ -1,6 +1,6 @@
 # @eik/node-client
 
-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.
+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).
 
 ## Install
 
@@ -8,184 +8,254 @@ The Eik Node.js client facilitates loading Eik config and providing URLs to asse
 npm install @eik/node-client
 ```
 
-## Basic usage
+## Usage
 
-```js
-import EikNodeClient from '@eik/node-client';
-
-const client = new EikNodeClient({
-    development: false,
-    base: '/public'
-});
-
-await client.load();
+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.
 
-const scriptPath = client.file('/a-script-file.js');
-```
-
-## Description
-
-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.
+For that you use the [`file()` method](#filepathname), which returns an object `{ value, integrity }` where `value` is the link to the file.
 
-In addition this module can also download the import maps defined in Eik config and provide these for inclusion in an application.
-
-The following will use the information in Eik config and provide an absolute URL to a file on an Eik server:
+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.
 
 ```js
-import EikNodeClient from '@eik/node-client';
+// Serve a local version of a file from `./public`
+// in development and from Eik in production
+import path from "node:path";
+import Eik from "@eik/node-client";
+import fastifyStatic from "@fastify/static";
+import fastify from "fastify";
+
+const app = fastify();
+
+// Serve the contents of the ./public folder on the path /public
+app.register(fastifyStatic, {
+	root: path.join(process.cwd(), "public"),
+	prefix: "/public/",
+});
 
-const client = new EikNodeClient({
-    development: false,
-    base: 'http://localhost:8080/public'        
+const eik = new Eik({
+	development: process.env.NODE_ENV === "development",
+	// base is only used when `development` is `true`
+   base: "/public",
 });
 
-await client.load();
+// load information from `eik.json` and the Eik server
+await eik.load();
+
+// when development is true script.value will be /public/script.js
+// when development is false script.value will be
+// https://{server}/pkg/{name}/{version}/script.js
+// where {server}, {name} and {version} are read from eik.json
+const script = eik.file("/script.js");
+
+app.get("/", (req, reply) => {
+	reply.type("text/html; charset=utf-8");
+	reply.send(`
+<html>
+	<body>
+		<script
+      	src="${script.value}"
+			${script.integrity ? `integrity="${script.integrity}"` : }
+			type="module"
+      ></script>
+	</body>
+</html>`);
+});
 
-// Will, for example, output: 
-// {
-//   integrity: sha512-zHQjnDpMW7IKVyTpT9cOPT1+xhUSOcbgXj6qHCPSPu1CbQfgwDEsIniXU54zDIN71zqmxLSp3hfIljpt69ok0w==
-//   value: https://cdn.eik.dev/pkg/mymodue/2.4.1/path/script.js   
-// }
-client.file('/path/script.js')
+app.listen({
+	port: 3000,
+});
+
+console.log("Listening on http://localhost:3000");
 ```
 
-The following is the same as above but in development mode. The output will then be based on the vaule set for `base`:
+### Include a `<script type="importmap">`
 
-```js
-import EikNodeClient from '@eik/node-client';
+This module can also download the import maps defined in Eik config so you can include them in your HTML responses.
 
-const client = new EikNodeClient({
-    development: true,
-    base: 'http://localhost:8080/public'        
+```js
+const client = new Eik({
+	loadMaps: true,
 });
-
 await client.load();
 
-// Will, for example, output: 
-// {
-//   integrity: null
-//   value: http://localhost:8080/public/path/script.js
-// }
-client.file('/path/script.js')
+const maps = client.maps();
+const combined = maps.reduce((map, acc) => ({ ...acc, ...map }), {});
+
+const html = `
+<script type="importmap">
+${JSON.stringify(combined, null, 2)}
+</script>
+`;
 ```
 
 ## Constructor
 
-Create a new client instance.
+Use the default export to create a new instance.
+
+You must call `load` before using the instance so it can read from `eik.json` and your Eik server.
 
 ```js
-const client = new EikNodeClient(options);
+import Eik from "@eik/node-client";
+
+const eik = new Eik();
+await eik.load();
 ```
 
 ### options
 
-| option      | default         | type      | required | details                                                                        |
-| ----------- | --------------- | --------- | -------- | ------------------------------------------------------------------------------ |
-| path        | `process.cwd()` | `string`  | `false`  | Path to directory containing an eik.json file or package.json with eik config. |
-| base        | `null`          | `string`  | `false`  | Base root to be used for returned asset files.                                 |
-| development | `false`         | `boolean` | `false`  | Set the module in development mode or not.                                     |
+| option      | default         | type      | required | details                                                                                          |
+| ----------- | --------------- | --------- | -------- | ------------------------------------------------------------------------------------------------ |
+| base        | `null`          | `string`  | `false`  | Base root to be used for returned asset files.                                                   |
+| development | `false`         | `boolean` | `false`  | Set the module in development mode or not.                                                       |
 | loadMaps    | `false`         | `boolean` | `false`  | Specifies whether import maps defined in the config should be loaded from the Eik server or not. |
-
-#### path
-
-Path to directory containing a eik.json file or package.json with eik config.
-
-#### base
-
-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.
-
-#### development
-
-Set the module in development mode or not.
-
-#### loadMaps
-
-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.
+| path        | `process.cwd()` | `string`  | `false`  | Path to directory containing an eik.json file or package.json with eik config.                   |
 
 ## API
 
-This module has the following API
-
 ### async .load()
 
-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. 
+Reads the Eik config from disk into the object instance.
 
-### .base()
+If `loadMaps` was set to `true` the import maps defined in the config will be fetched from the Eik server.
 
-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.
+### .file(pathname)
 
-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.
+Get a link to a file that will differ based on environment (development vs production).
+
+When running in production the returned link will point to the file on Eik.
 
 ```js
-const client = new EikNodeClient({
-    development: false,
-    base: 'http://localhost:8080/assets'
+// in production
+const eik = new Eik({
+	development: false,
 });
-await client.load();
+await eik.load();
 
-client.base()  // https://cdn.eik.dev/pkg/mymodue/2.4.1
+const file = eik.file("/path/to/script.js");
+// {
+//   value: https://eik.store.com/pkg/my-app/1.0.0/path/to/script.js
+//   integrity: sha512-zHQjnD-etc.
+// }
+// where the server URL, app name and version are read from eik.json
+// {
+//   "name": "my-app",
+//   "version": "1.0.0",
+//   "server": "https://eik.store.com",
+// }
 ```
 
-When in development mode, the returned value will be equal to whats set on the `base` argument on the constructor.
+When `development` is `true` the pathname is prefixed with the `base` option instead of pointing to Eik.
 
 ```js
-const client = new EikNodeClient({
-    development: true,
-    base: 'http://localhost:8080/assets'
+// in development
+const eik = new Eik({
+	development: true,
+	base: "/public",
 });
-await client.load();
+await eik.load();
 
-client.base()  // http://localhost:8080/assets
+const file = eik.file("/path/to/script.js");
+// {
+//   value: /public/path/to/script.js
+//   integrity: undefined
+// }
 ```
 
-### .file(file)
+#### arguments
+
+| option   | default | type     | details                                                                                                                                   |
+| -------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| 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`) |
 
-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.
+#### returns
 
-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.
+Returns an object with `value` and `integrity`:
 
 ```js
-const client = new EikNodeClient({
-    development: false,
-    base: 'http://localhost:8080/assets'
-});
-await client.load();
+{
+  integrity: 'sha512-zHQjnDpMW7IKVyTpT9cOPT1+xhUSOcbgXj6qHCPSPu1CbQfgwDEsIniXU54zDIN71zqmxLSp3hfIljpt69ok0w==',
+  value: 'https://eik.store.com/pkg/my-app/1.0.0/path/to/script.js'
+}
+```
+
+`integrity` is `undefined` if `development` is `true`:
 
-client.file('/js/script.js')  // Returns an asset.value like: https://cdn.eik.dev/pkg/mymodue/2.4.1/js/script.js
+```js
+{
+  integrity: undefined,
+  value: '/public/path/to/script.js'
+}
 ```
 
-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.
+### .maps()
+
+When `loadMaps` is `true` and you call `load`, the client fetches the configured import maps from the Eik server.
+
+This method returns the import maps that were fetched during `load`.
 
 ```js
-const client = new EikNodeClient({
-    development: true,
-    base: 'http://localhost:8080/assets'
+const client = new Eik({
+	loadMaps: true,
 });
 await client.load();
 
-client.file('/js/script.js')  // Returns an asset.value like: http://localhost:8080/assets/js/script.js
+const maps = client.maps();
+const combined = maps.reduce((map, acc) => ({ ...acc, ...map }), {});
+
+const html = `
+<script type="importmap">
+${JSON.stringify(combined, null, 2)}
+</script>
+`;
 ```
 
-#### arguments
+#### returns
+
+A list of Eik import maps.
+
+```json
+[
+	{
+		"imports": {
+			"date-fns": "https://eik.store.com/npm/date-fns/v3/index.js",
+			"lodash": "https://eik.store.com/npm/lodash/v4/index.js"
+		}
+	},
+	{
+		"imports": {
+			"lit": "https://eik.store.com/npm/lit/v3/index.js"
+		}
+	}
+]
+```
+
+### .base()
 
-| option      | default         | type       | required | details                                                                          |
-| ----------- | --------------- | ---------- | -------- | -------------------------------------------------------------------------------- |
-| file        | `null`          | `string`   | `false`  | File to append to the base of a full URL to an asset                             |
+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.
 
-Returns a object with as follow:
+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.
 
 ```js
-{
-  integrity: 'sha512-zHQjnDpMW7IKVyTpT9cOPT1+xhUSOcbgXj6qHCPSPu1CbQfgwDEsIniXU54zDIN71zqmxLSp3hfIljpt69ok0w==',
-  value: 'https://cdn.eik.dev/pkg/mymodue/2.4.1/path/script.js'
-}
+const client = new Eik({
+	development: false,
+	base: "http://localhost:8080/assets",
+});
+await client.load();
+
+client.base(); // https://cdn.eik.dev/pkg/mymodue/2.4.1
 ```
 
-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.
+When in development mode, the returned value will be equal to whats set on the `base` argument on the constructor.
 
-### .maps()
+```js
+const client = new Eik({
+	development: true,
+	base: "http://localhost:8080/assets",
+});
+await client.load();
 
-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`.
+client.base(); // http://localhost:8080/assets
+```
 
 ## License