rspade_system/app/RSpade/Core/JavaScript/CLAUDE.md

JavaScript Core Systems - RPC Server Architecture

Overview

JavaScript parsing and transformation use long-running Node.js RPC servers via Unix sockets to avoid spawning 1000+ Node processes during builds.

JS Parser - RPC Server

Components

• Js_Parser.php - PHP client, manages parser server lifecycle
• js-parser-server.js - Node.js RPC server, processes batch parse requests
• js-parser.js - Legacy single-file parser (kept for compatibility)

Server Lifecycle

1. Lazy start: Server spawns on first JS file parse during manifest build
2. Startup: Checks for stale socket, force-kills if found, starts fresh server
3. Wait: Polls socket with ping (50ms intervals, 10s max), fatal error if timeout
4. Usage: All JS parsing during build goes through RPC (batched when possible)
5. Shutdown: Graceful shutdown on manifest build completion (registered shutdown handler)

Socket

• Path: storage/rsx-tmp/js-parser-server.sock
• Protocol: Line-delimited JSON over Unix domain socket

RPC Methods

• ping → "pong" - Health check
• parse → {file: result, ...} - Batch parse multiple files
• shutdown → Graceful server termination

PHP API

Js_Parser::start_rpc_server();        // Lazy init, auto-called
Js_Parser::stop_rpc_server($force);   // Clean shutdown
Js_Parser::parse_via_rpc($files);     // Batch parse (future)

JS Transformer (Babel) - RPC Server

Components

• Js_Transformer.php - PHP client, manages transformer server lifecycle
• js-transformer-server.js - Node.js RPC server, processes batch Babel transformations
• js-transformer.js - Legacy single-file transformer (kept for compatibility)

Server Lifecycle

1. Lazy start: Server spawns on first JS transformation during bundle compilation
2. Startup: Checks for stale socket, force-kills if found, starts fresh server
3. Wait: Polls socket with ping (50ms intervals, 10s max), fatal error if timeout
4. Usage: All JS transformations during bundle builds go through RPC
5. Shutdown: Graceful shutdown when bundle compilation completes (registered shutdown handler)

Socket

• Path: storage/rsx-tmp/js-transformer-server.sock
• Protocol: Line-delimited JSON over Unix domain socket

RPC Methods

• ping → "pong" - Health check
• transform → {file: {status, result, hash}, ...} - Batch transform multiple files
• shutdown → Graceful server termination

PHP API

Js_Transformer::start_rpc_server();        // Lazy init, auto-called
Js_Transformer::stop_rpc_server($force);   // Clean shutdown
Js_Transformer::_transform_via_rpc(...);   // Internal RPC transformation

Transformation Details

• Preprocesses @decorator on standalone functions
• Applies Babel transformations: decorators, class properties, optional chaining, nullish coalescing
• Prefixes generated helper functions with file hash to prevent namespace collisions
• Uses target presets: modern, es6, es5
• Generates inline source maps for debugging

Common RPC Pattern

Force Parameter

stop_rpc_server($force = false):

• false (default): Send shutdown command, return immediately
• true: Send shutdown + wait + SIGTERM if needed (used for stale server cleanup)

Cache Integration

Cache checked before RPC call - only uncached files sent to server for processing.

Error Handling

Server failure → fatal error (no fallback). Server must start or build/compilation fails.

Performance Impact

Before RPC: N Node.js process spawns (where N = number of files needing processing) After RPC: Single persistent Node.js process per server type (~1-2s startup overhead)

Future: Other RPC Servers

This pattern is reusable for other expensive Node operations. See implementation guide in project summary.