SomonScript

Learn to program in your native language — a first step towards JavaScript

▶ Try SomonScript in your browser — nothing to install; a saved copy of the page works without the internet.

SomonScript is a programming language for learning to program in Tajik. Its keywords and built-in names are Tajik words written in Cyrillic, and every program compiles to JavaScript, which you can look at side by side: what you learn carries over to JavaScript, one of the most widely used languages. The compiler is actively developed (version 0.4.0) and suitable for evaluation, teaching pilots and experiments; please report the problems you find.

🗣️ Other Languages

• 🇺🇸 English - Main language
• 🇹🇯 Тоҷикӣ - Native language
• 🇷🇺 Русский - Russian language

---

Programming without a language barrier

Learning to program usually means learning English keywords at the same time. SomonScript lets a learner who reads Tajik start with the ideas — values, variables, conditions, loops, functions — written in words they know, and see the same program in JavaScript when they are ready for it. SomonScript is developed in cooperation with LindenTech IT Consulting.

---

✨ Why Choose SomonScript?

🌍 Breaking Language Barriers in Programming

Empowering Native Language Development

SomonScript revolutionizes software development by eliminating the fundamental language barrier that has historically limited programming accessibility. By providing complete Tajik Cyrillic syntax, developers can:

• Think Naturally: Express complex algorithms and logic in their native language patterns
• Reduce Cognitive Load: Eliminate the mental translation layer between concept and code
• Improve Code Comprehension: Write self-documenting code that's immediately readable to Tajik-speaking teams
• Accelerate Learning: New programmers can focus on programming concepts rather than foreign syntax
• Enable Cultural Context: Incorporate domain-specific terminology and cultural nuances directly into code

🔒 Type Checking

The compiler checks types before the program runs, with TypeScript's kinds of types:

• Union and intersection types
• Tuple types with length inference
• Interface inheritance and composition
• Generic type parameters
• Conditional type expressions

⚡ Development Snapshot

• Automated example audit – npm run audit:examples validates the reference programs on every release.
• Extensive test suite – 1220+ tests cover lexing, parsing, type checking, and the CLI. Coverage reports are generated in CI and shared on request.
• Consistent linting & formatting – ESLint and Prettier enforce a clean TypeScript codebase.
• Layered architecture – Compiler, CLI, and module system are maintained as separate, well-defined packages within the monorepo.
• Actively evolving – Suitable for evaluation and pilot projects; please report the gaps you find.

🚀 Developer Experience

# Quick setup and deployment
npm install -g @lindentech/somon-script
echo 'чоп("Салом, ҷаҳон!");' > hello.som
somon run hello.som

🎨 VS Code Extension

Get full IDE support with syntax highlighting, IntelliSense, and code snippets:

• Install from VS Code Marketplace: Search for "SomonScript" or install directly
• Features: Syntax highlighting, type-aware completions, 30+ snippets, real-time diagnostics
• Hover Info: View Tajik keyword documentation with JavaScript equivalents

---

🎯 Language Features

Core Language Highlights

// Variables with type inference
тағ ном = "Дониёр";
собит МАКС_СИННУ_СОЛ: рақам = 120;

// Functions with type annotations
функсия ҳисоб_кардан(а: рақам, б: рақам): рақам {
    бозгашт а + б;
}

Object-Oriented Programming Toolkit

// Classes with inheritance and polymorphism
синф Ҳайвон {
    хосусӣ ном: сатр;

    конструктор(ном: сатр) {
        ин.ном = ном;
    }

    ҷамъиятӣ овоз_додан(): сатр {
        бозгашт "Садои умумӣ";
    }
}

синф Саг мерос Ҳайвон {
    ҷамъиятӣ овоз_додан(): сатр {
        бозгашт "Вақ-вақ!";
    }
}

Advanced Type System Features

// Union types for flexible APIs
тағ маълумот: сатр | рақам | мантиқӣ = "Салом";

// Intersection types for composition
интерфейс Корбар {
    ном: сатр;
    синну_сол: рақам;
}

интерфейс Админ {
    сатҳи_дастрасӣ: рақам;
}

тағ супер_корбар: Корбар & Админ = {
    ном: "Алӣ",
    синну_сол: 30,
    сатҳи_дастрасӣ: 9
};

// Tuple types with precise structure
тағ координата: [рақам, рақам, сатр] = [41.2, 69.1, "Душанбе"];

Modern JavaScript Interop

// Template literals with interpolation
тағ ном = "Аҳмад";
тағ синну = 25;
тағ паём = `Салом, ${ном}! Шумо ${синну} сола доред.`;

// Multiline template literals
тағ матн = `Сатри якум
Сатри дуюм
Сатри сеюм`;

// Async/await for modern web development
ҳамзамон функсия маълумот_гирифтан(url: сатр): Promise<сатр> {
    тағ ҷавоб = интизор fetch(url);
    бозгашт интизор ҷавоб.text();
}

// Modules and imports - Full ES6+ module system
содир функсия ҳисоб_кардан(а: рақам, б: рақам): рақам {
    бозгашт а + б;
}

// Import from other modules
ворид { ҳисоб_кардан } аз "./math";
ворид пешфарз_функсия аз "./utils";
ворид * чун MathUtils аз "./math-utils";

// Dynamic imports for code splitting
ҳамзамон функсия loadModule() {
    собит module = интизор ворид("./dynamic-module");
    бозгашт module.someFunction();
}

// Error handling
кӯшиш {
    тағ натиҷа = тақсим_кардан(10, 0);
} гирифтан (хато) {
    чоп.сабт("Хато рух дод:", хато);
}

Bundling (Module System)

• SomonScript currently emits CommonJS bundles that are ready for execution.

somon bundle src/main.som -o dist/bundle.js

The bundler rewrites internal require() calls to a module map. When compiling SomonScript sources, relative imports may appear as .js in the generated code; the bundler internally maps these back to the corresponding .som modules when necessary.

Enable debugger-friendly builds with:

somon bundle src/main.som -o dist/bundle.js --source-map

Source maps now reference modules relative to the entry directory to avoid leaking absolute paths. Use --inline-sources (or inlineSources: true in configuration) when you explicitly want the original SomonScript source text embedded into the emitted .map file.

Documentation

• Module System guide: docs/module-system.md

Using SomonScript in Builds

SomonScript is a compiler: you compile .som sources to plain JavaScript with the somon CLI or the compile() library API and ship that JavaScript like any other Node.js code. The CLI exits non-zero on compilation errors, so it can gate CI jobs directly.

📖 Details: DEPLOYMENT.md

Module System Overview

SomonScript features a comprehensive module system designed for large-scale applications:

// math.som - Export functions and constants
содир функсия ҷамъ(а: рақам, б: рақам): рақам {
    бозгашт а + б;
}

содир собит ПИ: рақам = 3.14159;

содир пешфарз функсия ҳисобкунак(амал: сатр, а: рақам, б: рақам): рақам {
    // Default export implementation
}

// main.som - Import and use modules
ворид ҳисобкунак, { ҷамъ, ПИ } аз "./math";
ворид { формат } аз "./string-utils";

чоп.сабт(формат("Натиҷа: {0}", ҷамъ(5, 3)));

Module System Features:

• 🔄 Static & Dynamic Imports - ES6+ import/export syntax with dynamic loading
• 📁 Smart Resolution - Node.js-compatible module resolution with .som → .js mapping
• 🔗 Dependency Management - Automatic dependency graph construction and circular dependency detection
• 📦 Bundling Support - CommonJS bundles with optional minification and source maps
• ⚡ Performance Optimized - Module caching and efficient compilation order
• 🛠️ CLI Integration - Built-in commands for bundling, analysis, and dependency resolution

CLI Commands:

# Bundle modules into a single file
somon bundle src/main.som -o dist/app.js --minify

# Analyze module dependencies
somon module-info src/main.som --graph --stats --circular

# Resolve module paths
somon resolve "./utils" --from src/main.som

---

📊 Quality Checks

The project ships with automated checks that you can run locally:

Check	Command	Purpose
Example audit	npm run audit:examples	Ensures reference programs continue to compile/run
Test suite	npm test	Exercises compiler, CLI, and runtime behaviour
Linting & formatting	npm run lint	Verifies TypeScript style and static analysis rules
TypeScript build	npm run build	Compiles sources to JavaScript before publishing

---

🚀 Quick Start

Installation

Choose from multiple package registries:

# NPM (recommended for most users)
npm install -g @lindentech/somon-script

# JSR (recommended for TypeScript projects)
npx jsr add @lindentechde/somon-script

# Or use in a project
npm install @lindentech/somon-script --save-dev

CLI Multilingual Interface

SomonScript CLI now supports three languages: English, Tajik, and Russian. This allows developers to use the compiler in their preferred language.

Setting the Language

# Use Tajik interface
somon --lang tj compile app.som

# Use Russian interface
somon --lang ru compile app.som

# Use English interface (default)
somon --lang en compile app.som

With --lang tj or --lang ru, the compiler explains its errors for learners in that language: the line of code with a caret under the place, and a hint («Шояд агар-ро дар назар доштед?»). See Diagnostics in the learner's language.

Automatic Language Detection

The CLI automatically detects your system language from environment variables:

# Set preferred language via environment
export SOMON_LANG=tj  # Tajik
export SOMON_LANG=ru  # Russian
export SOMON_LANG=en  # English

# Or use system locale
export LANG=tg_TJ.UTF-8  # Automatically uses Tajik
export LANG=ru_RU.UTF-8  # Automatically uses Russian

Available Commands in Each Language

English	Tajik (Тоҷикӣ)	Russian (Русский)
somon compile app.som somon run app.som somon init my-project somon bundle src/main.som somon module-info src/main.som somon resolve "./utils"	somon --lang tj компайл app.som somon --lang tj иҷро app.som somon --lang tj оғоз лоиҳаи-ман somon --lang tj баста src/main.som somon --lang tj маълумоти-модул src/main.som somon --lang tj ҳал "./utils"	somon --lang ru компилировать app.som somon --lang ru запустить app.som somon --lang ru инициализация мой-проект somon --lang ru пакет src/main.som somon --lang ru информация-модуля src/main.som somon --lang ru разрешить "./utils"

Your First Program

# Hello World example
echo 'чоп.сабт("Hello, World!");' > hello.som
somon run hello.som

# Business logic with type safety
cat > calculator.som << 'EOF'
функсия ҷамъ(а: рақам, б: рақам): рақам {
    бозгашт а + б;
}

тағ натиҷа = ҷамъ(5, 3);
чоп.сабт("Натиҷа: " + натиҷа);
EOF

somon run calculator.som

Initialize a Project

somon init my-app
cd my-app
npm install
npm run dev

---

📚 CLI Reference

Compilation

# Compile to JavaScript
somon compile app.som

# With options
somon compile app.som --output dist/app.js --source-map --strict

# Compile with minification
somon compile app.som --minify --target es2020

Development

# Compile and run immediately
somon run app.som

# Initialize new project
somon init my-project

# Get help
somon --help
somon compile --help

Module Management

# Bundle modules into single file
somon bundle src/main.som -o dist/bundle.js --minify

# Analyze module dependencies
somon module-info src/main.som --graph --circular --stats

# Resolve module paths
somon resolve "./utils" --from src/main.som

---

🏗️ Architecture

SomonScript is built with modern compiler design principles:

Source Code (.som)
       ↓
   📝 Lexical Analysis
       ↓
   🌳 Syntax Analysis (AST)
       ↓
   🔍 Semantic Analysis & Type Checking
       ↓
   ⚙️ Code Generation
       ↓
   JavaScript Output

Key Components:

• Lexer: Tokenizes Tajik Cyrillic source code
• Parser: Builds Abstract Syntax Tree with error recovery
• Type Checker: Advanced static analysis with inference
• Code Generator: Produces clean, optimized JavaScript
• CLI: Developer-friendly command-line interface
• Module System: Module resolution, cyclic-dependency detection, and a CommonJS bundler

---

🛠️ Development

Prerequisites

• Node.js 20.x, 22.x, 23.x, or 24.x
• npm 8.x or higher
• TypeScript knowledge (for internal development)

Setup

# Clone repository
git clone https://github.com/lindentechde/Somon-Script.git
cd Somon-Script

# Install dependencies
npm install

# Build the compiler
npm run build

# Run tests
npm test

# Run examples
npm run examples

# Development mode (watch for changes)
npm run dev

Testing

# Full test suite
npm test

# With coverage
npm run test:coverage

# Specific test categories
npm run test:unit
npm run test:integration
npm run test:performance
npm run audit:examples

---

� Learning Resources

For Learners and Teachers

• 🎒 Lessons for beginners - 18 lessons in Tajik (in Russian, in English) with tasks that check themselves, and a guide for teachers
• 🎓 Tutorial - Structured learning pathway
• 📋 Examples - Example programs
• 🎯 Quick Reference - Essential syntax guide
• 🩺 Compiler messages in Tajik, Russian and English - what the errors say and their codes
• ⌨️ Reading input - хондан() and хонданиРақам()

For Technical Teams

• 📘 Language Reference - Complete API documentation
• 🔧 How-to Guides - Implementation patterns
• ⚡ Best Practices - Industry-standard coding guidelines

For Development Teams

• 🏛️ Architecture Guide - System design principles
• 🧪 Testing Guide - Quality assurance methodology
• 🤝 Community Participation - Engagement guidelines

Built-in Functions & APIs

• 📖 Console Methods Guide - Complete reference for all чоп.* methods (log, error, warn, info, debug, assert, count, time, table, trace, and more)
  • Тоҷикӣ (Tajik)
  • Русский (Russian)
• 🖨️ Console Output Examples - Simple examples for getting started
• 📊 Advanced Console Usage - Comprehensive guide with all console methods

---

🌍 Professional Support

Technical Services

• 💬 GitHub Discussions - Technical discussions and Q&A
• 🐛 Issues - Bug reports and feature requests

Professional Services

LindenTech IT Consulting offers professional development services:

1. Core Development: Enhance compiler capabilities and performance
2. Documentation: Improve technical documentation and guides
3. Testing: Expand test coverage and quality assurance
4. Integration: Build tooling and IDE support
5. Performance: Optimize compilation and runtime efficiency

📖 Documentation:

• Release Process Guide - How versions are bumped and published to npm and JSR
• CONTRIBUTING.md - Code style, commit messages and tests

---

📄 License

SomonScript is distributed under the MIT License. See the LICENSE file for the full text. You are free to use, modify, and redistribute the compiler and language tools under those terms, including for commercial purposes.

---

� Enterprise Partnership

Developed in Partnership with LindenTech IT Consulting

SomonScript is professionally developed in collaboration with LindenTech IT Consulting, a leading enterprise technology consultancy specializing in innovative software solutions and digital transformation.

LindenTech's Expertise:

• Enterprise Architecture - Scalable system design and implementation
• Custom Development - Tailored solutions for complex business requirements
• Technology Innovation - Cutting-edge programming language development
• Digital Transformation - Modern tooling and development methodologies

This strategic partnership ensures SomonScript meets enterprise-grade standards for reliability, performance, and maintainability, backed by professional consulting services and ongoing technical support.

Learn more: lindentech.de

---

�🌟 Technical Excellence

Built on proven software engineering principles and modern compiler technology:

• Advanced Type System - Based on established type theory research
• Clean Architecture - Modular design following SOLID principles
• Industry Standards - Compatible with existing JavaScript ecosystem
• Performance Optimized - Efficient compilation and runtime execution

Technology Stack

• TypeScript core implementation for reliability
• Node.js ecosystem compatibility
• Modern JavaScript target compilation
• Comprehensive testing framework

SomonScript - Learn to program in Tajik, then in JavaScript

GitHub • Documentation • Support