C++ style preprocessing conditionals for JavaScript and Webpack
npm install @dokkanwiki/conditional_js!GitHub Workflow Status !Codecov !GitHub
Use a C++ style pre-processor to conditionally remove JavaScript code.
Includes a Webpack loader.
- Supports the following preprocessor types:
- #define, #undef
- #if, #ifdef, #ifndef
- #else, #elif, #elifdef, #elifndef
- #error, #endif
- Conditional statements are pure javascript
- Allows a global definition context
- Supports isolate-vm for executing conditions in a secure enviroment
- Supports nested conditions
- Can be used through the provided Webpack loader or as a standalone class
- Supports multi-level sourcemap generation
- #define : add a definition for just one file. Does not nest into any imported/required files. If a value is not provided, the identifier will be set to true. The value can be a javascript expression.
- #undef : remove a definition. Global definitions that are undefined are removed for that file only.
- #if : Start a block that will be removed if expression is falsy.
- #ifdef : Start a block that will be removed if the identifier is not defined (no matter the value).
- #ifndef : Start a block that will be removed if the identifier is defined (no matter the value).
- #else: Start a sub-block that will be removed if another prior block is active.
- #elif : Start a sub-block that will be removed if the expression is falsy or a prior block is active.
- #elifdef : Start a sub-block that will be removed if the identifier is not defined (no matter the value) or a prior block is active.
- #elifndef : Start a sub-block that will be removed if the identifier is defined (no matter the value) or a prior block is active.
- #error : Throw an error with message if allowed to execute or is in an active block.
- #endif: Close a block
Install with a node package manager:
``bash`
npm install @dokkanwiki/conditional_js
# or
yarn add @dokkanwiki/conditional_js
# or
pnpm add @dokkanwiki/conditional_js
Webpack loader documentation: https://webpack.js.org/loaders/
Within your webpack configuration, you'll need to add @dokkanwiki/conditional_js to the rules that are processing your JavaScript.
Process javascript files directly:
`javascript`
module: {
rules: [
{
test: /\.m?js$/,
exclude: /node_modules/,
use: {
loader: '@dokkanwiki/conditional_js',
options: {
definitions: {
DEBUG: true,
NODE_ENV: process.env.NODE_ENV
}
}
}
}
]
}
Process before Babel:
`javascript
module: {
rules: [
{
test: /\.m?js$/,
exclude: /node_modules/,
use: [
{
loader: 'babel-loader',
options: {
presets: [
['@babel/preset-env', { targets: "defaults" }]
]
}
},
{
loader: '@dokkanwiki/conditional_js',
options: {
DEBUG: process.env.NODE_ENV === 'development'
}
}
]
}
]
}
`
- parser: Defaults to @ style macros (@if, @ifdef, etc). '@'
- Provide a string to determine flavor: or '#'file_detect
- Alternatively provide an object to define your own parsing method. Provide the following properties:
- : Regex string or RegExp class instancedefine
- Used to detect if a file should be processed
- , if, ifdef, ifndef, elif, else, elifdef, elifndef, endif, undef, errorRegExp
- Regex string, class instance, or a function that takes a string and returns either undefined for no match or an array of object with the following properties: value string of matched group, index position of matched group item in the string. See src/options.ts for additional information.action
- : Defaults to remove.remove
- Control what happens to inactive conditional blocks.
- Options are: or commentdefinitions
- : Object (key => value) of global definitions to apply to all files.sandbox
- : Defaults to trueisolate-vm
- Run conditional statements in sandboxtrue
- Provide to run in sandbox with default options.false
- [NOT RECOMMENDED] Provide to run conditional statements with eval(). memory_limit
- Provide an object with the following properties:
- : Memory limit in megabytes. Defaults to 128MB.timeout
- : Timeout for individual condition in milliseconds. Defaults to 250ms.
API Reference
#### ConditionalJsProcessor
- new ConditionalJsProcessor(options)process(source, context)
- source
- : file content as stringcontext
- : Optional object with the following properties:file_name
- : stringsource_map
- : string or objectobject
- Returns promise resolving to with the following properties:transformed_source
- transformed_map
- processor
- : ConditionalJsProcessor instancerelease()
- isolated-vm
- Clean up executor. No-op if not using a sandbox.
`javascript
// @if NODE_ENV === 'production'
// @undef PERFORMANCE_STATS
// @elif NODE_ENV === 'development'
// @define PERFORMANCE_STATS
// @else
// @error NODE_ENV must be either 'production' or 'development'
// @endif
const render = function () {
// @ifdef PERFORMANCE_STATS
const t0 = performance.now();
// @endif
requestAnimationFrame(render);
renderer.render(scene, camera);
// @ifdef PERFORMANCE_STATS
const t1 = performance.now();
console.log(Call to render() took ${t1 - t0} milliseconds.);``
// @endif
};