assign-gingerly 0.0.32 → 0.0.33

package/README.md

@@ -110,7 +110,7 @@ console.log(obj);
 
 When the right hand side of an expression is an object, assignGingerly behavior depends on the context:
 - For **nested paths** (starting with `?.`): recursively merges into nested objects, creating them if needed
-- For **plain keys**: performs simple assignment (like `Object.assign`), unless the target property is readonly or a class instance (see Examples 3a and 3b below)
+- For **plain keys**: performs simple assignment (like `Object.assign`), unless the target property is readonly or an accessor (see Examples 3a and 3b below)
 
 Of course, just as Object.assign led to object spread notation, assignGingerly could lead to some sort of deep structural JavaScript syntax, but that is outside the scope of this polyfill package.
 
@@ -144,38 +144,40 @@ console.log(obj.config); // { theme: 'dark' } - intermediate object created
 
 ## Example 3a - Automatic Readonly Property Detection
 
-assignGingerly automatically detects readonly properties and merges into them instead of attempting to replace them. This makes working with DOM properties like `style` and `dataset` much more ergonomic:
+assignGingerly automatically detects readonly properties and merges into them instead of attempting to replace them. This makes working with DOM properties like `dataset` ergonomic:
 
 ```TypeScript
-// Instead of this verbose syntax:
 const div = document.createElement('div');
 assignGingerly(div, {
-    '?.style?.height': '15px',
-    '?.style?.width': '20px'
-});
-
-// You can now use this cleaner syntax:
-assignGingerly(div, {
-    style: {
-        height: '15px',
-        width: '20px'
+    dataset: {
+        userId: '123',
+        userName: 'Alice'
     }
 });
-console.log(div.style.height); // '15px'
-console.log(div.style.width);  // '20px'
+console.log(div.dataset.userId);   // '123'
+console.log(div.dataset.userName); // 'Alice'
 ```
 
 **How it works:**
 
 When assignGingerly encounters an object value being assigned to an existing property, it checks if that property is readonly:
 - **Data properties** with `writable: false`
-- **Accessor properties** with a getter but no setter
+- **Accessor properties** with a getter but no setter (e.g., `dataset`, `shadowRoot`)
 
 If the property is readonly and its current value is an object, assignGingerly automatically merges into it recursively.
 
-**Examples of readonly properties:**
-- `HTMLElement.style` - The CSSStyleDeclaration object
-- `HTMLElement.dataset` - The DOMStringMap object  
+**Note on `element.style`:** The `style` property has both a getter and a setter, so it is *not* treated as readonly. Use nested path syntax instead:
+
+```TypeScript
+// Use nested path syntax for style
+assignGingerly(div, {
+    '?.style?.height': '15px',
+    '?.style?.width': '20px'
+});
+```
+
+**Examples of readonly properties that trigger merging:**
+- `HTMLElement.dataset` - getter only, no setter
 - Custom objects with `Object.defineProperty(obj, 'prop', { value: {}, writable: false })`
 - Accessor properties with getter only: `Object.defineProperty(obj, 'prop', { get() { return {}; } })`
 
@@ -225,134 +227,54 @@ assignGingerly(config, {
 console.log(config.settings.theme); // 'dark'
 ```
 
-## Example 3b - Automatic Class Instance Preservation
+## Example 3b - Class Instances Are Replaced
 
-In addition to readonly property detection, assignGingerly automatically preserves class instances when merging. This is particularly useful when working with enhancement instances:
+Unlike readonly/accessor properties, class instances on writable properties are **replaced** by simple assignment, just like plain objects. This allows you to swap one object for another without unexpected merging:
 
 ```TypeScript
-import 'assign-gingerly/object-extension.js';
-
-// Define an enhancement class
-class MyEnhancement {
-  constructor(element, ctx, initVals) {
-    this.element = element;
-    this.instanceId = Math.random(); // Track instance identity
-    if (initVals) {
-      Object.assign(this, initVals);
-    }
+class FakeDocumentFragment {
+  constructor() {
+    this.nodeType = 11;
+    this.childNodes = [];
   }
-  prop1 = null;
-  prop2 = null;
 }
 
-const element = document.createElement('div');
-element.enh = {
-  myEnh: new MyEnhancement(element, {}, {})
+const obj = {
+  clone: new FakeDocumentFragment()
 };
 
-const originalId = element.enh.myEnh.instanceId;
-
-// Clean syntax - no need for ?.myEnh?.prop1 notation
-assignGingerly(element, {
-  enh: {
-    myEnh: {
-      prop1: 'value1',
-      prop2: 'value2'
-    }
-  }
-});
-
-console.log(element.enh.myEnh.instanceId === originalId); // true - instance preserved!
-console.log(element.enh.myEnh.prop1); // 'value1'
-console.log(element.enh.myEnh.prop2); // 'value2'
-```
-
-**How it works:**
-
-When assignGingerly encounters an object value being assigned to an existing property, it checks if the current value is a class instance (not a plain object):
-
-- **Class instances** are detected by checking if their prototype is something other than `Object.prototype` or `null`
-- **Plain objects** `{}` have `Object.prototype` as their prototype
-- **Class instances** have their class's prototype
-
-If the existing value is a class instance, assignGingerly merges into it instead of replacing it.
-
-**What counts as a class instance:**
-- Custom class instances: `new MyClass()`
-- Built-in class instances: `new Date()`, `new Map()`, `new Set()`, etc.
-- Enhancement instances on the `enh` property
-- Any object whose prototype is not `Object.prototype` or `null`
-
-**What doesn't count:**
-- Plain objects: `{}`, `{ a: 1 }`
-- Arrays: `[]`, `[1, 2, 3]` (arrays are replaced, not merged)
-- Primitives: strings, numbers, booleans
-
-**Benefits:**
-
-This feature enables clean, framework-friendly syntax for updating enhancements:
+const element = document.createElement('div');
 
-```TypeScript
-// Before: Verbose nested path syntax
-assignGingerly(element, {
-  '?.enh?.mellowYellow?.madAboutFourteen': true
+// Replace the DocumentFragment with the actual element
+assignGingerly(obj, {
+  clone: element
 });
 
-// After: Clean object syntax
-assignGingerly(element, {
-  enh: {
-    mellowYellow: {
-      madAboutFourteen: true
-    }
-  }
-});
+console.log(obj.clone === element); // true - replaced, not merged
 ```
 
-**Additional examples:**
-
-```TypeScript
-// Multiple enhancements at once
-assignGingerly(element, {
-  enh: {
-    enhancement1: { prop: 'value1' },
-    enhancement2: { prop: 'value2' }
-  }
-});
-
-// Works with built-in classes too
-const obj = {
-  timestamp: new Date('2024-01-01')
-};
+**Why replacement instead of merging?**
 
-assignGingerly(obj, {
-  timestamp: {
-    customProp: 'metadata'
-  }
-});
+In real-world use cases, you often need to replace one object with another of a completely different type. For example, replacing a cloned DocumentFragment with the actual web component element. Automatic merging would corrupt the target by mixing properties from incompatible types.
 
-console.log(obj.timestamp instanceof Date); // true - Date instance preserved
-console.log(obj.timestamp.customProp);      // 'metadata'
-```
-
-**Combined with readonly detection:**
+**Readonly/accessor properties are still merged:**
 
-Both readonly properties and class instances are preserved:
+The distinction is clear:
+- **Writable data properties**: always replaced (whether holding a plain object or class instance)
+- **Readonly data properties** (`writable: false`): merged into
+- **Getter-only accessor properties** (no setter): merged into
+- **Getter+setter accessor properties** (e.g., `style`): setter runs with the value as-is
 
 ```TypeScript
 const div = document.createElement('div');
-div.enh = {
-  myEnh: new MyEnhancement(div, {}, {})
-};
 
 assignGingerly(div, {
-  style: { height: '100px' },      // Readonly - merged
-  enh: {
-    myEnh: { prop: 'value' }       // Class instance - merged
-  },
-  dataset: { userId: '123' }       // Readonly - merged
+  dataset: { userId: '123' },       // Getter-only - merged
+  '?.style?.height': '100px'        // Use nested path for style
 });
 
-// All instances and readonly objects preserved
+console.log(div.dataset.userId);  // '123'
+console.log(div.style.height);    // '100px'
 ```
 
 ## Example 3c - Method Calls with withMethods

package/assignGingerly.js

@@ -228,11 +228,14 @@ function ensureNestedPath(obj, pathParts) {
     return current;
 }
 /**
- * Helper function to check if a property is readonly
- * A property is readonly if:
+ * Helper function to check if a property should be merged into rather than replaced.
+ * A property is non-replaceable if:
  * - It's a data property with writable: false, OR
  * - It's an accessor property with a getter but no setter
  *
+ * Properties with both a getter and setter (e.g., element.style) are treated as
+ * replaceable — the setter runs with whatever value is provided (garbage in, garbage out).
+ *
  * Exported for use by eachTime.ts
  */
 export function isReadonlyProperty(obj, propName) {
@@ -253,8 +256,8 @@ export function isReadonlyProperty(obj, propName) {
     if ('value' in descriptor) {
         return descriptor.writable === false;
     }
-    // If it's an accessor property, check if it has only a getter (no setter)
-    if ('get' in descriptor) {
+    // If it's an accessor property with a getter but no setter, it's readonly
+    if ('get' in descriptor && descriptor.get !== undefined) {
         return descriptor.set === undefined;
     }
     return false;
@@ -439,10 +442,10 @@ function applyToEach(iterable, remainingPath, value, withMethods, aliasMap, opti
                 const lastKey = result.lastKey;
                 const parent = result.target;
                 if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
-                    if (lastKey in parent && (isReadonlyProperty(parent, lastKey) || isClassInstance(parent[lastKey]))) {
+                    if (lastKey in parent && isReadonlyProperty(parent, lastKey)) {
                         const currentValue = parent[lastKey];
                         if (typeof currentValue !== 'object' || currentValue === null) {
-                            throw new Error(`Cannot merge object into ${isReadonlyProperty(parent, lastKey) ? 'readonly ' : ''}primitive property '${String(lastKey)}'`);
+                            throw new Error(`Cannot merge object into readonly primitive property '${String(lastKey)}'`);
                         }
                         assignGingerly(currentValue, value, options);
                     }
@@ -729,16 +732,16 @@ export function assignGingerly(target, source, options) {
                 const lastKey = result.lastKey;
                 const parent = result.target;
                 if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
-                    // Check if property exists and is readonly OR is a class instance
-                    if (lastKey in parent && (isReadonlyProperty(parent, lastKey) || isClassInstance(parent[lastKey]))) {
+                    // Check if property exists and is readonly
+                    if (lastKey in parent && isReadonlyProperty(parent, lastKey)) {
                         const currentValue = parent[lastKey];
                         if (typeof currentValue !== 'object' || currentValue === null) {
-                            throw new Error(`Cannot merge object into ${isReadonlyProperty(parent, lastKey) ? 'readonly ' : ''}primitive property '${String(lastKey)}'`);
+                            throw new Error(`Cannot merge object into readonly primitive property '${String(lastKey)}'`);
                         }
                         assignGingerly(currentValue, value, options);
                     }
                     else {
-                        // Property is writable and not a class instance - replace it
+                        // Property is writable - replace it
                         parent[lastKey] = value;
                     }
                 }
@@ -751,18 +754,18 @@ export function assignGingerly(target, source, options) {
                 const lastKey = pathParts[pathParts.length - 1];
                 const parent = ensureNestedPath(target, pathParts);
                 if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
-                    // Check if property exists and is readonly OR is a class instance
-                    if (lastKey in parent && (isReadonlyProperty(parent, lastKey) || isClassInstance(parent[lastKey]))) {
-                        // Property is readonly or a class instance - check if current value is an object
+                    // Check if property exists and is readonly
+                    if (lastKey in parent && isReadonlyProperty(parent, lastKey)) {
+                        // Property is readonly - check if current value is an object
                         const currentValue = parent[lastKey];
                         if (typeof currentValue !== 'object' || currentValue === null) {
-                            throw new Error(`Cannot merge object into ${isReadonlyProperty(parent, lastKey) ? 'readonly ' : ''}primitive property '${String(lastKey)}'`);
+                            throw new Error(`Cannot merge object into readonly primitive property '${String(lastKey)}'`);
                         }
-                        // Recursively apply assignGingerly to the readonly object or class instance
+                        // Recursively apply assignGingerly to the readonly object
                         assignGingerly(currentValue, value, options);
                     }
                     else {
-                        // Property is writable and not a class instance - replace it
+                        // Property is writable - replace it
                         parent[lastKey] = value;
                     }
                 }
@@ -789,18 +792,18 @@ export function assignGingerly(target, source, options) {
             }
             // Normal assignment
             if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
-                // Check if property exists and is readonly OR is a class instance
-                if (key in target && (isReadonlyProperty(target, key) || isClassInstance(target[key]))) {
-                    // Property is readonly or a class instance - check if current value is an object
+                // Check if property exists and is readonly
+                if (key in target && isReadonlyProperty(target, key)) {
+                    // Property is readonly - check if current value is an object
                     const currentValue = target[key];
                     if (typeof currentValue !== 'object' || currentValue === null) {
-                        throw new Error(`Cannot merge object into ${isReadonlyProperty(target, key) ? 'readonly ' : ''}primitive property '${String(key)}'`);
+                        throw new Error(`Cannot merge object into readonly primitive property '${String(key)}'`);
                     }
-                    // Recursively apply assignGingerly to the readonly object or class instance
+                    // Recursively apply assignGingerly to the readonly object
                     assignGingerly(currentValue, value, options);
                 }
                 else {
-                    // Property is writable and not a class instance - replace it
+                    // Property is writable - replace it
                     target[key] = value;
                 }
             }

package/assignGingerly.ts

@@ -356,11 +356,14 @@ function ensureNestedPath(obj: any, pathParts: string[]): any {
 }
 
 /**
- * Helper function to check if a property is readonly
- * A property is readonly if:
+ * Helper function to check if a property should be merged into rather than replaced.
+ * A property is non-replaceable if:
  * - It's a data property with writable: false, OR
  * - It's an accessor property with a getter but no setter
  * 
+ * Properties with both a getter and setter (e.g., element.style) are treated as
+ * replaceable — the setter runs with whatever value is provided (garbage in, garbage out).
+ * 
  * Exported for use by eachTime.ts
  */
 export function isReadonlyProperty(obj: any, propName: string | symbol): boolean {
@@ -383,8 +386,8 @@ export function isReadonlyProperty(obj: any, propName: string | symbol): boolean
     return descriptor.writable === false;
   }
   
-  // If it's an accessor property, check if it has only a getter (no setter)
-  if ('get' in descriptor) {
+  // If it's an accessor property with a getter but no setter, it's readonly
+  if ('get' in descriptor && descriptor.get !== undefined) {
     return descriptor.set === undefined;
   }
   
@@ -589,10 +592,10 @@ function applyToEach(
         const parent = result.target;
         
         if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
-          if (lastKey in parent && (isReadonlyProperty(parent, lastKey) || isClassInstance(parent[lastKey]))) {
+          if (lastKey in parent && isReadonlyProperty(parent, lastKey)) {
             const currentValue = parent[lastKey];
             if (typeof currentValue !== 'object' || currentValue === null) {
-              throw new Error(`Cannot merge object into ${isReadonlyProperty(parent, lastKey) ? 'readonly ' : ''}primitive property '${String(lastKey)}'`);
+              throw new Error(`Cannot merge object into readonly primitive property '${String(lastKey)}'`);
             }
             assignGingerly(currentValue, value, options);
           } else {
@@ -918,15 +921,15 @@ export function assignGingerly(
         const parent = result.target;
         
         if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
-          // Check if property exists and is readonly OR is a class instance
-          if (lastKey in parent && (isReadonlyProperty(parent, lastKey) || isClassInstance(parent[lastKey]))) {
+          // Check if property exists and is readonly
+          if (lastKey in parent && isReadonlyProperty(parent, lastKey)) {
             const currentValue = parent[lastKey];
             if (typeof currentValue !== 'object' || currentValue === null) {
-              throw new Error(`Cannot merge object into ${isReadonlyProperty(parent, lastKey) ? 'readonly ' : ''}primitive property '${String(lastKey)}'`);
+              throw new Error(`Cannot merge object into readonly primitive property '${String(lastKey)}'`);
             }
             assignGingerly(currentValue, value, options);
           } else {
-            // Property is writable and not a class instance - replace it
+            // Property is writable - replace it
             parent[lastKey] = value;
           }
         } else {
@@ -938,17 +941,17 @@ export function assignGingerly(
         const parent = ensureNestedPath(target, pathParts);
 
         if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
-          // Check if property exists and is readonly OR is a class instance
-          if (lastKey in parent && (isReadonlyProperty(parent, lastKey) || isClassInstance(parent[lastKey]))) {
-            // Property is readonly or a class instance - check if current value is an object
+          // Check if property exists and is readonly
+          if (lastKey in parent && isReadonlyProperty(parent, lastKey)) {
+            // Property is readonly - check if current value is an object
             const currentValue = parent[lastKey];
             if (typeof currentValue !== 'object' || currentValue === null) {
-              throw new Error(`Cannot merge object into ${isReadonlyProperty(parent, lastKey) ? 'readonly ' : ''}primitive property '${String(lastKey)}'`);
+              throw new Error(`Cannot merge object into readonly primitive property '${String(lastKey)}'`);
             }
-            // Recursively apply assignGingerly to the readonly object or class instance
+            // Recursively apply assignGingerly to the readonly object
             assignGingerly(currentValue, value, options);
           } else {
-            // Property is writable and not a class instance - replace it
+            // Property is writable - replace it
             parent[lastKey] = value;
           }
         } else {
@@ -974,17 +977,17 @@ export function assignGingerly(
       
       // Normal assignment
       if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
-        // Check if property exists and is readonly OR is a class instance
-        if (key in target && (isReadonlyProperty(target, key) || isClassInstance(target[key]))) {
-          // Property is readonly or a class instance - check if current value is an object
+        // Check if property exists and is readonly
+        if (key in target && isReadonlyProperty(target, key)) {
+          // Property is readonly - check if current value is an object
           const currentValue = target[key];
           if (typeof currentValue !== 'object' || currentValue === null) {
-            throw new Error(`Cannot merge object into ${isReadonlyProperty(target, key) ? 'readonly ' : ''}primitive property '${String(key)}'`);
+            throw new Error(`Cannot merge object into readonly primitive property '${String(key)}'`);
           }
-          // Recursively apply assignGingerly to the readonly object or class instance
+          // Recursively apply assignGingerly to the readonly object
           assignGingerly(currentValue, value, options);
         } else {
-          // Property is writable and not a class instance - replace it
+          // Property is writable - replace it
           target[key] = value;
         }
       } else {

package/eachTime.js

@@ -58,7 +58,7 @@ export async function handleEachTime(target, pathParts, forEachIndex, value, wit
         (async () => {
             try {
                 // Import needed functions from assignGingerly
-                const { evaluatePathWithMethods, assignGingerly, isReadonlyProperty, isClassInstance } = await import('./assignGingerly.js');
+                const { evaluatePathWithMethods, assignGingerly, isReadonlyProperty } = await import('./assignGingerly.js');
                 if (pathAfterForEach.length > 0) {
                     const result = evaluatePathWithMethods(mountedElement, pathAfterForEach, value, withMethods || new Set());
                     if (result.isMethod) {
@@ -78,17 +78,17 @@ export async function handleEachTime(target, pathParts, forEachIndex, value, wit
                         const lastKey = result.lastKey;
                         const parent = result.target;
                         if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
-                            // Check if property exists and is readonly OR is a class instance
-                            if (lastKey in parent && (isReadonlyProperty(parent, lastKey) || isClassInstance(parent[lastKey]))) {
+                            // Check if property exists and is readonly
+                            if (lastKey in parent && isReadonlyProperty(parent, lastKey)) {
                                 const currentValue = parent[lastKey];
                                 if (typeof currentValue !== 'object' || currentValue === null) {
-                                    throw new Error(`Cannot merge object into ${isReadonlyProperty(parent, lastKey) ? 'readonly ' : ''}primitive property '${String(lastKey)}'`);
+                                    throw new Error(`Cannot merge object into readonly primitive property '${String(lastKey)}'`);
                                 }
                                 // Recursively apply assignGingerly
                                 assignGingerly(currentValue, value, options);
                             }
                             else {
-                                // Property is writable and not a class instance - replace it
+                                // Property is writable - replace it
                                 parent[lastKey] = value;
                             }
                         }

package/eachTime.ts

@@ -77,8 +77,7 @@ export async function handleEachTime(
         const { 
           evaluatePathWithMethods, 
           assignGingerly, 
-          isReadonlyProperty, 
-          isClassInstance 
+          isReadonlyProperty
         } = await import('./assignGingerly.js');
         
         if (pathAfterForEach.length > 0) {
@@ -105,18 +104,18 @@ export async function handleEachTime(
             const parent = result.target;
             
             if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
-              // Check if property exists and is readonly OR is a class instance
-              if (lastKey in parent && (isReadonlyProperty(parent, lastKey) || isClassInstance(parent[lastKey]))) {
+              // Check if property exists and is readonly
+              if (lastKey in parent && isReadonlyProperty(parent, lastKey)) {
                 const currentValue = parent[lastKey];
                 if (typeof currentValue !== 'object' || currentValue === null) {
                   throw new Error(
-                    `Cannot merge object into ${isReadonlyProperty(parent, lastKey) ? 'readonly ' : ''}primitive property '${String(lastKey)}'`
+                    `Cannot merge object into readonly primitive property '${String(lastKey)}'`
                   );
                 }
                 // Recursively apply assignGingerly
                 assignGingerly(currentValue, value, options);
               } else {
-                // Property is writable and not a class instance - replace it
+                // Property is writable - replace it
                 parent[lastKey] = value;
               }
             } else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assign-gingerly",
-  "version": "0.0.32",
+  "version": "0.0.33",
   "description": "This package provides a utility function for carefully merging one object into another.",
   "homepage": "https://github.com/bahrus/assign-gingerly#readme",
   "bugs": {