@pbwire/pbwire 0.1.0 → 0.1.8

package/README.md

@@ -1,9 +1,36 @@
 # pbwire Node.js binding
 
-A `FileDescriptorSet` (`protoc --descriptor_set_out`) becomes a schema at
-runtime; no code generation, no `protoc` plugin, no npm dependencies. The
-runtime is `runtime/addon.c`, an N-API addon in C over `libpbwire.a`; the
-`Schema`/`Message` surface is `lib/pbwire.js`.
+The runtime is `runtime/addon.c`, an N-API addon in C over `libpbwire.a`;
+the `Schema`/`Message` surface is `lib/pbwire.js`. No npm dependencies.
+
+Most code never touches that surface: generate a protobufjs-static-shaped
+facade once (`make -C codegen gen-node`) and use it like the
+library it mirrors — same `create`/`encode`/`decode`/`verify` calls,
+same observable behavior, but the wire format stays in the C core:
+
+```js
+const { Person } = require('./tests/gen/addressbook.js');
+
+const msg = Person.create({name: 'alice', id: 7});
+Person.verify(msg);                       // null: valid
+const wire = Person.encode(msg).finish(); // Buffer
+const back = Person.decode(wire);
+back.name;                                // 'alice'
+back.toJSON();                            // {name: 'alice', id: 7, ...}
+```
+
+The generated file embeds its own `FileDescriptorSet`, so there is no
+`.desc` to ship: `require` it and go. int64 reads as `BigInt`; `create`/
+`fromObject` also take `number|string|Long-like`. `toObject()` keys are
+camelCase (protobufjs convention); pass `{keepCase: true}` for proto
+names. `fromObject` rejects bad shapes with `TypeError`; `verify`
+returns the same reason strings as protobufjs. The one deliberate
+difference: direct post-hoc writes of an implicit zero (`m.i32 = 0`)
+are not marked present — set values through `create`/`fromObject` to
+write explicit zeros.
+
+The dynamic API is still there for gateways and schemas known only at
+runtime:
 
 ```js
 const { Schema } = require('./lib/pbwire');
@@ -11,18 +38,12 @@ const { Schema } = require('./lib/pbwire');
 const schema = Schema.fromFile('tests/data/demo.desc');
 const person = schema.message('demo.Person');
 
-const wire = person.encode({name: 'alice', id: 7, inner: {x: 42}});
-// or, by hand:
-const msg = person.newMessage();
-msg.set('name', 'alice').set('inner', {x: 42});
-msg.encode();          // Buffer
-msg.free();
-
-const back = person.decode(wire);
-back.get('name');      // 'alice'
-back.get('inner').x;   // 42
-back.encode().equals(wire);   // true: byte-exact re-encode
-back.free();
+const wire2 = person.encode({name: 'alice', id: 7, inner: {x: 42}});
+const back2 = person.decode(wire2);
+back2.get('name');      // 'alice'
+back2.get('inner').x;   // 42
+back2.encode().equals(wire2);   // true: byte-exact re-encode
+back2.free();
 ```
 
 ## How it works
@@ -187,19 +208,37 @@ per-message finalizer.
 - **No protoc plugin / code generation.** The schema is always loaded at run
   time, like the Python binding: a `FileDescriptorSet` is the only schema
   source, and there is no generated layout to keep in sync.
-- **No conformance testee.** The official suite is covered through the C core
-  and `conformance/`, not through this binding. The differential test above is
-  what keeps the addon's wire reader honest against the core's.
+Also exported: JSON/text format (`messageToJson`/`jsonToMessage` — the latter
+with an optional ignore-unknown flag, `messageToText`/`textToMessage` — the
+former with an optional print-unknown flag), field presence (`has`), and
+delimited framing (`encodeDelimited`/`decodeDelimited`, returning
+`{message, read}` so concatenated frames decode in a loop).
+See `test/test_pbwire.js`.
+
+## Conformance
+
+`conformance/testee.js` drives the official `conformance_test_runner`
+through this binding (`make conformance-node`):
+
+```
+CONFORMANCE SUITE PASSED: 2742 successes, 0 skipped, 2 expected failures,
+0 unexpected failures.
+CONFORMANCE SUITE PASSED: 445 successes, 0 skipped, 0 expected failures,
+0 unexpected failures.
+```
 
-Also out of scope here: JSON/text format (`pbw_json_print`/`pbw_text_print`),
-field presence introspection (`pbw_message_field_count`), and delimited framing.
-Each is one addon export away when a consumer needs it.
+Binary input decodes to a tree (unknown fields survive, oneof collapses to
+the last member) and every output renders that same tree; JSON input with
+unknown fields only parses when the test category asks to ignore them, and
+text output honors the runner's `print_unknown_fields` flag. The 2 expected
+failures are the shared `conformance/failure_list_pbwire.txt` (tag varints
+the reference C++ testee truncates identically); only JSPB answers `skipped`.
 
-## Typed models
+## Generated models
 
-`protoc-gen-pbwire-typed` (in `../typed`) generates `matrix3.d.ts` interfaces
+`protoc-gen-pbwire` (in `../../codegen`) generates `matrix3.d.ts` interfaces
 (for TypeScript) and a JSDoc/`@ts-check` `.js` with the same shapes plus the enum
 constants, describing exactly the plain objects `MessageType.encode()` accepts
 and `Message.get()` returns. The committed output is `tests/gen/` and
-`examples/gen/`; the typed test type-checks with `tsc --strict --checkJs`.
-See `../typed/README.md`.
+`examples/gen/`; the generated test type-checks with `tsc --strict --checkJs`.
+See `../../codegen/README.md`.

package/build.sh

@@ -46,4 +46,4 @@ if [ "${1:-all}" = build ]; then
 fi
 
 # --expose-gc so the finalizer test can force the collections it checks.
-exec node --expose-gc --test "$here/test/test_pbwire.js" "$here/tests/typed_test.js"
+exec node --expose-gc --test "$here/test/test_pbwire.js" "$here/tests/generated_test.js" "$here/tests/compat_test.js"

package/lib/pbwire-compat.js

@@ -0,0 +1,525 @@
+'use strict';
+
+/* pbwire compat runtime: the verify/fromObject/toObject engine every generated
+ * facade delegates to. Schemas are cached per embedded descriptor set, so any
+ * number of generated files share this module with no global-state surprises:
+ * one entry per distinct FileDescriptorSet, keyed by its own bytes.
+ */
+
+const { Schema } = require('./pbwire.js');
+
+const _schemas = new Map();
+function _type(descB64, full) {
+  let byName = _schemas.get(descB64);
+  if (byName === undefined) {
+    byName = new Map();
+    byName.set('', Schema.fromBytes(Buffer.from(descB64, 'base64')));
+    _schemas.set(descB64, byName);
+  }
+  let t = byName.get(full);
+  if (t === undefined) {
+    t = byName.get('').message(full);
+    byName.set(full, t);
+  }
+  return t;
+}
+
+function _isLongLike(v) {
+  return typeof v === 'object' && v !== null &&
+    Number.isInteger(v.low) && Number.isInteger(v.high);
+}
+
+function _longToBigInt(v) {
+  return (BigInt(v.high >>> 0) << 32n) | BigInt(v.low >>> 0);
+}
+
+// _toBigInt normalizes an int64-ish value for the encoder. BigInt passes
+// through, numbers pass through (the addon casts them, same as plain
+// objects), numeric strings and Long-like {low, high} become BigInt.
+function _toBigInt(v, path, unsigned) {
+  if (typeof v === 'bigint') {
+    // fall through to the range check below
+  } else if (typeof v === 'number') {
+    if (!Number.isInteger(v)) {
+      throw new TypeError('pbwire: ' + path + ' is not an integer');
+    }
+    return v;
+  } else if (typeof v === 'string') {
+    if (!/^-?\d+$/.test(v)) {
+      throw new TypeError('pbwire: ' + path + ' is not an integer string');
+    }
+    v = BigInt(v);
+  } else if (_isLongLike(v)) {
+    v = _longToBigInt(v);
+  } else {
+    throw new TypeError('pbwire: ' + path + ' is not an int64 value');
+  }
+  if (unsigned) {
+    if (v < 0n || v > 18446744073709551615n) {
+      throw new TypeError('pbwire: ' + path + ' out of uint64 range');
+    }
+  } else if (v < -9223372036854775808n || v > 9223372036854775807n) {
+    throw new TypeError('pbwire: ' + path + ' out of int64 range');
+  }
+  return v;
+}
+
+// Shape check only (any BigInt passes); range is enforced when the value
+// is normalized for the encoder in _toBigInt.
+function _checkInt64(v) {
+  if (typeof v === 'bigint') {
+    return true;
+  }
+  if (typeof v === 'number') {
+    return Number.isInteger(v);
+  }
+  if (typeof v === 'string') {
+    return /^-?\d+$/.test(v);
+  }
+  return _isLongLike(v);
+}
+
+// _verifyField returns null when v is valid, else a reason string.
+function _verifyField(fd, v, path, enums, classes) {
+  if (fd.rep) {
+    if (!Array.isArray(v)) {
+      return path + ': array expected';
+    }
+    for (let i = 0; i < v.length; i++) {
+      const bad = _verifyOne(fd, v[i], path + '[' + i + ']', enums, classes);
+      if (bad !== null) {
+        return bad;
+      }
+    }
+    return null;
+  }
+  return _verifyOne(fd, v, path, enums, classes);
+}
+
+function _verifyOne(fd, v, path, enums, classes) {
+  switch (fd.k) {
+  // Reason strings mirror protobufjs verify() verbatim so mixed code reads
+  // the same errors from either library. Like protobufjs, 32-bit checks are
+  // integer-only (range truncation happens in the encoder, identically).
+  case 'i32':
+  case 's32':
+  case 'sfx32':
+  case 'u32':
+  case 'fx32':
+    return Number.isInteger(v) ? null : path + ': integer expected';
+  case 'i64':
+  case 's64':
+  case 'sfx64':
+  case 'u64':
+  case 'fx64':
+    return _checkInt64(v) ? null : path + ': integer|Long expected';
+  case 'f32':
+  case 'f64':
+    return (typeof v === 'number') ? null : path + ': number expected';
+  case 'bool':
+    return (typeof v === 'boolean') ? null : path + ': boolean expected';
+  case 'str':
+    return (typeof v === 'string') ? null : path + ': string expected';
+  case 'bytes':
+    return (typeof v === 'object' && v !== null &&
+      (Buffer.isBuffer(v) || v instanceof Uint8Array))
+      ? null : path + ': buffer expected';
+  case 'enum': {
+    const names = enums[fd.en];
+    if (typeof v === 'number' && Number.isInteger(v)) {
+      // Open enums (proto3) carry unknown values through the round trip.
+      if (!fd.closed || names === undefined) {
+        return null;
+      }
+      for (const key in names) {
+        if (names[key] === v) {
+          return null;
+        }
+      }
+      return path + ': enum value expected';
+    }
+    return path + ': enum value expected';
+  }
+  case 'msg':
+    if (typeof v !== 'object' || v === null || Array.isArray(v)) {
+      return path + ': object expected';
+    }
+    return classes[fd.msg].verify(v);
+  default:
+    return null;
+  }
+}
+
+function _fromOne(fd, v, path, enums, classes) {
+  switch (fd.k) {
+  case 'i64':
+  case 's64':
+  case 'sfx64':
+    return _toBigInt(v, path, false);
+  case 'u64':
+  case 'fx64':
+    return _toBigInt(v, path, true);
+  case 'bytes':
+    if (Buffer.isBuffer(v)) {
+      return v;
+    }
+    if (v instanceof Uint8Array) {
+      return Buffer.from(v);
+    }
+    throw new TypeError('pbwire: ' + path + ' is not bytes');
+  case 'enum': {
+    if (typeof v === 'string') {
+      const names = enums[fd.en];
+      if (names !== undefined && names[v] !== undefined) {
+        return names[v];
+      }
+      throw new TypeError('pbwire: ' + path + ' unknown enum name ' + v);
+    }
+    if (typeof v === 'number' && Number.isInteger(v)) {
+      return v;
+    }
+    throw new TypeError('pbwire: ' + path + ' is not an enum value');
+  }
+  case 'msg':
+    if (v !== null && typeof v === 'object' && !(v instanceof classes[fd.msg])) {
+      return classes[fd.msg].fromObject(v);
+    }
+    return v;
+  default:
+    return v;
+  }
+}
+
+function _fromValue(fd, v, path, enums, classes) {
+  if (v === null || v === undefined) {
+    return fd.rep ? [] : null;
+  }
+  if (fd.rep) {
+    if (!Array.isArray(v)) {
+      throw new TypeError('pbwire: ' + path + ' is not an array');
+    }
+    return v.map((item, i) => _fromOne(fd, item, path + '[' + i + ']', enums, classes));
+  }
+  return _fromOne(fd, v, path, enums, classes);
+}
+
+function _toInt64(v, mode) {
+  const big = typeof v === 'bigint' ? v
+    : typeof v === 'number' ? BigInt(Math.trunc(v))
+    : _longToBigInt(v);
+  if (mode === 'String') {
+    return big.toString();
+  }
+  if (mode === 'Number') {
+    return Number(big);
+  }
+  return big;
+}
+
+function _toOne(fd, v, opts, enums, revEnums) {
+  switch (fd.k) {
+  case 'i64':
+  case 's64':
+  case 'sfx64':
+  case 'u64':
+  case 'fx64':
+    return _toInt64(v, opts.longs || 'BigInt');
+  case 'enum':
+    if ((opts.enums || 'Number') === 'String') {
+      const rev = revEnums[fd.en];
+      if (rev !== undefined && rev[v] !== undefined) {
+        return rev[v];
+      }
+    }
+    return v;
+  case 'bytes':
+    return (opts.bytes || 'Buffer') === 'base64' ? Buffer.from(v).toString('base64') : v;
+  case 'msg':
+    return v.toObject(opts);
+  default:
+    return v;
+  }
+}
+
+// Output keys are camelCase like protobufjs toObject; keepCase:true keeps
+// the proto names (the dynamic API's convention).
+function _toPlain(cls, msg, opts, enums, revEnums) {
+  const out = {};
+  const keyOf = (fd) => (opts.keepCase ? fd.n : fd.js);
+  const marked = msg._present instanceof Set ? msg._present : null;
+  for (const fd of cls._FIELDS) {
+    const v = msg[fd.js];
+    if (v === null || v === undefined) {
+      continue;
+    }
+    if (fd.rep && v.length === 0) {
+      continue;
+    }
+    // Unmarked fields are constructor defaults or direct post-hoc writes:
+    // include non-default values (direct post-hoc writes work), drop default
+    // ones (so create({}) encodes empty). Marked fields always go on the wire.
+    if (!opts.defaults && !fd.req && marked !== null &&
+        !marked.has(fd.js) && _isDefault(fd, v)) {
+      continue;
+    }
+    out[keyOf(fd)] = fd.rep
+      ? v.map((item) => _toOne(fd, item, opts, enums, revEnums))
+      : _toOne(fd, v, opts, enums, revEnums);
+  }
+  if (opts.defaults) {
+    for (const fd of cls._FIELDS) {
+      if (out[keyOf(fd)] !== undefined) {
+        continue;
+      }
+      if (fd.rep) {
+        out[keyOf(fd)] = [];
+      } else if (fd.k === 'msg') {
+        out[keyOf(fd)] = null;
+      } else {
+        out[keyOf(fd)] = _toOne(fd, _defaultFor(fd), opts, enums, revEnums);
+      }
+    }
+  }
+  return out;
+}
+
+function _isDefault(fd, v) {
+  if (fd.rep) {
+    return v.length === 0;
+  }
+  switch (fd.k) {
+  case 'i64':
+  case 's64':
+  case 'sfx64':
+  case 'u64':
+  case 'fx64':
+    return v === 0 || v === 0n;
+  case 'bool':
+    return v === false;
+  case 'str':
+    return v === '';
+  case 'bytes':
+    return v.length === 0;
+  case 'msg':
+    return v === null || v === undefined;
+  default:
+    return v === 0;
+  }
+}
+
+function _defaultFor(fd, classes) {
+  if (fd.rep) {
+    return [];
+  }
+  // Presence fields (explicit presence or sub-message) default to absent.
+  if (fd.has) {
+    return null;
+  }
+  switch (fd.k) {
+  case 'i64':
+  case 's64':
+  case 'sfx64':
+  case 'u64':
+  case 'fx64':
+    return 0n;
+  case 'f32':
+  case 'f64':
+  case 'i32':
+  case 's32':
+  case 'sfx32':
+  case 'u32':
+  case 'fx32':
+  case 'enum':
+    return 0;
+  case 'bool':
+    return false;
+  case 'str':
+    return '';
+  case 'bytes':
+    return Buffer.alloc(0);
+  case 'msg':
+    return null;
+  default:
+    return null;
+  }
+}
+
+function _encodeVarint(n) {
+  const parts = [];
+  while (n >= 128) {
+    parts.push((n % 128) | 128);
+    n = Math.floor(n / 128);
+  }
+  parts.push(n);
+  return Buffer.from(parts);
+}
+
+function _decodeVarint(buf, pos) {
+  let n = 0;
+  let shift = 0;
+  while (pos < buf.length) {
+    const b = buf[pos++];
+    n += (b & 127) * 2 ** shift;
+    shift += 7;
+    if ((b & 128) === 0) {
+      return [n, pos];
+    }
+    if (shift >= 64) {
+      throw new Error('pbwire: varint too long');
+    }
+  }
+  throw new Error('pbwire: truncated varint');
+}
+
+// _makeClass builds one message class over a MessageType. cls._FIELDS is the
+// table the engine above reads; wire bytes always come from the C core.
+// _fromWire converts C-validated wire values into an instance. Unlike
+// fromObject it performs no validation and no coercion: the decoder has
+// already checked every value against the schema, so nested plains only
+// need wrapping and every present field only needs marking. The encode
+// boundary (addon tree build) remains the loudness net for bad data.
+function _fromWire(cls, plain) {
+  // new keeps V8's hidden-class shape (measured faster than Object.create
+  // + defineProperty here); the constructor's defaults stand for absent
+  // fields, present ones are converted and marked below.
+  const inst = new cls();
+  const classes = cls._CLASSES;
+  for (const fd of cls._FIELDS) {
+    const v = plain[fd.n];
+    if (v === undefined) {
+      continue;
+    }
+    if (fd.k === 'msg') {
+      if (fd.rep) {
+        inst[fd.js] = v.map((item) => _fromWire(classes[fd.msg], item));
+      } else {
+        inst[fd.js] = _fromWire(classes[fd.msg], v);
+      }
+    } else if (fd.rep) {
+      inst[fd.js] = v.slice();
+    } else {
+      inst[fd.js] = v;
+    }
+    inst._present.add(fd.js);
+  }
+  return inst;
+}
+
+function _makeClass(full, descB64, fields) {
+  class Compat {
+    constructor(props) {
+      props = props || {};
+      Object.defineProperty(this, '_present', { value: new Set(), enumerable: false, writable: true });
+      for (const fd of fields) {
+        const v = props[fd.js] !== undefined ? props[fd.js] : props[fd.n];
+        if (v === undefined) {
+          this[fd.js] = _defaultFor(fd);
+        } else {
+          this[fd.js] = v;
+          // fromObject normalizes below; direct construction marks as set.
+          this._present.add(fd.js);
+        }
+      }
+    }
+    static create(props) {
+      return this.fromObject(props || {});
+    }
+    static encode(message) {
+      const inst = (message instanceof this) ? message : this.fromObject(message);
+      // The dynamic encoder takes proto names; toObject() shows camelCase.
+      const plain = _toPlain(this, inst, { keepCase: true }, this._ENUMS, this._REVENUMS);
+      const wire = _type(descB64, full).encode(plain);
+      return { finish: () => wire };
+    }
+    static encodeDelimited(message) {
+      const wire = this.encode(message).finish();
+      const out = Buffer.concat([_encodeVarint(wire.length), wire]);
+      return { finish: () => out };
+    }
+    static decode(bytes) {
+      const buf = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes);
+      const m = _type(descB64, full).decode(buf);
+      const plain = {};
+      for (const fd of fields) {
+        const v = m.get(fd.n);
+        if (v !== undefined) {
+          plain[fd.n] = v;
+        }
+      }
+      return _fromWire(Compat, plain);
+    }
+    static decodeDelimited(bytes) {
+      const buf = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes);
+      const pair = _decodeVarint(buf, 0);
+      return this.decode(buf.subarray(pair[1], pair[1] + pair[0]));
+    }
+    static verify(obj) {
+      if (obj === null || typeof obj !== 'object' || Array.isArray(obj)) {
+        return 'object expected';
+      }
+      const seen = new Map();
+      for (const fd of fields) {
+        let v = obj[fd.js];
+        if (v === undefined) {
+          v = obj[fd.n];
+        }
+        if (v === null || v === undefined) {
+          if (fd.req) {
+            return fd.n + ': required field missing';
+          }
+          continue;
+        }
+        const bad = _verifyField(fd, v, fd.n, this._ENUMS, this._CLASSES);
+        if (bad !== null) {
+          return bad;
+        }
+        if (fd.oneof !== null) {
+          if (seen.has(fd.oneof)) {
+            return fd.oneof + ': multiple values';
+          }
+          seen.set(fd.oneof, true);
+        }
+      }
+      return null;
+    }
+    static fromObject(obj) {
+      if (obj === null || typeof obj !== 'object' || Array.isArray(obj)) {
+        throw new TypeError('pbwire: fromObject expects an object');
+      }
+      const inst = new this();
+      for (const fd of fields) {
+        let v = obj[fd.js] !== undefined ? obj[fd.js] : obj[fd.n];
+        if (v === undefined) {
+          continue;
+        }
+        if (v === null) {
+          inst[fd.js] = fd.rep ? [] : null;
+          continue;
+        }
+        // One validation logic for verify() and fromObject(): normalize,
+        // then reject with the same reason verify() would give.
+        const nv = _fromValue(fd, v, fd.n, this._ENUMS, this._CLASSES);
+        const bad = _verifyField(fd, nv, fd.n, this._ENUMS, this._CLASSES);
+        if (bad !== null) {
+          throw new TypeError('pbwire: ' + bad);
+        }
+        inst[fd.js] = nv;
+        inst._present.add(fd.js);
+      }
+      return inst;
+    }
+    static toObject(message, opts) {
+      const inst = (message instanceof this) ? message : this.fromObject(message);
+      return _toPlain(this, inst, opts || {}, this._ENUMS, this._REVENUMS);
+    }
+    toObject(opts) {
+      return this.constructor.toObject(this, opts);
+    }
+    toJSON() {
+      return this.constructor.toObject(this, { enums: 'String', longs: 'String', bytes: 'base64' });
+    }
+  }
+  Compat._FIELDS = fields;
+  return Compat;
+}
+module.exports = { _makeClass };

package/lib/pbwire.js

@@ -107,6 +107,40 @@ class MessageType {
     return this._copy(addon.encodeObject(this._handle, value));
   }
 
+  /** Parse JSON mapping text into a Message; throws on malformed input.
+   * A second true argument skips unknown field names instead of failing. */
+  fromJson(json, ignore = false) {
+    if (typeof json !== 'string') {
+      throw new TypeError('pbwire: fromJson expects a string');
+    }
+    const message = new Message(this);
+    message._handle = addon.jsonToMessage(this._handle, json, ignore);
+    return message;
+  }
+
+  /** Parse text format into a Message; throws on malformed input. */
+  fromText(text) {
+    if (typeof text !== 'string') {
+      throw new TypeError('pbwire: fromText expects a string');
+    }
+    const message = new Message(this);
+    message._handle = addon.textToMessage(this._handle, text);
+    return message;
+  }
+
+  /** Decode one length-delimited frame: {message, read}, where read counts
+   * the length prefix plus the frame, so concatenated frames decode in a
+   * loop. Throws on a truncated frame. */
+  decodeDelimited(bytes) {
+    if (!Buffer.isBuffer(bytes)) {
+      throw new TypeError('pbwire: decodeDelimited expects a Buffer');
+    }
+    const res = addon.decodeDelimited(this._handle, bytes);
+    const message = new Message(this);
+    message._handle = res.message;
+    return { message, read: res.read };
+  }
+
   /** Decode wire bytes into a Message; throws on malformed input. */
   decode(bytes) {
     if (!Buffer.isBuffer(bytes)) {
@@ -152,6 +186,12 @@ class Message {
 
   /** Store a field value by name; `undefined`/`null` clears the field. */
   set(name, value) {
+    addon.set(this._tree(), name, value);
+    return this;
+  }
+
+  /** The mutable tree, decoding the retained bytes once when needed. */
+  _tree() {
     this._live();
     if (this._wire !== null) {
       // Writing needs a mutable tree: decode the retained bytes once.
@@ -159,8 +199,28 @@ class Message {
       this._wire = null;
       this._slices = null;
     }
-    addon.set(this._handle, name, value);
-    return this;
+    return this._handle;
+  }
+
+  /** JSON mapping text of this message. */
+  toJson() {
+    return addon.messageToJson(this._tree());
+  }
+
+  /** Protobuf text format of this message; a false argument drops unknown
+   * fields instead of printing them numerically. */
+  toText(printUnknown = true) {
+    return addon.messageToText(this._tree(), printUnknown);
+  }
+
+  /** Field presence by name: set (even to a zero) reads true. */
+  has(name) {
+    return addon.has(this._tree(), name);
+  }
+
+  /** One length-delimited frame (varint length + message). */
+  encodeDelimited() {
+    return addon.encodeDelimited(this._tree());
   }
 
   /** Wire bytes of this message. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pbwire/pbwire",
-  "version": "0.1.0",
+  "version": "0.1.8",
   "description": "Dynamic protobuf over the pbwire C ABI, schema at runtime, no generated code",
   "license": "Apache-2.0",
   "repository": {

package/runtime/addon.c

@@ -2528,6 +2528,279 @@ message_free(napi_env env, napi_callback_info info)
     return out;
 }
 
+/* JSON text of a tree (protobuf JSON mapping). */
+static napi_value
+message_to_json(napi_env env, napi_callback_info info)
+{
+    napi_value argv[1];
+    napi_value out = NULL;
+    message_handle *handle;
+    char *text = NULL;
+    size_t len = 0;
+    pbw_status status;
+
+    if (!get_args(env, info, argv, 1)) {
+        return NULL;
+    }
+    if (!unwrap_message(env, argv[0], &handle)) {
+        return NULL;
+    }
+    status = pbw_json_print(handle->msg, &text, &len);
+    if (status != PBW_OK) {
+        return fail_status(env, "messageToJson", status);
+    }
+    if (napi_create_string_utf8(env, text, len, &out) != napi_ok) {
+        pbw_free(text);
+        return NULL;
+    }
+    pbw_free(text);
+    return out;
+}
+
+/* Parses JSON mapping text into a new tree; an optional third boolean
+ * argument skips unknown field names instead of failing. */
+static napi_value
+json_to_message(napi_env env, napi_callback_info info)
+{
+    napi_value argv[3];
+    size_t argc = 3;
+    desc_handle *desc;
+    message_handle *handle;
+    pbw_message *msg = NULL;
+    string_buf buf;
+    const char *text;
+    pbw_status status;
+    pbw_json_parse_options opts;
+    bool ignore = false;
+
+    if (napi_get_cb_info(env, info, &argc, argv, NULL, NULL) != napi_ok ||
+        argc < 2) {
+        napi_throw_type_error(env, NULL, "pbwire: expected (desc, json)");
+        return NULL;
+    }
+    if (!unwrap(env, argv[0], (void **)&desc, "message descriptor handle")) {
+        return NULL;
+    }
+    if (argc > 2) {
+        napi_valuetype want = napi_undefined;
+
+        if (napi_typeof(env, argv[2], &want) != napi_ok ||
+            want != napi_boolean ||
+            napi_get_value_bool(env, argv[2], &ignore) != napi_ok) {
+            napi_throw_type_error(env, NULL,
+                                  "pbwire: ignore flag must be a boolean");
+            return NULL;
+        }
+    }
+    text = string_bytes(env, argv[1], &buf);
+    if (text == NULL) {
+        return NULL;
+    }
+    opts.ignore_unknown_fields = ignore;
+    status = pbw_json_parse_opts(desc->table->desc, text, buf.len, &opts,
+                                 &msg);
+    string_free(&buf, text);
+    if (status != PBW_OK) {
+        return fail_status(env, "jsonToMessage", status);
+    }
+    handle = calloc(1, sizeof(*handle));
+    if (handle == NULL) {
+        pbw_message_free(msg);
+        return fail_memory(env);
+    }
+    handle->msg = msg;
+    return new_message_value(env, desc, argv[0], handle);
+}
+
+/* Text format of a tree. */
+static napi_value
+message_to_text(napi_env env, napi_callback_info info)
+{
+    napi_value argv[2];
+    size_t argc = 2;
+    napi_value out = NULL;
+    message_handle *handle;
+    char *text = NULL;
+    size_t len = 0;
+    pbw_status status;
+    /* Absent means print (the binding's standing behavior); the testee
+     * passes the runner's print_unknown_fields flag explicitly. */
+    bool print_unknown = true;
+
+    if (napi_get_cb_info(env, info, &argc, argv, NULL, NULL) != napi_ok ||
+        argc < 1) {
+        napi_throw_type_error(env, NULL, "pbwire: expected (message)");
+        return NULL;
+    }
+    if (!unwrap_message(env, argv[0], &handle)) {
+        return NULL;
+    }
+    if (argc > 1) {
+        napi_valuetype want = napi_undefined;
+
+        if (napi_typeof(env, argv[1], &want) != napi_ok ||
+            want != napi_boolean ||
+            napi_get_value_bool(env, argv[1], &print_unknown) != napi_ok) {
+            napi_throw_type_error(env, NULL,
+                                  "pbwire: print flag must be a boolean");
+            return NULL;
+        }
+    }
+    status = pbw_text_print_opts(handle->msg, print_unknown, &text, &len);
+    if (status != PBW_OK) {
+        return fail_status(env, "messageToText", status);
+    }
+    if (napi_create_string_utf8(env, text, len, &out) != napi_ok) {
+        pbw_free(text);
+        return NULL;
+    }
+    pbw_free(text);
+    return out;
+}
+
+/* Parses text format into a new tree. */
+static napi_value
+text_to_message(napi_env env, napi_callback_info info)
+{
+    napi_value argv[2];
+    desc_handle *desc;
+    message_handle *handle;
+    pbw_message *msg = NULL;
+    string_buf buf;
+    const char *text;
+    pbw_status status;
+
+    if (!get_args(env, info, argv, 2)) {
+        return NULL;
+    }
+    if (!unwrap(env, argv[0], (void **)&desc, "message descriptor handle")) {
+        return NULL;
+    }
+    text = string_bytes(env, argv[1], &buf);
+    if (text == NULL) {
+        return NULL;
+    }
+    status = pbw_text_parse(desc->table->desc, text, buf.len, &msg);
+    string_free(&buf, text);
+    if (status != PBW_OK) {
+        return fail_status(env, "textToMessage", status);
+    }
+    handle = calloc(1, sizeof(*handle));
+    if (handle == NULL) {
+        pbw_message_free(msg);
+        return fail_memory(env);
+    }
+    handle->msg = msg;
+    return new_message_value(env, desc, argv[0], handle);
+}
+
+/* Presence of one field by name: set (even to a zero) reads true. */
+static napi_value
+message_has(napi_env env, napi_callback_info info)
+{
+    napi_value argv[2];
+    napi_value out = NULL;
+    message_handle *handle;
+    field_entry *entry;
+    int present;
+
+    if (!get_args(env, info, argv, 2)) {
+        return NULL;
+    }
+    if (!unwrap_message(env, argv[0], &handle)) {
+        return NULL;
+    }
+    entry = field_by_name(env, handle, argv[1]);
+    if (entry == NULL) {
+        return NULL;
+    }
+    present = pbw_message_get_field(handle->msg, entry->field) != NULL;
+    if (napi_get_boolean(env, present, &out) != napi_ok) {
+        return NULL;
+    }
+    return out;
+}
+
+/* One length-delimited frame (varint length + message) as a Buffer. */
+static napi_value
+encode_delimited(napi_env env, napi_callback_info info)
+{
+    napi_value argv[1];
+    napi_value out = NULL;
+    message_handle *handle;
+    uint8_t *wire = NULL;
+    size_t wire_len = 0;
+    pbw_status status;
+
+    if (!get_args(env, info, argv, 1)) {
+        return NULL;
+    }
+    if (!unwrap_message(env, argv[0], &handle)) {
+        return NULL;
+    }
+    status = pbw_encode_delimited(handle->msg, &wire, &wire_len);
+    if (status != PBW_OK) {
+        return fail_status(env, "encodeDelimited", status);
+    }
+    if (napi_create_buffer_copy(env, wire_len, wire, NULL, &out) != napi_ok) {
+        pbw_free(wire);
+        return NULL;
+    }
+    pbw_free(wire);
+    return out;
+}
+
+/* One frame from a Buffer: {message, read}, where read counts the length
+ * prefix plus the frame, so concatenated frames decode in a loop. */
+static napi_value
+decode_delimited(napi_env env, napi_callback_info info)
+{
+    napi_value argv[2];
+    napi_value out = NULL;
+    napi_value message_value = NULL;
+    napi_value read_value = NULL;
+    desc_handle *desc;
+    message_handle *handle;
+    pbw_message *msg = NULL;
+    void *data = NULL;
+    size_t len = 0;
+    size_t consumed = 0;
+    pbw_status status;
+
+    if (!get_args(env, info, argv, 2)) {
+        return NULL;
+    }
+    if (!unwrap(env, argv[0], (void **)&desc, "message descriptor handle")) {
+        return NULL;
+    }
+    if (napi_get_buffer_info(env, argv[1], &data, &len) != napi_ok) {
+        return fail_argument(env, "decodeDelimited expects a Buffer");
+    }
+    status = pbw_decode_delimited(desc->table->desc, data, len, &msg,
+                                  &consumed);
+    if (status != PBW_OK) {
+        return fail_status(env, "decodeDelimited", status);
+    }
+    handle = calloc(1, sizeof(*handle));
+    if (handle == NULL) {
+        pbw_message_free(msg);
+        return fail_memory(env);
+    }
+    handle->msg = msg;
+    message_value = new_message_value(env, desc, argv[0], handle);
+    if (message_value == NULL) {
+        return NULL;
+    }
+    if (napi_create_object(env, &out) != napi_ok ||
+        napi_set_named_property(env, out, "message", message_value) !=
+            napi_ok ||
+        napi_create_uint32(env, (uint32_t)consumed, &read_value) != napi_ok ||
+        napi_set_named_property(env, out, "read", read_value) != napi_ok) {
+        return NULL;
+    }
+    return out;
+}
+
 NAPI_MODULE_INIT()
 {
     napi_property_descriptor properties[] = {
@@ -2554,6 +2827,19 @@ NAPI_MODULE_INIT()
         {"copyEncoded", NULL, copy_encoded, NULL, NULL, NULL, napi_enumerable,
          NULL},
         {"free", NULL, message_free, NULL, NULL, NULL, napi_enumerable, NULL},
+        {"messageToJson", NULL, message_to_json, NULL, NULL, NULL,
+         napi_enumerable, NULL},
+        {"jsonToMessage", NULL, json_to_message, NULL, NULL, NULL,
+         napi_enumerable, NULL},
+        {"messageToText", NULL, message_to_text, NULL, NULL, NULL,
+         napi_enumerable, NULL},
+        {"textToMessage", NULL, text_to_message, NULL, NULL, NULL,
+         napi_enumerable, NULL},
+        {"has", NULL, message_has, NULL, NULL, NULL, napi_enumerable, NULL},
+        {"encodeDelimited", NULL, encode_delimited, NULL, NULL, NULL,
+         napi_enumerable, NULL},
+        {"decodeDelimited", NULL, decode_delimited, NULL, NULL, NULL,
+         napi_enumerable, NULL},
     };
 
     if (napi_define_properties(env, exports,