Improve documentation with centralized docs/ folder and enhanced README

README.md

@@ -2,19 +2,51 @@
 
 High performance JSON serialization and deserialization library for JavaScript, Node.js, browser.
 
-`json-pack` contains implementations of various JSON codecs into binary,
-formats, such as MessagePack, CBOR and other formats.
+`json-pack` contains implementations of various JSON codecs into binary formats, such as MessagePack, CBOR and other formats.
 
-- [__MessagePack__](./src/msgpack/README.md)
-- [__CBOR__](./src/cbor/README.md)
-- DAG-CBOR
-- JSON
-- DAG-JSON
-- UBJSON
-- Amazon Ion
-- RESP3
-- Bencode
+## Supported Formats
 
+This library implements the following serialization formats:
+
+- **[MessagePack](./docs/msgpack.md)** - Fast and lean implementation of MessagePack codec
+- **[CBOR](./docs/cbor.md)** - Concise Binary Object Representation codec
+- **[UBJSON](./docs/ubjson.md)** - Universal Binary JSON codec  
+- **[JSON](./docs/json.md)** - Enhanced JSON encoder/decoder with additional features
+- **[JSON Binary](./docs/json-binary.md)** - JSON with binary data support using Uint8Array
+- **[Amazon Ion](./docs/ion.md)** - Amazon's Ion data serialization format
+- **[BSON](./docs/bson.md)** - Binary JSON format used by MongoDB
+- **[RESP](./docs/resp.md)** - Redis Serialization Protocol (v2 and v3)
+- **[Bencode](./docs/bencode.md)** - BitTorrent's encoding format
+
+Each format comes with optimized encoders and decoders designed for maximum performance.
+
+## Installation
+
+```bash
+npm install @jsonjoy.com/json-pack
+```
+
+## Quick Start
+
+```ts
+import {MessagePackEncoder, MessagePackDecoder} from '@jsonjoy.com/json-pack/lib/msgpack';
+
+const encoder = new MessagePackEncoder();
+const decoder = new MessagePackDecoder();
+
+const data = {hello: 'world', numbers: [1, 2, 3]};
+const binary = encoder.encode(data);
+const restored = decoder.decode(binary);
+
+console.log(restored); // {hello: 'world', numbers: [1, 2, 3]}
+```
+
+## Documentation
+
+For detailed documentation on each codec, see the [docs/](./docs/) folder:
+
+- [Complete documentation index](./docs/README.md)
+- Individual codec documentation linked above in the "Supported Formats" section
 
 ## Benchmarks
 

docs/README.md

@@ -0,0 +1,115 @@
+# json-pack Documentation
+
+Welcome to the `json-pack` documentation. This library provides high-performance implementations of various binary serialization formats for JavaScript.
+
+## Available Codecs
+
+### Binary Formats
+
+- **[MessagePack](./msgpack.md)** - Fast and efficient binary serialization format
+  - Compact binary representation
+  - Support for binary data and extensions
+  - Fastest JavaScript implementation
+
+- **[CBOR](./cbor.md)** - Concise Binary Object Representation (RFC 7049)
+  - Self-describing binary format
+  - Rich data type support
+  - DAG-CBOR variant available
+
+- **[UBJSON](./ubjson.md)** - Universal Binary JSON
+  - Binary JSON with type information
+  - Fixed-length encoding for better performance
+  - Support for typed arrays
+
+- **[BSON](./bson.md)** - Binary JSON (MongoDB format)
+  - Document-oriented binary format
+  - Rich type system including dates and binary data
+  - MongoDB-compatible implementation
+
+### Protocol Formats
+
+- **[RESP](./resp.md)** - Redis Serialization Protocol
+  - RESP2 and RESP3 support
+  - Streaming decoder available
+  - Redis-compatible implementation
+
+- **[Amazon Ion](./ion.md)** - Amazon's data format
+  - Self-describing with rich type system
+  - Binary and text representations
+  - Symbol table support
+
+### Network/Transfer Formats
+
+- **[Bencode](./bencode.md)** - BitTorrent encoding format
+  - Simple binary encoding
+  - Dictionary ordering for reproducible output
+  - Extensions for additional types
+
+### Enhanced JSON
+
+- **[JSON](./json.md)** - High-performance JSON encoder/decoder
+  - Faster than native JSON in many cases
+  - Optimized for repeated operations
+  - Binary-safe implementation
+
+- **[JSON Binary](./json-binary.md)** - JSON with binary data support
+  - Uint8Array support via Base64 encoding
+  - Drop-in replacement for JSON with binary data
+
+## Performance
+
+All codecs in this library are optimized for performance and typically outperform other JavaScript implementations. Each codec documentation includes detailed benchmarks comparing performance against popular alternatives.
+
+## Usage Patterns
+
+### Basic Usage
+
+```ts
+import {MessagePackEncoder, MessagePackDecoder} from 'json-pack/lib/msgpack';
+
+const encoder = new MessagePackEncoder();
+const decoder = new MessagePackDecoder();
+
+const data = {hello: 'world', count: 42};
+const encoded = encoder.encode(data);
+const decoded = decoder.decode(encoded);
+```
+
+### Streaming Usage
+
+Many codecs support streaming operations for handling large datasets:
+
+```ts
+import {RespStreamingDecoder} from 'json-pack/lib/resp';
+
+const decoder = new RespStreamingDecoder();
+// Process streaming data...
+```
+
+### Binary Data
+
+Several codecs support efficient binary data handling:
+
+```ts
+import {MessagePackEncoderFull} from 'json-pack/lib/msgpack';
+
+const encoder = new MessagePackEncoderFull();
+const data = {
+  text: 'hello',
+  binary: new Uint8Array([1, 2, 3, 4])
+};
+const encoded = encoder.encode(data);
+```
+
+## Choosing a Format
+
+- **MessagePack**: Best general-purpose binary format, fastest performance
+- **CBOR**: Standards-compliant, rich type system, good for interoperability  
+- **BSON**: When working with MongoDB or need document-oriented features
+- **RESP**: For Redis protocol compatibility
+- **Ion**: When you need Amazon Ion compatibility or rich type annotations
+- **JSON**: When you need text format with better performance than native JSON
+- **Bencode**: For BitTorrent protocol compatibility
+- **UBJSON**: When you need typed binary JSON
+
+Each format has its strengths - choose based on your specific requirements for performance, compatibility, and features.

docs/bencode.md

@@ -0,0 +1,22 @@
+# Bencode codecs
+
+Implements [Bencode][bencode] encoder and decoder.
+
+[bencode]: https://en.wikipedia.org/wiki/Bencode
+
+Type coercion:
+
+- Strings and `Uint8Array` are encoded as Bencode byte strings, decoded as `Uint8Array`.
+- `Object` and `Map` are encoded as Bencode dictionaries, decoded as `Object`.
+- `Array` and `Set` are encoded as Bencode lists, decoded as `Array`.
+- `number` and `bigint` are encoded as Bencode integers, decoded as `number`.
+- Float `number` are rounded and encoded as Bencode integers, decoded as `number`.
+
+
+## Extensions
+
+This codec extends the Bencode specification to support the following types:
+
+- `null` (encoded as `n`)
+- `undefined` (encoded as `u`)
+- `boolean` (encoded as `t` for `true` and `f` for `false`)

docs/bson.md

@@ -0,0 +1,90 @@
+# BSON
+
+Performant implementation of [BSON][bson] (Binary JSON) for JavaScript.
+
+[bson]: https://bsonspec.org/
+
+## Overview
+
+BSON (Binary JSON) is a binary representation of JSON-like documents. It extends JSON's data model to provide additional data types, ordered fields, and efficient encoding and decoding.
+
+## Features
+
+- High-performance BSON encoding and decoding
+- Support for all BSON data types including:
+  - ObjectId
+  - Binary data
+  - Dates
+  - Regular expressions
+  - JavaScript code
+- MongoDB-compatible implementation
+- Efficient binary representation
+
+## Usage
+
+```ts
+import {BsonEncoder, BsonDecoder} from 'json-pack/lib/bson';
+
+const encoder = new BsonEncoder();
+const decoder = new BsonDecoder();
+
+const data = {
+  name: 'example',
+  created: new Date(),
+  binary: new Uint8Array([1, 2, 3])
+};
+
+const encoded = encoder.encode(data);
+const decoded = decoder.decode(encoded);
+```
+
+
+## Benchmarks
+
+```
+npx ts-node benchmarks/json-pack/bench.bson.encoding.ts
+=============================================================================== Benchmark: Encoding
+Warmup: 1000x , Node.js: v20.4.0 , Arch: arm64 , CPU: Apple M1
+----------------------------------------------------------------------------- Combined, 63374 bytes
+👍 json-pack JsonEncoder x 4,604 ops/sec ±0.12% (100 runs sampled)
+👎 json-pack BsonEncoder x 3,962 ops/sec ±0.18% (100 runs sampled)
+👎 bson BSON.serialize() x 1,439 ops/sec ±0.19% (100 runs sampled)
+👍 bson Buffer.from(EJSON.stringify()) x 1,699 ops/sec ±0.11% (100 runs sampled)
+Fastest is 👍 json-pack JsonEncoder
+---------------------------------------------------------------------------- Small object, 53 bytes
+👍 json-pack JsonEncoder x 4,464,852 ops/sec ±0.47% (96 runs sampled)
+👎 json-pack BsonEncoder x 3,684,236 ops/sec ±0.18% (100 runs sampled)
+👎 bson BSON.serialize() x 884,917 ops/sec ±0.14% (99 runs sampled)
+👍 bson Buffer.from(EJSON.stringify()) x 1,153,616 ops/sec ±0.16% (98 runs sampled)
+Fastest is 👍 json-pack JsonEncoder
+------------------------------------------------------------------------ Typical object, 1002 bytes
+👍 json-pack JsonEncoder x 306,241 ops/sec ±0.22% (100 runs sampled)
+👎 json-pack BsonEncoder x 368,051 ops/sec ±0.17% (100 runs sampled)
+👎 bson BSON.serialize() x 106,583 ops/sec ±0.84% (99 runs sampled)
+👍 bson Buffer.from(EJSON.stringify()) x 126,497 ops/sec ±0.12% (99 runs sampled)
+Fastest is 👎 json-pack BsonEncoder
+-------------------------------------------------------------------------- Large object, 3750 bytes
+👍 json-pack JsonEncoder x 91,646 ops/sec ±0.76% (100 runs sampled)
+👎 json-pack BsonEncoder x 109,402 ops/sec ±0.17% (100 runs sampled)
+👎 bson BSON.serialize() x 35,037 ops/sec ±0.19% (98 runs sampled)
+👍 bson Buffer.from(EJSON.stringify()) x 39,504 ops/sec ±0.49% (101 runs sampled)
+Fastest is 👎 json-pack BsonEncoder
+-------------------------------------------------------------------- Very large object, 45759 bytes
+👍 json-pack JsonEncoder x 6,234 ops/sec ±0.47% (99 runs sampled)
+👎 json-pack BsonEncoder x 4,824 ops/sec ±0.20% (99 runs sampled)
+👎 bson BSON.serialize() x 1,645 ops/sec ±0.17% (101 runs sampled)
+👍 bson Buffer.from(EJSON.stringify()) x 2,696 ops/sec ±0.66% (98 runs sampled)
+Fastest is 👍 json-pack JsonEncoder
+------------------------------------------------------------------ Object with many keys, 978 bytes
+👍 json-pack JsonEncoder x 260,571 ops/sec ±0.68% (96 runs sampled)
+👎 json-pack BsonEncoder x 243,776 ops/sec ±0.42% (98 runs sampled)
+👎 bson BSON.serialize() x 86,641 ops/sec ±0.29% (100 runs sampled)
+👍 bson Buffer.from(EJSON.stringify()) x 81,730 ops/sec ±0.13% (99 runs sampled)
+Fastest is 👍 json-pack JsonEncoder
+------------------------------------------------------------------------- String ladder, 4046 bytes
+👍 json-pack JsonEncoder x 92,381 ops/sec ±0.13% (100 runs sampled)
+👎 json-pack BsonEncoder x 127,132 ops/sec ±1.03% (90 runs sampled)
+👎 bson BSON.serialize() x 75,356 ops/sec ±1.18% (94 runs sampled)
+👍 bson Buffer.from(EJSON.stringify()) x 47,308 ops/sec ±0.08% (101 runs sampled)
+Fastest is 👎 json-pack BsonEncoder
+```