bunshin-clone 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yusuke Kamiyamane
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,198 @@
+# bunshin-clone
+
+High-performance deep clone utility with descriptor support. Supports circular references and complex built-in types.
+
+* ⚡ Fast (no unnecessary overhead)
+* ♻️ Deep clone (no structural sharing)
+* 🔁 Supports circular references
+* 🧠 Handles Map, Set, Array, TypedArray, Date, RegExp, etc.
+* 🧩 Optional descriptor preservation
+
+## Usage
+
+```ts
+import bunshinClone from 'bunshin-clone';
+
+const source = { foo: 1, nested: { x: 1 } };
+
+const result = bunshinClone(source);
+
+console.log(result);
+// { foo: 1, nested: { x: 1 } }
+
+console.log(result === source); // false
+console.log(result.nested === source.nested); // false
+```
+
+## API
+
+```ts
+bunshinClone(target)
+bunshinClone(target, options)
+```
+
+## Options
+
+```ts
+interface BunshinCloneOptions {
+  preserveDescriptors?: boolean;
+  strictDescriptors?: boolean;
+}
+```
+
+### preserveDescriptors
+
+* `false` (default): use standard merge (faster, ignores property descriptors)
+* `true`: preserve property descriptors (getters/setters, etc.)
+
+```ts
+const source = {};
+Object.defineProperty(source, 'x', {
+  get: () => 42,
+  enumerable: true,
+});
+
+const result = bunshinClone(source, { preserveDescriptors: true });
+
+Object.getOwnPropertyDescriptor(result, 'x')?.get;
+// => function
+```
+
+### strictDescriptors
+
+* `false` (default): skip incompatible descriptors
+* `true`: throw if descriptor cannot be merged (e.g. non-configurable or non-writable)
+
+```ts
+Object.freeze(obj);
+
+bunshinClone(obj, { strictDescriptors: true });
+// => may throw TypeError
+```
+
+## Supported Types
+
+bunshin-clone correctly handles:
+
+* Object (plain + prototype preserved)
+* Array
+* Map
+* Set
+* Date
+* RegExp
+* ArrayBuffer
+* DataView
+* TypedArray (Uint8Array, etc.)
+* Error / DOMException
+* Blob
+* ImageData
+* URL
+* URLSearchParams
+
+## Circular ref
+
+```ts
+const a: any = { x: 1 };
+a.self = a;
+
+const result = bunshinClone(a);
+
+result.self === result; // true
+```
+
+## Descriptor Behavior
+
+### Default (fast path)
+
+```ts
+const source = {
+  get x() {
+    return 42;
+  }
+};
+
+const result = bunshinClone(source);
+
+result.x; // 42
+// getter is NOT preserved
+```
+
+### preserveDescriptors: true
+
+```ts
+const source = {};
+Object.defineProperty(source, 'x', {
+  get: () => 42,
+  enumerable: true,
+});
+
+const result = bunshinClone(source, {
+  preserveDescriptors: true,
+});
+
+Object.getOwnPropertyDescriptor(result, 'x')?.get;
+// => preserved
+```
+
+### Unsupported / Pass-through Types
+
+Some values are returned as-is:
+
+* Function
+* WeakMap / WeakSet
+* Proxy (not cloned)
+* Other non-cloneable host objects
+
+```ts
+const fn = () => {};
+
+bunshinClone(fn) === fn; // true
+```
+
+## Design Notes
+
+### Deep clone (no structural sharing)
+
+Unlike merge utilities, bunshin-clone always produces a new structure:
+
+```ts
+const source = { a: { b: 1 } };
+
+const result = bunshinClone(source);
+
+result !== source; // true
+result.a !== source.a; // true
+```
+
+### Getter / Setter behavior
+
+* Default: evaluated and converted to value
+* preserveDescriptors: preserved as-is
+
+### Descriptor safety
+
+When `preserveDescriptors` is enabled:
+
+* descriptors are cloned safely
+* original object is never mutated
+* errors are controlled via `strictDescriptors`
+
+## Performance
+
+* No proxy / no diffing
+* Minimal branching
+* Fast path for plain objects and arrays
+* Competitive with structuredClone in many cases
+
+## Comparison
+
+| Feature              | bunshin-clone | structuredClone | lodash.clonedeep |
+|---------------------|--------------|----------------|------------------|
+| Circular refs       | ✅           | ✅             | ✅               |
+| Map / Set           | ✅           | ✅             | ⚠️ (partial)     |
+| TypedArray          | ✅           | ✅             | ⚠️ (shallow)     |
+| Descriptor support  | ✅           | ❌             | ❌               |
+| Functions           | pass-through | ❌ (throws)    | pass-through     |
+| Prototype preserved | ✅           | ❌             | ⚠️               |
+| Custom control      | ✅           | ❌             | ❌               |
+| Performance         | ⚡ fast       | ⚡ fast         | 🐢 slower        |

package/dist/index.cjs

@@ -0,0 +1,203 @@
+'use strict';
+
+// src/index.ts
+var EMPTY_OPTIONS = {};
+var { hasOwnProperty: HAS_OWN } = Object.prototype;
+var { toString: OBJECT_TO_STRING } = Object.prototype;
+function bunshinClone(target, options) {
+  return clone(target, options ?? EMPTY_OPTIONS, /* @__PURE__ */ new WeakMap());
+}
+function clone(node, options, ref) {
+  if (!isObject(node)) {
+    return node;
+  }
+  const cached = ref.get(node);
+  if (cached !== void 0) {
+    return cached;
+  }
+  if (options.preserveDescriptors && isPlainObject(node)) {
+    return cloneWithDescriptors(node, options, ref);
+  }
+  if (Array.isArray(node)) {
+    const result = [];
+    ref.set(node, result);
+    for (let i = 0, l = node.length; i < l; i++) {
+      result[i] = clone(node[i], options, ref);
+    }
+    return result;
+  }
+  if (isPlainObject(node)) {
+    const result = Object.create(Object.getPrototypeOf(node));
+    ref.set(node, result);
+    for (const key in node) {
+      if (!HAS_OWN.call(node, key) || isUnsafeKey(key)) {
+        continue;
+      }
+      result[key] = clone(node[key], options, ref);
+    }
+    return result;
+  }
+  if (node instanceof Map) {
+    const result = /* @__PURE__ */ new Map();
+    ref.set(node, result);
+    for (const [key, value] of node) {
+      result.set(clone(key, options, ref), clone(value, options, ref));
+    }
+    return result;
+  }
+  if (node instanceof Set) {
+    const result = /* @__PURE__ */ new Set();
+    ref.set(node, result);
+    for (const item of node) {
+      result.add(clone(item, options, ref));
+    }
+    return result;
+  }
+  if (node instanceof Date) {
+    const result = new Date(node.getTime());
+    ref.set(node, result);
+    return result;
+  }
+  if (node instanceof RegExp) {
+    const result = new RegExp(node.source, node.flags);
+    ref.set(node, result);
+    result.lastIndex = node.lastIndex;
+    return result;
+  }
+  if (node instanceof ArrayBuffer) {
+    const result = node.slice(0);
+    ref.set(node, result);
+    return result;
+  }
+  if (ArrayBuffer.isView(node)) {
+    if (node instanceof DataView) {
+      const result = new DataView(
+        node.buffer.slice(0),
+        node.byteOffset,
+        node.byteLength
+      );
+      ref.set(node, result);
+      return result;
+    } else {
+      const Ctor = node.constructor;
+      const result = new Ctor(node);
+      ref.set(node, result);
+      return result;
+    }
+  }
+  if (node instanceof Error || typeof DOMException !== "undefined" && node instanceof DOMException) {
+    const result = cloneError(node, options, ref);
+    ref.set(node, result);
+    return result;
+  }
+  if (typeof Blob !== "undefined" && node instanceof Blob) {
+    const result = node.slice(0, node.size, node.type);
+    ref.set(node, result);
+    return result;
+  }
+  if (typeof ImageData !== "undefined" && node instanceof ImageData) {
+    const result = new ImageData(
+      new Uint8ClampedArray(node.data),
+      node.width,
+      node.height
+    );
+    ref.set(node, result);
+    return result;
+  }
+  if (typeof URL !== "undefined" && node instanceof URL) {
+    const result = new URL(node.href);
+    ref.set(node, result);
+    return result;
+  }
+  if (typeof URLSearchParams !== "undefined" && node instanceof URLSearchParams) {
+    const result = new URLSearchParams();
+    ref.set(node, result);
+    for (const [key, value] of node) {
+      result.append(key, value);
+    }
+    return result;
+  }
+  ref.set(node, node);
+  return node;
+}
+function cloneError(value, options, ref) {
+  const name = value.name || "Error";
+  const message = value.message || "";
+  let result;
+  switch (name) {
+    case "RangeError":
+      result = new RangeError(message);
+      break;
+    case "ReferenceError":
+      result = new ReferenceError(message);
+      break;
+    case "SyntaxError":
+      result = new SyntaxError(message);
+      break;
+    case "TypeError":
+      result = new TypeError(message);
+      break;
+    default:
+      result = new Error(message);
+      result.name = name;
+  }
+  if (!options.preserveDescriptors && "cause" in value) {
+    result.cause = clone(result.cause, options, ref);
+  }
+  if (value.stack) {
+    result.stack = value.stack;
+  }
+  for (const key of Object.keys(value)) {
+    if (key === "name" || key === "message" || key === "stack") {
+      continue;
+    }
+    result[key] = value[key];
+  }
+  return result;
+}
+function cloneWithDescriptors(node, options, ref) {
+  const result = Object.create(Object.getPrototypeOf(node));
+  ref.set(node, result);
+  const descriptors = Object.getOwnPropertyDescriptors(node);
+  const keys = Reflect.ownKeys(descriptors);
+  for (let i = 0, l = keys.length; i < l; i++) {
+    const key = keys[i];
+    if (isUnsafeKey(key)) {
+      continue;
+    }
+    const descriptor = { ...descriptors[key] };
+    if ("value" in descriptor) {
+      descriptor.value = clone(descriptor.value, options, ref);
+    }
+    try {
+      Object.defineProperty(result, key, descriptor);
+    } catch (error) {
+      if (options.strictDescriptors) {
+        throw error;
+      }
+    }
+  }
+  return result;
+}
+function isObject(value) {
+  return typeof value === "object" && value !== null;
+}
+function isPlainObject(value) {
+  return OBJECT_TO_STRING.call(value) === "[object Object]";
+}
+function isUnsafeKey(key) {
+  return typeof key === "string" && (key === "__proto__" || key === "prototype" || key === "constructor");
+}
+/**
+ * bunshin-clone
+ * High-performance deep clone utility with descriptor support.
+ * Supports circular ref and complex built-in types.
+ *
+ * @version 1.0.0
+ * @author Yusuke Kamiyamane
+ * @license MIT
+ * @copyright Copyright (c) 2026 Yusuke Kamiyamane
+ * @see {@link https://github.com/y14e/bunshin-clone}
+ */
+
+module.exports = bunshinClone;

package/dist/index.d.cts

@@ -0,0 +1,18 @@
+/**
+ * bunshin-clone
+ * High-performance deep clone utility with descriptor support.
+ * Supports circular ref and complex built-in types.
+ *
+ * @version 1.0.0
+ * @author Yusuke Kamiyamane
+ * @license MIT
+ * @copyright Copyright (c) 2026 Yusuke Kamiyamane
+ * @see {@link https://github.com/y14e/bunshin-clone}
+ */
+interface BunshinCloneOptions {
+    readonly preserveDescriptors?: boolean;
+    readonly strictDescriptors?: boolean;
+}
+declare function bunshinClone(target: unknown, options?: BunshinCloneOptions): unknown;
+
+export { type BunshinCloneOptions, bunshinClone as default };

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * bunshin-clone
+ * High-performance deep clone utility with descriptor support.
+ * Supports circular ref and complex built-in types.
+ *
+ * @version 1.0.0
+ * @author Yusuke Kamiyamane
+ * @license MIT
+ * @copyright Copyright (c) 2026 Yusuke Kamiyamane
+ * @see {@link https://github.com/y14e/bunshin-clone}
+ */
+interface BunshinCloneOptions {
+    readonly preserveDescriptors?: boolean;
+    readonly strictDescriptors?: boolean;
+}
+declare function bunshinClone(target: unknown, options?: BunshinCloneOptions): unknown;
+
+export { type BunshinCloneOptions, bunshinClone as default };

package/dist/index.js

@@ -0,0 +1,201 @@
+// src/index.ts
+var EMPTY_OPTIONS = {};
+var { hasOwnProperty: HAS_OWN } = Object.prototype;
+var { toString: OBJECT_TO_STRING } = Object.prototype;
+function bunshinClone(target, options) {
+  return clone(target, options ?? EMPTY_OPTIONS, /* @__PURE__ */ new WeakMap());
+}
+function clone(node, options, ref) {
+  if (!isObject(node)) {
+    return node;
+  }
+  const cached = ref.get(node);
+  if (cached !== void 0) {
+    return cached;
+  }
+  if (options.preserveDescriptors && isPlainObject(node)) {
+    return cloneWithDescriptors(node, options, ref);
+  }
+  if (Array.isArray(node)) {
+    const result = [];
+    ref.set(node, result);
+    for (let i = 0, l = node.length; i < l; i++) {
+      result[i] = clone(node[i], options, ref);
+    }
+    return result;
+  }
+  if (isPlainObject(node)) {
+    const result = Object.create(Object.getPrototypeOf(node));
+    ref.set(node, result);
+    for (const key in node) {
+      if (!HAS_OWN.call(node, key) || isUnsafeKey(key)) {
+        continue;
+      }
+      result[key] = clone(node[key], options, ref);
+    }
+    return result;
+  }
+  if (node instanceof Map) {
+    const result = /* @__PURE__ */ new Map();
+    ref.set(node, result);
+    for (const [key, value] of node) {
+      result.set(clone(key, options, ref), clone(value, options, ref));
+    }
+    return result;
+  }
+  if (node instanceof Set) {
+    const result = /* @__PURE__ */ new Set();
+    ref.set(node, result);
+    for (const item of node) {
+      result.add(clone(item, options, ref));
+    }
+    return result;
+  }
+  if (node instanceof Date) {
+    const result = new Date(node.getTime());
+    ref.set(node, result);
+    return result;
+  }
+  if (node instanceof RegExp) {
+    const result = new RegExp(node.source, node.flags);
+    ref.set(node, result);
+    result.lastIndex = node.lastIndex;
+    return result;
+  }
+  if (node instanceof ArrayBuffer) {
+    const result = node.slice(0);
+    ref.set(node, result);
+    return result;
+  }
+  if (ArrayBuffer.isView(node)) {
+    if (node instanceof DataView) {
+      const result = new DataView(
+        node.buffer.slice(0),
+        node.byteOffset,
+        node.byteLength
+      );
+      ref.set(node, result);
+      return result;
+    } else {
+      const Ctor = node.constructor;
+      const result = new Ctor(node);
+      ref.set(node, result);
+      return result;
+    }
+  }
+  if (node instanceof Error || typeof DOMException !== "undefined" && node instanceof DOMException) {
+    const result = cloneError(node, options, ref);
+    ref.set(node, result);
+    return result;
+  }
+  if (typeof Blob !== "undefined" && node instanceof Blob) {
+    const result = node.slice(0, node.size, node.type);
+    ref.set(node, result);
+    return result;
+  }
+  if (typeof ImageData !== "undefined" && node instanceof ImageData) {
+    const result = new ImageData(
+      new Uint8ClampedArray(node.data),
+      node.width,
+      node.height
+    );
+    ref.set(node, result);
+    return result;
+  }
+  if (typeof URL !== "undefined" && node instanceof URL) {
+    const result = new URL(node.href);
+    ref.set(node, result);
+    return result;
+  }
+  if (typeof URLSearchParams !== "undefined" && node instanceof URLSearchParams) {
+    const result = new URLSearchParams();
+    ref.set(node, result);
+    for (const [key, value] of node) {
+      result.append(key, value);
+    }
+    return result;
+  }
+  ref.set(node, node);
+  return node;
+}
+function cloneError(value, options, ref) {
+  const name = value.name || "Error";
+  const message = value.message || "";
+  let result;
+  switch (name) {
+    case "RangeError":
+      result = new RangeError(message);
+      break;
+    case "ReferenceError":
+      result = new ReferenceError(message);
+      break;
+    case "SyntaxError":
+      result = new SyntaxError(message);
+      break;
+    case "TypeError":
+      result = new TypeError(message);
+      break;
+    default:
+      result = new Error(message);
+      result.name = name;
+  }
+  if (!options.preserveDescriptors && "cause" in value) {
+    result.cause = clone(result.cause, options, ref);
+  }
+  if (value.stack) {
+    result.stack = value.stack;
+  }
+  for (const key of Object.keys(value)) {
+    if (key === "name" || key === "message" || key === "stack") {
+      continue;
+    }
+    result[key] = value[key];
+  }
+  return result;
+}
+function cloneWithDescriptors(node, options, ref) {
+  const result = Object.create(Object.getPrototypeOf(node));
+  ref.set(node, result);
+  const descriptors = Object.getOwnPropertyDescriptors(node);
+  const keys = Reflect.ownKeys(descriptors);
+  for (let i = 0, l = keys.length; i < l; i++) {
+    const key = keys[i];
+    if (isUnsafeKey(key)) {
+      continue;
+    }
+    const descriptor = { ...descriptors[key] };
+    if ("value" in descriptor) {
+      descriptor.value = clone(descriptor.value, options, ref);
+    }
+    try {
+      Object.defineProperty(result, key, descriptor);
+    } catch (error) {
+      if (options.strictDescriptors) {
+        throw error;
+      }
+    }
+  }
+  return result;
+}
+function isObject(value) {
+  return typeof value === "object" && value !== null;
+}
+function isPlainObject(value) {
+  return OBJECT_TO_STRING.call(value) === "[object Object]";
+}
+function isUnsafeKey(key) {
+  return typeof key === "string" && (key === "__proto__" || key === "prototype" || key === "constructor");
+}
+/**
+ * bunshin-clone
+ * High-performance deep clone utility with descriptor support.
+ * Supports circular ref and complex built-in types.
+ *
+ * @version 1.0.0
+ * @author Yusuke Kamiyamane
+ * @license MIT
+ * @copyright Copyright (c) 2026 Yusuke Kamiyamane
+ * @see {@link https://github.com/y14e/bunshin-clone}
+ */
+
+export { bunshinClone as default };

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "bunshin-clone",
+  "version": "1.0.0",
+  "description": "High-performance deep clone utility with descriptor support",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "bun test",
+    "prepublishOnly": "npm run build && npm test",
+    "lint": "tsc --noEmit"
+  },
+  "keywords": [
+    "clone",
+    "deep",
+    "typescript"
+  ],
+  "author": "Yusuke Kamiyamane",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/y14e/bunshin-clone.git"
+  },
+  "bugs": {
+    "url": "https://github.com/y14e/bunshin-clone/issues"
+  },
+  "homepage": "https://github.com/y14e/bunshin-clone#readme",
+  "devDependencies": {
+    "bun-types": "latest",
+    "tsup": "^8.0.0",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}