@athanx/asun

Why ASUN?

json

Standard JSON repeats every field name in every record. When you send structured data to an LLM, over an API, or across services, that repetition wastes tokens, bytes, and attention:

[
  { "id": 1, "name": "Alice", "active": true },
  { "id": 2, "name": "Bob", "active": false },
  { "id": 3, "name": "Carol", "active": true }
]

asun

ASUN declares the schema once and streams data as compact tuples:

[{id, name, active}]:
  (1,Alice,true),
  (2,Bob,false),
  (3,Carol,true)

Fewer tokens. Smaller payloads. Clearer structure, and faster parsing than repeated-object JSON.

---

Zero-dependency JavaScript/TypeScript library for ASUN (Array-Schema Unified Notation) — a token-efficient, schema-driven data format for LLM interactions and large-scale data transfer.

@athanx/asun is the official runtime for both JavaScript and TypeScript users. It ships ESM/CJS builds and bundled .d.ts type declarations in a single package, so there is no separate asun-ts package to install.

Works in browsers, Node.js, Deno, Bun and any JS framework: Vue, React, Svelte, SolidJS, etc.

中文文档

---

What is ASUN?

ASUN separates schema from data, eliminating repeated key names found in JSON. The schema is declared once; each data row carries only values:

JSON (100 tokens):
{"users":[{"id":1,"name":"Alice","active":true},{"id":2,"name":"Bob","active":false}]}

ASUN (~35 tokens, 65% saved):
[{id@int, name@str, active@bool}]:(1,Alice,true),(2,Bob,false)

Aspect	JSON	ASUN
Token efficiency	100%	30–70% ✓
Key repetition	Every object	Declared once ✓
Human readable	Yes	Yes ✓
Type annotations	None	Built-in ✓
Data size	100%	40–55% ✓

---

Install

npm install @athanx/asun

Or copy dist/asun.min.js directly into a web page (exposes a global ASUN object).

TypeScript users do not need a separate stub package. npm run build emits dist/index.d.ts, and the package exports it via the types field.

---

Quick start

import {
  encode,
  encodeTyped,
  encodePretty,
  encodePrettyTyped,
  decode,
  encodeBinary,
  decodeBinary,
} from "@athanx/asun";

const users = [
  { id: 1, name: "Alice", score: 9.5 },
  { id: 2, name: "Bob", score: 7.2 },
];

// Schema is inferred automatically — no schema string needed
const text = encode(users); // schema without scalar hints
const textTyped = encodeTyped(users); // schema with scalar hints (use for typed round-trip)
const pretty = encodePretty(users); // pretty + untyped
const prettyTyped = encodePrettyTyped(users); // pretty + scalar hints
const blob = encodeBinary(users); // binary (schema inferred internally)

console.log(decode(textTyped)); // original array restored
console.log(decode(prettyTyped)); // same from pretty
console.log(decodeBinary(blob, "[{id@int, name@str, score@float}]")); // binary decode

Note on encode vs encodeTyped encode(obj) emits a schema without scalar hints ({id,name}) so the output is shorter. When decoded, all values without explicit types are returned as strings. Use encodeTyped(obj) when you need scalar hints to preserve numeric and boolean types on round-trip.

---

API

Type inference rules

JS value	Inferred ASUN type
whole number	int
fractional number	float
true / false	bool
text	str
null / undefined	str? (optional)

Note: Schema is inferred from the first element of an array. To make a field optional (str?), ensure the first element has null for that field.

encode(obj) → string

Serialize a plain object or array to ASUN text with an inferred schema without scalar hints. When decoded, all scalar fields without explicit hints come back as strings:

encode({ id: 1, name: "Alice" });
// → '{id,name}:\n(1,Alice)\n'

encode([{ id: 1 }, { id: 2 }]);
// → '[{id}]:\n(1),\n(2)\n'

decode(encode({ id: 1, name: "Alice" }));
// → { id: '1', name: 'Alice' }  ← all strings when scalar hints are omitted

Use encodeTyped when you need decode to restore the original types.

encodeTyped(obj) → string

Same as encode but emits an inferred schema with scalar hints. Use this when you want decode() to restore the original scalar types:

encodeTyped({ id: 1, name: "Alice", active: true });
// → '{id@int,name@str,active@bool}:\n(1,Alice,true)\n'

Nested object and array fields keep structural bindings even when scalar hints are omitted:

encode({
  profile: { host: "127.0.0.1", port: 8080 },
  tags: ["blue", "fast"],
});
// → '{profile@{host,port},tags@[]}:\n((127.0.0.1,8080),[blue, fast])\n'

encodePretty(obj) → string

Pretty-printed ASUN text with inferred untyped schema.

encodePrettyTyped(obj) → string

Pretty-printed ASUN text with inferred typed schema.

decode(text) → object | object[]

Deserialize ASUN text. The schema is embedded in the text itself:

const rec = decode("{id@int, name@str}:\n(1,Alice)\n");
const rows = decode("[{id@int, name@str}]:\n(1,Alice),\n(2,Bob)\n");

encodeBinary(obj) → Uint8Array

Serialize to binary format. Schema is inferred internally — no schema string needed:

const data = encodeBinary(rows);

decodeBinary(data, schema) → object | object[]

Deserialize from binary format. Schema is required because the binary wire format carries no embedded type information:

const rows = decodeBinary(data, "[{id@int, name@str}]");

---

Supported types

Schema type	JS value	Example
int	number (integer)	42, -100
float	number	3.14, -0.5
bool	true / false	true, false
str	text	Alice, "Carol Smith"
T?	value or null	hello / null

Optional fields: append ? to any type (str?, int?, float?, bool?).

---

Browser (CDN) usage

<script src="dist/asun.min.js"></script>
<script>
  const text = ASUN.encodeTyped([{ id: 1, name: "Alice" }]);
  console.log(ASUN.decode(text));
</script>

ESM in browser

<script type="module">
  import { encodeTyped, decode } from "./dist/index.js";
  const text = encodeTyped([{ id: 1, name: "Alice" }]);
  console.log(decode(text));
</script>

Vue / React / Svelte / SolidJS

Works as a regular npm package — just import and use:

// Vue composable example
import { encodeTyped, decode } from "@athanx/asun";

export function useAsun() {
  const serialize = (data: object[]) => encodeTyped(data);
  const deserialize = (text: string) => decode(text);
  return { serialize, deserialize };
}

---

Binary format

Little-endian layout, byte-identical to asun-rs and asun-go:

Type	Bytes
int	8 (i64 LE)
float	8 (f64 LE)
bool	1
str	4-byte length LE + UTF-8 bytes
optional	1-byte tag (0=null, 1=present) + value
slice	4-byte count LE + elements

---

Build from source

npm install
npm run build    # generates dist/index.js, dist/index.cjs, dist/index.d.ts, dist/asun.min.js
npm test         # vitest

---

Run examples

node examples/basic.js     # 9 scenarios, basic usage
node examples/complex.js   # complex nested scenarios and legacy-syntax rejection
node examples/bench.js     # performance vs JSON.parse / JSON.stringify

---

Performance

ASUN JS produces 50–55% smaller output than JSON. Because JSON.parse / JSON.stringify are implemented in C, raw speed is slower — but:

• Network bandwidth is typically the bottleneck — 50% smaller payload saves more time than parse overhead costs
• LLM token cost — 30–70% fewer tokens = lower API cost and faster responses
• Binary format — encodeBinary / decodeBinary is fastest for machine-to-machine transfer

For latency-sensitive hot paths, use the Rust or Go implementations if your stack supports them.

---

License

MIT

Contributors

• Athan

Latest Benchmarks

Measured on this machine with Node 24.14.0.

Headline numbers:

• Flat 1,000-record dataset: ASUN text 58,539 B vs JSON 121,451 B (51.8% smaller)
• Flat 5,000-record dataset: ASUN serialize 8.93ms vs JSON 13.27ms, but deserialize 20.10ms vs JSON 16.92ms
• Large 10,000-record dataset: ASUN serialize 37.86ms vs JSON 20.23ms, deserialize 37.25ms vs JSON 33.82ms
• Throughput summary on 10,000-record-style text path: ASUN text serialize ran at 0.30 M records/s vs JSON 0.75 M-class baseline, and deserialize was roughly at parity in this run
• Binary path is mainly useful for decode and transport size here: on 1,000 records, BIN deserialize 4.68ms vs JSON 2.08ms, with payload 72,784 B vs JSON 121,451 B