tessl/npm-ts-node

TypeScript execution environment and REPL for Node.js with source map support

—

Pending

Overview

Eval results

Files

REPL Environment

Name: tessl/npm-ts-node
Author: tessl

Interactive TypeScript REPL with evaluation context management and experimental top-level await support for development and debugging workflows.

Capabilities

Create REPL Service

Creates an interactive TypeScript REPL instance with custom evaluation capabilities.

/**
 * Create a ts-node REPL instance
 * @param options - Configuration options for the REPL
 * @returns ReplService instance for interactive TypeScript evaluation
 */
function createRepl(options?: CreateReplOptions): ReplService;

interface CreateReplOptions {
  /** Service instance to use for compilation */
  service?: Service;
  /** REPL state management */
  state?: EvalState;
  /** Compile function override */
  compile?: (code: string, fileName: string, lineOffset?: number) => string;
  /** Evaluation function override */
  evalFile?: (code: string, fileName: string) => any;
  /** Node.js eval function override */
  nodeEval?: (code: string, filename: string) => any;
}

Usage Examples:

import { createRepl } from "ts-node";

// Create basic REPL
const repl = createRepl();
repl.start();

// Create REPL with custom service
import { create } from "ts-node";
const service = create({ transpileOnly: true });
const customRepl = createRepl({ service });
customRepl.start();

REPL Service Interface

Main interface for interactive TypeScript evaluation and REPL management.

interface ReplService {
  /**
   * Evaluate TypeScript code in REPL context
   * @param code - TypeScript code to evaluate
   * @param context - Evaluation context object
   * @returns Evaluation result
   */
  evalCode(code: string, context: object): any;
  
  /**
   * Start the interactive REPL session
   */
  start(): void;
  
  /**
   * Node.js eval compatibility function
   * @param code - Code to evaluate
   * @param context - Evaluation context
   * @param filename - Source filename for error reporting
   * @param callback - Result callback function
   */
  nodeEval(code: string, context: object, filename: string, callback: Function): void;
  
  /**
   * Set the REPL evaluation context
   * @param context - Object containing variables available in REPL
   */
  setContext(context: object): void;
  
  /**
   * Reset the REPL state and clear evaluation history
   */
  resetState(): void;
}

Usage Examples:

import { createRepl } from "ts-node";

const repl = createRepl();

// Set context variables
repl.setContext({
  myVariable: 42,
  myFunction: (x: number) => x * 2
});

// Evaluate TypeScript code
const result = repl.evalCode('myFunction(myVariable)', {});
console.log(result); // 84

// Start interactive session
repl.start();

REPL State Management

State management for virtual files and evaluation context in the REPL environment.

class EvalState {
  /** Current evaluation input */
  input: string = '';
  /** Compiled output */
  output: string = '';
  /** Current evaluation version */
  version: number = 0;
  /** File system state tracking */
  files: Map<string, string> = new Map();
  
  constructor();
  
  /**
   * Reset state to initial conditions
   */
  reset(): void;
  
  /**
   * Update input and increment version
   * @param input - New input code
   */
  updateInput(input: string): void;
}

/**
 * Create evaluation-aware file system host
 * @param state - EvalState instance to track virtual files
 * @param composeWith - Optional host to compose with
 * @returns Host functions aware of virtual files
 */
function createEvalAwarePartialHost(
  state: EvalState, 
  composeWith?: EvalAwarePartialHost
): EvalAwarePartialHost;

interface EvalAwarePartialHost {
  fileExists(fileName: string): boolean;
  readFile(fileName: string): string | undefined;
  getDirectories?(path: string): string[];
}

Usage Examples:

import { createRepl, EvalState, createEvalAwarePartialHost } from "ts-node";

// Create custom REPL with state management
const state = new EvalState();
const host = createEvalAwarePartialHost(state);

const repl = createRepl({
  state,
  evalFile: (code, fileName) => {
    // Custom evaluation logic
    state.updateInput(code);
    return eval(code);
  }
});

// Track evaluation history
console.log(`Evaluation version: ${state.version}`);
console.log(`Current input: ${state.input}`);

REPL Constants

Predefined constants for REPL filename handling and context management.

/** Virtual filename for REPL evaluations */
const REPL_FILENAME: "[eval].ts";

/** Virtual name for REPL context */  
const REPL_NAME: "[eval]";

/** Virtual filename for stdin input */
const STDIN_FILENAME: "[stdin].ts";

/** Virtual name for stdin context */
const STDIN_NAME: "[stdin]";

/** Virtual filename for eval context */
const EVAL_FILENAME: "[eval].ts";

/** Virtual name for eval context */
const EVAL_NAME: "[eval]";

Context Setup

Utility functions for setting up REPL evaluation contexts.

/**
 * Setup context for REPL evaluation
 * @param context - Context object to populate
 * @param module - Module instance for require/import context
 * @param filenameAndDirname - Type of filename context to create
 */
function setupContext(
  context: any, 
  module: NodeJS.Module, 
  filenameAndDirname: 'eval' | 'stdin' | null
): void;

Usage Examples:

import { createRepl, setupContext, REPL_FILENAME } from "ts-node";
import { Module } from "module";

const repl = createRepl();

// Setup custom context
const context = {};
const module = new Module(REPL_FILENAME);
setupContext(context, module, 'eval');

// Now context has __filename, __dirname, require, etc.
console.log(context.__filename); // "[eval].ts"

Advanced REPL Usage

Top-level Await Support

import { createRepl } from "ts-node";

// Create REPL with experimental await support
const repl = createRepl({
  service: create({
    experimentalReplAwait: true,
    compilerOptions: {
      target: "es2018", // Required for top-level await
    }
  })
});

// Now you can use await in REPL
// > const data = await fetch('https://api.example.com');
// > console.log(data);

Custom Evaluation Logic

import { createRepl, EvalState } from "ts-node";

const state = new EvalState();

const repl = createRepl({
  state,
  evalFile: (code: string, fileName: string) => {
    console.log(`Evaluating: ${code}`);
    
    // Add custom globals
    const globals = {
      console,
      process,
      Buffer,
      // Add your custom utilities
      helper: (x: any) => JSON.stringify(x, null, 2)
    };
    
    // Create evaluation context
    const context = { ...globals };
    return eval(`(function() { ${code} }).call(this)`);
  }
});

repl.start();

Integration with Testing

import { createRepl } from "ts-node";
import { create } from "ts-node";

// Create REPL for testing TypeScript code
const testService = create({
  transpileOnly: true,
  compilerOptions: {
    target: "es2020",
    types: ["node", "jest"] // Include test type definitions
  }
});

const testRepl = createRepl({ service: testService });

// Set testing context
testRepl.setContext({
  describe: global.describe,
  it: global.it,
  expect: global.expect,
  beforeEach: global.beforeEach,
  afterEach: global.afterEach
});

testRepl.start();

Install with Tessl CLI