@eik/esbuild-plugin 1.1.47 → 1.1.48

package/README.md

@@ -11,17 +11,17 @@ $ npm install @eik/esbuild-plugin
 ## Usage
 
 ```js
-import * as eik from '@eik/esbuild-plugin';
-import esbuild from 'esbuild';
+import * as eik from "@eik/esbuild-plugin";
+import esbuild from "esbuild";
 
 await eik.load();
 
 await esbuild.build({
-    entryPoints: ['./src/app.js'],
-    bundle: true,
-    format: 'esm',
-    target: ['esnext'],
-    plugins: [eik.plugin()],
+	entryPoints: ["./src/app.js"],
+	bundle: true,
+	format: "esm",
+	target: ["esnext"],
+	plugins: [eik.plugin()],
 });
 ```
 
@@ -31,7 +31,7 @@ This plugin will read a local Eik config file (`eik.json`) and download the impo
 
 ### Plugin result
 
-Bundles will have bare imports mapped to absolute URLs. 
+Bundles will have bare imports mapped to absolute URLs.
 
 Ie. Something like this...
 
@@ -53,11 +53,11 @@ This module has the following API:
 
 Loads an Eik configuration or import maps directly for the plugn to use to apply.
 
-| option  | default        | type     | required | details                                                     |
-| ------- | -------------- | -------- | -------- | ----------------------------------------------------------- |
-| path    | `cwd/eik.json` | `string` | `false`  | Path to eik.json file.                                      |
-| urls    | `[]`           | `array`  | `false`  | Array of import map URLs to fetch from.                     |
-| maps    | `[]`           | `array`  | `false`  | Array of import map as objects.                             |
+| option | default        | type     | required | details                                 |
+| ------ | -------------- | -------- | -------- | --------------------------------------- |
+| path   | `cwd/eik.json` | `string` | `false`  | Path to eik.json file.                  |
+| urls   | `[]`           | `array`  | `false`  | Array of import map URLs to fetch from. |
+| maps   | `[]`           | `array`  | `false`  | Array of import map as objects.         |
 
 The plugin will attempt to read a `eik.json` from the current working directory of the Node.js process.
 
@@ -69,7 +69,7 @@ The path to the location of an `eik.json` file can be specified with the `path`
 
 ```js
 await eik.load({
-    path: '/path/to/eik.json',
+	path: "/path/to/eik.json",
 });
 ```
 
@@ -77,7 +77,7 @@ The plugin can also load import maps directly from one or multiple URLs using th
 
 ```js
 await eik.load({
-    urls: ['http://myserver/import-maps/map.json'],
+	urls: ["http://myserver/import-maps/map.json"],
 });
 ```
 
@@ -85,11 +85,13 @@ Additionally, individual import maps can be specified using the `maps` option.
 
 ```js
 await eik.load({
-    maps: [{
-        imports: {
-            'lit-element': 'https://cdn.eik.dev/lit-element/v2',
-        }
-    }],
+	maps: [
+		{
+			imports: {
+				"lit-element": "https://cdn.eik.dev/lit-element/v2",
+			},
+		},
+	],
 });
 ```
 
@@ -99,13 +101,15 @@ ie. in the following example
 
 ```js
 await eik.load({
-    path: '/path/to/eik.json',
-    urls: ['http://myserver/import-maps/map.json'],
-    maps: [{
-        imports: {
-            'lit-element': 'https://cdn.eik.dev/lit-element/v2',
-        }
-    }],
+	path: "/path/to/eik.json",
+	urls: ["http://myserver/import-maps/map.json"],
+	maps: [
+		{
+			imports: {
+				"lit-element": "https://cdn.eik.dev/lit-element/v2",
+			},
+		},
+	],
 });
 ```
 
@@ -116,26 +120,28 @@ Any import map URLs in `eik.json` will be loaded first, then merged with (and ov
 Returns the plugin which will apply the loaded import maps during build. The returned plugin should be appended to the ESBuild plugin array.
 
 ```js
-import * as eik from '@eik/esbuild-plugin';
-import esbuild from 'esbuild';
+import * as eik from "@eik/esbuild-plugin";
+import esbuild from "esbuild";
 
 await eik.load();
 
-esbuild.build({
-    entryPoints: ['src/main.js'],
-    bundle: true,
-    format: 'esm',
-    minify: false,
-    sourcemap: false,
-    target: ['chrome58', 'firefox57', 'safari11', 'edge16'],
-    plugins: [eik.plugin()],
-    outfile: 'out.js',
-}).catch(() => process.exit(1))
+esbuild
+	.build({
+		entryPoints: ["src/main.js"],
+		bundle: true,
+		format: "esm",
+		minify: false,
+		sourcemap: false,
+		target: ["chrome58", "firefox57", "safari11", "edge16"],
+		plugins: [eik.plugin()],
+		outfile: "out.js",
+	})
+	.catch(() => process.exit(1));
 ```
 
 ### .clear()
 
-Clears the loaded import maps from the plugins internal cache. 
+Clears the loaded import maps from the plugins internal cache.
 
 ## License
 

package/package.json

@@ -1,17 +1,21 @@
 {
   "name": "@eik/esbuild-plugin",
-  "version": "1.1.47",
+  "version": "1.1.48",
   "description": "ESBuild plugin for loading import maps from a Eik server and applying the mapping to ECMAScript modules in preparation for upload to the same server.",
   "type": "module",
   "main": "./src/plugin.js",
+  "types": "./types/plugin.d.ts",
   "files": [
-    "src"
+    "src",
+    "types"
   ],
   "scripts": {
-    "test": "tap --no-coverage",
-    "test:snapshot": "TAP_SNAPSHOT=1 tap test/*.js --no-coverage",
-    "lint": "eslint . --ext=js",
-    "lint:fix": "eslint . --fix --ext=js"
+    "test": "tap --disable-coverage --allow-empty-coverage",
+    "lint": "eslint .",
+    "lint:fix": "npm run lint -- --fix",
+    "types": "run-s types:module types:test",
+    "types:module": "tsc",
+    "types:test": "tsc --project tsconfig.test.json"
   },
   "repository": {
     "type": "git",
@@ -35,15 +39,19 @@
   },
   "homepage": "https://github.com/eik-lib/esbuild-plugin#readme",
   "devDependencies": {
-    "@semantic-release/changelog": "6.0.3",
-    "@semantic-release/git": "10.0.1",
-    "esbuild": "0.20.2",
-    "eslint": "8.57.0",
-    "eslint-config-airbnb-base": "15.0.0",
-    "eslint-plugin-import": "2.29.1",
-    "fastify": "4.26.2",
-    "semantic-release": "23.0.6",
-    "tap": "16.3.10"
+    "@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",
+    "@types/esbuild-plugin-import-map": "0.0.3",
+    "esbuild": "0.23.0",
+    "eslint": "9.8.0",
+    "fastify": "4.28.1",
+    "npm-run-all": "4.1.5",
+    "prettier": "3.3.3",
+    "semantic-release": "24.0.0",
+    "tap": "20.0.3",
+    "typescript": "5.5.4"
   },
   "dependencies": {
     "@eik/common": "3.0.1",

package/src/plugin.js

@@ -1,56 +1,110 @@
-/* eslint-disable no-restricted-syntax */
+import * as importMapPlugin from "esbuild-plugin-import-map";
+import { helpers } from "@eik/common";
+import { request } from "undici";
 
-import * as importMapPlugin from 'esbuild-plugin-import-map';
-import { helpers } from '@eik/common';
-import { request } from 'undici';
+/**
+ * @typedef {object} ImportMap
+ * @property {Record<string, string>} imports
+ */
 
+/**
+ * @param {string[]} urls
+ * @returns {Promise<ImportMap[]>}
+ */
 const fetchImportMaps = async (urls = []) => {
-    try {
-        const maps = urls.map(async (map) => {
-            const {
-                statusCode,
-                body,
-            } = await 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 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 /** @type {Promise<ImportMap>} */ (body.json());
+		});
+		return await Promise.all(maps);
+	} catch (err) {
+		throw new Error(
+			`Unable to load import map file from server: ${err.message}`,
+		);
+	}
 };
 
+/**
+ * @typedef {object} LoadOptions
+ * @property {string} [path=process.cwd()]
+ * @property {string[]} [urls=[]] URLs to import maps hosted on an Eik server. Takes precedence over `eik.json`.
+ * @property {ImportMap[]} [maps=[]] Inline import maps that should be used. Takes precedence over `urls` and `eik.json`.
+ */
+
+/**
+ * Loads an Eik configuration or import maps directly for the plugn to use.
+ * Call before building.
+ *
+ * @param {LoadOptions} options
+ * @returns {Promise<void>}
+ * @example
+ * ```js
+ * import * as eik from "@eik/esbuild-plugin";
+ * import esbuild from "esbuild";
+ *
+ * await eik.load();
+ * await esbuild.build({
+ *   plugins: [eik.plugin()],
+ * });
+ * ```
+ */
 export async function load({
-    path = process.cwd(),
-    maps = [],
-    urls = [],
+	path = process.cwd(),
+	maps = [],
+	urls = [],
 } = {}) {
-    const pMaps = Array.isArray(maps) ? maps : [maps];
-    const pUrls = Array.isArray(urls) ? urls : [urls];
+	const pMaps = Array.isArray(maps) ? maps : [maps];
+	const pUrls = Array.isArray(urls) ? urls : [urls];
 
-    const config = await helpers.getDefaults(path);
+	const config = await helpers.getDefaults(path);
 
-    const fetched = await fetchImportMaps([...config.map, ...pUrls]);
-    const mappings = pMaps.concat(fetched);
+	const fetched = await fetchImportMaps([...config.map, ...pUrls]);
+	const mappings = pMaps.concat(fetched);
 
-    await importMapPlugin.load(mappings);
+	await importMapPlugin.load(mappings);
 }
 
+/**
+ * Clear the loaded import maps from the plugins internal cache.
+ *
+ * @returns {void}
+ */
 export function clear() {
-    importMapPlugin.clear();
+	importMapPlugin.clear();
 }
 
+/**
+ * @typedef {object} Plugin
+ * @property {string} name
+ * @property {(build: any) => void} setup
+ */
+
+/**
+ * Returns the plugin which will apply the loaded import maps during build.
+ *
+ * @returns {Plugin}
+ * @example
+ * ```js
+ * import * as eik from "@eik/esbuild-plugin";
+ * import esbuild from "esbuild";
+ *
+ * await eik.load();
+ * await esbuild.build({
+ *   plugins: [eik.plugin()],
+ * });
+ * ```
+ */
 export function plugin() {
-    const obj = importMapPlugin.plugin();
-    obj.name = '@eik/esbuild-plugin';
-    return obj;
+	const obj = importMapPlugin.plugin();
+	obj.name = "@eik/esbuild-plugin";
+	return obj;
 }

package/types/plugin.d.ts

@@ -0,0 +1,69 @@
+/**
+ * @typedef {object} LoadOptions
+ * @property {string} [path=process.cwd()]
+ * @property {string[]} [urls=[]] URLs to import maps hosted on an Eik server. Takes precedence over `eik.json`.
+ * @property {ImportMap[]} [maps=[]] Inline import maps that should be used. Takes precedence over `urls` and `eik.json`.
+ */
+/**
+ * Loads an Eik configuration or import maps directly for the plugn to use.
+ * Call before building.
+ *
+ * @param {LoadOptions} options
+ * @returns {Promise<void>}
+ * @example
+ * ```js
+ * import * as eik from "@eik/esbuild-plugin";
+ * import esbuild from "esbuild";
+ *
+ * await eik.load();
+ * await esbuild.build({
+ *   plugins: [eik.plugin()],
+ * });
+ * ```
+ */
+export function load({ path, maps, urls, }?: LoadOptions): Promise<void>;
+/**
+ * Clear the loaded import maps from the plugins internal cache.
+ *
+ * @returns {void}
+ */
+export function clear(): void;
+/**
+ * @typedef {object} Plugin
+ * @property {string} name
+ * @property {(build: any) => void} setup
+ */
+/**
+ * Returns the plugin which will apply the loaded import maps during build.
+ *
+ * @returns {Plugin}
+ * @example
+ * ```js
+ * import * as eik from "@eik/esbuild-plugin";
+ * import esbuild from "esbuild";
+ *
+ * await eik.load();
+ * await esbuild.build({
+ *   plugins: [eik.plugin()],
+ * });
+ * ```
+ */
+export function plugin(): Plugin;
+export type LoadOptions = {
+    path?: string;
+    /**
+     * URLs to import maps hosted on an Eik server. Takes precedence over `eik.json`.
+     */
+    urls?: string[];
+    /**
+     * Inline import maps that should be used. Takes precedence over `urls` and `eik.json`.
+     */
+    maps?: ImportMap[];
+};
+export type Plugin = {
+    name: string;
+    setup: (build: any) => void;
+};
+export type ImportMap = {
+    imports: Record<string, string>;
+};