docs: update README and examples

Author: t2y

README.md

@@ -1,18 +1,103 @@
 # orderedmap
 ![Coverage](https://img.shields.io/badge/Coverage-65.2%25-yellow)
 
-An alternative generic ordered map in Go with de/serializing from/to JSON.
+A generic ordered map implementation in Go that preserves insertion order and supports JSON serialization/deserialization.
 
-## How to use
+## Installation
 
-See the [example code](./example_test.go).
+```bash
+go get github.com/kazamori/orderedmap
+```
+
+## Features
+
+- Generic type support with `OrderedMap[K, V]`
+- Preserves insertion order of keys
+- JSON marshaling/unmarshaling with order preservation
+- O(1) key lookup
+
+## Quick Start
+
+```go
+package main
+
+import (
+    "encoding/json"
+    "fmt"
+
+    "github.com/kazamori/orderedmap"
+)
+
+func main() {
+    // Create a new ordered map
+    m := orderedmap.New[string, any]()
+    m.Set("name", "Alice")
+    m.Set("age", 30)
+    m.Set("active", true)
+
+    // Iterate in insertion order
+    for _, p := range m.Pairs() {
+        fmt.Printf("%s: %v\n", p.Key, p.Value)
+    }
+
+    // Get a value
+    if val, ok := m.Get("name"); ok {
+        fmt.Println("Name:", val)
+    }
+
+    // Serialize to JSON (preserves order)
+    data, _ := json.Marshal(m)
+    fmt.Println(string(data))
+    // Output: {"name":"Alice","age":30,"active":true}
+}
+```
 
-## test CLI
+## JSON Unmarshaling
 
-For testing, deserialize JSON and then serialize it while preserving the order.
+Parse JSON while preserving the original key order:
 
+```go
+jsonData := []byte(`{"z":"last","a":"first","m":"middle"}`)
+m := orderedmap.New[string, any]()
+json.Unmarshal(jsonData, m)
+
+for _, p := range m.Pairs() {
+    fmt.Printf("%s: %v\n", p.Key, p.Value)
+}
+// Output:
+// z: last
+// a: first
+// m: middle
 ```
-$ ./bin/cli -data '{"s":"test","i":3,"a":[{"f":3.14},{"b":true}]}'
+
+## API Reference
+
+| Function/Method | Description |
+|----------------|-------------|
+| `New[K, V]()` | Create a new empty ordered map |
+| `WithCapacity[K, V](size)` | Create with pre-allocated capacity |
+| `NewFromMap[M, K, V](m)` | Create from a standard Go map |
+| `Set(key, value)` | Add or update a key-value pair |
+| `Get(key)` | Retrieve a value by key |
+| `Pairs()` | Get all pairs in insertion order |
+| `String()` | JSON string representation |
+| `ToMap[M, K, V](om)` | Convert to standard Go map |
+
+## Examples
+
+See [example_test.go](./example_test.go) for more usage examples.
+
+## CLI Tool
+
+A CLI tool is included for testing JSON round-trip serialization:
+
+```bash
+make build
+./bin/cli -data '{"s":"test","i":3,"a":[{"f":3.14},{"b":true}]}'
+```
+
+Output:
+```json
 {
   "s": "test",
   "i": 3,

example_test.go

@@ -1,6 +1,7 @@
 package orderedmap_test
 
 import (
+	"encoding/json"
 	"fmt"
 
 	"github.com/kazamori/orderedmap"
@@ -23,3 +24,86 @@ func Example() {
 	// ================================
 	// {"key1":"value1","key2":3,"key3":[1.41421356,3.14]}
 }
+
+func Example_get() {
+	m := orderedmap.New[string, int]()
+	m.Set("one", 1)
+	m.Set("two", 2)
+	m.Set("three", 3)
+
+	if val, ok := m.Get("two"); ok {
+		fmt.Println("Found:", val)
+	}
+	if _, ok := m.Get("missing"); !ok {
+		fmt.Println("Key not found")
+	}
+	// Output:
+	// Found: 2
+	// Key not found
+}
+
+func Example_jsonUnmarshal() {
+	jsonData := []byte(`{"z":"last","a":"first","m":"middle"}`)
+	m := orderedmap.New[string, any]()
+	if err := json.Unmarshal(jsonData, m); err != nil {
+		panic(err)
+	}
+
+	// Keys are preserved in original JSON order
+	for _, p := range m.Pairs() {
+		fmt.Printf("%s: %v\n", p.Key, p.Value)
+	}
+	// Output:
+	// z: last
+	// a: first
+	// m: middle
+}
+
+func Example_jsonMarshal() {
+	m := orderedmap.New[string, any]()
+	m.Set("name", "Alice")
+	m.Set("age", 30)
+	m.Set("active", true)
+
+	data, err := json.Marshal(m)
+	if err != nil {
+		panic(err)
+	}
+	fmt.Println(string(data))
+	// Output:
+	// {"name":"Alice","age":30,"active":true}
+}
+
+func Example_nestedJSON() {
+	jsonData := []byte(`{"user":{"name":"Bob","score":100},"items":["a","b","c"]}`)
+	m := orderedmap.New[string, any]()
+	if err := json.Unmarshal(jsonData, m); err != nil {
+		panic(err)
+	}
+
+	fmt.Println(m.String())
+	// Output:
+	// {"user":{"name":"Bob","score":100},"items":["a","b","c"]}
+}
+
+func Example_withCapacity() {
+	// Pre-allocate capacity for better performance
+	m := orderedmap.WithCapacity[string, int](100)
+	m.Set("first", 1)
+	m.Set("second", 2)
+	fmt.Println(m.String())
+	// Output:
+	// {"first":1,"second":2}
+}
+
+func Example_toMap() {
+	om := orderedmap.New[string, int]()
+	om.Set("a", 1)
+	om.Set("b", 2)
+
+	// Convert to standard Go map
+	m := orderedmap.ToMap[map[string]int](om)
+	fmt.Println(m["a"], m["b"])
+	// Output:
+	// 1 2
+}