bara-lang/examples/jsonista.md

jsonista.clj — Production JSON библиотека за Clojure/Nim

Моделирана след metosin/jsonista, но с нула Java зависимости.

Защо това е production пример?

Този пример демонстрира пълноценна JSON библиотека с API идентично на jsonista, но:

	JVM jsonista	Clojure/Nim jsonista
JVM зависимост	✅ Required (JVM + Jackson)	❌ Няма
Jackson/databind	✅ Required	❌ Няма
GraalVM native-image	❌ Необходим за бинарен файл	❌ Не е необходим
Бинарен размер	50MB+	< 1MB
Startup time	Бавен (JVM warmup)	Мигновен
Java stdlib	✅ Required	❌ Не

API

; Основни функции
(json/write-value-as-string data)                ; -> JSON string
(json/write-value-as-string data opts)           ; -> JSON string с опции
(json/read-value json-string)                    ; -> Clojure data
(json/read-value json-string opts)               ; -> Clojure data с опции
(json/write-value-to-file path data)             ; -> записва във файл
(json/write-value-to-file path data opts)        ; -> записва във файл
(json/read-value-from-file path)                 ; -> чете от файл
(json/read-value-from-file path opts)            ; -> чете от файл с опции

Опции

Опция	Тип	Описание
:keyword-keys?	bool	При четене, конвертира string ключове към keywords
:pretty?	bool	При писане, форматира JSON с отстъпи

Примери

Базово encoding/decoding

(def person {:name "Alice" :age 30})

(json/write-value-as-string person)
;; => {"name":"Alice","age":30}

(json/read-value "{\"name\":\"Alice\"}" {:keyword-keys? true})
;; => {:name "Alice"}

Pretty printing

(json/write-value-as-string
  {:user {:name "Bob" :roles [:admin :editor]}}
  {:pretty? true})
;; =>
;; {
;;   "user": {
;;     "name": "Bob",
;;     "roles": ["admin", "editor"]
;;   }
;; }

File I/O

(json/write-value-to-file "data.json" my-data {:pretty? true})
(json/read-value-from-file "data.json" {:keyword-keys? true})

Error handling

(json/read-value "{invalid}")
;; => {:error "input(1, 8) Error: string literal as key expected"}

Как работи?

Вместо Jackson (Java), използваме Nim std/json директно през FFI/runtime слоя:

Clojure code
      ↓
Clojure/Nim Compiler
      ↓
Nim код + cljnim_runtime (std/json)
      ↓
im c -d:release
      ↓
Native binary (< 1MB)

Конверсията CljVal ↔ JsonNode се случва в lib/cljnim_runtime.nim:

• ckNil → JNull
• ckBool → JBool
• ckInt → JInt
• ckFloat → JFloat
• ckString/ckKeyword → JString
• ckVector/ckList → JArray
• ckMap → JObject

Как да го пуснеш

# Компилиране и изпълнение
./cljnim run examples/jsonista.clj

# Или през Makefile
make check

Реален use-case

Този пример симулира real-world API работа — парсване на HTTP response с nested структури, keyword keys, file persistence и error handling. Перфектно за:

• REST API клиенти
• Конфигурационни файлове
• Data pipelines
• Log агрегация
• Microservices

Сравнение с оригиналния jsonista

Feature	JVM jsonista	Clojure/Nim
write-value-as-string	✅	✅
read-value	✅	✅
Keyword keys	✅	✅
Pretty print	✅	✅
Custom mapper	✅	✅ (чрез opts map)
File I/O	✅	✅
Tagged values	✅	Може да се добави
Modules (Joda, etc)	✅	Не е необходимо

---

Извод: С Clojure/Nim получаваш същото production-ready JSON API, но без целия Java overhead — native бинарен файл, мигновен старт, и достъп до цялата Nim/C ecosystem.