docs: sync from coderbuzz/codex@b37bd48

Author: github-actions[bot]

AI_KNOWLEDGE.md

@@ -1,4 +1,4 @@
-<!-- docs: sync from coderbuzz/codex@200be78 -->
+<!-- docs: sync from coderbuzz/codex@b37bd48 -->
 
 # Msgpack: AI Agent Knowledge File
 
@@ -11,7 +11,7 @@
 
 ## Mental Model
 
-`@coderbuzz/msgpack` is a **single-function library** with five exported
+`@coderbuzz/msgpack` is a **small library** with five exported
 functions. It maintains a single reusable internal encoder buffer to minimize
 allocations across encode calls.
 
@@ -95,7 +95,10 @@ send(pool.subarray(0, offset));
 
 **Rules:**
 - `offset` defaults to `0`.
-- No bounds checking on `target`: caller is responsible for buffer size.
+- No bounds checking on `target`: caller is responsible for buffer size. If the
+  encoded bytes do not fit, `target.set()` throws `RangeError` and nothing is written.
+- Encodes into the internal buffer first, then copies into `target`. It resets the
+  internal buffer, so it also invalidates any earlier `encodeUnsafe` view.
 - Returns the number of bytes written.
 
 ---
@@ -112,14 +115,18 @@ const restored = decode(bytes); // => { hello: "world" }
 
 **Rules:**
 - `undefined` values round-trip as `null` (MessagePack has no `undefined` type).
+- `uint64` (`0xcf`) and `int64` (`0xd3`) always decode as `bigint`, even for small values.
+- `float32` (`0xca`) and extension formats (`fixext`/`ext`, `0xd4`-`0xd8`, `0xc7`-`0xc9`)
+  are not decoded: they throw "unknown format byte".
 - Throws on unknown format byte: `"MessagePack: unknown format byte 0xNN at offset N"`.
 - No bounds checking on `data`. Malformed input can cause out-of-bounds reads.
 
 ---
 
 ### `encodedSize(value: unknown): number`
 
-Pre-calculates encoded size without allocating. Exact: `encodedSize(val) === encode(val).length`.
+Pre-calculates encoded size without allocating. Exact for supported types: `encodedSize(val) === encode(val).length`.
+Not exact for functions and symbols: `encodedSize` counts 1 byte, `encode` writes 0 bytes.
 
 ```ts
 const size = encodedSize({ name: "Ken", age: 30 }); // pre-calc
@@ -182,7 +189,7 @@ All non-integer numbers use float64 (`0xcb`, 9 bytes).
 
 | UTF-8 Byte Length | Format | Header Size |
 |-------------------|--------|-------------|
-| 1–31 | fixstr `0xa0\|len` | 1 |
+| 0–31 | fixstr `0xa0\|len` | 1 |
 | 32–255 | str8 `0xd9` | 2 |
 | 256–65535 | str16 `0xda` | 3 |
 | > 65535 | str32 `0xdb` | 5 |
@@ -191,7 +198,7 @@ All non-integer numbers use float64 (`0xcb`, 9 bytes).
 
 | Length | Format | Header Size |
 |--------|--------|-------------|
-| 1–255 | bin8 `0xc4` | 2 |
+| 0–255 | bin8 `0xc4` | 2 |
 | 256–65535 | bin16 `0xc5` | 3 |
 | > 65535 | bin32 `0xc6` | 5 |
 
@@ -259,8 +266,8 @@ function encodeBatch(items: unknown[]): Uint8Array {
 import { encode } from "@coderbuzz/msgpack";
 
 const data = { a: 1, b: 2, c: true };
-const msgpackBytes = encode(data);      // ~10-12 bytes
-const jsonBytes = new TextEncoder().encode(JSON.stringify(data)); // ~18-20 bytes
+const msgpackBytes = encode(data);      // 10 bytes
+const jsonBytes = new TextEncoder().encode(JSON.stringify(data)); // 22 bytes
 ```
 
 ---
@@ -276,7 +283,8 @@ const jsonBytes = new TextEncoder().encode(JSON.stringify(data)); // ~18-20 byte
 | Truncated/malformed input | Out-of-bounds read (no bounds check) |
 | Very large array (> 2^32) | Not supported (JS limit) |
 | `Date` object | Encoded as ISO string, NOT timestamp ext |
-| `Symbol`, `Map`, `Set` | Not supported: will fail type check |
+| `Map`, `Set`, class instances | Encoded as a map of own enumerable string keys (`Map`/`Set` become `{}`) |
+| `Symbol`, function | **Zero bytes written**, no error. Inside an array or object this produces a corrupt stream |
 
 ---
 
@@ -330,37 +338,39 @@ value to encode
   │   ├─ Number.isInteger(v) && in varint range → smallest fixint/uint/int
   │   └─ else                                   → float64 (0xcb)
   ├─ typeof v === "string"
-  │   ├─ len < 32 → inline UTF-8 encoder (no TextEncoder)
-  │   ├─ len < 256 → str8 (0xd9)
-  │   ├─ len < 65536 → str16 (0xda)
-  │   └─ len >= 65536 → str32 (0xdb)
+  │   ├─ len < 32 (UTF-16 units) → inline UTF-8 encoder (no TextEncoder)
+  │   ├─ len >= 32 → TextEncoder
+  │   └─ header by UTF-8 byte length: < 32 fixstr, < 256 str8 (0xd9),
+  │      < 65536 str16 (0xda), else str32 (0xdb)
   ├─ typeof v === "bigint"
   │   ├─ v >= 0n → uint64 (0xcf)
   │   └─ v < 0n  → int64 (0xd3)
   ├─ v instanceof Uint8Array → bin8/16/32 based on length
   ├─ v instanceof Date → ISO string via .toISOString()
   ├─ Array.isArray(v) → fixarray/array16/32 + recursive encode
-  └─ typeof v === "object" → fixmap/map16/32 + recursive encode keys+values
+  ├─ typeof v === "object" → fixmap/map16/32 + recursive encode keys+values
+  └─ symbol / function → nothing written
 ```
 
 ### Decode Decision Tree
 
 ```
 decode byte at position
+  ├─ 0x00..0x7f (positive fixint) → return byte
+  ├─ 0xe0..0xff (negative fixint) → return byte - 256
   ├─ 0xc0 → return null (nil)
   ├─ 0xc2/0xc3 → return false/true
-  ├─ 0xca → read float32 (4 bytes)
   ├─ 0xcb → read float64 (8 bytes)
-  ├─ 0xcc..0xcf → read uint8/16/32/64
-  ├─ 0xd0..0xd3 → read int8/16/32/64
+  ├─ 0xcc..0xcf → read uint8/16/32/64 (uint64 returns bigint)
+  ├─ 0xd0..0xd3 → read int8/16/32/64 (int64 returns bigint)
   ├─ 0xa0..0xbf (fixstr) → read string of length (byte & 0x1f)
   ├─ 0xd9..0xdb (str8/16/32) → read string with header length
   ├─ 0xc4..0xc6 (bin8/16/32) → return Uint8Array
   ├─ 0x90..0x9f (fixarray) → read array of length (byte & 0x0f), recurse
   ├─ 0xdc..0xdd (array16/32) → read array with header length, recurse
   ├─ 0x80..0x8f (fixmap) → read map of length (byte & 0x0f), recurse key+value
   ├─ 0xde..0xdf (map16/32) → read map with header length, recurse key+value
-  └─ default → throw "MessagePack: unknown format byte 0xNN at offset N"
+  └─ default (incl. 0xca float32, ext/fixext) → throw "MessagePack: unknown format byte 0xNN at offset N"
 ```
 
 **ASCII fast path (decode):** Strings ≤24 bytes where all bytes are ≤ 0x7F use `String.fromCharCode()` directly, avoiding `TextDecoder`.
@@ -391,6 +401,27 @@ vs `@msgpack/msgpack`:
 - Wire size: identical (same MessagePack spec)
 
 vs JSON:
-- Encode: 4.78M ops/s faster (native, in C)
-- Decode: 1.96M ops/s faster (native, in C)
-- Wire size: msgpack is 35-60% smaller (no field names, compact numerics)
+- Encode: JSON.stringify is faster, 4.78M ops/s vs 2.04M (native)
+- Decode: JSON.parse is faster, 1.96M ops/s vs 0.90M (native)
+- Wire size: 133 bytes vs 178 for the benchmark nested object (~25% smaller).
+  Field names are still written; savings come from compact headers and numerics.
+
+### Size Comparison vs JSON
+
+| Payload type | JSON size | Msgpack size | Savings |
+|---|---|---|---|
+| Compact object `{ name, age, active }` | 39 bytes | 25 bytes | ~36% |
+| Numeric array `[1..1000]` | 3894 bytes | 2621 bytes | ~33% |
+| Nested object (benchmark payload) | 178 bytes | 133 bytes | ~25% |
+
+---
+
+## Limitations
+
+- No MessagePack extension types (Timestamp, custom ext). `Date` encodes as an ISO string.
+- Decoder does not read `float32` (`0xca`) or `ext`/`fixext`; data from other encoders
+  that emit these throws.
+- No streaming decoder: the whole message must be in memory.
+- No bounds checking on decode: only decode trusted data.
+- ESM only, no CJS build (tsup `format: ['esm']`, target `es2022`).
+- Bundle size: under 3 KB gzip.

README.md

@@ -1,8 +1,8 @@
-<!-- docs: sync from coderbuzz/codex@200be78 -->
+<!-- docs: sync from coderbuzz/codex@b37bd48 -->
 
 # Msgpack: `@coderbuzz/msgpack`
 
-> **High-performance MessagePack for TypeScript.** Smaller than JSON. 2x faster than `@msgpack/msgpack`. Zero unnecessary allocations.
+> **High-performance MessagePack for TypeScript.** Smaller than JSON. 2.7x faster encode than `@msgpack/msgpack`. Zero unnecessary allocations.
 > AI agents: see [AI_KNOWLEDGE.md](https://github.com/coderbuzz/msgpack/blob/main/AI_KNOWLEDGE.md) for expert context.
 <p align="center">
   <a href="https://www.npmjs.com/package/@coderbuzz/msgpack"><img src="https://img.shields.io/npm/v/@coderbuzz/msgpack.svg?style=flat-square" alt="npm version" /></a>
@@ -13,7 +13,7 @@
   <a href="https://codecov.io/gh/coderbuzz/msgpack"><img src="https://codecov.io/gh/coderbuzz/msgpack/graph/badge.svg" alt="Codecov" /></a>
 </p>
 
-`@coderbuzz/msgpack` is a purpose-built MessagePack encoder/decoder optimized for minimal GC pressure and maximum throughput. For structured API responses, compact objects are **~55% smaller** than JSON, and numeric arrays are **~60% smaller**.
+`@coderbuzz/msgpack` is a purpose-built MessagePack encoder/decoder optimized for minimal GC pressure and maximum throughput. Compact objects are **~35% smaller** than JSON, and small-integer arrays are **~33% smaller**.
 
 ---
 
@@ -48,16 +48,16 @@
 
 | Payload type | JSON size | Msgpack size | Savings |
 |---|---|---|---|
-| Compact object `{ name, age, active }` | ~45 bytes | ~20 bytes | **~55%** |
-| Numeric array `[1..1000]` | ~3.9 KB | ~1.5 KB | **~60%** |
-| Structured API response (nested) | ~2 KB | ~1.3 KB | **~35%** |
+| Compact object `{ name, age, active }` | 39 bytes | 25 bytes | **~36%** |
+| Numeric array `[1..1000]` | 3894 bytes | 2621 bytes | **~33%** |
+| Nested object (benchmark payload) | 178 bytes | 133 bytes | **~25%** |
 
 ### Throughput & Wire Size (Apple M-series, Bun)
 
 Full results at **[github.com/coderbuzz/benchmarks](https://github.com/coderbuzz/benchmarks)**.
 
 | Scenario | @coderbuzz/msgpack | @msgpack/msgpack | Factor |
-|---|---|---|---|---|
+|---|---|---|---|
 | Nested object encode | **2.04M ops/s** | 0.77M | **2.7x** |
 | Nested object decode | **0.90M ops/s** | 0.87M | **1.04x** |
 | Wire size (nested object) | **133 bytes** | 133 bytes | Same |
@@ -84,10 +84,10 @@ import { encode, decode } from "npm:@coderbuzz/msgpack";
 ## Quick Start
 
 ```ts
-import { decode, encode } from "@coderbuzz/msgpack";
+import { decode, encode, encodedSize, encodeInto, encodeUnsafe } from "@coderbuzz/msgpack";
 
 const bytes = encode({ name: "Alice", age: 30, active: true });
-// => Uint8Array (compact binary, ~20 bytes vs ~45 bytes JSON)
+// => Uint8Array (compact binary, 25 bytes vs 39 bytes JSON)
 
 const value = decode(bytes);
 // => { name: "Alice", age: 30, active: true }
@@ -171,7 +171,7 @@ const buffer = new Uint8Array(size);
 encodeInto({ name: "Alice", age: 30, scores: [1, 2, 3] }, buffer);
 ```
 
-`encodedSize(val) === encode(val).length` always holds.
+`encodedSize(val) === encode(val).length` holds for the supported types above. It does not hold for functions and symbols, which `encode` writes as zero bytes.
 
 ---
 
@@ -196,7 +196,7 @@ encodeInto({ name: "Alice", age: 30, scores: [1, 2, 3] }, buffer);
 
 | Byte Length | Format | Header Size |
 |---|---|---|
-| 1–31 | fixstr | 1 byte |
+| 0–31 | fixstr | 1 byte |
 | 32–255 | str8 | 2 bytes |
 | 256–65535 | str16 | 3 bytes |
 | > 65535 | str32 | 5 bytes |
@@ -251,6 +251,7 @@ function batchEncode(items: unknown[]): Uint8Array {
 ## Limitations
 
 - **No MessagePack extension types**: Timestamp, custom extensions not supported. `Date` objects are ISO strings.
+- **Decoder reads only what the encoder writes**: `float32` (`0xca`), `fixext`/`ext` (`0xd4`-`0xd8`, `0xc7`-`0xc9`) throw "unknown format byte". Data from encoders that emit float32 will not decode.
 - **No streaming/SAX decoder**: Entire message in memory.
 - **No bounds checking on decode**: Only decode trusted data.
 - **No CJS build**: ESM only. Node.js 18+ with `"type": "module"`.