assign-gingerly 0.0.62 → 0.0.63

package/README.md

@@ -1312,7 +1312,15 @@ obj
 console.log(obj); // { a: 1, b: { c: 2 }, d: 3 }
 ```
 
-**Note**: The `assignTentatively` method on Object.prototype is simply an alias for `assignGingerly` and does **not** provide the reversibility features of the standalone `assignTentatively` function described in Example 8. For reversible assignments, use the standalone function from `assign-gingerly/assignTentatively`.
+**Note**: The `assignTentatively` method on Object.prototype provides full reversibility — it calls the standalone `assignTentatively` function and returns a reversal object. Apply the reversal with `obj.assignGingerly(reversal)` to undo all changes:
+
+```TypeScript
+const obj = { name: 'Alice', age: 30 };
+const reversal = obj.assignTentatively({ name: 'Bob', score: 100 });
+// obj = { name: 'Bob', age: 30, score: 100 }
+obj.assignGingerly(reversal);
+// obj = { name: 'Alice', age: 30 } — restored
+```
 
 The prototype extensions are non-enumerable and won't appear in `Object.keys()` or `for...in` loops.
 

package/object-extension.js

@@ -1,4 +1,5 @@
 import assignGingerly, { EnhancementRegistry, ItemscopeRegistry, getInstanceMap } from './assignGingerly.js';
+import assignTentatively from './assignTentatively.js';
 import { parseWithAttrs } from './parseWithAttrs.js';
 /**
  * Normalizes lifecycleKeys to always return an object with dispose and resolved keys
@@ -426,18 +427,13 @@ Object.defineProperty(Object.prototype, 'assignGingerly', {
 });
 /**
  * Adds assignTentatively method to all objects via the Object prototype
- * This is an alias for assignGingerly
+ * Returns a reversal object that can undo the changes when passed to assignGingerly.
  */
 Object.defineProperty(Object.prototype, 'assignTentatively', {
     value: function (source, options) {
-        // Auto-populate registry from customElementRegistry if this is an Element
-        if (this instanceof Element && (!options || !options.registry)) {
-            if (!options)
-                options = {};
-            options.registry = this.customElementRegistry?.enhancementRegistry;
-        }
-        assignGingerly(this, source, options);
-        return this;
+        const reversal = options?.reversal ?? {};
+        assignTentatively(this, source, { reversal });
+        return reversal;
     },
     writable: true,
     enumerable: false,

package/object-extension.ts

@@ -1,4 +1,5 @@
 import assignGingerly, { EnhancementRegistry, ItemscopeRegistry, IAssignGingerlyOptions, getInstanceMap, INSTANCE_MAP_GUID } from './assignGingerly.js';
+import assignTentatively from './assignTentatively.js';
 import { EnhancementConfig, SpawnContext } from './types/assign-gingerly/types.js';
 import { parseWithAttrs } from './parseWithAttrs.js';
 
@@ -60,22 +61,24 @@ declare global {
     ): this;
 
     /**
-     * Alias for assignGingerly. Carefully merge properties from a source object into this object.
-     * Supports nested paths with ?. notation and dependency injection via registry.
+     * Carefully merge properties from a source object into this object, tracking changes
+     * for reversibility. Returns a reversal object that can undo all modifications.
      * 
      * @param source - The source object to merge
-     * @param options - Optional configuration with registry for dependency injection
-     * @returns This object after merging
+     * @param options - Optional configuration with reversal tracking
+     * @returns A reversal object that, when passed to assignGingerly, undoes the changes
      * 
      * @example
-     * const target = {};
-     * target.assignTentatively({ '?.style?.height': '15px' });
-     * console.log(target); // { style: { height: '15px' } }
+     * const obj = { name: 'Alice', age: 30 };
+     * const reversal = obj.assignTentatively({ name: 'Bob', score: 100 });
+     * // obj = { name: 'Bob', age: 30, score: 100 }
+     * obj.assignGingerly(reversal);
+     * // obj = { name: 'Alice', age: 30 } — score removed, name restored
      */
     assignTentatively(
       source: Record<string | symbol, any>,
-      options?: IAssignGingerlyOptions
-    ): this;
+      options?: { reversal?: Record<string | symbol, any> }
+    ): Record<string | symbol, any>;
   }
 }
 
@@ -567,21 +570,17 @@ Object.defineProperty(Object.prototype, 'assignGingerly', {
 
 /**
  * Adds assignTentatively method to all objects via the Object prototype
- * This is an alias for assignGingerly
+ * Returns a reversal object that can undo the changes when passed to assignGingerly.
  */
 Object.defineProperty(Object.prototype, 'assignTentatively', {
   value: function <T extends object>(
     this: T,
     source: Record<string | symbol, any>,
-    options?: IAssignGingerlyOptions
-  ): T {
-    // Auto-populate registry from customElementRegistry if this is an Element
-    if (this instanceof Element && (!options || !options.registry)) {
-      if (!options) options = {};
-      options.registry = (this as any).customElementRegistry?.enhancementRegistry;
-    }
-    assignGingerly(this, source, options);
-    return this;
+    options?: { reversal?: Record<string | symbol, any> }
+  ): Record<string | symbol, any> {
+    const reversal = options?.reversal ?? {};
+    assignTentatively(this, source, { reversal });
+    return reversal;
   },
   writable: true,
   enumerable: false,

package/package.json

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