# msgpack-decode

## Purpose

Implements `decodeBinary`, the inverse of `encodeBinary`. Given a MessagePack binary buffer produced by the encoder, it reconstructs the original JavaScript value by first decoding the msgpack wire bytes to an intermediate plain-JS-object representation and then applying the same tag-based reconstruction logic used by `deserialize`.

The two-phase approach (msgpack decode → tag reconstruct) keeps the decoder code minimal and reuses the same registry lookup path as the JSON decoder.

## Features

- Full inverse of `encodeBinary`: all built-in and custom registered types are reconstructed
- `UnsupportedTypeError` thrown on unrecognised `__t` tags (same strict policy as JSON decoder)
- Reuses a single shared `Decoder` instance for zero allocation overhead across calls
- `DeserializeOptions` parameter accepted for API consistency with the JSON codec (signal not yet applied internally, as msgpack decode is synchronous and very fast)

## Usage: Basic Example

```typescript
import { decodeBinary, encodeBinary } from "@suaveplan/serialize";

const original = new Map([["key", new Date()]]);
const bytes = encodeBinary(original);
const restored = decodeBinary(bytes) as Map<string, Date>;

restored instanceof Map;           // true
restored.get("key") instanceof Date; // true
```

## Usage: Advanced Example

```typescript
import { decodeBinary, UnsupportedTypeError } from "@suaveplan/serialize";

async function receiveMessage(bytes: Uint8Array) {
  try {
    const value = decodeBinary(bytes);
    return value;
  } catch (err) {
    if (err instanceof UnsupportedTypeError) {
      // The sender used a type tag unknown to this receiver.
      // Either register the type or reject the message.
      throw new Error(`Unknown type: ${err.context?.tag}`);
    }
    throw err;
  }
}
```

## API Reference

### `decodeBinary(bytes: Uint8Array, opts?: DeserializeOptions): unknown`

Decode a MessagePack buffer to the original JavaScript value.

**Parameters:**

- `bytes` — a `Uint8Array` produced by `encodeBinary`
- `opts` — `DeserializeOptions` (accepted for API parity; signal not currently applied within this synchronous path)

**Returns:** the reconstructed JavaScript value.

**Throws:**

- `UnsupportedTypeError` when a `__t` tag has no registered decoder
- `RangeError` or `TypeError` from `@msgpack/msgpack` if the input bytes are malformed

### `DeserializeOptions`

See `json-decode.md`.

## Implementation Notes

- A single shared `Decoder` instance is reused to avoid per-call setup overhead; the decoder is stateless between calls.
- The `postDecode` function is structurally identical to the inner `decodeValue` used by `json-decode.ts`. Future refactoring could extract it to a shared utility; currently it is kept local to avoid premature abstraction.
- The `opts` parameter is accepted but currently unused because the msgpack decode step is synchronous and does not lend itself to mid-stream cancellation without a streaming API.