tessl/npm-edge-runtime

Runtime environment for executing Edge Functions with Web API compatibility and Node.js integration.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

CLI Interface

Name: tessl/npm-edge-runtime
Author: tessl

Command-line interface for executing Edge Functions, starting development servers, and interactive REPL sessions. Provides comprehensive tooling for development, testing, and deployment of Edge Functions.

Capabilities

Basic Command Usage

The edge-runtime command provides multiple execution modes for different development workflows.

# Execute a script file
edge-runtime <script-file>

# Run as HTTP server
edge-runtime --listen <script-file>

# Evaluate inline code
edge-runtime --eval <code>

# Start interactive REPL
edge-runtime

# Display help
edge-runtime --help

Usage Examples:

# Execute an edge function script
edge-runtime my-function.js

# Start development server on default port (3000)
edge-runtime --listen my-function.js

# Start server on specific port and host
edge-runtime --listen --port 8080 --host 0.0.0.0 my-function.js

# Test inline code
edge-runtime --eval "console.log('Hello from Edge Runtime')"

# Start interactive session
edge-runtime

Command-Line Flags

Complete set of command-line options for configuring runtime behavior.

--eval, -e <code>
    Evaluate an input script inline instead of reading from file

--help
    Display help message with all available options

--listen, -l
    Run the script as an HTTP server instead of one-time execution

--port, -p <number>
    Specify the port for HTTP server (default: 3000)
    Server will automatically try next port if specified port is in use

--host, -h <string>
    Specify the host/interface for HTTP server (default: 127.0.0.1)

--repl
    Start an interactive REPL session
    Note: REPL starts automatically when no script is provided

Flag Examples:

# Evaluate code directly
edge-runtime -e "addEventListener('fetch', e => e.respondWith(new Response('OK')))"

# Server with custom port
edge-runtime -l -p 8080 function.js

# Server on all interfaces
edge-runtime --listen --host 0.0.0.0 --port 3000 function.js

# Get help
edge-runtime --help

Script Execution Mode

Default mode for executing Edge Function scripts with one-time evaluation.

Usage Examples:

edge-runtime function.js

// function.js
addEventListener('fetch', event => {
  const response = new Response('Hello World', {
    headers: { 'content-type': 'text/plain' }
  });
  event.respondWith(response);
});

console.log('Edge function loaded successfully');

The script is executed once and the process exits. This mode is useful for:

Testing edge function syntax
Running initialization scripts
Validating edge function logic

Server Mode

HTTP server mode for development and testing with live request handling.

edge-runtime --listen [--port <port>] [--host <host>] <script-file>

Usage Examples:

# Start server on default port (3000)
edge-runtime --listen api.js

# Custom port and host
edge-runtime --listen --port 8080 --host 0.0.0.0 api.js

# Server automatically finds available port if specified port is busy
edge-runtime --listen --port 3000 api.js  # Will use 3001 if 3000 is busy

// api.js
addEventListener('fetch', event => {
  const url = new URL(event.request.url);
  
  if (url.pathname === '/api/hello') {
    event.respondWith(Response.json({ message: 'Hello World' }));
  } else if (url.pathname === '/api/time') {
    event.respondWith(Response.json({ 
      timestamp: Date.now(),
      iso: new Date().toISOString()
    }));
  } else {
    event.respondWith(new Response('Not Found', { status: 404 }));
  }
});

Server mode features:

Automatic port conflict resolution
Request logging with timing information
Graceful shutdown on SIGTERM/SIGINT
Hot reload capabilities (script is loaded once)

Inline Evaluation Mode

Execute Edge Function code directly from command line without creating files.

edge-runtime --eval <javascript-code>
edge-runtime -e <javascript-code>

Usage Examples:

# Simple response
edge-runtime -e "console.log('Runtime version:', EdgeRuntime)"

# Fetch event handler
edge-runtime -e "
addEventListener('fetch', event => {
  event.respondWith(new Response('Inline function working!'));
});
console.log('Inline function registered');
"

# JSON API response
edge-runtime -e "
addEventListener('fetch', event => {
  const data = { status: 'ok', timestamp: Date.now() };
  event.respondWith(Response.json(data));
});
"

Inline evaluation is useful for:

Quick testing and prototyping
CI/CD pipeline validation
Educational examples and demos

Interactive REPL Mode

Interactive Read-Eval-Print Loop for exploring Edge Runtime capabilities and testing code snippets.

edge-runtime
# or explicitly:
edge-runtime --repl

REPL Usage Examples:

// REPL starts with Edge Runtime context
ƒ => console.log('Hello from REPL')
Hello from REPL

// All Edge Runtime globals are available
ƒ => fetch
[Function: fetch]

ƒ => new Response('test').text()
Promise { <pending> }

// Define and test functions
ƒ => const myHandler = (event) => {
  event.respondWith(new Response('REPL handler'));
}

ƒ => addEventListener('fetch', myHandler)

// Test Web APIs
ƒ => new URL('https://example.com/path').pathname
'/path'

ƒ => crypto.randomUUID()
'a1b2c3d4-e5f6-7890-abcd-ef1234567890'

// Exit REPL
ƒ => .exit

REPL features:

Full Edge Runtime context with all Web APIs
Command history saved to ~/.edge_runtime_repl_history
Tab completion for available globals
Formatted output with syntax highlighting
Standard REPL commands (.exit, .help, etc.)

Environment Variables

Environment variables that affect CLI behavior.

EDGE_RUNTIME_LOGGING=<boolean>
    Enable or disable CLI logging output
    Default: true
    Example: EDGE_RUNTIME_LOGGING=false edge-runtime --listen api.js

Usage Examples:

# Disable logging
EDGE_RUNTIME_LOGGING=false edge-runtime --listen function.js

# Enable logging (default)
EDGE_RUNTIME_LOGGING=true edge-runtime --listen function.js

Error Handling and Debugging

The CLI provides comprehensive error reporting and debugging information.

Error Types:

# Syntax errors in edge function code
edge-runtime invalid-syntax.js
# Output: SyntaxError with line numbers and context

# Runtime errors during execution
edge-runtime runtime-error.js
# Output: Runtime error with stack trace

# Server startup errors
edge-runtime --listen --port 80 function.js
# Output: Permission error for privileged port

# File not found errors
edge-runtime nonexistent.js
# Output: Clear file not found message

Debug Output Examples:

# Server mode includes request logging
edge-runtime --listen function.js
# Output:
# ƒ 127.0.0.1 GET / → 200 OK in 2ms
# ƒ 127.0.0.1 POST /api/data → 201 Created in 15ms

Process Management

The CLI handles process lifecycle and signal management properly.

Signal Handling:

SIGTERM/SIGINT: Graceful shutdown with pending request completion
SIGUSR1: Debugging support (Node.js inspector)
Process exit codes: 0 for success, 1 for errors

Usage Examples:

# Start server in background
edge-runtime --listen function.js &
SERVER_PID=$!

# Graceful shutdown
kill -TERM $SERVER_PID

# Force shutdown if needed
kill -KILL $SERVER_PID

Install with Tessl CLI