docs: update READMEs

Update all README.md files with consistent import paths and working usage examples

Author: streamich

src/bencode/README.md

@@ -1,18 +1,63 @@
-# Bencode codecs
+# Bencode Codec
 
 Implements [Bencode][bencode] encoder and decoder.
 
 [bencode]: https://en.wikipedia.org/wiki/Bencode
 
-Type coercion:
+## Features
+
+- High-performance Bencode encoding and decoding
+- Support for all standard Bencode types
+- Extensions for additional JavaScript types
+- BitTorrent-compatible implementation
+
+## Usage
+
+Note: BencodeEncoder requires a Writer instance from the `@jsonjoy.com/util` package. Make sure to install it as a peer dependency:
+
+```bash
+npm install @jsonjoy.com/util
+```
+
+### Basic Usage
+
+```ts
+import {BencodeEncoder, BencodeDecoder} from '@jsonjoy.com/json-pack/lib/bencode';
+import {Writer} from '@jsonjoy.com/util/lib/buffers/Writer';
+
+const writer = new Writer();
+const encoder = new BencodeEncoder(writer);
+const decoder = new BencodeDecoder();
+
+const data = {
+  name: 'example.torrent',
+  length: 1024,
+  files: ['file1.txt', 'file2.txt']
+};
+
+const encoded = encoder.encode(data);
+const decoded = decoder.decode(encoded);
+
+console.log(decoded); // Original data structure
+```
+
+### Alternative: Use simpler codecs
+
+For easier usage without external dependencies, consider using MessagePack or CBOR codecs instead:
+
+```ts
+import {MessagePackEncoder, MessagePackDecoder} from '@jsonjoy.com/json-pack/lib/msgpack';
+// ... simpler usage
+```
+
+## 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:

src/bson/README.md

@@ -22,10 +22,20 @@ BSON (Binary JSON) is a binary representation of JSON-like documents. It extends
 
 ## Usage
 
+Note: BsonEncoder requires a Writer instance from the `@jsonjoy.com/util` package. Make sure to install it as a peer dependency:
+
+```bash
+npm install @jsonjoy.com/util
+```
+
+### Basic Usage
+
 ```ts
-import {BsonEncoder, BsonDecoder} from 'json-pack/lib/bson';
+import {BsonEncoder, BsonDecoder} from '@jsonjoy.com/json-pack/lib/bson';
+import {Writer} from '@jsonjoy.com/util/lib/buffers/Writer';
 
-const encoder = new BsonEncoder();
+const writer = new Writer();
+const encoder = new BsonEncoder(writer);
 const decoder = new BsonDecoder();
 
 const data = {
@@ -36,6 +46,17 @@ const data = {
 
 const encoded = encoder.encode(data);
 const decoded = decoder.decode(encoded);
+
+console.log(decoded); // Original data with BSON types preserved
+```
+
+### Alternative: Use simpler codecs
+
+For easier usage without external dependencies, consider using MessagePack or CBOR codecs instead:
+
+```ts
+import {MessagePackEncoder, MessagePackDecoder} from '@jsonjoy.com/json-pack/lib/msgpack';
+// ... simpler usage
 ```
 
 

src/cbor/README.md

@@ -5,36 +5,15 @@ 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:
+## Basic Usage
 
 ```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
+import {CborEncoder, CborDecoder} from '@jsonjoy.com/json-pack/lib/cbor';
 
-Encode a JavaScript POJO to CBOR:
-
-```ts
 const encoder = new CborEncoder();
+const decoder = new CborDecoder();
 
-const pojo = {
+const data = {
   id: 123,
   foo: 'bar',
   tags: ['a', 'b', 'c'],
@@ -47,39 +26,34 @@ const pojo = {
   },
 };
 
-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
-// ]
+const encoded = encoder.encode(data);
+const decoded = decoder.decode(encoded);
+
+console.log(decoded); // Original data structure
 ```
 
-Decode CBOR back to JavaScript POJO:
+## Advanced Usage
+
+To get started you need to import `CborEncoder` and `CborDecoder` classes like
+this:
 
 ```ts
-const decoderBase = new CborDecoderBase();
-const decoded = decoderBase.read(encoded);
+import {CborEncoder} from '@jsonjoy.com/json-pack/lib/cbor/CborEncoder';
+import {CborDecoder} from '@jsonjoy.com/json-pack/lib/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:
 
-console.log(decoded);
-// {
-//   id: 123,
-//   foo: 'bar',
-//   tags: ['a', 'b', 'c'],
-//   nested: {
-//     a: 1,
-//     b: 2,
-//     level2: {
-//       c: 3,
-//     }
-//   },
-// }
+```ts
+import {CborDecoderBase} from '@jsonjoy.com/json-pack/lib/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.
+
 ## Implementation details
 
 - Map keys are treated as strings.

src/ejson/README.md

@@ -17,11 +17,32 @@ This directory contains the implementation of MongoDB Extended JSON v2 codec, pr
 - Throws descriptive errors for malformed input
 - Supports both canonical and relaxed format parsing
 
-## API
+## Basic Usage
+
+```ts
+import {EjsonEncoder, EjsonDecoder} from '@jsonjoy.com/json-pack/lib/ejson';
+
+const encoder = new EjsonEncoder();
+const decoder = new EjsonDecoder();
+
+const data = {
+  _id: new BsonObjectId(0x507f1f77, 0xbcf86cd799, 0x439011),
+  count: new BsonInt64(9223372036854775807),
+  created: new Date('2023-01-15T10:30:00.000Z')
+};
+
+const encoded = encoder.encode(data);
+const decoded = decoder.decode(encoded);
+
+console.log(decoded); // Original data with BSON types preserved
+```
+
+## Advanced Usage
 
 ### Binary-First API (Recommended for Performance)
+
 ```typescript
-import {EjsonEncoder, EjsonDecoder} from '@jsonjoy.com/json-pack/ejson2';
+import {EjsonEncoder, EjsonDecoder} from '@jsonjoy.com/json-pack/lib/ejson';
 import {Writer} from '@jsonjoy.com/util/lib/buffers/Writer';
 
 const writer = new Writer();
@@ -36,8 +57,9 @@ const result = decoder.decode(bytes);
 ```
 
 ### String API (For Compatibility)
+
 ```typescript
-import {createEjsonEncoder, createEjsonDecoder} from '@jsonjoy.com/json-pack/ejson2';
+import {createEjsonEncoder, createEjsonDecoder} from '@jsonjoy.com/json-pack/lib/ejson';
 
 const encoder = createEjsonEncoder({ canonical: true });
 const decoder = createEjsonDecoder();

src/ion/README.md

@@ -2,7 +2,7 @@
 
 This library provides high-performance Amazon Ion binary format encoding and decoding capabilities.
 
-## Usage
+## Basic Usage
 
 ```typescript
 import {IonEncoderFast, IonDecoder} from '@jsonjoy.com/json-pack/lib/ion';
@@ -13,6 +13,8 @@ const decoder = new IonDecoder();
 const data = {users: [{name: 'Alice', age: 30}], count: 1};
 const encoded = encoder.encode(data);
 const decoded = decoder.decode(encoded);
+
+console.log(decoded); // Original data structure
 ```
 
 ## Important Usage Notes

src/json-binary/README.md

@@ -3,8 +3,10 @@
 A JSON serializer and parser which supports `Uint8Array` binary data.
 Encodes binary data as Base64 encoded data URI strings.
 
+## Basic Usage
+
 ```ts
-import * as JSONB from 'json-pack/lib/json-binary';
+import * as JSONB from '@jsonjoy.com/json-pack/lib/json-binary';
 
 const data = {
   foo: new Uint8Array([1, 2, 3]),
@@ -15,4 +17,6 @@ const json = JSONB.stringify(data);
 
 const data2 = JSONB.parse(json);
 // { foo: Uint8Array { 1, 2, 3 } }
+
+console.log(data2.foo instanceof Uint8Array); // true
 ```

src/json/README.md

@@ -12,15 +12,39 @@ Enhanced JSON implementation with high-performance encoding and decoding capabil
 
 ## Usage
 
+Note: JsonEncoder requires a Writer instance from the `@jsonjoy.com/util` package. Make sure to install it as a peer dependency:
+
+```bash
+npm install @jsonjoy.com/util
+```
+
+### Basic Usage
+
 ```ts
-import {JsonEncoder, JsonDecoder} from 'json-pack/lib/json';
+import {JsonEncoder, JsonDecoder} from '@jsonjoy.com/json-pack/lib/json';
+import {Writer} from '@jsonjoy.com/util/lib/buffers/Writer';
 
-const encoder = new JsonEncoder();
+const writer = new Writer();
+const encoder = new JsonEncoder(writer);
 const decoder = new JsonDecoder();
 
 const data = {hello: 'world', numbers: [1, 2, 3]};
 const encoded = encoder.encode(data);
 const decoded = decoder.decode(encoded);
+
+console.log(decoded); // {hello: 'world', numbers: [1, 2, 3]}
+```
+
+### Alternative: Use simpler codecs
+
+For easier usage without external dependencies, consider using MessagePack or CBOR codecs instead:
+
+```ts
+import {MessagePackEncoder, MessagePackDecoder} from '@jsonjoy.com/json-pack/lib/msgpack';
+
+const encoder = new MessagePackEncoder();
+const decoder = new MessagePackDecoder(); 
+// ... simpler usage
 ```
 
 ## Performance