Candor

A tiny programming language with one law: nothing fails silently.

JavaScript's original sin is silence — customer.emial quietly returns undefined and the bug surfaces three functions later, somewhere unrelated. Candor is the opposite bet: every mistake is loud, immediate, and points at its own line.

task Add(a, b)
    expect Add(2, 3) gives 5
    return a + b
end

say "40 + 2 = " + text(Add(40, 2))

Install

npm install -g candor-lang
candor run examples/hello.candor

Requires Node 18+.

The rules

Candor v0.1 is deliberately small, but every rule serves the law:

1. No undefined. Using a name before giving it a value is an error, with the line number.
2. No silent coercion. "5" + 3 is an error, not "53". Convert on purpose with text(...) and number(...).
3. No truthiness. if x where x is a number is an error. Say what you mean: if x != 0.
4. No Infinity, no NaN. Division by zero is an error. number("abc") is an error.
5. No silent returns. A task that finishes without return is an error — there is no implicit undefined to hand back.
6. No cross-type comparison. 1 == "1" is an error — they can never be equal, so it's probably a bug.
7. Promises are enforced. expect lines are living examples checked before every run. If one fails, the program refuses to run.

Language tour

-- comments start with --

-- values: numbers, text, booleans
x = 21
name = "Nova"
ready = true

-- print with say
say x * 2
say "Hello, " + name

-- convert explicitly (rule 2)
say "the answer is " + text(x * 2)
say number("12") + 1

-- conditions must be boolean (rule 3)
if x > 5
    say "big"
else
    say "small"
end

-- loops
i = 0
while i < 5
    i = i + 1
end

-- tasks (functions) carry their own promises (rule 7)
task Fact(n)
    expect Fact(5) gives 120
    if n <= 1
        return 1
    end
    return n * Fact(n - 1)
end

say Fact(6)

CLI

candor run file.candor     # run (expects must pass first)
candor check file.candor   # parse + expects only — the Candor build gate
candor --version

Use as a library

import { run, check, CandorError } from "candor-lang";

const { expects } = run('say "hi"');            // prints to stdout
run('say 1 + 1', { write: (s) => log(s) });     // capture output

Roadmap

• else fallback blocks — x = risky() else { ... } (absence must be handled, rule 1 goes structural)
• uses [...] effect declarations — a function's signature is its permission slip
• Unit types — dollars, minutes; mixing units is a compile error
• Lists and records
• candor:core — a no-GC, no-runtime dialect for systems work

Why

Designed by Kirpajeet Singh Gill with Claude, as an experiment in what a language looks like when it's built for the era of humans and AI writing code together — where the reader's real job is deciding whether to trust code they didn't write. Every rule above exists to make that trust checkable.

MIT licensed.