koda-format 1.0.0

package/dist/stringify.js

@@ -0,0 +1,88 @@
+/**
+ * KODA value to text (.koda). Produces compact, human-readable output.
+ * Keys that are valid identifiers are emitted unquoted; strings quoted when necessary.
+ */
+function needsQuote(s) {
+    if (s.length === 0)
+        return true;
+    const first = s[0];
+    if (!/[\w_]/.test(first) && first !== '_')
+        return true;
+    for (let i = 1; i < s.length; i++) {
+        if (!/[\w\-_]/.test(s[i]))
+            return true;
+    }
+    const lower = s.toLowerCase();
+    if (lower === 'true' || lower === 'false' || lower === 'null')
+        return true;
+    return false;
+}
+function escapeDouble(s) {
+    return s
+        .replace(/\\/g, '\\\\')
+        .replace(/"/g, '\\"')
+        .replace(/\b/g, '\\b')
+        .replace(/\f/g, '\\f')
+        .replace(/\n/g, '\\n')
+        .replace(/\r/g, '\\r')
+        .replace(/\t/g, '\\t');
+}
+function quoteKey(key) {
+    if (needsQuote(key))
+        return `"${escapeDouble(key)}"`;
+    return key;
+}
+function quoteValueString(s) {
+    if (needsQuote(s))
+        return `"${escapeDouble(s)}"`;
+    return s;
+}
+function writeNumber(n) {
+    if (Number.isInteger(n) && n >= Number.MIN_SAFE_INTEGER && n <= Number.MAX_SAFE_INTEGER) {
+        return String(n);
+    }
+    return JSON.stringify(n);
+}
+function stringifyValue(value, indent, newline, level) {
+    if (value === null)
+        return 'null';
+    if (value === true)
+        return 'true';
+    if (value === false)
+        return 'false';
+    if (typeof value === 'number')
+        return writeNumber(value);
+    if (typeof value === 'string')
+        return quoteValueString(value);
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return '[]';
+        const nextPrefix = indent.repeat(level + 1);
+        const sep = indent ? newline + nextPrefix : ' ';
+        const inner = value
+            .map((v) => stringifyValue(v, indent, newline, level + 1))
+            .join(sep);
+        return `[${sep}${inner} ]`;
+    }
+    const obj = value;
+    const keys = Object.keys(obj);
+    if (keys.length === 0)
+        return '{}';
+    const nextPrefix = indent.repeat(level + 1);
+    const sep = indent ? newline + nextPrefix : ' ';
+    const pairs = keys.map((k) => {
+        const keyPart = quoteKey(k) + ':';
+        const valuePart = stringifyValue(obj[k], indent, newline, level + 1);
+        return `${keyPart} ${valuePart}`;
+    });
+    return `{${sep}${pairs.join(sep)} }`;
+}
+/**
+ * Serialize a KODA value to text format.
+ */
+export function stringify(value, options = {}) {
+    const indent = options.indent ?? '';
+    const newline = options.newline ?? '\n';
+    return stringifyValue(value, indent, newline, 0).trim();
+}
+//# sourceMappingURL=stringify.js.map

package/dist/stringify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stringify.js","sourceRoot":"","sources":["../src/stringify.ts"],"names":[],"mappings":"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"}

package/native/binding.cc

@@ -0,0 +1,174 @@
+#include <napi.h>
+#include <node_api.h>
+
+#include "koda_binary.h"
+#include "koda_parse.h"
+#include "koda_value.h"
+
+namespace koda {
+
+static Napi::Value ValueToNapi(const Value& v, const Napi::Env& env) {
+  switch (v.type) {
+    case Value::Type::Null:
+      return env.Null();
+    case Value::Type::Bool:
+      return Napi::Boolean::New(env, v.b);
+    case Value::Type::Int:
+      return Napi::Number::New(env, static_cast<double>(v.i));
+    case Value::Type::Float:
+      return Napi::Number::New(env, v.d);
+    case Value::Type::String:
+      return Napi::String::New(env, v.s);
+    case Value::Type::Array: {
+      Napi::Array arr = Napi::Array::New(env, v.arr.size());
+      for (size_t i = 0; i < v.arr.size(); ++i)
+        arr[static_cast<uint32_t>(i)] = ValueToNapi(v.arr[i], env);
+      return arr;
+    }
+    case Value::Type::Object: {
+      Napi::Object obj = Napi::Object::New(env);
+      for (const auto& p : v.obj)
+        obj.Set(p.first, ValueToNapi(p.second, env));
+      return obj;
+    }
+  }
+  return env.Null();
+}
+
+static Value NapiToValue(const Napi::Value& val) {
+  if (val.IsNull() || val.IsUndefined()) return Value::null_val();
+  if (val.IsBoolean()) return Value::bool_val(val.As<Napi::Boolean>().Value());
+  if (val.IsNumber()) {
+    Napi::Number n = val.As<Napi::Number>();
+    double d = n.DoubleValue();
+    if (d >= -9007199254740992.0 && d <= 9007199254740992.0) {
+      int64_t i = static_cast<int64_t>(d);
+      if (static_cast<double>(i) == d) return Value::int_val(i);
+    }
+    return Value::float_val(d);
+  }
+  if (val.IsString()) return Value::string_val(val.As<Napi::String>().Utf8Value());
+  if (val.IsArray()) {
+    Value v;
+    v.type = Value::Type::Array;
+    Napi::Array arr = val.As<Napi::Array>();
+    for (uint32_t i = 0; i < arr.Length(); ++i)
+      v.arr.push_back(NapiToValue(arr[i]));
+    return v;
+  }
+  if (val.IsObject()) {
+    Value v;
+    v.type = Value::Type::Object;
+    Napi::Object obj = val.As<Napi::Object>();
+    Napi::Array keys = obj.GetPropertyNames();
+    for (uint32_t i = 0; i < keys.Length(); ++i) {
+      Napi::Value k = keys[i];
+      std::string key = k.As<Napi::String>().Utf8Value();
+      v.obj.emplace_back(key, NapiToValue(obj.Get(key)));
+    }
+    return v;
+  }
+  return Value::null_val();
+}
+
+static Napi::Value NativeParse(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+  if (info.Length() < 1 || !info[0].IsString()) {
+    Napi::TypeError::New(env, "Expected string").ThrowAsJavaScriptException();
+    return env.Null();
+  }
+  std::string text = info[0].As<Napi::String>().Utf8Value();
+  size_t max_depth = 256;
+  if (info.Length() >= 2 && info[1].IsObject()) {
+    Napi::Object opts = info[1].As<Napi::Object>();
+    if (opts.Has("maxDepth")) {
+      Napi::Value v = opts.Get("maxDepth");
+      if (v.IsNumber()) max_depth = static_cast<size_t>(v.As<Napi::Number>().Uint32Value());
+    }
+  }
+  try {
+    Value v = parse(text, max_depth);
+    return ValueToNapi(v, env);
+  } catch (const std::exception& e) {
+    Napi::Error::New(env, e.what()).ThrowAsJavaScriptException();
+    return env.Null();
+  }
+}
+
+static Napi::Value NativeStringify(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+  if (info.Length() < 1) {
+    Napi::TypeError::New(env, "Expected value").ThrowAsJavaScriptException();
+    return env.Null();
+  }
+  try {
+    Value v = NapiToValue(info[0]);
+    return Napi::String::New(env, stringify(v));
+  } catch (const std::exception& e) {
+    Napi::Error::New(env, e.what()).ThrowAsJavaScriptException();
+    return env.Null();
+  }
+}
+
+static Napi::Value NativeEncode(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+  if (info.Length() < 1) {
+    Napi::TypeError::New(env, "Expected value").ThrowAsJavaScriptException();
+    return env.Null();
+  }
+  size_t max_depth = 256;
+  if (info.Length() >= 2 && info[1].IsObject()) {
+    Napi::Object opts = info[1].As<Napi::Object>();
+    if (opts.Has("maxDepth") && opts.Get("maxDepth").IsNumber())
+      max_depth = static_cast<size_t>(opts.Get("maxDepth").As<Napi::Number>().Uint32Value());
+  }
+  try {
+    Value v = NapiToValue(info[0]);
+    std::vector<uint8_t> buf = encode(v, max_depth);
+    Napi::Buffer<uint8_t> out = Napi::Buffer<uint8_t>::Copy(env, buf.data(), buf.size());
+    return out;
+  } catch (const std::exception& e) {
+    Napi::Error::New(env, e.what()).ThrowAsJavaScriptException();
+    return env.Null();
+  }
+}
+
+static Napi::Value NativeDecode(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+  if (info.Length() < 1 || !info[0].IsBuffer()) {
+    Napi::TypeError::New(env, "Expected Buffer").ThrowAsJavaScriptException();
+    return env.Null();
+  }
+  Napi::Buffer<uint8_t> buf = info[0].As<Napi::Buffer<uint8_t>>();
+  size_t max_depth = 256;
+  size_t max_dict = 65536;
+  size_t max_str = 1000000;
+  if (info.Length() >= 2 && info[1].IsObject()) {
+    Napi::Object opts = info[1].As<Napi::Object>();
+    if (opts.Has("maxDepth") && opts.Get("maxDepth").IsNumber())
+      max_depth = static_cast<size_t>(opts.Get("maxDepth").As<Napi::Number>().Uint32Value());
+    if (opts.Has("maxDictionarySize") && opts.Get("maxDictionarySize").IsNumber())
+      max_dict = static_cast<size_t>(opts.Get("maxDictionarySize").As<Napi::Number>().Uint32Value());
+    if (opts.Has("maxStringLength") && opts.Get("maxStringLength").IsNumber())
+      max_str = static_cast<size_t>(opts.Get("maxStringLength").As<Napi::Number>().Uint32Value());
+  }
+  try {
+    Value v = decode(buf.Data(), buf.ByteLength(), max_depth, max_dict, max_str);
+    return ValueToNapi(v, env);
+  } catch (const std::exception& e) {
+    Napi::Error::New(env, e.what()).ThrowAsJavaScriptException();
+    return env.Null();
+  }
+}
+
+}  // namespace koda
+
+static Napi::Object Init(Napi::Env env, Napi::Object exports) {
+  exports.Set("parse", Napi::Function::New(env, koda::NativeParse));
+  exports.Set("stringify", Napi::Function::New(env, koda::NativeStringify));
+  exports.Set("encode", Napi::Function::New(env, koda::NativeEncode));
+  exports.Set("decode", Napi::Function::New(env, koda::NativeDecode));
+  return exports;
+}
+
+NODE_API_MODULE(koda_format, Init)

package/native/koda_binary.cc

@@ -0,0 +1,256 @@
+#include "koda_binary.h"
+
+#include <algorithm>
+#include <stdexcept>
+#include <set>
+
+namespace koda {
+
+namespace {
+
+void collect_keys(const Value& v, std::set<std::string>& out) {
+  switch (v.type) {
+    case Value::Type::Null:
+    case Value::Type::Bool:
+    case Value::Type::Int:
+    case Value::Type::Float:
+    case Value::Type::String:
+      break;
+    case Value::Type::Array:
+      for (const auto& el : v.arr) collect_keys(el, out);
+      break;
+    case Value::Type::Object:
+      for (const auto& p : v.obj) {
+        out.insert(p.first);
+        collect_keys(p.second, out);
+      }
+      break;
+  }
+}
+
+struct Encoder {
+  std::vector<uint8_t> buf;
+  size_t max_depth;
+  std::vector<std::string> dictionary;
+  std::map<std::string, size_t> key_to_index;
+
+  void u8(uint8_t x) { buf.push_back(x); }
+  void u32_be(uint32_t x) {
+    buf.push_back((x >> 24) & 0xFF);
+    buf.push_back((x >> 16) & 0xFF);
+    buf.push_back((x >> 8) & 0xFF);
+    buf.push_back(x & 0xFF);
+  }
+  void i64_be(int64_t x) {
+    for (int i = 7; i >= 0; --i) buf.push_back((x >> (i * 8)) & 0xFF);
+  }
+  void f64_be(double x) {
+    uint64_t u;
+    memcpy(&u, &x, 8);
+    for (int i = 7; i >= 0; --i) buf.push_back((u >> (i * 8)) & 0xFF);
+  }
+  void bytes(const uint8_t* p, size_t n) {
+    for (size_t i = 0; i < n; ++i) buf.push_back(p[i]);
+  }
+
+  void encode_value(const Value& v, size_t depth) {
+    if (depth > max_depth) throw std::runtime_error("Maximum nesting depth exceeded");
+    switch (v.type) {
+      case Value::Type::Null:
+        u8(TAG_NULL);
+        break;
+      case Value::Type::Bool:
+        u8(v.b ? TAG_TRUE : TAG_FALSE);
+        break;
+      case Value::Type::Int:
+        u8(TAG_INTEGER);
+        i64_be(v.i);
+        break;
+      case Value::Type::Float:
+        u8(TAG_FLOAT);
+        f64_be(v.d);
+        break;
+      case Value::Type::String:
+        u8(TAG_STRING);
+        u32_be(static_cast<uint32_t>(v.s.size()));
+        bytes(reinterpret_cast<const uint8_t*>(v.s.data()), v.s.size());
+        break;
+      case Value::Type::Array:
+        u8(TAG_ARRAY);
+        u32_be(static_cast<uint32_t>(v.arr.size()));
+        for (const auto& el : v.arr) encode_value(el, depth + 1);
+        break;
+      case Value::Type::Object: {
+        u8(TAG_OBJECT);
+        std::vector<std::pair<std::string, Value>> sorted = v.obj;
+        std::sort(sorted.begin(), sorted.end(),
+                  [](const auto& a, const auto& b) { return a.first < b.first; });
+        u32_be(static_cast<uint32_t>(sorted.size()));
+        for (const auto& p : sorted) {
+          auto it = key_to_index.find(p.first);
+          if (it == key_to_index.end()) throw std::runtime_error("Key not in dictionary");
+          u32_be(static_cast<uint32_t>(it->second));
+          encode_value(p.second, depth + 1);
+        }
+        break;
+      }
+    }
+  }
+};
+
+}  // namespace
+
+std::vector<uint8_t> encode(const Value& value, size_t max_depth) {
+  std::set<std::string> keys_set;
+  collect_keys(value, keys_set);
+  std::vector<std::string> dictionary(keys_set.begin(), keys_set.end());
+  std::map<std::string, size_t> key_to_index;
+  for (size_t i = 0; i < dictionary.size(); ++i) key_to_index[dictionary[i]] = i;
+
+  Encoder enc;
+  enc.max_depth = max_depth;
+  enc.dictionary = std::move(dictionary);
+  enc.key_to_index = std::move(key_to_index);
+
+  enc.bytes(MAGIC, 4);
+  enc.u8(VERSION);
+  enc.u32_be(static_cast<uint32_t>(enc.dictionary.size()));
+  for (const auto& k : enc.dictionary) {
+    enc.u32_be(static_cast<uint32_t>(k.size()));
+    enc.bytes(reinterpret_cast<const uint8_t*>(k.data()), k.size());
+  }
+  enc.encode_value(value, 0);
+  return enc.buf;
+}
+
+namespace {
+
+struct Decoder {
+  const uint8_t* data;
+  size_t size;
+  size_t offset = 0;
+  size_t max_depth;
+  size_t max_dict;
+  size_t max_str;
+  std::vector<std::string> dictionary;
+
+  void ensure(size_t n) {
+    if (offset + n > size) throw std::runtime_error("Truncated input");
+  }
+  uint8_t u8() {
+    ensure(1);
+    return data[offset++];
+  }
+  uint32_t u32_be() {
+    ensure(4);
+    uint32_t x = (static_cast<uint32_t>(data[offset]) << 24) |
+                 (static_cast<uint32_t>(data[offset + 1]) << 16) |
+                 (static_cast<uint32_t>(data[offset + 2]) << 8) |
+                 data[offset + 3];
+    offset += 4;
+    return x;
+  }
+  int64_t i64_be() {
+    ensure(8);
+    uint64_t u = 0;
+    for (int i = 0; i < 8; ++i) u = (u << 8) | data[offset + i];
+    offset += 8;
+    int64_t x;
+    memcpy(&x, &u, 8);
+    return x;
+  }
+  double f64_be() {
+    ensure(8);
+    uint64_t u = 0;
+    for (int i = 0; i < 8; ++i) u = (u << 8) | data[offset + i];
+    offset += 8;
+    double x;
+    memcpy(&x, &u, 8);
+    return x;
+  }
+
+  Value decode_value(size_t depth) {
+    if (depth > max_depth) throw std::runtime_error("Maximum nesting depth exceeded");
+    ensure(1);
+    uint8_t tag = u8();
+    switch (tag) {
+      case TAG_NULL:
+        return Value::null_val();
+      case TAG_FALSE:
+        return Value::bool_val(false);
+      case TAG_TRUE:
+        return Value::bool_val(true);
+      case TAG_INTEGER:
+        return Value::int_val(i64_be());
+      case TAG_FLOAT:
+        return Value::float_val(f64_be());
+      case TAG_STRING: {
+        uint32_t len = u32_be();
+        if (len > max_str) throw std::runtime_error("String too long");
+        ensure(len);
+        std::string s(reinterpret_cast<const char*>(data + offset), len);
+        offset += len;
+        return Value::string_val(std::move(s));
+      }
+      case TAG_BINARY:
+        throw std::runtime_error("Binary type not supported");
+      case TAG_ARRAY: {
+        Value v;
+        v.type = Value::Type::Array;
+        uint32_t n = u32_be();
+        v.arr.reserve(n);
+        for (uint32_t i = 0; i < n; ++i) v.arr.push_back(decode_value(depth + 1));
+        return v;
+      }
+      case TAG_OBJECT: {
+        Value v;
+        v.type = Value::Type::Object;
+        uint32_t n = u32_be();
+        for (uint32_t i = 0; i < n; ++i) {
+          uint32_t idx = u32_be();
+          if (idx >= dictionary.size()) throw std::runtime_error("Invalid key index");
+          v.obj.emplace_back(dictionary[idx], decode_value(depth + 1));
+        }
+        return v;
+      }
+      default:
+        throw std::runtime_error("Unknown type tag");
+    }
+  }
+};
+
+}  // namespace
+
+Value decode(const uint8_t* data, size_t size, size_t max_depth, size_t max_dict,
+             size_t max_str_len) {
+  Decoder dec;
+  dec.data = data;
+  dec.size = size;
+  dec.max_depth = max_depth;
+  dec.max_dict = max_dict;
+  dec.max_str = max_str_len;
+
+  dec.ensure(5);
+  for (int i = 0; i < 4; ++i)
+    if (dec.data[i] != MAGIC[i]) throw std::runtime_error("Invalid magic number");
+  dec.offset = 4;
+  uint8_t version = dec.u8();
+  if (version != VERSION) throw std::runtime_error("Unsupported version");
+
+  uint32_t dict_len = dec.u32_be();
+  if (dict_len > max_dict) throw std::runtime_error("Dictionary too large");
+  dec.dictionary.reserve(dict_len);
+  for (uint32_t i = 0; i < dict_len; ++i) {
+    uint32_t key_len = dec.u32_be();
+    if (key_len > max_str_len) throw std::runtime_error("Key string too long");
+    dec.ensure(key_len);
+    dec.dictionary.emplace_back(reinterpret_cast<const char*>(dec.data + dec.offset), key_len);
+    dec.offset += key_len;
+  }
+
+  Value v = dec.decode_value(0);
+  if (dec.offset != size) throw std::runtime_error("Trailing bytes after root value");
+  return v;
+}
+
+}  // namespace koda

package/native/koda_binary.h

@@ -0,0 +1,36 @@
+#ifndef KODA_BINARY_H
+#define KODA_BINARY_H
+
+#include <cstddef>
+#include <cstdint>
+#include <string>
+#include <vector>
+
+#include "koda_value.h"
+
+namespace koda {
+
+// Binary format constants (SPEC §6)
+constexpr uint8_t MAGIC[] = {0x4B, 0x4F, 0x44, 0x41};
+constexpr uint8_t VERSION = 1;
+
+constexpr uint8_t TAG_NULL = 0x01;
+constexpr uint8_t TAG_FALSE = 0x02;
+constexpr uint8_t TAG_TRUE = 0x03;
+constexpr uint8_t TAG_INTEGER = 0x04;
+constexpr uint8_t TAG_FLOAT = 0x05;
+constexpr uint8_t TAG_STRING = 0x06;
+constexpr uint8_t TAG_BINARY = 0x07;
+constexpr uint8_t TAG_ARRAY = 0x10;
+constexpr uint8_t TAG_OBJECT = 0x11;
+
+// Encode value to canonical binary. Throws std::runtime_error on depth exceed.
+std::vector<uint8_t> encode(const Value& value, size_t max_depth = 256);
+
+// Decode binary to value. Throws std::runtime_error on invalid input.
+Value decode(const uint8_t* data, size_t size, size_t max_depth = 256,
+             size_t max_dict = 65536, size_t max_str_len = 1000000);
+
+}  // namespace koda
+
+#endif