Skip to content

Commit 46f6e3d

Browse files
mgolmgol
authored
Core: Move the factory to separate exports
Since versions 1.11.0/2.1.0, jQuery has used a module wrapper with one strange addition - in CommonJS environments, if a global `window` with a `document` was not present, jQuery exported a factory accepting a `window` implementation and returning jQuery. This approach created a number of problems: 1. Properly typing jQuery would be a nightmare as the exported value depends on the environment. In practice, typing definitions ignored the factory case. 2. Since we now use named exports for the jQuery module version, it felt weird to have `jQuery` and `$` pointing to the factory instead of real jQuery. Instead, for jQuery 4.0 we leverage the just added `exports` field in `package.json` to expose completely separate factory entry points: one for the full build, one for the slim one. Exports definitions for `./factory` & `./factory-slim` are simpler than for `.` and `./slim` - this is because it's a new entry point, we only expose a named export and so there's no issue with just pointing Node.js to the CommonJS version (we cannot use the module version for `import` from Node.js to avoid double package hazard). The factory entry points are also not meant for the Web browser which always has a proper `window` - and they'd be unfit for an inclusion in a regular script tag anyway. Because of that, we also don't generate minified versions of these entry points. The factory files are not pushed to the CDN since they are mostly aimed at Node.js. Closes gh-5293
1 parent b923047 commit 46f6e3d

27 files changed

+367
-148
lines changed

‎README.md

+14
Original file line numberDiff line numberDiff line change
@@ -143,6 +143,20 @@ By default, jQuery generates a regular script JavaScript file. You can also gene
143143
npm run build -- --filename=jquery.module.js --esm
144144
```
145145

146+
##### Factory mode
147+
148+
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:
149+
150+
```bash
151+
npm run build -- --filename=jquery.factory.js --factory
152+
```
153+
154+
This option can be mixed with others like `--esm` or `--slim`:
155+
156+
```bash
157+
npm run build -- --filename=jquery.factory.slim.module.js --factory --esm --slim --dir="/dist-module"
158+
```
159+
146160
#### Custom Build Examples
147161

148162
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.

‎build/command.js

+6
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,12 @@ const argv = yargs( process.argv.slice( 2 ) )
5858
"Build an ES module (ESM) bundle. " +
5959
"By default, a UMD bundle is built."
6060
} )
61+
.option( "factory", {
62+
type: "boolean",
63+
description:
64+
"Build the factory bundle. " +
65+
"By default, a UMD bundle is built."
66+
} )
6167
.option( "slim", {
6268
alias: "s",
6369
type: "boolean",

‎build/fixtures/README.md

+6-23
Original file line numberDiff line numberDiff line change
@@ -136,16 +136,16 @@ Node.js doesn't understand AMD natively so this method is mostly used in a brows
136136

137137
### Node.js pre-requisites
138138

139-
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.
139+
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.
140140

141-
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.
141+
For Node-based environments that don't have a global `window`, jQuery exposes a dedicated `jquery/factory` entry point.
142142

143143
To `import` jQuery using this factory, use the following:
144144

145145
```js
146146
import { JSDOM } from "jsdom";
147147
const { window } = new JSDOM( "" );
148-
import jQueryFactory from "jquery";
148+
import { jQueryFactory } from "jquery/factory";
149149
const $ = jQueryFactory( window );
150150
```
151151

@@ -154,27 +154,10 @@ or, if you use `require`:
154154
```js
155155
const { JSDOM } = require( "jsdom" );
156156
const { window } = new JSDOM( "" );
157-
const $ = require( "jquery" )( window );
158-
```
159-
160-
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`:
161-
162-
```js
163-
import { JSDOM } from "jsdom";
164-
const { window } = new JSDOM( "" );
165-
globalThis.window = window;
166-
const { default: $ } = await import( "jquery" );
167-
```
168-
169-
or with `require`:
170-
171-
```js
172-
const { JSDOM } = require( "jsdom" );
173-
const { window } = new JSDOM( "" );
174-
globalThis.window = window;
175-
const $ = require( "jquery" );
157+
const { jQueryFactory } = require( "jquery/factory" );
158+
const $ = jQueryFactory( window );
176159
```
177160

178161
#### Slim build in Node.js
179162

180-
To use the slim build of jQuery in Node.js, use `"jquery/slim"` instead of `"jquery"` in both `require` or `import` calls above.
163+
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`.

‎build/tasks/build.js

+65-5
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ const excludedFromSlim = require( "./lib/slim-exclude" );
1515
const rollupFileOverrides = require( "./lib/rollup-plugin-file-overrides" );
1616
const pkg = require( "../../package.json" );
1717
const isCleanWorkingDir = require( "./lib/isCleanWorkingDir" );
18+
const processForDist = require( "./dist" );
1819
const minify = require( "./minify" );
1920
const getTimestamp = require( "./lib/getTimestamp" );
2021
const verifyNodeVersion = require( "./lib/verifyNodeVersion" );
@@ -71,8 +72,16 @@ async function readdirRecursive( dir, all = [] ) {
7172
return all;
7273
}
7374

74-
async function getOutputRollupOptions( { esm = false } = {} ) {
75-
const wrapperFileName = `wrapper${esm ? "-esm" : ""}.js`;
75+
async function getOutputRollupOptions( {
76+
esm = false,
77+
factory = false
78+
} = {} ) {
79+
const wrapperFileName = `wrapper${
80+
factory ? "-factory" : ""
81+
}${
82+
esm ? "-esm" : ""
83+
}.js`;
84+
7685
const wrapperSource = await read( wrapperFileName );
7786

7887
// Catch `// @CODE` and subsequent comment lines event if they don't start
@@ -163,6 +172,7 @@ async function build( {
163172
filename = "jquery.js",
164173
include = [],
165174
esm = false,
175+
factory = false,
166176
slim = false,
167177
version,
168178
watch = false
@@ -275,7 +285,7 @@ async function build( {
275285
plugins: [ rollupFileOverrides( fileOverrides ) ]
276286
} );
277287

278-
const outputOptions = await getOutputRollupOptions( { esm } );
288+
const outputOptions = await getOutputRollupOptions( { esm, factory } );
279289

280290
if ( watch ) {
281291
const watcher = rollup.watch( {
@@ -305,7 +315,11 @@ async function build( {
305315
version
306316
} );
307317

308-
await minify( { dir, filename, esm } );
318+
// Don't minify factory files; they are not meant
319+
// for the browser anyway.
320+
if ( !factory ) {
321+
await minify( { dir, filename, esm } );
322+
}
309323
break;
310324
}
311325
} );
@@ -317,7 +331,22 @@ async function build( {
317331
} = await bundle.generate( outputOptions );
318332

319333
await writeCompiled( { code, dir, filename, version } );
320-
await minify( { dir, filename, esm } );
334+
335+
// Don't minify factory files; they are not meant
336+
// for the browser anyway.
337+
if ( !factory ) {
338+
await minify( { dir, filename, esm } );
339+
} else {
340+
341+
// We normally process for dist during minification to save
342+
// file reads. However, some files are not minified and then
343+
// we need to do it separately.
344+
const contents = await fs.promises.readFile(
345+
path.join( dir, filename ),
346+
"utf8"
347+
);
348+
processForDist( contents, filename );
349+
}
321350
}
322351
}
323352

@@ -339,6 +368,37 @@ async function buildDefaultFiles( { version, watch } = {} ) {
339368
slim: true,
340369
version,
341370
watch
371+
} ),
372+
373+
build( {
374+
filename: "jquery.factory.js",
375+
factory: true,
376+
version,
377+
watch
378+
} ),
379+
build( {
380+
filename: "jquery.factory.slim.js",
381+
slim: true,
382+
factory: true,
383+
version,
384+
watch
385+
} ),
386+
build( {
387+
dir: "dist-module",
388+
filename: "jquery.factory.module.js",
389+
esm: true,
390+
factory: true,
391+
version,
392+
watch
393+
} ),
394+
build( {
395+
dir: "dist-module",
396+
filename: "jquery.factory.slim.module.js",
397+
esm: true,
398+
slim: true,
399+
factory: true,
400+
version,
401+
watch
342402
} )
343403
] );
344404

‎build/tasks/dist.js

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
"use strict";
22

33
// Process files for distribution.
4-
module.exports = async function processForDist( text, filename ) {
4+
module.exports = function processForDist( text, filename ) {
55
if ( !text ) {
66
throw new Error( "text required for processForDist" );
77
}

‎build/tasks/node_smoke_tests.js

+101-17
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,8 @@ const util = require( "util" );
55
const exec = util.promisify( require( "child_process" ).exec );
66
const verifyNodeVersion = require( "./lib/verifyNodeVersion" );
77

8-
const allowedModules = [ "commonjs", "module" ];
8+
const allowedLibraryTypes = [ "regular", "factory" ];
9+
const allowedSourceTypes = [ "commonjs", "module" ];
910

1011
if ( !verifyNodeVersion() ) {
1112
return;
@@ -17,33 +18,116 @@ if ( !verifyNodeVersion() ) {
1718
// important so that the tests & the main process don't interfere with
1819
// each other, e.g. so that they don't share the `require` cache.
1920

20-
async function runTests( sourceType, module ) {
21-
if ( !allowedModules.includes( sourceType ) ) {
22-
throw new Error(
23-
`Usage: \`node_smoke_tests [${allowedModules.join( "|" )}]:JQUERY\``
24-
);
21+
async function runTests( { libraryType, sourceType, module } ) {
22+
if ( !allowedLibraryTypes.includes( libraryType ) ||
23+
!allowedSourceTypes.includes( sourceType ) ) {
24+
throw new Error( `Incorrect libraryType or sourceType value; passed: ${
25+
libraryType
26+
} ${ sourceType } "${ module }"` );
2527
}
26-
const dir = `./test/node_smoke_tests/${sourceType}`;
28+
const dir = `./test/node_smoke_tests/${ sourceType }/${ libraryType }`;
2729
const files = await fs.promises.readdir( dir, { withFileTypes: true } );
2830
const testFiles = files.filter( ( testFilePath ) => testFilePath.isFile() );
31+
32+
if ( !testFiles.length ) {
33+
throw new Error( `No test files found for ${
34+
libraryType
35+
} ${ sourceType } "${ module }"` );
36+
}
37+
2938
await Promise.all(
3039
testFiles.map( ( testFile ) =>
31-
exec( `node "${dir}/${testFile.name}" "${module}"` )
40+
exec( `node "${ dir }/${ testFile.name }" "${ module }"` )
3241
)
3342
);
34-
console.log( `Node smoke tests passed for ${sourceType} "${module}".` );
43+
console.log( `Node smoke tests passed for ${
44+
libraryType
45+
} ${ sourceType } "${ module }".` );
3546
}
3647

3748
async function runDefaultTests() {
3849
await Promise.all( [
39-
runTests( "commonjs", "jquery" ),
40-
runTests( "commonjs", "jquery/slim" ),
41-
runTests( "commonjs", "./dist/jquery.js" ),
42-
runTests( "commonjs", "./dist/jquery.slim.js" ),
43-
runTests( "module", "jquery" ),
44-
runTests( "module", "jquery/slim" ),
45-
runTests( "module", "./dist-module/jquery.module.js" ),
46-
runTests( "module", "./dist-module/jquery.slim.module.js" )
50+
runTests( {
51+
libraryType: "regular",
52+
sourceType: "commonjs",
53+
module: "jquery"
54+
} ),
55+
runTests( {
56+
libraryType: "regular",
57+
sourceType: "commonjs",
58+
module: "jquery/slim"
59+
} ),
60+
runTests( {
61+
libraryType: "regular",
62+
sourceType: "commonjs",
63+
module: "./dist/jquery.js"
64+
} ),
65+
runTests( {
66+
libraryType: "regular",
67+
sourceType: "commonjs",
68+
module: "./dist/jquery.slim.js"
69+
} ),
70+
runTests( {
71+
libraryType: "regular",
72+
sourceType: "module",
73+
module: "jquery"
74+
} ),
75+
runTests( {
76+
libraryType: "regular",
77+
sourceType: "module",
78+
module: "jquery/slim"
79+
} ),
80+
runTests( {
81+
libraryType: "regular",
82+
sourceType: "module",
83+
module: "./dist-module/jquery.module.js"
84+
} ),
85+
runTests( {
86+
libraryType: "regular",
87+
sourceType: "module",
88+
module: "./dist-module/jquery.slim.module.js"
89+
} ),
90+
91+
runTests( {
92+
libraryType: "factory",
93+
sourceType: "commonjs",
94+
module: "jquery/factory"
95+
} ),
96+
runTests( {
97+
libraryType: "factory",
98+
sourceType: "commonjs",
99+
module: "jquery/factory-slim"
100+
} ),
101+
runTests( {
102+
libraryType: "factory",
103+
sourceType: "commonjs",
104+
module: "./dist/jquery.factory.js"
105+
} ),
106+
runTests( {
107+
libraryType: "factory",
108+
sourceType: "commonjs",
109+
module: "./dist/jquery.factory.slim.js"
110+
} ),
111+
runTests( {
112+
libraryType: "factory",
113+
sourceType: "module",
114+
module: "jquery/factory"
115+
} ),
116+
runTests( {
117+
libraryType: "factory",
118+
sourceType: "module",
119+
module: "jquery/factory-slim"
120+
} ),
121+
runTests( {
122+
libraryType: "factory",
123+
sourceType: "module",
124+
module: "./dist-module/jquery.factory.module.js"
125+
} ),
126+
runTests( {
127+
libraryType: "factory",
128+
sourceType: "module",
129+
module: "./dist-module/jquery.factory.slim.module.js"
130+
} )
47131
] );
48132
}
49133

0 commit comments

Comments
 (0)