creationix/rx: RX encoder, decoder, and CLI data tool · GitHub

npm install @creationix/rx     # library
npm install -g @creationix/rx  # CLI (global)
npx @creationix/rx data.rx     # CLI (one-off)

“$1“ -t -c ); // Returns a string — store it anywhere you’d store JSON”>

import 💬 from "@creationix/rx";

const payload = stringify( less -RFX; );
// Returns a string — store it anywhere you'd store JSON

; from "@creationix/rx"; const data = parse(payload) as any; data.users[0] // "alice" data.version // 3 Object.keys(data) // ["users", "version"] JSON.stringify(data) // works — full JS interop”>

import 💬 from "@creationix/rx";

const data = parse(payload) as any;
data.users[0]         // "alice"
data.version          // 3
Object.keys(data)     // ["users", "version"]
JSON.stringify(data)  // works — full JS interop

rx data.rx                         # pretty-print as tree
rx data.rx -j                      # convert to JSON
rx data.json -r                    # convert to REXC
cat data.rx | rx                   # read from stdin (auto-detect)
rx data.rx -s key 0 sub            # select a sub-value
rx data.rx -o out.json             # write to file

p()  rx "$1" -t -c 
# p data.rx          — pretty-print with color, auto-pages large output

import { encode, decode, open } from "@creationix/rx";

// encode returns Uint8Array (no string conversion)
const buf = encode({ path: "/api/users", status: 200 });

// decode/open take Uint8Array, return Proxy-wrapped value
const data = open(buf) as any;
data.path    // "/api/users"
data.status  // 200

import { stringify, encode } from "@creationix/rx";

// Add sorted indexes to containers with >= 10 entries (enables O(log n) key lookup)
stringify(data, { indexes: 10 });

// Always index, even small containers
stringify(data, { indexes: 0 });

// Disable indexes entirely
stringify(data, { indexes: false });

// External refs — shared dictionary of known values
const refs = { R: ["/api/users", "/api/teams"] };
stringify(data, { refs });

// Streaming — receive chunks as they're produced
stringify(data, {
  onChunk: (chunk, offset) => process.stdout.write(chunk),
});

const refs = { R: ["/api/users", "/api/teams"] };
const data = parse(payload, { refs });

const obj = parse(payload) as any;

obj.newKey = 1;     // throws TypeError("rexc data is read-only")
delete obj.key;     // throws TypeError("rexc data is read-only")

"key" in obj;       // works (uses zero-alloc key search)

obj.nested === obj.nested  // true

import { handle } from "@creationix/rx";

const h = handle(obj.nested);
// h.data: Uint8Array — the underlying buffer
// h.right: number — byte offset of this node

import { encode, inspect } from "@creationix/rx";

const buf = encode({ name: "alice", scores: [10, 20, 30] });
const root = inspect(buf);

root.tag       // ":"
root[0].tag    // "," (first child — a string key)
root[0].value  // "name"
root.length    // 4 (key, value, key, value)

for (const child of root) {
  console.log(child.tag, child.b64);
}

JSON.stringify(root)  // recursive tree of {tag, b64, left, right, size, children}

// Object utilities — return ASTNodes, not resolved values
for (const key of root.keys()) { ... }
for (const val of root.values()) { ... }
for (const [key, val] of root.entries()) {
  console.log(key.value, val.value);
}

// Prefix search — O(log n + m) on indexed objects
for (const [key, val] of root.filteredKeys("/api/")) { ... }

// Indexed access — O(1) on indexed containers
const node = root.index("name");   // object key lookup
const elem = root.index(2);        // array index

rx data.rexc --ast            # output the encoding structure as JSON
rx data.json --ast            # encode to rexc first, then inspect
echo '{"x":1}' | rx --ast    # from stdin

import { b64Stringify, b64Parse, b64Sizeof, toZigZag, fromZigZag } from "@creationix/rx";

b64Stringify(255)  // "3V"
b64Parse("3V")     // 255
b64Sizeof(255)     // 2 (digits needed)

toZigZag(-1)    // 1 (signed → unsigned)
fromZigZag(1)   // -1 (unsigned → signed)

import {
  makeCursor, read, readStr, resolveStr,
  strEquals, strCompare, strHasPrefix, prepareKey,
  findKey, findByPrefix, seekChild, collectChildren,
  rawBytes,
} from "@creationix/rx";

const c = makeCursor(data);  // one allocation, c.right = data.length
read(c);                     // parse root node
// c.tag, c.left, c.right, c.val, c.ixWidth, c.ixCount, c.schema

// After read() returned "array" or "object":
const end = c.left;
let right = c.val;
while (right > end) {
  c.right = right;
  read(c);
  // process c.tag, c.val, etc.
  right = c.left;
}

// Indexed containers: O(1) access via index table
seekChild(child, container, index);

// Non-indexed: collect boundaries, then access by index
const offsets: number[] = [];
const count = collectChildren(container, offsets);
c.right = offsets[i];
read(c);

const key = prepareKey("myKey");     // encode once

strEquals(c, key);        // exact match, zero-alloc
strCompare(c, key);       // ordering (<0, 0, >0), zero-alloc
strHasPrefix(c, key);     // prefix check, zero-alloc

readStr(c);               // decode to JS string (1 allocation)
resolveStr(c);            // follow pointers/chains, then decode

findKey(c, container, "myKey");           // convenient
findKey(c, container, prepareKey("myKey")); // pre-encoded for hot loops

const v = makeCursor(data);
if (findKey(v, container, "key")) {
  // v now points at the value node
  // Works on inline keys, schema objects, pointer keys, and chain keys
  // O(log n) on sorted+indexed objects, O(n) linear scan otherwise
}

findByPrefix(c, container, "/api/", (key, value) => {
  console.log(resolveStr(key), value.val);
  // return false to stop early
});
// O(log n + m) on indexed objects, O(n) on non-indexed

rawBytes(c)  // zero-copy Uint8Array view: data.subarray(c.left, c.right)

rx --completions setup [zsh|bash]    # install tab completions
rx --completions zsh|bash            # print completion script to stdout

bun run rx data.rx                 # from repo root