@eik/common 2.0.3 → 3.0.1

package/CHANGELOG.md

@@ -1,3 +1,91 @@
+## [3.0.1](https://github.com/eik-lib/common/compare/v3.0.0...v3.0.1) (2022-05-04)
+
+
+### Bug Fixes
+
+* **deps:** update dependency glob to v8 ([#225](https://github.com/eik-lib/common/issues/225)) ([fd01a56](https://github.com/eik-lib/common/commit/fd01a566b404164bdc847cc7a1803b124e131e41))
+* **deps:** update dependency validate-npm-package-name to v4 ([#222](https://github.com/eik-lib/common/issues/222)) ([c3721ab](https://github.com/eik-lib/common/commit/c3721abf058c93d4e500945c3c014c748c1f2acd))
+
+# [3.0.0](https://github.com/eik-lib/common/compare/v2.0.3...v3.0.0) (2021-08-12)
+
+
+### Bug Fixes
+
+* ensure absolute file paths work as expected ([4f6ce5e](https://github.com/eik-lib/common/commit/4f6ce5e251dcbf0df0b51cc36f73b10585b96538))
+* include eik json schema file in package when publishing ([f0c3c45](https://github.com/eik-lib/common/commit/f0c3c45439a637e8a3cb3a475bca70f2a77c1901))
+* update require statements to avoid circular dependencies ([4359bec](https://github.com/eik-lib/common/commit/4359bec140539c6144be48f7b9ff774b9601d068))
+
+
+### Features
+
+* add extension, mime-type and content-type to file location ([a9b4fe1](https://github.com/eik-lib/common/commit/a9b4fe15cf39425070b9bd260183656933d94c5d))
+* Add hapi support for local assets ([7528c32](https://github.com/eik-lib/common/commit/7528c3277c537e7e0a4228c949988bc7e7a90074))
+* add mappings() method to eik config object ([f989ae0](https://github.com/eik-lib/common/commit/f989ae0e2de0aa5646fd33d0f5854bc7e74c8734)), closes [/github.com/eik-lib/issues/issues/2#issuecomment-779099732](https://github.com//github.com/eik-lib/issues/issues/2/issues/issuecomment-779099732)
+
+
+* refactor!: packageURL removed, localAssets fixed and updated ([90fd181](https://github.com/eik-lib/common/commit/90fd1818f69384d4edeb056dc2c8367e51b21d44))
+* refactor!: remove pathsAndFiles methods ([90d8a12](https://github.com/eik-lib/common/commit/90d8a12e4df8e3a37f295c6136e94bf4ade68cb4))
+* feat!: preserve directory structure when globbing in config ([dff2830](https://github.com/eik-lib/common/commit/dff28301f9bc6e37ef9db32455fa64f5a7a9e80a))
+
+
+### BREAKING CHANGES
+
+* packageURL was removed as it no longer makes sense given the changes to eik json files config
+
+localAssets has been refactored to use the new mappings method of eik config
+* Consumers of the Eik Config class will all need to be updated to use the newer .mappings() method instead.
+* directory structures are no longer flattened
+
+# [4.0.0-next.4](https://github.com/eik-lib/common/compare/v4.0.0-next.3...v4.0.0-next.4) (2021-02-23)
+
+
+### Bug Fixes
+
+* include eik json schema file in package when publishing ([f0c3c45](https://github.com/eik-lib/common/commit/f0c3c45439a637e8a3cb3a475bca70f2a77c1901))
+
+# [4.0.0-next.3](https://github.com/eik-lib/common/compare/v4.0.0-next.2...v4.0.0-next.3) (2021-02-23)
+
+
+### Bug Fixes
+
+* update require statements to avoid circular dependencies ([4359bec](https://github.com/eik-lib/common/commit/4359bec140539c6144be48f7b9ff774b9601d068))
+
+# [4.0.0-next.2](https://github.com/eik-lib/common/compare/v4.0.0-next.1...v4.0.0-next.2) (2021-02-23)
+
+
+### Bug Fixes
+
+* ensure absolute file paths work as expected ([4f6ce5e](https://github.com/eik-lib/common/commit/4f6ce5e251dcbf0df0b51cc36f73b10585b96538))
+
+# [4.0.0-next.1](https://github.com/eik-lib/common/compare/v3.0.0-next.1...v4.0.0-next.1) (2021-02-19)
+
+
+### Features
+
+* Add hapi support for local assets ([7528c32](https://github.com/eik-lib/common/commit/7528c3277c537e7e0a4228c949988bc7e7a90074))
+
+# [3.0.0-next.1](https://github.com/eik-lib/common/compare/v2.0.3...v3.0.0-next.1) (2021-02-18)
+
+
+### Features
+
+* add extension, mime-type and content-type to file location ([a9b4fe1](https://github.com/eik-lib/common/commit/a9b4fe15cf39425070b9bd260183656933d94c5d))
+* add mappings() method to eik config object ([f989ae0](https://github.com/eik-lib/common/commit/f989ae0e2de0aa5646fd33d0f5854bc7e74c8734)), closes [/github.com/eik-lib/issues/issues/2#issuecomment-779099732](https://github.com//github.com/eik-lib/issues/issues/2/issues/issuecomment-779099732)
+
+
+* refactor!: packageURL removed, localAssets fixed and updated ([90fd181](https://github.com/eik-lib/common/commit/90fd1818f69384d4edeb056dc2c8367e51b21d44))
+* refactor!: remove pathsAndFiles methods ([90d8a12](https://github.com/eik-lib/common/commit/90d8a12e4df8e3a37f295c6136e94bf4ade68cb4))
+* feat!: preserve directory structure when globbing in config ([dff2830](https://github.com/eik-lib/common/commit/dff28301f9bc6e37ef9db32455fa64f5a7a9e80a))
+
+
+### BREAKING CHANGES
+
+* packageURL was removed as it no longer makes sense given the changes to eik json files config
+
+localAssets has been refactored to use the new mappings method of eik config
+* Consumers of the Eik Config class will all need to be updated to use the newer .mappings() method instead.
+* directory structures are no longer flattened
+
 ## [2.0.3](https://github.com/eik-lib/common/compare/v2.0.2...v2.0.3) (2021-02-11)
 
 

package/README.md

@@ -8,7 +8,7 @@ This package contains common utilities and schemas
 
 #### eik.json
 
-Importing schemas 
+Importing schemas
 
 ```js
 const { schemas, assert } = require('@eik/common');
@@ -24,7 +24,7 @@ const { error, value } = schemas.validate.eikJSON({
     files: [],
 });
 
-//or 
+//or
 
 assert.eikJSON({
     name: 'my-app',
@@ -75,24 +75,27 @@ const { error, value } = schemas.validate.server('http://myeikserver.com');
 
 assert.server('http://myeikserver.com');
 ```
+
 ##### files
 
 ```js
 const { error, value } = schemas.validate.files({
-    './index.js': '/path/to/file.js'
+    './index.js': '/path/to/file.js',
 });
 
 // or
 
 assert.files({
-    './index.js': '/path/to/file.js'
+    './index.js': '/path/to/file.js',
 });
 ```
 
 ##### import map
 
 ```js
-const { error, value } = schemas.validate.importMap('http://meserver.com/map.json');
+const { error, value } = schemas.validate.importMap(
+    'http://meserver.com/map.json',
+);
 
 const { error, value } = schemas.validate.importMap([
     'http://meserver.com/map1.json',
@@ -137,10 +140,10 @@ For an `eik.json` file such as
     "name": "my-app",
     "version": "1.0.0",
     "server": "https://assets.myeikserver.com",
-    "files" :{
+    "files": {
         "esm.js": "./assets/esm.js",
         "esm.css": "./assets/esm.css",
-        "/": "./assets/**/*.map",
+        "/": "./assets/**/*.map"
     }
 }
 ```
@@ -156,7 +159,7 @@ A number of routes would be mounted into your app.
 
 #### packageURL
 
-This helper function can be used to build URLs for given entries in an `eik.json` files section. 
+This helper function can be used to build URLs for given entries in an `eik.json` files section.
 
 Given the following `eik.json` file:
 
@@ -165,10 +168,10 @@ Given the following `eik.json` file:
     "name": "my-app",
     "version": "1.0.0",
     "server": "https://assets.myeikserver.com",
-    "files" :{
+    "files": {
         "esm.js": "./assets/esm.js",
         "esm.css": "./assets/esm.css",
-        "/": "./assets/**/*.map",
+        "/": "./assets/**/*.map"
     }
 }
 ```
@@ -181,4 +184,3 @@ const url = await helpers.packageURL('esm.js');
 ```
 
 The URL returned will be `https://assets.myeikserver.com/pkg/my-app/1.0.0/esm.js`
-

package/eikjson.d.ts

@@ -0,0 +1,41 @@
+/* tslint:disable */
+/**
+ * This file was automatically generated by json-schema-to-typescript.
+ * DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,
+ * and run json-schema-to-typescript to regenerate this file.
+ */
+
+export interface EikjsonSchema {
+  /**
+   * The URL address of the Eik server where packages are published to.
+   */
+  server: string;
+  /**
+   * The name of the Eik package. Follows the same rules as for NPM package names. Must be parseable by validate-npm-package-name package, which is bundled with npm as a dependency.
+   */
+  name: string;
+  /**
+   * The version of the Eik package. Follows the same rules as for NPM package versions. Must be parseable by node-semver, which is bundled with npm as a dependency.
+   */
+  version: string;
+  /**
+   * The type of the Eik package. Must be one of 'package', 'npm' or 'map'. Setting this value changes the URL publish namespace between '/pkg' (default), '/npm' and '/map', use 'npm' when publishing NPM packages. Use 'map' when publishing import maps.
+   */
+  type?: "package" | "npm" | "map";
+  /**
+   * File mapping definition for the package. Keys represent files or paths to be created on the Eik Server. Values represent paths to local files to be published.
+   */
+  files:
+    | {
+        [k: string]: string;
+      }
+    | string;
+  /**
+   * Import map files given by URL(s) to be used during package bundling. Specified as a URL or array of URLs. URLs are locations of import map files that follow the W3C import map spec.
+   */
+  "import-map"?: string | string[];
+  /**
+   * Location of local Eik build directory (defaults to .eik). Used by Eik client.
+   */
+  out?: string;
+}

package/lib/classes/custom-error.js

@@ -1,4 +1,7 @@
 module.exports = class CustomError extends Error {
+    /**
+     * @param {string} message
+     */
     constructor(message) {
         super(message);
         this.name = this.constructor.name;

package/lib/classes/eik-config.js

@@ -1,38 +1,77 @@
-const { promisify } = require('util');
-const path = require('path');
-const glob = promisify(require('glob'));
+/* eslint-disable no-continue */
+
+/**
+ * @type {(value: unknown, message?: string) => asserts value}
+ */
+const assert = require('assert');
+const { extname, join, isAbsolute } = require('path');
 const NoFilesMatchedError = require('./no-files-matched-error');
 const SingleDestMultipleSourcesError = require('./single-dest-multiple-source-error');
-const { assert, schema } = require('../schemas');
+const FileMapping = require('./file-mapping');
+const RemoteFileLocation = require('./remote-file-location');
+const schemas = require('../schemas');
+const { removeTrailingSlash } = require('../helpers/path-slashes');
+const typeSlug = require('../helpers/type-slug');
+const resolveFiles = require('../helpers/resolve-files');
 
 const _config = Symbol('config');
 const _tokens = Symbol('tokens');
 
+/**
+ * Normalizes Eik JSON "files" definition to object form if in string form
+ *
+ * @param {EikjsonSchema["files"]} files
+ *
+ * @returns {{[k: string]: string;}}
+ */
+const normalizeFilesDefinition = (files) =>
+    typeof files === 'string' ? { '/': files } : files;
+
+/**
+ * @typedef {import ("../../eikjson").EikjsonSchema} EikjsonSchema
+ */
+
 module.exports = class EikConfig {
-    constructor(configHash, tokens, configRootDir) {
-        this[_config] = configHash;
+    /**
+     * @param {EikjsonSchema?} configHash
+     * @param {[string, string][]?} tokens
+     * @param {string?} configRootDir
+     */
+    constructor(configHash, tokens = null, configRootDir = process.cwd()) {
+        /** @type EikjsonSchema */
+        this[_config] = JSON.parse(JSON.stringify(configHash)) || {};
         this[_tokens] = new Map(tokens);
-        this.cwd = configRootDir;
-        this.map = [].concat(configHash['import-map'] || []);
+
+        assert(
+            isAbsolute(configRootDir),
+            `"configRootDir" must be an absolute path: "${configRootDir}" given`,
+        );
+        this.cwd = removeTrailingSlash(configRootDir);
+        /** @type {string[]} */
+        this.map = [].concat(this[_config]['import-map'] || []);
     }
 
+    /** @type {EikjsonSchema["name"]} */
     get name() {
         return this[_config].name;
     }
 
+    /** @type {EikjsonSchema["version"]} */
     get version() {
         return this[_config].version;
     }
 
     set version(newVersion) {
-        assert.version(newVersion);
+        schemas.assert.version(newVersion);
         this[_config].version = newVersion;
     }
 
+    /** @type {EikjsonSchema["type"]} */
     get type() {
-        return this[_config].type || schema.properties.type.default;
+        return this[_config].type || schemas.schema.properties.type.default;
     }
 
+    /** @type {string} */
     get server() {
         const configuredServer = this[_config].server;
         if (configuredServer) {
@@ -41,64 +80,86 @@ module.exports = class EikConfig {
         return this[_tokens].keys().next().value;
     }
 
+    /** @type {[string, string][]} */
     get token() {
         return this[_tokens].get(this.server);
     }
 
+    /** @type {EikjsonSchema["files"]} */
     get files() {
         return this[_config].files;
     }
 
+    /**
+     * Normalized relative directory path with any leading ./ or
+     * trailing / characters stripped. Defaults to .eik
+     *
+     * @returns {string} out path string
+     */
     get out() {
-        return this[_config].out || '.eik';
+        const defaulted = this[_config].out || '.eik';
+        const out = defaulted.startsWith('./')
+            ? defaulted.substr(2)
+            : defaulted;
+        return removeTrailingSlash(out);
     }
 
+    /**
+     * Serializes internal values to an object
+     *
+     * @returns {EikjsonSchema} object consistent with EikjsonSchema
+     */
     toJSON() {
         return { ...this[_config] };
     }
 
+    /**
+     * Validates config values against the eik JSON schema
+     *
+     * @return {void}
+     */
     validate() {
-        assert.eikJSON(this[_config]);
+        schemas.assert.eikJSON(this[_config]);
     }
 
-    async pathsAndFiles() {
-        const resolvedFiles = await Promise.all(
-            Object.entries(this.files).map(([pathname, file]) =>
-                Promise.all([pathname, file, glob(file, { cwd: this.cwd })]),
-            ),
-        );
-        return resolvedFiles.flatMap(([pathname, file, filePaths]) => {
-            if (filePaths.length === 0) {
-                throw new NoFilesMatchedError(file);
+    /**
+     * Resolves file locations on disk based on values defined in files property
+     * of config object.
+     *
+     * @returns {Promise<FileMapping[]>}
+     */
+    async mappings() {
+        const normalizedFiles = normalizeFilesDefinition(this.files);
+        const resolvedFiles = await resolveFiles(normalizedFiles, this.cwd);
+
+        return resolvedFiles.flatMap((files) => {
+            const { destination, source } = files;
+            const filesArray = Array.from(files);
+            if (filesArray.length === 0) {
+                throw new NoFilesMatchedError(source);
             }
 
-            const url = new URL(pathname, 'http://origin');
-            const basename = path.basename(url.pathname);
-            const isNamedDest = basename.includes('.');
-
-            if (isNamedDest) {
-                if (filePaths.length > 1)
-                    throw new SingleDestMultipleSourcesError(pathname);
-                return [[pathname, filePaths[0], pathname, file]];
+            if (extname(destination) !== '' && filesArray.length > 1) {
+                throw new SingleDestMultipleSourcesError(destination);
             }
-            return filePaths.map((filePath) => [
-                path.join(pathname, path.basename(filePath)),
-                filePath,
-                pathname,
-                file,
-            ]);
-        });
-    }
 
-    async pathsAndFilesAbsolute() {
-        const relativePathsAndFiles = await this.pathsAndFiles();
-        return relativePathsAndFiles.reduce((acc, [destPath, srcPath]) => {
-            const absoluteSrc = path.isAbsolute(srcPath)
-                ? srcPath
-                : path.join(this.cwd, srcPath);
-            const absoluteDest = path.join(this.cwd, this.out, destPath);
-            acc.set(absoluteSrc, absoluteDest);
-            return acc;
-        }, new Map());
+            return filesArray.map((localFile) => {
+                const shouldMapFilename = extname(destination);
+                const relativePathname = shouldMapFilename
+                    ? destination
+                    : join(destination, localFile.relative);
+                const packagePathname = join(
+                    typeSlug(this.type),
+                    this.name,
+                    this.version,
+                );
+                const remoteDestination = new RemoteFileLocation(
+                    relativePathname,
+                    packagePathname,
+                    this.server,
+                );
+                return new FileMapping(localFile, remoteDestination);
+            });
+        });
     }
 };

package/lib/classes/file-mapping.js

@@ -0,0 +1,40 @@
+/* eslint-disable no-unused-vars */
+
+/**
+ * @type {(value: unknown, message?: string) => asserts value}
+ */
+const assert = require('assert');
+const LocalFileLocation = require('./local-file-location');
+const RemoteFileLocation = require('./remote-file-location');
+
+/**
+ * Class containing a local file system source location and remote server destination location for a file.
+ */
+class FileMapping {
+    /**
+     * @param {LocalFileLocation} source
+     * @param {RemoteFileLocation} destination
+     */
+    constructor(source, destination) {
+        assert(
+            source instanceof LocalFileLocation,
+            '"source" must be an instance of LocalFileLocation',
+        );
+        assert(
+            destination instanceof RemoteFileLocation,
+            '"destination" must be an instance of RemoteFileLocation',
+        );
+
+        /**
+         * @type {LocalFileLocation} source
+         */
+        this.source = source;
+
+        /**
+         * @type {RemoteFileLocation} destination
+         */
+        this.destination = destination;
+    }
+}
+
+module.exports = FileMapping;

package/lib/classes/invalid-config-error.js

@@ -1,6 +1,9 @@
 const CustomError = require('./custom-error');
 
 module.exports = class InvalidConfigError extends CustomError {
+    /**
+     * @param {string} msg
+     */
     constructor(msg) {
         super(`Eik config object was invalid: '${msg}'`);
     }

package/lib/classes/local-file-location.js

@@ -0,0 +1,59 @@
+/**
+ * @type {(value: unknown, message?: string) => asserts value}
+ */
+const assert = require('assert');
+const { join, extname, isAbsolute } = require('path');
+const mime = require('mime-types');
+
+/**
+ * Class containing information about a local file
+ */
+class LocalFileLocation {
+    /**
+     * @param {string} path path to file on disk relative to basePath
+     * @param {string} basePath basePath to the file's location on disk
+     */
+    constructor(path, basePath) {
+        assert(typeof path === 'string', '"path" must be of type "string"');
+        assert(
+            typeof basePath === 'string',
+            '"basePath" must be of type "string"',
+        );
+        assert(!isAbsolute(path), '"path" must be a relative path');
+
+        /**
+         * @type {string} path to file on disk relative to this.basePath
+         */
+        this.relative = path;
+
+        /**
+         * @type {string} absolute path to root files location on disk
+         */
+        this.basePath = basePath;
+
+        /**
+         * @type {string} absolute path to file on disk,
+         * this is a concatentation of this.basePath and this.relative
+         */
+        this.absolute = join(basePath, path);
+
+        /**
+         * @type {string} file extension with "." character included. (eg. ".json")
+         */
+        this.extension = extname(path);
+
+        /**
+         * @type {string} full content-type header value for file
+         */
+        this.contentType =
+            mime.contentType(this.extension) || 'application/octet-stream';
+
+        /**
+         * @type {string} mime type of file
+         */
+        this.mimeType =
+            mime.lookup(this.extension) || 'application/octet-stream';
+    }
+}
+
+module.exports = LocalFileLocation;

package/lib/classes/missing-config-error.js

@@ -1,6 +1,9 @@
 const CustomError = require('./custom-error');
 
 module.exports = class MissingConfigError extends CustomError {
+    /**
+     * @param {string} dir
+     */
     constructor(dir) {
         super(`No package.json or eik.json file found in: '${dir}'`);
     }

package/lib/classes/no-files-matched-error.js

@@ -1,6 +1,9 @@
 const CustomError = require('./custom-error');
 
 module.exports = class NoFilesMatchedError extends CustomError {
+    /**
+     * @param {string} file
+     */
     constructor(file) {
         const message = `No files found for path: '${file}'`;
         super(message);

package/lib/classes/read-file.js

@@ -1,12 +1,7 @@
-'use strict';
-
 const { isReadableStream } = require('../stream');
 
 const ReadFile = class ReadFile {
-    constructor({
-        mimeType = '',
-        etag = '',
-    } = {}) {
+    constructor({ mimeType = '', etag = '' } = {}) {
         this._mimeType = mimeType;
         this._stream = undefined;
         this._etag = etag;
@@ -17,7 +12,8 @@ const ReadFile = class ReadFile {
     }
 
     set stream(value) {
-        if (!isReadableStream(value)) throw new Error('Value is not a Readable stream');
+        if (!isReadableStream(value))
+            throw new Error('Value is not a Readable stream');
         this._stream = value;
     }
 
@@ -32,5 +28,5 @@ const ReadFile = class ReadFile {
     get [Symbol.toStringTag]() {
         return 'ReadFile';
     }
-}
+};
 module.exports = ReadFile;

package/lib/classes/remote-file-location.js

@@ -0,0 +1,41 @@
+/**
+ * @type {(value: unknown, message?: string) => asserts value}
+ */
+const assert = require('assert');
+const { join } = require('path');
+
+class RemoteFileLocation {
+    /**
+     * @param {string} filePathname pathname for file relative to package root eg. /folder/client.js
+     * @param {string} packagePathname pathname for package root eg. /pkg/my-pack/1.0.0
+     * @param {string} origin server origin eg. https://server.com
+     */
+    constructor(filePathname, packagePathname, origin) {
+        assert(
+            typeof filePathname === 'string',
+            '"filePathname" must be of type "string"',
+        );
+        assert(
+            typeof packagePathname === 'string',
+            '"packagePathname" must be of type "string"',
+        );
+        assert(typeof origin === 'string', '"origin" must be of type "string"');
+
+        /**
+         * @type {string} pathname to package root
+         */
+        this.packagePathname = new URL(packagePathname, origin).pathname;
+
+        /**
+         * @type {string} pathname to file relative to package root
+         */
+        this.filePathname = new URL(filePathname, origin).pathname;
+
+        /**
+         * @type {URL} WHATWG URL object containing the full remote URL for the file
+         */
+        this.url = new URL(join(packagePathname, filePathname), origin);
+    }
+}
+
+module.exports = RemoteFileLocation;