fs/lib/resourceFactory.js

  1. import path from "node:path";
  2. import {minimatch} from "minimatch";
  3. import DuplexCollection from "./DuplexCollection.js";
  4. import FsAdapter from "./adapters/FileSystem.js";
  5. import MemAdapter from "./adapters/Memory.js";
  6. import ReaderCollection from "./ReaderCollection.js";
  7. import ReaderCollectionPrioritized from "./ReaderCollectionPrioritized.js";
  8. import Resource from "./Resource.js";
  9. import WriterCollection from "./WriterCollection.js";
  10. import Filter from "./readers/Filter.js";
  11. import Link from "./readers/Link.js";
  12. import {getLogger} from "@ui5/logger";
  13. const log = getLogger("resources:resourceFactory");
  15. /**
  16.  * @module @ui5/fs/resourceFactory
  17.  * @description A collection of resource related APIs
  18.  * @public
  19.  */
  21. /**
  22.  * Creates a resource <code>ReaderWriter</code>.
  23.  *
  24.  * If a file system base path is given, file system resource <code>ReaderWriter</code> is returned.
  25.  * In any other case a virtual one.
  26.  *
  27.  * @public
  28.  * @param {object} parameters Parameters
  29.  * @param {string} parameters.virBasePath Virtual base path. Must be absolute, POSIX-style, and must end with a slash
  30.  * @param {string} [parameters.fsBasePath]
  31.  *   File System base path.
  32.  *   If this parameter is supplied, a File System adapter will be created instead of a Memory adapter.
  33.  *   The provided path must be absolute and must use platform-specific path segment separators.
  34.  * @param {string[]} [parameters.excludes] List of glob patterns to exclude
  35.  * @param {object} [parameters.useGitignore=false]
  36.  *   Whether to apply any excludes defined in an optional .gitignore in the base directory.
  37.  *   This parameter only takes effect in conjunction with the <code>fsBasePath</code> parameter.
  38.  * @param {@ui5/project/specifications/Project} [parameters.project] Project this adapter belongs to (if any)
  39.  * @returns {@ui5/fs/adapters/FileSystem|@ui5/fs/adapters/Memory} File System- or Virtual Adapter
  40.  */
  41. export function createAdapter({fsBasePath, virBasePath, project, excludes, useGitignore}) {
  42. 	if (fsBasePath) {
  43. 		return new FsAdapter({fsBasePath, virBasePath, project, excludes, useGitignore});
  44. 	} else {
  45. 		return new MemAdapter({virBasePath, project, excludes});
  46. 	}
  47. }
  49. /**
  50.  * Creates a File System adapter and wraps it in a ReaderCollection
  51.  *
  52.  * @public
  53.  * @param {object} parameters Parameters
  54.  * @param {string} parameters.virBasePath Virtual base path. Must be absolute, POSIX-style, and must end with a slash
  55.  * @param {string} parameters.fsBasePath
  56.  *   File System base path. Must be absolute and must use platform-specific path segment separators
  57.  * @param {object} [parameters.project] Experimental, internal parameter. Do not use
  58.  * @param {string[]} [parameters.excludes] List of glob patterns to exclude
  59.  * @param {string} [parameters.name] Name for the reader collection
  60.  * @returns {@ui5/fs/ReaderCollection} Reader collection wrapping an adapter
  61.  */
  62. export function createReader({fsBasePath, virBasePath, project, excludes = [], name}) {
  63. 	if (!fsBasePath) {
  64. 		// Creating a reader with a memory adapter seems pointless right now
  65. 		// since there would be no way to fill the adapter with resources
  66. 		throw new Error(`Unable to create reader: Missing parameter "fsBasePath"`);
  67. 	}
  68. 	let normalizedExcludes = excludes;
  69. 	// If a project is supplied, and that project is of type application,
  70. 	// Prefix all exclude patterns with the virtual base path (unless it already starts with that)
  71. 	// TODO 4.0: // TODO specVersion 4.0: Disallow excludes without namespaced prefix in configuration
  72. 	// Specifying an exclude for "/test" is disambigous as it neither reflects the source path nor the
  73. 	// ui5 runtime path of the excluded resources. Therefore, only allow paths like /resources/<namespace>/test
  74. 	// starting with specVersion 4.0
  75. 	if (excludes.length && project && project.getType() === "application") {
  76. 		normalizedExcludes = excludes.map((pattern) => {
  77. 			if (pattern.startsWith(virBasePath) || pattern.startsWith("!" + virBasePath)) {
  78. 				return pattern;
  79. 			}
  80. 			log.verbose(
  81. 				`Prefixing exclude pattern defined in application project ${project.getName()}: ${pattern}`);
  82. 			return prefixGlobPattern(pattern, virBasePath);
  83. 		});
  84. 		// Flatten list of patterns
  85. 		normalizedExcludes = Array.prototype.concat.apply([], normalizedExcludes);
  86. 		log.verbose(`Effective exclude patterns for application project ${project.getName()}:\n` +
  87. 			normalizedExcludes.join(", "));
  88. 	}
  89. 	return new ReaderCollection({
  90. 		name,
  91. 		readers: [createAdapter({
  92. 			fsBasePath,
  93. 			virBasePath,
  94. 			project,
  95. 			excludes: normalizedExcludes
  96. 		})]
  97. 	});
  98. }
  100. /**
  101.  * Creates a ReaderCollection
  102.  *
  103.  * @public
  104.  * @param {object} parameters Parameters
  105.  * @param {string} parameters.name The collection name
  106.  * @param {@ui5/fs/AbstractReader[]} parameters.readers List of resource readers (all tried in parallel)
  107.  * @returns {@ui5/fs/ReaderCollection} Reader collection wrapping provided readers
  108.  */
  109. export function createReaderCollection({name, readers}) {
  110. 	return new ReaderCollection({
  111. 		name,
  112. 		readers
  113. 	});
  114. }
  116. /**
  117.  * Creates a ReaderCollectionPrioritized
  118.  *
  119.  * @public
  120.  * @param {object} parameters
  121.  * @param {string} parameters.name The collection name
  122.  * @param {@ui5/fs/AbstractReader[]} parameters.readers Prioritized list of resource readers
  123.  * 																(first is tried first)
  124.  * @returns {@ui5/fs/ReaderCollectionPrioritized} Reader collection wrapping provided readers
  125.  */
  126. export function createReaderCollectionPrioritized({name, readers}) {
  127. 	return new ReaderCollectionPrioritized({
  128. 		name,
  129. 		readers
  130. 	});
  131. }
  133. /**
  134.  * Creates a WriterCollection
  135.  *
  136.  * @public
  137.  * @param {object} parameters
  138.  * @param {string} parameters.name The collection name
  139.  * @param {object.<string, @ui5/fs/AbstractReaderWriter>} parameters.writerMapping Mapping of virtual base
  140.  * 	paths to writers. Path are matched greedy
  141.  * @returns {@ui5/fs/WriterCollection} Writer collection wrapping provided writers
  142.  */
  143. export function createWriterCollection({name, writerMapping}) {
  144. 	return new WriterCollection({
  145. 		name,
  146. 		writerMapping
  147. 	});
  148. }
  150. /**
  151.  * Creates a [Resource]{@link @ui5/fs/Resource}.
  152.  * Accepts the same parameters as the [Resource]{@link @ui5/fs/Resource} constructor.
  153.  *
  154.  * @public
  155.  * @param {object} parameters Parameters to be passed to the resource constructor
  156.  * @returns {@ui5/fs/Resource} Resource
  157.  */
  158. export function createResource(parameters) {
  159. 	return new Resource(parameters);
  160. }
  162. /**
  163.  * Creates a Workspace
  164.  *
  165.  * A workspace is a DuplexCollection which reads from the project sources. It is used during the build process
  166.  * to write modified files into a separate writer, this is usually a Memory adapter. If a file already exists it is
  167.  * fetched from the memory to work on it in further build steps.
  168.  *
  169.  * @public
  170.  * @param {object} parameters
  171.  * @param {@ui5/fs/AbstractReader} parameters.reader Single reader or collection of readers
  172.  * @param {@ui5/fs/AbstractReaderWriter} [parameters.writer] A ReaderWriter instance which is
  173.  *        only used for writing files. If not supplied, a Memory adapter will be created.
  174.  * @param {string} [parameters.name="workspace"] Name of the collection
  175.  * @param {string} [parameters.virBasePath="/"] Virtual base path
  176.  * @returns {@ui5/fs/DuplexCollection} DuplexCollection which wraps the provided resource locators
  177.  */
  178. export function createWorkspace({reader, writer, virBasePath = "/", name = "workspace"}) {
  179. 	if (!writer) {
  180. 		writer = new MemAdapter({
  181. 			virBasePath
  182. 		});
  183. 	}
  185. 	return new DuplexCollection({
  186. 		reader,
  187. 		writer,
  188. 		name
  189. 	});
  190. }
  192. /**
  193.  * Create a [Filter-Reader]{@link @ui5/fs/readers/Filter} with the given reader.
  194.  * The provided callback is called for every resource that is retrieved through the
  195.  * reader and decides whether the resource shall be passed on or dropped.
  196.  *
  197.  * @public
  198.  * @param {object} parameters
  199.  * @param {@ui5/fs/AbstractReader} parameters.reader Single reader or collection of readers
  200.  * @param {@ui5/fs/readers/Filter~callback} parameters.callback
  201.  * 				Filter function. Will be called for every resource passed through this reader.
  202.  * @returns {@ui5/fs/readers/Filter} Reader instance
  203.  */
  204. export function createFilterReader(parameters) {
  205. 	return new Filter(parameters);
  206. }
  208. /**
  209.  * Create a [Link-Reader]{@link @ui5/fs/readers/Filter} with the given reader.
  210.  * The provided path mapping allows for rewriting paths segments of all resources passed through it.
  211.  *
  212.  * @example
  213.  * import {createLinkReader} from "@ui5/fs/resourceFactory";
  214.  * const linkedReader = createLinkReader({
  215.  *     reader: sourceReader,
  216.  *     pathMapping: {
  217.  *          linkPath: `/app`,
  218.  *          targetPath: `/resources/my-app-name/`
  219.  *      }
  220.  * });
  221.  *
  222.  * // The following resolves with a @ui5/fs/ResourceFacade of the resource
  223.  * // located at "/resources/my-app-name/Component.js" in the sourceReader
  224.  * const resource = await linkedReader.byPath("/app/Component.js");
  225.  *
  226.  * @public
  227.  * @param {object} parameters
  228.  * @param {@ui5/fs/AbstractReader} parameters.reader Single reader or collection of readers
  229.  * @param {@ui5/fs/readers/Link/PathMapping} parameters.pathMapping
  230.  * @returns {@ui5/fs/readers/Link} Reader instance
  231.  */
  232. export function createLinkReader(parameters) {
  233. 	return new Link(parameters);
  234. }
  236. /**
  237.  * Create a [Link-Reader]{@link @ui5/fs/readers/Link} where all requests are prefixed with
  238.  * <code>/resources/<namespace></code>.
  239.  *
  240.  * This simulates "flat" resource access, which is for example common for projects of type
  241.  * "application".
  242.  *
  243.  * @public
  244.  * @param {object} parameters
  245.  * @param {@ui5/fs/AbstractReader} parameters.reader Single reader or collection of readers
  246.  * @param {string} parameters.namespace Project namespace
  247.  * @returns {@ui5/fs/readers/Link} Reader instance
  248.  */
  249. export function createFlatReader({reader, namespace}) {
  250. 	return new Link({
  251. 		reader: reader,
  252. 		pathMapping: {
  253. 			linkPath: `/`,
  254. 			targetPath: `/resources/${namespace}/`
  255. 		}
  256. 	});
  257. }
  259. /**
  260.  * Normalizes virtual glob patterns by prefixing them with
  261.  * a given virtual base directory path
  262.  *
  263.  * @param {string} virPattern glob pattern for virtual directory structure
  264.  * @param {string} virBaseDir virtual base directory path to prefix the given patterns with
  265.  * @returns {string[]} A list of normalized glob patterns
  266.  */
  267. export function prefixGlobPattern(virPattern, virBaseDir) {
  268. 	const mm = new minimatch.Minimatch(virPattern);
  270. 	const resultGlobs = [];
  271. 	for (let i = 0; i < mm.globSet.length; i++) {
  272. 		let resultPattern = path.posix.join(virBaseDir, mm.globSet[i]);
  274. 		if (mm.negate) {
  275. 			resultPattern = "!" + resultPattern;
  276. 		}
  277. 		resultGlobs.push(resultPattern);
  278. 	}
  279. 	return resultGlobs;
  280. }