typia 15.0.0 → 15.1.0

package/lib/internal/_ProtobufWriter.d.ts

@@ -1,5 +1,18 @@
 import { _IProtobufWriter } from "./_IProtobufWriter";
 import { _ProtobufSizer } from "./_ProtobufSizer";
+/**
+ * Writes a Protocol Buffer message into a buffer that {@link _ProtobufSizer}
+ * sized.
+ *
+ * The calls must match the sizer's calls in order, because string and message
+ * lengths are read back from the sizer instead of being measured again. Adapted
+ * from the fixed writer of as-proto.
+ *
+ * @evidence contracts/common.md#principled-implementation The writer allocates one buffer of the length the sizer measured and fills it in the same call order, reading the recorded string and message lengths from the sizer in sequence, so no length is recomputed and the buffer is exactly the right size. Varints are written in seven-bit groups, ZigZag values are unsigned, floats are little-endian and strings are UTF-8 encoded.
+ * @evidence contracts/common.md#clear-and-simple-design One class holding the buffer, a data view, the write pointer and a cursor into the sizer's lengths; its private varint writers are shared by the scalar methods.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It adapts the as-proto fixed writer and follows the protobuf wire format; a call order that differs from the sizer's is a contract violation that this class does not detect.
+ * @evidence contracts/common.md#meaningful-documentation A reference comment names the origin and the fields have comments; the public methods are documented individually.
+ */
 export declare class _ProtobufWriter implements _IProtobufWriter {
     /** Related sizer */
     private readonly sizer;
@@ -12,22 +25,160 @@ export declare class _ProtobufWriter implements _IProtobufWriter {
     /** Index in varlen array from sizer. */
     private varlenidx;
     constructor(sizer: _ProtobufSizer);
+    /**
+     * Return the buffer that is being filled.
+     *
+     * @evidence contracts/common.md#principled-implementation Returns the buffer that is being filled, which has the final length from construction.
+     * @evidence contracts/common.md#clear-and-simple-design One accessor.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It returns the same buffer and does not copy.
+     * @evidence contracts/common.md#meaningful-documentation A short comment states what is returned.
+     */
     buffer(): Uint8Array;
+    /**
+     * Write a boolean as one byte.
+     *
+     * @evidence contracts/common.md#principled-implementation One byte of zero or one, through the byte writer.
+     * @evidence contracts/common.md#clear-and-simple-design One delegation.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The rule is the wire format's.
+     * @evidence contracts/common.md#meaningful-documentation A short comment states what is written.
+     */
     bool(value: boolean): void;
+    /**
+     * Write the low eight bits of the value.
+     *
+     * @evidence contracts/common.md#principled-implementation Writes the low eight bits of the value at the pointer and advances it, which is the primitive that bool and the varint writers build on.
+     * @evidence contracts/common.md#clear-and-simple-design One store.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The mask makes an out-of-range input wrap instead of corrupting neighbors.
+     * @evidence contracts/common.md#meaningful-documentation A short comment states what is written.
+     */
     byte(value: number): void;
+    /**
+     * Write a signed 32-bit integer; a negative value is sign-extended to a
+     * 64-bit varint.
+     *
+     * @evidence contracts/common.md#principled-implementation A negative value goes through the 64-bit writer so it is sign-extended to ten bytes, and a non-negative one is written as an unsigned 32-bit varint.
+     * @evidence contracts/common.md#clear-and-simple-design One branch over two writers.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The rule is the wire format's.
+     * @evidence contracts/common.md#meaningful-documentation A short comment states what is written.
+     */
     int32(value: number): void;
+    /**
+     * Write a signed 32-bit integer in ZigZag form as an unsigned varint.
+     *
+     * @evidence contracts/common.md#principled-implementation The ZigZag value is converted to unsigned before the varint is written, so magnitudes of 2^30 or more are written in five bytes; the sizer measures the same value, so the announced and written lengths agree.
+     * @evidence contracts/common.md#clear-and-simple-design One expression over the shared writer.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The mapping is the protobuf definition.
+     * @evidence contracts/common.md#meaningful-documentation A comment states the unsigned mapping and why it is needed.
+     */
     sint32(value: number): void;
+    /**
+     * Write an unsigned 32-bit integer as a varint.
+     *
+     * @evidence contracts/common.md#principled-implementation The value is written as a seven-bit group varint.
+     * @evidence contracts/common.md#clear-and-simple-design One delegation.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The rule is the wire format's.
+     * @evidence contracts/common.md#meaningful-documentation A short comment states what is written.
+     */
     uint32(value: number): void;
+    /**
+     * Write a signed 64-bit integer in ZigZag form.
+     *
+     * @evidence contracts/common.md#principled-implementation The number or bigint is converted to a bigint and ZigZag mapped, then written as an unsigned 64-bit varint.
+     * @evidence contracts/common.md#clear-and-simple-design One expression over the 64-bit writer.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The mapping is the protobuf definition.
+     * @evidence contracts/common.md#meaningful-documentation A short comment states what is written.
+     */
     sint64(value: number | bigint): void;
+    /**
+     * Write a signed 64-bit integer as a varint of its unsigned pattern.
+     *
+     * @evidence contracts/common.md#principled-implementation The value is converted to a bigint and written as an unsigned 64-bit pattern, so negative values take ten bytes.
+     * @evidence contracts/common.md#clear-and-simple-design One delegation.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The rule is the wire format's.
+     * @evidence contracts/common.md#meaningful-documentation A short comment states what is written.
+     */
     int64(value: number | bigint): void;
+    /**
+     * Write an unsigned 64-bit integer as a varint.
+     *
+     * @evidence contracts/common.md#principled-implementation The value is converted to a bigint and written as a 64-bit varint.
+     * @evidence contracts/common.md#clear-and-simple-design One delegation.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The rule is the wire format's.
+     * @evidence contracts/common.md#meaningful-documentation A short comment states what is written.
+     */
     uint64(value: number | bigint): void;
+    /**
+     * Write a 32-bit float in little-endian order.
+     *
+     * @evidence contracts/common.md#principled-implementation Four little-endian bytes through the data view, advancing the pointer.
+     * @evidence contracts/common.md#clear-and-simple-design One store.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The rule is the wire format's.
+     * @evidence contracts/common.md#meaningful-documentation A short comment states what is written.
+     */
     float(val: number): void;
+    /**
+     * Write a 64-bit float in little-endian order.
+     *
+     * @evidence contracts/common.md#principled-implementation Eight little-endian bytes through the data view, advancing the pointer.
+     * @evidence contracts/common.md#clear-and-simple-design One store.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The rule is the wire format's.
+     * @evidence contracts/common.md#meaningful-documentation A short comment states what is written.
+     */
     double(val: number): void;
+    /**
+     * Write the length prefix and the bytes.
+     *
+     * @evidence contracts/common.md#principled-implementation The byte length is written as an unsigned varint and the bytes are copied after it.
+     * @evidence contracts/common.md#clear-and-simple-design One prefix write and one copy loop.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The rule is the wire format's.
+     * @evidence contracts/common.md#meaningful-documentation A short comment states what is written.
+     */
     bytes(value: Uint8Array): void;
+    /**
+     * Write the recorded byte length and the UTF-8 bytes.
+     *
+     * @evidence contracts/common.md#principled-implementation The UTF-8 byte length that the sizer recorded is written as the prefix and the encoded bytes follow, so the length is not measured twice and always matches the bytes if the same string is written as was sized.
+     * @evidence contracts/common.md#clear-and-simple-design One function using the recorded length and a shared encoder.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts A different string than the one sized would corrupt the layout, which this class does not guard.
+     * @evidence contracts/common.md#meaningful-documentation A short comment states what is written.
+     */
     string(value: string): void;
+    /**
+     * Write the recorded length of the message that follows.
+     *
+     * @evidence contracts/common.md#principled-implementation The next recorded length is read from the sizer and written as the prefix of the message that follows.
+     * @evidence contracts/common.md#clear-and-simple-design One delegation to the length cursor.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The recorded lengths come from the sizer and are not recomputed.
+     * @evidence contracts/common.md#meaningful-documentation A short comment states what is written.
+     */
     fork(): void;
+    /**
+     * Do nothing, because the sizer already recorded the length that `fork`
+     * wrote.
+     *
+     * @evidence contracts/common.md#principled-implementation Nothing remains to be done at the end of a message, because the prefix was written by fork from the sizer's measurement.
+     * @evidence contracts/common.md#clear-and-simple-design An empty method that keeps the writer interface symmetrical with the sizer.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The comment says the work is done by the sizer.
+     * @evidence contracts/common.md#meaningful-documentation An inline comment states why it is empty.
+     */
     ldelim(): void;
+    /**
+     * Return the filled buffer.
+     *
+     * @evidence contracts/common.md#principled-implementation Returns the filled buffer, which equals the measured length when the call order matched.
+     * @evidence contracts/common.md#clear-and-simple-design One accessor.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It returns the buffer without trimming or copying.
+     * @evidence contracts/common.md#meaningful-documentation A short comment states what is returned.
+     */
     finish(): Uint8Array;
+    /**
+     * Allocate a new buffer of the sizer's current length and rewind the writer.
+     *
+     * @evidence contracts/common.md#principled-implementation A fresh buffer of the sizer's current length is allocated and the pointers rewound so the writer can be reused after the sizer was reset and refilled.
+     * @evidence contracts/common.md#clear-and-simple-design Four assignments.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts No old buffer is retained.
+     * @evidence contracts/common.md#meaningful-documentation A short comment states what is rebuilt.
+     */
     reset(): void;
     private variant32;
     private variant64;

package/lib/internal/_ProtobufWriter.js

@@ -3,6 +3,19 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports._ProtobufWriter = void 0;
 const utils_1 = require("@typia/utils");
 /// @reference https://github.com/piotr-oles/as-proto/blob/main/packages/as-proto/assembly/internal/FixedWriter.ts
+/**
+ * Writes a Protocol Buffer message into a buffer that {@link _ProtobufSizer}
+ * sized.
+ *
+ * The calls must match the sizer's calls in order, because string and message
+ * lengths are read back from the sizer instead of being measured again. Adapted
+ * from the fixed writer of as-proto.
+ *
+ * @evidence contracts/common.md#principled-implementation The writer allocates one buffer of the length the sizer measured and fills it in the same call order, reading the recorded string and message lengths from the sizer in sequence, so no length is recomputed and the buffer is exactly the right size. Varints are written in seven-bit groups, ZigZag values are unsigned, floats are little-endian and strings are UTF-8 encoded.
+ * @evidence contracts/common.md#clear-and-simple-design One class holding the buffer, a data view, the write pointer and a cursor into the sizer's lengths; its private varint writers are shared by the scalar methods.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It adapts the as-proto fixed writer and follows the protobuf wire format; a call order that differs from the sizer's is a contract violation that this class does not detect.
+ * @evidence contracts/common.md#meaningful-documentation A reference comment names the origin and the fields have comments; the public methods are documented individually.
+ */
 class _ProtobufWriter {
     constructor(sizer) {
         this.sizer = sizer;
@@ -11,50 +24,157 @@ class _ProtobufWriter {
         this.ptr = 0;
         this.varlenidx = 0;
     }
+    /**
+     * Return the buffer that is being filled.
+     *
+     * @evidence contracts/common.md#principled-implementation Returns the buffer that is being filled, which has the final length from construction.
+     * @evidence contracts/common.md#clear-and-simple-design One accessor.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It returns the same buffer and does not copy.
+     * @evidence contracts/common.md#meaningful-documentation A short comment states what is returned.
+     */
     buffer() {
         return this.buf;
     }
+    /**
+     * Write a boolean as one byte.
+     *
+     * @evidence contracts/common.md#principled-implementation One byte of zero or one, through the byte writer.
+     * @evidence contracts/common.md#clear-and-simple-design One delegation.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The rule is the wire format's.
+     * @evidence contracts/common.md#meaningful-documentation A short comment states what is written.
+     */
     bool(value) {
         this.byte(value ? 1 : 0);
     }
+    /**
+     * Write the low eight bits of the value.
+     *
+     * @evidence contracts/common.md#principled-implementation Writes the low eight bits of the value at the pointer and advances it, which is the primitive that bool and the varint writers build on.
+     * @evidence contracts/common.md#clear-and-simple-design One store.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The mask makes an out-of-range input wrap instead of corrupting neighbors.
+     * @evidence contracts/common.md#meaningful-documentation A short comment states what is written.
+     */
     byte(value) {
         this.buf[this.ptr++] = value & 255;
     }
+    /**
+     * Write a signed 32-bit integer; a negative value is sign-extended to a
+     * 64-bit varint.
+     *
+     * @evidence contracts/common.md#principled-implementation A negative value goes through the 64-bit writer so it is sign-extended to ten bytes, and a non-negative one is written as an unsigned 32-bit varint.
+     * @evidence contracts/common.md#clear-and-simple-design One branch over two writers.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The rule is the wire format's.
+     * @evidence contracts/common.md#meaningful-documentation A short comment states what is written.
+     */
     int32(value) {
         if (value < 0)
             this.int64(value);
         else
             this.variant32(value >>> 0);
     }
+    /**
+     * Write a signed 32-bit integer in ZigZag form as an unsigned varint.
+     *
+     * @evidence contracts/common.md#principled-implementation The ZigZag value is converted to unsigned before the varint is written, so magnitudes of 2^30 or more are written in five bytes; the sizer measures the same value, so the announced and written lengths agree.
+     * @evidence contracts/common.md#clear-and-simple-design One expression over the shared writer.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The mapping is the protobuf definition.
+     * @evidence contracts/common.md#meaningful-documentation A comment states the unsigned mapping and why it is needed.
+     */
     sint32(value) {
-        this.variant32((value << 1) ^ (value >> 31));
+        // ZigZag is an unsigned value; the unsigned shift keeps a magnitude of 2^30
+        // or more from being read as a negative number by the varint writer.
+        this.variant32(((value << 1) ^ (value >> 31)) >>> 0);
     }
+    /**
+     * Write an unsigned 32-bit integer as a varint.
+     *
+     * @evidence contracts/common.md#principled-implementation The value is written as a seven-bit group varint.
+     * @evidence contracts/common.md#clear-and-simple-design One delegation.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The rule is the wire format's.
+     * @evidence contracts/common.md#meaningful-documentation A short comment states what is written.
+     */
     uint32(value) {
         this.variant32(value);
     }
+    /**
+     * Write a signed 64-bit integer in ZigZag form.
+     *
+     * @evidence contracts/common.md#principled-implementation The number or bigint is converted to a bigint and ZigZag mapped, then written as an unsigned 64-bit varint.
+     * @evidence contracts/common.md#clear-and-simple-design One expression over the 64-bit writer.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The mapping is the protobuf definition.
+     * @evidence contracts/common.md#meaningful-documentation A short comment states what is written.
+     */
     sint64(value) {
         value = BigInt(value);
         this.variant64((value << BigInt(0x01)) ^ (value >> BigInt(0x3f)));
     }
+    /**
+     * Write a signed 64-bit integer as a varint of its unsigned pattern.
+     *
+     * @evidence contracts/common.md#principled-implementation The value is converted to a bigint and written as an unsigned 64-bit pattern, so negative values take ten bytes.
+     * @evidence contracts/common.md#clear-and-simple-design One delegation.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The rule is the wire format's.
+     * @evidence contracts/common.md#meaningful-documentation A short comment states what is written.
+     */
     int64(value) {
         this.variant64(BigInt(value));
     }
+    /**
+     * Write an unsigned 64-bit integer as a varint.
+     *
+     * @evidence contracts/common.md#principled-implementation The value is converted to a bigint and written as a 64-bit varint.
+     * @evidence contracts/common.md#clear-and-simple-design One delegation.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The rule is the wire format's.
+     * @evidence contracts/common.md#meaningful-documentation A short comment states what is written.
+     */
     uint64(value) {
         this.variant64(BigInt(value));
     }
+    /**
+     * Write a 32-bit float in little-endian order.
+     *
+     * @evidence contracts/common.md#principled-implementation Four little-endian bytes through the data view, advancing the pointer.
+     * @evidence contracts/common.md#clear-and-simple-design One store.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The rule is the wire format's.
+     * @evidence contracts/common.md#meaningful-documentation A short comment states what is written.
+     */
     float(val) {
         this.view.setFloat32(this.ptr, val, true);
         this.ptr += 4;
     }
+    /**
+     * Write a 64-bit float in little-endian order.
+     *
+     * @evidence contracts/common.md#principled-implementation Eight little-endian bytes through the data view, advancing the pointer.
+     * @evidence contracts/common.md#clear-and-simple-design One store.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The rule is the wire format's.
+     * @evidence contracts/common.md#meaningful-documentation A short comment states what is written.
+     */
     double(val) {
         this.view.setFloat64(this.ptr, val, true);
         this.ptr += 8;
     }
+    /**
+     * Write the length prefix and the bytes.
+     *
+     * @evidence contracts/common.md#principled-implementation The byte length is written as an unsigned varint and the bytes are copied after it.
+     * @evidence contracts/common.md#clear-and-simple-design One prefix write and one copy loop.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The rule is the wire format's.
+     * @evidence contracts/common.md#meaningful-documentation A short comment states what is written.
+     */
     bytes(value) {
         this.uint32(value.byteLength);
         for (let i = 0; i < value.byteLength; i++)
             this.buf[this.ptr++] = value[i];
     }
+    /**
+     * Write the recorded byte length and the UTF-8 bytes.
+     *
+     * @evidence contracts/common.md#principled-implementation The UTF-8 byte length that the sizer recorded is written as the prefix and the encoded bytes follow, so the length is not measured twice and always matches the bytes if the same string is written as was sized.
+     * @evidence contracts/common.md#clear-and-simple-design One function using the recorded length and a shared encoder.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts A different string than the one sized would corrupt the layout, which this class does not guard.
+     * @evidence contracts/common.md#meaningful-documentation A short comment states what is written.
+     */
     string(value) {
         const len = this.varlen(); // use precomputed length
         this.uint32(len);
@@ -62,15 +182,48 @@ class _ProtobufWriter {
         for (let i = 0; i < binary.byteLength; i++)
             this.buf[this.ptr++] = binary[i];
     }
+    /**
+     * Write the recorded length of the message that follows.
+     *
+     * @evidence contracts/common.md#principled-implementation The next recorded length is read from the sizer and written as the prefix of the message that follows.
+     * @evidence contracts/common.md#clear-and-simple-design One delegation to the length cursor.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The recorded lengths come from the sizer and are not recomputed.
+     * @evidence contracts/common.md#meaningful-documentation A short comment states what is written.
+     */
     fork() {
         this.uint32(this.varlen()); // use precomputed length
     }
+    /**
+     * Do nothing, because the sizer already recorded the length that `fork`
+     * wrote.
+     *
+     * @evidence contracts/common.md#principled-implementation Nothing remains to be done at the end of a message, because the prefix was written by fork from the sizer's measurement.
+     * @evidence contracts/common.md#clear-and-simple-design An empty method that keeps the writer interface symmetrical with the sizer.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The comment says the work is done by the sizer.
+     * @evidence contracts/common.md#meaningful-documentation An inline comment states why it is empty.
+     */
     ldelim() {
         // nothing to do - all dirty work done by sizer
     }
+    /**
+     * Return the filled buffer.
+     *
+     * @evidence contracts/common.md#principled-implementation Returns the filled buffer, which equals the measured length when the call order matched.
+     * @evidence contracts/common.md#clear-and-simple-design One accessor.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It returns the buffer without trimming or copying.
+     * @evidence contracts/common.md#meaningful-documentation A short comment states what is returned.
+     */
     finish() {
         return this.buf;
     }
+    /**
+     * Allocate a new buffer of the sizer's current length and rewind the writer.
+     *
+     * @evidence contracts/common.md#principled-implementation A fresh buffer of the sizer's current length is allocated and the pointers rewound so the writer can be reused after the sizer was reset and refilled.
+     * @evidence contracts/common.md#clear-and-simple-design Four assignments.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts No old buffer is retained.
+     * @evidence contracts/common.md#meaningful-documentation A short comment states what is rebuilt.
+     */
     reset() {
         this.buf = new Uint8Array(this.sizer.len);
         this.view = new DataView(this.buf.buffer);

package/lib/internal/_ProtobufWriter.js.map

@@ -1 +1 @@
-{"version":3,"file":"_ProtobufWriter.js","sourceRoot":"","sources":["../../src/internal/_ProtobufWriter.ts"],"names":[],"mappings":";;;AAAA,wCAAyC;AAKzC,kHAAkH;AAClH;IAgBE,YAAY,KAAqB;QAC/B,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,GAAG,GAAG,IAAI,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACrC,IAAI,CAAC,IAAI,GAAG,IAAI,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAC1C,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC;QACb,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC;IACrB,CAAC;IAED,MAAM;QACJ,OAAO,IAAI,CAAC,GAAG,CAAC;IAClB,CAAC;IAED,IAAI,CAAC,KAAc;QACjB,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3B,CAAC;IAED,IAAI,CAAC,KAAa;QAChB,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,KAAK,GAAG,GAAG,CAAC;IACrC,CAAC;IAED,KAAK,CAAC,KAAa;QACjB,IAAI,KAAK,GAAG,CAAC;YAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;;YAC5B,IAAI,CAAC,SAAS,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC;IACnC,CAAC;IAED,MAAM,CAAC,KAAa;QAClB,IAAI,CAAC,SAAS,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC;IAC/C,CAAC;IAED,MAAM,CAAC,KAAa;QAClB,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IACxB,CAAC;IAED,MAAM,CAAC,KAAsB;QAC3B,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QACtB,IAAI,CAAC,SAAS,CAAC,CAAC,KAAK,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,KAAK,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACpE,CAAC;IAED,KAAK,CAAC,KAAsB;QAC1B,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IAChC,CAAC;IAED,MAAM,CAAC,KAAsB;QAC3B,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IAChC,CAAC;IAED,KAAK,CAAC,GAAW;QACf,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;QAC1C,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC;IAChB,CAAC;IAED,MAAM,CAAC,GAAW;QAChB,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;QAC1C,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC;IAChB,CAAC;IAED,KAAK,CAAC,KAAiB;QACrB,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;QAC9B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,UAAU,EAAE,CAAC,EAAE;YAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC;IAC9E,CAAC;IAED,MAAM,CAAC,KAAa;QAClB,MAAM,GAAG,GAAW,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,yBAAyB;QAC5D,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAEjB,MAAM,MAAM,GAAe,IAAI,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACpD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,UAAU,EAAE,CAAC,EAAE;YACxC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,CAAE,CAAC;IACtC,CAAC;IAED,IAAI;QACF,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,yBAAyB;IACvD,CAAC;IAED,MAAM;QACJ,+CAA+C;IACjD,CAAC;IAED,MAAM;QACJ,OAAO,IAAI,CAAC,GAAG,CAAC;IAClB,CAAC;IAED,KAAK;QACH,IAAI,CAAC,GAAG,GAAG,IAAI,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC1C,IAAI,CAAC,IAAI,GAAG,IAAI,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAC1C,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC;QACb,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC;IACrB,CAAC;IAEO,SAAS,CAAC,GAAW;QAC3B,OAAO,GAAG,GAAG,IAAI,EAAE,CAAC;YAClB,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;YAC3C,GAAG,GAAG,GAAG,KAAK,CAAC,CAAC;QAClB,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,GAAG,CAAC;IAC7B,CAAC;IAEO,SAAS,CAAC,GAAW;QAC3B,GAAG,GAAG,MAAM,CAAC,OAAO,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;QAC9B,OAAO,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;YAC1B,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;YACnE,GAAG,GAAG,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC;QAC5B,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IACrC,CAAC;IAEO,MAAM;QACZ,OAAO,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM;YAC/C,CAAC,CAAC,CAAC;YACH,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,CAAE,CAAC;IAC3C,CAAC;CACF;;AACD,MAAM,IAAI,GAAG,IAAI,iBAAS,CAAC,GAAG,EAAE,CAAC,IAAI,WAAW,EAAE,CAAC,CAAC"}
+{"version":3,"file":"_ProtobufWriter.js","sourceRoot":"","sources":["../../src/internal/_ProtobufWriter.ts"],"names":[],"mappings":"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"}

package/lib/internal/_ProtobufWriter.mjs

@@ -1,5 +1,18 @@
 import { Singleton } from "@typia/utils";
 //#region src/internal/_ProtobufWriter.ts
+/**
+* Writes a Protocol Buffer message into a buffer that {@link _ProtobufSizer}
+* sized.
+*
+* The calls must match the sizer's calls in order, because string and message
+* lengths are read back from the sizer instead of being measured again. Adapted
+* from the fixed writer of as-proto.
+*
+* @evidence contracts/common.md#principled-implementation The writer allocates one buffer of the length the sizer measured and fills it in the same call order, reading the recorded string and message lengths from the sizer in sequence, so no length is recomputed and the buffer is exactly the right size. Varints are written in seven-bit groups, ZigZag values are unsigned, floats are little-endian and strings are UTF-8 encoded.
+* @evidence contracts/common.md#clear-and-simple-design One class holding the buffer, a data view, the write pointer and a cursor into the sizer's lengths; its private varint writers are shared by the scalar methods.
+* @evidence contracts/common.md#prohibited-implementation-shortcuts It adapts the as-proto fixed writer and follows the protobuf wire format; a call order that differs from the sizer's is a contract violation that this class does not detect.
+* @evidence contracts/common.md#meaningful-documentation A reference comment names the origin and the fields have comments; the public methods are documented individually.
+*/
 var _ProtobufWriter = class {
 	constructor(sizer) {
 		this.sizer = sizer;
@@ -8,60 +21,198 @@ var _ProtobufWriter = class {
 		this.ptr = 0;
 		this.varlenidx = 0;
 	}
+	/**
+	* Return the buffer that is being filled.
+	*
+	* @evidence contracts/common.md#principled-implementation Returns the buffer that is being filled, which has the final length from construction.
+	* @evidence contracts/common.md#clear-and-simple-design One accessor.
+	* @evidence contracts/common.md#prohibited-implementation-shortcuts It returns the same buffer and does not copy.
+	* @evidence contracts/common.md#meaningful-documentation A short comment states what is returned.
+	*/
 	buffer() {
 		return this.buf;
 	}
+	/**
+	* Write a boolean as one byte.
+	*
+	* @evidence contracts/common.md#principled-implementation One byte of zero or one, through the byte writer.
+	* @evidence contracts/common.md#clear-and-simple-design One delegation.
+	* @evidence contracts/common.md#prohibited-implementation-shortcuts The rule is the wire format's.
+	* @evidence contracts/common.md#meaningful-documentation A short comment states what is written.
+	*/
 	bool(value) {
 		this.byte(value ? 1 : 0);
 	}
+	/**
+	* Write the low eight bits of the value.
+	*
+	* @evidence contracts/common.md#principled-implementation Writes the low eight bits of the value at the pointer and advances it, which is the primitive that bool and the varint writers build on.
+	* @evidence contracts/common.md#clear-and-simple-design One store.
+	* @evidence contracts/common.md#prohibited-implementation-shortcuts The mask makes an out-of-range input wrap instead of corrupting neighbors.
+	* @evidence contracts/common.md#meaningful-documentation A short comment states what is written.
+	*/
 	byte(value) {
 		this.buf[this.ptr++] = value & 255;
 	}
+	/**
+	* Write a signed 32-bit integer; a negative value is sign-extended to a
+	* 64-bit varint.
+	*
+	* @evidence contracts/common.md#principled-implementation A negative value goes through the 64-bit writer so it is sign-extended to ten bytes, and a non-negative one is written as an unsigned 32-bit varint.
+	* @evidence contracts/common.md#clear-and-simple-design One branch over two writers.
+	* @evidence contracts/common.md#prohibited-implementation-shortcuts The rule is the wire format's.
+	* @evidence contracts/common.md#meaningful-documentation A short comment states what is written.
+	*/
 	int32(value) {
 		if (value < 0) this.int64(value);
 		else this.variant32(value >>> 0);
 	}
+	/**
+	* Write a signed 32-bit integer in ZigZag form as an unsigned varint.
+	*
+	* @evidence contracts/common.md#principled-implementation The ZigZag value is converted to unsigned before the varint is written, so magnitudes of 2^30 or more are written in five bytes; the sizer measures the same value, so the announced and written lengths agree.
+	* @evidence contracts/common.md#clear-and-simple-design One expression over the shared writer.
+	* @evidence contracts/common.md#prohibited-implementation-shortcuts The mapping is the protobuf definition.
+	* @evidence contracts/common.md#meaningful-documentation A comment states the unsigned mapping and why it is needed.
+	*/
 	sint32(value) {
-		this.variant32(value << 1 ^ value >> 31);
-	}
+		this.variant32((value << 1 ^ value >> 31) >>> 0);
+	}
+	/**
+	* Write an unsigned 32-bit integer as a varint.
+	*
+	* @evidence contracts/common.md#principled-implementation The value is written as a seven-bit group varint.
+	* @evidence contracts/common.md#clear-and-simple-design One delegation.
+	* @evidence contracts/common.md#prohibited-implementation-shortcuts The rule is the wire format's.
+	* @evidence contracts/common.md#meaningful-documentation A short comment states what is written.
+	*/
 	uint32(value) {
 		this.variant32(value);
 	}
+	/**
+	* Write a signed 64-bit integer in ZigZag form.
+	*
+	* @evidence contracts/common.md#principled-implementation The number or bigint is converted to a bigint and ZigZag mapped, then written as an unsigned 64-bit varint.
+	* @evidence contracts/common.md#clear-and-simple-design One expression over the 64-bit writer.
+	* @evidence contracts/common.md#prohibited-implementation-shortcuts The mapping is the protobuf definition.
+	* @evidence contracts/common.md#meaningful-documentation A short comment states what is written.
+	*/
 	sint64(value) {
 		value = BigInt(value);
 		this.variant64(value << BigInt(1) ^ value >> BigInt(63));
 	}
+	/**
+	* Write a signed 64-bit integer as a varint of its unsigned pattern.
+	*
+	* @evidence contracts/common.md#principled-implementation The value is converted to a bigint and written as an unsigned 64-bit pattern, so negative values take ten bytes.
+	* @evidence contracts/common.md#clear-and-simple-design One delegation.
+	* @evidence contracts/common.md#prohibited-implementation-shortcuts The rule is the wire format's.
+	* @evidence contracts/common.md#meaningful-documentation A short comment states what is written.
+	*/
 	int64(value) {
 		this.variant64(BigInt(value));
 	}
+	/**
+	* Write an unsigned 64-bit integer as a varint.
+	*
+	* @evidence contracts/common.md#principled-implementation The value is converted to a bigint and written as a 64-bit varint.
+	* @evidence contracts/common.md#clear-and-simple-design One delegation.
+	* @evidence contracts/common.md#prohibited-implementation-shortcuts The rule is the wire format's.
+	* @evidence contracts/common.md#meaningful-documentation A short comment states what is written.
+	*/
 	uint64(value) {
 		this.variant64(BigInt(value));
 	}
+	/**
+	* Write a 32-bit float in little-endian order.
+	*
+	* @evidence contracts/common.md#principled-implementation Four little-endian bytes through the data view, advancing the pointer.
+	* @evidence contracts/common.md#clear-and-simple-design One store.
+	* @evidence contracts/common.md#prohibited-implementation-shortcuts The rule is the wire format's.
+	* @evidence contracts/common.md#meaningful-documentation A short comment states what is written.
+	*/
 	float(val) {
 		this.view.setFloat32(this.ptr, val, true);
 		this.ptr += 4;
 	}
+	/**
+	* Write a 64-bit float in little-endian order.
+	*
+	* @evidence contracts/common.md#principled-implementation Eight little-endian bytes through the data view, advancing the pointer.
+	* @evidence contracts/common.md#clear-and-simple-design One store.
+	* @evidence contracts/common.md#prohibited-implementation-shortcuts The rule is the wire format's.
+	* @evidence contracts/common.md#meaningful-documentation A short comment states what is written.
+	*/
 	double(val) {
 		this.view.setFloat64(this.ptr, val, true);
 		this.ptr += 8;
 	}
+	/**
+	* Write the length prefix and the bytes.
+	*
+	* @evidence contracts/common.md#principled-implementation The byte length is written as an unsigned varint and the bytes are copied after it.
+	* @evidence contracts/common.md#clear-and-simple-design One prefix write and one copy loop.
+	* @evidence contracts/common.md#prohibited-implementation-shortcuts The rule is the wire format's.
+	* @evidence contracts/common.md#meaningful-documentation A short comment states what is written.
+	*/
 	bytes(value) {
 		this.uint32(value.byteLength);
 		for (let i = 0; i < value.byteLength; i++) this.buf[this.ptr++] = value[i];
 	}
+	/**
+	* Write the recorded byte length and the UTF-8 bytes.
+	*
+	* @evidence contracts/common.md#principled-implementation The UTF-8 byte length that the sizer recorded is written as the prefix and the encoded bytes follow, so the length is not measured twice and always matches the bytes if the same string is written as was sized.
+	* @evidence contracts/common.md#clear-and-simple-design One function using the recorded length and a shared encoder.
+	* @evidence contracts/common.md#prohibited-implementation-shortcuts A different string than the one sized would corrupt the layout, which this class does not guard.
+	* @evidence contracts/common.md#meaningful-documentation A short comment states what is written.
+	*/
 	string(value) {
 		const len = this.varlen();
 		this.uint32(len);
 		const binary = utf8.get().encode(value);
 		for (let i = 0; i < binary.byteLength; i++) this.buf[this.ptr++] = binary[i];
 	}
+	/**
+	* Write the recorded length of the message that follows.
+	*
+	* @evidence contracts/common.md#principled-implementation The next recorded length is read from the sizer and written as the prefix of the message that follows.
+	* @evidence contracts/common.md#clear-and-simple-design One delegation to the length cursor.
+	* @evidence contracts/common.md#prohibited-implementation-shortcuts The recorded lengths come from the sizer and are not recomputed.
+	* @evidence contracts/common.md#meaningful-documentation A short comment states what is written.
+	*/
 	fork() {
 		this.uint32(this.varlen());
 	}
+	/**
+	* Do nothing, because the sizer already recorded the length that `fork`
+	* wrote.
+	*
+	* @evidence contracts/common.md#principled-implementation Nothing remains to be done at the end of a message, because the prefix was written by fork from the sizer's measurement.
+	* @evidence contracts/common.md#clear-and-simple-design An empty method that keeps the writer interface symmetrical with the sizer.
+	* @evidence contracts/common.md#prohibited-implementation-shortcuts The comment says the work is done by the sizer.
+	* @evidence contracts/common.md#meaningful-documentation An inline comment states why it is empty.
+	*/
 	ldelim() {}
+	/**
+	* Return the filled buffer.
+	*
+	* @evidence contracts/common.md#principled-implementation Returns the filled buffer, which equals the measured length when the call order matched.
+	* @evidence contracts/common.md#clear-and-simple-design One accessor.
+	* @evidence contracts/common.md#prohibited-implementation-shortcuts It returns the buffer without trimming or copying.
+	* @evidence contracts/common.md#meaningful-documentation A short comment states what is returned.
+	*/
 	finish() {
 		return this.buf;
 	}
+	/**
+	* Allocate a new buffer of the sizer's current length and rewind the writer.
+	*
+	* @evidence contracts/common.md#principled-implementation A fresh buffer of the sizer's current length is allocated and the pointers rewound so the writer can be reused after the sizer was reset and refilled.
+	* @evidence contracts/common.md#clear-and-simple-design Four assignments.
+	* @evidence contracts/common.md#prohibited-implementation-shortcuts No old buffer is retained.
+	* @evidence contracts/common.md#meaningful-documentation A short comment states what is rebuilt.
+	*/
 	reset() {
 		this.buf = new Uint8Array(this.sizer.len);
 		this.view = new DataView(this.buf.buffer);