JScriptor - Lightweight Typed Superset for JavaScript

✨ Features

JScriptor is a lightweight, typed superset of JavaScript that catches type errors early and keeps your codebase clean and maintainable—without any heavy setup.

🔍

Type Inference

Automatic type detection using Hindley-Milner type system with advanced unification algorithms.

🧠

Polymorphic Functions

Supports functions that work with multiple types, enabling flexible and reusable code.

📦

Zero Configuration

Works out of the box with sensible defaults. No complex setup required.

💡

Clear Error Reporting

Detailed type error messages with file locations and helpful hints for faster debugging.

⚙️

Configurable

Customize type checking behavior via jscriptor.config.js for your project needs.

🚀

Fast & Lightweight

Minimal overhead with optimized performance for large codebases.

Supported JavaScript Features

Variable declarations (const, let)
Arrow functions and function calls
Binary expressions (+, -, *, /, ==, !=, etc.)
Conditional expressions (ternary operator)
Array and object literals
String, number, and boolean literals
Return statements
Block statements with scope management

⚡ Quick Start

1. Initialize Configuration

jscriptor init

This creates a jscriptor.config.js file with sensible defaults.

2. Add to package.json

{
  "scripts": {
    "typecheck": "jscriptor check-all",
    "typecheck:file": "jscriptor check"
  }
}

3. Run Type Checking

# Check all files based on config
npm run typecheck

# Check a specific file
npm run typecheck:file src/app.js

CLI Commands

`jscriptor init`

Creates a jscriptor.config.js file with sensible defaults

`jscriptor check <file>`

Type checks a single JavaScript file

`jscriptor check-all`

Type checks all files matching patterns in your config

`jscriptor help`

Displays usage information and available commands

🧪 Examples

✅ Valid Code (No Type Errors)

// Function with type inference
const identity = (x) => { return x; };
const result = identity(42); // ✅ Number type inferred

// Binary operations with matching types
const sum = 5 + 10; // ✅ Number + Number
const message = "Hello" + " World"; // ✅ String + String

// Conditional expressions
const max = a > b ? a : b; // ✅ Boolean condition

❌ Type Errors

// Type mismatch in binary operation
const badMath = 5 + "hello"; // ❌ Number + String

// Wrong argument type for function
const add = (x, y) => { return x + y; };
const res = add(5, "hello"); // ❌ String passed to function expecting Number

// Non-boolean condition in ternary
const num = 5;
const result = num ? "yes" : "no"; // ❌ Number used as condition

🖥️ Example Output

📄 Checking src/simple-errors.js...

❌ 1 error(s) found

1. [E_TERNARY_TEST_NOT_BOOL] Type mismatch in ternary: condition must be Boolean, got Number
   at src/simple-errors.js:15:20

 13 | 
 14 | // Type error: ternary with non-boolean condition
 15 | const badTernary = num ? "yes" : "no";
    |                    ^
 16 | 
 17 | console.log("This file has type errors!");
   💡 Hint: The condition in a ternary operator must evaluate to a boolean

📊 Summary: Found 1 type error(s) in src/simple-errors.js

⚙️ Configuration

JScriptor uses a jscriptor.config.js file to configure type checking behavior. Run jscriptor init to create a default configuration file.

Configuration Options

module.exports = {
  // Entry points - files or directories to type-check
  include: [
    "src/**/*.js",
    "lib/**/*.js"
  ],
  
  // Files to exclude from type checking
  exclude: [
    "node_modules/**/*",
    "dist/**/*",
    "build/**/*",
    "**/*.test.js",
    "**/*.spec.js"
  ],
  
  // Output directory for compiled files (optional)
  outDir: null,
  
  // Whether to watch for file changes
  watch: false,
  
  // Strict mode settings
  strict: {
    // Require explicit type annotations
    explicitTypes: false,
    // Check for unused variables
    unusedVars: false,
    // Check for unreachable code
    unreachableCode: false,
  },
  
  // Type checking options
  typeCheck: {
    // Whether to infer types from usage
    inferTypes: true,
    // Whether to check function return types
    checkReturnTypes: true,
    // Whether to check parameter types
    checkParameterTypes: true,
  },
  
  // Compiler options
  compiler: {
    // Whether to preserve comments
    preserveComments: true,
    // Whether to generate source maps
    sourceMaps: false,
    // Target JavaScript version
    target: "es2020",
  }
};

`include`

Glob patterns for files to type check

`exclude`

Glob patterns for files to skip

`strict`

Strict mode settings for additional checks

`typeCheck`

Core type checking behavior

`compiler`

Compilation and output options

🛠 How It Works

🔤 Tokenize

Parses JavaScript into tokens using lexical analysis

🌳 Parse

Builds an Abstract Syntax Tree (AST) from tokens

🔍 Type Check

Infers and validates types using Hindley-Milner system

📝 Report

Generates clear error messages with file locations

🔧 Development

Want to contribute or test JScriptor locally? Here's how to set up the development environment.

Local Development Setup

# Clone the repository
git clone https://github.com/Hareesh108/jscriptor.git
cd jscriptor

# Install dependencies
npm install

# Link the CLI locally
npm link

# Test on an example file
echo 'const x = 5; const y = "hi"; const z = x + y;' > test.js
jscriptor test.js

# Unlink when done
npm unlink -g jscriptor

Project Structure

src/
├── cli.js                 # Command-line interface
├── compile.js             # Main compilation entry point
├── config.js              # Configuration loading and processing
├── 01-tokenize/           # Lexical analysis
│   ├── tokenize.js        # Tokenizer implementation
│   └── utils.js           # Token utilities
├── 02-parse/              # Syntax analysis
│   └── parse.js           # Parser implementation
├── 03-typecheck/          # Type checking and inference
│   ├── typecheck.js       # Main type checker
│   ├── db.js              # Type database
│   ├── errors.js          # Error reporting
│   ├── scope.js           # Scope management
│   ├── unification.js     # Type unification
│   ├── type-utils.js      # Type utilities
│   ├── utils.js           # General utilities
│   └── visitors/          # AST visitors
│       ├── index.js       # Visitor dispatcher
│       ├── declarations.js # Declaration visitors
│       ├── expressions.js  # Expression visitors
│       ├── functions.js    # Function visitors
│       ├── identifiers.js  # Identifier visitors
│       └── literals.js     # Literal visitors
└── test/                  # Test files
    ├── check.js           # Test runner
    ├── test.js            # Test utilities
    └── typecheck.spec.js  # Type checker tests

📋 Roadmap

Current Version (v0.0.5)

Basic type inference and checking
CLI interface with configuration support
Error reporting with file locations
Support for common JavaScript constructs

Upcoming Features

Enhanced CLI output with syntax highlighting
Plugin system for custom type rules
VS Code extension for real-time type checking
Type annotations support (optional)
Watch mode for continuous type checking
Performance optimizations for large codebases