deepclone

DeepClone

A high-performance deep cloning library for Go that provides safe, efficient copying of any Go value.

✨ Features

• 🚀 High Performance: Zero-allocation fast paths for primitive types
• 🛡️ Circular Reference Safe: Automatic detection and handling of circular references
• 🔒 Thread Safe: Concurrent operations with safe caching mechanisms
• 📦 Universal Support: Works with all Go types including channels, functions, and interfaces
• 🎯 Extensible: Custom cloning behavior via Cloneable interface
• ⚡ Zero Dependencies: Uses only Go standard library

📦 Installation

go get github.com/kaptinlin/deepclone

🚀 Quick Start

package main

import (
    "fmt"
    "github.com/kaptinlin/deepclone"
)

func main() {
    // Deep clone any value
    original := map[string][]int{
        "numbers": {1, 2, 3},
        "scores":  {85, 90, 95},
    }
    
    cloned := deepclone.Clone(original)
    
    // Modify original - cloned remains independent
    original["numbers"][0] = 999
    
    fmt.Println("Original:", original["numbers"]) // [999, 2, 3]
    fmt.Println("Cloned:", cloned["numbers"])     // [1, 2, 3]
}

💡 Core Concept

All operations perform deep copies by default:

• Primitives: int, string, bool → Copied by value (zero allocations)
• Collections: slice, map, array → New containers with cloned elements
• Structs: New instances with all fields deeply cloned
• Pointers: New pointers pointing to cloned values
• Custom Types: Support via Cloneable interface

📚 Examples

Basic Usage

// Primitives (zero allocation)
number := deepclone.Clone(42)
text := deepclone.Clone("hello")

// Collections (deep cloned)
slice := deepclone.Clone([]string{"a", "b", "c"})
data := deepclone.Clone(map[string]int{"key": 42})

// Complex structures
type User struct {
    Name    string
    Friends []string
    Config  map[string]interface{}
}

user := User{
    Name:    "Alice",
    Friends: []string{"Bob", "Charlie"},
    Config:  map[string]interface{}{"theme": "dark"},
}

cloned := deepclone.Clone(user) // Complete deep copy

Custom Cloning Behavior

type Document struct {
    Title   string
    Content []byte
    Version int
}

// Implement custom cloning logic
func (d Document) Clone() any {
    return Document{
        Title:   d.Title,
        Content: deepclone.Clone(d.Content).([]byte),
        Version: d.Version + 1, // Increment version on clone
    }
}

doc := Document{Title: "My Doc", Version: 1}
cloned := deepclone.Clone(doc) // Version becomes 2

For more examples, see examples/ directory.

⚡ Performance

DeepClone is optimized for performance with:

• Zero allocations for primitive types
• Fast paths for common slice/map types
• Reflection caching for struct types
• Minimal overhead for complex operations

Benchmark Results

Tested on Apple M3, macOS (darwin/arm64):

For detailed benchmarks and comparisons with other libraries, see benchmarks/.

# Run benchmarks
cd benchmarks && go test -bench=. -benchmem

📖 API Reference

Core Function

func Clone[T any](src T) T

Creates a deep copy of any value. The returned value is completely independent of the original.

Custom Cloning Interface

type Cloneable interface {
    Clone() any
}

Implement this interface to provide custom cloning behavior for your types.

🛠️ Advanced Features

• Circular Reference Detection: Prevents infinite loops in self-referencing structures
• Interface Preservation: Maintains original interface types while cloning concrete values
• Thread Safety: All operations are safe for concurrent use
• Type Caching: Struct metadata is cached for improved performance on repeated operations

🤝 Contributing

We welcome contributions! Please feel free to:

• Report bugs
• Suggest new features
• Submit pull requests
• Improve documentation

📋 Requirements

• Go 1.25 or later
• No external dependencies

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.