assign-gingerly 0.0.61 → 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.
 
@@ -4057,9 +4065,9 @@ assignFrom(oElement, {
 assignFrom(oElement, {
     '?.textContent =>': {
         do: 'builtIns.join',
-        separator: ' | ',
         get: {
-            value: ['?.firstName', '?.lastName']
+            value: ['?.firstName', '?.lastName'],
+            separator: ' | '
         }
     }
 }, { from: vm });

package/handlers/join.js

@@ -66,8 +66,7 @@ export class JoinHandler {
         this.config = config;
     }
     async assign(lhsTarget, resolvedParams) {
-        const { value } = resolvedParams;
-        const separator = this.config.separator ?? '';
+        const { value, separator = '' } = resolvedParams;
         const items = Array.isArray(value) ? processValue(value) : [value];
         return items.join(separator);
     }

package/handlers/join.ts

@@ -71,8 +71,7 @@ export class JoinHandler implements AssignFromHandler {
     }
 
     async assign(lhsTarget: any, resolvedParams: Record<string, any>): Promise<string> {
-        const { value } = resolvedParams;
-        const separator = this.config.separator ?? '';
+        const { value, separator = '' } = resolvedParams;
 
         const items = Array.isArray(value) ? processValue(value) : [value];
         return items.join(separator);

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.61",
+  "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": {