cloner 1.1.0

Utilities for deep cloning collections and custom types with flexible extension points and optional circular reference detection.

1.1.0

Breaking Changes

• Extracted cloneMapTyped from ICloning into separate IMapTypedCloning
• Re-structurization of logging framework in cloner:base.dart
• Updated AdaptiveCloner construction/builder behavior

Added

• PureCloner: Added a new cloner implementation that performs deep cloning for common Dart collections and objects, without preserving type arguments or underlying collection implementations
• Builder extraction API for cloners: All core cloner implementations (BaseCloner, CountedCloner, HashedCloner, AdaptiveCloner, PureCloner) now expose a .builder() method, allowing constructorless builder access for configuration and instantiation (enables more flexible and idiomatic cloner construction and runtime configuration)
• Interfaces for logging and builder extraction: Added ILogging, IShowLogging, IPrintLogging, and IBuildable interfaces to support logging and builder extraction for cloners

Changed

• Cloner architecture: Refactored cloner interfaces in cloner:base.dart:
  • Base interface update: ICloning is now an agent interface focused on value cloning, and is split into smaller sub-interfaces for lists, sets, and maps (enables more modular cloner implementations and easier extension)
  • ICloning now only enforces dynamic map cloning (cloneMap<K, V>), with strict typed map cloning (cloneMapTyped<K, V>) moved to a separate IMapTypedCloning interface. This enables more flexible cloner implementations and extension support
  • All cloner base implementations now implement IBuildable, exposing a .builder() method for runtime builder extraction
• Revamp AdaptiveCloner
• Refresh benchmarks

Fixed

• Logging architecture: Logging for clone operations is now consistent and accessible via log history and mixins. Log history can be accessed and reset, and printing can be enabled or disabled
• Extension error handling: Collection extension methods now reliably throw UnsupportedTypedCloneException when a cloner does not support strict typed cloning, improving error reporting for unsupported scenarios
• Builder API consistency: All cloner builders now implement a consistent instance() method returning a fresh builder, improving builder usage patterns

---

1.0.4

Added

• SetClone wrapper for typed nested set cloning that enables safe deep cloning of nested sets while preserving both the element type and the runtime set implementation. Use SetClone for cases where you need to clone nested typed sets and retain their concrete collection type
• IRestorable interface: Added IRestorable, which provides a reset() method for cloners that maintain internal state. Both CountedCloner and HashedCloner now implement IRestorable, allowing their internal counters or hash tracking to be reset between clone operations

Fixed

• cloneValue for ICloneable now correctly passes the cloner instance
• Preservation of set and map concrete types: SetClone and MapClone now more reliably preserve the underlying collection implementation (e.g., LinkedHashSet, HashSet) during cloning and copying

1.0.3

Added

• Serialization support for cloner builders: Major cloner builders (BaseClonerBuilder, CountedClonerBuilder, HashedClonerBuilder) now implement ISerializable, allowing serialization and deserialization of builder configuration to/from strings. This enables saving and restoring cloner settings (can be handy for isolates)
• Builder serialization helpers serializeBaseFlag and deserializeBaseFlag for encoding/decoding cloner configuration flags
• Exception hierarchy: Introduced ACloneException and ASerializationException as base classes for cloning and serialization errors, respectively. Specific exceptions (e.g., UnsupportedTypedCloneException, LimitExceededException, CircularReferenceCloneException, DeserializationFormatException) now extend these bases

Changed

• ICloneable<T>.clone() method now accepts an optional ICloning parameter, allowing custom clone logic to receive the current cloner instance

Deprecations

• replicate() method has been removed. Use the builder pattern (*Builder().build()) for cloner instantiation and configuration
• Cloner.reference property is removed. Use Cloner.builder and Cloner.instance() for global cloner configuration and access.

1.0.2

Added

• Builder pattern for cloners: All cloner implementations (BaseCloner, CountedCloner, HashedCloner) now have corresponding *Builder classes (e.g., BaseClonerBuilder) for configuration and instantiation. This enables more flexible and idiomatic cloner construction
• AdaptiveCloner: New AdaptiveCloner and AdaptiveClonerBuilder for dispatching cloning operations to different delegate cloners based on configuration (e.g., AOT/JIT, collection type)
• MClonerLogging mixin: Add MClonerLogging for logging clone operations, with log history and optional printing.
• Extensions accept custom cloner: Collection extension methods (clone, cloneDynamic) now accept an optional cloner parameter for explicit cloner usage

Changed

• Global cloner API: Cloner.reference is deprecated in favor of Cloner.builder (to leverage aforementioned builder pattern for global cloner configuration)
• Cloner.instance now uses the builder
• DEPRECATED replicate(): The replicate() method on cloners is deprecated and will be removed in a future release
• Extensions: Collection extensions now use the builder-based cloner and allow passing a custom cloner

Fixed

• CountedCloner nesting depth limit now takes in account only collections (cloneValue() is excluded)

1.0.1

Added

• New CountedCloner and HashedCloner implementations:
  • CountedCloner enforces recursion depth and total clone count limits to prevent stack overflows and runaway cloning.
  • HashedCloner provides circular reference detection for collections, throwing CircularReferenceCloneException on cycles.
• LimitExceededException for reporting exceeded size/nesting limits during cloning.
• Benchmarks and performance recommendations for different cloner implementations (see doc/benchmarks)

Changed

• Cloner now uses CountedCloner as the default global cloner instead of BaseCloner
• ICloning.replicate signature simplified: removed doCircRefCheck parameter (circular reference detection is now handled by HashedCloner)
• Collection extension methods (clone, cloneDynamic) no longer accept doCircRefCheck parameter
• Improved documentation and README with new "Benchmarks" and "Worth Noting" sections

Fixed

• Improved test coverage for circular reference and limit enforcement scenarios

1.0.0

Initial version

• ICloneable and ICopyable contracts for custom deep/shallow copy support
• Cloner facade with pluggable backend
• BaseCloner default implementation and ICloning interface for custom cloners
  • Element/value-wise deep cloning for List, Set, and Map
  • Optional circular-reference detection
• Collection extensions: List.clone() / Set.clone() / Map.clone()
• MapClone typed map wrapper for safe nested typed map cloning and copy()/clone() helpers
• Typed-clone safety checks and UnsupportedTypedCloneException for unsupported typed scenarios
• Preserves common concrete collection implementations (LinkedHashMap, HashMap) where possible