lykn

S-expression syntax for JavaScript

lykn is a lightweight Lisp that compiles to clean, readable JavaScript. No runtime, no dependencies in the output — just JS you'd write by hand, but expressed in s-expressions.

lykn has two syntax layers: surface syntax for everyday code (typed functions, algebraic data types, pattern matching, immutable bindings) and kernel syntax for low-level control. Both are s-expressions; surface forms compile to kernel forms, which compile to JavaScript.

The name means good luck in Norwegian, luck in Swedish, and — if you squint at the Icelandic — closure.

Status

v0.4.0 — Safe operators land. = is now strict equality in surface syntax (a === b), matching every Lisp dialect. and/or/not are short-circuit logical operators, not function calls. All mutation goes through named forms (bind, reset!, swap!). See DD-22. Self-contained Rust compiler (no runtime dependencies). 73KB browser bundle.

Quick taste

;; Immutable bindings
(bind greeting "hello, world")

;; Typed functions with runtime safety
(func greet
  :args (:string name)
  :returns :string
  :body (+ greeting ", " name "!"))

;; Threading macros
(bind result (-> 5 (+ 3) (* 2)))

;; Objects with keyword syntax
(bind user (obj :name "lykn" :version "0.4.0"))

;; Controlled mutation via cells
(bind counter (cell 0))
(swap! counter (=> (n) (+ n 1)))
(console:log (express counter))

;; Macros still work — define your own forms
(macro when (test (rest body))
  `(if ,test (block ,@body)))

(when (> result 0)
  (console:log "positive"))

Compiles to:

const greeting = "hello, world";
function greet(name) {
  if (typeof name !== "string") throw new TypeError("greet: arg 'name' expected string, got " + typeof name);
  const result__gensym0 = greeting + ", " + name + "!";
  if (typeof result__gensym0 !== "string") throw new TypeError("greet: return value expected string, got " + typeof result__gensym0);
  return result__gensym0;
}
const result = (5 + 3) * 2;
const user = {name: "lykn", version: "0.4.0"};
const counter = {value: 0};
counter.value = ((n) => n + 1)(counter.value);
console.log(counter.value);
if (result > 0) {
  console.log("positive");
}

Architecture

lykn has two compiler implementations sharing the same syntax and semantics:

Rust compiler (standalone binary, no runtime dependencies):

.lykn source → reader → expander → classifier → analyzer → emitter → codegen → JavaScript

JS compiler (browser bundle + Deno):

.lykn source → reader → surface macros → expander → compiler → astring → JavaScript

Rust pipeline (crates/)

• Reader (lykn-lang/reader) — S-expression parser with source locations
• Expander (lykn-lang/expander) — macro expansion (user macros via Deno subprocess)
• Classifier (lykn-lang/classifier) — S-expressions → typed surface AST
• Analyzer (lykn-lang/analysis) — type registry, exhaustiveness checking, scope tracking, unused binding detection
• Emitter (lykn-lang/emitter) — surface forms → kernel S-expressions
• Codegen (lykn-lang/codegen) — kernel S-expressions → JavaScript text (pure Rust, no external dependencies)

JS pipeline (src/)

• Reader (src/reader.js) — parses s-expressions, handles # dispatch (`, ,, ,@, #a(...), #o(...), #NNr, #;, #|...|#), dotted pairs
• Surface macros (src/surface.js) — transforms high-level surface forms to kernel forms
• Expander (src/expander.js) — three-pass macro expansion pipeline (Bawden's quasiquote algorithm)
• Compiler (src/compiler.js) — kernel forms → ESTree AST → JS via astring
• Browser shim (src/lykn-browser.js) — 73KB bundle with <script type="text/lykn"> support and window.lykn API

Toolchain

brew install biome deno

Lint

# JS (src/)
deno lint src/
biome lint src/

# Rust
cargo clippy

Format

# JS (src/)
biome format src/
biome format --write src/    # fix in place

# Rust
cargo fmt

Test

deno task test              # all tests
deno task test:unit         # unit tests only
deno task test:integration  # integration tests only
cargo test                  # Rust tests

Usage

Browser

<script src="dist/lykn-browser.js"></script>
<script type="text/lykn">
  ;; Macros work inline in the browser!
  (macro when (test (rest body))
    `(if ,test (block ,@body)))

  (const el (document:query-selector "#output"))
  (when el
    (= el:text-content "Hello from lykn!"))
</script>

Or use the API directly:

lykn.compile('(+ 1 2)')   // → "1 + 2;\n"
lykn.run('(+ 1 2)')       // → 3
await lykn.load('/app.lykn')

Note: import-macros is not available in the browser (no file system access). Inline macro definitions work.

Build Browser Bundle

deno task build

Rust CLI

# Build from source
mkdir -p ./bin
cargo build --release && cp ./target/release/lykn ./bin

# Compile .lykn to JavaScript
lykn compile main.lykn                    # output to stdout
lykn compile main.lykn -o main.js         # output to file
lykn compile main.lykn --strip-assertions # omit type checks / contracts
lykn compile main.lykn --kernel-json      # output kernel JSON (debug)

# Format
lykn fmt main.lykn                        # stdout
lykn fmt -w main.lykn                     # in place

# Syntax check
lykn check main.lykn

Run Examples

# Compile to JS and run with any JS runtime
lykn compile examples/surface/main.lykn -o /tmp/main.js && deno run /tmp/main.js

# Serve the browser examples (needs a local server for external .lykn files)
deno run --allow-net --allow-read jsr:@std/http@1/file-server --port 5099
# Then open http://localhost:5099/examples/surface/browser.html

Both examples/surface/ (recommended) and examples/kernel/ are available.

Supported forms

Surface forms

Surface syntax is the recommended way to write lykn. These forms expand to kernel forms at compile time.

Bindings & mutation

Functions

Types & pattern matching

Objects

Threading macros

Equality & logic

Kernel forms

Kernel forms are the compilation targets for surface macros. You can use them directly for low-level control, JS interop, or when surface syntax doesn't cover a specific JS feature.

Basics

Functions

Modules

Control flow

Expressions

Destructuring

Classes

Operators

Macros

Data literals and sugar

Design principles

• Thin skin over JS. lykn is not a new language. It's a syntax for the language you already have. The output should look like code you'd write.
• No runtime. Compiled lykn is just JS. Nothing extra ships to the browser.
• Self-contained. The Rust compiler is a single binary with no runtime dependencies. The browser bundle is 73KB. You can read the whole thing.
• Two worlds. Rust for the compiler and dev-side tooling (fast, single binary). JS for the browser bundle and in-browser <script> workflow.

References

• ESTree spec — the AST format lykn targets
• astring — ESTree to JS code generation
• Bawden 1999 — "Quasiquotation in Lisp", the algorithm behind lykn's macro expansion
• Fennel — inspiration for enforced gensym hygiene model
• eslisp — spiritual ancestor; reference implementation
• BiwaScheme — inspiration for the in-browser <script> workflow

License

Apache-2.0