assign-gingerly 0.0.62 → 0.0.64

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/assignTentatively.ts

@@ -1,9 +1,8 @@
 /**
- * Interface for assignTentatively options with reversal tracking
+ * assignTentatively — reversible assignment with change tracking.
  */
-export interface IAssignTentativelyOptions {
-  reversal?: Record<string | symbol, any>;
-}
+import type { IAssignTentativelyOptions } from './types/assign-gingerly/types.js';
+export type { IAssignTentativelyOptions };
 
 /**
  * Helper function to check if a string key represents an += command

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,6 @@
 import assignGingerly, { EnhancementRegistry, ItemscopeRegistry, IAssignGingerlyOptions, getInstanceMap, INSTANCE_MAP_GUID } from './assignGingerly.js';
+import assignTentatively from './assignTentatively.js';
+import type { IAssignTentativelyOptions } from './types/assign-gingerly/types.js';
 import { EnhancementConfig, SpawnContext } from './types/assign-gingerly/types.js';
 import { parseWithAttrs } from './parseWithAttrs.js';
 
@@ -60,22 +62,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?: IAssignTentativelyOptions
+    ): Record<string | symbol, any>;
   }
 }
 
@@ -567,21 +571,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?: IAssignTentativelyOptions
+  ): Record<string | symbol, any> {
+    const reversal = options?.reversal ?? {};
+    assignTentatively(this, source, { ...options, reversal });
+    return reversal;
   },
   writable: true,
   enumerable: false,

package/package.json

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

package/types/assign-gingerly/types.d.ts

@@ -261,6 +261,34 @@ export interface IAssignGingerlyOptions {
   signal?: AbortSignal;
 }
 
+/**
+ * Options for assignTentatively — reversible assignment with change tracking.
+ * 
+ * Supports a subset of assignGingerly's path features (nested paths, +=, =!, -=)
+ * with the addition of reversal tracking.
+ */
+export interface IAssignTentativelyOptions {
+  /**
+   * Object to accumulate reversal entries into.
+   * If omitted, a new object is created internally.
+   * Pass an existing object to accumulate reversals across multiple calls.
+   * 
+   * The reversal object can be passed to assignGingerly to undo all changes:
+   * @example
+   * const reversal = {};
+   * assignTentatively(obj, { name: 'Bob' }, { reversal });
+   * // Later:
+   * assignGingerly(obj, reversal); // restores name to original value
+   */
+  reversal?: Record<string | symbol, any>;
+
+  /**
+   * Alias mappings for property and method names.
+   * Same semantics as IAssignGingerlyOptions.aka — substituted before path evaluation.
+   */
+  aka?: Record<string, string>;
+}
+
 /**
  * Options for synchronous value resolution (getValues / getValue).
  * Extends IAssignGingerlyOptions with synchronous protocol handlers.