npm package: @jsonists/jsn
Description: JSN — A programming language written in JSON. Compiler, runtime, and package manager in one.
Author: jsonists
Latest version: 0.2.1

# 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

```bash
npm install -g @jsonists/jsn
```

Or build from source:

```bash
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:

```bash
jsn init my-project
cd my-project
```

Write your first program in `index.json`:

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

Run it:

```bash
jsn run index.json
```

Output:

```
Hello world!
```

---

## Language Overview

### Variables

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

### Math

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

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

### Conditionals

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

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

### Loops

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

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

### Functions

```json
{
  "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:

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

### Error Handling

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

### String Operations

```json
{ "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`:

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

Then install:

```bash
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:

```js
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](LICENSE) for details.

Built by [jsonists](https://github.com/jsonists).