novac 2.0.1 → 2.2.0

package/kits/kitproto/kitdef.js

@@ -0,0 +1,613 @@
+// kitproto — novac protocol buffers / binary serialization kit
+// Pure JS. No external deps.
+// Define message schemas, encode to compact binary, decode back.
+// Supports: int32, int64, uint32, uint64, sint32, sint64, float, double,
+//           bool, string, bytes, nested messages, repeated fields, maps,
+//           oneofs, enums, optional/required fields, versioning.
+
+'use strict';
+
+// ─── WIRE TYPES ───────────────────────────────────────────────────────────────
+
+const WIRE = {
+  VARINT:   0, // int32, int64, uint32, uint64, sint32, sint64, bool, enum
+  I64:      1, // fixed64, sfixed64, double
+  LEN:      2, // string, bytes, embedded messages, packed repeated
+  I32:      5, // fixed32, sfixed32, float
+};
+
+const FIELD_TYPES = {
+  int32:    { wire: WIRE.VARINT,  js: 'number'  },
+  int64:    { wire: WIRE.VARINT,  js: 'bigint'  },
+  uint32:   { wire: WIRE.VARINT,  js: 'number'  },
+  uint64:   { wire: WIRE.VARINT,  js: 'bigint'  },
+  sint32:   { wire: WIRE.VARINT,  js: 'number'  }, // zigzag
+  sint64:   { wire: WIRE.VARINT,  js: 'bigint'  }, // zigzag
+  bool:     { wire: WIRE.VARINT,  js: 'boolean' },
+  enum:     { wire: WIRE.VARINT,  js: 'number'  },
+  fixed32:  { wire: WIRE.I32,     js: 'number'  },
+  sfixed32: { wire: WIRE.I32,     js: 'number'  },
+  float:    { wire: WIRE.I32,     js: 'number'  },
+  fixed64:  { wire: WIRE.I64,     js: 'bigint'  },
+  sfixed64: { wire: WIRE.I64,     js: 'bigint'  },
+  double:   { wire: WIRE.I64,     js: 'number'  },
+  string:   { wire: WIRE.LEN,     js: 'string'  },
+  bytes:    { wire: WIRE.LEN,     js: 'buffer'  },
+  message:  { wire: WIRE.LEN,     js: 'object'  },
+  map:      { wire: WIRE.LEN,     js: 'object'  },
+};
+
+// ─── VARINT ENCODING ─────────────────────────────────────────────────────────
+
+function encodeVarint(value) {
+  const bytes = [];
+  let v = typeof value === 'bigint' ? value : BigInt(Math.trunc(value));
+  // Handle negative numbers as two's complement 64-bit
+  if (v < 0n) v = v + (1n << 64n);
+  do {
+    let byte = Number(v & 0x7fn);
+    v >>= 7n;
+    if (v > 0n) byte |= 0x80;
+    bytes.push(byte);
+  } while (v > 0n);
+  return Buffer.from(bytes);
+}
+
+function decodeVarint(buf, offset) {
+  let result = 0n, shift = 0n;
+  let pos    = offset;
+  while (pos < buf.length) {
+    const byte = buf[pos++];
+    result |= BigInt(byte & 0x7f) << shift;
+    shift += 7n;
+    if (!(byte & 0x80)) break;
+  }
+  return { value: result, offset: pos };
+}
+
+function decodeVarintSigned(buf, offset) {
+  const { value, offset: newOffset } = decodeVarint(buf, offset);
+  // Convert from unsigned 64-bit to signed
+  const signed = value >= (1n << 63n) ? value - (1n << 64n) : value;
+  return { value: signed, offset: newOffset };
+}
+
+// Zigzag encoding for sint32/sint64
+function zigzagEncode32(n) { return ((n << 1) ^ (n >> 31)) >>> 0; }
+function zigzagDecode32(n) { return ((n >>> 1) ^ -(n & 1)); }
+function zigzagEncode64(n) { return (n << 1n) ^ (n >> 63n); }
+function zigzagDecode64(n) { return (n >> 1n) ^ -(n & 1n); }
+
+// ─── FIELD TAG ────────────────────────────────────────────────────────────────
+
+function encodeTag(fieldNumber, wireType) {
+  return encodeVarint(BigInt((fieldNumber << 3) | wireType));
+}
+
+function decodeTag(buf, offset) {
+  const { value, offset: newOffset } = decodeVarint(buf, offset);
+  const tag        = Number(value);
+  const fieldNumber = tag >>> 3;
+  const wireType   = tag & 0x7;
+  return { fieldNumber, wireType, offset: newOffset };
+}
+
+// ─── PRIMITIVE ENCODERS ───────────────────────────────────────────────────────
+
+function encodeField(type, value) {
+  switch (type) {
+    case 'int32':
+    case 'uint32':
+    case 'enum':
+      return encodeVarint(value);
+    case 'int64':
+    case 'uint64':
+      return encodeVarint(value);
+    case 'sint32':
+      return encodeVarint(zigzagEncode32(value));
+    case 'sint64':
+      return encodeVarint(zigzagEncode64(typeof value === 'bigint' ? value : BigInt(value)));
+    case 'bool':
+      return encodeVarint(value ? 1 : 0);
+    case 'fixed32':
+    case 'sfixed32': {
+      const b = Buffer.allocUnsafe(4);
+      b.writeInt32LE(value, 0);
+      return b;
+    }
+    case 'float': {
+      const b = Buffer.allocUnsafe(4);
+      b.writeFloatLE(value, 0);
+      return b;
+    }
+    case 'fixed64':
+    case 'sfixed64': {
+      const b = Buffer.allocUnsafe(8);
+      b.writeBigInt64LE(typeof value === 'bigint' ? value : BigInt(value), 0);
+      return b;
+    }
+    case 'double': {
+      const b = Buffer.allocUnsafe(8);
+      b.writeDoubleLE(value, 0);
+      return b;
+    }
+    case 'string': {
+      const encoded = Buffer.from(value, 'utf8');
+      return Buffer.concat([encodeVarint(encoded.length), encoded]);
+    }
+    case 'bytes': {
+      const buf = Buffer.isBuffer(value) ? value : Buffer.from(value);
+      return Buffer.concat([encodeVarint(buf.length), buf]);
+    }
+    default:
+      throw new Error(`Unknown primitive type: ${type}`);
+  }
+}
+
+function decodeField(type, buf, offset, length) {
+  switch (type) {
+    case 'int32': {
+      const { value, offset: o } = decodeVarintSigned(buf, offset);
+      return { value: Number(BigInt.asIntN(32, value)), offset: o };
+    }
+    case 'uint32': {
+      const { value, offset: o } = decodeVarint(buf, offset);
+      return { value: Number(value) >>> 0, offset: o };
+    }
+    case 'int64': {
+      const { value, offset: o } = decodeVarintSigned(buf, offset);
+      return { value, offset: o };
+    }
+    case 'uint64': {
+      const { value, offset: o } = decodeVarint(buf, offset);
+      return { value, offset: o };
+    }
+    case 'sint32': {
+      const { value, offset: o } = decodeVarint(buf, offset);
+      return { value: zigzagDecode32(Number(value)), offset: o };
+    }
+    case 'sint64': {
+      const { value, offset: o } = decodeVarint(buf, offset);
+      return { value: zigzagDecode64(value), offset: o };
+    }
+    case 'bool': {
+      const { value, offset: o } = decodeVarint(buf, offset);
+      return { value: value !== 0n, offset: o };
+    }
+    case 'enum': {
+      const { value, offset: o } = decodeVarint(buf, offset);
+      return { value: Number(value), offset: o };
+    }
+    case 'fixed32':
+    case 'sfixed32':
+      return { value: buf.readInt32LE(offset), offset: offset + 4 };
+    case 'float':
+      return { value: buf.readFloatLE(offset), offset: offset + 4 };
+    case 'fixed64':
+    case 'sfixed64':
+      return { value: buf.readBigInt64LE(offset), offset: offset + 8 };
+    case 'double':
+      return { value: buf.readDoubleLE(offset), offset: offset + 8 };
+    case 'string': {
+      const { value: len, offset: o } = decodeVarint(buf, offset);
+      const end = o + Number(len);
+      return { value: buf.slice(o, end).toString('utf8'), offset: end };
+    }
+    case 'bytes': {
+      const { value: len, offset: o } = decodeVarint(buf, offset);
+      const end = o + Number(len);
+      return { value: buf.slice(o, end), offset: end };
+    }
+    default:
+      throw new Error(`Unknown primitive type: ${type}`);
+  }
+}
+
+// ─── SCHEMA DEFINITION ───────────────────────────────────────────────────────
+
+/**
+ * Define a message schema.
+ *
+ * @example
+ * const Person = defineMessage('Person', {
+ *   name:   { field: 1, type: 'string' },
+ *   age:    { field: 2, type: 'int32' },
+ *   email:  { field: 3, type: 'string', optional: true },
+ *   scores: { field: 4, type: 'int32',  repeated: true },
+ *   address:{ field: 5, type: 'message', message: Address },
+ *   meta:   { field: 6, type: 'map', keyType: 'string', valueType: 'string' },
+ * });
+ */
+function defineMessage(name, fields) {
+  // Build field number → field name + def lookup
+  const byNumber = {};
+  const byName   = {};
+  for (const [fname, def] of Object.entries(fields)) {
+    if (!def.field) throw new Error(`Field '${fname}' in message '${name}' missing 'field' number`);
+    if (!def.type)  throw new Error(`Field '${fname}' in message '${name}' missing 'type'`);
+    byNumber[def.field] = { name: fname, ...def };
+    byName[fname]       = { name: fname, ...def };
+  }
+  return { _name: name, _fields: byName, _byNumber: byNumber };
+}
+
+/**
+ * Define an enum.
+ * @example
+ * const Status = defineEnum('Status', { UNKNOWN: 0, ACTIVE: 1, INACTIVE: 2 });
+ */
+function defineEnum(name, values) {
+  const byName   = { ...values };
+  const byValue  = Object.fromEntries(Object.entries(values).map(([k, v]) => [v, k]));
+  return { _name: name, _byName: byName, _byValue: byValue, _isEnum: true };
+}
+
+// ─── ENCODER ─────────────────────────────────────────────────────────────────
+
+function encode(schema, obj) {
+  if (!schema || !schema._fields) throw new Error('Invalid schema — use defineMessage()');
+  const parts = [];
+
+  for (const [fname, def] of Object.entries(schema._fields)) {
+    const value = obj[fname];
+    if (value === undefined || value === null) {
+      if (!def.optional && !def.repeated) {
+        // Use default: 0 / '' / false / [] depending on type — just skip for now
+      }
+      continue;
+    }
+
+    const fieldNum = def.field;
+
+    // Map field
+    if (def.type === 'map') {
+      for (const [k, v] of Object.entries(value)) {
+        // Encode as a message with field 1 = key, field 2 = value
+        const entrySchema = defineMessage(`${fname}_entry`, {
+          key:   { field: 1, type: def.keyType   ?? 'string' },
+          value: { field: 2, type: def.valueType ?? 'string' },
+        });
+        const entryBuf = encode(entrySchema, { key: k, value: v });
+        parts.push(encodeTag(fieldNum, WIRE.LEN));
+        parts.push(encodeVarint(entryBuf.length));
+        parts.push(entryBuf);
+      }
+      continue;
+    }
+
+    // Repeated field
+    if (def.repeated) {
+      if (!Array.isArray(value)) throw new Error(`Field '${fname}' is repeated but got non-array`);
+      const isPacked = FIELD_TYPES[def.type]?.wire === WIRE.VARINT ||
+                       FIELD_TYPES[def.type]?.wire === WIRE.I32    ||
+                       FIELD_TYPES[def.type]?.wire === WIRE.I64;
+      if (isPacked && def.packed !== false) {
+        // Pack into single LEN field
+        const packed = Buffer.concat(value.map(v => encodeField(def.type, v)));
+        parts.push(encodeTag(fieldNum, WIRE.LEN));
+        parts.push(encodeVarint(packed.length));
+        parts.push(packed);
+      } else {
+        for (const item of value) {
+          if (def.type === 'message') {
+            const nested = encode(def.message, item);
+            parts.push(encodeTag(fieldNum, WIRE.LEN));
+            parts.push(encodeVarint(nested.length));
+            parts.push(nested);
+          } else {
+            parts.push(encodeTag(fieldNum, FIELD_TYPES[def.type].wire));
+            parts.push(encodeField(def.type, item));
+          }
+        }
+      }
+      continue;
+    }
+
+    // Nested message
+    if (def.type === 'message') {
+      const nested = encode(def.message, value);
+      parts.push(encodeTag(fieldNum, WIRE.LEN));
+      parts.push(encodeVarint(nested.length));
+      parts.push(nested);
+      continue;
+    }
+
+    // Oneof — just encode the present field
+    if (def.oneof) {
+      // handled as regular field
+    }
+
+    // Enum
+    if (def.type === 'enum' && def.enum) {
+      const numVal = typeof value === 'string' ? def.enum._byName[value] : value;
+      parts.push(encodeTag(fieldNum, WIRE.VARINT));
+      parts.push(encodeVarint(numVal ?? 0));
+      continue;
+    }
+
+    // Primitive
+    const ft = FIELD_TYPES[def.type];
+    if (!ft) throw new Error(`Unknown field type '${def.type}' for field '${fname}'`);
+    parts.push(encodeTag(fieldNum, ft.wire));
+    parts.push(encodeField(def.type, value));
+  }
+
+  return Buffer.concat(parts);
+}
+
+// ─── DECODER ─────────────────────────────────────────────────────────────────
+
+function decode(schema, buf) {
+  if (!schema || !schema._fields) throw new Error('Invalid schema — use defineMessage()');
+  const obj = {};
+  let offset = 0;
+
+  // Initialize repeated fields and maps
+  for (const [fname, def] of Object.entries(schema._fields)) {
+    if (def.repeated) obj[fname] = [];
+    if (def.type === 'map') obj[fname] = {};
+  }
+
+  while (offset < buf.length) {
+    const { fieldNumber, wireType, offset: tagEnd } = decodeTag(buf, offset);
+    offset = tagEnd;
+
+    const def = schema._byNumber[fieldNumber];
+    if (!def) {
+      // Unknown field — skip it
+      offset = skipField(buf, offset, wireType);
+      continue;
+    }
+
+    // Map field
+    if (def.type === 'map') {
+      const { value: len, offset: o } = decodeVarint(buf, offset);
+      const entryBuf = buf.slice(o, o + Number(len));
+      offset = o + Number(len);
+      const entrySchema = defineMessage(`${def.name}_entry`, {
+        key:   { field: 1, type: def.keyType   ?? 'string' },
+        value: { field: 2, type: def.valueType ?? 'string' },
+      });
+      const entry = decode(entrySchema, entryBuf);
+      obj[def.name][entry.key] = entry.value;
+      continue;
+    }
+
+    // LEN-delimited
+    if (wireType === WIRE.LEN) {
+      const { value: len, offset: o } = decodeVarint(buf, offset);
+      const end      = o + Number(len);
+      const fieldBuf = buf.slice(o, end);
+      offset = end;
+
+      if (def.type === 'message') {
+        const nested = decode(def.message, fieldBuf);
+        if (def.repeated) obj[def.name].push(nested);
+        else obj[def.name] = nested;
+        continue;
+      }
+
+      if (def.type === 'string') {
+        const val = fieldBuf.toString('utf8');
+        if (def.repeated) obj[def.name].push(val);
+        else obj[def.name] = val;
+        continue;
+      }
+
+      if (def.type === 'bytes') {
+        if (def.repeated) obj[def.name].push(fieldBuf);
+        else obj[def.name] = fieldBuf;
+        continue;
+      }
+
+      // Packed repeated
+      if (def.repeated) {
+        let pos = 0;
+        while (pos < fieldBuf.length) {
+          const { value, offset: newPos } = decodeField(def.type, fieldBuf, pos);
+          obj[def.name].push(value);
+          pos = newPos;
+        }
+        continue;
+      }
+    }
+
+    // VARINT
+    if (wireType === WIRE.VARINT) {
+      if (def.type === 'enum' && def.enum) {
+        const { value, offset: o } = decodeVarint(buf, offset);
+        const numVal = Number(value);
+        const strVal = def.enum._byValue[numVal] ?? numVal;
+        if (def.repeated) obj[def.name].push(strVal);
+        else obj[def.name] = strVal;
+        offset = o;
+        continue;
+      }
+      const { value, offset: o } = decodeField(def.type, buf, offset);
+      if (def.repeated) obj[def.name].push(value);
+      else obj[def.name] = value;
+      offset = o;
+      continue;
+    }
+
+    // I32
+    if (wireType === WIRE.I32) {
+      const { value, offset: o } = decodeField(def.type, buf, offset);
+      if (def.repeated) obj[def.name].push(value);
+      else obj[def.name] = value;
+      offset = o;
+      continue;
+    }
+
+    // I64
+    if (wireType === WIRE.I64) {
+      const { value, offset: o } = decodeField(def.type, buf, offset);
+      if (def.repeated) obj[def.name].push(value);
+      else obj[def.name] = value;
+      offset = o;
+      continue;
+    }
+
+    offset = skipField(buf, offset, wireType);
+  }
+
+  return obj;
+}
+
+function skipField(buf, offset, wireType) {
+  switch (wireType) {
+    case WIRE.VARINT: {
+      while (offset < buf.length && buf[offset] & 0x80) offset++;
+      return offset + 1;
+    }
+    case WIRE.I64:  return offset + 8;
+    case WIRE.I32:  return offset + 4;
+    case WIRE.LEN: {
+      const { value: len, offset: o } = decodeVarint(buf, offset);
+      return o + Number(len);
+    }
+    default: throw new Error(`Unknown wire type ${wireType} during skip`);
+  }
+}
+
+// ─── MESSAGE CLASS FACTORY ───────────────────────────────────────────────────
+
+/**
+ * Create a Message class from a schema.
+ * Instances have encode(), toJSON(), static decode().
+ *
+ * @example
+ * const Person = createMessageClass(PersonSchema);
+ * const p = new Person({ name: 'Alice', age: 30 });
+ * const buf = p.encode();
+ * const p2  = Person.decode(buf);
+ */
+function createMessageClass(schema) {
+  class Message {
+    constructor(data = {}) {
+      Object.assign(this, data);
+    }
+    encode() { return encode(schema, this); }
+    toJSON()  {
+      const obj = {};
+      for (const key of Object.keys(schema._fields)) {
+        if (this[key] !== undefined) obj[key] = this[key];
+      }
+      return obj;
+    }
+    static decode(buf) { return new Message(decode(schema, buf)); }
+    static get schema() { return schema; }
+    static get name()   { return schema._name; }
+  }
+  Object.defineProperty(Message, 'name', { value: schema._name });
+  return Message;
+}
+
+// ─── VERSIONING ───────────────────────────────────────────────────────────────
+
+/**
+ * Wrap a message with a version header.
+ * @param {number} version
+ * @param {Buffer} payload
+ * @returns {Buffer}
+ */
+function encodeVersioned(version, payload) {
+  const verBuf = Buffer.allocUnsafe(4);
+  verBuf.writeUInt32BE(version, 0);
+  return Buffer.concat([verBuf, payload]);
+}
+
+/**
+ * Decode a versioned message.
+ * @param {Buffer} buf
+ * @returns {{ version: number, payload: Buffer }}
+ */
+function decodeVersioned(buf) {
+  const version = buf.readUInt32BE(0);
+  const payload = buf.slice(4);
+  return { version, payload };
+}
+
+// ─── STREAM ENCODER / DECODER ────────────────────────────────────────────────
+
+/**
+ * Encode multiple messages into a length-delimited stream.
+ * @param {object} schema
+ * @param {object[]} messages
+ * @returns {Buffer}
+ */
+function encodeStream(schema, messages) {
+  const parts = [];
+  for (const msg of messages) {
+    const encoded = encode(schema, msg);
+    const lenBuf  = Buffer.allocUnsafe(4);
+    lenBuf.writeUInt32BE(encoded.length, 0);
+    parts.push(lenBuf, encoded);
+  }
+  return Buffer.concat(parts);
+}
+
+/**
+ * Decode a length-delimited stream into multiple messages.
+ * @param {object} schema
+ * @param {Buffer} buf
+ * @returns {object[]}
+ */
+function decodeStream(schema, buf) {
+  const messages = [];
+  let offset     = 0;
+  while (offset + 4 <= buf.length) {
+    const len     = buf.readUInt32BE(offset);
+    offset += 4;
+    const msgBuf  = buf.slice(offset, offset + len);
+    offset += len;
+    messages.push(decode(schema, msgBuf));
+  }
+  return messages;
+}
+
+// ─── SCHEMA INTROSPECTION ─────────────────────────────────────────────────────
+
+/**
+ * Dump a schema as a human-readable description.
+ * @param {object} schema
+ * @returns {string}
+ */
+function describeSchema(schema) {
+  const lines = [`message ${schema._name} {`];
+  for (const [fname, def] of Object.entries(schema._fields)) {
+    const repeated = def.repeated ? 'repeated ' : '';
+    const optional = def.optional ? 'optional ' : '';
+    const type     = def.type === 'message' ? def.message._name : def.type;
+    lines.push(`  ${optional}${repeated}${type} ${fname} = ${def.field};`);
+  }
+  lines.push('}');
+  return lines.join('\n');
+}
+
+// ─── EXPORTS ─────────────────────────────────────────────────────────────────
+
+module.exports = {
+  kitdef: {
+    defineMessage,
+    defineEnum,
+    createMessageClass,
+    encode,
+    decode,
+    encodeVersioned,
+    decodeVersioned,
+    encodeStream,
+    decodeStream,
+    describeSchema,
+    // Low-level
+    encodeVarint,
+    decodeVarint,
+    encodeField,
+    decodeField,
+    encodeTag,
+    decodeTag,
+    WIRE,
+    FIELD_TYPES,
+  }
+};
+