@aedge-io/typed-clone

This skill addresses the common issues of type loss, poor performance, and inability to clone custom types when performing deep copies of complex objects in JavaScript/TypeScript development. In practice, developers often need to copy complex data structures containing Maps, Sets, Dates, TypedArrays, or even circular references. Built-in methods like JSON.parse(JSON.stringify()) or structuredClone either have type limitations or cannot handle functions or custom classes.

Usage is straightforward: simply install the @aedge-io/typed-clone package via npm or JSR, import the clone function, and then call clone(yourObject) to obtain a type-safe deep copy. For custom classes, you can implement a simple Symbol protocol (the [Clone] method) to let the library know how to clone them, enabling seamless integration.

It is particularly suitable for TypeScript/JavaScript developers who work with heterogeneous, complex data structures, especially those whose projects already use many custom classes, require referential transparency, or wish to avoid writing cumbersome cloning logic manually. For example, in scenarios like state management, data serialization/deserialization, or when creating data snapshots, this library provides a reliable foundational implementation.

We recommend introducing this library early in a project to standardize data cloning practices. Note that it primarily relies on the runtime's structuredClone as a fallback, so the environment must support it (Node.js ≥17, Deno ≥1.14, Bun ≥1.0.0, or browsers with structuredClone support). For types that cannot be cloned (e.g., functions), it explicitly returns a Ref<T> type, alerting the developer that this is a reference requiring special handling in the code.