js-tail-recursion-opt-rspeedy-plugin

A rSpeedy plugin for automatic tail recursion optimization in Lynx applications. This plugin integrates the js-tail-recursion-opt-plugin with Lynx's rSpeedy build system to automatically optimize tail-recursive functions at build time.

Features

- ✅ Automatic tail recursion detection and optimization
- ✅ Zero runtime overhead (compile-time optimization)
- ✅ Stack overflow prevention
- ✅ Works with JavaScript and TypeScript
- ✅ Compatible with Lynx rSpeedy build system
- ✅ Maintains source map support for debugging
- ✅ Flexible configuration options

Installation

``bash
npm install js-tail-recursion-opt-rspeedy-plugin
`

Usage

$3

Configure in your lynx.config.mjs:

`javascript
import { defineConfig } from "@lynx-js/rspeedy";
import { pluginReactLynx } from "@lynx-js/react-rsbuild-plugin";
import { pluginTailRecursion } from "js-tail-recursion-opt-rspeedy-plugin";

export default defineConfig({
source: {
entry: "./index.tsx",
alias: {
"@components": "./components",
"@assets": "./assets",
},
},
plugins: [
pluginReactLynx(),
pluginTailRecursion({
// Configuration options (all optional)
onlyAnnotated: false, // Only optimize functions with @tail-recursion annotation
annotationTag: "@tail-recursion", // Custom annotation tag
debug: false, // Enable debug logging
exclude: [/node_modules/], // Files to exclude
include: [/\.(js|ts|jsx|tsx)$/], // Files to include
})
],
});
`

$3

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| onlyAnnotated | boolean | false | Only optimize functions annotated with specific comment |
| annotationTag | string | "@tail-recursion" | Annotation tag to look for when onlyAnnotated is true |
| debug | boolean | false | Enable debug logging |
| exclude | RegExp[] | [/node_modules/] | Files to exclude from optimization |
| include | RegExp[] | [/\.(js\|ts\|jsx\|tsx)$/] | Files to include for optimization |

$3

Before optimization:
`javascript
// This will cause stack overflow with large inputs
function factorial(n, acc = 1) {
if (n <= 1) return acc;
return factorial(n - 1, n * acc); // Tail recursive call
}

// With onlyAnnotated=true and annotation:
// @tail-recursion
function sum(arr, index = 0, acc = 0) {
if (index >= arr.length) return acc;
return sum(arr, index + 1, acc + arr[index]);
}
`

After optimization (conceptually):
`javascript
function factorial(n, acc = 1) {
while (true) {
if (n <= 1) return acc;

let _n = n - 1;
let _acc = n * acc;
n = _n;
acc = _acc;
continue;
}
}
`

How It Works

This plugin wraps the js-tail-recursion-opt-plugin with a rSpeedy-compatible adapter using unplugin. During the build process:

1. Detects JavaScript/TypeScript files based on include/exclude patterns
2. Applies Babel transformation with tail recursion optimization
3. Maintains source maps for debugging compatibility
4. Outputs optimized code without runtime overhead

Benefits

- Performance: Eliminate stack overflow crashes
- Compatibility: Works seamlessly with Lynx framework
- Transparency: No code changes required (unless using onlyAnnotated`)
- Debugging: Full source map support maintained
- Flexibility: Configurable optimization behavior

Related Packages

- js-tail-recursion-opt-plugin - Core Babel plugin
- js-tail-recursion-opt-vite-plugin - Vite plugin
- js-tail-recursion-opt-webpack-plugin - Webpack plugin

License

MIT