Skip to content

Introduction to SuperJS

SuperJS (SJS) is a strict, type-safe superset of JavaScript that follows the ECMAScript standard — every valid .js file is also valid .sjs, with every modern JS feature (ES5 through ES2025) type-checked. It adds a sound, Go-inspired type system designed for clarity and safety. It compiles to clean JavaScript today; native binaries and WebAssembly are on the roadmap (see v2.0) — one source, every target.

SuperJS is not TypeScript. It deliberately discards the parts of TypeScript that make reasoning about types difficult (any, mapped types, conditional types, infer) and replaces them with simpler, safer constructs: sum types, match expressions, and non-nullable types by default.

How SJS Differs from TypeScript

FeatureTypeScriptSuperJS
anyAllowed (soundness hole)Banned — use dynamic instead
Null safetyOpt-in (strictNullChecks)On by default; T? is the nullable form
Mapped typesSupportedBanned — use object types
Conditional typesSupportedBanned — use sum types
Algebraic sum typesNot supportedFirst-class: type R<T,E> = Ok(T) | Err(E)
Match expressionsNot supportedBuilt-in with exhaustiveness checking
! non-null assertionSupportedBanned — use narrowing
JSXRequires configOn by default
Type philosophyStructural + escape hatchesSound, gradual, Go-inspired

The 10 SJS Types

number string boolean bigint symbol void null never dynamic object T

Types are non-nullable by default. A string cannot hold null. Use string? to declare a nullable string.

Quick Start

Install the CLI from npm — a self-contained bundle with no runtime dependencies:

npm install -g @superjsorg/cli      # provides the `superjs` command

Compile your first file:

superjs build hello.sjs             # → hello.js (+ source map)

Prefer the programmatic API? Install @superjsorg/compiler and call transform() / compile().

Your First SJS File

// hello.sjs
const message: string = "Hello, World!"
console.log(message)

function greet(name: string): string {
  return `Hello, ${name}!`
}

console.log(greet("SuperJS"))

Null Safety

Types are non-nullable by default. Use T? to opt into nullability:

function findUser(id: number): string? {
  if (id === 1) return "Alice"
  return null
}

const name = findUser(42)            // type: string?
const display = name ?? "Unknown"    // ?? is type-checked against string?
console.log(display)

Sum Types and Match

type Result<T, E> = Ok(T) | Err(E)

function divide(a: number, b: number): Result<number, string> {
  if (b === 0) return Err("division by zero")
  return Ok(a / b)
}

const result = divide(10, 2)
const msg = match result {
  Ok(val) => `Result: ${val}`,
  Err(e)  => `Error: ${e}`,   // compiler enforces all variants are covered
}
console.log(msg)

CLI at a Glance

superjs build src/          # compile .sjs → .js (+ source maps)
superjs check src/          # type-check only
superjs explain SJS-E001    # explain a diagnostic code
superjs init                # write a default config

Config lives in superjs.config.json:

{ "compilerOptions": { "target": "ES2022", "outDir": "dist", "strict": false } }

What's Next

  • Language Reference — full syntax and type system documentation
  • Type System — null safety, sum types, generics, and structural object types
  • Tooling — CLI options, config schema, and diagnostic codes
  • Examples — practical SJS code samples
Documentation