[BREAKING] Transform to native ESM (#398)

BREAKING CHANGE: This package has been transformed to native ESM. Therefore it no longer provides a CommonJS export. If your project uses CommonJS, it needs to be converted to ESM or use a dynamic import. For more information see also: - https://sap.github.io/ui5-tooling/updates/migrate-v3/ - https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c Co-authored-by: Florian Vogt <florian.vogt@sap.com>
SAP · Oct 24, 2022 · 2b61580 · 2b61580
1 parent a18fc04
commit 2b61580
Show file tree

Hide file tree

Showing 48 changed files with 1,947 additions and 2,917 deletions.
diff --git a/.eslintrc.js → .eslintrc.cjs b/.eslintrc.js → .eslintrc.cjs
@@ -1,4 +1,7 @@
 module.exports = {
+	"parserOptions": {
+		"sourceType": "module",
+	},
 	"env": {
 		"node": true,
 		"es2021": true
@@ -73,7 +76,8 @@ module.exports = {
 	"settings": {
 		"jsdoc": {
 			"tagNamePreference": {
-				"return": "returns"
+				"return": "returns",
+				"augments": "extends"
 			}
 		}
 	},

diff --git a/index.js b/index.js
diff --git a/jsdoc-plugin.cjs b/jsdoc-plugin.cjs
@@ -0,0 +1,9 @@
+/*
+ * This plugin fixes unexpected JSDoc behavior that prevents us from using types that start with an at-sign (@).
+ * JSDoc doesn't see "{@" as a valid type expression, probably as there's also {@link ...}.
+ */
+exports.handlers = {
+	jsdocCommentFound: function(e) {
+		e.comment = e.comment.replace(/{@ui5\//g, "{ @ui5/");
+	}
+};
diff --git a/jsdoc-plugin.js b/jsdoc-plugin.js
diff --git a/jsdoc.json b/jsdoc.json
@@ -3,12 +3,12 @@
 		"allowUnknownTags": false
 	},
 	"source": {
-		"include": ["README.md", "index.js"],
+		"include": ["README.md"],
 		"includePattern": ".+\\.js$",
 		"excludePattern": "(node_modules(\\\\|/))"
 	},
 	"plugins": [
-		"./jsdoc-plugin"
+		"./jsdoc-plugin.cjs"
 	],
 	"opts": {
 		"encoding": "utf8",

diff --git a/lib/AbstractReader.js b/lib/AbstractReader.js
@@ -1,12 +1,13 @@
-const randomInt = require("random-int");
-const Trace = require("./tracing/Trace");
+import randomInt from "random-int";
+import Trace from "./tracing/Trace.js";
 
 /**
  * Abstract resource locator
  *
- * @public
  * @abstract
- * @memberof module:@ui5/fs
+ * @public
+ * @class
+ * @alias @ui5/fs/AbstractReader
  */
 class AbstractReader {
 	/**
@@ -33,7 +34,7 @@ class AbstractReader {
 	 * 										virtual directory structure
 	 * @param {object} [options] glob options
 	 * @param {boolean} [options.nodir=true] Do not match directories
-	 * @returns {Promise<module:@ui5/fs.Resource[]>} Promise resolving to list of resources
+	 * @returns {Promise<@ui5/fs/Resource[]>} Promise resolving to list of resources
 	 */
 	byGlob(virPattern, options = {nodir: true}) {
 		const trace = new Trace(virPattern);
@@ -60,7 +61,7 @@ class AbstractReader {
 	 * @param {string} virPath Virtual path
 	 * @param {object} [options] Options
 	 * @param {boolean} [options.nodir=true] Do not match directories
-	 * @returns {Promise<module:@ui5/fs.Resource>} Promise resolving to a single resource
+	 * @returns {Promise<@ui5/fs/Resource>} Promise resolving to a single resource
 	 */
 	byPath(virPath, options = {nodir: true}) {
 		const trace = new Trace(virPath);
@@ -70,51 +71,51 @@ class AbstractReader {
 		});
 	}
 
-
 	/**
-	 * Create a [Filter-Reader]{@link module:@ui5/fs.readers.Filter} from the current reader
+	 * Create a [Filter-Reader]{@link @ui5/fs/readers/Filter} from the current reader.
 	 *
 	 * @public
-	 * @param {module:@ui5/fs.readers.Filter~callback} callback
+	 * @param {@ui5/fs/readers/Filter~callback} callback
 	 * 				Filter function. Will be called for every resource passed through this reader.
-	 * @returns {module:@ui5/fs.reader.Filter} Filter instance
+	 * @returns {Promise<@ui5/fs/readers/Filter>} Promise resolving with filter instance
 	 */
-	filter(callback) {
-		const Filter = require("./readers/Filter");
+	async filter(callback) {
+		const {default: Filter} = await import("./readers/Filter.js");
 		return new Filter({
 			reader: this,
 			callback
 		});
 	}
 
 	/**
-	 * Create a [Transformer-Reader]{@link module:@ui5/fs.readers.Transformer} from the current reader
+	 * Create a [Transformer-Reader]{@link @ui5/fs/readers/Transformer} from the current reader.
 	 *
 	 * @private
-	 * @param {module:@ui5/fs.readers.Transformer~callback} callback
+	 * @param {@ui5/fs/readers/Transformer~callback} callback
 	 * 				Callback to check and eventually transform any resource passed through the reader
-	 * @returns {module:@ui5/fs.reader.Transformer} Transformer instance
+	 * @returns {Promise<@ui5/fs/readers/Transformer>} Promise resolving with transformer instance
 	 */
-	transform(callback) {
-		const Transformer = require("./readers/Transformer");
+	async transform(callback) {
+		const {default: Transformer} = await import("./readers/Transformer.js");
 		return new Transformer({
 			reader: this,
 			callback
 		});
 	}
+
 	/**
-	 * Create an abstraction of this reader instance where all requests are prefixed with
+	 * Create a [Link-Reader]{@link @ui5/fs/readers/Link} where all requests are prefixed with
 	 * <code>/resources/<namespace></code>.
 	 *
 	 * This simulates "flat" resource access, which is for example common for projects of type
-	 * "application"
+	 * "application".
 	 *
 	 * @public
 	 * @param {string} namespace Project namespace
-	 * @returns {module:@ui5/fs.reader.AbstractReader} Reader instance
+	 * @returns {Promise<@ui5/fs/readers/Link>} Promise resolving with reader instance
 	 */
-	flatten(namespace) {
-		const Link = require("./readers/Link");
+	async flatten(namespace) {
+		const {default: Link} = await import("./readers/Link.js");
 		return new Link({
 			reader: this,
 			pathMapping: {
@@ -132,8 +133,8 @@ class AbstractReader {
 	 * @param {string|string[]} virPattern glob pattern as string or an array of
 	 *         glob patterns for virtual directory structure
 	 * @param {object} options glob options
-	 * @param {module:@ui5/fs.tracing.Trace} trace Trace instance
-	 * @returns {Promise<module:@ui5/fs.Resource[]>} Promise resolving to list of resources
+	 * @param {@ui5/fs/tracing.Trace} trace Trace instance
+	 * @returns {Promise<@ui5/fs/Resource[]>} Promise resolving to list of resources
 	 */
 	_byGlob(virPattern, options, trace) {
 		throw new Error("Function '_byGlob' is not implemented");
@@ -146,8 +147,8 @@ class AbstractReader {
 	 * @protected
 	 * @param {string} pattern glob pattern
 	 * @param {object} options glob options
-	 * @param {module:@ui5/fs.tracing.Trace} trace Trace instance
-	 * @returns {Promise<module:@ui5/fs.Resource[]>} Promise resolving to list of resources
+	 * @param {@ui5/fs/tracing.Trace} trace Trace instance
+	 * @returns {Promise<@ui5/fs/Resource[]>} Promise resolving to list of resources
 	 */
 	_runGlob(pattern, options, trace) {
 		throw new Error("Function '_runGlob' is not implemented");
@@ -160,12 +161,12 @@ class AbstractReader {
 	 * @protected
 	 * @param {string} virPath Virtual path
 	 * @param {object} options Options
-	 * @param {module:@ui5/fs.tracing.Trace} trace Trace instance
-	 * @returns {Promise<module:@ui5/fs.Resource>} Promise resolving to a single resource
+	 * @param {@ui5/fs/tracing.Trace} trace Trace instance
+	 * @returns {Promise<@ui5/fs/Resource>} Promise resolving to a single resource
 	 */
 	_byPath(virPath, options, trace) {
 		throw new Error("Function '_byPath' is not implemented");
 	}
 }
 
-module.exports = AbstractReader;
+export default AbstractReader;
diff --git a/lib/AbstractReaderWriter.js b/lib/AbstractReaderWriter.js
@@ -1,12 +1,13 @@
-const AbstractReader = require("./AbstractReader");
+import AbstractReader from "./AbstractReader.js";
 
 /**
  * Abstract resource locator
  *
- * @public
  * @abstract
- * @memberof module:@ui5/fs
- * @augments module:@ui5/fs.AbstractReader
+ * @public
+ * @class
+ * @alias @ui5/fs/AbstractReaderWriter
+ * @extends @ui5/fs/AbstractReader
  */
 class AbstractReaderWriter extends AbstractReader {
 	/**
@@ -25,7 +26,7 @@ class AbstractReaderWriter extends AbstractReader {
 	 * Writes the content of a resource to a path.
 	 *
 	 * @public
-	 * @param {module:@ui5/fs.Resource} resource Resource to write
+	 * @param {@ui5/fs/Resource} resource Resource to write
 	 * @param {object} [options]
 	 * @param {boolean} [options.readOnly=false] Whether the resource content shall be written read-only
 	 *						Do not use in conjunction with the <code>drain</code> option.
@@ -48,7 +49,7 @@ class AbstractReaderWriter extends AbstractReader {
 	 *
 	 * @abstract
 	 * @protected
-	 * @param {module:@ui5/fs.Resource} resource Resource to write
+	 * @param {@ui5/fs/Resource} resource Resource to write
 	 * @param {object} [options] Write options, see above
 	 * @returns {Promise<undefined>} Promise resolving once data has been written
 	 */
@@ -57,4 +58,4 @@ class AbstractReaderWriter extends AbstractReader {
 	}
 }
 
-module.exports = AbstractReaderWriter;
+export default AbstractReaderWriter;