@eik/node-client 1.1.61 → 1.1.63

package/dist/index.cjs

@@ -4,115 +4,348 @@ var common = require('@eik/common');
 var undici = require('undici');
 var path = require('path');
 
+/**
+ * @typedef {object} AssetOptions
+ * @property {string} [value=""]
+ */
+
+/**
+ * Holds attributes for use when linking to assets hosted on Eik.
+ *
+ * @example
+ * ```
+ * // JS and <script>
+ * const script = eik.file("/app.js");
+ * const html = `<script
+ *   src="${script.value}"
+ *   ${script.integrity ? `integrity="${script.integrity}"` : ""}
+ *   type="module"></script>`;
+ * ```
+ * @example
+ * ```
+ * // CSS and <link>
+ * const styles = eik.file("/styles.css");
+ * const html = `<link
+ *   href="${styles.value}"
+ *   ${styles.integrity ? `integrity="${styles.integrity}"` : ""}
+ *   rel="stylesheet" />`;
+ * ```
+ */
 class Asset {
-    constructor({
-        value = '',
-    } = {}) {
-        this.integrity = undefined;
-        this.value = value;
-    }
+	/**
+	 * Value for use in [subresource integrity](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity#examples).
+	 * Not calculated if `development` is `true`.
+	 *
+	 * @type {string | undefined}
+	 */
+	integrity = undefined;
+
+	/**
+	 * URL to the file for use in `<script>` or `<link>`.
+	 * @type {string}
+	 */
+	value;
+
+	/**
+	 * @param {AssetOptions} options
+	 */
+	constructor({ value = "" } = {}) {
+		this.integrity = undefined;
+		this.value = value;
+	}
 }
 
-const trimSlash = (value = '') => {
-    if (value.endsWith('/')) return value.substring(0, value.length - 1);
-    return value;
+const trimSlash = (value = "") => {
+	if (value.endsWith("/")) return value.substring(0, value.length - 1);
+	return value;
 };
 
 const fetchImportMaps = async (urls = []) => {
-    try{
-        const maps = urls.map(async (map) => {
-            const {
-                statusCode,
-                body
-            } = await undici.request(map, { maxRedirections: 2 });
-            
-            if (statusCode === 404) {
-                throw new Error('Import map could not be found on server');
-            } else if (statusCode >= 400 && statusCode < 500) {
-                throw new Error('Server rejected client request');
-            } else if (statusCode >= 500) {
-                throw new Error('Server error');
-            }
-            return body.json();
-        });
-        return await Promise.all(maps);
-    } catch (err) {
-        throw new Error(
-            `Unable to load import map file from server: ${err.message}`,
-        );
-    }
+	try {
+		const maps = urls.map(async (map) => {
+			const { statusCode, body } = await undici.request(map, {
+				maxRedirections: 2,
+			});
+
+			if (statusCode === 404) {
+				throw new Error("Import map could not be found on server");
+			} else if (statusCode >= 400 && statusCode < 500) {
+				throw new Error("Server rejected client request");
+			} else if (statusCode >= 500) {
+				throw new Error("Server error");
+			}
+			return body.json();
+		});
+		return await Promise.all(maps);
+	} catch (err) {
+		throw new Error(
+			`Unable to load import map file from server: ${err.message}`,
+		);
+	}
 };
 
-class NodeClient {
-    #development;
-    #loadMaps;
-    #config;
-    #path;
-    #base;
-    #maps;
-    constructor({
-        development = false,
-        loadMaps = false,
-        base = '',
-        path = process.cwd(),
-    } = {}) {
-        this.#development = development;
-        this.#loadMaps = loadMaps;
-        this.#config = {};
-        this.#path = path;
-        this.#base = trimSlash(base);
-        this.#maps = [];
-    }
-
-    async load() {
-        this.#config = await common.helpers.getDefaults(this.#path);
-        if (this.#loadMaps) {
-            this.#maps = await fetchImportMaps(this.#config.map);
-        }
-    }
-
-    get name() {
-        if (this.#config.name) return this.#config.name;
-        throw new Error('Eik config was not loaded before calling .name');
-    }
-
-    get version() {
-        if (this.#config.version) return this.#config.version;
-        throw new Error('Eik config was not loaded before calling .version');
-    }
-
-    get type() {
-        if (this.#config.type && this.#config.type === 'package') return 'pkg';
-        if (this.#config.type) return this.#config.type;
-        throw new Error('Eik config was not loaded before calling .type');
-    }
-
-    get server() {
-        if (this.#config.server) return this.#config.server;
-        throw new Error('Eik config was not loaded before calling .server');
-    }
-
-    get pathname() {
-        if (this.#config.type && this.#config.name && this.#config.version) return path.join('/', this.type, this.name, this.version);
-        throw new Error('Eik config was not loaded before calling .pathname');
-    }
-
-    base() {
-        if (this.#development) return this.#base;
-        return `${this.server}${this.pathname}`;
-    }
-
-    file(file = '') {
-        const base = this.base();
-        return new Asset({
-            value: `${base}${file}`,
-        });
-    }
-
-    maps() {
-        if (this.#config.version && this.#loadMaps) return this.#maps;
-        throw new Error('Eik config was not loaded or "loadMaps" is "false" when calling .maps()');
-    }
+/**
+ * @typedef {object} Options
+ * @property {string} [base=null]
+ * @property {boolean} [development=false]
+ * @property {boolean} [loadMaps=false]
+ * @property {string} [path=process.cwd()]
+ */
+
+/**
+ * @typedef {object} ImportMap
+ * @property {Record<string, string>} imports
+ */
+
+/**
+ * An Eik utility for servers running on Node. With it you can:
+ *  - generate different URLs to assets on an Eik server depending on environment (development vs production).
+ *  - get the import maps you have configured in `eik.json` from the Eik server, should you want to use them in the HTML response.
+ *
+ * @example
+ * ```js
+ * // Create an instance, then load information from `eik.json` and the Eik server
+ * import Eik from "@eik/node-client";
+ *
+ * const eik = new Eik();
+ * await eik.load();
+ * ```
+ * @example
+ * ```js
+ * // 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();
+ * app.register(fastifyStatic, {
+ *    root: path.join(process.cwd(), "public"),
+ *    prefix: "/public/",
+ * });
+ *
+ * const eik = new Eik({
+ *    development: process.env.NODE_ENV === "development",
+ *    base: "/public",
+ * });
+ *
+ * // 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>`);
+ * });
+ *
+ * app.listen({
+ *    port: 3000,
+ * });
+ *
+ * console.log("Listening on http://localhost:3000");
+ * ```
+ */
+class Eik {
+	#development;
+	#loadMaps;
+	#config;
+	#path;
+	#base;
+	#maps;
+
+	/**
+	 * @param {Options} options
+	 */
+	constructor({
+		development = false,
+		loadMaps = false,
+		base = "",
+		path = process.cwd(),
+	} = {}) {
+		this.#development = development;
+		this.#loadMaps = loadMaps;
+		this.#config = {};
+		this.#path = path;
+		this.#base = trimSlash(base);
+		this.#maps = [];
+	}
+
+	/**
+	 * Reads the Eik config from disk into the object instance, used for building {@link file} links in production.
+	 *
+	 * If {@link Options.loadMaps} is `true` the import maps
+	 * defined in the Eik config will be fetched from the Eik server for
+	 * use in {@link maps}.
+	 */
+	async load() {
+		this.#config = await common.helpers.getDefaults(this.#path);
+		if (this.#loadMaps) {
+			this.#maps = await fetchImportMaps(this.#config.map);
+		}
+	}
+
+	/**
+	 * The `"name"` field from the Eik config
+	 * @throws if read before calling {@link load}
+	 */
+	get name() {
+		if (this.#config.name) return this.#config.name;
+		throw new Error("Eik config was not loaded before calling .name");
+	}
+
+	/**
+	 * The `"version"` field from the Eik config
+	 * @throws if read before calling {@link load}
+	 */
+	get version() {
+		if (this.#config.version) return this.#config.version;
+		throw new Error("Eik config was not loaded before calling .version");
+	}
+
+	/**
+	 * The `"type"` field from the Eik config mapped to its URL equivalent (eg. "package" is "pkg").
+	 * @throws if read before calling {@link load}
+	 */
+	get type() {
+		if (this.#config.type && this.#config.type === "package") return "pkg";
+		if (this.#config.type) return this.#config.type;
+		throw new Error("Eik config was not loaded before calling .type");
+	}
+
+	/**
+	 * The `"server"` field from the Eik config
+	 * @throws if read before calling {@link load}
+	 */
+	get server() {
+		if (this.#config.server) return this.#config.server;
+		throw new Error("Eik config was not loaded before calling .server");
+	}
+
+	/**
+	 * The pathname to the base on Eik (ex. /pkg/my-app/1.0.0/)
+	 * @throws if read before calling {@link load}
+	 */
+	get pathname() {
+		if (this.#config.type && this.#config.name && this.#config.version)
+			return path.join("/", this.type, this.name, this.version).replace(/\\/g, "/");
+		throw new Error("Eik config was not loaded before calling .pathname");
+	}
+
+	/**
+	 * Similar to {@link file}, this method returns a path to the base on Eik
+	 * (ex. https://eik.store.com/pkg/my-app/1.0.0), or {@link Options.base}
+	 * if {@link Options.development} is true.
+	 *
+	 * You can use this instead of `file` if you have a directory full of files
+	 * and you don't need {@link Asset.integrity}.
+	 *
+	 * @returns {string} The base path for assets published on Eik
+	 * @throws when {@link Options.development} is false if called before calling {@link load}
+	 */
+	base() {
+		if (this.#development) return this.#base;
+		return `${this.server}${this.pathname}`;
+	}
+
+	/**
+	 * Get a link to a file that is published on Eik when running in production.
+	 * When {@link Options.development} is `true` the pathname is prefixed
+	 * with the {@link Options.base} option instead of pointing to Eik.
+	 *
+	 * @param {string} pathname pathname to the file 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)
+	 * @returns {import('./asset.js').Asset}
+	 * @throws when {@link Options.development} is false if called before calling {@link load}
+	 *
+	 * @example
+	 * ```js
+	 * // in production
+	 * const eik = new Eik({
+	 *   development: false,
+	 * });
+	 * await eik.load();
+	 *
+	 * 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",
+	 * // }
+	 * ```
+	 * @example
+	 * ```js
+	 * // in development
+	 * const eik = new Eik({
+	 *   development: true,
+	 *   base: "/public",
+	 * });
+	 * await eik.load();
+	 *
+	 * const file = eik.file("/path/to/script.js");
+	 * // {
+	 * //   value: /public/path/to/script.js
+	 * //   integrity: undefined
+	 * // }
+	 * ```
+	 */
+	file(pathname = "") {
+		const base = this.base();
+		return new Asset({
+			value: `${base}${pathname}`,
+		});
+	}
+
+	/**
+	 * When {@link Options.loadMaps} is `true` and you call {@link load}, the client
+	 * fetches the configured import maps from the Eik server.
+	 *
+	 * This method returns the import maps that were fetched during `load`.
+	 *
+	 * @returns {ImportMap[]}
+	 * @throws if {@link Options.loadMaps} is not `true` or called before calling {@link load}
+	 *
+	 * @example
+	 * ```js
+	 * // generate a <script type="importmap">
+	 * // for import mapping in the browser
+	 * const client = new Eik({
+	 *   loadMaps: true,
+	 * });
+	 * await client.load();
+	 *
+	 * const maps = client.maps();
+	 * const combined = maps
+	 *   .map((map) => map.imports)
+	 *   .reduce((map, acc) => ({ ...acc, ...map }), {});
+	 *
+	 * const html = `
+	 * <script type="importmap">
+	 * ${JSON.stringify(combined, null, 2)}
+	 * </script>
+	 * `;
+	 * ```
+	 */
+	maps() {
+		if (this.#config.version && this.#loadMaps) return this.#maps;
+		throw new Error(
+			'Eik config was not loaded or "loadMaps" is "false" when calling .maps()',
+		);
+	}
 }
 
-module.exports = NodeClient;
+module.exports = Eik;

package/package.json

@@ -1,10 +1,12 @@
 {
   "name": "@eik/node-client",
-  "version": "1.1.61",
-  "description": "A node.js client for interacting with a Eik server.",
+  "version": "1.1.63",
+  "description": "Utilities for working with assets and import maps on an Eik server",
   "type": "module",
   "main": "./dist/index.cjs",
+  "types": "./types/index.d.ts",
   "exports": {
+    "types": "./types/index.d.ts",
     "import": "./src/index.js",
     "require": "./dist/index.cjs"
   },
@@ -13,22 +15,26 @@
     "package.json",
     "LICENSE",
     "dist",
-    "src"
+    "src",
+    "types"
   ],
   "scripts": {
-    "test": "tap --disable-coverage --allow-empty-coverage",
-    "lint:fix": "eslint --fix .",
+    "build": "rollup -c",
+    "clean": "rimraf .tap dist node_modules types",
     "lint": "eslint .",
-    "prepare": "npm run -s build",
-    "build": "rollup -c"
+    "lint:fix": "eslint --fix .",
+    "test": "tap --disable-coverage --allow-empty-coverage",
+    "types": "run-s types:module types:test",
+    "types:module": "tsc",
+    "types:test": "tsc --project tsconfig.test.json",
+    "prepare": "npm run -s build"
   },
   "repository": {
     "type": "git",
     "url": "git@github.com:eik-lib/node-client.git"
   },
   "keywords": [
-    "eik",
-    "esm"
+    "eik"
   ],
   "author": "Finn.no",
   "license": "MIT",
@@ -42,17 +48,17 @@
     "undici": "5.28.4"
   },
   "devDependencies": {
-    "@babel/eslint-parser": "7.24.5",
-    "@semantic-release/changelog": "6.0.3",
-    "@semantic-release/git": "10.0.1",
-    "eslint": "8.57.0",
-    "eslint-config-airbnb-base": "15.0.0",
-    "eslint-config-prettier": "9.1.0",
-    "eslint-plugin-import": "2.29.1",
-    "eslint-plugin-prettier": "5.1.3",
-    "prettier": "3.2.5",
-    "rollup": "4.13.2",
-    "semantic-release": "23.0.8",
-    "tap": "18.7.2"
+    "@eik/eslint-config": "1.0.2",
+    "@eik/prettier-config": "1.0.1",
+    "@eik/semantic-release-config": "1.0.0",
+    "@eik/typescript-config": "1.0.0",
+    "eslint": "9.8.0",
+    "npm-run-all": "4.1.5",
+    "prettier": "3.3.3",
+    "rimraf": "6.0.1",
+    "rollup": "4.20.0",
+    "semantic-release": "24.0.0",
+    "tap": "21.0.0",
+    "typescript": "5.5.4"
   }
 }

package/src/asset.js

@@ -1,8 +1,50 @@
-export default class Asset {
-    constructor({
-        value = '',
-    } = {}) {
-        this.integrity = undefined;
-        this.value = value;
-    }
+/**
+ * @typedef {object} AssetOptions
+ * @property {string} [value=""]
+ */
+
+/**
+ * Holds attributes for use when linking to assets hosted on Eik.
+ *
+ * @example
+ * ```
+ * // JS and <script>
+ * const script = eik.file("/app.js");
+ * const html = `<script
+ *   src="${script.value}"
+ *   ${script.integrity ? `integrity="${script.integrity}"` : ""}
+ *   type="module"></script>`;
+ * ```
+ * @example
+ * ```
+ * // CSS and <link>
+ * const styles = eik.file("/styles.css");
+ * const html = `<link
+ *   href="${styles.value}"
+ *   ${styles.integrity ? `integrity="${styles.integrity}"` : ""}
+ *   rel="stylesheet" />`;
+ * ```
+ */
+export class Asset {
+	/**
+	 * Value for use in [subresource integrity](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity#examples).
+	 * Not calculated if `development` is `true`.
+	 *
+	 * @type {string | undefined}
+	 */
+	integrity = undefined;
+
+	/**
+	 * URL to the file for use in `<script>` or `<link>`.
+	 * @type {string}
+	 */
+	value;
+
+	/**
+	 * @param {AssetOptions} options
+	 */
+	constructor({ value = "" } = {}) {
+		this.integrity = undefined;
+		this.value = value;
+	}
 }