jalapenojson

Guide

How to use jalapenojson from Python, JavaScript and C. The format itself is described in the spec.

Python. Date columns use the datetime types directly:

Python
from datetime import date, datetime, timezone, timedelta
from jalapenojson import encode, decode

blob = encode(rows, schema=[("id","i",4), ("name","s",16), ("seen","z")])
rows = decode(blob)
rows[0]["seen"]           # datetime(2026, 1, 15, 9, 30, tzinfo=timezone(timedelta(hours=2)))

d gives a date, t a time, n a naive datetime, z an aware one. On the way in, a datetime in a d column is an error rather than a silently truncated date, and a naive datetime in a z column is an error rather than a guessed offset.

f, y, d, t, n and z always take the same number of bytes, so their size can be left out. i is 1, 2, 4 or 8 bytes, and s and b take the size you give them.

A y column holds a boolean, in one byte:

Python
blob = encode([{"id": 1001, "paid": True}], schema=[("id","i",4), ("paid","y")])
decode(blob)[0]["paid"]   # True

It takes True and False and nothing else, so 1, "true" and None are errors rather than guesses. There is no null in the format, so a missing value is an error in every column.

A nested list is a column whose type is a schema's number, and the schema it names is passed alongside schema 1, with as many more as you need:

Python
doc = encode(orders,
             schema=[("order","i",4), ("items","2")],
             extra_schemas=[[("sku","s",2), ("qty","i",1)]])
decode(doc)[0]["items"]   # [{"sku": "A1", "qty": 2}, ...]

A value that does not fit its column is an error, and the encoder does not truncate it: an i:1 holds -128 to 127, and an s:3 holds three bytes of UTF-8. A shorter s value is followed by a break byte and reads back as what was written. size_columns() works the sizes out from the rows you have, when you would rather not:

Python
from jalapenojson import size_columns
schema, extra = size_columns(rows, [("uuid","s"), ("iso","s"), ("cents","i")])

view() reads the same document without converting all of it. It works out where each column starts from the header and converts only the values you ask for:

Python
from jalapenojson import view
t = view(blob)
t.rows                    # how many rows
t.get(0, "name")          # one value
t.column("id")            # one column, converted in one go
t.row(0)                  # a whole row
t.get(0, "items")         # a list column: a Table over that list's rows

JavaScript:

JavaScript
import { encode, decode } from "./jalapenojson.js";
const buf = encode(rows, [["id","i",4], ["name","s",16], ["seen","z"]]);
const back = decode(buf);          // Uint8Array in, objects out
back[0].seen                       // { instant: Date, offsetMinutes: 120, micros: 0 }

d, t and n come back as canonical strings, because JavaScript has no type for a date without a zone. z comes back as { instant, offsetMinutes, micros }: a JS Date is an instant, so it cannot carry the offset (the value would be shown in the reader's timezone instead) or a fraction finer than a millisecond. encode accepts that shape, a canonical string, or a bare Date (written against UTC, to millisecond precision). An i value comes back as a number, or as a BigInt when it is too large for a number to hold exactly. A y column comes back as true or false, and encode takes those two and nothing else.

Nested lists take the schema they name as a third argument, and come back as arrays of objects:

JavaScript
const buf = encode(orders, [["order","i",4], ["items","2"]],
                   [[["sku","s",2], ["qty","i",1]]]);
decode(buf)[0].items               // [{ sku: "A1", qty: 2 }, ...]

The sizes work as in Python, and sizeColumns() works them out from your rows:

JavaScript
encode(rows, [["uuid","s",32], ["iso","s",3], ["cents","i",8]]);
sizeColumns(rows, [["uuid","s"], ["iso","s"], ["cents","i"]]);

view() reads the same document without converting all of it:

JavaScript
import { view } from "./jalapenojson.js";
const t = view(buf);
t.rows                             // how many rows
t.get(0, "name")                   // one value
t.column("name")                   // one column, as an array
t.numbers("price")                 // a number column, as a typed array
t.row(0)                           // a whole row
t.get(0, "items")                  // a nested list, as a view over its rows

numbers() hands back an Int8Array, Int16Array, Int32Array, BigInt64Array or Float64Array, whichever the column's type is. When the column starts at a multiple of its values' size in memory, it is a view over the document's bytes and copies nothing, so writing to it writes to the document. Otherwise it is a copy, since JavaScript makes a typed array only at such an offset. Use view() when you want part of a document, or its columns as arrays, and decode() when you want every row as an object.

C: c/jalapenojson.h is a single-header zero-copy reader.

C
jj_doc doc;
int rc = jj_parse(buf, len, &doc);          // buf must outlive doc
if (rc != JJ_OK) return fprintf(stderr, "%s\n", jj_strerror(rc));
long long id = jj_int(jj_field(&doc, 0, 0));
jj_free(&doc);

jj_parse mutates buf (column names are NUL-terminated in place) and checks every position against len, so the buffer does not need to be NUL-terminated. It reads the header and the list fields and no other value, so a value comes back as the bytes it is, and jj_field finds it by arithmetic. For a document you did not write, jj_float_checked says whether a float is finite, jj_bool_checked whether a y byte is 00 or 01, and jj_str_checked whether an s value is UTF-8. An s value's len stops at its break byte. jj_list hands back a view over one nested list's rows. It allocates nothing, so it cannot fail on a document jj_parse accepted:

C
if (jj_is_list(doc.col_types[2])) {
    jj_doc items;
    if (jj_list(&doc, 0, 2, &items) == JJ_OK)
        for (ptrdiff_t r = 0; r < items.n_rows; r++)
            printf("%lld\n", jj_int(jj_field(&items, r, 1)));
}

The reader never recurses, so a document cannot drive it off the stack, and how deep to go is the caller's own decision. Python and JavaScript do not recurse either, so lists nest as deep as memory allows in all three.

jj_column(&doc, c) is the first byte of a column. A column can start at any byte, so read its values with the accessors or memcpy, not through a cast pointer.

Dates live in c/jj_date.h, layered on top and entirely optional:

C
#include "jj_date.h"
jj_date d;
if (jj_date_parse(jj_field(&doc, r, c), doc.col_types[c], &d) == JJ_DATE_OK)
    printf("%d-%02d-%02d\n", d.year, d.month, d.day);