jquery · mgol · Sep 19, 2023 · Jul 5, 2023 · Sep 19, 2023 · Sep 19, 2023
diff --git a/README.md b/README.md
@@ -143,6 +143,20 @@ By default, jQuery generates a regular script JavaScript file. You can also gene
 npm run build -- --filename=jquery.module.js --esm
 ```
 
+##### Factory mode
+
+By default, jQuery depends on a global `window`. For environments that don't have one, you can generate a factory build that exposes a function accepting `window` as a parameter that you can provide externally (see [`README` of the published package](build/fixtures/README.md) for usage instructions). You can generate such a factory using the `--factory` parameter:
+
+```bash
+npm run build -- --filename=jquery.factory.js --factory
+```
+
+This option can be mixed with others like `--esm` or `--slim`:
+
+```bash
+npm run build -- --filename=jquery.factory.slim.module.js --factory --esm --slim --dir="/dist-module"
+```
+
 #### Custom Build Examples
 
 Create a custom build using `npm run build`, listing the modules to be excluded. Excluding a top-level module also excludes its corresponding directory of modules.

diff --git a/build/command.js b/build/command.js
@@ -58,6 +58,12 @@ const argv = yargs( process.argv.slice( 2 ) )
 			"Build an ES module (ESM) bundle. " +
 			"By default, a UMD bundle is built."
 	} )
+	.option( "factory", {
+		type: "boolean",
+		description:
+			"Build the factory bundle. " +
+			"By default, a UMD bundle is built."
+	} )
 	.option( "slim", {
 		alias: "s",
 		type: "boolean",

diff --git a/build/fixtures/README.md b/build/fixtures/README.md
@@ -136,16 +136,16 @@ Node.js doesn't understand AMD natively so this method is mostly used in a brows
 
 ### Node.js pre-requisites
 
-For jQuery to work in Node, a window with a document is required. Since no such window exists natively in Node, one can be mocked by tools such as [jsdom](https://github.com/jsdom/jsdom). This can be useful for testing purposes.
+For jQuery to work in Node, a `window` with a `document` is required. Since no such window exists natively in Node, one can be mocked by tools such as [jsdom](https://github.com/jsdom/jsdom). This can be useful for testing purposes.
 
-jQuery checks for a `window` global with a `document` property and - if one is not present, as is the default in Node.js - it returns a factory accepting a `window` as a parameter instead.
+For Node-based environments that don't have a global `window`, jQuery exposes a dedicated `jquery/factory` entry point.
 
 To `import` jQuery using this factory, use the following:
 
 ```js
 import { JSDOM } from "jsdom";
 const { window } = new JSDOM( "" );
-import jQueryFactory from "jquery";
+import { jQueryFactory } from "jquery/factory";
 const $ = jQueryFactory( window );
 ```
 
@@ -154,27 +154,10 @@ or, if you use `require`:
 ```js
 const { JSDOM } = require( "jsdom" );
 const { window } = new JSDOM( "" );
-const $ = require( "jquery" )( window );
-```
-
-If the `window` global is present at the moment of the `import` or `require` of `"jquery"`, it will resolve to a jQuery instance, as in the browser. You can set such a global manually to simulate the behavior; with `import`:
-
-```js
-import { JSDOM } from "jsdom";
-const { window } = new JSDOM( "" );
-globalThis.window = window;
-const { default: $ } = await import( "jquery" );
-```
-
-or with `require`:
-
-```js
-const { JSDOM } = require( "jsdom" );
-const { window } = new JSDOM( "" );
-globalThis.window = window;
-const $ = require( "jquery" );
+const { jQueryFactory } = require( "jquery/factory" );
+const $ = jQueryFactory( window );
 ```
 
 #### Slim build in Node.js
 
-To use the slim build of jQuery in Node.js, use `"jquery/slim"` instead of `"jquery"` in both `require` or `import` calls above.
+To use the slim build of jQuery in Node.js, use `"jquery/slim"` instead of `"jquery"` in both `require` or `import` calls above. To use the slim build in Node.js with factory mode, use `jquery/factory-slim` instead of `jquery/factory`.
diff --git a/build/tasks/build.js b/build/tasks/build.js
@@ -15,6 +15,7 @@ const excludedFromSlim = require( "./lib/slim-exclude" );
 const rollupFileOverrides = require( "./lib/rollup-plugin-file-overrides" );
 const pkg = require( "../../package.json" );
 const isCleanWorkingDir = require( "./lib/isCleanWorkingDir" );
+const processForDist = require( "./dist" );
 const minify = require( "./minify" );
 const getTimestamp = require( "./lib/getTimestamp" );
 const verifyNodeVersion = require( "./lib/verifyNodeVersion" );
@@ -71,8 +72,16 @@ async function readdirRecursive( dir, all = [] ) {
 	return all;
 }
 
-async function getOutputRollupOptions( { esm = false } = {} ) {
-	const wrapperFileName = `wrapper${esm ? "-esm" : ""}.js`;
+async function getOutputRollupOptions( {
+	esm = false,
+	factory = false
+} = {} ) {
+	const wrapperFileName = `wrapper${
+		factory ? "-factory" : ""
+	}${
+		esm ? "-esm" : ""
+	}.js`;
+
 	const wrapperSource = await read( wrapperFileName );
 
 	// Catch `// @CODE` and subsequent comment lines event if they don't start
@@ -163,6 +172,7 @@ async function build( {
 	filename = "jquery.js",
 	include = [],
 	esm = false,
+	factory = false,
 	slim = false,
 	version,
 	watch = false
@@ -275,7 +285,7 @@ async function build( {
 		plugins: [ rollupFileOverrides( fileOverrides ) ]
 	} );
 
-	const outputOptions = await getOutputRollupOptions( { esm } );
+	const outputOptions = await getOutputRollupOptions( { esm, factory } );
 
 	if ( watch ) {
 		const watcher = rollup.watch( {
@@ -305,7 +315,11 @@ async function build( {
 						version
 					} );
 
-					await minify( { dir, filename, esm } );
+					// Don't minify factory files; they are not meant
+					// for the browser anyway.
+					if ( !factory ) {
+						await minify( { dir, filename, esm } );
+					}
 					break;
 			}
 		} );
@@ -317,7 +331,22 @@ async function build( {
 		} = await bundle.generate( outputOptions );
 
 		await writeCompiled( { code, dir, filename, version } );
-		await minify( { dir, filename, esm } );
+
+		// Don't minify factory files; they are not meant
+		// for the browser anyway.
+		if ( !factory ) {
+			await minify( { dir, filename, esm } );
+		} else {
+
+			// We normally process for dist during minification to save
+			// file reads. However, some files are not minified and then
+			// we need to do it separately.
+			const contents = await fs.promises.readFile(
+				path.join( dir, filename ),
+				"utf8"
+			);
+			processForDist( contents, filename );
+		}
 	}
 }
 
@@ -339,6 +368,37 @@ async function buildDefaultFiles( { version, watch } = {} ) {
 			slim: true,
 			version,
 			watch
+		} ),
+
+		build( {
+			filename: "jquery.factory.js",
+			factory: true,
+			version,
+			watch
+		} ),
+		build( {
+			filename: "jquery.factory.slim.js",
+			slim: true,
+			factory: true,
+			version,
+			watch
+		} ),
+		build( {
+			dir: "dist-module",
+			filename: "jquery.factory.module.js",
+			esm: true,
+			factory: true,
+			version,
+			watch
+		} ),
+		build( {
+			dir: "dist-module",
+			filename: "jquery.factory.slim.module.js",
+			esm: true,
+			slim: true,
+			factory: true,
+			version,
+			watch
 		} )
 	] );
 

diff --git a/build/tasks/dist.js b/build/tasks/dist.js
@@ -1,7 +1,7 @@
 "use strict";
 
 // Process files for distribution.
-module.exports = async function processForDist( text, filename ) {
+module.exports = function processForDist( text, filename ) {
 	if ( !text ) {
 		throw new Error( "text required for processForDist" );
 	}

diff --git a/build/tasks/node_smoke_tests.js b/build/tasks/node_smoke_tests.js
@@ -5,7 +5,8 @@ const util = require( "util" );
 const exec = util.promisify( require( "child_process" ).exec );
 const verifyNodeVersion = require( "./lib/verifyNodeVersion" );
 
-const allowedModules = [ "commonjs", "module" ];
+const allowedLibraryTypes = [ "regular", "factory" ];
+const allowedSourceTypes = [ "commonjs", "module" ];
 
 if ( !verifyNodeVersion() ) {
 	return;
@@ -17,33 +18,116 @@ if ( !verifyNodeVersion() ) {
 // important so that the tests & the main process don't interfere with
 // each other, e.g. so that they don't share the `require` cache.
 
-async function runTests( sourceType, module ) {
-	if ( !allowedModules.includes( sourceType ) ) {
-		throw new Error(
-			`Usage: \`node_smoke_tests [${allowedModules.join( "|" )}]:JQUERY\``
-		);
+async function runTests( { libraryType, sourceType, module } ) {
+	if ( !allowedLibraryTypes.includes( libraryType ) ||
+			!allowedSourceTypes.includes( sourceType ) ) {
+		throw new Error( `Incorrect libraryType or sourceType value; passed: ${
+			libraryType
+		} ${ sourceType } "${ module }"` );
 	}
-	const dir = `./test/node_smoke_tests/${sourceType}`;
+	const dir = `./test/node_smoke_tests/${ sourceType }/${ libraryType }`;
 	const files = await fs.promises.readdir( dir, { withFileTypes: true } );
 	const testFiles = files.filter( ( testFilePath ) => testFilePath.isFile() );
+
+	if ( !testFiles.length ) {
+		throw new Error( `No test files found for ${
+			libraryType
+		} ${ sourceType } "${ module }"` );
+	}
+
 	await Promise.all(
 		testFiles.map( ( testFile ) =>
-			exec( `node "${dir}/${testFile.name}" "${module}"` )
+			exec( `node "${ dir }/${ testFile.name }" "${ module }"` )
 		)
 	);
-	console.log( `Node smoke tests passed for ${sourceType} "${module}".` );
+	console.log( `Node smoke tests passed for ${
+		libraryType
+	} ${ sourceType } "${ module }".` );
 }
 
 async function runDefaultTests() {
 	await Promise.all( [
-		runTests( "commonjs", "jquery" ),
-		runTests( "commonjs", "jquery/slim" ),
-		runTests( "commonjs", "./dist/jquery.js" ),
-		runTests( "commonjs", "./dist/jquery.slim.js" ),
-		runTests( "module", "jquery" ),
-		runTests( "module", "jquery/slim" ),
-		runTests( "module", "./dist-module/jquery.module.js" ),
-		runTests( "module", "./dist-module/jquery.slim.module.js" )
+		runTests( {
+			libraryType: "regular",
+			sourceType: "commonjs",
+			module: "jquery"
+		} ),
+		runTests( {
+			libraryType: "regular",
+			sourceType: "commonjs",
+			module: "jquery/slim"
+		} ),
+		runTests( {
+			libraryType: "regular",
+			sourceType: "commonjs",
+			module: "./dist/jquery.js"
+		} ),
+		runTests( {
+			libraryType: "regular",
+			sourceType: "commonjs",
+			module: "./dist/jquery.slim.js"
+		} ),
+		runTests( {
+			libraryType: "regular",
+			sourceType: "module",
+			module: "jquery"
+		} ),
+		runTests( {
+			libraryType: "regular",
+			sourceType: "module",
+			module: "jquery/slim"
+		} ),
+		runTests( {
+			libraryType: "regular",
+			sourceType: "module",
+			module: "./dist-module/jquery.module.js"
+		} ),
+		runTests( {
+			libraryType: "regular",
+			sourceType: "module",
+			module: "./dist-module/jquery.slim.module.js"
+		} ),
+
+		runTests( {
+			libraryType: "factory",
+			sourceType: "commonjs",
+			module: "jquery/factory"
+		} ),
+		runTests( {
+			libraryType: "factory",
+			sourceType: "commonjs",
+			module: "jquery/factory-slim"
+		} ),
+		runTests( {
+			libraryType: "factory",
+			sourceType: "commonjs",
+			module: "./dist/jquery.factory.js"
+		} ),
+		runTests( {
+			libraryType: "factory",
+			sourceType: "commonjs",
+			module: "./dist/jquery.factory.slim.js"
+		} ),
+		runTests( {
+			libraryType: "factory",
+			sourceType: "module",
+			module: "jquery/factory"
+		} ),
+		runTests( {
+			libraryType: "factory",
+			sourceType: "module",
+			module: "jquery/factory-slim"
+		} ),
+		runTests( {
+			libraryType: "factory",
+			sourceType: "module",
+			module: "./dist-module/jquery.factory.module.js"
+		} ),
+		runTests( {
+			libraryType: "factory",
+			sourceType: "module",
+			module: "./dist-module/jquery.factory.slim.module.js"
+		} )
 	] );
 }