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

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

Usage

With Lynx rSpeedy

Configure in your lynx.config.mjs:

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
    })
  ],
});

Configuration Options

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

Example

Before optimization:

// 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):

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