Contributing

Setting up the Development Environment

• Make sure you are using the current version of Node.js (JScrewIt may or may not build well with older versions of Node.js).
• Fork the repo on GitHub: https://github.com/fasttime/JScrewIt/fork.
• Clone your fork to your local machine: run git clone https://github.com/${YOUR_GITHUB_USERNAME}/JScrewIt.git.
• In the local repo folder, run npm run build to install dependencies and build the project (this will take a few minutes).
• To quickly rebuild JScrewIt without installing dependencies or building the subpackages, run npx gulp. If gulp-cli is installed, you can run just gulp.

Updating dependencies

If the build starts to fail, it's possible that your local dependencies are out of date.

• Delete node_modules in the repo folder and in all packages subfolders:
  • Bash: rm -rf node_modules packages/*/node_modules
  • PowerShell: rm -Re -Fo node_modules, packages\*\node_modules
• Rerun npm run build and see if it works.

Adding a feature

Define the feature

Features are defined as key-value mappings in file src/lib/features.js. At a minimum, an elementary feature definition should include a description and a check function. The full typing of a feature definition value can be seen in file packages/~feature-hub/src/feature.ts in the type FeatureInfo.

For a change that adds a definition for an elementary feature, see for example here. Note that only the file src/lib/features.js in that commit was edited manually, the other changed files were autogenerated by running gulp in the local repo folder.

Mark feature availability

The next step is determining which browsers and versions of Node.js support the new feature. To check if a feature is available in Node.js, run the command npm run feature-info: this will print a list of available features. For example, in Node.js 22 the output will look like shown in the block.

Compatible feature: NODE_22
Available features: ARRAY_ITERATOR, ARROW, AT, ATOB, ESC_HTML_QUOT, ESC_HTML_QUOT_ONLY, ESC_REGEXP_LF, ESC_REGEXP_SLASH, FILL, FLAT, FROM_CODE_POINT, FUNCTION_19_LF, GENERIC_ARRAY_TO_STRING, GLOBAL_UNDEFINED, GMT, INCR_CHAR¹, INTL, ITERATOR_HELPER, LOCALE_INFINITY, LOCALE_NUMERALS, LOCALE_NUMERALS_EXT, NAME, NO_FF_SRC, NO_IE_SRC, NO_OLD_SAFARI_ARRAY_ITERATOR, OBJECT_UNDEFINED, REGEXP_STRING_ITERATOR, SHORT_LOCALES, UNDEFINED, V8_SRC
Emulated features: ANY_DOCUMENT, ANY_WINDOW, BARPROP, CAPITAL_HTML, CONSOLE, DOCUMENT, DOMWINDOW, ESC_HTML_ALL, FF_SRC, FUNCTION_22_LF, HISTORY, HTMLAUDIOELEMENT, HTMLDOCUMENT, IE_SRC, LOCATION, NODECONSTRUCTOR, NO_V8_SRC, OBJECT_ARRAY_ENTRIES_CTOR, OBJECT_L_LOCATION_CTOR, OBJECT_W_CTOR, OLD_SAFARI_LOCATION_CTOR, PLAIN_INTL, SELF_OBJ, STATUS, WINDOW
(¹) Feature excluded when strict mode is enforced.

To check if a feature is available in a browser, open the file test/spec-runner.html in the browser (this file is autogenerated when JScrewIt is built). A list of available features as shown below will appear on the top of the page.

To mark the feature as available in an engine, edit file src/lib/features.js and add the feature name to the includes section of the engine (the syntax is different for original and inherited engine features). See here for an example. Note that only the file src/lib/features.js in that commit was edited manually, the other changed files were autogenerated by running gulp in the local repo folder. If you rebuild JScrewIt and check the feature list now, you will notice a slight change. The output for Node.js 22 will now look like the following.

Characteristic feature: NODE_22
Available features: ARRAY_ITERATOR, ARROW, AT, ATOB, ESC_HTML_QUOT, ESC_HTML_QUOT_ONLY, ESC_REGEXP_LF, ESC_REGEXP_SLASH, FILL, FLAT, FROM_CODE_POINT, FUNCTION_19_LF, GENERIC_ARRAY_TO_STRING, GLOBAL_UNDEFINED, GMT, INCR_CHAR¹, INTL, ITERATOR_HELPER, LOCALE_INFINITY, LOCALE_NUMERALS, LOCALE_NUMERALS_EXT, NAME, NO_FF_SRC, NO_IE_SRC, NO_OLD_SAFARI_ARRAY_ITERATOR, OBJECT_UNDEFINED, REGEXP_STRING_ITERATOR, SHORT_LOCALES, UNDEFINED, V8_SRC
Emulated features: ANY_DOCUMENT, ANY_WINDOW, BARPROP, CAPITAL_HTML, CONSOLE, DOCUMENT, DOMWINDOW, ESC_HTML_ALL, FF_SRC, FUNCTION_22_LF, HISTORY, HTMLAUDIOELEMENT, HTMLDOCUMENT, IE_SRC, LOCATION, NODECONSTRUCTOR, NO_V8_SRC, OBJECT_ARRAY_ENTRIES_CTOR, OBJECT_L_LOCATION_CTOR, OBJECT_W_CTOR, OLD_SAFARI_LOCATION_CTOR, PLAIN_INTL, SELF_OBJ, STATUS, WINDOW
(¹) Feature excluded when strict mode is enforced.

The first line now says Characteristic Feature. This means that the engine feature NODE_22 includes all elementary features available in the current engine.

Add feature emulation logic

Some unit tests may require features that are not available in the current engine. Feature emulation helps to run those tests in all supported engines regardless of availability. Emulation for a feature is implemented as a function that typically redefines built-in globals and provides instructions to revert those changes. The emulated objects don't need to behave as per specification, just work the way JScrewIt expects. Feature emulation logic is contained in file helpers/feature-emulation.helpers.js. This commit adds support for feature ITERATOR_HELPER.