🛠️ JScriptor — Lightweight Typed Superset for JavaScript

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

---

✨ Features

• 🔍 Type Inference: Automatic type detection using Hindley-Milner type system
• 🧠 Polymorphic Functions: Supports functions that work with multiple types
• 📦 Zero Configuration: Works out of the box with sensible defaults
• 💡 Clear Error Reporting: Detailed type error messages with file locations
• ⚙️ Configurable: Customize type checking behavior via jscriptor.config.js
• 🚀 Fast: Lightweight implementation with minimal overhead
• 🔧 CLI Tools: Command-line interface for easy integration

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

---

📦 Installation

npm install --save-dev jscriptor

---

⚡ Quick Start

1. Create your program:

// myProgram.jsconstdouble=(x)=>{returnx+x;};constnum=5;conststr="hello";constdoubledNum=double(num);constmixed=double(num)+double(str);// ❌ Type error

1. Initialize configuration (optional):

jscriptor init

1. Add to package.json scripts:

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

1. Run type checking:

# Check all files based on config
npm run typecheck
# Check a specific file
npm run typecheck:file src/app.js

---

📦 NPM Registry Example

We've created a complete example project that demonstrates using JScriptor from the npm registry:

Quick Setup

# Clone the example
git clone https://github.com/Hareesh108/jscriptor.git
cd jscriptor/npm-example
# Install JScriptor from npm registry
npm install --save-dev jscriptor
# Initialize configuration
npm run init
# Run type checking
npm run typecheck

Example Project Structure

npm-example/
├── package.json # Dependencies and scripts
├── jscriptor.config.js # JScriptor configuration
├── src/
│ ├── simple-valid.js # Valid code (no errors)
│ ├── simple-errors.js # Code with type errors
│ └── utils.js # Utility functions
└── README.md # Example documentation

Available Scripts

• npm run typecheck - Check all files based on config
• npm run typecheck:file - Check a specific file
• npm run init - Initialize JScriptor configuration

Test Results

The example demonstrates:

• ✅ Valid code: simple-valid.js passes type checking
• ❌ Type errors: simple-errors.js shows clear error messages
• 🔧 Configuration: Customizable via jscriptor.config.js

---

🖥️ Example Output

JScriptor provides clear, detailed error messages:

📄 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

---

🧪 More Examples

✅ Valid Code (No Type Errors)

// Function with type inferenceconstidentity=(x)=>{returnx;};constresult=identity(42);// ✅ Number type inferred// Binary operations with matching typesconstsum=5+10;// ✅ Number + Numberconstmessage="Hello"+" World";// ✅ String + String// Conditional expressionsconstmax=a>b ? a : b;// ✅ Boolean condition

❌ Type Errors

// Type mismatch in binary operationconstbadMath=5+"hello";// ❌ Number + String// Wrong argument type for functionconstadd=(x,y)=>{returnx+y;};constres=add(5,"hello");// ❌ String passed to function expecting Number// Non-boolean condition in ternaryconstnum=5;constresult=num ? "yes" : "no";// ❌ Number used as condition

---

🛠 How It Works

• compile → Parses JavaScript into an AST
• typeCheck → Infers and validates types
• nameCheck → Checks naming and scope rules

---

🖥️ CLI Commands

JScriptor provides a comprehensive command-line interface:

# Initialize a new project with default configuration
jscriptor init
# Type check a single file
jscriptor check src/app.js
# Type check all files based on jscriptor.config.js
jscriptor check-all
# Show help and usage information
jscriptor help

Command Details

• 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

---

⚙️ 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-checkinclude: ["src/**/*.js","lib/**/*.js"],// Files to exclude from type checkingexclude: ["node_modules/**/*","dist/**/*","build/**/*","**/*.test.js","**/*.spec.js"],// Output directory for compiled files (optional)outDir: null,// Whether to watch for file changeswatch: false,// Strict mode settingsstrict: {// Require explicit type annotationsexplicitTypes: false,// Check for unused variablesunusedVars: false,// Check for unreachable codeunreachableCode: false,},// Type checking optionstypeCheck: {// Whether to infer types from usageinferTypes: true,// Whether to check function return typescheckReturnTypes: true,// Whether to check parameter typescheckParameterTypes: true,},// Compiler optionscompiler: {// Whether to preserve commentspreserveComments: true,// Whether to generate source mapssourceMaps: false,// Target JavaScript versiontarget: "es2020",}};

Configuration Sections

• 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

---

📋 Roadmap

Current Version (v0.0.6)

• ✅ 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
• 🧪 More comprehensive test coverage
• 📖 Detailed documentation and tutorials

---

🔧 Local Development Setup

If you want to contribute or test JS Scriptor locally instead of installing from npm:

1. Clone the repo

   git clone https://github.com/Hareesh108/jscriptor.git
   cd jscriptor

2. Install dependencies

   npm install

3. Link the CLI locally This makes the jscriptor command available on your system:

   npm link

4. Test it on an example file

   echo'const x = 5; const y = "hi"; const z = x + y;'> examples/test.js
   jscriptor examples/test.js

   ✅ You should see a type error reported for mixing Number and String.

5. Unlink when done If you no longer want the global link:

   npm unlink -g jscriptor

---

🛠 Development Workflow

• Source code lives in src/
• CLI entrypoint → src/cli.js
• Tokenization → src/01-tokenize/
• Parsing → src/02-parse/
• Type checking → src/03-typecheck/
• Compiler → src/compile.js
• Configuration → src/config.js

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

You can run your local changes directly with:

# Test the CLI
jscriptor check ./src/test/check.js # Test with example project
jscriptor check-all

📜 License

MIT © 2025 Hareesh Bhittam