Initial Commit

packages/foundation/flow/cbor/src/encoder/encoder.md

@@ -0,0 +1,89 @@
+# `encoder`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs --> - half-float — Encodes a JavaScript `number` as IEEE……
+- [half-float](./half-float.md) — Encodes a JavaScript `number` as IEEE 754 binary16 (CBOR major 7 / value 25) when the round-trip is exact, and otherwis…
+- half-float — Encodes a JavaScript `number` as IEEE……
+
+- [half-float](./half-float.md) — Encodes a JavaScript `number` as IEEE 754 binary16 (CBOR major 7 / value 25) when the round-trip is exact, and otherwis…
+
+- half-float — Encodes a JavaScript `number` as IEEE……
+
+- [half-float](./half-float.md) — Encodes a JavaScript `number` as IEEE 754 binary16 (CBOR major 7 / value 25) when the round-trip is exact, and otherwis…
+
+- half-float — Encodes a JavaScript `number` as IEEE…
+
+- [half-float](./half-float.md) — Encodes a JavaScript `number` as IEEE 754 binary16 (CBOR major 7 / value 25) when the round-trip is exact, and otherwis…
+- [half-float](./half-float.md) — Encodes a JavaScript `number` as IEEE 754 binary16 (CBOR major 7 / value 25) when the round-trip is exact, and otherwis…
+
+## Purpose
+
+The CBOR encoder serialises an arbitrary JavaScript value into RFC 8949 binary
+form. It supports every CBOR major type (0–7) and applies preferred
+serialisation rules — shortest-form integers always-on, shortest-exact float
+width by default. It also exposes a deterministic-encoding mode (RFC 8949
+§4.2) for callers that need byte-stable output across runs (e.g. signature
+generation, content addressing).
+
+## Features
+
+- All seven major types: unsigned, negative, byte string, text string, array,
+  map, tag, and major-7 (simple values + floats).
+- Shortest-form integers per RFC 8949 §4.2.1 — always-on, regardless of mode.
+- Shortest-exact float selection among `{float16 (opt-in), float32, float64}`.
+- Deterministic mode: sorted map keys (lexicographic over canonical encoded
+  key bytes), no indefinite-length items, no half-float, rejects `undefined`.
+- BigInt support: ranges within `±u64` use major 0/1; outside that range, tag
+  2 (positive) or tag 3 (negative) bignum byte-string.
+- `Tagged<T>` round-trip — encode emits tag-then-inner per §3.4.
+- `Map<K,V>` and plain object literals both serialise to major 5 maps.
+- Configurable `maxDepth` (default 64) and `maxItems` (default 1_000_000)
+  guard against pathological inputs.
+
+## Usage: Basic Example
+
+```ts
+import { encode } from "@suaveplan/cbor/encoder";
+
+const bytes = encode({ a: 1, b: [true, "two"] });
+```
+
+## Usage: Advanced Example
+
+```ts
+import { encode } from "@suaveplan/cbor/encoder";
+import { Tagged } from "@suaveplan/cbor/tags";
+
+// Deterministic encoding for signing
+const claims = new Map<number, unknown>([
+  [1, "issuer"],
+  [4, new Tagged(1, 1700000000)], // exp claim with epoch tag
+]);
+const signedBytes = encode(claims, { deterministic: true });
+```
+
+## API Reference
+
+- `encode(value: unknown, options?: EncoderOptions): Uint8Array`
+- `EncoderOptions`:
+  - `deterministic?: boolean` — default `false`. Enforces RFC 8949 §4.2.
+  - `preferFloat16?: boolean` — default `false`. Try binary16 when exact.
+    Ignored when `deterministic` is `true`.
+  - `maxDepth?: number` — default 64. Throws `CBOR.NESTED_TOO_DEEP` on overflow.
+  - `maxItems?: number` — default 1_000_000. Throws `CBOR.LENGTH_OVERFLOW`.
+
+Throws `CborError` with codes `UNEXPECTED_TYPE` (functions, symbols),
+`NON_DETERMINISTIC` (e.g. `undefined` under deterministic), `NESTED_TOO_DEEP`,
+and `LENGTH_OVERFLOW`.
+
+## Implementation Notes
+
+The encoder accumulates output as an array of `Uint8Array` chunks and
+concatenates at the end. This avoids the O(n²) cost of repeatedly grow-and-
+copying a single buffer. Map-key sorting in deterministic mode encodes each
+key first (yielding the canonical bytes), then sorts the entry list by
+lexicographic byte order before emitting headers and bodies. BigInt encoding
+uses native `DataView.setBigUint64` for the in-range case and a hand-rolled
+big-endian byte builder for tag 2/3 bignums to avoid pulling in any external
+dependency.