or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

ast-nodes.mdcli-tools.mdcompilation.mdexecution.mdindex.mdrepl-interactive.mdutilities.md
tile.json

execution.mddocs/

Code Execution

Direct execution of CoffeeScript code in various contexts including Node.js main module and sandboxed VM environments.

Capabilities

Run Function

Compiles and executes CoffeeScript code in the Node.js main module context, making it suitable for running complete programs.

/**
 * Compiles and executes CoffeeScript code in Node.js main module context
 * @param code - CoffeeScript source code to execute
 * @param options - Execution options object
 * @returns Return value from executed code
 */
function run(code, options);

Parameters:

  • code (string): CoffeeScript source code to compile and execute
  • options (object, optional): Execution configuration options

Returns:

  • Any: Return value from the executed CoffeeScript code

Usage Examples:

const CoffeeScript = require('coffee-script');

// Execute simple CoffeeScript
CoffeeScript.run(`
  console.log "Hello from CoffeeScript!"
  x = 42
  console.log "The answer is #{x}"
`);

// Execute with filename for better error reporting
CoffeeScript.run(`
  fs = require 'fs'
  content = fs.readFileSync 'package.json', 'utf8'
  data = JSON.parse content
  console.log "Package name: #{data.name}"
`, {
  filename: 'script.coffee'
});

// Execute and capture return value
const result = CoffeeScript.run(`
  square = (x) -> x * x
  result = square 7
  result  # This will be returned
`);
console.log(result); // 49

Eval Function

Evaluates CoffeeScript code in a sandboxed VM context, providing isolation and custom environments.

/**
 * Evaluates CoffeeScript code in a sandboxed VM context
 * @param code - CoffeeScript source code to evaluate
 * @param options - Evaluation options object
 * @returns Return value from evaluated code
 */
function eval(code, options);

Parameters:

  • code (string): CoffeeScript source code to evaluate
  • options (object, optional): Evaluation configuration options

Returns:

  • Any: Return value from the evaluated CoffeeScript code

Access Pattern:

const CoffeeScript = require('coffee-script');
// Note: eval is a reserved word, so use bracket notation for direct access
const evalFunction = CoffeeScript["eval"];

Usage Examples:

const CoffeeScript = require('coffee-script');

// Basic evaluation
const result = CoffeeScript.eval('6 * 7');
console.log(result); // 42

// Evaluation with custom sandbox
const customResult = CoffeeScript.eval(`
  greeting = "Hello"
  name = customName
  "#{greeting}, #{name}!"
`, {
  sandbox: {
    customName: 'Alice'
  }
});
console.log(customResult); // "Hello, Alice!"

// Evaluation with filename for debugging
const mathResult = CoffeeScript.eval(`
  add = (a, b) -> a + b
  multiply = (a, b) -> a * b
  
  x = 10
  y = 5
  result = add(multiply(x, 2), y)
  result
`, {
  filename: 'math-operations.coffee'
});
console.log(mathResult); // 25

Registration Function

Returns the registration module that enables Node.js to require CoffeeScript files directly.

/**
 * Returns the register module for enabling .coffee file requires
 * @returns Register module object
 */
function register();

Usage Examples:

const CoffeeScript = require('coffee-script');

// Enable .coffee file requiring
CoffeeScript.register();

// Now you can require .coffee files directly
const myModule = require('./my-script.coffee');

// Alternative: Use the register entry point
require('coffee-script/register');
const anotherModule = require('./another-script.coffee');

Execution Options

Run Options

interface RunOptions {
  /** Filename for error reporting and module resolution */
  filename?: string;
}

Eval Options

interface EvalOptions {
  /** Custom sandbox object with variables available to evaluated code */
  sandbox?: object;
  
  /** Filename for error reporting and debugging */
  filename?: string;
  
  /** Module name for the evaluation context */
  modulename?: string;
}

Execution Context Details

Run Context

The run function executes code in the main Node.js module context, which means:

  • Code has access to all Node.js built-in modules
  • Variables become global unless declared with proper scoping
  • require() works normally for loading dependencies
  • module.exports can be used to export values
  • Code runs with the same privileges as the main process

Eval Context

The eval function runs code in a sandboxed VM context, which provides:

  • Isolated execution environment
  • Custom variable injection via sandbox option
  • Limited access to Node.js APIs (unless explicitly provided)
  • Safe evaluation of untrusted code
  • Custom require implementation if needed

Sandbox Example:

const CoffeeScript = require('coffee-script');

const result = CoffeeScript.eval(`
  # Access sandbox variables
  total = 0
  total += item for item in items
  
  # Use provided utilities
  message = utils.formatMessage "Total: #{total}"
  
  {
    total: total
    message: message
  }
`, {
  sandbox: {
    items: [1, 2, 3, 4, 5],
    utils: {
      formatMessage: (msg) => `[INFO] ${msg}`
    }
  }
});

console.log(result);
// { total: 15, message: '[INFO] Total: 15' }

Error Handling

Both execution functions provide enhanced error reporting with CoffeeScript-specific context:

const CoffeeScript = require('coffee-script');

try {
  CoffeeScript.run(`
    undefinedFunction()
  `, {
    filename: 'test.coffee'
  });
} catch (error) {
  console.log(error.message);
  console.log(error.location); // CoffeeScript source location
}