Merge pull request #14 from jsonjoy-com/copilot/fix-13

Improve documentation with centralized docs/ folder and enhanced README

Author: streamich

README.md

@@ -2,18 +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](./src/msgpack/README.md)** - Fast and lean implementation of MessagePack codec
+- **[CBOR](./src/cbor/README.md)** - Concise Binary Object Representation codec
+- **[UBJSON](./src/ubjson/README.md)** - Universal Binary JSON codec  
+- **[JSON](./src/json/README.md)** - Enhanced JSON encoder/decoder with additional features
+- **[JSON Binary](./src/json-binary/README.md)** - JSON with binary data support using Uint8Array
+- **[Amazon Ion](./src/ion/README.md)** - Amazon's Ion data serialization format
+- **[BSON](./src/bson/README.md)** - Binary JSON format used by MongoDB
+- **[RESP](./src/resp/README.md)** - Redis Serialization Protocol (v2 and v3)
+- **[Bencode](./src/bencode/README.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, refer to the individual README files in their respective folders:
+
+- Individual codec documentation is available in each `src/<codec>/README.md` file
+- Each codec includes comprehensive usage examples, API documentation, and performance benchmarks
 
 
 ## Benchmarks

src/bson/README.md

@@ -1,9 +1,43 @@
 # BSON
 
-Performant impelementation of [BSON][bson] (Binary JSON) for JavaScript.
+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
 

src/cbor/README.md

@@ -1,5 +1,84 @@
 # `json-pack` CBOR Codec
 
+`json-pack` implements fast [CBOR][cbor] encoder and decoder. It is written in TypeScript
+and has no external dependencies.
+
+[cbor]: https://cbor.io/
+
+## Getting started
+
+To get started you need to import `CborEncoder` and `CborDecoder` classes like
+this:
+
+```ts
+import {CborEncoder} from 'json-joy/es2020/json-pack/cbor/CborEncoder';
+import {CborDecoder} from 'json-joy/es2020/json-pack/cbor/CborDecoder';
+```
+
+The `CborDecoder` implements full decoding feature set including advanced
+features like value skipping and decoding one level at-a-time. Those features
+are not necessary for most use cases, to save on bundle size you can import
+the "base" decoder instead:
+
+```ts
+import {CborDecoderBase} from 'json-joy/es2020/json-pack/cbor/CborDecoderBase';
+```
+
+The base decoder implements all CBOR decoding features except for the advanced
+shallow decoding features, like skipping, one level at-a-time decoding.
+
+## Usage
+
+Encode a JavaScript POJO to CBOR:
+
+```ts
+const encoder = new CborEncoder();
+
+const pojo = {
+  id: 123,
+  foo: 'bar',
+  tags: ['a', 'b', 'c'],
+  nested: {
+    a: 1,
+    b: 2,
+    level2: {
+      c: 3,
+    }
+  },
+};
+
+const encoded = encoder.encode(pojo);
+console.log(encoded);
+// Uint8Array(53) [
+//   164,  98, 105, 100,  24, 123,  99, 102, 111, 111,
+//    99,  98,  97, 114, 100, 116,  97, 103, 115, 131,
+//    97,  97,  97,  98,  97,  99, 120,   6, 110, 101,
+//   115, 116, 101, 100, 163,  97,  97,   1,  97,  98,
+//     2, 120,   6, 108, 101, 118, 101, 108,  50, 161,
+//    97,  99,   3
+// ]
+```
+
+Decode CBOR back to JavaScript POJO:
+
+```ts
+const decoderBase = new CborDecoderBase();
+const decoded = decoderBase.read(encoded);
+
+console.log(decoded);
+// {
+//   id: 123,
+//   foo: 'bar',
+//   tags: ['a', 'b', 'c'],
+//   nested: {
+//     a: 1,
+//     b: 2,
+//     level2: {
+//       c: 3,
+//     }
+//   },
+// }
+```
 
 ## Implementation details
 

src/ion/README.md

@@ -38,7 +38,6 @@ for (const item of items) {
 ```
 
 This limitation primarily affects complex nested objects with many string keys. Simple data structures may work with reused instances, but fresh instances are recommended for guaranteed correctness.
-
 ## Benchmarks
 
 Encoding:

src/json/README.md

@@ -1,3 +1,32 @@
+# JSON Encoder/Decoder
+
+Enhanced JSON implementation with high-performance encoding and decoding capabilities.
+
+## Features
+
+- **JsonEncoder** - High-performance JSON encoder with better performance than native `JSON.stringify`
+- **JsonDecoder** - Fast JSON decoder optimized for specific use cases
+- Support for streaming operations
+- Binary-safe encoding/decoding
+- Optimized for repeated encoding operations
+
+## Usage
+
+```ts
+import {JsonEncoder, JsonDecoder} from 'json-pack/lib/json';
+
+const encoder = new JsonEncoder();
+const decoder = new JsonDecoder();
+
+const data = {hello: 'world', numbers: [1, 2, 3]};
+const encoded = encoder.encode(data);
+const decoded = decoder.decode(encoded);
+```
+
+## Performance
+
+This JSON implementation is optimized for performance and in many cases outperforms the native `JSON.stringify()` and `JSON.parse()` methods, especially for repeated operations.
+
 ## Benchmarks
 
 Encoding:

src/resp/README.md

@@ -1 +1,61 @@
 # RESP v2 and RESP3 codecs
+
+Redis Serialization Protocol (RESP) implementation supporting both RESP2 and RESP3 formats.
+
+## Overview
+
+RESP is the protocol used by Redis to communicate between clients and servers. This implementation provides:
+
+- **RESP3** encoder (`RespEncoder`) - Full support for all RESP3 data types
+- **RESP2** encoder (`RespEncoderLegacy`) - Legacy RESP2 support  
+- **RESP decoder** (`RespDecoder`) - Decodes both RESP2 and RESP3 formats
+- **Streaming decoder** (`RespStreamingDecoder`) - For parsing streaming RESP data
+
+## Supported Data Types
+
+### RESP3 Types
+- Simple strings
+- Simple errors  
+- Integers
+- Bulk strings
+- Arrays
+- Nulls
+- Booleans
+- Doubles
+- Maps
+- Sets
+- Attributes
+- Push messages
+- Verbatim strings
+
+### RESP2 Types  
+- Simple strings
+- Errors
+- Integers
+- Bulk strings  
+- Arrays
+
+## Usage
+
+```ts
+import {RespEncoder, RespDecoder} from 'json-pack/lib/resp';
+
+const encoder = new RespEncoder();
+const decoder = new RespDecoder();
+
+// Encode data
+const data = {hello: 'world', count: 42};
+const encoded = encoder.encode(data);
+
+// Decode data
+const decoded = decoder.decode(encoded);
+console.log(decoded); // {hello: 'world', count: 42}
+```
+
+## Extensions
+
+The RESP implementation supports Redis-specific extensions:
+
+- **RespAttributes** - For attribute metadata
+- **RespPush** - For push messages  
+- **RespVerbatimString** - For verbatim strings with format info