🏆 @bepalo/rjson

A compact, URL-friendly serialization format that is smaller than JSON while remaining human-readable and fast to parse.

RJSON (Remote JavaScript Object Notation) is a specification and implementation inspired by RISON and it is designed for:

• Better frontend-to-backend communication via search parameters.
• Compact payloads
• Human-readable configuration
• Fast parsing without AST generation
• JavaScript-native data structures

✨ Features

• ⚡ Fast parser with direct character scanning (recursive descent parsing).
• 📦 Smaller than JSON for many real-world payloads
• 🌐 URL-friendly syntax
• 🧩 Supports objects, arrays, strings, numbers, booleans
• 🔐 Supports null and undefined
• 🗜️ Built-in mapped-array compression
• 📝 Tagged template support
• 🔧 Zero dependencies
• 🟦 TypeScript ready
• 🚀 Runtime agnostic (Node.js, Bun, Deno)

📑 Table of Contents

1. Features
2. Installation
3. Quick Start
4. Syntax Overview
5. Core Types
6. Mapped Arrays
7. API Reference
8. Design Goals
9. License

🚀 Get Started

📥 Installation

bun

bun add @bepalo/rjson

npm

npm install @bepalo/rjson

pnpm

pnpm add @bepalo/rjson

deno

import { RJSON } from "jsr:@bepalo/rjson";

📦 Quick Start

Parse RJSON

import { RJSON } from "@bepalo/rjson";

const user = RJSON.parse("(name:'Natnael',age:25,active:T)");

console.log(user);

Output:

{
  name: "Natnael",
  age: 25,
  active: true
}

Stringify Objects

import { RJSON } from "@bepalo/rjson";

const text = RJSON.stringify({
  name: "Natnael",
  age: 25,
  active: true,
});

console.log(text);

Output:

(name:'Natnael',age:25,active:T)

Stringify arrays

import { RJSON } from "@bepalo/rjson";

const text = RJSON.stringify([1, 3.1415, null, undefined, true, "hello"]);

console.log(text);

Output:

_(1,3.1415,,U,T,'hello')_

Stringify mapped-arrays

import { RJSON } from "@bepalo/rjson";

const text = RJSON.stringifyMappedArray(true, ["id", "title", "body"]);

console.log(text);

Output:

~T(id,title,body)~

Tagged Template Helper

import { rjson } from "@bepalo/rjson";

const user = rjson`(name:'Natnael',age:25,active:T)`;

console.log(user);

Output:

{
  name: "Natnael",
  age: 25,
  active: true,
}

📚 Syntax Overview

Type	RJSON	JSON
Object	(name:'John')	{"name":"John"}
Array	_(1,2,3)_	[1,2,3]
String	'hello' "hello" `hello`	"hello"
Number	123	123
Boolean	T / F	true / false
Null	N	null
Undefined	U	Not supported
Mapped Array	~T(admin,user)~	{"admin":true,"user":true}

📚 Core Types

Objects

(name:'John',age:30)

Produces:

{
  name: "John",
  age: 30
}

Arrays

_(1,2,3,4)_

Produces:

[1, 2, 3, 4];

Nested Structures

(user:(name:'John',age:30),active:T)

Produces:

{
  user: {
    name: "John",
    age: 30
  },
  active: true
}

Strings

Supported delimiters:

'hello'
"hello"
`hello`

Escaping:

'can\'t'

const text = `'can\\'t'`;

Produces:

"can't";

Numbers

Supported formats:

123
-123
+123
12.5
1e10
1e-10

Examples:

age:25
price:19.99
distance:1.5e6

Booleans

T

Produces:

true;

---

F

Produces:

false;

Null

N

Produces:

null;

Empty values are also treated as null:

(name:)

Produces:

{
  name: null;
}

Undefined

(name:U)

Produces:

{
  name: undefined;
}

🗜️ Mapped Arrays

Mapped arrays compress repeated values.

Instead of:

{
  admin: true,
  editor: true,
  user: true
}

Use:

~T(admin,editor,user)~

Result:

{
  admin: true,
  editor: true,
  user: true
}

---

The value can be any valid RJSON type

~F(create,update,delete)~
~(roles:_('admin','user')_)(create,update,delete)~
~~F(admin,user)~(create,update,delete)~

🔧 API Reference

parseRJSON

Parses RJSON text.

const value = parseRJSON("(name:'John',active:T)");

stringifyRJSON

Serializes JavaScript values.

const text = stringifyRJSON({
  name: "John",
  active: true,
});

Result:

(name:'John',active:T)

stringifyRJSONMappedArray

Creates mapped-array expressions.

stringifyRJSONMappedArray(true, ["read", "write", "delete"]);

Result:

~T(read,write,delete)~

rjson

Tagged-template parser.

const data = rjson`
(name:'John')
`;

🎯 Why RJSON?

It is designed for better frontend-to-backend communication via search parameters.

Benefits:

• Smaller payloads
• Easier URL embedding
• Human-readable
• JavaScript-oriented
• Fast parsing

Example:

JSON

{
  "name": "John",
  "active": true,
  "roles": ["admin", "user"]
}

RJSON

(name:'John',active:T,roles:_('admin','user')_)

⚠️ Current Limitations

• Whitespace is forbidden.
• Designed primarily for compact transport and URLs.

Invalid:

(
 name : 'John'
)

Valid:

(name:'John')

📄 License

MIT

🕊️ Thanks and Enjoy

If you find RJSON useful, please consider starring the repository and sharing it with others.

💖 Be a Sponsor

Support development and future improvements.