JSN

A programming language written in pure JSON.

JSN is a production-grade language where all source code is valid JSON. No custom syntax, no semicolons, no indentation rules. If you can write JSON, you can write JSN.

Installation

npm install -g @jsonists/jsn

Or build from source:

git clone https://github.com/jsonists/jsn.git
cd jsn
npm install
npm install -g .

Requires Node.js 18 or later.

Getting Started

Create a new project:

jsn init my-project
cd my-project

Write your first program in index.json:

[
  { "let": { "name": "world" } },
  { "print": "Hello {name}!" }
]

Run it:

jsn run index.json

Output:

Hello world!

Language Overview

Variables

{ "let": { "x": 10, "name": "jsn" } }
{ "const": { "PI": 3.14159 } }
{ "set": { "x": 20 } }

Math

{ "let": { "sum": { "add": [10, 20] } } }
{ "let": { "diff": { "sub": ["sum", 5] } } }

Supported operators: add, sub, mul, div, mod, pow, sqrt, abs, round, floor, ceil.

Conditionals

{
  "if": {
    "condition": { "gt": ["x", 10] },
    "then": { "print": "big" },
    "else": { "print": "small" }
  }
}

Comparisons: gt, lt, gte, lte, eq, neq, and, or, not.

Loops

{
  "for": {
    "let": { "i": 0 },
    "condition": { "lt": ["i", 10] },
    "step": { "increment": "i" },
    "body": { "print": "{i}" }
  }
}

{
  "forEach": {
    "in": "items",
    "as": "item",
    "body": { "print": "{item}" }
  }
}

Functions

{
  "define": {
    "name": "factorial",
    "params": ["n"],
    "body": {
      "if": {
        "condition": { "lte": ["n", 1] },
        "then": { "return": 1 },
        "else": {
          "return": {
            "mul": ["n", { "call": "factorial", "with": { "n": { "sub": ["n", 1] } } }]
          }
        }
      }
    }
  }
}

Call a function:

{ "call": "factorial", "with": { "n": 10 } }

Error Handling

{
  "try": {
    "body": [{ "throw": "something went wrong" }],
    "catch": {
      "as": "err",
      "body": { "print": "Caught: {err.message}" }
    }
  }
}

String Operations

{ "upper": "hello" }
{ "concat": ["hello", " ", "world"] }
{ "split": { "value": "a,b,c", "by": "," } }

CLI Reference

| Command | Description | |---|---| | jsn run <file> | Execute a JSN program | | jsn install | Install dependencies from package.yml | | jsn install <user/repo> | Install a package from GitHub | | jsn remove <user/repo> | Remove a package | | jsn init <name> | Scaffold a new JSN project | | jsn compile <file> | Compile to bytecode (.jsnc) | | jsn repl | Start the interactive shell | | jsn list | List installed packages | | jsn version | Print version |

Package Manager (JPM)

JSN has a built-in package manager that fetches packages directly from GitHub.

Create a package.yml:

name: my-project
version: 1.0.0
main: index.json
dependencies:
  jsonists/json-ws: 1.0.0

Then install:

jsn install

Packages are cached in .jsn/packages/ and tracked via jsn.lock.

Project Structure

packages/
  compiler/    Lexer, Parser, Validator, AST
  runtime/     Executor, Scope, Event Loop, Memory, Errors
  jpm/         Package manager (fetcher, resolver, installer)
std/           Standard library (core, math, string, array, object, fs)
cli/           Command-line interface
examples/      Example programs
docs/          Language documentation
tests/         Test suite

For Library Authors

JSN exposes its internals so future packages can build on top of it:

const { Executor, Scope } = require('@jsonists/jsn');
const { compile, parse } = require('@jsonists/jsn/compiler');

This allows libraries like json-ws, json-db, and json-http to plug directly into the JSN runtime.

License

Apache-2.0 -- see LICENSE for details.

Built by jsonists.