@creationix/jot 0.0.1 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Tim Caswell
+
+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

@@ -1,6 +1,104 @@
 # Jot Format
 
-Jot is a compact, LLM friendly JSON variant designed to use fewer tokens while remaining easy to read and write.
+Jot is a compact, human-readable JSON variant that uses fewer tokens for LLM applications.
+
+**JSON:**
+
+```json
+{"context":{"task":"Our favorite hikes together","location":"Boulder"},"friends":["ana","luis","sam"],"hikes":[{"id":1,"name":"Blue Lake Trail","km":7.5},{"id":2,"name":"Ridge Overlook","km":9.2}]}
+```
+
+**Jot:**
+
+```jot
+{context:{task:Our favorite hikes together,location:Boulder},friends:[ana,luis,sam],hikes:{{:id,name,km;1,Blue Lake Trail,7.5;2,Ridge Overlook,9.2}}}
+```
+
+Same data, 26% fewer tokens, still readable.
+
+## Why Jot?
+
+- **Save on LLM costs** — Fewer tokens = lower API bills
+- **Fit more in context** — Get more data into your prompts
+- **Human readable** — Unlike binary formats, you can read and write it directly
+- **JSON compatible** — Parses to the same JavaScript objects
+
+## Token Savings
+
+<!-- START TOKEN SAVINGS -->
+Across 18 sample files, Jot averages **13% token savings**.
+
+| Sample | JSON | Jot | Savings |
+|--------|------|-----|---------|
+| [users-50](samples/users-50.pretty.jot) | 1327 | 837 | 37% |
+| [products](samples/products.pretty.jot) | 772 | 613 | 21% |
+| [large](samples/large.pretty.jot) | 240 | 221 | 8% |
+| [small](samples/small.pretty.jot) | 37 | 36 | 3% |
+| [irregular](samples/irregular.pretty.jot) | 49 | 49 | 0% |
+
+[Full report →](TOKEN_SAVINGS.md)
+<!-- END TOKEN SAVINGS -->
+
+## Installation
+
+### npm / pnpm / yarn
+
+```sh
+npm i --save @creationix/jot
+```
+
+### CommonJS
+
+```js
+const { parse, stringify } = require("@creationix/jot");
+```
+
+### ES Modules
+
+```js
+import { parse, stringify } from "@creationix/jot";
+```
+
+### Browser
+
+Copy [dist/jot.js](dist/jot.js) to your project and import as a native ES module:
+
+```html
+<script type="module">
+  import { parse, stringify } from "./jot.js";
+</script>
+```
+
+### TypeScript
+
+TypeScript definitions are included. You can also import [src/jot.ts](src/jot.ts) directly into your project.
+
+## Usage
+
+```js
+import { parse, stringify } from "@creationix/jot";
+
+// Parse Jot to JavaScript
+const data = parse("{name:Alice,scores:[98,87,92]}");
+// { name: "Alice", scores: [98, 87, 92] }
+
+// Stringify JavaScript to Jot
+const jot = stringify({ name: "Bob", active: true });
+// {name:Bob,active:true}
+
+// Pretty print with options
+const pretty = stringify(data, { pretty: true, indent: "  " });
+```
+
+## Syntax
+
+Jot is JSON with three optimizations:
+
+1. **Unquoted strings** — Strings are only quoted if necessary
+2. **Key folding** — Single-key nested objects collapse: `{a:{b:1}}` → `{a.b:1}`
+3. **Tables** — Arrays of objects with the same schema use `{{:cols;row;row}}` syntax
+
+Here's a complete example showing all three:
 
 ```jot
 {
@@ -19,21 +117,14 @@ Jot is a compact, LLM friendly JSON variant designed to use fewer tokens while r
 }
 ```
 
-It is JSON with three optimizations:
+### Unquoted Strings
 
-1. **Unquoted strings** — Strings are only quoted if necessary.
-2. **Key folding** — Single-key nested objects collapse: `{a:{b:1}}` → `{a.b:1}`
-   if normal keys contain dots, keep quotes: `{"a.b":1}`
-3. **Tables** — Object arrays with repeating schemas use `{{:cols;row;row}}` syntax
-
-## Unquoted Strings
-
-The only times that you need to quote a string are:
+Quote a string only when:
 
-- It is a valid JSON value (`true`, `false`, `null`, or a number like `42`, `3.14`, `-0.5`, or `1e10`)
-- It contains special characters: `: ; , { } [ ] "` or control characters (newline, tab, etc)
-- It is empty or has leading or trailing whitespace
-- It being used as a key in an object and contains `.` (to distinguish from folded keys)
+- It's a reserved value (`true`, `false`, `null`) or a number (`42`, `3.14`, `-0.5`, `1e10`)
+- It contains special characters: `: ; , { } [ ] "` or control characters
+- It's empty or has leading/trailing whitespace
+- It's a key containing `.` (to distinguish from folded keys)
 
 ```json
 {"name":"Alice","city":"New York","count":"42"}
@@ -43,9 +134,9 @@ The only times that you need to quote a string are:
 {name:Alice,city:New York,count:"42"}
 ```
 
-## Key Folding
+### Key Folding
 
-When a nested object has exactly ONE key, fold it:
+When a nested object has exactly one key, fold it:
 
 ```json
 {"server":{"host":"localhost"}}
@@ -55,7 +146,7 @@ When a nested object has exactly ONE key, fold it:
 {server.host:localhost}
 ```
 
-If normal keys contain dots, keep quotes to avoid confusion:
+If a key itself contains dots, quote it to avoid confusion:
 
 ```json
 {"data.point":{"x":10,"y":20}}
@@ -65,13 +156,9 @@ If normal keys contain dots, keep quotes to avoid confusion:
 {"data.point":{x:10,y:20}}
 ```
 
-## Tables
+### Tables
 
-One common shape in data is a table — an array of multiple objects with the same schema.
-
-Object arrays use `{{:schema;row;row;...}}` when schemas repeat. Start with `:` followed by column names:
-
-Don't use tables when there's no schema reuse (each object unique) — regular arrays are more compact.
+Arrays of objects with repeating schemas become tables. Start with `:` followed by column names:
 
 ```json
 [{"id":1,"name":"Alice"},{"id":2,"name":"Bob"}]
@@ -90,3 +177,5 @@ To change schema mid-table, add another `:schema;` row:
 ```jot
 {{:id,name;1,Alice;2,Bob;:x,y;10,20;30,40}}
 ```
+
+Don't use tables when there's no schema reuse — regular arrays are more compact.

package/dist/jot.cjs

@@ -0,0 +1,446 @@
+"use strict"
+Object.defineProperty(exports, "__esModule", { value: true })
+exports.stringify = stringify
+exports.parse = parse
+const RESERVED = new Set(["true", "false", "null"])
+const UNSAFE = [":", ",", "{", "}", "[", "]", '"', ";", "\\"]
+const WS_RE = /\s/
+const KEY_TERM_RE = /[:\,{}\[\];]|\s/
+function needsQuotes(s, extra = []) {
+  const chars = [...UNSAFE, ...extra]
+  return (
+    s === "" ||
+    s.trim() !== s ||
+    RESERVED.has(s) ||
+    !Number.isNaN(Number(s)) ||
+    chars.some((c) => s.includes(c)) ||
+    [...s].some((c) => c.charCodeAt(0) < 32)
+  )
+}
+const quote = (s) => (needsQuotes(s) ? JSON.stringify(s) : s)
+const quoteKey = (s) => (needsQuotes(s, ["."]) ? JSON.stringify(s) : s)
+function getFoldPath(value) {
+  const path = []
+  let current = value
+  while (current !== null && typeof current === "object" && !Array.isArray(current)) {
+    const keys = Object.keys(current)
+    if (keys.length !== 1 || keys[0].includes(".")) {
+      break
+    }
+    path.push(keys[0])
+    current = current[keys[0]]
+  }
+  return path.length > 0 ? { path, leaf: current } : null
+}
+function groupBySchema(arr) {
+  const groups = []
+  for (const obj of arr) {
+    const keys = Object.keys(obj)
+    const last = groups.at(-1)
+    if (last && last.keys.join(",") === keys.join(",")) {
+      last.objects.push(obj)
+    } else {
+      groups.push({ keys, objects: [obj] })
+    }
+  }
+  return groups
+}
+let opts = {}
+let depth = 0
+const ind = () => (opts.pretty ? (opts.indent ?? "  ").repeat(depth) : "")
+function stringifyValue(value, atLineStart = false) {
+  if (value === null) {
+    return "null"
+  }
+  if (typeof value === "boolean") {
+    return String(value)
+  }
+  if (typeof value === "number") {
+    return String(value)
+  }
+  if (typeof value === "string") {
+    return quote(value)
+  }
+  if (Array.isArray(value)) {
+    return stringifyArray(value)
+  }
+  if (typeof value === "object") {
+    return stringifyObject(value, atLineStart)
+  }
+  return String(value)
+}
+function stringifyArray(arr) {
+  const isTable = arr.length >= 2 && arr.every((i) => i !== null && typeof i === "object" && !Array.isArray(i))
+  if (isTable) {
+    const groups = groupBySchema(arr)
+    if (groups.some((g) => g.objects.length >= 2)) {
+      return stringifyTable(groups)
+    }
+  }
+  if (arr.length === 1) {
+    return `[${stringifyValue(arr[0])}]`
+  }
+  const hasComplex = arr.some((i) => i !== null && typeof i === "object")
+  if (opts.pretty && arr.length > 0 && hasComplex) {
+    depth++
+    const items = arr.map((i) => `${ind()}${stringifyValue(i, true)}`)
+    depth--
+    return `[\n${items.join(",\n")}\n${ind()}]`
+  }
+  const sep = opts.pretty ? ", " : ","
+  const items = arr.map((v) => stringifyValue(v)).join(sep)
+  return opts.pretty ? `[ ${items} ]` : `[${items}]`
+}
+function stringifyTable(groups) {
+  const sep = opts.pretty ? ", " : ","
+  if (opts.pretty) {
+    depth++
+    const schemaInd = ind()
+    depth++
+    const dataInd = ind()
+    const rows = []
+    for (const { keys, objects } of groups) {
+      rows.push(`${schemaInd}:${keys.map((k) => quoteKey(k)).join(sep)}`)
+      for (const obj of objects) rows.push(`${dataInd}${keys.map((k) => stringifyValue(obj[k])).join(sep)}`)
+    }
+    depth -= 2
+    return `{{\n${rows.join("\n")}\n${ind()}}}`
+  }
+  const parts = []
+  for (const { keys, objects } of groups) {
+    parts.push(`:${keys.map((k) => quoteKey(k)).join(sep)}`)
+    for (const obj of objects) {
+      parts.push(keys.map((k) => stringifyValue(obj[k])).join(sep))
+    }
+  }
+  return `{{${parts.join(";")}}}`
+}
+function stringifyObject(obj, atLineStart = false) {
+  const keys = Object.keys(obj)
+  const pair = (k, pretty) => {
+    const val = obj[k]
+    if (!needsQuotes(k, ["."]) && val !== null && typeof val === "object" && !Array.isArray(val)) {
+      const fold = getFoldPath(val)
+      if (fold) {
+        const foldedKey = `${k}.${fold.path.join(".")}`
+        return pretty ? `${foldedKey}: ${stringifyValue(fold.leaf)}` : `${foldedKey}:${stringifyValue(fold.leaf)}`
+      }
+    }
+    const qk = quoteKey(k)
+    return pretty ? `${qk}: ${stringifyValue(val)}` : `${qk}:${stringifyValue(val)}`
+  }
+  if (opts.pretty && keys.length > 1) {
+    depth++
+    const rawPairs = keys.map((k) => pair(k, true))
+    const lastMulti = rawPairs.at(-1)?.endsWith("}") || rawPairs.at(-1)?.endsWith("]")
+    const compact = atLineStart && !lastMulti
+    const pairs = rawPairs.map((p, i) => (i === 0 && compact ? p : `${ind()}${p}`))
+    depth--
+    return compact ? `{ ${pairs.join(",\n")} }` : `{\n${pairs.join(",\n")}\n${ind()}}`
+  }
+  if (opts.pretty && keys.length === 1) {
+    return `{ ${pair(keys[0], true)} }`
+  }
+  return `{${keys.map((k) => pair(k, false)).join(",")}}`
+}
+function stringify(data, options = {}) {
+  opts = { pretty: false, indent: "  ", ...options }
+  depth = 0
+  return stringifyValue(data)
+}
+// Parser
+class JotParser {
+  input
+  pos = 0
+  constructor(input) {
+    this.input = input
+  }
+  parse() {
+    this.ws()
+    const result = this.value("")
+    this.ws()
+    if (this.pos < this.input.length) {
+      throw new Error(`Unexpected character at position ${this.pos}: '${this.input[this.pos]}'`)
+    }
+    return result
+  }
+  ws() {
+    while (this.pos < this.input.length && WS_RE.test(this.input[this.pos])) this.pos++
+  }
+  peek = () => this.input[this.pos] || ""
+  value(terminators = "") {
+    this.ws()
+    const ch = this.peek()
+    if (ch === "{") {
+      return this.input[this.pos + 1] === "{" ? this.table() : this.object()
+    }
+    if (ch === "[") {
+      return this.array()
+    }
+    if (ch === '"') {
+      return this.quoted()
+    }
+    return this.atom(terminators)
+  }
+  quoted() {
+    this.pos++
+    let result = ""
+    while (this.pos < this.input.length) {
+      const ch = this.input[this.pos]
+      if (ch === '"') {
+        this.pos++
+        return result
+      }
+      if (ch === "\\") {
+        this.pos++
+        const esc = this.input[this.pos]
+        const escMap = {
+          '"': '"',
+          "\\": "\\",
+          "/": "/",
+          b: "\b",
+          f: "\f",
+          n: "\n",
+          r: "\r",
+          t: "\t",
+        }
+        if (esc in escMap) {
+          result += escMap[esc]
+        } else if (esc === "u") {
+          result += String.fromCharCode(Number.parseInt(this.input.slice(this.pos + 1, this.pos + 5), 16))
+          this.pos += 4
+        } else {
+          throw new Error(`Invalid escape sequence '\\${esc}'`)
+        }
+      } else {
+        result += ch
+      }
+      this.pos++
+    }
+    throw new Error("Unterminated string")
+  }
+  parseToken(terminators) {
+    const start = this.pos
+    if (terminators === "") {
+      const token = this.input.slice(start).trim()
+      this.pos = this.input.length
+      if (token === "") {
+        throw new Error(`Unexpected end of input at position ${start}`)
+      }
+      return token
+    }
+    while (this.pos < this.input.length && !terminators.includes(this.input[this.pos])) {
+      this.pos++
+    }
+    const token = this.input.slice(start, this.pos).trim()
+    if (token === "") {
+      throw new Error(`Unexpected character at position ${this.pos}: '${this.peek()}'`)
+    }
+    return token
+  }
+  tokenToValue(token) {
+    if (token === "null") {
+      return null
+    }
+    if (token === "true") {
+      return true
+    }
+    if (token === "false") {
+      return false
+    }
+    const num = Number(token)
+    if (!Number.isNaN(num) && token !== "") {
+      return num
+    }
+    return token
+  }
+  atom(terminators) {
+    return this.tokenToValue(this.parseToken(terminators))
+  }
+  array() {
+    this.pos++
+    const result = []
+    this.ws()
+    while (this.peek() !== "]") {
+      if (this.pos >= this.input.length) {
+        throw new Error("Unterminated array")
+      }
+      result.push(this.value(",]"))
+      this.ws()
+      if (this.peek() === ",") {
+        this.pos++
+        this.ws()
+      }
+    }
+    this.pos++
+    return result
+  }
+  table() {
+    this.pos += 2
+    const result = []
+    let schema = []
+    this.ws()
+    while (this.input.slice(this.pos, this.pos + 2) !== "}}") {
+      if (this.pos >= this.input.length) {
+        throw new Error("Unterminated table")
+      }
+      this.ws()
+      if (this.peek() === ":") {
+        this.pos++
+        schema = this.schemaRow()
+      } else {
+        if (schema.length === 0) {
+          throw new Error(`Data row without schema at position ${this.pos}`)
+        }
+        const values = this.dataRow(schema.length)
+        const obj = {}
+        for (let i = 0; i < schema.length; i++) {
+          obj[schema[i]] = values[i]
+        }
+        result.push(obj)
+      }
+      this.ws()
+      if (this.peek() === ";") {
+        this.pos++
+        this.ws()
+      }
+    }
+    this.pos += 2
+    return result
+  }
+  schemaRow() {
+    const cols = []
+    let col = ""
+    while (this.pos < this.input.length) {
+      const ch = this.input[this.pos]
+      if ((ch === "}" && this.input[this.pos + 1] === "}") || ch === ";" || ch === "\n") {
+        if (col.trim()) {
+          cols.push(col.trim())
+        }
+        break
+      }
+      if (ch === ",") {
+        if (col.trim()) {
+          cols.push(col.trim())
+        }
+        col = ""
+        this.pos++
+        continue
+      }
+      col += ch
+      this.pos++
+    }
+    return cols
+  }
+  dataRow(colCount) {
+    const values = []
+    for (let i = 0; i < colCount; i++) {
+      this.ws()
+      values.push(this.tableValue(i < colCount - 1 ? ",;}\n" : ";}\n"))
+      this.ws()
+      if (this.peek() === ",") {
+        this.pos++
+      }
+    }
+    return values
+  }
+  tableValue(terminators) {
+    this.ws()
+    const ch = this.peek()
+    if (ch === '"') {
+      return this.quoted()
+    }
+    if (ch === "{") {
+      return this.input[this.pos + 1] === "{" ? this.table() : this.object()
+    }
+    if (ch === "[") {
+      return this.array()
+    }
+    const start = this.pos
+    while (this.pos < this.input.length) {
+      const c = this.input[this.pos]
+      if ((c === "}" && this.input[this.pos + 1] === "}") || terminators.includes(c)) {
+        break
+      }
+      this.pos++
+    }
+    const token = this.input.slice(start, this.pos).trim()
+    return token === "" ? null : this.tokenToValue(token)
+  }
+  object() {
+    this.pos++
+    const result = {}
+    this.ws()
+    while (this.peek() !== "}") {
+      if (this.pos >= this.input.length) {
+        throw new Error("Unterminated object")
+      }
+      const { key, quoted } = this.parseKey()
+      this.ws()
+      if (this.peek() !== ":") {
+        throw new Error(`Expected ':' after key '${key}' at position ${this.pos}`)
+      }
+      this.pos++
+      const value = this.value(",}")
+      if (quoted) {
+        result[key] = value
+      } else {
+        this.merge(result, this.unfold(key, value))
+      }
+      this.ws()
+      if (this.peek() === ",") {
+        this.pos++
+        this.ws()
+      }
+    }
+    this.pos++
+    return result
+  }
+  parseKey() {
+    this.ws()
+    if (this.peek() === '"') {
+      return { key: this.quoted(), quoted: true }
+    }
+    const start = this.pos
+    while (this.pos < this.input.length && !KEY_TERM_RE.test(this.input[this.pos])) this.pos++
+    const key = this.input.slice(start, this.pos)
+    if (key === "") {
+      throw new Error(`Expected key at position ${this.pos}`)
+    }
+    return { key, quoted: false }
+  }
+  unfold(keyPath, value) {
+    const parts = keyPath.split(".")
+    const result = {}
+    let current = result
+    for (let i = 0; i < parts.length - 1; i++) {
+      const nested = {}
+      current[parts[i]] = nested
+      current = nested
+    }
+    current[parts.at(-1)] = value
+    return result
+  }
+  merge(target, src) {
+    for (const key of Object.keys(src)) {
+      const tv = target[key]
+      const sv = src[key]
+      if (
+        key in target &&
+        typeof tv === "object" &&
+        tv !== null &&
+        !Array.isArray(tv) &&
+        typeof sv === "object" &&
+        sv !== null &&
+        !Array.isArray(sv)
+      ) {
+        this.merge(tv, sv)
+      } else {
+        target[key] = sv
+      }
+    }
+  }
+}
+function parse(input) {
+  return new JotParser(input).parse()
+}

package/dist/jot.d.ts

@@ -0,0 +1,6 @@
+export interface StringifyOptions {
+  pretty?: boolean
+  indent?: string
+}
+export declare function stringify(data: unknown, options?: StringifyOptions): string
+export declare function parse(input: string): unknown