Get started with Lion

This guide walks you through installing @lionlang/core, running your first Lion expression, and extending the environment with custom JavaScript values. You will have a working Lion program in under five minutes.

Lion requires two peer dependencies: effect for typed asynchronous evaluation, and typescript with strict mode enabled. Both must be installed in your project before using @lionlang/core.

Install @lionlang/core

Add the package and its peer dependencies to your project.

npm

npm install @lionlang/core effect

yarn

yarn add @lionlang/core effect

pnpm

pnpm add @lionlang/core effect

bun

bun add @lionlang/core effect

Import run and stdlib

run is the top-level entry point for evaluating Lion expressions. stdlib is the default environment containing all built-in modules.

import { Effect } from "effect";
import { run } from "@lionlang/core/evaluation/evaluate";
import { stdlib } from "@lionlang/core/modules";

The run function accepts any JSON-compatible value as an expression and a plain object as the environment. It returns an Effect that resolves to the evaluation result.

Evaluate your first expression

Pass a Lion expression and the standard library environment to run, then execute the Effect with Effect.runPromise.

const result = await Effect.runPromise(
  run(["number/add", 1, 2], stdlib)
);

console.log(result); // => 3

The expression ["number/add", 1, 2] is a plain JSON array. The first element, "number/add", resolves to a function in stdlib. The remaining elements are the arguments. The result is 3.

Add a custom environment

Spread stdlib into your own object to add custom bindings. Any string in a Lion expression resolves against the environment — including your own values, objects, and functions.

import { Effect } from "effect";
import { run } from "@lionlang/core/evaluation/evaluate";
import { stdlib } from "@lionlang/core/modules";

const env = {
  ...stdlib,
  price: 100,
  taxRate: 0.08,
  clamp: (min: number, max: number, value: number) =>
    Math.min(max, Math.max(min, value)),
};

// "price" and "taxRate" resolve to 100 and 0.08 from the environment
const total = await Effect.runPromise(
  run(["number/add", "price", ["number/multiply", "price", "taxRate"]], env)
);
console.log(total); // => 108

// "clamp" resolves to your custom JavaScript function
const clamped = await Effect.runPromise(run(["clamp", 0, 100, 150], env));
console.log(clamped); // => 100

Because strings resolve at evaluation time, you can store Lion programs as JSON and supply different environments at runtime — changing behavior without modifying the program.

Next steps

Expression model

Learn how arrays, strings, objects, and primitives evaluate in detail.

Special forms

Explore define, lambda, cond, match, begin, and quote.

Standard library

Browse all built-in modules and their available functions.

Custom environment

Learn patterns for injecting JavaScript APIs into the Lion environment.

Get Started

Core Concepts

Standard Library

Guides

Get started with Lion

Next steps

Expression model

Special forms

Standard library

Custom environment

​Next steps

Expression model

Special forms

Standard library

Custom environment

Next steps