@bepalo/rjson 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Bepalo Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,494 @@
+# 🏆 @bepalo/rjson
+
+[![npm version](https://img.shields.io/npm/v/@bepalo/rjson.svg)](https://www.npmjs.com/package/@bepalo/rjson)
+[![CI](https://img.shields.io/github/actions/workflow/status/bepalo/rjson/ci.yaml?label=ci)](https://github.com/bepalo/rjson/actions/workflows/ci.yaml)
+[![tests](https://img.shields.io/github/actions/workflow/status/bepalo/rjson/testing.yaml?label=tests)](https://github.com/bepalo/rjson/actions/workflows/testing.yaml)
+[![license](https://img.shields.io/npm/l/@bepalo/rjson.svg)](LICENSE)
+
+<!-- ![Benchmarked](https://img.shields.io/badge/benchmarked-yes-green) -->
+
+[![Vitest](https://img.shields.io/badge/vitest-6E9F18?style=for-the-badge&logo=vitest&logoColor=white)](test-result.md)
+
+**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
+
+```bash
+bun add @bepalo/rjson
+```
+
+#### npm
+
+```bash
+npm install @bepalo/rjson
+```
+
+#### pnpm
+
+```bash
+pnpm add @bepalo/rjson
+```
+
+#### deno
+
+```ts
+import { RJSON } from "jsr:@bepalo/rjson";
+```
+
+## 📦 Quick Start
+
+### Parse RJSON
+
+```ts
+import { RJSON } from "@bepalo/rjson";
+
+const user = RJSON.parse("(name:'Natnael',age:25,active:T)");
+
+console.log(user);
+```
+
+Output:
+
+```js
+{
+  name: "Natnael",
+  age: 25,
+  active: true
+}
+```
+
+### Stringify Objects
+
+```ts
+import { RJSON } from "@bepalo/rjson";
+
+const text = RJSON.stringify({
+  name: "Natnael",
+  age: 25,
+  active: true,
+});
+
+console.log(text);
+```
+
+Output:
+
+```txt
+(name:'Natnael',age:25,active:T)
+```
+
+### Stringify arrays
+
+```ts
+import { RJSON } from "@bepalo/rjson";
+
+const text = RJSON.stringify([1, 3.1415, null, undefined, true, "hello"]);
+
+console.log(text);
+```
+
+Output:
+
+```txt
+_(1,3.1415,,U,T,'hello')_
+```
+
+### Stringify mapped-arrays
+
+```ts
+import { RJSON } from "@bepalo/rjson";
+
+const text = RJSON.stringifyMappedArray(true, ["id", "title", "body"]);
+
+console.log(text);
+```
+
+Output:
+
+```txt
+~T(id,title,body)~
+```
+
+### Tagged Template Helper
+
+```ts
+import { rjson } from "@bepalo/rjson";
+
+const user = rjson`(name:'Natnael',age:25,active:T)`;
+
+console.log(user);
+```
+
+Output:
+
+```js
+{
+  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
+
+```txt
+(name:'John',age:30)
+```
+
+Produces:
+
+```js
+{
+  name: "John",
+  age: 30
+}
+```
+
+#### Arrays
+
+```txt
+_(1,2,3,4)_
+```
+
+Produces:
+
+```js
+[1, 2, 3, 4];
+```
+
+#### Nested Structures
+
+```txt
+(user:(name:'John',age:30),active:T)
+```
+
+Produces:
+
+```js
+{
+  user: {
+    name: "John",
+    age: 30
+  },
+  active: true
+}
+```
+
+#### Strings
+
+Supported delimiters:
+
+```txt
+'hello'
+"hello"
+`hello`
+```
+
+Escaping:
+
+```txt
+'can\'t'
+```
+
+```js
+const text = `'can\\'t'`;
+```
+
+Produces:
+
+```js
+"can't";
+```
+
+#### Numbers
+
+Supported formats:
+
+```txt
+123
+-123
++123
+12.5
+1e10
+1e-10
+```
+
+Examples:
+
+```txt
+age:25
+price:19.99
+distance:1.5e6
+```
+
+#### Booleans
+
+```txt
+T
+```
+
+Produces:
+
+```js
+true;
+```
+
+---
+
+```txt
+F
+```
+
+Produces:
+
+```js
+false;
+```
+
+#### Null
+
+```txt
+N
+```
+
+Produces:
+
+```js
+null;
+```
+
+Empty values are also treated as null:
+
+```txt
+(name:)
+```
+
+Produces:
+
+```js
+{
+  name: null;
+}
+```
+
+#### Undefined
+
+```txt
+(name:U)
+```
+
+Produces:
+
+```js
+{
+  name: undefined;
+}
+```
+
+### 🗜️ Mapped Arrays
+
+Mapped arrays compress repeated values.
+
+Instead of:
+
+```js
+{
+  admin: true,
+  editor: true,
+  user: true
+}
+```
+
+Use:
+
+```txt
+~T(admin,editor,user)~
+```
+
+Result:
+
+```js
+{
+  admin: true,
+  editor: true,
+  user: true
+}
+```
+
+---
+
+The value can be any valid RJSON type
+
+```txt
+~F(create,update,delete)~
+~(roles:_('admin','user')_)(create,update,delete)~
+~~F(admin,user)~(create,update,delete)~
+```
+
+## 🔧 API Reference
+
+### parseRJSON
+
+Parses RJSON text.
+
+```ts
+const value = parseRJSON("(name:'John',active:T)");
+```
+
+### stringifyRJSON
+
+Serializes JavaScript values.
+
+```ts
+const text = stringifyRJSON({
+  name: "John",
+  active: true,
+});
+```
+
+Result:
+
+```txt
+(name:'John',active:T)
+```
+
+### stringifyRJSONMappedArray
+
+Creates mapped-array expressions.
+
+```ts
+stringifyRJSONMappedArray(true, ["read", "write", "delete"]);
+```
+
+Result:
+
+```txt
+~T(read,write,delete)~
+```
+
+### rjson
+
+Tagged-template parser.
+
+```ts
+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
+
+```json
+{
+  "name": "John",
+  "active": true,
+  "roles": ["admin", "user"]
+}
+```
+
+RJSON
+
+```txt
+(name:'John',active:T,roles:_('admin','user')_)
+```
+
+## ⚠️ Current Limitations
+
+- Whitespace is forbidden.
+- Designed primarily for compact transport and URLs.
+
+Invalid:
+
+```txt
+(
+ name : 'John'
+)
+```
+
+Valid:
+
+```txt
+(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.
+
+<a href="https://ko-fi.com/natieshzed">
+  <img height="32" src="https://img.shields.io/badge/Ko--fi-donate-orange?style=for-the-badge&logo=ko-fi&logoColor=white">
+</a>

package/dist/cjs/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./rjson.ts";
+export { default } from "./rjson.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC"}

package/dist/cjs/index.js

@@ -0,0 +1,24 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = void 0;
+__exportStar(require("./rjson.js"), exports);
+var rjson_ts_1 = require("./rjson.js");
+Object.defineProperty(exports, "default", { enumerable: true, get: function () { return __importDefault(rjson_ts_1).default; } });
+//# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA,6CAA2B;AAC3B,uCAAqC;AAA5B,oHAAA,OAAO,OAAA"}

package/dist/cjs/rjson.d.ts

@@ -0,0 +1,30 @@
+interface ParseRJSONState {
+    start: number;
+    end: number;
+    i: number;
+    charCode: number;
+    forbidTextKeys?: boolean;
+    forbidEmptyKeys?: boolean;
+}
+export declare const parseRJSON: (source: string, initalState?: Partial<ParseRJSONState>) => unknown;
+export declare function rjson(strings: TemplateStringsArray, ...values: unknown[]): unknown;
+export declare const stringifyRJSONKey: (key: string) => string;
+export declare const stringifyRJSONArray: (data: unknown[]) => string;
+export declare const stringifyRJSONObject: (data: Record<string, unknown>) => string;
+export declare const stringifyRJSONMappedArray: (value: unknown | undefined | null, data: unknown[]) => string;
+export declare const stringifyRJSONString: (data: string) => string;
+export declare const stringifyRJSONNumber: (data: number) => string;
+export declare const stringifyRJSONBoolean: (data: boolean) => string;
+export declare const stringifyRJSON: (data?: unknown) => string;
+export declare const RJSON: {
+    parse: (source: string, initalState?: Partial<ParseRJSONState>) => unknown;
+    stringify: (data?: unknown) => string;
+    stringifyKey: (key: string) => string;
+    stringifyObject: (data: Record<string, unknown>) => string;
+    stringifyMappedArray: (value: unknown | undefined | null, data: unknown[]) => string;
+    stringifyString: (data: string) => string;
+    stringifyNumber: (data: number) => string;
+    stringifyBoolean: (data: boolean) => string;
+};
+export default RJSON;
+//# sourceMappingURL=rjson.d.ts.map

package/dist/cjs/rjson.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rjson.d.ts","sourceRoot":"","sources":["../../src/rjson.ts"],"names":[],"mappings":"AAwCA,UAAU,eAAe;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,CAAC,EAAE,MAAM,CAAC;IACV,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AA8bD,eAAO,MAAM,UAAU,GACrB,QAAQ,MAAM,EACd,cAAc,OAAO,CAAC,eAAe,CAAC,KACrC,OAwBF,CAAC;AAEF,wBAAgB,KAAK,CACnB,OAAO,EAAE,oBAAoB,EAC7B,GAAG,MAAM,EAAE,OAAO,EAAE,GACnB,OAAO,CAKT;AAED,eAAO,MAAM,iBAAiB,GAAI,KAAK,MAAM,KAAG,MAiB/C,CAAC;AAEF,eAAO,MAAM,mBAAmB,GAAI,MAAM,OAAO,EAAE,KAAG,MAErD,CAAC;AAEF,eAAO,MAAM,oBAAoB,GAAI,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,MAMpE,CAAC;AAEF,eAAO,MAAM,yBAAyB,GACpC,OAAO,OAAO,GAAG,SAAS,GAAG,IAAI,EACjC,MAAM,OAAO,EAAE,KACd,MAEF,CAAC;AAEF,eAAO,MAAM,oBAAoB,GAAI,MAAM,MAAM,KAAG,MAQnD,CAAC;AAEF,eAAO,MAAM,oBAAoB,GAAI,MAAM,MAAM,KAAG,MASnD,CAAC;AAEF,eAAO,MAAM,qBAAqB,GAAI,MAAM,OAAO,KAAG,MAErD,CAAC;AAEF,eAAO,MAAM,cAAc,GAAI,OAAO,OAAO,KAAG,MAoB/C,CAAC;AAEF,eAAO,MAAM,KAAK;oBA3HR,MAAM,gBACA,OAAO,CAAC,eAAe,CAAC,KACrC,OAAO;uBAmG4B,OAAO,KAAG,MAAM;wBA/Df,MAAM,KAAG,MAAM;4BAuBX,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,MAAM;kCASlE,OAAO,GAAG,SAAS,GAAG,IAAI,QAC3B,OAAO,EAAE,KACd,MAAM;4BAIkC,MAAM,KAAG,MAAM;4BAUf,MAAM,KAAG,MAAM;6BAWd,OAAO,KAAG,MAAM;CAmC3D,CAAC;AAEF,eAAe,KAAK,CAAC"}